The module map
The source is a Swift package of layered modules, and the layering is a rule rather than a habit: a module may depend on the ones below it and never on the ones above. The rule exists so that one model's assumptions cannot reach the storage layer, and so that the half of the product concerned with catalogs, downloads and verification can be exercised without a graphics stack attached.
The bounded read path — pread, cache control, region descriptors, the tile container format. Depends on nothing else in the package.
The adoption seam between a read buffer and an MLX array. Above StorageCore, never below it.
Catalog, resumable downloader, storage and permission lifecycle, verification, and the pure planning arithmetic of the memory dial. Links no MLX and no Metal.
Architecture-specific layouts, tensor order, expert routing, and generation semantics.
The measured scenarios: what a device actually runs, as opposed to what it picks.
The bounded runner implementations and the product memory policies. The top of the stack.
Three rules the layering exists to enforce
- MinirunKit deliberately links no MLX. The half that must link an adapter is the runner implementation, which sits above the scenarios and only has to satisfy the protocol MinirunKit declares.
- The command-line argument parser is the package's only external dependency, and it must never reach StorageCore.
- The memory-dial planner is pure unsigned integer arithmetic over a census the caller transcribed: no clock, no filesystem, no MLX. Its tests run with no drive and no checkpoint attached.
The specification is the design record
A single living document, the storage-native MLX inference specification, carries the numbered requirements the code refers to: the container requirements, the planning rules, the reproducibility checklist every documented measurement must satisfy, and a changelog in which each version states what changed and what it was measured against.
It describes its own status as exploration and pre-architecture. That is worth taking literally. The container format is versioned with an explicit compatibility policy, and the project's claims are bounded by what has been measured, but the design is not frozen and the document says so.
It also records explicit non-goals. Competitive interactive throughput is one of them. Minirun is built so that a model larger than memory runs correctly, boundedly and verifiably; being fast at it is desirable and is not the criterion the work is judged on.
Decisions are recorded, including the ones that cost something
Architecture decision records sit beside the specification. Each names the context, the alternatives that were rejected and why, the evidence, the decision, and — the part that matters most — the consequences that were knowingly accepted.
| ADR | Decision |
|---|---|
| 0001 | A pread worker pool rather than an asynchronous dispatch I/O path for the pager. |
| 0002 | No fork of mlx-swift. Adopting a read buffer is the default transfer mode; copying is the retained fallback. |
| 0003 | Per-layer containers, whole-expert reads, a pinned hot set, and the repack question moved to the deterministic stream. |
| 0004 | The pinned repository-info siblings set independently authorizes tree completeness; the digest tree alone cannot. |
| 0005 | A manager-owned file-descriptor capability for artifact HTTP bodies. |
| 0006 | Explicit HTTP authorization is bound to one origin across redirects. |
| 0007 | The product runtime binds to current verified evidence, never to a repository name or a compiled-in revision. |
| 0008 | Local artifacts are removed through descriptor-bound isolation rather than by path. |
| 0009 | Indexed model discovery is separated from tree authority. |
| 0010 | K3 retains its attention decode state in latent form rather than decompressed. |
| 0011 | A deliberately bounded iPhone K3 tier, rather than a generic force-run switch. |
| 0012 | Persistent verification binds to a volume UUID and object ids, so evidence survives a remount. |
| 0013 | Under held verification authority, a tile the run already verified is not re-hashed at decode. |
What a new model family costs
Adding a family is not a name in a menu. The catalog carries two separate facts about a model, and both need a case: the architecture, which is what the runtime computes, and the artifact layout, which is how the published bytes are arranged on disk. Two models can share an architecture family and be laid out differently, and it is the layout that decides whether a directory someone picked is what the runner expects.
Both enumerations carry an explicit unrecognized case. That is a statement of missing knowledge rather than a fallback: a repository with no declared layout stays visible, and callers must not infer one from filenames.
- An architecture case
- The adapter that knows the model's tensor order, routing, recurrent or cache state, and generation semantics.
- A layout case
- The declared unit directory and file-suffix arrangement the downloader plans against and the verifier validates.
- A bounded runner
- An implementation that admits a run against a stated budget, refuses rather than clamping, tears down its own state on stop, and reports honest lifecycle and measurement events.
- A product registry entry
- One binding that pairs a real tokenizer with a real runner, and carries the tokenizer's source model, revision and digest evidence. The registry is the sole capability authority: a catalog field cannot enable a run, and the verified constructor accepts neither a preview tokenizer nor a mock runner.
Licence and contribution terms
The public source distribution is the buildable macOS and iOS product, released under the Apache License 2.0 with a NOTICE file, third-party attribution and an explicit trademark policy. Contributions are accepted under a Developer Certificate of Origin 1.1 sign-off.
The research repository that holds the raw experiment records, the cluster and conversion tooling, and the checkpoint-derived fixtures is separate and remains private. Publishing more of it is intended rather than promised, and this documentation states which side of that boundary a thing is on rather than implying everything is already open.