feat(language): a parameter says whether its table must cover every coordinate, so a row lost in preparation is not read as a mask

[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

parameters: takes coverage: total | masked, default total. A parameter declaring itself a mask is refused as a bound or a divisor — the two positions rule 8 gives absence no reading — before any data arrives.

parameters:
  cost: { dims: [generator] } # total: every generator has one
  ramp_limit: { dims: [generator], coverage: masked } # no row means no limit

Why

A table short of a coordinate and a table that never had one are identical in the data and mean opposite things. lpspec says so, and says it cannot decide:

sparse_parameters … reports rather than judges: a table that lost a row and a where: that removed one build the same model, and nothing else would say which parameters could be either.

That is a precise statement that the information is not in the file. Rule 8 gives absence a reading; nothing gave it a permission. This is the permission, and once declared the reporting can start judging.

What lpspec removes or changes

The one of the three with real downstream work.

• Gains a bind-time check. sources.py refuses a total parameter short of a coordinate its dims reach — a DataError naming parameter and coordinate. Today that is countable, not reportable.
• diagnostics().sparse_parameters narrows and loses its caveat. The "could be either" sentence is exactly what this key removes. It stays useful for masked parameters; for total ones the row becomes an error.
• The ports corpus migrates. Deliberately-sparse parameters in examples/ports/*.yaml and differential/pypsa/ need coverage: masked, as this PR does to math-spec's own examples. Mechanical — they are the ones whose descriptions already say "no value means …".
• Unchanged: curves.py, shape recognition, both lanes' compilers.

Verified

Toolchain reconstructed at the versions pixi.toml pins, run on this branch: ruff format --check / ruff check (0.16.1, pinned) clean; pyrefly (1.2.0, pinned) 0 errors; reuse compliant; typos clean; prettier clean; pytest -q -n auto 837 passed, 1 skipped (829 on the base — 8 new); mkdocs build --strict builds, and Read the Docs built the PR for real.

schema/math-spec.schema.json regenerated with python -m tools.schema (+9 lines); test_schema.py green.

Not run: zizmor, taplo (neither's files changed), compile-tex — coverage is not a rendered attribute and the golden typesetter tests are green, so this branch's LaTeX is byte-identical to its base's.

Mutation table

Both guards deleted in turn on a clean tree, restored with git checkout --, __pycache__ dropped both sides. tools/mutate.py expresses neither (a deleted call; a deleted dict update), so both were taken by hand.

Mutation	Result
the guard is never called	4 failed
the divisor arm dropped, bounds still checked	2 failed
restored	833 passed (837 once the typst extra was installed)

The second is the one that matters: bounds are the obvious position, divisors the one a reader forgets, so a guard catching only the first would look right.

The permissive half is tested too — masked as a coefficient, a term and a where all still load. A guard refusing those would refuse the construct the declaration exists to describe.

The decision worth arguing about

The default. total breaks nothing here (this repo binds no data) and is what the other rules assume — but it is the whole downstream cost, and reversing it later is not free: ship masked as the default and every existing model silently means "sparsity allowed", after which total can only arrive as a per-file opt-in forever. One line in model.py plus eight example declarations if you want it the other way. Worth settling before there is a corpus, which is why it is here rather than buried in the diff.

Stack: second of three, on #242.

Relates to #296 (parameter coverage; #245 covers lookups)

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34348743 | 📁 Comparing 200b831 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

[FBumann]

Note

The following content was generated by AI.

Closed in favour of #245, which now carries both halves of #296 as one PR.

#296 proposes coverage: on parameters: and lookups: sharing one vocabulary; this PR and #245 were that one issue written in two sittings. Keeping them apart also meant publishing ParameterCoverage on the program surface for exactly one release, since #245 renames it to Coverage.

No coverage is lost: the commit from this branch is unchanged in #245 (1bb17a0 + 200b831), tests included.

Branch claude/parameter-coverage is left in place for now, since #244 and #249 are still based on it.