Three steps, and only the third is public
Publishing a Minirun artifact is a sequence, not a single upload. A builder converts an upstream checkpoint into units and containers without changing any weight value. A gate proves that what landed on disk is what the checkpoint contained. Only then does a publisher move the result to Hugging Face, and it does so in a way that makes the public branch change exactly once.
This page describes the protocol the three existing artifacts were published under. It is written so that the contract is inspectable now, before the tooling is public.
Fetch pinned ranges from the upstream revision and write units, containers, and manifests. No dequantization.
Read the written bytes back off the drive against their recorded digests, then reopen the whole product through the reader that will consume it.
Upload only to a deterministic candidate branch, which is both the resume target and the record of what was published.
One commit copies the complete release onto the public branch, guarded by the parent commit that was observed.
Resolve the returned immutable commit and fail if it is not the expected release.
The builders
Each model family has its own builder, because the plan differs even though the machinery does not. All three fetch from a pinned upstream revision over HTTP range requests, share the same transport, retry and ledger code, and write the same container format.
They are resumable by construction rather than by retry. One journal file per unit is replaced atomically, so a killed job resumes from what the disk can prove rather than from what the process remembered. A chunk digest and a file offset are recorded together after every write, so a resume truncates back to a boundary that was actually durable. What is already verified is not fetched again.
| Family | Builder | What is family-specific |
|---|---|---|
| Kimi K3 | Tools/k3_flagship/build_full_artifact.py | 93 layer units plus a globals unit; MXFP4 expert containers and BF16/F32 deterministic streams. |
| DeepSeek V4 Flash | Tools/v4_flash/build_v4_artifact.py | 43 layer units, three multi-token-prediction units and one globals unit; block-FP8 containers alongside plain streams. |
| MiniMax H3 | Tools/h3/build_h3_artifact.py | Five upstream repositories reconciled into one artifact, with affine 8-bit containers and precomputed modulation. |
Byte-preserving means byte-preserving
A container written by these builders is a reordering of the checkpoint's own packed and scale streams. A plain stream is the checkpoint's bytes verbatim. The only bytes the builder writes that did not come from the checkpoint are container headers and the zero padding of an under-full scale sub-region.
There is no dequantization step and no requantization step, so there is no quality question to answer about the conversion. The corresponding obligation is that the offset arithmetic must be exactly right, because getting it wrong does not raise an error: it returns the right number of bytes from the wrong place, and those bytes decode into a plausible-looking tensor. Every fetched blob is therefore checked on arrival against the properties real data must have, and the negative control — omitting the base offset, which yields uniform random-looking bytes — is recorded and rejected.
The gate contract
Release verifiers and numerical probes use process exit status as part of their contract. A written JSON report or a printed summary is not, by itself, a passing result.
| Code | Name | Meaning |
|---|---|---|
| 0 | PASS | The required, non-empty evidence was checked and agreed. |
| 1 | FAIL | Evidence contradicted the expected bytes or numerics, or a claimed artifact was malformed or missing. |
| 2 | INCONCLUSIVE | The requested selection produced no evidence, required coverage was absent, or the result could not decide the claim. |
| 77 | SKIP | An explicitly optional probe could not run in this environment, or the caller explicitly disabled its central comparison. |
The Hub protocol
The publication step separates resumable transfer from release visibility. Transfer may take many commits; the public branch receives a complete release in one commit.
Before any upload, staging is reconciled in place and its file set is required to equal the validated release exactly. The public index, the public manifests and the payloads are then reopened from that reconciled tree through the consumer that will read them in production. For the two families whose containers carry digests, that round trip opens every tile container with the production format reader and reads every tile, which checks each recorded digest. A malformed public manifest, an unreadable payload, or zero evidence aborts publication.
Upload targets a deterministic candidate branch derived from the release paths, public metadata and staged payload identities. Replacing a payload — even with another file of the same size — produces a different resume target, so nothing has to reread terabytes merely to name the job. The candidate is then resolved to an immutable commit and its remote path and size inventory must match exactly, allowing only the platform-managed attributes file.
Promotion is one commit that copies every selected file from the immutable candidate, deletes stale release paths for a full publish, and is guarded by the branch head that was actually observed. If the head moved, the commit fails rather than overwriting concurrent work. The returned commit is inventoried, and publication fails if it is not the expected release.
- Promotion fails closed above 25,000 files or operations, matching the checked platform commit limit.
- Candidate branches are retained on purpose. They are the resume target and the record of what was published; deleting them automatically would turn an ambiguous client timeout into an unrecoverable state.
- The protocol does not claim that a lost response reveals whether a commit happened. It guarantees that any commit it makes on the public branch contains the complete selected snapshot, never one upload batch.
- The remote gate checks exact paths and sizes. Byte integrity comes from the local digest gates, the post-write round trip wherever the format carries a digest, and same-repository copying from the immutable candidate. It does not claim to re-download the model.
What the app requires of a publication
Discovery, verification, and chat are three separate capabilities with three different requirements. A repository can satisfy the first two and not the third, and the product says so rather than hiding the model or promising a conversation it cannot have.
- To be discovered
- The repository must be owned by the publishing account and its name must end in -minirun. This is an open set: a newly published repository is listed, downloadable and verifiable with no app release.
- To be verified
- The publication must expose a complete tree — a paginated digest tree whose exact path set equals the pinned repository-info siblings set at the same commit — and a container layout the app can validate without guessing. Root-level files in an unrecognized layout are classified conservatively; if that yields no positive-size payload, verification refuses rather than assuming a root file is a model weight.
- To be used for chat
- The app additionally needs a compiled runtime for that family: a model adapter, the tokenizer or input pipeline, a bounded runner, and one product registry entry pairing them. That is code, so a new model family needs an app release.
New revisions do not need a new app
A supported family's repository can be republished without shipping an app version. The product may recognize a family by its repository identity, but it may not authorize execution from that identity or from a revision compiled into the binary. Every accepted catalog refresh resolves the repository to an immutable commit and an independently reconciled complete tree, and execution requires complete local verification of that exact commit.
For K3, chat becomes available only when the current catalog descriptor and the selected local artifact agree, complete verification evidence exists for that exact commit and tree, the tokenizer declaration read from the verified index matches its recorded byte count, digest, source repository and revision, licence file and vocabulary geometry, and a product registry entry pairs the real tokenizer with the real runner. The tokenizer's source revision is evidence carried by the artifact, not a constant compiled into the app.
The symmetric consequence is stated too: an existing local copy becomes incomplete when the published tree gains files. It stays visible, but it cannot be used for chat until it is updated and fully verified. No previous evidence is silently inherited.