feat(LTX25-UPSAMPLER-ARMS): port the upsampler's dims=2 arm, and mirror model.py:47's else

[localai-org-maint-bot]

Port the latent upsampler's dims == 2 arm, which the second phase can already consume.

Ltx2LatentUpsample refused every dims != 3 config. dims is read off the
checkpoint's own metadata, mirroring model_configurator.py:17, so a 2-D
upsampler was an ordinary input this engine turned away.

What upstream builds, and what that costs

conv = torch.nn.Conv2d if dims == 2 else torch.nn.Conv3d (model.py:47)
reaches four parameter groups -- initial_conv (:49), both ResBlock stacks
(:53, :76-78, via res_block.py:21) and final_conv (:80). The forward
folds the frame axis into the batch (:86) and unfolds it at :100.

That fold has exactly two consequences and both are the port:

• the four groups become 4-D kernels, so EnumerateLtx2UpsamplerTensors
  emits different shapes;
• GroupNorm normalises per frame, because (b f) makes every frame its own
  sample. Our reduction runs over frames * height * width.

This runs one frame at a time, which reproduces the fold rather than
approximating it: a one-frame volume hands the existing reduction precisely the
per-frame statistic, so no second normaliser exists to drift.

The stack became one lambda for both ranks, because upstream's two branches run
the identical module sequence and differ only in the fold around them.

model.py:47's else is mirrored as written, so any dims that is not 2 builds
Conv3d. The old Require(config.dims == 3, ...) refused checkpoints upstream
runs -- a refusal this port had invented.

The two contradictions that stay refused, and why one of them mattered

dims=2 with temporal_upsample and dims=2 with rational_resampler are
configurations upstream cannot run. Both are now executed against the real
module by scripts/gen-ltx2-pipeline-goldens.py, which asserts each raises and
what it says, and emits nothing -- so the golden stays byte-identical while the
refusals are pinned to upstream behaviour rather than to reasoning about it.

The rational one is the finding. Every operator in that branch is already
per-frame, so a folded one-frame volume satisfies all of them and this port
computed a complete, finite, plausible latent where upstream raises
not enough values to unpack (expected 5, got 4)
(spatial_rational_resampler.py:41). No shape check anywhere could fault it.
That is the same failure mode this row's own mutation B demonstrated, left open
one branch over, and it took a review to find.

It also corrects a mechanism this row asserted without measuring. Conv3d does
not raise on the rank: it accepts a 4-D input as an unbatched 5-D one, so the
channel count is what disagrees -- expected input[1, 3, 32, 4, 6] to have 32 channels, but got 3. At frames == mid_channels the conv passes and
PixelShuffleND(1) fails instead. The conclusion held; the reasoning did not.

A third repair moves the dims=2 temporal refusal to load time. It was
refused, but from inside the rounds loop, reached only after two full denoise
stages -- while the temporal_upsampler_path block exists precisely so a caller
learns at load, and says so in its own comment.

A fourth gives Conv2dPad1PerFrame the bias check its sibling Conv3dPad1 has
had since #644. A correct kernel with a short bias indexed past the end of a
std::vector; the dims=2 arm routes four parameter groups through that helper,
so this change is what made the gap reachable.

Reached, and consumable rather than merely computed

Ltx2UpsampleVideoLatent has three product call sites. Both spatial ones
require the frame count back unchanged -- vshape.frames at
ltx2_video.cpp:3525-3531 and slot_positions.size() at :3552-3563. The
dims=2 arm returns exactly that, with H and W doubled, so the end-to-end case
renders a full-size clip through LoadVideoEngine/Generate instead of
asserting a changed error message.

Evidence

Red first: the dims=2 golden failed on six parameter counts (5184 vs 1728
for initial_conv, 27648 vs 9216 for each ResBlock conv) and then threw
ltx2 upsampler: dims=2 is not ported.

Two mutations, each restored byte-for-byte and sha256-verified:

Mutation	Golden	End-to-end render	What it proves
const bool two_d = false	RED	RED at test_ltx2_video.cpp:690	The production path really enters the new branch. A render that fails, not a unit test
keep the 2-D convolutions, drop the fold	RED, max|diff| = 0.679842	GREEN	The fold's only consequence is numerical. Every shape is identical, so no shape check can see it and the value golden is the sole gate

The generator's new assertions are armed, not decorative: replacing the expected
substring makes it raise and quote the real upstream exception.

Tests are ported by executing the real upstream module at the fd4ded7f pin.
403 golden lines added, no existing golden moved, oracle revision constants
unchanged, and the goldens regenerate byte-identically after the merge.

A8 is deliberately not here, and now has its own issue

The spatiotemporal arm returns [c, 2f-1, 2h, 2w] against the two consumers
above that need the frame count back. They agree only when vshape.frames == 1,
i.e. frames <= 8, where the doubling is cancelled by the mandatory first-frame
drop. Porting it would trade a named refusal for a generic shape complaint on
every real clip -- the substitution the guard at ltx2_video.cpp:3473-3502
exists to prevent.

That is a product decision, so it is tracked by #2584 and listed under
## Owed. It was originally recorded against #2577, which this PR closes, so the
owed item would have pointed at a closed issue the moment it landed;
check-agent-record.py could not have caught that, because the ## Owed entry
satisfies the gate on its own.

This reverses the scope document's sizing, which called A8 the cheaper of the
two. It is right about the operator and had not counted the second consumer.
That document is operator-owned and is not edited from here; the contradiction
is recorded in the row spec.

Also

Corrects two claims in ltx2_upsampler.h that the tree falsifies (#2580): there
are three upsampler call sites, not one, and DFR's rounds loop drives the
temporal arm the header called unreachable. The same false statement survives in
a user-facing Fail() at ltx2_video.cpp:3499-3501, already tracked as D11b and
left to its owner.

Every ltx2_video.cpp anchor in this branch's prose moved by the 16 lines the
load guard adds and was re-derived by grepping for the statements themselves.
docs/FEATURES.md is a keyed record, so its automatic three-way merge was
discarded on both merges and the two scoped rows reapplied by hand.

Closes #2577
Closes #2580

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [claude-code]