The Container

Chris Hay

THE CONTAINER · CANDIDATE SPEC §4–5

ONE DIRECTORY, ONE ROOT

A VINDEX3 container is not a single blob. It is a directory whose every part is named, addressable, and explained — this page walks all of them.

What is a VINDEX3 container?

A directory, not a blob: one root authority (index.json) speaking for version, identity, checksums and segments; a system graph recording what the model means; segments holding the bytes; and execution profiles selecting among physically present representations. Every part is named and checkable, so the same artifact can be understood, executed, transformed and verified — including after the source checkpoint is deleted.

Today, changing your mind about a model means making another file.

WHAT THIS FIXES

You download a checkpoint: a folder of shards whose meaning lives in filename conventions. You quantize it: now there are two files, and the lineage between them is a commit message somewhere. A colleague needs another precision: three. Delete the original to save space, and no one can ever again prove what the copies are. The release was a system — a model, its tower, its drafter, its precisions. The folder is a rumor about it.

THE QUESTIONS A FOLDER CANNOT ANSWER

What are these model objects? What operations can consume them? Which representations are equivalent? Which parts should be resident? What future computation will need them? A serving file answers one question — how do I store and run these tensors. The container is built to answer all of them.

THE BRIDGE — FROM CHECKPOINT TO CONTAINER

Start from the files you already have. Compile down.

a checkpoint — what you download today

config.json

model-00001-of-00004.safetensors

model-00002-of-00004.safetensors

model-00003-of-00004.safetensors

model-00004-of-00004.safetensors

tokenizer.json

may now be deleted — execution must not change

inventory ↓

read what the source declares

plan ↓

judge it — typed findings, ambiguity refused

graph ↓

components · objects · edges

encode ↓

segments first, index.json last

verify ↓

Declared ≡ Resolved ≡ Graph ≡ Encoded

model.vindex/ — written, then proven

system_graph.json

segments/ — one per logical object

tokenizer.json + capability snapshot

index.json — the root, written last

verified — byte-faithful to its source

A checkpoint — config.json and safetensors shards — is inventoried, judged, formed into a graph, encoded in write order with index.json last, and verified against its source. Then the checkpoint may be deleted: execution must not change. That is the whole bridge, and it is crossed once.

There is no second root. A second root creates competing authorities — whose checksums win? whose version controls compatibility?

THE CONTAINER — THREE DEPTHS

ONE DIRECTORY, ONE ROOT

A container is an ordinary directory you can list. One file in it is in charge: index.json, the single root authority that names every part, carries its checksums, and states the version governing how the whole thing is read. Everything else is reached through it — the system graph that says what the model's parts mean, the segment files that hold the bytes, the profiles that decide which of them load. There is no second root, because two roots are two answers to the same question.

EXPLORE — CLICK YOUR WAY INTO A CONTAINER

Go on. Open things.

A worked example — the same geometry as the encoder below on the Bytes page, not a specific model. Every size is computed with the spec's own arithmetic. Nothing here is a screenshot.

model.vindex/ — THE CANONICAL SHAPE

Four parts. One is in charge.

index.jsonSOLE ROOT AUTHORITY

The one file every reader opens first, and the only place the container speaks for itself. It names the model, declares the container generation, and carries the maps that make everything else findable and checkable. If a fact matters to loading the container, it is here or reachable from here.

versionthe container generation — VINDEX3 spans schemas 3–4, and a fresh encode stamps 4; detection uses this field only, never filename sniffing

model · familyidentity: which model this is, and its architecture family

hidden_size · num_layersthe geometry every consumer needs before touching a weight

system_graph · moe_manifestwhich shape this container is: the canonical graph shape carries a graph and no manifest; the transitional bank shape carries the reverse. Absence of a manifest is not evidence a model is dense

representationswhich physical encodings exist for which objects, with recorded fidelity

profiles · variantsthe execution profiles — inline in the index, not a directory — and each region set's physically present variants with its baseline

segmentswhich files hold which payloads — the loader never globs the directory

authorityCanonical or Derived — a derived image cannot recompile itself, and says so; derived_from_model keeps the provenance link

precision_mapwhen present, the compiled policy saying what encoding each tensor is in

system_graph.jsonTHE SEMANTIC AUTHORITY

The SystemGraph, verbatim: components, logical objects, hidden-state edges, per-layer attention policies. Built once from source evidence when the container is made; from then on it is the only semantic authority — execution, verification, and the query surface all read the graph, never the checkpoint. The Graph chapter walks it in full.

segments/THE PAYLOAD

One file per logical-object representation — target.decoder_stack.bin, target.embedding.bin — each carrying its own tensor table (name, dtype, shape, offset, length) and hashed twice in a single writing pass: the payload, and the whole file. Names inside a segment are object-relative, never artifact-global. The write order is deliberate — segments first, index.json last — so a crash midway leaves a directory that never claimed to be a container.

tokenizer.json + capability snapshot

The supporting cast: the tokenizer, tokenizer_config, special_tokens_map, generation_config, chat template. The encoder proper writes only what execution needs; this snapshot is what keeps a fresh container servable — without it, a container binds with token-id capability only and refuses text inference.

The canonical shape — what every mainline producer writes: encode, extract with an explicit V3 request, and the LQL and factory surfaces, all through one shared pipeline.

Four parts. One is in charge. — index.json · system_graph.json · segments/ · tokenizer.json + capability snapshot.

the ABI — §5.1 The canonical layering

A VINDEX3 container is, canonically:

container envelope            the directory + index.json (sole root authority)
  └── SystemGraph             the logical-model authority: components,
      │                       per-layer attention policies, hidden-state edges
      └── logical objects     identity {component}.{kind} — embedding,
          │                   decoder_stack, output_head, perception_tower, …
          └── representations physically present encodings of an object,
              │               each with recorded fidelity (canonical | approximate)
              └── segments    hashed, mmap-able byte files
                  └── codecs  the segment's encoding: plain tensor-table,
                              LYRW v2 expert banks (§6), future families

Meaning flows down; bytes never define meaning. The graph references object and representation ids; the index's directory maps representations to segment bytes; graph edges never reference safetensors names — the HF checkpoint disappears as an authority once encoded. The full graph schema is specified in the living spec (§5–§6 there); its shape:

SystemGraph
├── components: [Component]        id, role, num_layers, hidden_size,
│                                  attention: [AttentionLayerPolicy]?
├── objects:    [LogicalObject]    id, component, kind,
│                                  source_bindings, representations
└── edges:      [HiddenStateEdge]  producer_component, producer_layers,
                                   consumer_component, consumer_object

the whole document →

One directory, explored three ways: what it is, the real thing to click through, and the canonical layering the specification requires.

The container model — learn: what a container is · inspect: open a real one · spec: the clause that governs it. One concept, one URL, the depth of your choosing.

THE TRANSITIONAL BANK SHAPE

One other shape exists, and since the 3.0 Candidate it is named and ranked rather than left ambient: the expert-bank import layout — index.json, a moe_manifest.json binding banks to programmes, and LYRW v2 bank files. It predates the graph authority; readers must accept it, new writers should not extend it, and its future is fixed by the convergence rule: the graph is the format, and a bank layout is an encoding a representation may use. The Bytes page walks its binary layout to the byte.

THE FIVE DURABLE WEIGHT CLASSES — THE SERVING VOCABULARY

A classification, not a directory tree.

class 1 — control & routerSMALL, DECISIVE

Token embeddings, normalisation weights, the LM head, the routers that decide which experts see each token, and the recurrence and control parameters of linear-attention designs. Small, and routing errors compound — so this class is preserved at source precision, never approximated.

class 2 — dense spineEVERY TOKEN

The backbone every token passes through: the attention projections — softmax attention, and the KDA, MLA and linear-attention families where a model uses them. A dense-only model is simply a container where this class carries the whole story.

class 3 — shared FFNALWAYS RESIDENT

Feed-forward weights every token uses regardless of routing: shared experts, and the shared pre/post projections of latent-space designs. Kept apart from the routed banks because they are always resident, while routed banks can be paged, trimmed, or left on disk.

classes 4 & 5 — routed expert banksTHE BULK

The bulk of a mixture-of-experts model: the per-layer expert banks — gate/up in one class, down-projections in the other. Stored as group extents, so experts can be fetched in useful units, and split into segment files when a layer outgrows the shard cap — the reason a fifty-gigabyte layer is not a fifty-gigabyte file.

Classes are the boundaries serving policy can decide about independently — fetch, place, quantise, omit, query. Draft-era layouts mandated one directory per class; the Candidate keeps the classes and withdraws the directory tree: storage references are container-relative paths, and there is no sixth class — hot sets, expert retention, cache sizing, and prefetch order are profile and runtime metadata, never new storage classes.

A classification, not a directory tree. — class 1 — control & router · class 2 — dense spine · class 3 — shared FFN · classes 4 & 5 — routed expert banks.

WHY CLASSES AT ALL

A part gets its own physical identity only when the runtime may independently omit it, quantise it, place it, prefetch it, execute it — or query it. That is the split rule. The query clause is real: WALK reads gate rows without up or down, so on a browse-enabled index the gate role has an independent access pattern by construction. Query metadata itself stays derived and optional — its absence downgrades label richness, never correctness — because no query index is stored beside the weights: the weights are the query index.

THREE AXES — IDENTITY, REPRESENTATION, RESIDENCE

LOGICAL OBJECT        what it is
      ↓
REPRESENTATION        how it is encoded
      ↓
RESIDENCE             where the useful bytes live right now

Residency is operational, not semantic: the same container means the same thing mmap-cold on NVMe, resident in unified memory, or split across devices. The Candidate pins the division — the format may carry portable residency facts (access class, zero-copy capability, evictability, co-use grouping), while placement belongs to a runtime plan that is never persisted: a device name in the format would age with the machine, not the model. Artifact size, resident-set size and bytes-touched-per-token are three independent quantities — which is the whole point for models larger than memory.

One token, one flash. The first three classes work on every token; the routed banks contribute a sliver — a handful of experts out of hundreds, different ones each time. Different traffic is different economics, and different economics is why each class may be placed, paged, or quantised on its own terms.

Classes 1–3: touched by every token. Classes 4–5: touched top-k-at-a-time. The split rule in one picture.

inventory → plan → encode → inspect → verify → execute → serve — one checkpoint — every stage, once.

Named parts are a promise. The next chapter is whether you can check it — down to the byte.

FOLLOW THIS IDEA — THE SYSTEM GRAPH →FOLLOW THIS IDEA — LYRW, TO THE BYTE →FOLLOW THIS IDEA — SELECTION, NOT CONVERSION →

PUBLISHED 29 AUG 2026 · REVISED 30 AUG 2026 · VERSION 3.0 Candidate

CITE

site build 43a1b6b · built 2026-09-02

CITE THIS

Web page · 3.0 Candidate

Hay, C. (2026). The Container. In VINDEX3 Specification (Version 3.0 Candidate). VINDEX3. https://vindex3.org/container

A chapter of the specification, citable on its own. Cite the version rather than the site — the canonical reference, and how to use it, live at /cite.

SOURCES

vindex3-format-spec.md §4–5, §8–9, §15 (the 3.0 Candidate)
reference implementation — index.rs (Vindex3Index)