feat(ltx-2.5): port the prompt-side AdaLN, and stop the opt-in from clearing it

[localai-bot]

Closes part of #644 (row 0).

The defect

use_prompt_adaln_single defaults TRUE in both references — diffusers
transformer_ltx2.py:1185, LTX-2 model.py:77 and model_configurator.py:76/:138
(config.get("use_prompt_adaln_single", True)) — and the shipped LTX-2.5 DiT carries
the module's tensors. ltx2_loader.cpp cleared the flag unconditionally in three
places, so every render kept only the static prompt_scale_shift_table and dropped
the timestep-conditioned half of the prompt K/V modulation.

It was invisible: shapes unchanged, values finite, and every committed golden was
generated with the flag OFF (gen-ltx2-goldens.py:149), so the gate agreed with the
defect. Reaching it required allow_unported_modules=1, which a real render needs
for keyframes_abs_pos_embedding — so the only way to load a real DiT was also the
way to silently disable a correctness setting.

Measured magnitude, flag ON vs OFF over the same shared weights

CORRECTED 2026-08-13 (#663). These four rows are GATE-FLOOR numbers from
SYNTHETIC weights and NONE of them answers "does this matter". The static table
AND the prompt-AdaLN MLP are both drawn from param_spec's scale=0.05
(gen-ltx2-goldens.py:100-106), so every ratio below is a property of the
FIXTURE and moves with the init scale (0.005 → 4.1%, 0.2 → 1450%). They are
reported because the mutation has to be shown to move something.

Quantity (SYNTHETIC fixture, gate floor)	Delta
timestep term vs the static table it is added to	max|term| 0.0252 vs max|table| 0.0487 — 51.7%
block-0 modulated prompt K/V	0.0310 — 5.82% of max|off|
DiT video output (2 blocks)	1.4567e-4 — 73x the gate's 2e-6 f32 floor
DiT audio output	7.367e-5 — 37x the floor

On the SHIPPED checkpoint the term DOMINATES the table it is added to, measured
through upstream's own AdaLayerNormSingle on the real weights: rms|term| /
rms|table| = 1347% video, 1583% audio; max|term| / max|table| =
7119% / 2817%. Compared like for like against the 51.7% above, this fixture
UNDERSTATED the defect by 138x (video) and 54x (audio). Reproduce with
scripts/measure-ltx2-prompt-adaln.py; details in
.agents/specs/ltx25-prompt-adaln.md §Outcome.

What was ported, and from where

Piece	Upstream
the module	model.py:222-227 (video), :252-257 (audio); AdaLayerNormSingle(dim, embedding_coefficient=2), adaln.py:19-45
the producer	transformer_args.py:274-277, driven by modality.sigma [batch] and not the per-token timesteps; scaled by timestep_scale_multiplier at :173-186
the consumer	transformer.py:441-446, summed into the table before (1 + scale) applies; threaded per stream at :288-296 / :317-325
diffusers twin	transformer_ltx2.py:1536-1547, :1648-1649, :677-693

Both arms: Ltx2DitForward (f32 host) and Ltx2DitForwardDevice (f32 and the bf16
production stream). Pins: LTX-2 fd4ded7f, diffusers 3a2f35d4.

What replaced the cleared flag

The three = false assignments become an invariant: the resolved flag must equal
whether the FILE carries prompt_adaln_single, refused by name otherwise. And
Ltx2AdoptDeclaredDitParams now clears exactly ONE flag in its config copy —
use_keyframes_abs_pos_embedding, whose module really is unported — so
allow_unported_modules can no longer switch a ported feature off. A config that
disagrees with the shapes about the flag is now refused rather than forced into
agreement on both sides.

Both shipped DiTs were re-read off the NAS to confirm this refuses neither: the FP8
file carries no __metadata__ at all, the NVFP4 file's config OMITS the key, so
upstream's TRUE default decides on both and matches their tensors.

Evidence

Goldens executed from upstream ltx_core at reduced dims (gen-ltx2-goldens.py
section 6). Every pre-existing golden VALUE is byte-identical; only case-header
comments changed.

Five mutations, each RED, each restored byte-for-byte (source md5s re-checked):

Mutation	Result
host ModulateContext ignores the prompt term	3/35 cases, 6/2435 assertions, exit 1
device path always takes the static-only branch	1/15 cases, 6/523 assertions, exit 1
re-add use_prompt_adaln_single = false in the loader	guard throws by name; assertion count DROPS 4826 → 4815, exit 1
MLP driven by timesteps instead of sigma	2/35 cases, 4/2435, exit 1
shift and scale rows swapped	2/35 cases, 4/2435, exit 1

A permanent in-tree case asserts the flag-ON forward misses the flag-OFF golden,
so a module that is bound but never added cannot pass.

Gate

BUILD_EXIT=0 throughout; build logs grepped for No space left|BFD assertion (0).
ctest -N = 423; full ctest -j8 423/423 pass, exit 0 after merging
origin/main (b81a5e413) and rebuilding.

Suite counts vs the cefacd2d0 baseline, measured by reverting the tree to HEAD,
rebuilding and running, then re-applying the diff and re-verifying its md5:

Suite	HEAD	this row
test_ltx2	30 / 1627	35 / 2435
test_ltx2_loader	24 / 4817	26 / 4826
test_ltx2_device	13 / 498	15 / 523
test_ltx2_video	30 / 502	30 / 502 (SKIPPED default; 30 / 8734 with LTX2_CHECKPOINT_ROOT set)

Spec: .agents/specs/ltx25-prompt-adaln.md, committed at baa92ccf7 before any
implementation.

🤖 Generated with Claude Code