Fix pre-warm accumulation; correct resident_generate()'s @return

[TroyHernandez]

Two unrelated defects in code merged today, in one PR at Troy's request.
They are separate commits and separate NEWS entries — the behavioural fix
is 653eedb, the docs correction is fddd739, so bisecting the allocator
change does not mean reading past roxygen.

Found by vientito (gpu.ctl) reviewing #62 after it merged.

---

1. Pre-warm accumulation (653eedb)

.resident_prewarm(), added in 0.2.2.4, asked for the full onload need
on every activation. After the first render that doubles the CUDA
caching allocator's pool, and under release = FALSE it keeps doubling
until activation is refused.

Three activate/render/deactivate cycles on SDXL, one process:

	before	after
release = FALSE	5.299 → 10.322 → REFUSED	5.396 → 5.498 → 5.498
release = TRUE	5.299 → 10.123 → 10.125	5.396 → 5.396 → 5.396

The cycle 1→2 step was 5.023 GiB against a pre-warm block of
need * 1.05 = 5.021 GiB. That is the mechanism: a render fragments the
cache into its activation blocks, so the next single large request cannot
be served from what remains and takes a fresh cudaMalloc beside the old
one. release = TRUE masked it, because .resident_release_vram()'s
empty_cache caps the pool at two blocks.

Why this matters to the caller it was written for. A residency broker
passes release = FALSE deliberately — an exclusive device grant means
blocks never returned cannot be taken by anything else between requests.
So an SDXL entry would serve two requests and refuse every one after. On a
12 GB card sooner.

It broke the budget independently of the refusal. Both arms double
between cycle 1 and cycle 2, so any peak measured on a single activation
understates steady state about 2x — declaring 5.398 for something that
needs 10.125 on its second request, with the first looking perfect.

The fix reads what the allocator already holds and grows only what is
missing: skip when the pool covers the transfer, otherwise request the
shortfall. On a cold pool held is 0, so it is byte-identical to the
previous behaviour and the 74x cold-start win is untouched.

How it was found matters

Activate/deactivate cycles with no render in between hold dead flat at
5.098 GiB in both arms — the block is reused cleanly across bare
transitions. It takes a generation in between to fragment the pool. So one
cycle is not a test, and neither is a cycle without a render. The obvious
probe would have shown nothing wrong.

held is injectable for the same reason .resident_check_fits() takes
free_gb: without CUDA the measurement is 0, which would always warm, so
a test that wants the skip has to state what the pool holds rather than
depend on the machine having a card. Six new assertions cover skip,
shortfall, cold pool, and two nonsense readings.

---

2. resident_generate()'s @return was wrong (fddd739)

The @return added in 0.2.2.4 said flux1/flux2/zimage return bare
image arrays, ltx returns a video array, and sdxl is the odd one out
with list(image, metadata). All four claims are wrong, and in the
damaging direction: it tells a consumer to special-case sdxl and treat
flux2 as an array, which fails on first contact.

Every generator returns a list:

txt2img_flux    invisible(list(image = img_array, metadata = metadata))
txt2img_flux2   invisible(list(image = img_array, metadata = metadata))
txt2img_zimage  invisible(list(image = img_array, metadata = metadata))
txt2img_sdxl    return(list(image = img_array, metadata = metadata))
txt2img_sd21    return(list(image = img_array, metadata = metadata))
txt2vid_ltx2    invisible(result)   # video, audio, sample_rate, latents, ...

So sdxl agrees with the other image families rather than diverging,
and the corrected contract is simpler than the one it replaces: unwrap
$image across all five image families, $video for ltx. The only real
inconsistency left is return() versus invisible(), which affects
console auto-printing and nothing else.

The decision not to normalise the shapes stands; only the stated reason
was inverted.

Observed at runtime for sdxl, sd21 and ltx during this work,
confirmed for flux2 by the gpu.ctl side, and read from source for
flux1 and zimage.

---

Suite 1203 assertions, 0 failures. vientito is independently re-running
both arms against this branch before merge — they hold the before-numbers
and the harness, and the author measuring his own fix is the arrangement
their own measurement doc argues against.

[TroyHernandez]

Review addressed — all three findings were real, and the third had a part I had not spotted.

1. Allocator stats read from the wrong device — fixed

cuda_memory_stats() does take device and defaults to cuda_current_device(), so calling it bare reports whichever device is current rather than the one the handle bound. resident_load() binds an explicit "cuda:N" precisely so transitions cannot drift, so a cuda:1 handle deciding from cuda:0's pool would skip a pre-warm it needs or repeat one it does not. Added .cuda_index(), with tests for an unqualified device and for a malformed ordinal that must not become NA and poison the lookup.

The second half of that finding was also right: reserved includes live allocations, which cannot serve this transfer. Now reserved - allocated. That tightened the result as well — residual growth across cycles fell from 0.102 GiB to 0.002 GiB, because the decision is no longer made on bytes that were never available.

2. Shortfall request may not grow the pool — fixed the arithmetic, documented the limit

The margin correction is right and now reads bytes * 1.05 - held; (bytes - held) * 1.05 asks for 5% of the gap and undershoots the target whenever held > 0.

On the deeper point — a request smaller than a free block already in cache is served from that block and grows nothing — that is correct and I have documented it as best-effort rather than implying a guarantee. It is bounded and harmless: the onload falls back to the per-tensor path for the remainder, which is the pre-fix behaviour. The alternative, asking for the whole figure to force a new segment, is exactly the accumulation bug this function exists to avoid. The cold pool, which is the case worth optimising and the one a broker's first request hits, is unaffected.

3. @return still inaccurate — fixed, and worse than reported

txt2img_sd21() uses return() too — which the commit introducing that text had listed correctly two paragraphs earlier, so the doc contradicted its own commit message. And ltx's video/audio are produced only when decode_video/decode_audio are TRUE; a caller that disables either gets a list without the field rather than a NULL one, which is why txt2vid_ltx2() indexes with [[ ]] internally. Both now stated.

Verification

Also closed the three gaps flagged for the verifier, rather than leaving them:

Five cycles, release = FALSE, render each cycle

5.396 → 5.398 → 5.398 → 5.398 → 5.398 GiB

Flat at 3 is not flat at N, so this runs to 5.

Cold-start win intact — measured, not argued from the code

cycle 1   activate 2.48 s     (2.51 s before the accumulation fix)
cycles 2-5 activate 0.16 s

A phase-offloading family is untouched

flux2, three cycles: state=active, components_on_gpu=0, reserved 0.002 GiB

components_on_gpu = 0 while active proves the bulk branch was never taken, so the pre-warm was never reached.

Suite 1209 assertions, 0 failures.

[TroyHernandez]

Re-review addressed. All three were right; the second would have shipped a doc page missing the very rationale it was added to explain.

1. Margin threshold inconsistent — fixed

The skip tested held >= bytes while growth aimed at bytes * 1.05, which put a step in the middle: 3.999 GiB held asked for 0.201 GiB, 4.000 GiB held asked for nothing. target is now computed once and governs both the skip and the size, so they cannot disagree.

Added a test for the discontinuity itself rather than just the new value — holding a hair under and a hair over the raw need must differ by a hair, not by the whole margin.

2. Generated documentation incomplete — fixed, both halves

man/dot-cuda_index.Rd was untracked. git add -u stages tracked files only, so a newly generated Rd was silently left out. Staged by explicit path. This is the "never git add -A" rule biting from the other side: -u is the safe default precisely because it ignores untracked files, which means new files have to be named.

The duplicate @param tags were worse than cosmetic. The partial-cache paragraph was written after @param device, so roxygen read it as a continuation of that tag rather than as description — meaning the generated page did not contain the best-effort rationale at all. The reason the function deliberately does not force pool growth was in the source and absent from the docs, which is the half of that finding that mattered. Prose now precedes the tags, duplicates removed, and I verified against the generated Rd rather than assuming the regeneration fixed it.

3. NEWS carried superseded measurements — fixed

It still reported 5.396 / 5.498 / 5.498 from before the free-cache correction. Now 5.396 / 5.398 across five cycles, plus the cold-start figure and the phase-offload check, since those are otherwise numbers a reader has to take on trust.

Re-verified after the threshold change

five cycles, release=FALSE   5.396 → 5.398 → 5.398 → 5.398 → 5.398 GiB
cold start                   2.52 s
warm activations             0.17 s

Suite 1211 assertions, 0 failures. Working tree clean, nothing untracked.