fix(LTX25-TILED-DECODE): chunking binds at 81 frames, and the untiled-axis mapper had no gate (#644)

[localai-bot]

Answers the FAIL review of PR #656 and the records FAIL review of this PR. Issue #644, spec .agents/specs/ltx25-tiled-decode.md.

Two reviewers have confirmed the engineering independently: all three refutations reproduced, the tiling goldens regenerated byte-for-byte, the memory probe reproduced at three scales, and Ltx2VideoDecodeStreaming verified bit-identical to the untiled path on the real checkpoint. None of that is re-litigated below. Every finding from both reviews is closed with reproduced RED/GREEN evidence.

F1 (BLOCKING) — temporal chunking binds at 81 frames, not 121

latent_t = (frames - 1) / 8 + 1 reaches 11 at 81 frames, and split_temporal_causal short-circuits only while latent_t <= 10 (tiling.py:239-240). Executed against upstream at the pin over range(1, 137, 8), the interval count goes 1 → 2 exactly at 81.

The row's own golden already said so — kLtx2AutoCases carries 768x768/81f -> t_intervals = 2, chunks = 2 — and docs/FEATURES.md said 81. Five prose sites said 121 and are corrected: ltx2_tiling.h, ltx2_video.cpp, docs/USAGE.md, and §0 / §1 / §2 of the spec.

Root cause, recorded because it is the reusable part. scripts/probe_ltx2_tiling_layout.py swept 9, 25, 25, 25, 121, 241 — it never sampled a frame count between 25 and 121, so it stepped over its own binding point and the number it happened to land on became the threshold. The probe now walks the temporal axis one latent frame at a time and asserts the transition is at 81, naming every file to reconcile if it ever moves. A sweep that skips its binding point now fails instead of publishing a number.

The 81–120 window is stated, not implied. docs/USAGE.md records the recipe default as 1024x1536 at 121 frames, so an ordinary request is inside it. scripts/probe_ltx2_tiled_equivalence.cpp measures it on the shipped conv VAE (ltx-2.5-video-vae-conv-bf16.safetensors, sha256 685b06ee3d9b2039647698fc4ea33175112462fc374e2777312c907897dfce8d) at 81 64 64:

[equiv] 64x64, latent 11,2,2  AUTO h=768/64 w=768/64 f=80/24
[equiv] tiles=2 groups=2  ->  untiled [3,81,64,64]  streamed [3,81,64,64] chunks=2
[equiv] max|diff| = 0.050304323434829712   non-bit-identical floats = 962983 / 995328
[equiv] untiled |out|max = 0.75126725435256958   ratio = 6.6959%
[equiv] (a FLAT append of the chunk buffers — the WRONG layout, kept only to show the size of the artifact — would report max|diff| = 0.71614238619804382, 985849 / 995328)

96.75% of channel values move, by up to 6.70% of the output's own range. That is upstream's behaviour, mirrored — but the one-tile control's safety argument covers below 81 frames and not 81–120, and now says so.

That headline was 0.716 — "95% of the output's own range" — until it was re-derived, and it was 14x too large. The probe reassembled the streamed chunks with a flat append, and a chunk is [C, t, H, W] CHANNEL-MAJOR (ltx2_video_vae.h:212-220), so appending buffers end to end is not [C, T, H, W] once C > 1 and there is more than one chunk — both true here (C = 3, chunks = 2). It was comparing channel 1 against channel 0's later frames. The refuted figure is kept named as refuted, and the corrected probe prints it as a labelled diagnostic on every run, so both columns come out of one binary on one run:

	flat-append artifact (REFUTED)	corrected
max|diff|	0.71614238619804382	0.050304323434829712
non-bit-identical	985849 / 995328 (99.05%)	962983 / 995328 (96.75%)
untiled |out|max	0.75126725435256958	0.75126725435256958
ratio of range	95.3%	6.6959%

The qualitative conclusion is untouched — nearly every value still moves, 81–120 is still a tiled regime the one-tile control does not cover, and the refusal stands. Only the magnitude was wrong, and it was wrong in the direction that made the argument look stronger.

F2 (BLOCKING) — the !IsTiled() mapper branches shipped ungated

Reproduced first. With map_t/map_s's {1.0f} broadcast masks set to {0.0f} — which multiplies the entire decoded volume by zero, i.e. renders a black clip — at the reviewed head:

test_ltx2_tiling : 9 cases | 9 passed | 0 failed ; 830 assertions | 830 passed  SUCCESS
test_ltx2_video  : 30 cases | 30 passed | 0 failed ; 502 assertions | 502 passed SUCCESS

Measured rather than assumed. Swept over all eight (frames, height, width) × (tiled, untiled) combinations against upstream at the pin:

frames	spatial	upstream tiled_decode
tiled	any combination	runs; max|diff| vs forward == 0.0
UNTILED	every combination	TypeError at conv_video_decoder.py:424

because DEFAULT_MAPPING_OPERATION hands it slice(0, None) and :424 subtracts that None stop. The two halves are therefore not symmetric, and are closed differently:

• the spatial half is gated end to end — a new UNTILED_SPATIAL arm in the generator (kLtx2TileDec*UpstreamUntiledSpatialVsUntiled, *UntiledSpatialChunkCount) and a (B'') control in RunDecodeArm on both causality arms;
• the temporal half is refused by name in Ltx2ConvVideoDecodeTiled, mirroring upstream's own failure rather than inventing a concrete stop upstream never computes. kLtx2TileDec*UpstreamUntiledFramesRaises records that upstream raises, so the refusal is mirrored and not local policy;
• the mapper output itself is pinned by new goldens section 3b (kLtx2UntiledMap*), upstream's create_tiles executed on an all-untiled config.

The same black-out mutation now goes RED: 10 cases → 7 passed / 3 failed, 907 assertions → 5 failed, exit 1, with untiled-spatial control max|diff| vs untiled = 2.31736 against upstream's 0. Restored (git diff empty), rebuilt GREEN.

F3 — the recorded ctest -N did not reproduce

It never could. 416 was the ninja edge count of ninja test_ltx2_tiling test_ltx2_vae test_ltx2_video, whose last line is [416/416] Linking CXX executable tests/test_ltx2_video — a build number read as a test number, so "full ctest 416/416" describes a run that never happened at that denominator. The real value and the configure line that produces it are recorded together under The gate below.

F4–F10

• F4 ltx2_video_vae.cpp:17-18 no longer records tiled decode as owed; the encoder half still is.
• F5 the shared Ltx2NoiseStream* across tiles is documented at the declaration and recorded under What is owed. It mirrors upstream (self.forward per tile, one generator) and is inert on the shipped checkpoint (timestep_conditioning: false, no inject_noise); a gate over a noise-drawing config is owed.
• F6 a new multi-chunk test_ltx2_video case drives chunk.first_frame + f through the PPM writer at 81 frames. Per-chunk numbering goes RED at 35 assertions.
• F7 a previous render's frame tail is deleted before a new render writes, so a shorter re-render can no longer be muxed past its own end. Disabling the cleanup goes RED at 72 assertions.
• F8 the "the full pixel volume is NEVER materialized" claim is bounded to the tiled case at both anchors — at one tile the chunk is the volume.
• F9 the compile line for both probes is recorded in their headers, with why they are deliberately not CMake targets.
• F10 the fixture's res_x_y block (a global GroupNorm the shipped ladder lacks) is disclosed in the test header, with which claim it affects and which it does not.

The records review of this PR — what closed each finding

F-A (BLOCKING) — this description still published the number the cycle exists to retract. The tree was corrected at five sites; the surface a merger reads was not. This body carried max|diff| = 0.716…, "99.05% of channel values move, by up to 95% of the output's own range", and a ctest -N of 448. That is this row's own defining failure — a 14x-wrong headline on a reader-facing surface — live on the pull request whose subject is repairing it. Closed by rewriting the body from a fresh run of the probe, by its own recorded recipe, on the merged head; the refuted figure stays, named as refuted, because a correction that deletes the wrong number teaches nothing.

F-B (BLOCKING) — 48 commits behind, two keyed records in conflict. git merge-tree --write-tree exited 1 with content conflicts in .agents/roadmap_v1.md and docs/FEATURES.md, both keyed records that must never take an automatic three-way merge. Both took main's file whole against a pinned origin/main SHA — never the moving ref, because this is a shared checkout and a peer's fetch advances it mid-operation. .agents/roadmap_v1.md is now byte-identical to main: this branch's only edit to it was one issue-intake row, and #846 moved that table into the append-only .agents/issue-index.md, where the #644 row already exists and is current, and where check-issue-index-append-only.py forbids editing a row and check_issue_index forbids duplicating one. docs/FEATURES.md differs from main by exactly one added line, this row's own key; every unrelated key is byte-identical, including the Safetensors direct load, no conversion row that was duplicated at the old head and is single on main (#769). The five silent auto-merges against c629b5d0f (the same campaign's image conditioning) were checked by semantics rather than by the absence of a conflict — a clean merge-tree is not a tree that builds — and the result rebuilt and re-gated from scratch.

F-C — the recorded test_op_parity red was expected at the old head and is gone. 043e56862 (fix(GATE-OP-PARITY-MANIFEST), closes #755) is in main and is not in the old head's ancestry (git merge-base --is-ancestor exit 1, positive control on the merge base exit 0). The 1-of-456 failure was therefore a missing fix, not a standing red, and it does not reproduce on this merged head.

F-D (nit) — the density assertion's message named only one of its two causes. The walk requires latent_t to advance by exactly 1 per step, so a step finer than 8 pixel frames repeats a depth and fails too — correct for the anti-fake purpose, but a future editor tightening the sweep would read the failure as "upstream moved the bound". The message now names both directions and says which fix each needs. Both mutations reproduce: step 8 → 80 exits 1 (latent_t jumps [(1, 11)], 2 frame counts visited) and step 8 → 4 exits 1 (17 zero-jumps, 34 frame counts visited); unmutated it exits 0 over 17 densely walked frame counts.

F-E (nit) — the raise-mechanism goldens were emitted into C string literals unescaped. A future upstream message or checkout path carrying a " or a backslash would have produced a golden that does not compile, while the generator reported success. Both fields now go through json.dumps. On today's values the output is byte-identical, proven rather than argued: the regenerated file's sha256 is bf2bdb4d43e73d4da73e360a816ee20e5f4b9224902fab9486fb173822a41d12, equal to the committed one, diff exit 0.

The gate

Head 84e2ec8ee67c839817a2f932dd81dc3c03dd4432, whose tree is e34e10e37b892dc36167fa677c845850ba2445e2 plus this spec's gate record; the gate itself was run on e34e10e37, which merges main pinned at b5a5f3b182d7e8c1b4b3781da32726d3d6eda5ec. Two merge commits, each resolved against a pinned SHA rather than the moving ref: 02444f5ff (main @ 51e0cb5b1, 48 commits, the two keyed-record conflicts of F-B) and e34e10e37 (main @ b5a5f3b18, whose Music3 row sits immediately above this row's docs/FEATURES.md key and conflicts for that reason alone; resolved the same way). Every number below is from this head — nothing is carried forward.

Clean rm -rf build + cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + ninja -C build. BUILD_EXIT=0 captured separately from the run, [1407/1407] reached. No space left|BFD assertion count 0 against a positive control of 925 Building CXX lines in the same log; warning: count 0. df -h / 80G free (82%) at the end; uptime load average 30.2. The build directory was deleted immediately after the gate.

ctest -N is 474 here and 473 on main, measured with the same command and attributed rather than asserted: test_ltx2_tiling is Test #73 in this listing and absent from main's (grep -c 1 here, 0 there), git diff b5a5f3b18 -- tests/CMakeLists.txt is exactly +7 lines (that one registration) with no target added or removed anywhere else, and grep -c '^vllm_cpp_add_test(' goes 448 on main to 449 here. Main's side was measured by configuring main's own two CMakeLists.txt files in a scratch build directory, which was deleted; both files were restored and verified by sha256sum, not by git status.

Focused, with COUNTS — a changed count is RED unless attributed:

suite	cases	assertions	vs the pre-merge head (70fddfa)
test_ltx2_tiling	10 / 10	915 / 915	unchanged
test_ltx2_vae	36 / 36	3039 / 3039	unchanged
test_ltx2_video	34 / 34	747 / 747	was 32 / 684; the +2 cases arrive with main, not from this row — grep -c '^TEST_CASE(' is 33 on main and 34 here, and git diff b5a5f3b18 on that file adds exactly one TEST_CASE and removes none
test_ltx2_pipeline	37 / 37	2382 / 2382	unchanged

Full: ctest --test-dir build -j6 --output-on-failure → 474 passed / 0 failed out of 474, 168.50 s, ctest exit 0, with 474 lines matching ^ *[0-9]+/474 Test in the log, so the run's own denominator is asserted against ctest -N rather than assumed equal to it. Two tests report Skipped by their own guards (test_modelopt_mixed_precision_checkpoint, test_voxtral_e2e).

Known-red

None in this gate. Two are worth recording because they were expected and did not happen:

• test_op_parity is GREEN (Test #422). Its recorded 1-of-456 red at the pre-merge head was a missing fix rather than a standing red — see F-C above.
• test_serve_low_tools failed in the intermediate -j6 run at 0bf0eb9a8 under load average 90–133 and passed serially in 23.54 s; on the quieter box at this head it passes in the parallel run too. It is -j starvation, not a regression.

test_cpu_x86_llamacpp_floor (#618), windows-msvc-* (#664/#720/#757) and sanitize-cpu (#627) are the in-flight repo-wide reds; untouched here. scripts/agent-preflight.sh passes at this head, test_cpu_x86_llamacpp_floor included.

🤖 Generated with Claude Code