File-backed model registry

Why a file-backed registry

A database is useful at scale, but it is not required to begin. A carefully designed file-backed registry can provide reproducibility, portability, code review, offline operation, and transparent backups. The key is to treat the filesystem as an immutable artifact store, not as a folder of mutable filenames.

Directory layout

registry/
  artifacts/
    sha256-abcd.../
      manifest.json
      model.bin
      tokenizer.json
      contract.json
      lineage.json
      evaluation-card.json
      signatures/
  aliases/
    document-classifier-champion.json
    document-classifier-canary.json
  indexes/
    by-capability.json
    by-parent.json
    by-state.json
  locks/
  audit/
    2026-06-26.jsonl

Immutable artifacts

The artifact directory name is the digest of a canonical package manifest or complete bundle. Once written and verified, it is never edited. Corrections create a new artifact. This makes rollback and audit deterministic.

Atomic aliases

Human-readable aliases such as champion point to immutable artifact identifiers. Update aliases by writing a new file, syncing it, and atomically renaming it. Keep the previous alias record in append-only audit storage.

PROCEDURE promote_alias(alias_name, artifact_id, approval)
    REQUIRE ARTIFACT_EXISTS_AND_VERIFIED(artifact_id)
    REQUIRE approval.satisfies_policy

    next <- {
        alias: alias_name,
        artifact_id: artifact_id,
        previous_artifact_id: READ_ALIAS(alias_name),
        changed_at_utc: NOW_UTC(),
        approval_id: approval.id
    }

    WRITE_TEMP_FILE(alias_name, CANONICAL_JSON(next))
    FSYNC_TEMP_FILE(alias_name)
    ATOMIC_RENAME_TEMP_TO_ALIAS(alias_name)
    APPEND_AUDIT_EVENT("alias_promoted", next)
END PROCEDURE

Concurrency

Use advisory locks or lock directories around writes. Readers do not need locks when artifact directories are immutable and aliases are atomically replaced. Avoid network filesystems whose rename or fsync semantics are not understood.

Generated indexes

Indexes are derived, not authoritative. A build command scans manifests and writes capability, lineage, state, and search indexes. If an index is corrupted, regenerate it from artifacts and audit events.

Signing and trust

Store detached signatures or signed canonical manifests. Verification keys are managed outside the registry write path. A package copied into the directory is not eligible until its digest, signature, contract, and evaluation card are verified.

Backup and recovery

Back up artifacts, aliases, audit logs, and signing metadata separately. Recovery should rebuild indexes and verify every alias target. Test restoration before the registry becomes operationally critical.

Migration path

When query volume, multi-writer coordination, or retention becomes too complex, add a database as an index over the same immutable artifact store. Preserve content-addressed identifiers and manifest formats so the control plane does not depend on one database product.