MLF 1.0 · Compiler 1.0.0
Flatten it later. Keep the structure first.
MLF preserves what is routinely lost when structured work is reduced to a single token sequence: coordinates, regions, semantic roles, formulas, dependency edges, traversal paths, presentation hints, provenance, and an explicit record of what the import could not carry.
manifest.json
The unique entry point. Selects the document-level resources; nothing else may claim to be the root.
container and integrity — outside the four fingerprints
The package layout from README.md, with each member marked by the fingerprints it feeds. A .mlf file is the deterministic ZIP-compatible exchange form of this same directory.
Status
| Component | Status |
|---|---|
| MLF 1.0 container and manifest | Stable |
| CSV / Markdown / bounded XLSX compilation | Stable reference implementation |
| Validation, fingerprints, diff, migration, safe export | Stable |
| Runtime scheduling and model projections | Supported reference layer |
| Inference ledger, review, calibration, OOD, intake governance | Research / governed extension |
| Complete Excel execution compatibility | Not claimed |
| Production-safe automatic dependency inference | Not claimed |
Re-run on a clean runner on across Python 3.11, 3.12 and 3.13: 54 passed, plus the CLI smoke test and the distribution build.
The projection thesis
One structure is canonical. Everything else is a view of it.
MLF preserves the complete structure first. Sequence, tensor, graph, execution, and human views are reversible projections of that structure.
That is why the format stores routes as data rather than assuming row-major, keeps styles in their own file rather than mixing them into cells, and records what an import lost rather than presenting a clean result it cannot support.
Six layers
The architecture separates six concerns. The stable file format lives in L1–L3; the layers above 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.
The formula triple
Where a formula exists, MLF keeps three representations of it at once.
source expression
normalized AST
explicit dependency edgesDisagreement between the three is evidence and must be reported. No layer silently overwrites the others.
Identity is not location
A coordinate answers where a cell currently appears. A stable ID answers which semantic object the record represents. A transformation should preserve identity when a cell moves, and create a new identity when semantic identity changes.
Try it
Python 3.11 or newer.
python -m pip install -e .
mlfc --versionmlfc compile examples/input/sample.csv examples/output/sample.mlf --overwrite
mlfc validate examples/output/sample.mlf
mlfc inspect examples/output/sample.mlf
mlfc fingerprint examples/output/sample.mlfExport a separate safe projection — the source is never overwritten:
mlfc export examples/output/sample.mlf examples/output/sample.safe-copy.xlsx --target xlsx