feat(language): a file says what it reads under one given key

[FBumann]

Prompt: "Decided with @FabianHofmann: Move all about given into a top level key."

Note

The following content was generated by AI.

What this changes

Two top-level keys become one, closed at two kinds:

given:
  variables:
    Port_p: { dims: [snapshot, port] }
  constraints:
    Bus_nodal_balance: { dims: [snapshot, bus] }

The loaded objects follow the file, so the schema is the shape a reader sees: Spec.given.variables, Spec.given.constraints, and Program.given.variables / .constraints on a GivenTargets. The declaration keys go from twelve back to eleven, which is one fewer than the count #507 asks you to accept.

Both types keep their own blocks (GivenVariableBlock, GivenConstraintBlock) — only where they sit moved. given: itself takes those two keys and nothing else:

given: unknown key 'parameters' in a given block. Valid keys: constraints, variables.

Everything that moved

Where	What
model.py	GivenBlock holds both mappings; Spec.given replaces the two fields; the collision walk and the frame walk read through it
program.py	GivenTargets holds both, sealed as every other group is; Program.given replaces the two fields
composition.py	GIVEN_SECTIONS becomes GIVEN_KINDS, which maps the key inside given: to what one entry is called. The key is the owning section's name too, so section.removeprefix('given_') is gone
lowering.py, resolution.py, dimensions.py, advice.py, typesetting/	every read is schema.given.variables or schema.given.constraints
examples/library/	generator.yaml and load.yaml declare given: variables:
docs	declarations.md is one ## given section with two subsections, and the anchor #given is what the other pages link

_agreed now takes the label for what one entry is called, because the same helper folds the coordinate space and the given kinds, and only the caller knows which. _lay_over gained a given branch: a patch is laid over one kind at a time, so patching the columns a file reads cannot drop the row families beside them.

Verified

Same environment as the rest of the stack: python 3.13, dependencies by pip, not the pinned solve.

• pytest -q — 1367 passed, 6 skipped (1365 on fix(language): a composition refusal calls a library file a fragment rather than a template #511's head, so 2 new; every other test moved with the rename rather than being added).
• python -m tools.schema regenerated; the diff is GivenBlock added, the two top-level properties replaced by one $ref. python -m tools.gallery regenerated the four library pages. The golden typesetter output does not move — the golden model reads nothing.
• mkdocs build --strict builds, after the usual local drop of the CPython inventory this proxy 403s. The built page carries id="given", id="given-variables" and id="given-constraints", and both inbound links resolve to #given.
• ruff format --check ., ruff check, typos, prettier clean. render_tex renders 34 models.
• Sentence length on the pages this touched, median and count over 25 words: declarations 13/10, file 11/2, limits 17/26, howto/compose 14/4. This diff changed four sentences on those pages.

Not run: reuse, zizmor, taplo, and compile-tex's tectonic half.

Mutation table

Two guards are new here, and each is caught by the test written for it.

Mutation	Result
_lay_over replaces given: whole rather than a kind at a time	1 failed — test_a_patch_over_one_kind_of_given_leaves_the_other_alone
GivenBlock is open rather than closed	2 failed — test_given_holds_two_kinds_and_refuses_a_third, and the schema drift test
restored	1367 passed

Deliberately not done

• No third kind. given: is closed at variables: and constraints:; parameters or dimensions enter the day something reads one, and until then the schema's own error names what is valid.
• No alias for the old spelling. The project holds no compatibility promise, and the closed schema's refusal is the whole migration story.
• Not folded back into feat(language): a component template loads and prints as math on its own #507 and feat(language): math can be layered onto a model built elsewhere #508. Those two PRs still introduce the flat keys, and this one moves them. Doing it in place would have meant rewriting two PRs and merging forward through three more; you chose the separate PR.

Stack: on #511 → #510 → #508 → #507 → #505.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CA5v9XJvgYViUHP7hSiKPU

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34613389 | 📁 Comparing cce70c6 against latest (bc1d9d4)

  🔍 Preview build  

23 files changed · + 7 added · ± 16 modified

+ Added

• examples/library/index.html
• howto/compose/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html
• reference/math_spec/composition/index.html

± Modified

• CHANGELOG/index.html
• examples/index.html
• about/limits/index.html
• reference/language/index.html
• reference/language/declarations/index.html
• reference/language/file/index.html
• reference/language/reading/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/lowering/index.html
• and 6 more...