feat(LTX25-RES2S-LOOP): the res_2s loop, its second evaluation, and the phi that must not be fixed (#921)

[localai-bot]

Closes #921. Row
LTX25-RES2S-LOOP, spec
ltx25-res2s-loop.md,
committed in de8bd2b2c before any implementation code.

TI2VidTwoStagesHQPipeline can now be served, as pipeline_kind res2s_two_stage. What was missing was not arithmetic around the edges: the
res_2s SAMPLER is what makes the high-quality preset high quality, and serving
LTX_2_3_HQ_PARAMS on the Euler loop renders a finished, correctly sized,
plausible clip at half the model evaluations the preset was tuned for. No
shape, frame count, sample rate or pixel says so.

So the gate is a COUNT. Ltx2Res2sDenoisingLoop evaluates the transformer at
sigmas[i], again at sqrt(sigma * sigma_next), and once more at a terminal
sigma the schedule injects, which is 2 * steps + 1 against the first-order
arm's steps. Measured end to end through VideoEngine::Generate: 7 and 11
forwards at 3 and 5 steps on res2s_two_stage against 3 and 5 on one_stage,
all four read off real renders rather than one computed from another.

Three upstream facts this port would have got wrong by analogy

Each verified at Lightricks/LTX-2 fd4ded7f rather than inherited from the
issue.

The loop runs on its own defaults. DiffusionStage.__call__ hands it SIX
keyword arguments and no others (utils/blocks.py:566-573), so every remaining
knob takes its declared default on the shipped arm. Two of those contradict the
already-shipped ancestral arm: noise_seed is the constant -1 rather than the
request's seed, so the res_2s SDE injections do not depend on the seed at all;
and new_noise_fn is _get_new_noise, which NORMALIZES, against the ancestral
loop's _get_plain_noise ten lines away in the same file.

phi is a cancellation cliff, not a series expansion. Its guard is
abs(z) < 1e-10 and outside it upstream evaluates (exp(z) - remainder) / z^j
directly, so upstream's own phi(2, -1e-10) is 0.0 and phi(2, -1e-8) is
1.1102230246251563. A Taylor series near zero, which is the numerically better
implementation, returns 0.5 at both and diverges from the model's own runtime.
The goldens pin the cancelled values with ==, not a tolerance, and the header
says not to fix it.

The SDE coefficients run at TWO widths, because upstream hands them two:
float64 from the substep's [sigma, sub_sigma] pair (samplers.py:342) and
float32 from the loop's own schedule at step level (:415). One templated
implementation, three instantiations, no second copy of the formula.

Evidence

Every golden came out of upstream's own executing code, imported from the
checkout and run: phi, get_res2s_coefficients, Res2sDiffusionStep,
post_process_latent and the loop itself. Only the denoiser, the noise draw
(torch.randn, whose stream this port does not have) and two media-IO modules
are substituted. Video latents come back BIT-EXACT on three of five fixtures and
one ulp on the other two.

Twenty mutations over five rounds, eighteen detected. Each row records
git diff --stat, whether it BUILT with its compile-error count, the exit code
captured directly, and the doctest case and assertion counts.

Four survivors were real holes and are closed. The loop tolerance was this
file's kRoundOff of 5e-6 and could not see the precision split, so it is now
one ulp. No fixture ran at eta != 0.5, so the pinned substep eta was invisible,
and an Eta1 fixture generated from upstream now separates them. The engine's
call to the noise normalization was gated by nothing, because normalization
changes no count, so Ltx2ConditioningTrace::res2s_noise_moment_error now
observes it. The fixture's noise hook was stateless and handed both modalities
the same values, so swapping the video and audio draws changed nothing; it is
now stateful, as upstream's generator is.

Two survivors stand and are recorded rather than papered over. The bong
guard's strict sigma > 0.03 cannot be reached through a float32 schedule on
either side, because 0.03f widens to 0.029999999329447746; the test comment
that claimed to pin it has been replaced by that derivation. And the
h * a21 association differs by less than one ulp at this fixture's scale.

Four mutations could not fail, and each was printed rather than counted as a
pass. M6a through M6d each removed one of two idempotent normalize calls.
M6b ran a truncated -tc filter that matched ZERO cases and printed
SUCCESS! with exit 0 over a clean build and a correct diff, which only the
case-count column caught. M18a targeted the wrong file and reported
ANCHOR NOT FOUND.

Reachability

vllm_video_generate to VideoEngine::Generate to Ltx2VideoEngine::Generate
to the phase loop's kRes2s dispatch. Deleting that dispatch reds the
end-to-end case (exit 1, 6 failed assertions). --pipeline-kind passes the
string through with no allowlist (examples/ltx2_gen/main.cpp:239), so
ltx2-gen, the C ABI and --video-extra pipeline_kind=res2s_two_stage on the
server all reach the arm.

The engine's per-evaluation body is hoisted into one Evaluate lambda that both
samplers call, rather than a second forward path written by hand, so the
keyframe-marker guards, the frozen scalar sigma and the device/host split are
reached identically from both and dit_evaluations is a single increment no arm
can bypass.

Gate

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DVLLM_CPP_CUDA=OFF

CONFIGURE_EXIT=0, BUILD_EXIT=0, : error: count 0, ctest -N 498,
CTEST_EXIT=0, "100% tests passed, 0 tests failed out of 498" in 177.81 s,
on the merged tree at da54d350e. Load average 117.09 at the start of that run;
free disk 13 G of 447 G at 98%. No space left and BFD assertion are 0 in
both the build and ctest logs, with the greps positive-controlled (each returns
1 on a synthetic line carrying the string).

An earlier run of the same tree failed test_serve_low_tools, which passed solo
with exit 0 at 19.74 s. That is the load-dependent flake
#428, not this change.

Not claimed

No render on real weights. dgx.casa is contended and OOM-reboots under a
second job, and a sampler is exactly the thing CPU goldens gate well; the
real-checkpoint HQ render is owed under the spec's ## Owed. The loop's SDE
noise is drawn from this port's SplitMixGaussian rather than upstream's seeded
torch.randn, so a render is not bit-comparable with Lightricks' — the same
limit the shipped ancestral arm already carries. legacy_mode=False is not
built: nothing upstream reaches it from any pipeline in scope, so a selection
surface for it would be invented here.

FOLLOWING_AGENTS_PROTOCOL

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

[localai-bot]

Superseded by #1125.

This branch carried da54d350e161, a git merge origin/main commit with a bare subject and no body. scripts/check-commit-trailers.py:336 builds its range with rev-list and no --no-merges, so merge commits need the block too — it reported three findings on that one commit, and commit-protocol-tag was red at every head.

It could not be repaired in place: da54d350e161 is a first-parent ancestor of every candidate head, so rev-list includes it whatever the merge base becomes. Fixing it means rewriting history, which means a force-push, which this project does not do. The fresh implementer correctly stopped rather than improvising, and left the call to the operator.

#1125 is the same tree — verified: git rev-parse HEAD^{tree} on the new branch equals the tree of 3307b6d96, so nothing was lost in the recreation — collapsed to one commit with the block intact, then merged with 589abad12 (#1115) which landed during the recreation.

check-commit-trailers now exits 0 on the new branch, with this branch's head exiting 1 as the armed control. Full gate on the merged tree: CONFIGURE_EXIT=0, BUILD_EXIT=0, 0 compile errors, 504 targets linked, ctest -N 502, 502 of 502 passed, CTEST_EXIT=0, with No space left and BFD both 0 against positive controls that return 1.

All the review's substance rode across unchanged: the res_2s arm routed through Ltx2GuidedDenoise rather than resolved textually, the dit_forwards counter that makes an unguided HQ arm RED, the substep-latent survivor closed, the tautological VT_CHECK replaced with the trace delta, and both generator scripts committed.