feat(language): a file says what it reads, and fragments and patches compose into one model

[FabianHofmann]

Prompt: implement dev/composition/plan.md here on this branch. delegate each commit to a fable agent and let each commit reviewed by another fable agent and let the revisions of each review be implemented by another agent. when you are done, raise a pr

Note

The following content was generated by AI.

A file names what it reads under one closed given: key, math_spec.merge composes fragments into one model, math_spec.override lays patches over a base, and a component library under examples/library/ shows the three composing. This rebuilds the stack #505 → #520 on current main; it does not close #302, only its fragment half.

Eight commits: the plan's four, each followed by the commit that applies its review. pixi run ci is green on the final tree.

Decisions to read, not skim

• A fourth kind of construct in limits.md. given: is a declaration section, neither primitive, macro nor refused. How a new construct enters now lists four kinds.
• Eleven declaration keys. file.md, index.md rule 1 and the Spec docstring say so.
• advice kind given is a note. reading.md tells a consumer with no host to refuse. The two agree only if the consumer acts on the note.
• A program carries what it does not build; lowering does not refuse. Program.given holds GivenDeclaration(dims) per name.
• merge and override are two verbs. Peers and layers obey opposite laws. They compose as override(merge({…}), {…}).
• A patch cannot retire a dimension or relation, and a restatement must be equal. The reference stack let null remove an axis while its docs said an axis is never changed. The rule is now one thing in code and prose.
• A whole section set to null in a patch is refused. It was a silent no-op.
• A fragment cannot read what it builds. merge refuses it, so a composed model never hides a file that does not load alone.
• Silence is not version 0. merge omits version when no fragment declares it, and a silent fragment does not disagree with one that pins a version.
• A reader's schema default counts as said. A reader writing domain: continuous folds into an introducer that omits domain. Spec.to_dict() emits every default, so a Spec-loaded fragment needs this to merge at all.
• The composed objective sums in fragment-name order, with each term parenthesised. The reference summed in iteration order, so its result depended on the order of the fragments.
• Two patches that both add the same dimension identically are refused as an overlap. A known limit of the disjointness rule.
• description is prose and never a disagreement. The first author's wording is carried.
• A given variable prints no domain line and no bounds. The owner has them. It prints in the legend under Given.

Not done, on purpose

• render_tex compiles the three fragments under default symbols, because it finds a symbol table by model stem. The gallery pages use examples/symbols/library.yaml through symbols_for. Fixing it is a tools/ change of its own.
• The composed page's YAML is merge's return dumped by yaml.safe_dump, so its flow style differs from the hand-written fragments.
• The six refusals quoted on compose.md are read by nothing. To file after merge, as fix(language): a composition refusal calls a library file a fragment rather than a template #511 named.
• Not in scope, as the plan says: a shell verb, a provenance object, qualified names (chore(main): release 0.0.0-alpha.4 #29), given: parameters/dimensions, a binder.

Departures from Part 2 defaults

• tests/fixtures.override is renamed varied across eleven test files, so the verb owns the word. The plan counted nine.
• pyproject.toml allows the typo balnce; it is the did-you-mean input in the given tests.
• The kwarg given in typesetting/symbols.py is renamed upright, so given has one meaning in the tree.

Commit 1 — a file says what it reads under one given key (5ff1426, 84c7797)

model.py: GivenVariableBlock, GivenConstraintBlock, GivenBlock (closed, __bool__), Spec.given beside variables. A given variable joins the namespace collision check; a given constraint also under constraints: is refused; both frames join the dimension check; _names_are_names reaches into the two inner mappings. resolution.py, dimensions.py read the merged maps; the dual() refusal names given: constraints:. program.py: GivenDeclaration, GivenTargets (seals its own mappings), Program.given. advice.py: kind given; a dimension only a given frame indexes is reached. boundedness.py: a given column in the objective with no constraint naming it no longer crashes the unboundedness pass with a KeyError; this guard the stack lacked. Typesetting: Given legend group, given names choosable in the symbol table, typeset_declaration says a given name prints no line of its own.

Docs: declarations.md#given, file.md, index.md, reading.md What a program does not build (executed by test_reading_page.py), errors.md advice row, limits.md fourth kind and templates → fragments.

Mutation table (guard deleted, suite run, restored):

Guard	Failures
_names_are_names reaches into given	1
given constraint also built is refused	1
given variable joins the flat namespace	1
given frames join the dimension check	1
GivenTargets seals its mappings	1
advice kind given	4
dimension only a given frame indexes is reached	1
given column in objective skipped by the unboundedness pass	1
dual() refusal names given: constraints:	1
typeset_declaration names the legend for a given name	2

Schema regenerated; golden output unchanged.

Commit 2 — a patch file extends a model rather than a copy of it (bf9bfeb, e65969f)

composition.py with override(base, patches). A partial entry must land on a declaration the base has, with the near miss named. A whole entry creates. null at declaration level removes; a stale removal is refused. Sibling patches must write disjoint paths. A dimension or relation may be added or restated equally, never changed or removed. The objective is one declaration laid over by the same rules. Base and patches are deep-copied, never mutated. given: is laid over one kind at a time, entry by entry, reading the entry class off GivenBlock.model_fields. An unknown given: kind passes through for the closed schema to refuse at load.

Docs: docs/howto/compose.md with the recipe, What a patch may say, and each refusal quoted from a real run. Nav entry; limits.md link.

Guard removed	Failures
partial entry on nothing created anyway	5
stale removal ignored	1
sibling patches not checked for disjointness	4
dimension redeclared replaced	1
objective removal on none ignored	1
partial objective on none created	1
null at depth removes	2
given laid whole, not one kind at a time	2
given kind laid whole, not entry by entry	2
base and patches not copied	1
dimension removal refused	1
restatement compared for equality	1
null section refused	3

Commit 3 — fragments compose into one model, each reading what a sibling introduces (de802dd, 1da63b5)

merge(fragments, description=None) beside override, reusing its constants and helpers. dimensions/relations must agree with prose excluded. Every other name is owned and a second claim names both fragments. Objectives are summed in fragment-name order, each term parenthesised, senses must agree. Versions must agree where declared. A given declaration folds into its introducer when it says the same or less; two fragments that only read a name must read it the same way; a name nothing introduces stays under given:. A fragment that reads what it builds is refused. advice's given note names merge().

Docs: compose.md A library of components with two refusals from real runs; declarations.md#given folding sentences; limits.md states both verbs.

Guard removed	Failures
versions may differ	1
shared block disagreement not refused	2
prose compared as a claim	4
second claim of an owned name not refused	1
reader not checked against introducer	2
given never folded	5
schema default not counted as said	1
senses may differ	1
objective terms joined without parentheses	1
fragments not deep-copied	1
sorted objective terms	2
the read-what-it-builds refusal	2
the omitted version key	1

Commit 4 — a component library composes into one model, and each file prints alone (cea9efe, 16777b6)

examples/library/{surface,generator,load}.yaml, variants/commitment.yaml, examples/symbols/library.yaml. Components key to a port, so the balance is written once in the surface. tools/_page.py::tab moved out of home_math.py; tools/gallery.py renders the three fragments and a composed page with one tab per variant; render_tex.NOT_MODELS skips variants/. Five pages under docs/examples/library/, nav, .prettierignore, catalogue row. tests/test_library_example.py: nine cases, including that the balance in the merged model equals the surface's own, and that every variant has a tab on the committed composed page.

Gate

pixi run ci on 16777b6, exit 0:

lint         12 jobs pass (ruff, taplo, zizmor, pyrefly, typos, reuse, prettier, …)
test         1424 passed in 3.36s
docs-build   Documentation built in 2.90 seconds (--strict)
compile-tex  rendered 33 model(s), compiled 34 document(s)

Each of the eight commits was gated with pixi run lint, pixi run test and pixi run docs-build on its own tree. Each plan commit was reviewed by a second agent reading the full implementations and probing every rule; the following fix/docs commit applies that review.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34696755 | 📁 Comparing f314efc against latest (3317ecf)

  🔍 Preview build  

51 files changed · + 10 added · ± 41 modified

+ Added

• examples/library/index.html
• howto/compose/index.html
• howto/see-an-expansion/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html
• reference/language/assumptions/index.html
• reference/math_spec/composition/index.html
• reference/math_spec/sos/index.html

± Modified

• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• examples/commitment/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• howto/curve-by-hand/index.html
• and 31 more...

[FabianHofmann]

@FBumann it was complicated to rebase the stack pr #512 - #520 so I combined everything here from scatch to trigger a pr on linopy with the given feature

[FBumann]

@FabianHofmann Does this mean i can close my 6-PR stack?

[FabianHofmann]

@FabianHofmann Does this mean i can close my 6-PR stack?

yes, it does

[FBumann]

Perfect
I closed them

[FBumann]

Superseeded by #690 and #691