refactor(program): a program names its nodes by the naming rule and its groups as the file does

[FBumann]

Prompt: "I landed 565

Lets land as much of 580 on main now as possible!! In adifferent branch and PR!"

Note

The following content was generated by AI.

Every public name in math_spec.program follows the naming rule in docs/contributing.md, that rule now states what it actually governs, and a relation is read from the program the way the file declares it. Nothing the language accepts, refuses or prints changes.

This is #580 on main, without the two renames that need #566. It is a break, described here because the alpha stream refuses the marker. Eighteen public names go and sixteen arrive.

What this changes

Predicate nodes. The Node suffix marks the core AST, and the program uses bare names. The where vocabulary carried the suffix.

Was	Is
AndNode	And
OrNode	Or
NotNode	Not
BooleanLiteralNode	BooleanLiteral
ParameterDefinedNode	ParameterDefined
VariableDefinedNode	VariableDefined
ParameterComparisonNode	ParameterComparison
DimensionComparisonNode	DimensionComparison
DimensionPositionNode	DimensionPosition
RelationComparisonNode	RelationComparison
RelationPairComparisonNode	RelationPairComparison
RelationDefinedNode	RelationDefined

Unions

Was	Is
ExpressionNode	Expression
WhereNode	Predicate
TypedPredicateNode	TypedPredicate
ConnectiveWhereNode	Connective

Expression nodes and their fields

Was	Is
At	Pullback
Window	WindowSum
Translate.dimension	Translate.along, the keyword shift takes
Window.dimension	WindowSum.along, the keyword sum_back takes

Program and declarations

Was	Is
Program.named_expressions	Program.expressions, the file's own expressions: section
Program.expressions, the objective and both sides of every constraint	Program.roots
Program.relations, a property built from the per-dimension nesting	Program.relations, a field: a Mapping[str, RelationDeclaration] keyed by name
DimensionDeclaration.relations	gone; DimensionDeclaration carries dtype alone
RelationDeclaration(name, columns, key), a NamedTuple	RelationDeclaration(columns, key), a frozen dataclass; the name is its key
Direction, a NamedTuple whose name read off the relation	a frozen dataclass carrying name as a field
Partition, the same	the same
Direction.is_function_read	gone; a local of the one resolution call that asks it
Footprint.shapes	Footprint.kinds

Deleted

Was	Now
Expression base class, with __add__ and __mul__	the nodes share no base; Expression is the union. Build Add(a, b), Multiply(a, b)
Program.dimension(name)	program.dimensions[name]
Program.parameter(name)	program.parameters[name]
Program.variable(name)	program.variables[name]

The naming rule itself. docs/contributing.md said a node names the coordinate map rather than the operator. That describes one node of five, and it made Translate read as a counter-example to the rule it was cited for. It now says a node names the operation, with the five verbs and their nodes beside each other, because one verb lowers to two nodes and the file's spelling cannot decide the name. Its layer table cited DimensionComparisonNode as a core-AST name, which this change makes a program name; it cites UnresolvedComparisonNode instead.

One lookup, one home. RelationDeclaration.dim read dict(self.columns)[role], rebuilding the mapping on every call. The typesetter calls it once per role inside comprehensions over roles. It now reads a cached_property mapping. No measurement was taken, so this is a shape change and no speed is claimed.

Kept, deliberately. Sum.over, because the file writes over= and the program follows the file. Also the public walk helpers with no caller in this tree, since whether lpspec reads them is not visible from here.

Why

The naming table says Node marks the core AST and the program uses bare names, yet the program's where vocabulary carried the suffix. At is a preposition that says nothing, where both this tree and lpspec already call the operator a pullback in prose, in a refusal, in the typesetter and in the notation page's own examples. Window did not say it sums, where GroupSum and Sum do. A translation and a window called their axis dimension, where the file, the surface keyword and Partition.along all say along.

The file's expressions: arrived under a different name because Program.expressions meant something else: a derived traversal sitting among six declaration groups and reading like a seventh. roots marks it as derived.

Relations were nested under each dimension they touch, one relation under several, and a property undid the nesting. With the group keyed by name, the declaration's own name field was a second home for one fact. Direction and Partition carry the name instead, because a value that travels without the program has to say which relation it came from. lpspec's read_column takes a node and no program, which is what makes that necessary.

is_function_read named one fact twice: the refusal printed two lines below it says "is not single-valued". "Function" also reads as callable to a Python reader. It has two callers in one resolution function and no consumer asks it, so it is a local there rather than a member of the public record. Footprint.kinds holds type[Expression], and the reading page already iterates it as kind.

The singular accessors covered three of five groups and one had no caller. Their near-miss message only fired when a Python consumer mistyped a literal, which is a bug in the consumer; every name a file can get wrong is already caught at load. The operator sugar contradicted the reading page's "you never build a node yourself", and existed for three assertions.

The break

lpspec reads program.At, program.Window, program.ExpressionNode, program.WhereNode and the suffixed predicate nodes. It pins math-spec by tag, so nothing breaks before this tags. It already owes the same follow-up to #494 and #559, and doing all three at once is one edit rather than three.

The later renames cost it nothing. lpspec reads footprint.domains, footprint.quadratic and footprint.sos_types, never shapes, and it does not read is_function_read.

What this leaves to #580, and why it is not #580 retargeted

#580 sits on #569, which sits on #566, which sat on #565. Its diff does not retarget onto main: replayed there it conflicts in eleven of its twenty-two files, so this branch re-applies the renames by script and takes the residue by hand, the same way #580 was itself re-derived from #475.

Two of #580's predicate renames are not here. ExpressionComparisonNode and ArithmeticComparisonNode arrive with #566, so main has no such names to rename. When #566 lands it owes its two new nodes under the rule this change states, and the sentence #580 adds to the reading page about lowering rewriting one into the other comes with them. Nothing else of #580's program.py work is left out.

#580 is not closed, its branch is not touched, and nothing is force-pushed. Whether it is rebased onto this or reduced to the two comparison nodes is the author's call.

Gates

pixi.sh is refused by this environment's egress proxy with a 403, so the gates ran from a uv environment on Python 3.12 with the pinned ruff==0.16.1 and pyrefly==1.2.0. That is a departure from the "every command runs under pixi run" default.

gate	result
pytest -q	1357 passed
ruff check, ruff format --check	clean
pyrefly check	0 errors, 9 suppressed, as on the base
mkdocs build --strict	clean, with the docs.python.org inventory dropped for the run, which the proxy refuses with a 403
prettier --check on every Markdown	clean
typos, reuse lint	clean
python -m tools.schema	no diff
python -m tests.typesetting.golden	no diff
the four page generators	no diff; tests/test_docs.py covers them and passes
taplo, zizmor, compile-tex	not run, for want of the tools

Neither the schema nor the golden output moves, because the schema is built from model.py and this diff does not reach it. No TOML and no workflow file is touched, which is what taplo and zizmor read.

The cached_property on a frozen dataclass was checked against the three things that could break: Direction still hashes as a dict key, a declaration still compares equal after its cache is warm, and a lowered spec still pickles, which test_a_lowered_spec_still_pickles_and_lowers_to_the_same_program covers.

Coverage moved:

• test_a_relation_names_the_dimension_its_values_label is replaced by test_a_relation_is_declared_as_the_file_declares_it, which lowers a file rather than hand-building a program.
• test_an_unknown_dimension_is_a_near_miss_rather_than_an_empty_declaration is deleted with the accessor it tested. It asserted a KeyError message for a mistyped literal in consumer code, which is the wrong layer.
• test_expressions_are_the_ones_a_row_is_built_from is test_roots_are_the_trees_a_row_is_built_from.
• test_a_program_seals_its_declaration_groups is parametrized over relations too.
• Three assertions that built nodes with * and + call Multiply and Add.
• The golden test's carrier set gains Direction, Partition and RelationDeclaration, which its dataclass walk now reaches.

What this deliberately does not do

• Direction and Partition share five members and differ in three each. No shared base or protocol is introduced. A base for two small records buys a detour for every reader, and the two are different concepts by refactor(language): a partition is a class of its own rather than a direction #559's argument.
• node.direction.consumed_dims keeps its extra hop. That arrived with refactor(language): a relation is read in a direction rather than walked #494 and feat(language): a call walks one relation, so by= names one rather than a list #533, which took the accessors off the node so the direction is the one home for the fact.
• program.py is over a thousand lines across four vocabularies. Splitting it is separable work and belongs on its own branch, not in a rename.
• Sum.over is not renamed. The file writes over=.
• Translate is not Shift. This tree says "translation" for the operator in separability.py, dimensions.py, lowering.py, the typesetter README and a section heading on the operators page. shift is the file's verb and Translate is the program's noun, which is the split the new rule states.
• The branch name is this session's rather than <type>/<topic> from a worktree.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JPqtQuarRGDmX2WrNVuKDP

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34663822 | 📁 Comparing b2beea8 against latest (b458ce8)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• CHANGELOG/index.html
• contributing/index.html
• reference/reading/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/program/index.html
• reference/math_spec/resolution/index.html
• reference/math_spec/separability/index.html