feat(program): a where mask answers its own questions — conjuncts, names, atoms and the dims it is read at

[FBumann]

Prompt: "Can we make the masking fully statefull using dataclasses like the other operators and declarations in Program? Changing what lives in .root?" / "I think we should do both."

Note

The following content was generated by AI.

A where mask reaches a consumer as a Mask that answers every question the language owns about it: .conjuncts, .names_read, .atoms as properties of .root, and .dims — the dimensions the mask is read at — stored, resolved at lowering, the one moment that holds both the predicate and every name's dims. Region.when arrives in the same carrier, so one helper covers every mask in a program. The free conjuncts() is retired to _conjuncts behind the property — one public door.

Built from main per instruction (the stack was abandoned): the two commits of #317 and #318 are cherry-picked here, so this PR supersedes both.

Why dims stops being a question the consumer answers (corrected after the consumer's review, superseded in shape by #324): dims_read(name_dims) required a name→dims mapping that the first consumer builds by hand today from public Program fields, and calls at three sites — a parameters+variables-only copy of the read-through rule that would silently narrow the answer the day an atom kind consulted the mapping for anything more. This PR stores the answer on Mask at lowering; #324, three PRs up the stack and on the same reviewer's proposal, moves it further — onto the leaves at resolution, making Mask.dims derived and this PR's stored field an intermediate shape that never survives to the end of the stack. Read this PR for Mask as the carrier and Region.when joining it; read #324 for where dims finally lives.

The trade, named: Mask is the program's first denormalized node — a hand-built Mask(root, wrong_dims) disagrees with itself and nothing validates it. In production only lowering builds one, so it cannot bite there; a test fixture that hand-builds declarations now supplies dims by hand, and a wrong set is a silent behavioural switch in whatever reads it. Free dims_read stays available for synthetic predicates (and enters program.__all__ in the stacked #321).

Verified

pixi run ci exit 0 in this worktree: lint clean, 930 passed, mkdocs build --strict builds, 27 TeX documents compile. schema/ and tests/typesetting/golden/ untouched — the typesetter runs off the Spec side and never reads program.Region.when.

Failing-first: with src/ stashed back to the unreworked tree, the new tests cannot even collect — TypeError: Mask.__init__() takes 2 positional arguments but 3 were given. The pins that pass on both trees (unmasked where is None, constraint where is a Mask, atoms-vs-conjuncts on a and (b or c)) close gaps mutation testing found in #318, where dropping _mask's None fold or collapsing atoms into conjuncts left the suite green.

Post-review: _Lowering carries name_dims as a cached_property, so a cases-heavy walk resolves the mapping once rather than once per cases: node — machinery #324 then deletes with the mapping itself. Do not land this PR without the rest of the stack: alone, it ships an intermediate shape.

Deliberately not done: relocating the resolved where-node vocabulary from where_parser into program — that is the stacked follow-up (#321), kept out so this diff stays the API reshape alone. conjuncts/names_read/atoms stay properties rather than stored fields: they are pure functions of .root and cannot disagree with it; only dims needs outside knowledge. One departure from the house dims: tuple[str, ...] style: Mask.dims is a frozenset because a mask restricts an unordered set of axes — declaration tuples carry axis order, a mask has none.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34333790 | 📁 Comparing 48979ca against latest (18644cd)

  🔍 Preview build  

4 files changed

± reference/language/reading/index.html
± reference/math_spec/lowering/index.html
± reference/math_spec/program/index.html
± reference/math_spec/where_parser/index.html

[FBumann]

Note

The following content was generated by AI.

Superseded by #327, which combines the reviewed stack into a single diff on the maintainer's call. The review history — two consumer reviews and one consolidated agent review, with mutation tables — lives in this stack's bodies; the tree at #327 is byte-identical to the stack's top.