fix(LTX25-RETIRE-DEAD-ARMS): retire the invented refusals, refuse the ignored extra (#644, #611)

[localai-bot]

Row LTX25-RETIRE-DEAD-ARMS. Closes part of #644 (items D–I and N); addresses #611.
Files #691 and #692. Spec:
.agents/specs/ltx25-retire-dead-arms.md,
committed before code.

Our LTX-2.5 refusal ledger claimed more than was true, and one load extra was
accepted and read by nothing. Every claim below was re-derived against
Lightricks/LTX-2 fd4ded7f and huggingface/diffusers 3a2f35d4, both verified
with git rev-parse HEAD on the local checkouts. A prior grounding report was an
input, never a result.

This body was itself corrected by review. The first version of this PR
shipped two false absence claims of exactly the kind the row exists to retire.
Both are fixed in 2d1d59d9f; see Review repair for what
changed and why. Read that section before the sections above it — they are the
corrected text, not the original.

Retired — defects in our record, not gaps in our port

kMultishot was FABRICATED. It refused "multishot generation" and its enum
comment cited "ltx-pipelines multishot entry points". No such entry point,
symbol or string exists in either reference. Searched as a subject rather than
from our own phrasing (the self-confirming-grep trap, #604):

• multishot / multi_shot / multi-shot: 0 hits, both references.
• The only upstream sense of "shot" is one camera take — duration_head.py:1,5
  "predicts shot duration", README.md:136 "think like a cinematographer
  describing a shot list", and in diffusers, where the word is far more common,
  utils.py:217 "Shot type (exactly one: extreme wide shot / wide shot / medium
  shot / …)".
• The only scene hit is PySceneDetect in the trainer.
• ltx-pipelines has 11 documented pipelines and diffusers 16 ltx2/ modules;
  none is multi-shot.

kVideoEngineWiring was STALE. It said the wiring through
vllm::multimodal::VideoEngine "is phase L7, not L5". L7 landed in cefacd2d0.
A refusal whose subject shipped is a false statement, not a record of debt.

Both retirements are recorded in the header, in the spec, and in their commit
messages — which is where an exception's reason lives (AGENTS.md, "there is no
waiver registry").

Re-anchored

kCfgParallelism → kMultiGpuParallelism. Zero cfg hits in either
multigpu/ tree. The three real forms are sequence-parallel (sp_builder.py:25),
tiled data parallel (tdp_builder.py:25, upscale only) and distributed VAE decode
(distributed_decoder.py:204-256). Upstream calls MGPU "a latency tool, not a
memory tool" (docs/multigpu/README.md:5-16), and there is no CFG pass here to
split anyway: the distilled recipe runs SimpleDenoiser at both stages
(distilled.py:266,295), documented "single transformer call, no guidance"
(denoisers.py:3), with cfg_scale=1.0, stg_scale=0.0 (denoisers.py:25-26).

kInt8ConvRot is UNREACHABLE upstream — not absent. (Corrected by review;
the first version of this PR said "verified absent" and "int8 appears upstream
only in the trainer", and both were false.) convrot / conv_rot / quarot /
spinquant really are 0 hits. But two things do exist:

• A dead int8 kernel in an INFERENCE package. ltx-kernels
blockwise/triton_ops.py:25-50 is a per-row int8 quantize with fp32 scales —
  output dtype torch.int8 at :43 — aliased rowwise_int_quantize_triton at
  :436. That alias is its only reference; blockwise/functional.py:12-18
  re-exports five other names and not this one. The package is a fork of
  Lightricks' int8 kernel library retargeted to fp8/fp6/nvfp4, and its custom-op
  namespace is still literally q8_kernels_ops (functional.py:25).
• A vendored fast-Hadamard-transform family, quantization-coupled.
  ltx-kernels/csrc/ops/include/ carries Tri Dao's FHT with
  DequantHadamardParamsBase:54, QuantHadamardParamsBase:71 and
  QuantMax<int8_t> at fast_hadamard_transform_common.h:14. A Hadamard
  transform is the "rot" of QuaRot/SpinQuant, so "0 hits for hadamard" was
  wrong on the one search term that mattered.

The disposition is unchanged, because nothing calls either. hadamard_mult_thread
/ _warp have no call site in csrc/; fast_hadamard_transform_cuda is
commented out (rms_norm_rope_cuda.cu:225-228); and the only live struct,
NormRopeHadamardParamsBase, drives norm_rope_cvt_kernel
(rms_norm_rope_cuda.cu:51-170), which is RMS-norm → RoPE → store with no
rotation at all, instantiated for bf16 and Float8_e4m3fn only (:219-223).
Upstream's four wired inference quantization kinds (quantization_factory.py:23-26
— the first version of this PR miscited this as :23-27) are fp8-cast,
fp8-scaled-mm, nvfp4-cast and nvfp4-prequant. None is int8.

Classified

Five of the seven enumerators had no product call site — only
kTemporalUpsampler (ltx2_upsampler.cpp:395) and kBetaScheduler
(ltx2_pipeline.cpp:199) are constructed by a product path. Recording the rest as
"refused by name" overstated what exists. The header, the messages and the ledger
test now separate a reachable refusal from a declared-out-of-scope marker,
and the marker messages say DECLARED, NOT REQUESTABLE.

docs/FEATURES.md now carries that split as two rows, not one. The first
version of this PR re-merged it into a single "Declared, not requestable" row
covering all five arms, which mislabelled the two a caller can actually trip —
the exact conflation the code change had just removed.

Refused — the user-visible half (#611)

duration_head_path was in kKnownLoadExtras and read by nothing, so a caller
who pointed at a duration head silently got the recipe default. CheckUnservedExtras
now refuses it by name, saying the head is unported, why the file would never be
opened, and to use num_frames / duration instead.

Not by dropping the key: "unknown load extra" would claim the family does not
define it, which is false and sends the reader hunting a typo.

The full kKnownLoadExtras audit — the durable half of this PR

All ten keys. Every reader is inside Ltx2VideoEngine::Load in
src/vllm/multimodal/ltx2_video.cpp, so the column below names the value each key
is read into — that is what a line number was standing in for, and unlike a
line number it does not go stale:

Key	Read into	Status
audio_prompt_embeds_path	audio_embeds_path	READ
pipeline_kind	im.pipeline_kind	READ
model_version	override_version	READ
allow_unported_modules	dit_options.allow_unported_modules	READ
max_phase	im.max_phase	READ
dit_config_path	config_path	READ
prompt_embeds_valid_rows	im.prompt_valid_rows	READ
encoder_config_path	encoder_config_path	READ
upsampler_path	upsampler_path	READ
duration_head_path	nothing	was ACCEPTED AND IGNORED — now refused

Nine of ten were wired; duration_head_path was the only defect, so #611's "audit
the rest the same way" is closed rather than sampled. One documentation gap found
by the same sweep: docs/USAGE.md listed the LTX-2.5 extras and omitted
encoder_config_path, which is defined and read. Fixed.

Line numbers are no longer written by hand anywhere in this row. The first
version of this PR recorded them, in the source file they were wrong about, and
review found nine of nine stale by +37. Correcting them by hand was not enough:
merging origin/main moved the real ones again inside this same PR. They now live
in one READER ANCHORS comment that test_ltx2_video derives from the source
on every run, printing the replacement list when they drift. The test hard-codes
no line number itself, so it cannot rot, and the only obligation it creates falls
on whoever moves a reader, in the file they are already editing.

Review repair

A fresh review of 4e5be2585 returned FAIL with six findings, all of them
evidence accuracy rather than logic. No disposition moved. Two are instances
of #604 — an absence asserted from a grep of our own vocabulary — committed inside
the row whose whole purpose is to close them.

	Finding	Where
F1	"int8 appears upstream only in the trainer", shipped in a user-visible refusal message. False: a dead int8 quantize kernel lives in the ltx-kernels inference package	fixed, 2d1d59d9f
F2	The spec listed hadamard among "0 hits" and concluded "no rotation of any kind". False: LTX-2 vendors a quantization-coupled fast-Hadamard family. Conclusion survives on different, re-derived evidence	fixed, 2d1d59d9f
F3	Nine reader anchors stale by +37, cited in the file they were wrong about	fixed, 2d1d59d9f — now derived, not recorded
F4	docs/FEATURES.md re-merged the reachable/marker split into one row	fixed, 2d1d59d9f
F5	The split gates message text, not reachability: give kLoraFusion a call site and the test stays green while the refusal tells the caller it is not requestable	filed #691
F6	.agents/specs/ltx-2-5.md:291 still records the fabricated multishot arm as owed; operator-owned file, out of this row's scope	filed #692

F5 and F6 are placed in the roadmap issue table under ROAD-V1-LTX25 and named in
this row's spec §3 "Out", so the three surfaces agree.

RED before GREEN

The original two cases failed before the fix, for exactly the intended reason —
the load succeeded:

[doctest] test cases:  2 |  0 passed | 2 failed | 30 skipped
[doctest] assertions: 14 | 12 passed | 2 failed |
[doctest] Status: FAILURE!

Each repair was red first as well, against the shipped artifact it corrects:

• F1 — test_ltx2_pipeline.cpp:1303,1306 failed against the shipped
  kInt8ConvRot message.
• F3 — Recorded: []. Actual: [638 693 789 805 807 839 864 969 1010].
• F4 — both reachable arms found on the single conflated FEATURES.md row.

F2 is prose in a spec about an upstream checkout; no test in this tree can carry
it, so it is stated as re-derived evidence instead.

The inventory case parses the accepted list out of the unknown-extra refusal,
which is built from kKnownLoadExtras itself, so an eleventh decorative key fails
it. Asserting on a copy of the list kept in the test would have been true by
construction and gated nothing.

Mutation-proven, four ways

Every claimed guarantee was mutated in the built tree and each mutation went red;
the tree was then restored byte-for-byte (git status clean, git diff HEAD
empty).

Mutation	Result
Add an eleventh key to kKnownLoadExtras	RED — kKnownLoadExtras grew; add the key to served or refused (and the anchor case fires too, since the inserted line moved every reader)
if (false && !duration_head.empty()) in CheckUnservedExtras	RED — duration_head_path is served by no code + an accepted-but-unread extra must be refused by name
Re-insert multishot, drop marker from kLoraFusion	RED — both CHECK_FALSE(Mentions(message, "multishot")) and CHECK(Mentions(message, "DECLARED, NOT REQUESTABLE"))
Add marker to the reachable kBetaScheduler	RED — CHECK_FALSE(Mentions(message, "DECLARED, NOT REQUESTABLE"))

The third and fourth are the two directions of the F4 split, so it is proven not
to be one-sided. Note that the second mutation prints assertions: 537 | 535 passed while failing — the exit code is the authority, not the summary line.

Gate

Re-run in full after merging origin/main (7965f12bf .. 5498b4aea, 37
commits), from a fresh configure into a deleted build tree — the previous one
was reclaimed by a disk sweep, so nothing here is incremental.

CONFIGURE_EXIT=0, BUILD_EXIT=0 (1319/1319 targets), ENOSPC_HITS=0 — no
No space left, no BFD assertion.

ctest -N → 444. ctest --output-on-failure (serial) → 444 executed,
99% passed, 1 failed, 991.76 s. The denominator is asserted against the run:
444 enumerated, 444 executed. Two pre-existing environment skips:
test_modelopt_mixed_precision_checkpoint, test_voxtral_e2e.

The one failure is #737 and is not this PR's. test_op_parity throws
[json.exception.type_error.302] type must be string, but is null at
tests/parity/test_op_parity.cpp:1989 — the null field in the MiniMax-Music3
golden manifest added to main today, already filed and reproduced on clean main.
This branch touches no golden, no manifest and nothing under tests/parity/
(12 files changed, all LTX-2.5 source, tests, spec and docs). Note its summary
line reads assertions: 70 | 70 passed | 0 failed while failing — a thrown
test case is invisible to the assertion counter, so the exit code is the authority.

ctest -N moved 423 → 444 since the first version of this PR. Fully attributed to
main: this branch adds zero test registrations (git diff origin/main...HEAD | grep '^+.*add_test' → nothing), and main's newest merged commit 5498b4aea adds
test_qwen3_8_text_only, which is the last of them.

Suite	Before	After
test_ltx2_video	30 cases / 502 assertions SUCCESS	33 cases / 541 assertions SUCCESS
test_ltx2_pipeline	37 cases / 2382 assertions SUCCESS	38 cases / 2395 assertions SUCCESS

Both exit 0. The before column was measured, not reasoned about: the
pre-change versions of the touched files were checked out, rebuilt and run, then
restored. The ledger case itself drops from 7 to 5 entries — a changed count,
and it is the retirement — while gaining assertions rather than losing them. The
post-merge counts are identical to the pre-merge ones, which is the check that
main's 37 commits changed nothing for this row; main touched none of this row's
source or tests across that range.

scripts/agent-preflight.sh --staged at commit time: all checkers green, including
doc-checkpoint --staged, which required the docs/USAGE.md paragraph in this
diff (include/vllm/… is classified user_usage).

scripts/agent-preflight.sh in full: two failures, both #733 / #731 and both
already open against clean main — audit-live-rows and its mutation suite
test_audit_live_rows, on
MODEL-MUSIC-minimax-music3-mini-max-music3-for-conditional-generation
(.agents/model-matrix.md:459), an ACTIVE row with "no branch, no commit on main
mentioning the row ID". Isolated by measurement rather than argued: this branch's
only .agents/ edits (two roadmap issue rows and one new spec file) were reverted
in place and the checker re-run, and its output is byte-identical with and
without them, exit 1 both ways. This branch does not touch model-matrix.md,
engine-matrix.md, backend-matrix.md or feature-matrix.md.

Two further environment notes, recorded because they were hit and would otherwise be
misread as findings. tests/scripts/test_cpu_x86_llamacpp_floor.py failed with
NO_QUIET_WINDOW (exit 4, busy=362% load=100.52) while other sessions were
building, and passed on re-run; this PR touches no scripts/ file.
test_openai_conformance failed three times in a row at load 95–127 — all
client-timeout shapes against a 30 s read timeout, with a different failing
assertion set each time — and passes in the gate above. Neither is a finding.

🤖 Generated with Claude Code