Model Artifact Mesh, Build Variants and Replicas

1. The real problem: a model name is not an executable identity

A production system may call everything “atlas-7b” while that friendly name hides different upstream revisions, quantizations, formats, and runtime-specific builds. If the system stores only a filename or alias, it cannot prove which bytes were qualified. This lesson builds a Model Artifact Mesh that separates immutable build identity from mutable names.

2. Bounded outcome

The owned artifact is Model Artifact Mesh Manifest & Replica Integrity Record v1. It records source repository and revision, build recipe, variant, format, precision/quantization, digest, size, runtime compatibility, hardware constraints, qualification binding, and replica state. Resumable transport, legal permission, node selection, and runtime telemetry remain outside this lesson.

3. Three identity layers: source, build, replica

Source identity says which repository revision a build came from. Build identity says how that source became a concrete format/precision/quantization and binds the result to a digest. Replica identity says where one copy of that exact build lives and what digest is observed there. Collapsing these layers destroys provenance and auditability.

4. Content address beats filename

OCI Content Descriptors include a digest as a content identifier and a byte size, and the specification recommends verifying retrieved content against digest and size when consuming from untrusted sources. We borrow that content-addressability pattern for model artifacts without claiming that MAKNOW artifacts must be OCI images. Filenames are metadata; the digest is decisive identity evidence.

5. Pin the upstream revision

Hugging Face Hub downloads can be pinned to a specific revision, including a full commit hash, and snapshot downloads materialize under a commit-specific snapshot path. That is valuable provenance, but it does not identify a local build variant. One source revision may produce FP16, Q4, Q5, or runtime-specific outputs, each requiring its own immutable build identity.

6. What counts as a build variant?

A build variant is more than a label such as “Q4.” Record format, precision or quantization, build-recipe version, runtime compatibility, hardware constraints, digest, and byte size. Any decisive change that alters output bytes or executable constraints creates a new variant. Never overwrite the old identity.

7. Mesh and the index pattern

OCI Image Index is a standardized example of a higher-level manifest that points to one or more manifests and can describe platform variants. MAKNOW uses the concept as a design pattern: one artifact family may point to several immutable builds. Model quantization and runtime metadata remain MAKNOW-specific and are not equated with OCI platform fields.

8. A mutable alias is a pointer, not identity

atlas-7b:prod may point to the FP16 digest today and a Q4 digest tomorrow. Historical audit records therefore store the exact digest, not only the alias. Repointing an alias must not transfer old qualifications or replica records to the new target. Aliases help discovery; they do not prove identity.

9. Qualification must bind to a digest

Qualification binds to the exact build digest and relevant source/build provenance. A new Q5 build from the same source revision cannot inherit Q4 or FP16 qualification merely because the family name is unchanged. Until independently qualified, the new digest remains blocked or deferred rather than silently accepted.

10. When is a replica AVAILABLE?

A replica becomes AVAILABLE only when the expected build digest and size are known, the observed replica digest and size match, provenance is coherent, verification evidence is fresh enough, and qualification binds to that exact digest. A replica with the same filename and alias but a different digest is QUARANTINED.

11. Preserve UNKNOWN, STALE, and QUARANTINED

If no replica digest was measured, preserve UNKNOWN. If verification is older than the evidence freshness window, preserve STALE. If digest or size conflicts with the build identity, use QUARANTINED. Do not coerce these typed states into a generic success boolean.

12. Atlas-7B scenario

The upstream revision is r42. A GPU FP16 safetensors build has replicas on gpu-a and gpu-b; a CPU Q4 GGUF build lives on edge-c. The mutable alias atlas-7b:prod points to the FP16 build. After a mirror refresh, gpu-b keeps the same filename but reports a different digest. gpu-a may remain AVAILABLE; gpu-b must be QUARANTINED.

13. Changed-context transfer: add Q5

A Q5 build is produced from the same r42 source. The source revision is unchanged, but recipe, quantization, and digest are new. Add Q5 beside Q4 and FP16 without mutating either prior identity. Old qualification and replica records do not silently transfer to Q5.

14. Boundary with adjacent lessons

AIE-014 owns chunked and resumable byte transfer. AIE-015 owns license policy. AIE-016 owns capability-aware placement. AIE-017 owns device telemetry. AIE-013 owns artifact identity, provenance, build variants, mutable aliases, qualification binding, and replica integrity only.

15. Decision and delivery checklist

For every build, record exact source revision, recipe version, variant, format/precision/quantization, digest, size, and qualification target. For every replica, record observed digest/size, evidence freshness, provenance consistency, and final typed state: AVAILABLE, UNKNOWN, STALE, QUARANTINED, or BLOCKED. The decision must be auditable from the record without hidden reasoning.