feat(language): merge and override load every model they compose and return one

[FBumann]

Prompt: Merge and override should always go through tospec

Prompt: And yes to making null the removal/default everywhere

Note

The following content was generated by AI.

merge loads every fragment and override loads its base with to_spec. Both return a loaded Spec. A null in a patch makes what it names absent: a declaration is removed, and a field takes its default. A merged model also keeps its fragments' assumptions:.

The base branch is #571 rebased onto main (claude/loving-thompson-vurdqx). This PR is the three commits on top of it.

What this changes

• merge loads each fragment with to_spec before it composes them. A fragment that does not load on its own is refused under its own name, followed by the refusal to_spec gives. A sibling can no longer make a broken fragment load.
• override loads the base the same way. A patch is not a model, so it is laid over as written, and the result is loaded.
• Both return a Spec, not a mapping. to_spec(merge(…)) is now merge(…).
• null in a patch makes what it names absent. A null on a declaration removes it, as before. A null on a field drops the field, and the field takes its default when the patched model loads. bounds: {upper: null} opens the bound, and domain: null gives continuous.
• Assumptions are kept. A merged model keeps its fragments' assumptions:. They were dropped without a word, because composition.py listed the sections it owns by hand. The list is now read off the schema.
• Removed: _reads_only_what_it_does_not_build (to_spec refuses such a fragment), and the lookup that counted a schema default as said (every fragment now arrives through to_dict() with its defaults written out).
• The how-to, the composed example page (regenerated), limits.md and the tests move with it.

Why

• A fragment is a whole model. With given:, a fragment loads, typesets and gets advice on its own. Loading it before composing makes that promise hold by construction. Before, a fragment that used a dimension it did not declare was refused alone and loaded once merged.
• One door. A composed model passed through to_spec in every caller anyway. Returning the Spec removes a step each caller could forget.
• null means absent. A null on a field was laid as a value, so bounds: {upper: null} built a model the schema refuses, and a patch could not open a bound. feat(language): a bound is null where it is open, never infinite, in the file and in the program #689 makes null the default of a bound in the file too, so the value a patch writes and the default it falls back to are the same. Where the schema already took null, as for where:, the result does not change: every field that accepts null defaults to it.

Guards, gates, behaviour moved, what was not done

Each guard deleted in turn, suite run, tree restored:

Guard	Failures
fragments not loaded	28, including test_a_fragment_that_does_not_load_on_its_own_is_refused
base not loaded	6, including test_a_base_that_does_not_load_is_refused_though_a_patch_would_mend_it
result not loaded	15, including the null-field cases
two versions not refused	test_fragments_written_against_two_language_versions_are_refused
owned sections listed by hand	test_every_section_a_fragment_owns_reaches_the_composition
null on a field laid as a value	test_a_null_field_takes_its_default[a-bound-two-levels-down], [a-field-that-takes-no-null]
null on a top-level field laid as a value	test_a_null_field_takes_its_default[a-top-level-field-that-takes-no-null]

The assumptions test and the null-field bound and domain cases were written first and failed on the tree before the fix.

Coverage that moved:

• The fixtures that read flow without declaring it now declare it under given:, because a fragment has to load on its own.
• test_a_fragment_that_reads_what_it_builds_is_refused now asserts to_spec's refusal under the fragment's name.
• test_a_version_no_fragment_pins_is_left_out is deleted, because a loaded model always carries a version. The version refusal is tested by standing up a second supported version with monkeypatch, since this reader knows only 0.
• test_the_result_shares_no_declaration_with_the_base_or_the_patch is deleted, because the result is a new validated model by construction.
• Assertions on the returned dict read the Spec instead.

Behaviour a reader sees. The composed example page prints the model as Spec.to_dict() writes it, so defaults such as version: 0, dtype: float and domain: continuous now show. The refusals quoted on compose.md were produced again by running each case. "A name one fragment both builds and reads" is now "A fragment that does not load on its own".

Gates run. pixi run lint passes. pixi run test: 1752 passed before the null commit, and the suite is green after it. mkdocs build shows no warnings except one: this sandbox cannot fetch the docs.python.org inventory, which fails --strict. render-tex rendered 34 models.

Not run. compile-tex: the tectonic bundle download is blocked here.

Not done.

• A given frame is still compared as a list, so [g, t] against [t, g] is refused as a disagreement.
• Program.given still drops the domain a file states.
• specsolve still needs to refuse a program whose given is not empty. That check needs a math_spec release that carries given.

Departure from a default. The branch stacks on a rebase of #571 instead of on main, because composition.py exists only there.

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34754427 | 📁 Comparing 4ff3483 against latest (9c7c0a5)

  🔍 Preview build  

64 files changed · + 10 added · ± 30 modified · - 24 deleted

+ Added

• first-model/index.html
• examples/library/index.html
• howto/compose/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/program/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html

± Modified

• index.html
• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• about/what-counts-as-public-api/index.html
• examples/pypsa/index.html
• howto/check/index.html
• howto/curve-by-hand/index.html
• and 20 more...

- Deleted

• about/file-and-program/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/boundedness/index.html
• reference/math_spec/degree/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/expansion/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/model/index.html
• and 14 more...

[FBumann]

Prompt: "I think we should close all superseeded ones that are from me (FBumann), and name what superseeded them "Superseeded by #xyz""

Note

The following content was generated by AI.

Superseded by #732.

---

Generated by Claude Code