feat(LTX25-RES2S-LOOP): the res_2s loop, its second evaluation, and the guidance the naive merge would have dropped (#921)

[localai-bot]

pipeline_kind=res2s_two_stage serves upstream's TI2VidTwoStagesHQPipeline --
the high-quality arm. New TU ltx2_samplers.{h,cpp}, mirroring upstream's own
utils/ partition: a stepper advances a substep, a sampler decides how many
there are.

Ported at fd4ded7f: Ltx2Phi (utils/res2s.py:4-22),
Ltx2GetRes2sCoefficients + Ltx2PhiCache (:25-62),
Ltx2Res2sNormalizeNoise (utils/samplers.py:160-170), Ltx2Res2sDenoisingLoop
(:208-447), and Res2sTwoStageRecipe (ti2vid_two_stages_hq.py:59-340 +
utils/constants.py:95-115).

THE SAMPLER IS THE HQ VARIANT. Serving the HQ preset on the Euler loop renders a
plausible clip that is quietly not HQ, at roughly half the model evaluations the
preset was tuned for, and no shape or token gate can see it. The gate is
therefore an exact DiT-evaluation count -- 2n+1 when the schedule ends at 0,
else 2n -- asserted with the eval-sigma sequence beside it, so two forwards at
the same sigma also fails. End to end: 7 and 11 evaluations at 3 and 5 steps on
res2s_two_stage, against 3 and 5 on one_stage.

phi is a CANCELLATION CLIFF, not a series expansion. Upstream guards only
abs(z) < 1e-10 and otherwise evaluates the quotient directly, so its own
phi(2,-1e-10) is 0.0 and phi(2,-1e-8) is 1.1102230246251563. A Taylor
expansion near zero -- the numerically BETTER port -- returns 0.5 and diverges
from what the model actually ran. Pinned with ==.

GUIDANCE, which the merge nearly dropped. daeff67f2 (#1092) landed the guided
video denoiser into the same phase loop. A textual resolution keeping Evaluate
as a bare Ltx2DitForward would have made the HQ preset the only unguided video
arm in the tree -- upstream's stage 1 runs a GuidedDenoiser at cfg 3.0/7.0 and
rescale 0.45 (ti2vid_two_stages_hq.py:271-281) -- and the evaluation count
cannot see it, because a denoiser call is one evaluation guided or not.

So Evaluate builds the Ltx2X0Model lambda and calls Ltx2GuidedDenoise, and
a SECOND counter was added: dit_forwards counts actual Ltx2DitForward calls
and is 3 * (2n+1) on HQ stage 1 (cond + uncond + modality), asserted exactly at
two step counts with forwards != evaluations as its own assertion. Stripping
guidance from the res_2s arm alone is RED.

step_index mirrors upstream literally: step_idx at the first evaluation
(samplers.py:301), a literal 0 at the substep beside its one-element schedule
(:385), n_full_steps at the terminal one (:437). Since should_skip_step
is step % (skip_step + 1) != 0, the literal 0 makes the substep unskippable at
any skip_step -- inert on the HQ preset's own skip_step = 0, live for a
request override.

A mutation survivor the review did not list: the substep's x0 conversion must use
the latent THAT EVALUATION was handed, because the substep runs over x_mid.
Reading the stream latent moves the whole substep prediction and nothing could
see it, since the loop's arithmetic is gated with a fixture denoiser that
performs no conversion. Now gated and RED.

The engine's VT_CHECK was a tautology -- both operands came from the same
stats object and 2n+1 > n holds for every n -- and is now the trace delta
against stats.evaluations. The argument is executable: the same under-counting
defect beside the restored old check is GREEN.

Both generator scripts are committed rather than described.
scripts/gen-ltx2-res2s-goldens.py imports upstream's own phi,
get_res2s_coefficients, Res2sDiffusionStep, post_process_latent,
_channelwise_normalize and res2s_audio_video_denoising_loop at the pin and
reproduces ltx2_res2s_goldens.inc byte for byte -- which is the evidence the
goldens are upstream's and not this port's.

Supersedes #1101, whose branch carried a merge commit with a bare subject and no
trailer block. check-commit-trailers.py walks merges, that commit was a
first-parent ancestor of every candidate head, and repairing it would have needed
a force-push. Same tree, one commit, block intact.

Owed, not claimed: no render on real weights, and no oracle-run comparison --
everything is gated against upstream SOURCE at fd4ded7f. The HQ preset is
host-only here, because its modality_scale = 3.0 asks for the isolated-modality
pass and Ltx2DitForwardDevice takes no perturbations; that is #1092's owed
device work, not newly incurred.

Closes #921.

FOLLOWING_AGENTS_PROTOCOL

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