docs(language): the rules binding obeys belong to the language, not to whichever engine reads the data

[FBumann]

Prompt: "Please do a few stacked PRs implementing this / All stacked onto the cases pr / And to the description, add what lpspec removes or changes"

Note

The following content was generated by AI.

What this changes

Three facts decide which model a file and a table make together. Each is real, each is load-bearing, and each was written down in a consumer rather than in the language — so a second consumer would inherit none of them.

Rule	Where it was stated
A dimension's own source supplies its members	lpspec/sources.py::check_index_ownership
Their order is that source's order, not sorted	the same docstring, and unique(maintain_order=True)
One row per coordinate	lpspec/sources.py, as "by contract"

Docs only, 2 files, +38/-3.

Why

what-counts-as-language.md already decides it: "A consumer may not state a rule about the language that another consumer then has to restate."

The order rule is the one with teeth. shift, sum_back and position() all walk it, so a Julia consumer reading only the language reference could reasonably sort — and answer shift(p, over=snapshot, offset=1) with a different row, silently, with no error anywhere. #32 notes "nothing in a file says they arrive sorted"; this says what does.

What lpspec removes or changes

Nothing behavioural. unique(maintain_order=True) already is the rule. What changes is who speaks: check_index_ownership, _labels / polars_index and the "by contract" comment stop stating rules and start implementing ones the language states. Can land any time after this — nothing breaks while both say the same thing.

Verified

pixi is unavailable here, so the toolchain was reconstructed at the versions pixi.toml pins and run directly on this branch: ruff format --check and ruff check (0.16.1, the pinned version) clean; pyrefly (1.2.0, pinned) 0 errors; reuse lint compliant 196/196; typos clean; prettier --check clean; pytest -q -n auto 829 passed, 1 skipped; mkdocs build --strict builds.

The strict docs build is the gate that matters for a docs PR. It aborts locally on Couldn't load inventory https://docs.python.org/3/objects.inv … 403 Forbidden — the sandbox proxy refusing an outbound fetch, not a content error — so I dropped that one config line for a local run and restored it (mkdocs.yml is unchanged in the diff). Read the Docs then built the PR for real, inventory fetch included, which is the stronger evidence.

Not run: zizmor (no workflow changed), taplo (no TOML changed), compile-tex (no model file changed).

Deliberately not done

Not made an eleventh rule. These arguably belong in the ten-rule table in reference/language/index.md. Renumbering "the ten rules" is an editorial decision about the front door and it is yours — two lines if you want it.

No enforcement here, because there is nothing to enforce without data. Message constructors not moved: the sentences these rules print still live in lpspec/sources.py, and moving them needs an errors.py addition here first.

Stack: base of three, on #168 — which is behind main (based on #211, main at alpha.47), so the stack rebases when that lands.

Closes #295

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34348742 | 📁 Comparing f488380 against latest (a9237ec)

  🔍 Preview build  

40 files changed · + 2 added · ± 37 modified · - 1 deleted

+ Added

• examples/commitment/index.html
• reference/math_spec/exclusivity/index.html

± Modified

• index.html
• CHANGELOG/index.html
• examples/index.html
• about/ceiling/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• examples/pypsa_quadratic/index.html
• examples/pypsa_stochastic/index.html
• and 27 more...

- Deleted

• reference/math_spec/where_parser/index.html