test(ltx-2.5): the register boundary, made numerically reachable (#435)

[localai-bot]

Closes review finding F1 (MEDIUM) on PR #574, plus the sibling F3 (LOW) and F4 (INFO). Issue: #435.

Base is row/LTX25-L9C-CONNECTOR-DRAIN at 708e05b56.

The gap

prompt_embeds_valid_rows is the single knob deciding which token positions become the connector's trained learnable_registers (104 of 128 rows on the accepted render). A fresh reviewer changed s = im.prompt_valid_rows to s = im.prompt_valid_rows + 1 at src/vllm/multimodal/ltx2_video.cpp:744 and test_ltx2_video stayed fully green — 23/23 cases, 253/253 assertions, exit 0. Reproduced here before anything was written.

The existing case asserts only that a render at valid=4 differs from one at valid=2. Any monotone corruption of the boundary keeps that true. The defect it cannot see is one padded row conditioned on caller junk instead of a trained register: finite, correctly shaped, plausible, wrong.

The closure

The substitution — not the mask — is what carries the boundary. binary_mask * hidden_states + (1 - binary_mask) * registers (embeddings_connector.py:148-150) replaces a masked position's features, so what the caller supplied there cannot reach the render. The mask carries nothing either way: :152 returns torch.zeros_like(mask), and _to_binary_mask's < 0.000001 (embeddings_processor.py:46-48) is satisfied by both values an additive mask holds.

So positions separate by whether perturbing them moves a byte, and the boundary is pinned from both sides:

• rows [valid, N) are registers → perturbing them must change nothing
• rows [0, valid) are caption → perturbing the last one must change something

Polarity from (attention_mask - 1) * finfo.max (transformer_args.py:203-206); contiguity from _compute_right_pad_order's stable descending argsort (embeddings_processor.py:33-38), which is what makes the padded set the suffix the extra names.

RED evidence

Each mutation applied to the product code, built and run in one chain, then restored — git diff empty and HEAD unchanged after every one.

mutation	failing subcase	doctest
prompt_valid_rows + 1	every row at or past the count is a register	1/1 failed, 110/111 assertions, Status: FAILURE!, exit 1
prompt_valid_rows - 1	the row just BEFORE the count is caption	1/1 failed, 110/111 assertions, Status: FAILURE!, exit 1
0	both caption arms	1/1 failed, 109/111 assertions, Status: FAILURE!, exit 1
v_rows	every row at or past the count is a register	1/1 failed, 110/111 assertions, Status: FAILURE!, exit 1

And + 1 over the whole suite: 24 | 23 passed | 1 failed, 364 | 363 passed | 1 failed. Only the new case moves — the reviewer's finding reproduced and closed in one run.

Siblings

F3. Ltx2ParseConnectorConfig reads connector_num_learnable_registers; neither configurator does (embeddings_connector.py:194-219, :222-256 both take the class default of 128), so "key for key" is not literally true of that key. The divergence is deliberate and stays, but a read nothing can falsify is a claim rather than a gate — so it now has one: the fixture's stored table stays [2, dim] while the config declares 4, and the shape check fires. REDs when the read is made inert (4/5 assertions).

The correction lands in porting-inventory.md and the test, not as a comment beside the parse: check-doc-checkpoint classifies src/vllm/model_executor/models/ as feature_surface and would demand a docs/FEATURES.md entry for a comment that changes no feature. The parse's existing comment already says "NOT read by either configurator".

F4. The masked-mask refusal claimed it fires at num_learnable_registers = 0. It cannot — with registers disabled the additive mask passes straight through and < 0.000001 is still true at every position. The comment and message now say the branch is unreachable on every input either reference produces, name what would reach it, and say why it is not gated.

porting-inventory.md's "mutation M3/M4" labels existed only in a PR body; replaced with the test case names, which are in the tree.

Not reproduced: the shipped-checkpoint case does not skip silently — MESSAGE: SKIPPED: set LTX2_CHECKPOINT_ROOT ... prints in the baseline run. It is invisible under ctest's output capture, and its env is deliberately not the tree-wide CHECKPOINT_ROOT (.env.example: that one "declares an INTENT, not a behaviour" and nothing reads it). Both now stated at the case.

Gate

Clean-configured CPU-only Release build (-DCMAKE_BUILD_TYPE=Release -DVLLM_CPP_CUDA=OFF), rebuilt from a wiped CMakeCache.txt/CMakeFiles:

• BUILD_EXIT=0, enospc_hits=0, werror_hits=0, df 89% throughout
• ctest -N → Total Tests: 399
• ctest -j4 → 100% tests passed, 0 tests failed out of 399, CTEST_EXIT=0
• test_ltx2_video → 24 | 24 passed | 0 failed, 365 | 365 passed | 0 failed, Status: SUCCESS! (baseline was 23 | 23, 253 | 253)
• check-doc-checkpoint.py --base 708e05b56 --head HEAD → OK

🤖 Generated with Claude Code

[localai-bot]

Landed on row/MODEL-DIFFUSION-LTX25 at aa6aa0ecd — 846301cfb is an ancestor (verified with git merge-base --is-ancestor), folded in via the L9-stack collapse at 2c1dda5df / 25bfd6640.

Closing rather than merging because the base branch it targeted (row/LTX25-L9C-CONNECTOR-DRAIN) has itself been collapsed into the campaign; merging here would re-open a stack that no longer exists. Nothing is lost — the commits are on the campaign branch and reach main through #437.

The finding it closed is worth restating, since it is the fourth instance of one class in this campaign: mutating prompt_valid_rows by +1 left the entire suite green, because the only case asserted that two renders DIFFER, and any monotone corruption of the boundary satisfies that. It is now pinned two-sided — +1, -1, 0 and v_rows each red exactly one subcase, and under +1 across the whole suite only the new case moves.