fix(dnn): wire the int8 redirect into --tiny-model and stop vmaf_tiny_v3.int8 double-scaling

[lusoris]

Summary

Completes the int8 half of epic #1242. vmaf_use_tiny_model() — the entry point behind --tiny-model — ignored the sidecar's quant_mode and always opened the fp32 graph; it now mirrors vmaf_dnn_session_open(), redirecting to <stem>.int8.onnx and falling back to fp32 per ADR-1032 with a debug log line. model/tiny/vmaf_tiny_v3.int8.json shipped without "onnx_has_scaler": true although the graph bakes the StandardScaler, so libvmaf.c double-scaled the canonical-6 vector: on the Netflix src01_hrc00/hrc01_576x324 pair (48 frames, CPU) pooled vmaf_tiny_model was 16.020865 and is now 71.952113 against an fp32 baseline of 72.359458, with per-frame PLCC vs fp32 going 0.975443 to 0.999876. A scaler/sidecar consistency gate over every model/tiny/*.int8.onnx now runs in three places so this cannot recur. On the Python side, measure_quant_drop.py gained --fp32 / --int8 / --budget / --id so an uncommitted model can be gated without a registry entry (verified PLCC=0.999880 drop=0.000120 on the shipped v3 pair), and qat_train.py now picks its training loader from the rank of qat.input_shape — rank-4 configs like learned_filter_v1_qat.yaml previously could not train at all, because every config went to the tabular datamodule and the missing-cache branch silently downgraded the run to --smoke. The three docs/ai/ placeholders (#1242's last docs task) are replaced with the audited state of the tree rather than restated plans. Verification: meson dnn suite 13/13 with -Denable_dnn=enabled + ONNX Runtime in the container, Netflix golden gate 271 passed / 12 skipped / 0 failed, 40 Python tests green. Two things are deliberately not here and are recorded rather than half-wired: the loader still does not verify int8_sha256 (documented in docs/ai/quantization.md and pinned in core/src/dnn/AGENTS.md — a digest mismatch is a third outcome ADR-1032 does not define, so it needs its own ADR), and the discovery that the two gpu-full CI jobs can never be scheduled is filed as T-GPU-RUNNER-LABEL-MISMATCH-2026-09-05 in docs/state.md rather than fixed here.

Follow-up fix on this branch: the redirect must not fail an invocation that worked

The first cut of the redirect only fell back to fp32 when the int8 file was
missing or failed the op allowlist. That is not the only way an int8 graph can
be unusable: model/tiny/nr_metric_v1.json declares quant_mode: "dynamic",
so --tiny-model model/tiny/nr_metric_v1.onnx now redirected to
nr_metric_v1.int8.onnx — which clears the size cap and the allowlist and then
fails ORT session creation with -EIO and Could not find an implementation for ConvInteger(10) on any ONNX Runtime build without that kernel.
core/test/dnn/test_cli.sh caught it: it fails with this branch's loader and
passes with master's. Both twins now retry the fp32 baseline once when
vmaf_ort_open() fails on a redirected path (vmaf_ort_open() leaves its
out-parameter untouched on error, so the retry cannot leak the failed session).
meson test -C build-cpu --suite dnn is 13/13 again.

Type

• fix — bug fix — int8 redirect missing from vmaf_use_tiny_model(), and a shipped sidecar that double-scaled its features.

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (pre-commit on every touched file; clang-tidy -p core/build core/src/dnn/dnn_attach_api.c reports only the two modernize-use-nullptr warnings master already carries — the function-size, redundant-branch-condition and dead-store findings the first draft introduced were refactored away).
• Unit tests: meson test -C /tmp/build-dnn --suite dnn 13/13 OK with -Denable_dnn=enabled; pytest ai/tests/test_measure_quant_drop_unit.py ai/tests/test_qat_train_loader.py 29 passed / 4 skipped; pytest python/test/model_registry_schema_test.py 11 passed / 1 xfailed; bash core/test/dnn/test_registry.sh and python ai/scripts/validate_model_registry.py both OK on 26 entries.
• Docs in the same PR: docs/ai/quantization.md, docs/ai/inference.md, docs/ai/extractor-template.md, docs/ai/sidecar-online-training.md, docs/usage/cli.md.
• SIMD/GPU, twins, new C sources, breaking change, ADR — no SIMD or GPU path touched (the DNN loader is backend-agnostic; execution-provider selection is unchanged). dnn_attach_api.c and dnn_api.c are twins and both are edited here: the redirect logic and the two-trigger fp32 fallback are identical in each, and core/src/dnn/AGENTS.md pins that they must stay so. No new C source files. No breaking change — the redirect only fires for sidecars declaring quant_mode != fp32, which no default model does. No ADR: ADR-1032's fallback semantics are applied to a failure mode it did not enumerate, not changed; the alternative (fail loudly on an unopenable int8 graph) would regress --tiny-model invocations that work on master today, so there is no second reasonable option to weigh.

Bug-status hygiene (ADR-0165)

• docs/state.md — closed T-DNN-ATTACH-INT8-REDIRECT-MISSING-2026-09-04 and T-TINY-V3-INT8-SIDECAR-MISSING-ONNX-HAS-SCALER-2026-09-04 (Recently closed, with the measured before/after scores); opened T-GPU-RUNNER-LABEL-MISMATCH-2026-09-05 (Open bugs).

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 digest for this work, docs/research/2029-int8-static-qat-readiness.md, already landed on master in PR docs(ai): int8 static PTQ / QAT readiness smoke for the 1.0.0 retrain #1293; this PR implements its findings (§5 gaps 1, 2, 4, 5) and adds no new research.
• Decision matrix — docs/ai/quantization.md §Mode selection (redirect vs. explicit-path alternatives), backed by docs/research/2029-int8-static-qat-readiness.md §2 and §6 already on master.
• AGENTS.md invariant note — core/src/dnn/AGENTS.md §"Invariant — int8 loader redirect and scaler declaration contract"
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/vmaf-tiny-v3-int8-scaler.md, changelog.d/fixed/dnn-attach-int8-redirect.md, changelog.d/added/measure-quant-drop-path-overrides.md, changelog.d/added/qat-train-4d-image-loader.md, changelog.d/changed/docs-ai-gaps-1242.md
• Rebase note — docs/rebase-notes.md entry

Reproducer

# 1. The scaler fix, end to end. Requires ONNX Runtime, so run in the container.
#    A copy of the sidecar with "onnx_has_scaler" removed reproduces the defect.
docker exec -u 0 -w /workspace/.claude/worktrees/int8loader vmaf-dev-mcp bash -lc '
  D=/tmp/v3proof; mkdir -p $D/before $D/after
  cp model/tiny/vmaf_tiny_v3.int8.onnx $D/before/; cp model/tiny/vmaf_tiny_v3.int8.onnx $D/after/
  /opt/vmaf-venv/bin/python -c "
import json
d=json.load(open(\"model/tiny/vmaf_tiny_v3.int8.json\"))
b=dict(d); b.pop(\"onnx_has_scaler\")
json.dump(b, open(\"/tmp/v3proof/before/vmaf_tiny_v3.int8.json\",\"w\"))
json.dump(d, open(\"/tmp/v3proof/after/vmaf_tiny_v3.int8.json\",\"w\"))"
  for v in before after; do
    /usr/local/bin/vmaf --backend cpu \
      -r python/test/resource/yuv/src01_hrc00_576x324.yuv \
      -d python/test/resource/yuv/src01_hrc01_576x324.yuv \
      -w 576 -h 324 -p 420 -b 8 -m path=model/vmaf_float_v0.6.1.json \
      --tiny-model $D/$v/vmaf_tiny_v3.int8.onnx --tiny-device cpu \
      -o $D/$v.json --json >/dev/null 2>&1
    echo -n "$v: "
    /opt/vmaf-venv/bin/python -c "
import json,sys; print(json.load(open(sys.argv[1]))[\"pooled_metrics\"][\"vmaf_tiny_model\"][\"mean\"])" $D/$v.json
  done'
# before: 16.020865
# after:  71.952113        (fp32 vmaf_tiny_v3.onnx baseline: 72.359458)

# 2. C loader + registry gate.
docker exec -u 0 -w /workspace/.claude/worktrees/int8loader vmaf-dev-mcp bash -lc '
  meson setup /tmp/build-dnn /workspace/.claude/worktrees/int8loader/core \
      -Denable_cuda=false -Denable_sycl=false -Denable_dnn=enabled -Denable_tools=true
  ninja -C /tmp/build-dnn && meson test -C /tmp/build-dnn --suite dnn'
# Ok: 13   Fail: 0   (includes test_vmaf_use_tiny_model and test_registry)

# 3. Registry consistency gate, host-side, no ONNX Runtime needed.
TINY_DIR=model/tiny bash core/test/dnn/test_registry.sh
python ai/scripts/validate_model_registry.py
python -m pytest python/test/model_registry_schema_test.py -q
# OK: 26 registry entries verified
# OK: 26 registry entries valid against registry.schema.json
# 11 passed, 1 xfailed

# 4. The two Python-script gaps.
python -m pytest ai/tests/test_measure_quant_drop_unit.py ai/tests/test_qat_train_loader.py -q
# 29 passed, 4 skipped   (2 further failures on a host without onnxruntime are pre-existing)
docker exec -u 0 -w /workspace/.claude/worktrees/int8loader vmaf-dev-mcp \
  /opt/vmaf-venv/bin/python ai/scripts/measure_quant_drop.py \
    --fp32 model/tiny/vmaf_tiny_v3.onnx --int8 model/tiny/vmaf_tiny_v3.int8.onnx --budget 0.002
# [PASS] vmaf_tiny_v3   mode=override PLCC=0.999880  drop=0.000120  budget=0.0020  worst_abs=2.2058

# 5. Netflix golden gate (CPU, -Denable_dnn=disabled — the CI configuration).
make test-netflix-golden
# 271 passed, 12 skipped

Known follow-ups

• The loader does not verify int8_sha256. Documented in docs/ai/quantization.md and pinned as an invariant in core/src/dnn/AGENTS.md; adding it needs an ADR because a digest mismatch is a third outcome ADR-1032's fp32-fallback semantics do not define, and it would have to land in both loader twins at once.
• T-GPU-RUNNER-LABEL-MISMATCH-2026-09-05 (docs/state.md, Open bugs): the Coverage GPU (advisory) and SYCL float_ssim Parity jobs target runs-on: [self-hosted, linux, gpu-full], but the only registered runner is labelled sycl-arc and GPU_COVERAGE_ENABLED is unset, so neither can be scheduled. No CI job covers tiny-AI cross-device parity at all. docs/ai/inference.md now records this instead of "planned: self-hosted runner"; the CI fix is a separate change.
• Research-2029 §5 gaps 3 and 6 are untouched by this PR: pinning quant_format=QuantFormat.QDQ in ptq_static.py / qat_train.py (tracked as T-AI-PTQ-STATIC-QUANT-FORMAT-UNPINNED-2026-09-03), and the end-to-end VMAF delta gate.

🤖 Generated with Claude Code

[lusoris]

Cleared three of the four failures; the fourth needs a test I'd rather flag than guess at.

Fixed and pushed:

1. Pre-Commit (f14afde..) — a keep-both rebase left duplicate state.md rows for T-TINY-V3-INT8-SIDECAR-MISSING-ONNX-HAS-SCALER and T-DNN-ATTACH-INT8-REDIRECT-MISSING. The two copies differed only in the reference column; kept the PR #1320 citation over the branch-name one, since a branch name is the placeholder state-md-touch-check.sh rejects and stops meaning anything once the branch is deleted.
2. Tiny AI — graph_bakes_scaler() guarded onnx.load() against the library being absent but not the file being unparseable, so test_consistency_check_int8_sha_mismatch (which writes b"int8payload" on purpose) got a DecodeError instead of the mismatch it asserts. Worse, the exception aborted _consistency_check and discarded every other finding. Now degrades to the same byte scan the no-onnx path uses.
3. Tidy Ratchet — exit 3, the good kind: this PR took dnn_attach_api.c from 1 warning to 0. Applied exactly CI's measured delta (total 2950 → 2949) rather than re-running the ratchet locally, since a host build resolves enable_dnn=auto differently from the CI cpu lane and would rebaseline unrelated files.

Still failing — Coverage Gate, and it is this PR's own new code:

critical: core/src/dnn/dnn_api.c — 82.0000% (min 83%)
  FAIL: security-critical file below 83%

Every other critical file passes. The 1-point miss is the int8→fp32 retry branch this PR adds to dnn_api.c:

if (rc < 0 && load_path != onnx_path) {
    load_path = onnx_path;
    rc = vmaf_ort_open(&s->ort, onnx_path, cfg);
}

Why the existing test does not cover it. test_use_tiny_model_int8_redirect_and_fallback covers the missing-file fallback — it unlinks the int8 and re-attaches. This branch is the session-open-failure fallback: the int8 file exists and clears both the size cap and the op allowlist, but vmaf_ort_open fails anyway (the "Could not find an implementation for ConvInteger" case the comment cites). Different branch, and it is reached through the session API rather than vmaf_use_tiny_model.

The mechanism to test it already exists: core/test/dnn/test_ort_error_injection.c compiles ort_backend.c with a mock OrtApi and a scenario enum that steers which call returns a non-NULL OrtStatus. Covering this branch means making CreateSession fail for the first open and succeed for the retry — the scenario global is currently all-or-nothing, so it needs a call-count-scoped scenario.

Holding this PR in the merge train meanwhile so it stops blocking the window — it has held it for about an hour across four CI rounds.