feat(language): a lookup says whether a key with no row was meant

[FBumann]

Prompt: "Doesn't a period to snapshot lookup need one to one?" — "But it might be a valuable one…? Related to #245?" — "How would the coverage look like on lookups? Per column, per key? Per value?" — "Do this as a stacked draft pr?"

Note

The following content was generated by AI. Stacked on #437; the base branch is its head. The lookup half of #245, restated for a relation with a key. The parameter half stays in #245.

What this changes

A keyed lookup takes coverage: total | masked, default total: every key tuple has a row, and the consumer that binds the table refuses one short of a key. masked says the gap is meant. A bare relation declares neither, and a bare where: on a total lookup is refused, since it masks nothing.

lookups:
  gen_bus: { over: [generator, bus], key: generator } # total: every generator is on a bus
  line_to: { over: [line, bus], key: line, coverage: masked } # an open end is meant
  zone_of: { over: [generator, period, zone], key: [generator, period] } # total over generator × period
  connection: { over: [generator, bus] } # no key, so no coverage: the rows it has

Per key, not per column or per value. The key is the one column set where "every tuple of the product has a row" is the claim anyone wants: it is the parameter rule one axis over, so total means the same on both blocks. Per column is weaker on a composite key, and per value column ("every period has a snapshot") is a claim about the other dimension's labels rather than about the table.

Two refusals, both decided by the file alone.

Lookup 'connection' declares no key, so nothing is there for 'coverage:' to be total over — a bare relation is the rows it has. Drop the coverage line, or declare key: for the columns each row is identified by.

Constraint 'wired': 'gen_bus' is total, so a row exists at every ['generator'] and the mask has no effect. Remove it, or declare coverage: masked on the lookup if a key may have no row.

The second follows the precedent of a bare dimension name in a where, which is refused for the same reason. It is the one decision here that could be dropped without touching the rest; say so and it goes.

What consumers see. LookupDeclaration.coverage is Coverage | None: total or masked for a keyed table, None for a bare relation, which answers for no coverage the way #245's block-owned parameters do. Namespace carries it too, since the where refusal reads it. coverage is not typeset, the precedent dtype sets, and the golden .out files are byte-identical.

Coverage moved. Four fixtures test the bare where: name form on a keyed lookup and now declare masked: the golden model's zone_of, the dimension tests' gen_bus and gen_zone, and the lowering test's zone_of. No example in examples/ uses a bare lookup name in a where, so none changed.

Every guard deleted in turn

Each on a clean tree at 31a6595, restored with git checkout -- and __pycache__ dropped on both sides; the tree came back clean and the suite at 1211 passed.

Mutation	Result
the bare-relation refusal never fires	2 failed, 1209 passed
the bare-where-on-total refusal never fires	1 failed, 1210 passed
the unwritten default flips to masked	9 failed, 1202 passed
lowering drops the coverage	2 failed, 1209 passed
a bare relation answers total instead of None	16 failed, 1195 passed

Verified

uv venv on Python 3.13 with ruff==0.16.1 and pyrefly==1.2.0; pixi is blocked here. On 31a6595 over the #437 head: pytest -q -n auto 1211 passed, 6 skipped (the two TeX compilers). ruff check, ruff format --check, reuse lint, prettier --list-different on every docs page: clean. mkdocs build --strict passes with the python.org inventory removed, which the proxy answers 403. Every generator re-run (tools.schema, tests.typesetting.golden, tools.notation, tools.gallery, tools.spec_math, tools.home_math); the schema and notation.md moved, nothing else. The two messages quoted above are the loader's own output on a model built to trigger them.

Not run: compile-tex; pixi run ci itself. pyrefly check reports 11 errors in this venv, the same 11 on the base branch (unused ignores and no yaml stubs), so they are the environment's. typos flags typ in five places, none of them in a file this PR touches.

Why

key: says at most one row per key tuple, never at least one. A snapshot with no period, a generator on no bus, are rows lost in preparation, and today the language reads each as "belongs to no group" and drops its terms from every sum silently. That is the data-safety hole cardinality does not close; totality does, and the two compose: a key plus total is a total function.

Stacked on #437 because that PR changes what "total" is over: a composite key is total over the product of its dimensions, and a bare relation has nothing to be total over, which is the refusal above.

🤖 Generated with Claude Code

https://claude.ai/code/session_016LDbfiWuoU2U8g8vV6iWq5

---

Generated by Claude Code

Superseeds #438 #430 #256

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34479006 | 📁 Comparing 31a6595 against latest (eac1930)

  🔍 Preview build  

24 files changed · ± 24 modified

± Modified

• CHANGELOG/index.html
• examples/operators/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
• reference/notation/index.html
• reference/language/absence/index.html
• and 14 more...