fix(main-red): the LTX-2.5 VAE loader read the safetensors mmap through a uint16_t* it is not allowed to form (#674)

[localai-bot]

Closes #674.

main has been RED on sanitize-cpu (address,undefined) since cefacd2d0
(#641, the LTX-2.5 landing). This closes it. The other half of that same red,
the device-leakage DSR ratchet (#553), needed no change and is dealt with
below.

What was wrong

Ltx2LoadVaeWeights read the safetensors mmap through a pointer it is not
allowed to form:

const uint16_t* src = reinterpret_cast<const uint16_t*>(t.data);
for (int64_t i = 0; i < numel; ++i) values[i] = Bf16ToF32(src[i]);

StTensor::data points into the read-only mapping at
8 + <JSON header length> + <sum of the preceding tensors' sizes>
(safetensors_reader.h:16-23). Not one of those three terms is required to be
even, so a BF16 tensor beginning on an odd byte is an ordinary safetensors
file and not a corrupt one. Forming and dereferencing a const uint16_t* there
is undefined behaviour on every target, and a genuine fault on the
strict-alignment ones this project builds and ships for: build-test-cpu-arm64,
Jetson/Orin (sm_110), Thor.

The fix

vt::LoadUnaligned<uint16_t> (include/vt/unaligned.h) — a std::memcpy with
no alignment precondition, which compiles to the same single load where the
address does happen to be aligned. Not a cast, not a pragma, not a suppression,
and not a change to any gate.

That seam exists because of this bug class: #301 created it the first time
this red-ed main. This is the third recurrence — #301 (closed:
cpu_ops.cpp:33, laguna.cpp:1028), #627 (open: qwen3_5_weights.cpp:332),
and now the VAE loader — and minimax_h3_vae_loader.cpp:87-101 already carried
both the repair and the reason in prose while a new loader reached main with
the cast anyway. Nothing greps for the pattern; that observation is recorded on
#674 and #627 rather than acted on here.

The coverage that caught it was accidental — that is fixed too

test_ltx2_video only reached the defect because ltx2_fixture's JSON header
happens to make one VAE tensor's offset odd today. A rename or a reshape in
that fixture silently retires the coverage and leaves every assertion green.

So this adds a case that forces the odd offset — it writes the file itself
and pads the counted JSON header by one space, keeping whichever of the two
parities is odd — and then asserts the parity it depends on before loading:

REQUIRE((reinterpret_cast<uintptr_t>(file.Get(name).data) % 2) == 1);

An edit that makes the address even now fails that REQUIRE instead of passing
while covering nothing. The values are chosen bf16-exact so the value check is
equality rather than a band, which makes a wrong-by-one-byte read a hard
failure. The case deliberately does not use Workspace: writing the whole
LTX-2.5 fixture would make it depend on the very fixture whose accidental
coverage it replaces.

Evidence

RED then GREEN, same binary, same command. setarch -R because sanitizer builds
SIGSEGV instantly on this host without it (ASLR entropy vs the kernel), which
reads exactly like a crash in the code under test.

cmake -S . -B build-sanitize -DVLLM_CPP_BUILD_TESTS=ON -DVLLM_CPP_CUDA=OFF \
      -DVLLM_CPP_SANITIZE='address,undefined'
UBSAN_OPTIONS=print_stacktrace=1 \
ASAN_OPTIONS=detect_leaks=1:strict_string_checks=1 VT_POOL_BYPASS=1 \
setarch -R ctest --test-dir build-sanitize -R '^test_ltx2_video$' --output-on-failure

step	result
RED, whole target, unmodified 7965f12bf	***Failed — ltx2_loader.cpp:1325:91: runtime error: load of misaligned address 0x7fffc81cc129 for type 'const uint16_t', stack #0 Ltx2LoadVaeWeights #1 Ltx2VideoEngine::Load ltx2_video.cpp:777 #8 test_ltx2_video.cpp:218
RED, the NEW case alone, unmodified src	same finding at 0x7ffff7fb005b (odd), stack #1 DOCTEST_ANON_FUNC_153 test_ltx2_video.cpp:1189 — so the forced-offset case reproduces it on its own
GREEN, the NEW case alone	1 passed | 0 failed, assertions: 11 | 11 passed, Status: SUCCESS!
GREEN, whole target, rebased head	1/1 Test #30: test_ltx2_video ... Passed 157.35 sec

Also green on the rebased head: scripts/check-device-leakage.py --report,
tests/scripts/test_device_leakage.py (26/26),
scripts/check-doc-checkpoint.py, scripts/check-public-doc-tables.py,
and scripts/agent-preflight.sh including its committed-range and
commit-trailer gates.

Baseline to subtract

• test_cpu_x86_llamacpp_floor — test_cpu_x86_llamacpp_floor: the contended-leg case is load-dependent — at loadavg 63 the harness exits NO_QUIET_WINDOW (4) instead of GIVING_UP (2), so the guarantee goes untested and reads as a failure of whatever diff is in flight #618 exactly: it asserts a wall-clock
  ratio and exits NO_QUIET_WINDOW (4) instead of GIVING_UP (2) under load.
  It failed at loadavg 216 and passed on the same tree at loadavg 56, which
  is the issue's own description of itself. It reads none of the four files in
  this diff.
• python3 -m pytest tests/scripts/ --ignore=tests/scripts/test_cpu_kernel_bench.py
  reports 10 failures (test_check_windows_portability,
  test_gen_vulkan_spirv, test_mlx_system_headers, test_now_render). All
  ten reproduce identically on a pristine extraction of the base SHA
  7965f12bf with no diff applied, so they are pre-existing on main.
• windows-msvc-cpu / windows-msvc-vulkan are PR-only with no main
  baseline (test_openai_api_server crashes on Windows with STATUS_STACK_BUFFER_OVERRUN (0xC0000409), unmasked by the #512 fix #584), plus video_engine.cpp reaches Windows with unguarded POSIX stat — reddens windows-msvc-* on EVERY open PR #664.

The other half of the cefacd2d0 red: no change needed

device-leakage was already repaired by 11cc1d589, which routed LTX-2.5's
device question through CurrentPlatform().device_type() rather than taking the
ALLOWLIST escape. Verified rather than assumed — both CI steps run verbatim:
kcuda=0, DSR 32 == baseline 32, test_device_leakage.py 26/26, with
scripts/device-leakage-baseline.json untouched since 99b7443bd
(accelerator-seam S7), so it is a repair and not a raised threshold. #553 is
closed with that evidence. Its still-open successors #659 and #660 are separate
defects and are untouched here.

Scope, and what is left owed

Only the site that is red is touched. 19 sibling sites in 11 other loaders
form the same typed pointer over StTensor::data; the full grep is posted as an
inventory on #627, which owns the class. The widest is
qwen3_dspark_weights.cpp:99, a const int64_t* needing 8-byte alignment — UB
on 7 of every 8 offsets rather than 1 of 2. The sweep is value-identical by
construction but #627 requires 27B/35B/Coder golden-md5 inertness evidence for
the shared loader, and this repair has no GPU to produce it, so it is recorded
as owed rather than done blind.

docs/FEATURES.md records the resulting guarantee on the row it belongs to —
"Safetensors direct load" — rather than in the LTX-2.5 row, which is already at
its entry budget.

🤖 Generated with Claude Code

[localai-bot]

Verified the alignment claim on Thor itself (aarch64, sm_110, NVIDIA Thor compute_cap 11.0, g++ 13.3, Ubuntu 24.04) rather than reasoning about it from x86. Result confirms the fix but narrows one claim in the PR body, so recording both halves.

I built a standalone reproduction of the exact shape — a bf16 payload placed at a deliberately odd offset inside a byte buffer, read once through reinterpret_cast<const uint16_t*> and once through the memcpy seam — and ran three arms on Thor.

The UB is real and reproduces on Thor:

align_repro.cpp:64:20: runtime error: load of misaligned address 0xaaab18e4b2b1
  for type 'const uint16_t', which requires 2 byte alignment
0xaaab18e4b2b1: note: pointer points here
 00 00 00  00 80 3f 00 40 40 40 80  40 80 bf 00 c0 00 3f 00 ...
              ^
    #0 ... in main align_repro.cpp:64

Same diagnostic class as the CI failure. The fix arm is clean under the identical sanitizer flags, and both arms produce byte-identical values (1, 2, 3, 4, -1, -2, 0.5, 0), so the memcpy seam is value-preserving here as expected.

What did NOT reproduce — and this is the correction. The PR body says the cast is "a genuine fault on the strict-alignment ones this project builds and ships for: build-test-cpu-arm64, Jetson/Orin (sm_110), Thor." On Thor it does not fault:

arm	-O2	UBSan	-O2 -mstrict-align
DEFECT	exit 0, correct values	misaligned-address error	exit 0
FIX	exit 0, correct values	clean	exit 0

ARMv8 permits unaligned LDRH at EL0 — Linux leaves SCTLR_EL1.A off — so the compiler emits a plain halfword load that the hardware tolerates, and even -mstrict-align did not trap it in this shape.

So the accurate statement is: undefined behaviour that the sanitizer catches and that reds a required gate, not a crash waiting to happen on our aarch64 targets. That is still a fix worth landing exactly as written — UB is UB, the sanitize-cpu job is red because of it, the seam already exists for this bug class, and a future compiler is entitled to assume the alignment and miscompile around it. But the justification should rest on that rather than on a fault nobody can demonstrate, because an overclaim here is the kind of thing that gets quoted back later.

Two things in this PR I'd highlight as the strongest parts, unchanged by the above:

• Finding that the existing coverage was accidental — test_ltx2_video only reached the defect because the fixture's JSON header happens to make one offset odd today — and replacing it with a case that forces the odd offset and then REQUIREs the parity it depends on. That converts a coincidence into a guarantee, and a fixture edit can no longer silently retire the coverage.
• Recording that this is the third recurrence of the class (main is RED on sanitize-cpu (address,undefined): 5 UBSan misaligned bf16 loads from the borrowed-mmap load path #301, UBSan: TransposeBf16 reinterpret_casts unaligned safetensors bytes to const uint16_t* — latent UB on the 35B MoE loader path #627, now main is RED on sanitize-cpu: Ltx2LoadVaeWeights reinterpret_casts unaligned safetensors bytes to const uint16_t* (third recurrence of the class) #674) while minimax_h3_vae_loader.cpp:87-101 already carried both the repair and the reason in prose. Nothing greps for the pattern; that is the real finding and it outlives this PR.

Repro and runner are throwaway; nothing was installed on the Thor host and no build tooling was added.