LTX-2.5 token-APPEND: the phase loop is fixed-width, and it is what blocks BOTH the reference arms and the last-frame keyframe

[localai-bot]

Found while porting ICLoraPipeline (row LTX25-IC-LORA, #923). Filed rather than fixed there because it is a shared prerequisite with a second arm and needs its own spec.

What is blocked

Two conditioning arms, both refused today, and both for this same reason:

• reference-image / reference-video — src/vllm/multimodal/ltx2_video.cpp, the ref_image_paths / ref_video_dir refusal. LTX-2.5 IC-LoRA: port ICLoraPipeline — read the adapter's metadata, fuse the LoRA, and lift the reference-video refusal #923 closed the reason that refusal used to give (the IC-LoRA scale factors were unreadable; --lora now reads them) and rewrote it to name this one.
• last-frame keyframe — the refusal immediately above it, which has named this cause accurately since it was written.

The mechanism

Upstream's appending conditioning items concatenate onto latent, denoise_mask, positions and clean_latent:

• VideoConditionByReferenceLatent.apply_to — conditioning/types/reference_video_cond.py:97-100
• VideoConditionByKeyframeIndex.apply_to — conditioning/types/keyframe_cond.py:79-82

and clear_conditioning (ltx_core/tools.py:88-105) trims the appended tokens back off before unpatchify.

What is and is NOT in the way

Re-derived at 4d81ad2, because the cost is much smaller than the two refusals imply:

piece	state
the conditioning item	ported and gated — Ltx2ConditionVideoByReference, src/vllm/model_executor/models/ltx2_conditioning.cpp:221
the VAE encoder	ported and reached — Ltx2ConvVideoEncode
the DiT's token count	not in the way — Ltx2ModalityInput::tokens is a per-call field
the DiT's attention mask	not in the way — a self-attention strength mask is already accepted (ltx2.h, Ltx2ModalityInput::attention_mask; implemented in ltx2_dit.cpp, mirroring _prepare_self_attention_mask, transformer_args.py:208-237)
Ltx2LatentState having no attention-mask field	not in the way for the default arm — at conditioning_attention_strength == 1.0 with no mask, upstream computes attn_mask = None (iclora_utils.py:157-160) and update_attention_mask returns None (mask_utils.py:141-143)
the engine's phase loop	this is the gap

One Ltx2VideoTokenCount(vshape, 1) feeds the sigma schedule, the Ltx2ModalityInput handed to the DiT, and Ltx2VideoUnpatchify. It has to carry the GROWN state.tokens through denoise instead, and trim back to the target count before unpatchify.

Done when

• A reference video supplied through ref_video_dir, together with a --lora whose metadata declares the scale factors, renders rather than refusing.
• A last-frame keyframe renders.
• Both gated through a production entry point, with the trim proven by a mutation that removes it.
• The two refusals are deleted rather than reworded.

Owner: a follow-on row. Listed under ## Owed in ltx25-ic-lora.md.

[localai-bot]

Landed as c7cb59fbb (PR #964, row LTX25-TOKEN-APPEND). The Closes keyword did not fire because the reference was parenthetical in the title rather than a closing keyword in the body, so this is a manual close with the evidence recorded.

Verified on main rather than asserted:

:1772  const int64_t target_tokens = ...
:2008  VT_CHECK(video.tokens > target_tokens, ...)      <- the sequence GROWS
:2276  Ltx2ClearConditioning(&finished, target_tokens)  <- it TRIMS
:2279  VT_CHECK(video.tokens == target_tokens, ...)

The gate was 485/485 with all eleven commits passing check-doc-checkpoint individually and the positive control still failing, so the greens were real.

One arm was lifted — the last-frame keyframe — because its refusal named token-append as the sole cause and nothing else blocked it. The other three stayed refused with their messages untouched, which was the right call at the time and is now the thing to revisit: two fresh reviews have since found that both #929's and #938's refusals name causes this row made false. #938's reviewer went further and could not establish that the reference-video arm is blocked at all any more — upstream's default IC-LoRA path (iclora_utils.py:156-168) sets attn_mask = None at strength 1.0 and applies no wrapper, which I confirmed independently, so the attention-strength arm is not in the way either.

So the follow-up is not "update a message". It is: re-derive what actually blocks reference-video, and if the answer is nothing, serve it.

Two records still need attention, tracked here so they are not lost:

• .agents/issue-index.md on main already carries a #930 row, and PR feat(LTX25-IC-LORA): read the IC-LoRA adapter, fuse it into every arm, and stop blaming the metadata (#923) #938 appends a second one describing this blocker as open. The file is merge=union and append-only, so both will survive and neither can be corrected after landing. feat(LTX25-IC-LORA): read the IC-LoRA adapter, fuse it into every arm, and stop blaming the metadata (#923) #938 must correct its row before it merges.
• src/vllm/multimodal/ltx2_video.cpp:1379-1380 keeps a running tally of refusals whose stated reason turned out to be false or stale. It reads six. Merging either feat(LTX25-GENERATED-KEYFRAMES): the second feature called "keyframe", refused by what is missing (#920) #929 or feat(LTX25-IC-LORA): read the IC-LoRA adapter, fuse it into every arm, and stop blaming the metadata (#923) #938 unchanged would make seven, and for the second time with a test asserting the wrong reason by name.

FOLLOWING_AGENTS_PROTOCOL