Tiny-model registry — schema and verification¶

The registry at model/tiny/registry.json is the trust root of libvmaf's tiny-AI surface. Every ONNX model shipped under model/tiny/ is indexed there with a SHA-256 pin, license metadata and a Sigstore bundle path. T6-9 / ADR-0211 formalised the schema and wired --tiny-model-verify to cosign verify-blob.

The registry holds 26 entries. Thirteen are CI smoke fixtures with smoke: true, see CI-only smoke fixtures.

Registry shape¶

{
  "$schema": "./registry.schema.json",
  "schema_version": 1,
  "models": [
    {
      "id": "learned_filter_v1",          // stable id; a label, not a --tiny-model value
      "kind": "filter",                    // fr | nr | filter
      "onnx": "learned_filter_v1.onnx",
      "opset": 17,
      "sha256": "412d537…e27",
      "quant_mode": "dynamic",             // fp32 | dynamic | static | qat
      "int8_sha256": "1cff6fe…2d3",
      "quant_accuracy_budget_plcc": 0.01,
      "license": "BSD-2-Clause-Patent",
      "license_url": "https://github.com/VMAFx/vmafx/blob/master/NOTICE",
      "sigstore_bundle": "learned_filter_v1.onnx.sigstore.json",
      "description": "Tiny residual filter for vmaf_pre — degraded → clean luma.",
      "notes": "Self-supervised on KoNViD-1k …"
    }
  ]
}

The full JSON Schema is model/tiny/registry.schema.json. The schema rejects unknown properties (additionalProperties: false).

Fields¶

The Sigstore bundle file is generated at release time by .github/workflows/supply-chain.yml. Before a release the path is declared but the file may be absent. The runtime verifier (--tiny-model-verify) treats an absent bundle as fail-closed.

Validate the registry¶

ai/scripts/validate_model_registry.py runs the JSON Schema check and the cross-file consistency check: every ONNX exists, every sha256 matches, every non-smoke entry has a sidecar. It also reads each graph (and its int8 sibling) with ai/src/aiutils/onnx_signature.py, which needs no onnx package, and fails when the registry opset or a sidecar's opset, sha256, input_names / output_names, input_name / output_name, feature-list length, encoder_vocab, codec_block_dim or codec_block_layout disagrees with the graph. It is a CI gate; run it before pushing:

python3 ai/scripts/validate_model_registry.py \
    --out-json runs/tiny_model_registry_validation.json
# → OK: 26 registry entries valid against registry.schema.json

To validate an off-tree registry, pass it and its schema explicitly:

python3 ai/scripts/validate_model_registry.py /path/to/other-registry.json \
    --schema /path/to/registry.schema.json \
    --out-json runs/offtree_registry_validation.json

Without jsonschema installed the validator falls back to a structural check, so distros without python-jsonschema still get the required-field invariants. Install jsonschema for full Draft 2020-12 coverage.

The optional --out-json report records the verdict, model count, errors, registry and schema paths, and the ADR-0661 run_provenance block. Use it for release evidence and for debugging failures without CI log scrollback.

Verify a model at runtime¶

--tiny-model-verify makes the loader check the model's Sigstore bundle before it opens the file:

vmaf -r ref.y4m -d dis.y4m \
     --tiny-model model/tiny/learned_filter_v1.onnx \
     --tiny-model-verify

The loader runs these steps:

1. Look up the model's basename in model/tiny/registry.json (alongside the .onnx by default).
2. Read the entry's sigstore_bundle path.
3. Spawn cosign verify-blob --bundle=<path> --certificate-identity-regexp … --certificate-oidc-issuer https://token.actions.githubusercontent.com <onnx> with posix_spawnp(3p) and an explicit argv array, no shell.
4. Refuse to load on a non-zero exit, a missing cosign, a missing bundle or a missing registry entry.

The flag is off by default for dev-friendliness; production deployments should set it. cosign must be on $PATH; install a prebuilt binary from the Sigstore release page. The C entry point is vmaf_dnn_verify_signature(onnx_path, registry_path) in core/include/libvmaf/dnn.h; both arguments are NULL-tolerant in the documented way.

Directory jail¶

The registry pins model identity. The optional VMAF_TINY_MODEL_DIR environment variable constrains model location. Set it on production hosts:

export VMAF_TINY_MODEL_DIR=/opt/vmaf-models
vmaf --tiny-model /opt/vmaf-models/vmaf_tiny_v2.onnx --tiny-model-verify ...

At load time libvmaf canonicalises the jail and the requested ONNX path. The model must resolve below the jail. Sibling-prefix escapes, symlink escapes, missing jail directories, and jail values that point at files fail closed with -EACCES. The jail does not replace registry verification or the operator allowlist: run all three layers together in production (see security.md).

What the registry is not¶

• Not the inference contract. Per-model input and output names, normalisation and expected ranges live in the sidecar JSON next to the ONNX (<basename>.json). The registry stays small and easy to audit. Attached multi-output models may use sidecar output_names[] for stable scalar-score suffixes in report keys.
• Not the operator-allowlist source of truth. That is core/src/dnn/op_allowlist.c. The registry pins identity; the allowlist constrains content.
• Not a path allowlist. Use VMAF_TINY_MODEL_DIR to reject model paths outside a trusted directory.

Add a model¶

1. Drop the .onnx and the matching <basename>.json sidecar under model/tiny/.
2. Compute the digest: sha256sum model/tiny/<name>.onnx.
3. Add an entry to registry.json. Use existing entries as templates; the schema enforces required fields.
4. Leave bundle generation to the release. Before a release the sigstore_bundle path may point at a file that does not exist yet.
5. Run python3 ai/scripts/validate_model_registry.py and fix what it reports.

The /add-model <path> skill scaffolds steps 1 to 4.

CI-only smoke fixtures¶

Thirteen registry entries (smoke: true) exist to exercise the loader and validator in CI. They are not user-facing surfaces, are exempt from the ADR-0042 five-point model-card requirement, and are excluded from doc-coverage checks. Do not set them to smoke: false without a model card and the full ADR-0042 bar.

lpips_sq_v1 and its cards¶

The registry entry lpips_sq_v1 (smoke: false) points to lpips_sq.onnx. Two model-card pages describe the same model: lpips_sq and lpips_sq_v1. The registry id and the file name differ by the _v1 suffix; this is a tracked cosmetic gap (scaffold-audit ADR-0621 P3-5).