MMLF 1.0

The document is the program.

MMLF is a typed YAML or JSON document that is simultaneously the input, the program and the audit subject. Version 1.0 freezes its surface and its computational semantics.

Stability rule

MMLF 1.0 freezes the document surface and computational semantics implemented by Runtime 0.9. Runtime 1.x may add optional backward-compatible fields. An incompatible semantic change requires MMLF 2.0 and a migration path — it does not get to arrive in a minor release.

A whole document

This is the stable example the CI runs on every commit. Four root fields are required; everything else is optional and additive.

yaml

format: MMLF
version: "1.0"
ledger_id: mmlf-v1-stable-demo
metadata:
  title: Stable MMLF 1.0 arithmetic demo
  authors: [Neo.K]
  license: Apache-2.0
objects:
  - id: source-three
    type: real
    value: 3
branches:
  - id: add
    source_id: source-three
    base: 3
    operator: add
    operand: 2
    expected_result: 5
  - id: multiply
    source_id: source-three
    base: 3
    operator: multiply
    operand: 2
    expected_result: 6
layout:
  - [add, multiply]
traversals:
  display: [left_to_right, right_to_left]
  execute: dependency_topological
audit_policy:
  local_required: true
  signed_global_cancellation_allowed: false
  numeric_tolerance: 1.0e-12

Note traversals. Display order and execution order are declared separately, because reading a matrix left to right and executing it in dependency order are different questions about the same object.

Note expected_result too. The document states what it believes the answer is, which is what makes a local audit possible at all — the runtime has something to disagree with.

Optional sections

Each of these switches on one capability layer. A document that omits them all is still valid, and executes as deterministic arithmetic with local audit.

Section	Turns on
`metadata`	title, authors, licence, migration provenance
`objects`	typed sources a branch can draw from
`layout`	the matrix arrangement
`traversals`	display and execution order, declared separately
`audit_policy`	what counts as a failure, and at what tolerance
`evaluation_scenarios`	substitution scenarios over symbolic values
`constraints`	row, column, block and region conditions
`fixed_point_groups`	iterated groups with convergence contracts
`corrections`	append-only corrections, never in-place edits
`fdcs`	counterfactual interventions, uncertainty, decisions
`boundary_events`	declared events at the model boundary

Migration

Documents from 0.1 through 0.9 still load and still execute according to their declared version. Migration to 1.0 is a separate, verified operation.

bash

mmlc migrate examples/four_operations.yaml \
  --output migrated/four_operations_v1.yaml

Validate the source document using its original schema.
Canonicalize legacy syntax.
Write a stable MMLF 1.0 document.
Preserve the original semantic feature profile through metadata.
Validate the migrated document.
Execute source and target deterministically, and compare a version-independent snapshot.

Step four is the one that matters. A migrated document carries metadata.migrated_from, and the runtime executes it according to that recorded profile.

declared

migrated_from is operational, not decorative. Without it, migrating a v0.5 document to the 1.0 surface would silently activate execution semantics that did not exist when the document was written.

Across the release validation, 40 examples were migrated and 12 migration-equivalence cases were checked, with zero failures.

Shape versus semantics

Two different checks run, and conflating them is how a document passes validation and then fails to mean anything.

JSON Schema: Validates document shape.
Runtime validation: Additionally checks IDs, layouts, references, operator domains, dependency cycles, intervention conflicts, fixed-point contracts, and feature-specific invariants.

All schemas ship inside the installed Python package under mmlc.schemas, so validation behaves identically from an editable install, a wheel, a source distribution, or a normal installed environment.

Canonical values

MMLC preserves exact fractions and symbolic values where supported. Output serialization uses canonical tagged representations rather than quietly casting everything to floating point — which is the difference between a ledger you can audit and a ledger that is approximately right.