fix(LTX25-RETIRE-DEAD-ARMS): retire the invented refusals, and the assertion that could not fail (#644, #611)

[localai-bot]

Retires the arms of the LTX-2.5 out-of-scope ledger that do not exist upstream, refuses the load extra that was accepted and read by nothing, and — after four rounds of review — repairs the ledger's own claim about which refusals a request can reach. 12 files, +2148/−54: spec, header, refusal messages, two public documents, and the tests that hold each claim.

Tracks #611 and #644 items D–I and N. Pattern this row is an instance of: #604. Spec: .agents/specs/ltx25-retire-dead-arms.md. Pins: Lightricks/LTX-2 @ fd4ded7f, huggingface/diffusers @ 3a2f35d4, vllm-project/vllm-omni @ a4ea67a21.

Closes #889. Closes #890. Closes #892.

#893 stays open on purpose and must not be closed by this merge: it is the ## Nothing lands dead disclosure for Ltx2Schedule, which this branch labels honestly rather than wires. #611 and #691 also stay open, with their remaining halves named at the end.

The body that was here belonged to #880, and replacing it is part of this change. The repository sets squash_merge_commit_message = PR_BODY, so this field is the landed commit message. It carried, verbatim, the already-merged body of #880 (keyframes_abs_pos_embedding) — a different row, a different issue, a different diff, 22 files that are not these 12. Landing it would have written a permanent commit message describing work already on main. No gate can catch that: the trailer and style checkers validate the body's shape, and its shape was perfect. Recorded rather than quietly swapped, because "the body is the commit message" only protects the history if somebody checks that it describes this change.

What was wrong

Ltx2UnportedPipelineFeature is a ledger of arms this port refuses by name. Read as a whole it claimed more than was true, in five separate ways.

1. One arm was fabricated. kMultishot refused "multishot generation" and cited "ltx-pipelines multishot entry points". No such entry point, symbol or string exists in either reference. Retired.
2. One arm was stale. kVideoEngineWiring said the end-to-end composition "is phase L7, not L5". L7 landed in cefacd2d0. A refusal whose subject shipped is a false statement. Retired.
3. One arm's name described something upstream does not do. kCfgParallelism was anchored to ltx-pipelines/multigpu, which contains no CFG batching. Renamed kMultiGpuParallelism and re-anchored.
4. "Refused by name" overstated a marker. Most entries have no product call site: nothing a caller can send reaches them. A declared boundary is worth having — calling it a refusal was the defect. The ledger, the header, the messages and both public documents now distinguish a reachable refusal from a declared-out-of-scope marker.
5. duration_head_path was accepted and read by nothing (LTX-2.5: duration_head_path is accepted and never read — a caller who supplies it silently gets the recipe default #611). A caller who pointed at a duration head silently got the recipe default. Now refused by name, with the full ten-key kKnownLoadExtras inventory recorded and gated.

The four review rounds

Every finding is written into the spec's ## Outcome rather than summarised away, because the findings are the row's subject.

Round	Finding	Where it had shipped
1	"int8 appears upstream only in the trainer" is false; hadamard is not 0 hits	the user-visible refusal message, and §1.2
2	Nine reader anchors stale, off by 37 lines and then by another 25	§2.1, cited in the file they were wrong about
3	scene asserted trainer-only; the shot file list offered as exhaustive at five when it is seven	the shipped header, and §1.1
4	cfg asserted absent from both multigpu trees; a fourth form omitted (#892)	the shipped header and message, and §1.3
4	kBetaScheduler published as reachable with no caller (#889)	header, docs/FEATURES.md, docs/USAGE.md, §1.6
4	The one genuinely reachable refusal shadowed by a guard over the same variable (#890)	ltx2_video.cpp

The first four are one defect: an absence asserted from our own vocabulary, with no positive control, three of them behind a path filter that excluded the files carrying the answer. A row whose stated purpose is retiring instances of #604 committed four of them, three into files a user or a porter reads.

The last two are a different defect and worth separating. They were not inaccurate citations. They were classification and control flow, and between them the ledger's reachable column was empty in practice while two public surfaces published two entries in it.

#889 — a refusal nothing calls

The header defines a reachable refusal as one "a caller CAN trip", and docs/USAGE.md published "Both are reachable — a render asking for either gets a refusal naming the missing piece." Neither was true of kBetaScheduler. Its site ltx2_pipeline.cpp:199 sits inside Ltx2Schedule, and Ltx2Schedule has zero call sites in src/, include/ or examples/. The engine calls Ltx2SigmaSchedule directly, and no ABI field, load extra or CLI flag carries a scheduler kind. The only driver is the unit test that constructs the enumerator by hand.

§1.6 had asked whether an enumerator appears in src/. That question's true answer is the wrong answer: a case label is not a caller.

Upstream decides the repair, and it forbids the wiring one. At fd4ded7f, BetaScheduler is defined at ltx-core components/schedulers.py:91 and constructed nowhere in the repository. All seven ltx-pipelines entry points hard-code LTX2Scheduler(): ti2vid_one_stage.py:81, ti2vid_two_stages.py:87, ti2vid_two_stages_hq.py:90, a2vid_two_stage.py:78, t2a_one_stage.py:67, keyframe_interpolation.py:82, retake.py:96. vLLM-Omni a4ea67a21 has zero hits for the name, against 81 files carrying ltx as the control. Routing the engine through Ltx2Schedule would have invented a scheduler-selection surface upstream does not have, so mirroring upstream means reclassifying the arm as a marker.

The split is now derived rather than written. test_ltx2_pipeline gains "the reachable/marker split matches the source": it walks the product tree, counts callers of each arm's entry function, and requires the message to agree in both directions — no caller demands DECLARED, NOT REQUESTABLE, and a caller appearing later forbids it. Two positive controls ride in the same walk, plus a file-count floor, because this is an absence claim about our own tree and this row has already shipped four of those. That is the anti-tautological shape #691 asks for, applied to the beta arm; #691 stays open for the three markers that have no call site to derive from.

#890 — the shadowed arm

The phase guard tested im.upsampler_cfg.temporal_upsample alone. Every both-flags config satisfies that too, so the two guards were an implication over one variable and this one always fired first. A caller supplying a genuine spatiotemporal checkpoint was told it is the TEMPORAL x2 upsampler and pointed at the spatial one: wrong on both counts, and pointing them at the arm they already had. It also made the ledger refusal at ltx2_upsampler.cpp:465 unreachable from any request — so after #889, the reachable column was empty.

Narrowed to temporal_upsample && !spatial_upsample, so a both-flags config falls through to the refusal that names the correct arm.

The reviewer who found this named a real limit on their own evidence: no fixture drove a both-flags checkpoint through LoadVideoEngine, so mutation could not separate "unreachable" from "untested", and only the static implication settled it. That hole is closed here, and closed the way AGENTS.md ## Nothing lands dead requires — the new subcase drives the checkpoint through LoadVideoEngine + Generate, not through a direct call to Ltx2LatentUpsample.

#892 — a fourth form, hidden by a path filter

The header shipped an assertion that cfg is absent from both multigpu trees; the refusal shipped "three forms". Re-derived at the pin, with the file list as the control in the same pass:

git ls-files -- '*multigpu*'        ->  33 files   (the control)
git grep -n -i cfg -- '*multigpu*'  ->   5 lines   (not 0)

Two of the five are substantive prose at docs/multigpu/gemma.md:103-104. The spec's grep was correct and its path filter was wrong: scoped to the two SOURCE trees, it excluded docs/multigpu/, where the answer is written out. There is also a fourth BuilderProtocol in the directory the refusal cites — multigpu/bp_gemma_builder.py:42, BatchParallelGemmaBuilder, which partitions a prompt list across ranks.

The disposition is unchanged and stronger. gemma.md:104 records that the distilled pipeline this port runs takes no negative_prompt and "runs without CFG", so the one form that would carry a CFG pair is the one upstream tells you not to use here. A reason beats an absence.

Nothing lands dead: the disclosure this owes

AGENTS.md ## Nothing lands dead and .agents/reachability.md landed in 8f49ac3be (#886) while this repair was in flight, and they name #889's shape exactly: the test-only driver, where the only thing that calls the new code is the test written for it. The guide ships no checker and says why, so there is no exit code to report.

Per that rule, stated here, in the commit body, and under ## Owed in the spec: Ltx2Schedule and Ltx2SchedulerKind are UNREACHED. Owned by row LTX25-RETIRE-DEAD-ARMS, tracked by #893. This is not a staged slice awaiting a wiring wave — upstream selects no scheduler anywhere, so there is nothing to wire it to. The open decision is retire-or-keep-as-recorded-mirror, and that is a behaviour change owing its own red-first evidence, which is why this branch labels the arm honestly and does not also delete the dispatcher.

Red before, green after

Repair	RED before	GREEN after
#889	split case reports Ltx2Schedule callers = <none> with both controls live; DECLARED, NOT REQUESTABLE absent from the message	test_ltx2_pipeline 42/42 cases, 2485 assertions, exit 0
#890	SPATIOTEMPORAL absent; it is the TEMPORAL x2 upsampler and Supply the spatial upsampler both present	test_ltx2_video 40/40 cases, 827 assertions, exit 0
#892	three forms present; four forms / BatchParallelGemmaBuilder / gemma.md absent; header cfg sentence present at offset 32030	included above

The full RED run was test_ltx2_pipeline 39/42 cases with 8 assertions failing, and test_ltx2_video red on the new subcase.

Four mutations, each of which BUILT with 0 errors before it was run — a mutation that fails to compile reads as a passing test:

Mutation	BUILT	Result
Widen the guard back to temporal_upsample alone	yes, 0 errors	RED, 3 assertions
Reachability mutation: delete the production call site Ltx2UpsampleVideoLatent	yes, 0 errors	RED in test_ltx2_video, and it fires the split case's positive control, which then reports Ltx2UpsampleVideoLatent callers = <none>
Drop the marker suffix from the beta refusal	yes, 0 errors	RED in both the ledger case and the split case
Restore "three forms" in the message	yes, 0 errors	RED, 2 assertions

The tree was restored byte-for-byte after each, verified by sha256sum -c.

One consequence worth recording, because it cost a build cycle: the header may not QUOTE the retired sentence while explaining it. A text gate matches text and cannot tell a quotation from a claim. The corrected note describes the old sentence instead of reproducing it, and says so in the comment.

Keyed records, edited by key

docs/FEATURES.md and docs/USAGE.md are keyed records. Exactly two FEATURES rows change; the other 365 lines are byte-identical, verified by sha256 of the filtered file, with the filter's own line count (367 → 365 on both sides) as the positive control. docs/FEATURES.md:165 "Temporal x2 ups gated, UNDRIVEN" is untouched, verified by sha256 of that line against HEAD. In docs/USAGE.md only one paragraph moves: lines 1–1956 hash identically, and the tail hashes identically at a 5-line offset.

.agents/issue-index.md gains four rows and loses none — git diff --numstat reads 4 0, against a positive control showing the same tool reporting 11 6 for docs/USAGE.md. scripts/check-issue-index-append-only.py exits 0.

Every file:line anchor was re-derived at this tree and asserted unique, not merely present. Three were correct: ltx2_upsampler.cpp:465, ltx2_pipeline.cpp:199, ltx2_pipeline.cpp:191. Two had moved with the merge and are now named by symbol instead of by line, because ltx2_video.cpp moves on every merge and three anchors in this row went stale inside one branch. The nine derived READER ANCHORS moved five lines when 98f8e046d landed; the gate that derives them caught it, which is what it was built for.

Gate

CPU, this box, clean configure into a fresh build/. Shared and busy: another session was running its own ctest -j 8 concurrently and load average sat between 11 and 84 during the run.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DVLLM_CPP_CUDA=OFF   CONFIGURE_EXIT=0
cmake --build build -j6                                                      BUILD_EXIT=0
ctest --test-dir build -j4 --output-on-failure                               CTEST_EXIT=0

grep -c ': error:' over the build log = 0. No space left = 0 and BFD assertion = 0, against positive controls of 603 Building CXX and 478 Linking CXX lines, so the log was searchable and carries no ENOSPC. The build ended [1083/1083]. df -h / 32G free (93%) after the build.

ctest -N = 477, which is main's count: this branch registers no new ctest entry. git diff <merge-base>..HEAD -- tests/CMakeLists.txt | grep '^+' | grep -cE 'vllm_cpp_add_test|add_test\(' = 0, against a positive control of 1 for 07457f87c, which did add one. The CMake change is three target_compile_definitions blocks and their comments.

Full suite: 100% tests passed, 0 tests failed out of 477, 250.14 s. Two did not run and neither belongs to this row: test_modelopt_mixed_precision_checkpoint and test_voxtral_e2e, both Skipped. The same ENOSPC grep over the ctest log is 0 against a positive control of 475 Passed lines.

No known-red fired in this run, including test_cpu_x86_llamacpp_floor (#618) despite the load. Read that as this branch not adding one, not as those issues closing.

scripts/agent-preflight.sh reports the seven CI-wiring failures that are pre-existing on main (check-release-binary-contract, check-release-workflow, check-test-registration and their four suites; root cause #873, fix in flight as #878). Proven pre-existing rather than asserted: git diff origin/main HEAD over every input those checkers read — scripts/check-test-registration.py, scripts/check-release-binary-contract.py, scripts/check-release-workflow.py, their four test scripts, and .github/workflows/ — is empty, against a positive control where the same command reports docs/FEATURES.md and src/vllm/multimodal/ltx2_video.cpp.

check-commit-style.py --range <merge-base>..HEAD and check-commit-trailers.py --range <merge-base>..HEAD both exit 0. The trailer gate initially failed on the two git merge commits, which carried no trailer block — rev-list includes merge commits and the checker has no exemption for them. Repaired by redoing the merge with an authored message rather than by exempting anything, and ea6b01f1f remains an ancestor of this head, so the push is a fast-forward and nothing was force-pushed.

Not in scope, still owed

Constructing a duration head (#611; its user-visible half, silent substitution of the recipe default, is closed). The retire-or-keep decision on Ltx2Schedule (#893). The anti-tautological gate for the three markers that have no call site to derive from (#691). .agents/specs/ltx-2-5.md §2 "Out" still lists multishot and is operator-owned (#692).

FOLLOWING_AGENTS_PROTOCOL

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