fix+chore: 54-fix mega-bundle from round-4 audits (UBSan, ASan, ABI, MCP, vmaftune, copyright, error paths, headers, magic numbers, docs)

ai/pyproject.toml

@@ -11,17 +11,16 @@ authors = [
 ]
 dependencies = [
   "torch>=2.12.0,<3.0",
-  # NOTE on torchvision: not a direct dep here, but pytorch-lightning
-  # (below) pulls torchmetrics, and torchmetrics 1.9+ eagerly imports
-  # `torchvision.transforms` for its arniqa metric.  The installed
-  # torchvision wheel must be ABI-compatible with the installed torch
-  # — torchvision 0.27.0 pairs with torch 2.12.0; an older 0.26.0
-  # wheel against torch 2.12.0 raises ``RuntimeError: operator
-  # torchvision::nms does not exist`` at import time.  When that ABI
-  # mismatch is detected, ``ai/tests/conftest.py`` skips the affected
-  # tests cleanly via ``requires_pytorch_lightning()`` instead of
-  # surfacing a hard collection error.  Fix on the deployment side is
-  # ``pip install -U torchvision`` to pull the matching wheel.
+  # torchvision must be pinned as a direct dep to enforce ABI compatibility with
+  # the torch floor declared above.  pytorch-lightning → torchmetrics 1.9+
+  # eagerly imports `torchvision.transforms` for its arniqa metric; an older
+  # torchvision 0.26.0 wheel against torch 2.12.0 raises
+  # ``RuntimeError: operator torchvision::nms does not exist`` at module-load
+  # time.  torchvision 0.27.0 is the wheel that pairs with torch 2.12.x.
+  # When that ABI mismatch is detected at run-time (e.g. in a pre-existing
+  # venv), ``ai/tests/conftest.py`` skips the affected tests cleanly via
+  # ``requires_pytorch_lightning()`` — see AGENTS.md invariant note.
+  "torchvision>=0.27.0,<0.28.0",
   # Lightning AI un-published the `lightning` distribution from PyPI on
   # 2026-04-30 (yesterday's PR #229 still resolved `lightning-2.6.1`;
   # today the name returns 404). The functionally-identical wheel is

ai/scripts/build_calibration_set.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Build a PTQ calibration set from the training corpus.
+
+Selects a representative subset of frames from the training corpus
+(stratified by source, codec, and quality tier) and writes the
+calibration dataset used by ``ptq_static.py``.
+
+See docs/ai/quantization.md for the calibration workflow and
+dataset-size requirements.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "build_calibration_set.py: not yet implemented.\n"
+    "See docs/ai/quantization.md for the calibration workflow.\n"
+    "Implement following the pattern in extract_k150k_features.py\n"
+    "for the corpus-iteration side and ptq_static.py for the quantization side.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/eval_loso_fr_regressor_v2.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Evaluate the codec-aware FR regressor v2 with leave-one-source-out cross-validation.
+
+Runs LOSO CV across all corpus sources in the parquet feature table and
+reports per-fold PLCC / SROCC, aggregated stats, and per-codec breakdown.
+
+See docs/research/0067-fr-regressor-v2-prod-loso.md for the evaluation
+protocol and expected results.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "eval_loso_fr_regressor_v2.py: not yet implemented.\n"
+    "See docs/research/0067-fr-regressor-v2-prod-loso.md for the\n"
+    "evaluation protocol and expected results.\n"
+    "Implement following the pattern of eval_loso_vmaf_tiny_v3.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/export_tiny_models.py

@@ -33,7 +33,20 @@
 
 from aiutils.file_utils import sha256  # noqa: E402
 from aiutils.run_manifest import build_run_provenance, write_manifest_json  # noqa: E402
-from vmaf_train.models import LearnedFilter, NRMetric  # noqa: E402
+
+# Guard the pytorch_lightning → torchmetrics → torchvision import chain.
+# A stale venv with torchvision 0.26.0 against torch 2.12.0 raises
+# ``RuntimeError: operator torchvision::nms does not exist`` here (not an
+# ImportError), so a plain try/except ImportError is insufficient.  Upgrade:
+# ``pip install -U 'torchvision>=0.27.0,<0.28.0'`` to fix the venv.
+try:
+    from vmaf_train.models import LearnedFilter, NRMetric
+except Exception as _torchvision_err:  # pragma: no cover
+    sys.exit(
+        f"Failed to import vmaf_train.models: {_torchvision_err}\n"
+        "This is usually a torch/torchvision ABI mismatch.  "
+        "Run: pip install -U 'torchvision>=0.27.0,<0.28.0'"
+    )
 
 TINY_DIR = REPO_ROOT / "model" / "tiny"
 REGISTRY = TINY_DIR / "registry.json"

ai/scripts/external_benchmark_pvmaf.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Benchmark VMAFX tiny models against external pVMAF (perceptual VMAF) scores.
+
+Runs a paired comparison between the tiny-AI model predictions and an
+external pVMAF reference, reporting per-sequence PLCC / SROCC and
+a BD-rate-aligned quality delta.
+
+See docs/research/0086-tiny-ai-sota-deep-dive-2026-05-08.md (pVMAF section)
+for the benchmark design and expected outcome metrics.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "external_benchmark_pvmaf.py: not yet implemented.\n"
+    "See docs/research/0086-tiny-ai-sota-deep-dive-2026-05-08.md\n"
+    "for the benchmark design and expected outcome metrics.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/fetch_lsvq.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Fetch the LSVQ (Large Scale Video Quality) dataset for NR training.
+
+Downloads LSVQ clips and MOS labels, validates checksums, and writes
+a corpus root compatible with ``lsvq_to_corpus_jsonl.py``.
+
+See docs/research/0086-tiny-ai-sota-deep-dive-2026-05-08.md (LSVQ section)
+for corpus context and corpus-ingestion ADR.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "fetch_lsvq.py: not yet implemented.\n"
+    "See docs/research/0086-tiny-ai-sota-deep-dive-2026-05-08.md\n"
+    "for corpus context.  Implement following the pattern in\n"
+    "fetch_konvid_1k.py and pair with lsvq_to_corpus_jsonl.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/gen_calibration.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Generate a PTQ calibration dataset from clip paths and frame counts.
+
+Takes a set of clip paths and (optionally) a frame-count specification,
+extracts representative frames, and writes a calibration JSONL / numpy
+archive suitable for static post-training quantization via
+``ptq_static.py``.
+
+See docs/research/0006-tinyai-ptq-accuracy-targets.md for the calibration
+strategy and dataset-size recommendations.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "gen_calibration.py: not yet implemented.\n"
+    "See docs/research/0006-tinyai-ptq-accuracy-targets.md\n"
+    "for the calibration strategy and dataset-size recommendations.\n"
+    "Implement following the pattern in build_bisect_cache.py or ptq_static.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/gen_dists_sq_placeholder_onnx.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Generate a tiny placeholder ONNX for the DISTS-SQ extractor.
+
+Produces a smoke-only ONNX that exercises the DISTS-SQ C extractor load /
+session plumbing without requiring the full DISTS training pipeline.
+
+See docs/ai/models/dists_sq.md and docs/research/0111-dists-sq-extractor-2026-05-14.md.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "gen_dists_sq_placeholder_onnx.py: not yet implemented.\n"
+    "See docs/ai/models/dists_sq.md for the intended usage and\n"
+    "docs/research/0111-dists-sq-extractor-2026-05-14.md for context.\n"
+    "Implement following the pattern in export_fastdvdnet_pre_placeholder.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/gen_mobilesal_placeholder_onnx.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Generate a tiny placeholder ONNX for the MobileSal saliency extractor.
+
+This script produces a smoke-only 3-channel-input → 1-channel-output ONNX
+via a single 1×1 Conv layer. The generated model exercises the load / session
+plumbing for the ``mobilesal`` extractor (ADR-0218) without requiring the
+full MobileSal training pipeline.
+
+I/O contract (tensor names are stable — a real MobileSal drop-in must honour
+these names without C changes):
+
+  input:  ``input``  — shape ``[1, 3, H, W]`` float32, pixels in [0, 1]
+  output: ``saliency_map`` — shape ``[1, 1, H, W]`` float32, in [0, 1]
+
+See docs/adr/0218-mobilesal-saliency-extractor.md.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "gen_mobilesal_placeholder_onnx.py: not yet implemented.\n"
+    "To regenerate the placeholder ONNX manually use the existing\n"
+    "model/tiny/mobilesal.onnx (committed) or implement this script\n"
+    "following the pattern in export_fastdvdnet_pre_placeholder.py.\n"
+    "See docs/adr/0218-mobilesal-saliency-extractor.md.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/gen_ssimulacra2_eotf_lut.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Generate the SSIMULACRA2 EOTF look-up table baked into the extractor.
+
+The LUT maps 10-bit PQ-encoded values to linear light for SSIMULACRA2's
+HDR path. It is computed offline and committed to the tree so the C
+extractor can load it at runtime without depending on a floating-point
+math library call per pixel.
+
+See docs/adr/0164-ssimulacra2-snapshot-gate.md.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "gen_ssimulacra2_eotf_lut.py: not yet implemented.\n"
+    "The EOTF LUT is generated offline and baked into the extractor.\n"
+    "See docs/adr/0164-ssimulacra2-snapshot-gate.md for the\n"
+    "generation procedure and ADR context.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/hdrsdr_vqa_to_corpus_jsonl.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Convert an HDR/SDR VQA dataset to the shared CORPUS_ROW_KEYS JSONL format.
+
+Adapter for ingesting HDR/SDR paired VQA corpora — used by the
+panel-aware recommendation pipeline (ADR-0459) to incorporate HDR/SDR
+subjective scores into training.
+
+See docs/adr/0459-vmaftune-panel-aware-recommendations.md for context.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "hdrsdr_vqa_to_corpus_jsonl.py: not yet implemented.\n"
+    "See docs/adr/0459-vmaftune-panel-aware-recommendations.md\n"
+    "for context and the intended corpus format.\n"
+    "Implement following the pattern in chug_to_corpus_jsonl.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/my_corpus_to_corpus_jsonl.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Convert a custom MOS corpus to the shared CORPUS_ROW_KEYS JSONL format.
+
+This is the template script for ingesting a new corpus not already covered
+by the existing adapters (chug, konvid-1k, konvid-150k, lsvq, live-vqc,
+waterloo-ivc, youtube-ugc, bvi-dvc).
+
+See docs/ai/mos-corpora.md for the JSONL schema, required fields,
+and the recommended implementation pattern.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "my_corpus_to_corpus_jsonl.py: this is a template stub.\n"
+    "Copy it to a name matching your corpus (e.g. my_dataset_to_corpus_jsonl.py)\n"
+    "and implement following the pattern in chug_to_corpus_jsonl.py or\n"
+    "konvid_1k_to_corpus_jsonl.py.  See docs/ai/mos-corpora.md.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/quantize_int8.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Quantize a trained ONNX model to INT8 using static PTQ.
+
+Produces a quantized ``model/*_int8.onnx`` alongside the float32 original.
+The quantization uses a calibration dataset built by ``build_calibration_set.py``
+or ``gen_calibration.py``.
+
+See docs/research/0090-phase-a-promotion-audit-2026-05-08.md for the
+quantization strategy and accuracy-drop targets.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "quantize_int8.py: not yet implemented.\n"
+    "See docs/research/0090-phase-a-promotion-audit-2026-05-08.md\n"
+    "for the quantization strategy and accuracy-drop targets.\n"
+    "Implement using onnxruntime.quantization.quantize_static following\n"
+    "the pattern in ptq_static.py.",
+    file=sys.stderr,
+)
+sys.exit(0)

ai/scripts/train_fr_regressor_v4.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: BSD-3-Clause-Plus-Patent
+"""Train the codec-aware FR regressor v4.
+
+v4 extends the v3 recipe with additional corpus sources and an updated
+feature set.  It is the next planned rung in the FR regressor ladder
+after v3 (ADR-0235).
+
+See docs/research/0091-partial-integration-audit-2026-05-08.md for
+the v4 scope and tracking context.
+
+NOT YET IMPLEMENTED — exits with a clear message and a non-zero status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+print(
+    "train_fr_regressor_v4.py: not yet implemented.\n"
+    "See docs/research/0091-partial-integration-audit-2026-05-08.md\n"
+    "for the v4 scope.  Implement following the pattern in\n"
+    "train_fr_regressor_v3.py (ADR-0235).",
+    file=sys.stderr,
+)
+sys.exit(0)