feat(ai): add a resumable stage runner and a mini retrain that exercises the retrain tooling in CI

[lusoris]

Summary

The retrain tooling now runs end to end in CI on a generated corpus. make mini-retrain (about 40 s) runs extraction, feature checks, combination, training and export of vmaf_tiny_v2..v4 and fr_regressor_v1, validation, registry validation and a PLCC / SROCC / RMSE gate, with the runbook's scripts and flags. Every stage writes a manifest; a killed run resumes from the manifests; a missing or corrupt input fails with the stage name before anything runs. Stacked work (codec-aware FR regressors, ensemble, NR head, QAT, quantisation, model cards, predictor, K150K stage, resource plan) is not in this PR.

Defects found on the way: motion was NaN in every extracted row (fixed here); seven more are recorded as docs/state.md rows (runbook flags, validators passing NaN, trainers without a finite check, extraction swallowing failures, registry upsert dropping fields, K150K identity rows in the teacher fit (maintainer decision), missing signing bundles).

Evidence

Measured with the dev image's torch 2.14.1 / onnxruntime 1.30.0 / ONNX 1.22 on CPU (4 cores) and vmaf 1.0.0-rc.2.

Check	Result
pytest ai/e2e ai/tests/test_pipeline.py test_retrain_checks.py test_mini_corpus.py test_feature_extractor_unit.py	78 passed
Two fresh runs	corpus, feature tables, checkpoints, ONNX files, registry, gate report byte-identical (14 stable outputs compared); sidecars differ by run path only
SIGKILL of the driver and its stage during train_tiny_v2, then re-run	earlier stages not redone, run completes
Mini gate	4 of 4 models pass (PLCC 0.66-0.68, SROCC 0.69-0.71, RMSE 10.5-10.9 in-sample; mini thresholds prove plumbing only, see runbook section 13)

Failing-first. Real defect: the first run stopped at verify_features with column(s) ['motion'] are NaN in every row; test_lookup_motion_reads_the_sad_score_libvmaf_emits fails without the alias. Planted defects (each stops at the named stage with a named error): dropped column, NaN feature, 0-1 label scale, wrong teacher, all-NaN column, truncated table; a constant-output model passes validate_vmaf_tiny_v3.py ("PASS - PLCC nan >= gate") and is stopped by the gate stage. Mutations: removing the key check, output-digest check, preflight, empty-file check, exit-code check, the running guard each fail named unit tests; removing the finite check, the dead-column check or the gate's NaN handling fails the matching e2e test.

Type

• feat — new feature
• fix — bug fix
• build / ci — tooling / infra

Checklist

• Conventional Commits.
• make format && make lint green locally (hooks on); praetorctl audit clean.
• No SIMD/GPU, no native file, no ABI change: Python tooling and CI only; tidy: not applicable (no native file touched).
• ADR: ADR-1898, row in docs/adr/_index_fragments/.
• docs/state.md updated: 7 rows opened, 1 closed (T-AI-FULL-FEATURES-MOTION-ALL-NAN-2026-10-05).
• No Netflix golden assertion modified.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: tooling and CI; measurements are in this body.
• Decision matrix — ADR-1898 ## Alternatives considered.
• AGENTS.md invariant note — ai/AGENTS.d/mini-retrain.md.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/added/mini-retrain-pipeline.md, changelog.d/fixed/full-features-motion-nan.md.
• Rebase note — docs/rebase-notes.md.

Docs: docs/ai/retrain-runbook-1246.md section 13.

Reproducer

meson setup build core && ninja -C build tools/vmaf
make mini-retrain MINI_RETRAIN_DIR=runs/mini VMAF_BIN=build/tools/vmaf
make mini-retrain-test

Known follow-ups

Stacked PRs: runbook flag fixes with a runbook-lint test; validators and trainers refuse NaN; extraction failure accounting; registry upsert; remaining model families and stages; resource plan. Hardware: the run used the CPU only.