feat(ltx-2.5): image conditioning at crf=0, the VAE encoder load path, and the keyframe refusal repair (#644)

[localai-bot]

Reconstruction of row LTX25-IMAGE-COND onto main. Issue #644. Spec:
.agents/specs/ltx25-image-conditioning.md.

Carries the whole row — the feature reviewed as #657 and the review
repair reviewed as #666. Neither ever reached main, so both close as
superseded by this.

Why a new branch, and the lesson worth keeping

#666's baseRefName was row/LTX25-IMAGE-COND, not main. Merging it
squashed it onto #657's head — and that head, a7154bd1e, was itself a
merge: origin/main. Squashing on top of a merge flattens the merge away.

Git then no longer knew the row had ever seen main. Measured:

git merge-base 247eba52b origin/main	b81a5e413 — 67 commits back
the row's apparent diff	252 files, 42,426 insertions
git merge origin/main	19 conflicts, incl. add/add on files purely main's

Those add/add files — gpt2.*, talker.*, w2vbert.*, test_talker.cpp,
test_w2vbert.cpp, .agents/specs/indextts-2-5.md,
.agents/specs/minimax-music3.md — are how main's newest work gets silently
reverted by a well-meaning conflict resolution. The merge was abandoned rather
than resolved.

Never squash-merge into a branch that has itself merged main. The squash
commit inherits authorship of everything main did since, and nothing reports
it at the time. Verify baseRefName before merging — "X is an ancestor of Y"
does not tell you what Y's base branch is.

How it was rebuilt

Branched from an immutable SHA, never the ref. origin/main is shared with
the other worktrees in this checkout and moved four times during this work.
That is not cosmetic: at one point it made main's own new files (the
dit_front/dit_stack cluster) read as content this row had deleted, and the
"repair" that invited produced a CMakeLists.txt listing TUs the tree did not
contain. Caught before building; the attempt was aborted, not patched.

The row's real delta is git diff 32d82c64d 247eba52b — 32d82c64d being the
main the row was last gated against, 247eba52b the squash, whose tree is
byte-identical (d276e5194) to the previously gated 56c2309ca. That is 19
files, all owned by this row, applied three-way and rebased forward twice.

Correction to the reconstruction recipe: git diff a7154bd1e 247eba52b is
not the repair. It spans 246 files / 38,314 insertions, 11 of them
main's, because a7154bd1e carries main only to b81a5e413 while
247eba52b carries it to 32d82c64d. Using it reintroduces the exact problem
being fixed. The repair-only diff is git show eb58fd58f — 8 files, +266/-57.

docs/FEATURES.md conflicted twice; both times resolved as a keyed record —
main's file taken wholesale, this row's key reapplied, never the automatic
three-way result. .agents/roadmap_v1.md applied cleanly and was verified the
same way. main's known duplicate Safetensors direct load key (#769) is
carried through untouched at its existing multiplicity of 2 — neither fixed here
nor multiplied.

Verification by file list

This is the check that catches a bad reconstruction, and it passes:

• git diff 043e56862 --name-only → exactly 19 files, all LTX-2.5
• zero occurrences of gpt2.*, talker.*, w2vbert.*, music3_oracle.py,
  bigvgan, website/
• both keyed records differ from main by exactly one line each
• both CMake files purely additive — zero removed lines
• registration delta exactly +1: 446 vllm_cpp_add_test vs main's 445,
  for test_ltx2_image_cond
• git merge-base HEAD 043e56862 = 043e56862 — the base is healthy again

What the row actually does

Unchanged from the reviewed work; see the commit body and the spec.

• Feature (feat(ltx-2.5): image conditioning at crf=0, and the VAE encoder load path that did not exist (#644) #657): the video VAE encoder load path, which existed nowhere
  in the tree (Ltx2VideoVaeEncoderKeyRules), plus image conditioning served at
  image_crf=0 — PPM → aspect-fill resize → VAE encode → place at latent frame
  0 → noise, gated against upstream executed at reduced dimensions.
• Repair (fix(ltx-2.5): the keyframe refusal named a FALSE reason, and a test pinned it (#644) #666): the last-frame keyframe refusal named a reason that is
  false at pin fd4ded7f (keyframes_abs_pos_embedding), and a test had
  been written to assert that wrong reason by name. Both corrected; the
  refusal now names the token-append machinery. Plus a gate for the per-phase
  conditioning claim that a mutation had been surviving, nine corrected
  file:line anchors, and a res_x/num_layers strictness fix mirroring
  upstream's subscript. Full RED/GREEN evidence in fix(ltx-2.5): the keyframe refusal named a FALSE reason, and a test pinned it (#644) #666.

Gate (CPU-only, Release, VLLM_CPP_CUDA=OFF)

BUILD_EXIT=0, 0 hits for "No space left" / "BFD assertion"
ctest -N              461   (main's 460 + test_ltx2_image_cond)
test_ltx2_video        33 cases /  576 assertions, exit 0
test_ltx2_image_cond   15 cases /  223 assertions, exit 0
test_ltx2_vae          36 / 3039     test_ltx2          35 / 2435
test_ltx2_loader       26 / 4826     test_ltx2_pipeline 37 / 2382
test_ltx2_device       15 /  523
agent-preflight.sh --staged           All gates green.

test_ltx2_video reads 33/576 where the pre-reconstruction record says
32/565. That drift is main's, not this row's: fc903b8dd (#674) added
TEST_CASE("ltx2 VAE weights load from an ODD safetensors payload offset (#674)")
to the same file, worth +1 case and +11 assertions. main went 30 → 31 cases
over the window while this row's contribution stayed +2 (one rename, two
additions), which is what the diff shows.

LTX2_CHECKPOINT_ROOT is unset on this box, so test_ltx2_video's
shipped-checkpoint subcase SKIPPED and is not in those counts.

The full ctest at this head is VOID — not passing, not failing

The shared disk hit 100% mid-run with two other sessions compiling. The run
aborted at 265/461, and test_tool_choice_grammar "failed" by reading back an
empty /tmp/vllm_toolchoice_gbnf_0.json it had itself just written, with the
ctest log truncated mid-sentence. An ENOSPC run reports on a filesystem, not on a
diff, so it is recorded as void rather than interpreted as a result. The build
preceding it completed cleanly with zero ENOSPC hits, and the seven suites
above ran after it and passed.

The last valid full run was at eae25c745 — identical 19-file row content, a
base four commits older — at 459/461, the two being test_engine_core_proc
(the documented ctest -j starvation; passes serially) and test_op_parity
(#737, since fixed on main by 043e56862, which this branch now sits on).
A local re-run is owed once the box has headroom; this PR's CI covers it on a
clean runner.

Reds inherited, not caused

windows-msvc-vulkan is #757 (C4456 shadowing in
tests/vt/test_backend_cross_device.cpp, fix in flight as #779) and
windows-msvc-cpu fails later and differently in test_openai_api_server.exe —
a fourth, distinct issue. Neither is this lane. sanitize-cpu should now be
green: this branch sits past #674 (fc903b8dd).

Closes the work tracked by #657 and #666.

🤖 Generated with Claude Code