feat(language): a partition names the value columns it groups by, so a relation may gain one without changing the call

[FBumann]

Prompt: I think we should fix 538 before we merge this and write it up properly at once. PRs should be stacked. First the fix, then the docs!

Note

The following content was generated by AI.

What this changes

within= is required whenever shift, sum_back or position names a by=. Closes #538. The docs PR #539 stacks on this one.

• shift and sum_back refuse a by= without within= by their call shape, the mechanism sum and at already use for over= and into=. position() refuses it at resolution, since its grammar stays permissive so that the message can name the rewrite.
• The refusal reads: shift() through a relation leaves within= unsaid. A partition names the value columns it groups by, so that a relation may gain a value column without changing what this call means. Write: …
• Every partition call in the tree names its group: two example models, the golden model, the tests and the hand-written pages. The generated pages and the golden outputs were regenerated. The typeset math does not move, so the three .out files are unchanged and the schema is unchanged.
• The break: a file with shift(…, by=cal) and no within= no longer loads. The refusal names the rewrite. No alias and no deprecation, per the alpha stream.

Why

Rule 3 of the rules agreed for relations says adding a value column is safe. It held for sum and at since #532 and failed for partitions, where an omitted within= meant every value column:

cal: { key: hour, values: day }          →  shift(p, along=hour, offset=1, edge=0, by=cal) grouped by ('day',)
cal: { key: hour, values: [day, week] }  →  the same call grouped by ('day', 'week')

Tests

Three refusal cases in tests/test_validation.py fail on main and pass here: a shift, a sum_back and a position that leave within= unsaid. tests/test_lowering.py gains a test that the same call groups by ('day',) on both calendars above once it names within=day.

Coverage that moved: no test asserted the old default in words. The tests that relied on it now name their group, one per call.

Gates

pixi cannot be installed here, since the egress proxy refuses pixi.sh, so the gates ran from a uv venv on Python 3.13.

gate	result
pytest -n auto	1298 passed, 6 skipped
ruff check, ruff format --check	clean
pyrefly check	0 errors
typos, prettier	clean
mkdocs build --strict	clean, with the unreachable docs.python.org inventory dropped for the run
tools.schema, tests.typesetting.golden, the four page generators	re-run; the schema and the .out files did not move
compile-tex	not run, for want of a TeX distribution
reuse lint, zizmor, taplo	not run; no new file, no workflow and no TOML changed

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q2gdGgMAdJ5ZVe8VM8tDTk

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34636717 | 📁 Comparing 9d486ca against latest (f4c4ec0)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• examples/operators/index.html
• examples/pypsa_multi_period/index.html
• reference/notation/index.html
• reference/language/dimensions/index.html
• reference/language/expressions/index.html
• reference/language/operators/index.html
• reference/math_spec/operators/index.html
• reference/math_spec/program/index.html