record(LTX25-PROMPT-ADALN): the prompt-AdaLN defect was understated ~138x, and the keyframes claim next door was false (#644)

[localai-bot]

Claims-and-records repair for #644, on top of #654. The port itself is untouched
— reviewed PASS, and nothing executable changes here except three refusal
messages.

F1 — the headline numbers were fixture artifacts, and the truth is far worse

The spec Outcome, #654's body and tests/vllm/models/test_ltx2.cpp all quoted
51.7% ("term vs table") and 5.82% (block-0 K/V) as the answer to "does
this matter". Both come from the generator's synthetic init: the static
prompt_scale_shift_table and every prompt-AdaLN MLP parameter are drawn
from the same param_spec rule at scale=0.05
(scripts/gen-ltx2-goldens.py:100-106), so the ratio between them is a property
of the FIXTURE — it moves with the init scale (0.005 → 4.1%, 0.2 → 1450%). The
Outcome disclaimed only the two OUTPUT rows as synthetic-bounded and then called
the other two the answer, though all four have identical provenance.

Re-measured here on the shipped weights, through upstream's own
AdaLayerNormSingle(dim, embedding_coefficient=2) evaluated on sigma * 1000
exactly as transformer_args.py:274-278 / :177 do, against all 48
prompt_scale_shift_table / audio_prompt_scale_shift_table tensors of
/mnt/nas_share/checkpoints/ltx-2.5/lightricks-ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-nvfp4.safetensors,
with ltx_core at fd4ded7f imported by path and its __file__ asserted:

	video (4096)	audio (2048)
rms|table|, 48 blocks	0.017553	0.021925
rms|term|, uniform σ∈[0,1]	0.236446	0.347171
term/table, RMS	1347%	1583%
max|term| / max|table|	7119%	2817%
term/table RMS, the file's own LinearQuadratic sampler, 8 steps	1275%	1492%

Like for like — the fixture ratio is max-vs-max and so is the shipped one —
per stream, each against its OWN fixture denominator:

	fixture max|term|/max|table|	shipped	understatement
video (prompt_adaln_single vs prompt_scale_shift_table)	51.7%	7119%	138x
audio (audio_prompt_adaln_single vs audio_prompt_scale_shift_table)	40.6%	2817%	69x

Corrected 2026-08-13 (review finding F-2). This read "138x (video) and 54x
(audio)" as if both were per-stream. The video figure is right and
like-for-like. The audio one divided the shipped AUDIO ratio by the VIDEO
fixture denominator, because gen-ltx2-goldens.py emits exactly one fixture
ratio and it is the video stream's. 54x is literally true about that single
published figure and errs CONSERVATIVE. The audio stream's own fixture ratio,
recomputed with the identical statistic on the identical fixture (the generator
is imported, so no weight is re-drawn), is 40.6% — max|term| 0.0201763 vs
max|table| 0.0496868 — giving 2817 / 40.6 = 69x. Video re-derived in the
same run: 0.0252012 / 0.0487142 = 51.7327%, and 7119 / 51.73 = 137.6.

Fixed at the source. The generator emitted BOTH video-only rows unlabelled
— "timestep term vs static table" and "block 0 modulated prompt K/V" — which is
how a video denominator came to be applied to an audio numerator.
gen-ltx2-goldens.py now names the stream on both and ltx2_goldens.inc was
regenerated against ltx_core fd4ded7f (REGEN_EXIT=0); the diff is
those two comment lines and nothing else, every golden VALUE byte-identical,
the Regenerate with: header unchanged because the committed command was re-run
verbatim. test_ltx2.cpp and the spec's gate-floor table say the same.

On the shipped model the timestep term DOMINATES the static
table; the table is the perturbation. Pre-row renders applied
context*(1 + ~0.018 rms) + ~0.018 where upstream applies
context*(1 + ~0.32 rms) + ~0.10; stated as the quantity actually consumed at
transformer.py:446, on a unit-rms context the modulated context moves +8.8%
(video) and +31.3% (audio).

Both dispositions the finding offered are taken. The four fixture rows are
now labelled GATE-FLOOR numbers from synthetic weights — in the spec, in the
goldens' emitted comment block, and in test_ltx2.cpp — and the
real-checkpoint measurement is stated as the answer to "does this matter".
Labelling alone would have left the spec with no answer to its own §6 question;
stating the real numbers alone would have left four unlabelled fixture ratios in
three files for someone to re-quote.

scripts/measure-ltx2-prompt-adaln.py is committed so the number is re-runnable
rather than transcribed.

F2 — a false claim about a checkpoint, the same class this row just fixed

ltx2.h:47-49, a line surviving inside the paragraph #654 rewrote, said "LTX-2.5's
checkpoint does not carry the parameter" about keyframes_abs_pos_embedding.
Verified independently against both files' headers and upstream's own loader:

	FP8 (vonkaiser)	NVFP4 (first-party)
carries the tensor	YES — F8_E4M3 [1, 4096] + F32 scale	no
declares the flag	no __metadata__ AT ALL	true
LTXModelConfigurator.from_metadata	RAISES KeyError: 'caption_channels'	builds it, [1, 4096]

Two corrections to the reasoning that came with the finding, both measured:

• The FP8 file does not "resolve the flag False at
  model_configurator.py:82". Upstream never reaches line 82 on it —
  _build_caption_projections indexes caption_channels on the empty config
  first and raises. That file ships no config at all, so what its flag resolves
  to is decided entirely out of band, and the tensor it carries is trained.
• On the NVFP4 file the flag IS on and the module IS built, but the tensor is
  absent — 0 of its 7876 entries match keyframes_abs_pos. What that leaves is
  an UNMATERIALISED META PARAMETER, not a silent zero.

Corrected 2026-08-13 (review finding F-1, the blocking one). This bullet
said the parameter "keeps torch.zeros(1, inner_dim) (model.py:217-219)
through load_state_dict(..., strict=False)
(loader/single_gpu_model_builder.py:98) — a genuine no-op there". It is not
a no-op. It quoted that line while dropping the assign=True that is ON THE
SAME LINE, and upstream builds on the meta device — loader/helpers.py:84-95,
create_meta_model: with torch.device("meta"): configurator.from_metadata(...)
at :90-91. A key absent from the state dict is never materialised at all. The
row exists to delete a claim asserted with anchors and never checked, and it
replaced it with a claim whose anchors were read but not executed — in
include/, the product tree.

Run here through upstream's own create_meta_model on the shipped file's real
__metadata__ (read with upstream's own read_model_metadata /
SafetensorsModelStateDictLoader, which JSON-decodes each value,
sft_loader.py:58-74 — the flag lives at config.transformer, not at the top
level, which is why a raw __metadata__ read returns None for it):

config.transformer['use_keyframes_abs_pos_embedding'] = True
keyframes_abs_pos_embedding: shape=(1, 4096) dtype=torch.float32 device=meta is_meta=True
supports_keyframes_abs_pos_embedding (BEFORE load) : False
after load_state_dict(sd, strict=False, assign=True):
  neighbour patchify_proj.weight : device=cpu is_meta=False   <- materialised
  keyframes_abs_pos_embedding    : device=meta is_meta=True
  in missing_keys                : True
  reading the value RAISES       : RuntimeError: Tensor.item() cannot be called on meta tensors
supports_keyframes_abs_pos_embedding (AFTER load)  : False

Upstream says so itself, and then never asks.
supports_keyframes_abs_pos_embedding (model.py:166-173) returns False for
"a model whose config set the flag but whose checkpoint carried no weight for it
(the parameter would still be on meta)" (:170), and
enable_keyframes_abs_pos_embedding (model.py:175-200) exists because such a
parameter "would fail at the first forward" (:182). Both are defined and
never called — one grep -rn hit each across the whole Lightricks/LTX-2
checkout at fd4ded7f, the definition itself, re-confirmed here with a positive
control rather than transcribed.

Polarity is not what fails. apply_keyframes_absolute_embedding is
hidden_states + mask * embedding (transformer_args.py:23-43, the sum at
:43), so real zeros would be inert. The mechanism claim fails on meta,
not on additivity.

This STRENGTHENS the conclusion and changes nothing downstream. The refusal
stays keyed on tensor presence for the FP8 file, and the NVFP4 file is refused by
FLAG in ParseLtx2DitParams (ltx2.cpp:192-198) — where upstream, had it
loaded, would carry a parameter its own guard reports as unsupported.

Confirmed too that it is not keyframe-only: transformer_args.py:269 applies it
on every prepare whose keyframes_mask is set, and tools.py:186-196 sets
that mask unconditionally on the first latent frame.

Refusal keying: UNCHANGED, deliberately. RefuseUnported fires on the
TENSORS the file carries. Keying it on the resolved flag would, on the FP8 DiT,
read a DEFAULT rather than the file — that file declares nothing — and load it
while silently discarding a trained [1, 4096] parameter. Tensor presence is the
only signal that file actually carries. No behaviour changed, so no new gate is
owed; three refusal MESSAGES changed, because they asserted an implication that
is false in both directions.

F3 — records the lifecycle change did not move

• .agents/model-matrix.md still listed "timestep-INDEPENDENT prompt K/V
  (cacheable once per request)" — precisely what the row disproved.
• docs/STATUS.md did not mention the prompt-side AdaLN. Added inside the
  SHRINK-ONLY ratchet: the cell went 218 → 217 chars and
  check-public-doc-tables.py stays green at oversized_cells: 44.
• docs/FEATURES.md and docs/USAGE.md described the keyframes opt-in as if one
  file were involved; both DiTs need it, for different reasons.

One finding detail did not hold. It cited .agents/model-matrix.md:98 as
already saying the two DiTs "differ in a TRAINED keyframes_abs_pos_embedding".
grep -n keyframes .agents/model-matrix.md returns nothing on this branch. The
corroborating anchors are .agents/specs/ltx-2-5.md §3.1 and
tests/vllm/multimodal/test_ltx2_video.cpp:913-914.

The two LOW notes, recorded honestly

• test_ltx2_video's shipped-checkpoint case is env-gated on
  LTX2_CHECKPOINT_ROOT and SKIPS by default, so "unchanged 30/502" meant the
  whole real-header case did not run. With the variable set the same binary
  measures 30 / 8734 — verified here, exit 0 both ways. Recorded in the spec's
  gate table and at the skip site, so the next quote carries its configuration.
  Now also filed as #673:
  LTX2_CHECKPOINT_ROOT is set by no workflow — grep -rn CHECKPOINT_ROOT .github/ exits 1 with zero hits while the same pattern matches in tests/ and
  .agents/ (positive control in the same command) — so CI executes 502 of 8734
  assertions, 5.7%, at an unchanged case count of 30, and
  scripts/measure-ltx2-prompt-adaln.py is a manual tool no gate invokes. This
  row's checkpoint-derived evidence is therefore manual and host-local.
  Recorded as visible debt; wiring checkpoints into CI is explicitly not in scope
  here.
• Upstream loads with strict=False, assign=True
  (single_gpu_model_builder.py:98 — quoted in full, because dropping the
  assign=True is exactly what made the keyframes claim above wrong), so a
  config declaring the prompt-AdaLN flag false over a file that carries the
  module would silently run flag-OFF upstream where we now refuse. Ours is
  better; it is a documented divergence, not a mirror, and is named as one
  alongside the tensor-keyed keyframes refusal.

F4 — the branch was behind, and inherited a red it did not cause

check-device-leakage FAILED on the head: kcuda=2 > baseline 0, both hits in
src/vllm/multimodal/ltx2_video.cpp:532,549 — a file this diff does not touch,
present at the parent 968461cda and already fixed on main by 11cc1d589.
Merging origin/main is the whole repair; no edit of mine was needed and none was
made. Before: FAIL, kcuda=2. After: OK, kcuda=0, DSR 32 == baseline 32.

The merge was not a plain auto-merge and the resolution is recorded in its own
commit message. This branch's base row row/LTX25-PROMPT-ADALN was SQUASHED onto
main as 65e79eee5, so the merge base predates the squash and git reported
add/add conflicts on files where both sides carry identical content. Resolved
deterministically: the tree was set to origin/main wholesale
(git read-tree -u --reset origin/main), then this branch's single commit
968461cda..2990ed81b was reapplied with git apply --3way. Verified, not
assumed — git diff origin/main on the resolved tree is byte-identical to
git diff 968461cda 2990ed81b except two hunk-header line offsets where main's
own later edits shifted the file. The four paths BOTH sides changed
(model-matrix.md, FEATURES.md, STATUS.md, test_ltx2_video.cpp) were each
inspected directly: main's content intact, this branch's edit present exactly
once, no duplicated relocation.

windows-msvc-cpu / windows-msvc-vulkan are red on every open PR in the repo
from a separate cause, tracked as #664 and being fixed on
row/FIX-WINDOWS-POSIX-VIDEO-ENGINE. Not chased here, and
src/vllm/multimodal/video_engine.cpp is untouched.

Gate

Nothing runtime changed. ltx2.h and test_ltx2.cpp move comment text only;
the one script edit (gen-ltx2-goldens.py) alters only the COMMENT the generator
emits; ltx2_goldens.inc moves two comment lines with every value byte-identical.
No src/ file is touched at all — so identical suite counts are the expected
result and the point of measuring them.

BUILD_EXIT=0 on a clean Release configure of the merged head; build log grepped
for No space left|BFD assertion — 0 hits; warning:|error: — 0 hits.
ctest -N = 423.

Suite counts, unchanged from the row. All four re-measured on this head,
exit 0 each:

Suite	this branch
test_ltx2	35 cases / 2435 assertions
test_ltx2_loader	26 / 4826
test_ltx2_device	15 / 523
test_ltx2_video	30 / 502 skipped-default; 30 / 8734 with LTX2_CHECKPOINT_ROOT

tests/vllm/models/ltx2_goldens.inc was regenerated from
scripts/gen-ltx2-goldens.py against ltx_core fd4ded7f (REGEN_EXIT=0):
every golden VALUE byte-identical, the diff is the two stream labels alone — which
re-proves provenance as well as the wording.

Full ctest -j4 on the merged head: 422/423, CTEST_EXIT=8, 2 skipped as on
the baseline (test_modelopt_mixed_precision_checkpoint, test_voxtral_e2e). The
single failure is test_async_llm, which is on this repo's documented
starve-under--j list; re-run serially it is 1/1 PASS, exit 0.

Two environment failures, recorded rather than reported as verdicts.

• The first LTX2_CHECKPOINT_ROOT run exited 1 with a zero-byte log — no
  doctest summary at all — under a load average above 190. An empty log is a
  killed process, not a failing test. Re-run: 30 / 8734, Status: SUCCESS, exit 0.
• test_cpu_x86_llamacpp_floor fails with NO_QUIET_WINDOW (exit 4, busy=102%,
  load 53–204). It is the documented behaviour of that harness on a box that is
  never quiet — around ten agents were building throughout. Both files it
  exercises are byte-identical to origin/main (git diff origin/main -- scripts/cpu-x86-llamacpp-floor.sh tests/scripts/test_cpu_x86_llamacpp_floor.py
  is empty), so running it here is running main's version: it cannot be this
  diff. Reported as pending an idle box, not waived and not fixed.

An earlier full run was VOIDED rather than reported: another session's
disk-pressure cleanup deleted build/ while ctest was at 421/423, and the last
two tests recorded Not Run — Failed to change working directory. A run whose
tree vanished under it is not a result; it was rebuilt and re-run from scratch.

Spec: .agents/specs/ltx25-prompt-adaln.md. .agents/specs/ltx-2-5.md is
operator-owned and untouched.

🤖 Generated with Claude Code