feat(program): a model is a document another language can read, so a second consumer needs no second parser

[FBumann]

Prompt: "Please add a pr that is visionary regarding the best and most capable api which stays safe and predictable."

Note

The following content was generated by AI.

What this changes

Two verbs, and the API stops being Python-shaped.

document = ms.to_json('dispatch.yaml')  # or a Spec, or a Program you already hold
ms.from_json(document) == ms.to_program('dispatch.yaml')  # True

A consumer written in Python imports Program and is done. A consumer written in anything else has had exactly one route to the same model: implement the language a second time — a second parser, a second name resolution, a second dim algebra. That is the one thing hard rule 1 exists to forbid, and shipping the waist only as importable Python quietly guaranteed it.

Everything in a program is already resolved, so the document carries no grammar, no expression strings and nothing to parse. A reader dispatches on a tag and builds a node.

Why this and not another verb

The companion page in #246 argues that capability here is measured on the far side — what a second consumer can build, not what a caller can call — and names this as the largest capability the API can gain, precisely because it is not a feature. One serialisation, and every non-Python consumer becomes possible without a line of language reimplemented. Nothing else on any list multiplies like that, and it adds nothing a caller must learn.

This PR is that argument cashed. It also settles the decision I flagged as needing to be made before there are readers, not after: what a consumer does with a document it does not understand.

Safe and predictable, concretely

Reading is closed. A tag names a class in a registry built by reflection over the two modules that define nodes. Nothing is imported, evaluated, or constructed by name from the document — a hostile document can name a node that does not exist and get an error, and cannot name anything else at all.

Refusal is by name, never by guess.

this document names a node 'Sumk', which is not one this release has. Did you mean 'Sum'?

this is a program document at wire version 1, and this release reads 0. The wire version
moves when the encoding changes, so a document from a newer release is not one to guess at
— read it with the release that wrote it.

WIRE_VERSION is the format's own and moves when the encoding changes, not when the language does — the two version things that would otherwise be conflated.

The encoding is reflective, so it cannot go stale. A node added to the program is serialisable the day it exists, with no table to update. And tests/test_program_nodes.py already refuses a node no file lowers to, so the round trip covers every node by construction rather than by a list somebody keeps in step.

It is exact, not approximate. Round-tripped against the every-node fixture and every model in examples/ — equality on the Program, field for field, because a consumer trusting this document instead of the language has nothing to compare a subtly different field against.

The landmine, which is not exotic

allow_nan=False, and it costs something real. An unbounded variable's bound is -inf — so every model with a one-sided bound contains a non-finite float, and the obvious encoding writes Infinity, which is Python's extension and not JSON. A reader in a language with a strict parser would have stopped on the first realistic model.

Non-finite floats are written {"$": "float", "value": "-inf"}, and there is a test per shipped model asserting no Infinity or NaN appears and that json.loads accepts it.

What lpspec removes or changes

Nothing today, and something worth having tomorrow.

Nothing, because lpspec imports math_spec and reads the Program directly; this adds a route it does not need.

Worth having, because the two lanes are differentially tested against each other and both consume the same resolved AST — which ceiling.md already names as the gap: "a shared misreading passes the differential suite green." A document is what lets a third consumer, in another language, be compared against both. The examples/ports/ corpus exists for that class of bug; this is what would let it be checked from outside Python.

It is also what a Julia or Rust reader needs before it can exist at all, which is the adoption question rather than a code one.

Verified

Toolchain reconstructed at the versions pixi.toml pins: ruff format --check / ruff check (0.16.1, pinned) clean; pyrefly (1.2.0, pinned) 0 errors; pytest -q 885 passed, 0 skipped (858 on the base — 27 new). reuse, typos, prettier --check, render_tex (27 models) and mkdocs build --strict were run on the top of the stack (#250), which contains these commits.

The new reading.md section is executed, not just written: tests/test_reading_page.py runs every Python block on that page against a real model and checks every # value line. The round-trip claim there is one of them, which is why the page's claim count moved from 7 to 8.

Not run: zizmor, taplo (neither's files changed), and the tectonic half of compile-tex.

Mutation table

Each guard broken in turn on a clean tree, restored with git checkout --:

Mutation	Result
non-finite floats written raw, so Infinity leaks	20 failed
the wire version is never checked	1 failed
an unknown tag is silently ignored	15 failed
arrays decode as lists rather than tuples	13 failed
restored	all green

The last one is the reason the round trip asserts equality rather than resemblance: a list where a tuple belongs compares unequal and changes nothing you would see by reading a document.

Deliberately not done

No conformance corpus shipped as a fixture directory. The round-trip tests are the corpus, and committing generated documents beside them would be a second copy to regenerate — better once there is an external consumer to hand them to, which is when their shape will be known.

No schema for the document. A JSON Schema of the wire format is derivable from the same reflection and would be the natural next thing for a non-Python reader; it is not needed to write one, and guessing at its shape before a reader exists is what this repository calls YAGNI.

WIRE_VERSION is 0 and the language version is untouched. They answer different questions and this PR deliberately does not couple them.

Changed in review. _registry() is @cached and _decode no longer threads it through every recursive call — the reflection is per-release, not per-node, and the parameter was six mentions buying nothing. The one thing that did not survive the same pass: folding _encode's inline isinstance(value, tuple) and hasattr(value, '_fields') into _is_named_tuple loses the narrowing pyrefly needs to accept value._fields, so the apparent duplication is earning its keep and stays.

Stack: sixth, on #246 → #245 → #244 → #243 → #242 → #168.

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34316873 | 📁 Comparing c1d5a2e against latest (a9237ec)

  🔍 Preview build  

25 files changed · + 6 added · ± 19 modified

+ Added

• about/what-counts-as-a-verb/index.html
• examples/commitment/index.html
• examples/composed/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/merge/index.html
• reference/math_spec/serialisation/index.html

± Modified

• examples/index.html
• reference/notation/index.html
• reference/language/declarations/index.html
• reference/language/dimensions/index.html
• reference/language/expressions/index.html
• reference/language/file/index.html
• reference/language/reading/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/expression_parser/index.html
• reference/math_spec/lowering/index.html
• and 9 more...

[FBumann]

Not in scope for now