feat(language): fragments add terms to a named expression that its reader marks as a sum, and merge sums them

[FBumann]

Prompt: "Then retry. Iterate until the split is clean, reasonable and its easy to add new features via a fragment."

Prompt: "What do you think of this idea? Then the flag on the reader's given: entry is the design. It is the only statement the language needs, and the regular blocks stay as they are." (and the follow-ups that settled the frame rule, the kept entry and where each check runs)

Note

The following content was generated by AI.

A given: expressions: entry marked additive: true says the name is a sum other files add terms to. Each contributor declares an ordinary named expression under the name, and merge sums them and keeps the marked entry.

Stacked on #728. The whole design is presented in #723.

What this changes

• The reader marks the sum. additive: true on a given: expressions: entry, beside its dims. The entry's description is the sum's. Only one file has to mark a name; other readers state the frame and nothing more, and where two entries meet the frame is compared as a set and the flag comes from either.
• A contributor is an ordinary named expression under that name, with no flag and no copied prose. Alone it loads over its own term.
• One rule, three cases. A pure reader carries the marked entry and no term. A plain contributor carries a term and no entry. A file that carries both (a hub that adds a term of its own, or a composed model) reads the sum so far. In that form two things are checked at load: the term carries no dimension the entry does not state, and the term is one expression:, not cases:. Lowering folds the entry into the definition, as ExpressionDeclaration.additive, and leaves it out of program.given.
• merge sums every declaration of a marked name, each in parentheses, in fragment-name order, and keeps the marked entry, so a later merge adds more. It refuses:
  • a term written as cases:, since nothing at load says a plain contributor is one; the message says to name the cased term and add the name;
  • a term over a dimension the marked entry does not state, both named;
  • a file that declares a term and reads the name without carrying the marked entry, with one term or several, since alone it reads its term and composed it would read the sum.
• A name two fragments declare and no entry marks is refused as a collision, as before, and the message now says a sum needs a given: entry marked additive: true.
• A marked name no file adds to stays under given:. Zero would leave the reader's row with no variable, which the language refuses.
• A composed objective keeps the first description a fragment gives it. It was dropped before.
• Typesetting: the legend says "a sum other files add terms to", under Given for a pure reader and under Definitions once the entry folds into a definition.
• Docs: a "sum other files add to" section under given: expressions in declarations.md, a row in compose.md, a sentence in reading.md.

Why

In the PyPSA model, seven expressions and two rows sum one term per component. The file that owns each lists every component, so a new component edited four other files. Marking the sum on its reader puts the one statement on the file that gives the sum its meaning, and the one that should be present. Leaving that file out now collides instead of merging silently into a sum nothing reads. Every contributor stays an ordinary expression: in #723 the split drops 40 flag lines and 31 copied descriptions and gains 9 marked entries.

Guards, gates, choices, what was not done

This replaces the first design of this PR, which put additive: true on every share, as a field of the named expression. That design refused a self-reading share only once two shares existed, left a missing reader silent, and copied each hub's description into every share. The review that led here is in #723.

Guards, each deleted in turn, the suite run, the tree restored:

Guard	Failures
merge: a term written as cases:	1: test_a_cased_contributor_is_refused_by_merge
merge: a term over more than the sum	1: test_a_term_over_a_dimension_the_sum_does_not_state_is_refused_by_merge
merge: a contributor reading the sum	2: test_a_contributor_that_reads_the_sum_without_the_entry_is_refused[beside-another-term], [as-the-only-term]
merge: the terms of a marked name are not claimed	12, including test_merging_sums_every_term_of_a_marked_name_in_fragment_name_order
merge: the marked entry is kept	5, including test_a_composed_model_takes_more_terms_in_a_second_merge
merge: two readers agree on the frame	1: test_two_readers_that_disagree_about_the_frame_are_refused
merge: the collision names the fix	1: test_two_terms_and_no_marked_reader_collide_and_the_message_names_the_fix
load: a cased term beside the marked entry	1: test_a_cased_term_beside_the_marked_entry_is_refused_at_load
load: a term over more than the sum	1: test_a_term_over_a_dimension_the_sum_does_not_state_is_refused_at_load
lowering: a defined sum leaves program.given	2, including test_a_file_may_add_a_term_and_read_the_sum_when_it_marks_it

tests/test_additive.py holds 24 cases, rewritten for this design before the code; 14 failed on the tree before merge changed.

Gates, in a Python 3.12 uv virtualenv, on a98ad6c:

pytest tests -n 8                       1812 passed, 7 skipped
ruff check . / ruff format --check .    clean
pyrefly check                           0 errors (9 suppressed)
typos . / reuse lint                    clean

Not run: compile-tex, mkdocs build --strict (the proxy refuses the docs.python.org inventory), zizmor, taplo.

Choices.

• The flag is on the reader's given: entry, not on each term: one statement, on the file that gives the sum its meaning.
• The kept entry is the general form, not an exception to "a name declared and given is refused": a marked entry beside a declaration means the declaration is the sum so far.
• A term's frame is a subset of the entry's dims, not their union: a reader's row may carry a dimension through another term, and the composed load refuses a row that would repeat. feat(language): a fragment reads a parameter or a named expression another file declares, under given: #728 uses the same rule for a single definition.
• A share prints =: in any one model the expression is the sum of the terms that model has.
• A contributor read alone does not say it is a term. The file loads as it reads.

Not done. No CHANGELOG.md line, for the reason given in #728.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sr4SCw5A7GUF5ARhdCaKR1

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34761193 | 📁 Comparing a98ad6c against latest (188262a)

  🔍 Preview build  

50 files changed · + 8 added · ± 39 modified · - 3 deleted

+ Added

• CHANGELOG/index.html
• first-model/index.html
• 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

± Modified

• 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/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• and 29 more...

- Deleted

• changelog/index.html
• first-spec/index.html
• about/versions/index.html

[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