Model residency: pinned host weights, disposable GPU copies

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: diffuseR
 Title: Functional Interface to Diffusion Models in R
-Version: 0.2.1.1
+Version: 0.2.1.2
 Authors@R: c(
     person("Troy", "Hernandez", email = "troy@cornball.ai", role = c("aut", "cre"),
            comment = c(ORCID = "0009-0005-4248-604X")),

NAMESPACE

@@ -181,6 +181,12 @@ export(qwen_bpe_tokenizer)
 export(qwen3_encoder)
 export(recommend)
 export(reshard_safetensors)
+export(resident_activate)
+export(resident_deactivate)
+export(resident_generate)
+export(resident_load)
+export(resident_status)
+export(resident_unload)
 export(save_frames)
 export(save_image)
 export(save_video)
@@ -229,6 +235,7 @@ export(zimage_transformer)
 export(zimage_unpatchify)
 
 S3method(print,bpe_tokenizer)
+S3method(print,diffuseR_resident)
 S3method(print,ltx23_checkpoint)
 S3method(print,qwen_tokenizer)
 S3method(print,unigram_tokenizer)

NEWS.md

@@ -1,3 +1,29 @@
+# diffuseR 0.2.1.2
+
+* Model residency: `resident_load()`, `resident_activate()`,
+  `resident_deactivate()`, `resident_generate()`, `resident_status()`
+  and `resident_unload()` keep a pipeline's weights page-locked on the
+  host and treat the GPU copy as disposable, so handing a small card
+  between models is a DMA transfer rather than a full reload. Same
+  contract as whisper and chatterbox, with no `gpu.ctl` dependency.
+  This sits above the per-generation phase offloading in the
+  `txt2img_*` functions: those swap one component at a time within a
+  render, residency decides who owns the card between renders. For a
+  phase-offloading pipeline (the default) activation is the ownership
+  claim and the transfers stay per-phase; only a pipeline loaded with
+  `phase_offload = FALSE` is copied to the card wholesale, and that
+  path is checked against free VRAM first. `resident_status()` reports
+  `components_on_gpu` alongside `state`, because the two legitimately
+  disagree: a render returns every component to pinned host memory as
+  its phase ends, so an active handle can hold nothing.
+
+  Verified on an RTX 5060 Ti (16 GB) against local artifacts: flux2
+  (11.22 GB pinned, 9.1 s render), flux1 (15.73 GB, 40.1 s), zimage
+  (13.45 GB, 19.5 s) and ltx (18.41 GB across 5 components). All three
+  image models reproduce bit-for-bit across a deactivate/activate
+  cycle. FLUX.1 and LTX both have pinned sets larger than the card, so
+  they exercise the refusal path rather than bulk onload.
+
 # diffuseR 0.2.1.1
 
 Addresses the CRAN review of the 0.2.0 submission.