The container
A directory that happens to zip.
An MLF package is a set of explicit records in a directory. The .mlf file is the deterministic, ZIP-compatible exchange form of exactly that directory — same bytes, same meaning, no separate format to keep in sync.
What 1.0 froze
- Deterministic
.mlfdirand.mlfcontainers. - A unique
manifest.jsonentry point. - Matrix, cell, region, role and style records.
- Coexistence of source formula, normalized AST and dependency graph.
- Route graph and reversible projection metadata.
- Provenance, conversion-loss reports, four-layer fingerprints and checksums.
- MLF 0.1 read compatibility, and non-destructive migration to 1.0.
- Safe import and export boundaries, with explicit unsupported-feature reporting.
Records, not a blob
The canonical package is a set of explicit records rather than one serialized object. Each file answers one question, and each can be read without parsing the rest.
manifest.json- Selects document-level resources.
- Matrix JSONL
- Cells, regions and styles, one record per line.
- Formula JSONL
- Source expressions and normalized ASTs.
- Graph JSONL
- Dependency edges and traversal routes.
- Provenance JSONL
- Append-only history.
- Reports
- Fingerprints and conversion loss.
checksums.json- Binds paths to bytes.
Layer separation
Six concerns, deliberately kept apart. The stable file format lives primarily in L1–L3; runtime, model and governance components consume the format without redefining it.
- L0Physical substrate
- L1Container and integritystable format
- L2Matrix knowledge modelstable format
- L3Formula, dependency, route and provenance graphsstable format
- L4Runtime and model projections
- L5Human projections and governance
L1–L3 hold the stable file format. L4 and L5 consume it without redefining it.
That boundary is what makes the format outlive its tooling. A projection layer can be replaced without touching a byte of the container.
Projections
Sequence, matrix tensor, graph tensor, execution stage, shard, summary and human table outputs are all projections. They are not replacements for the source structure, and the format never stores a projection in place of what it came from.
A human view is a view. It is written into projections/human_views.jsonl alongside the structure, not instead of it.
Determinism
Compiling the same input twice produces the same package, byte for byte. That is what makes the four fingerprints comparable across machines, and what lets mlfc diff say something meaningful about two packages rather than about two serialization runs.