fix(cuda): scope the drain batch to its engine and fence the indexed reads (Netflix/vmaf#1305)

[lusoris]

Summary

Closes T-UPSTREAM-1305-CUDA-DRAIN-BATCH-THREAD-GLOBAL-2026-09-03, which is two defects of the same shape.

Fork half. The ADR-0242 fence batch in core/src/cuda/drain_batch.c was static _Thread_local and keyed by nothing else, so two VmafContexts sharing an OS thread shared the batch. A context that closed left its CUevents and its bool * drained flags registered, and the next context's flush waited on destroyed events and wrote through freed pointers. The batch now carries the owning VmafCudaState: open() claims it and drops a previous owner's entries, flush() returns 0 without touching CUDA for a foreign owner and clears the entries it consumed, and thread_destroy() wipes entries, the open flag and the owner before the caller frees the engine state.

Upstream half (Netflix/vmaf#1305). vmaf_score_at_index() and vmaf_feature_score_at_index() read the feature collector with no CUDA sync, no drain flush and no thread-pool wait, so a caller draining index N-2 while N was in flight read unwritten slots. They now call a fence_for_read() helper — worker-thread wait, drain flush, pending collect for indices at or below the requested one — but only after the lock-free read reports the slot unwritten, so reads that hit written slots keep their cost and the streaming path keeps its throughput.

Verified on the RTX 4090: CUDA vs CPU on the Netflix src01 pair is unchanged (adm2/adm3/adm_scale0-3/aim/vif_scale0-3 identical, motion2 / motion3 / vmaf 1e-6, the documented GPU tolerance); the Netflix golden gate is 271 passed / 12 skipped / 0 failed; the new unit test pins the ownership rules and needs nvcc but no device.

Type

• fix — CUDA engine lifetime + public read-API correctness

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (pre-commit on every touched file; assertion-density.sh PASS).
• Unit tests: core/test/test_cuda_drain_batch.c (4 cases, fast suite, no device needed).
• Docs — no docs needed: no user-visible surface changes; the behaviour change is that a documented API stops returning stale data, and it is recorded in docs/state.md and the CUDA AGENTS.md invariant.
• SIMD/GPU, twins, new C sources, breaking change, ADR — CUDA engine only; no twin, no new public symbol (vmaf_cuda_drain_batch_pending() is in the private drain_batch.h), no ADR (ADR-0242 already governs the batch).

Bug-status hygiene (ADR-0165)

• docs/state.md — T-UPSTREAM-1305-CUDA-DRAIN-BATCH-THREAD-GLOBAL-2026-09-03 moved to Recently closed with both halves and the evidence.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: the state.md row already carries the analysis, and the fix follows the ownership rule ADR-0242 implies.
• Decision matrix — no alternatives: only-one-way fix. A thread-local batch shared by two engines is wrong under any design; the alternatives (a per-context batch allocation, or dropping the batch) either change ADR-0242's shape or lose its optimisation.
• AGENTS.md invariant note — core/src/cuda/AGENTS.md § Lifecycle invariants: the drain batch belongs to one engine at a time; never restore the owner-less open(void) signature.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/cuda-drain-batch-per-state-lifetime.md.
• Rebase note — docs/rebase-notes.md entry (core/src/libvmaf.c is upstream-mirror; the two hunks there are fork-only).

Reproducer

meson setup core/build core -Denable_cuda=true -Denable_sycl=false -Db_lto_threads=4 && ninja -C core/build
core/build/test/test_cuda_drain_batch                      # 4 tests run, 4 passed
Y=python/test/resource/yuv
core/build/tools/vmaf -r $Y/src01_hrc00_576x324.yuv -d $Y/src01_hrc01_576x324.yuv -w 576 -h 324 -p 420 -b 8 \
  --backend cuda --model version=vmaf_v0.6.1 --json -o cuda.json
core/build/tools/vmaf -r $Y/src01_hrc00_576x324.yuv -d $Y/src01_hrc01_576x324.yuv -w 576 -h 324 -p 420 -b 8 \
  --no_cuda --model version=vmaf_v0.6.1 --json -o cpu.json   # adm/vif identical, motion/vmaf within 1e-6
make VENV=/path/to/.venv test-netflix-golden               # 271 passed, 12 skipped

🤖 Generated with Claude Code