refactor(language): an expression resolves straight into the program's own nodes

[FBumann]

Prompt: Review the packages code as a whole. Do you see room for simplififcation? Or reuction of concepts? … Let's apply your proposed changes … Now let's work on the big thing … Let's do this … Rebase the full stack

Note

The following content was generated by AI.

Resolution builds program.Expression nodes, so every pass after it reads one vocabulary and lowering only packages declarations. Before that, a piecewise block is checked once at load, one function types an expression string, and four duplicate shapes are gone. Stacked on #632; the whole stack is rebased onto main at #640.

Warning

Found in review, fixed at #643: a dim fault under a bare sum() is a SchemaError where the dim rules raise DimensionError, and the tests were loosened rather than pinned; sum(sum(p, into=g)) added a false "already a scalar"; the exclusivity rewrite rounded a literal to six digits; an undeclared piecewise over: added per-link lines; a str or bool breakpoint parameter and an lp x-link with no variable were refused only under an emitted row; offset=-tag lost its dtype hint; fan_in crashed on a Named; _operands repeated children; the otherwise test in the walk was always true; the UNREACHABLE entry if isinstance(node, Cases): names a line that runs. Unclaimed here and pinned there: an unused template or entry is now refused for the form of an amount, an edge or a bare sum.

Concepts

• One expression vocabulary. The syntax tree the grammar builds is read by expansion and resolution only. Everything after — the dim rules, the degree rules, the exclusivity check, the typesetter, lowering — reads program.Expression. The predicate side already worked this way; the arithmetic side now does too.
• Resolution builds, lowering packages. A Sum, GroupSum, Pullback, Translate or WindowSum is built at the call, with the Direction or Partition resolution already computed. Resolved holds ConstraintDeclarations and an ObjectiveDeclaration. Lowering rebuilds each declaration with every Named use inlined and does nothing else to a tree.
• A formal builds nothing and refuses nothing. _Resolver.arith returns None with an error for a refusal and None with no error for a node a macro formal stands under. A template is checked by resolving it and keeping the errors; the call site that binds the formals is where the node is built. No Formal leaf exists. This is also what fixes fix(language): a macro template nothing calls is held to every rule a call site is #628's refusal of a formal along= beside by=; fix(language): a long chain of named expressions loads, a typo beside a formal is refused, and a fault in an entry hides no other #643 pins it.
• The otherwise region is built by resolution. Its mask is the remainder of the other regions (resolution.remainder), so a consumer adds regions. The typesetter prints "otherwise" for the last region.
• The form of an amount and an edge is decided where it is read. A literal offset= or window= is whole and in range, a named one is a parameter, and a shift without an edge= says what it means, all in resolution, so Translate.offset and WindowSum.width are the int | str they say. The dim rules keep only what needs the operand's dims.
• A piecewise block is checked once, at load, with every other declaration. The names it references are Spec reference rules, the names it emits are collision rules the sos check shares, and its frame is curve_frame, which the expansion and the typesetter both read. The expansion cannot fail for what load admits; two rules load did not decide here are decided at fix(language): a long chain of named expressions loads, a typo beside a formal is refused, and a fault in an entry hides no other #643.
• A named expression is resolution's. Expansion substitutes macros only. A use of an expressions: entry resolves to the one Named node built for the entry, and the memo, the cycle check and the "does not load" refusal stay where refactor(language): each named expression is resolved once, and every use reads that node #632 put them.
• An assumption is the class named Assumption. The file's section is assumptions: and every other declaration class is a noun; the Holds class and its Assumption alias, which stood in for kinds that never came, are one class.

Renames

Was	Is
validation._check_expression and resolution._value	resolution.resolve_expression_text, and resolve_constraint_text for a constraint
resolution.ResolvedConstraint	program.ConstraintDeclaration
resolution.ResolvedAssumption	program.Assumption
piecewise.Assumed	model.AssumptionBlock
program.Holds, and the program.Assumption alias of it	program.Assumption, one class
model.LinkSign	_expression_parser.ComparisonOperator
program.ExpressionComparison[Side]	program.ExpressionComparison, both sides Expression
_expression_parser.case_context	errors.case_context
dimensions._AMOUNTS and _Amount	operators.AMOUNTS and Amount
lowering._none_of	resolution.remainder
lowering._Lowering.expr and .mask	lowering.inline and inline_mask
piecewise._nominated	PiecewiseBlock.nominated
typesetting.walk.Walk._curve_frame	piecewise.curve_frame

degree.carries_variable is removed as a duplicate of program.carries_variable, which was already there.

Removed

• Parser nodes: VariableNode, ParameterNode, DualNode, DimensionNode, DirectionNode, PartitionNode, EdgeNode, CaseArm, CasesNode, DefinitionNode, and the groups KwargNode, UnresolvedNode, LeafNode. The parser keeps NumberNode, NameNode, NameListNode, KeywordNode, UnaryOperatorNode, BinaryOperatorNode, FunctionCallNode and ComparisonNode.
• Public: math_spec.PiecewiseExpansionError, math_spec.program.Holds.
• Lowering: _Lowering, _CALLS, _amount, _partition_of.
• Dim rules: _CALL_RULES, _dims_call, _cases_dims, _check_amount_form, _check_edge, _edge_fill, _vacates, _whole, _amount_of (the form checks moved to resolution; the rest is one dims_of over program nodes).
• Degree: _REDUCTIONS, the reductions being the node kinds now.
• Typesetter: walk._amount, walk._step, Walk._curve_frame.
• Guards: the six "reached X unresolved" assertion arms in degree, dimensions, lowering and the walk.

Added

• program.Named(name, body): the one node a Spec.resolved tree holds that no Program does. Exported, since program.__all__ is checked against what the module defines; absent from Expression, so a consumer's exhaustive match is unchanged. program.children steps through it.
• piecewise.Emitted and piecewise.curve_frame, operators.Amount, lowering.inline, resolution.remainder, resolution.resolve_constraint_text.

Method, gate output, alternatives

The commits

Six on one branch, because the session was held to one. That departs from one issue, one PR; split at the commits if wanted.

1. chore(resolution): one door for an expression string. resolve_expression_text in resolution.py replaces validation.py's _check_expression and resolution's _value, which were the same five steps down to the message text.
2. refactor(language): a piecewise block is checked once at load. Spec._validate_expressions computes resolved before it expands, so the expansion reads each link's typed tree rather than parsing the text again. PiecewiseExpansionError is gone: a block is refused as a SchemaError or a DimensionError like any other declaration.
3. chore: a shape declared once. assumptions_of returns AssumptionBlocks, Resolved.assumptions holds the program's assumption class, and the LinkSign alias is gone.
4. refactor(language): an expression resolves straight into the program's own nodes. The ledger above. feat(language): a where may read a predicate through a relation with at() #634's at() over a predicate is carried in this commit: PulledBackPredicate is built from the Direction the relation read returns, pulled_back_dims serves the expression and the predicate alike, and the walk's _pullback reads through the helper feat(language): a where may read a predicate through a relation with at() #634 added.
5. chore(schema): the published schema regenerated for a docstring the fourth commit changed.
6. refactor(program): an assumption is the class named Assumption. The rename of Holds, in source, tests and reading.md.

The rebase

The seven branches of the stack, #626 through #632 and this one, are rebased onto main at #640, one commit each, in that order. Two of the seven conflicted with #634: #626 on the shape of the Predicate union, #632 on an import line, both resolved in the commit that meets them. This branch's fourth commit conflicted in the four modules #634 touched, and is resolved with the files of the merge commit that was pushed and validated here before (540d412); the rebased head's tree equals that merge's tree, release files aside, so the earlier gate output stands. Each branch was pushed with a lease against the head it was rebased from.

Breaking for consumers

• math_spec.PiecewiseExpansionError no longer exists. fluxopt/lpspec re-exports it in errors.py and __init__.py, lists it in tests/test_architecture.py and tests/test_api.py, and matches it in tests/test_piecewise.py:293,298; each becomes SchemaError or DimensionError. No alias, per the alpha-stream rule.
• math_spec.program.Holds no longer exists; the class is Assumption, which reading.md documents. lpspec names neither.
• math_spec.program.Named is new in __all__ and absent from Expression. lpspec's test_docs_site.py:291 pins get_args(program.Expression), which is unchanged.
• program.ConstraintSense stays: lpspec reads it in three places, and the Literal cannot move into program.py without an import cycle through model.py.

Behaviour a user sees

• Every golden output is unchanged: python -m tests.typesetting.golden re-run on main's model, no diff. The file language changes in one direction: a template nothing calls and an expressions: entry nothing reads are now refused for a fractional or out-of-range amount, a bad edge, and a bare sum() of a scalar, because those forms are decided in resolution. fix(language): a long chain of named expressions loads, a typo beside a formal is refused, and a fault in an entry hides no other #643 pins both.
• A block naming an undeclared parameter, a non-binary gate or a non-bool points: is refused with every other reference fault in the file, one per line.
• A fault in the form of an amount or an edge, a bare sum() of a scalar, a dim fault under a bare sum(), and a negated named offset are collected with the other resolution faults as a SchemaError, where each raised a DimensionError first. fix(language): a long chain of named expressions loads, a typo beside a formal is refused, and a fault in an entry hides no other #643 pins the class per rule.
• A named amount written +p reads as p; only -p is refused as a negation.

Tests

• 1565 passed on the rebased head, and each rebased branch below it passes its own suite (1570 to 1578). refactor(language): each named expression is resolved once, and every use reads that node #632's head had 1562 before the rebase: the parser test for nine resolved nodes' __str__, the unresolved-name test in test_degree, and two rows of the operator-table test went with the classes they tested.
• Coverage that moved: tests/test_lowering.py's "lowers to its node" cases assert the node resolution builds; tests/test_expansion.py reads through Named with lowering.inline; the golden census counts Expression members plus Named and the operators by node type; tests/test_piecewise.py asserts SchemaError where it asserted PiecewiseExpansionError.
• The line census of the walk (test_the_golden_model_reaches_every_line_of_the_walk, needs coverage) passes; the one arm it cannot reach, a Cases outside a Named, is in UNREACHABLE with its reason.
• Not done: a mutation sweep at fix(language): a long chain of named expressions loads, a typo beside a formal is refused, and a fault in an entry hides no other #643 found nine guards of the moved and added rules with no test, not three: the three frame refusals curve_frame carries, three reference rules of a block, three kwargs naming nothing. Three of the nine were redundant with the check beside them. All are pinned or gone there.

Numbers

Against #632's head, src/ is 16 files, 1281 added, 1745 removed. Parser node classes 18 to 8; program node classes 15 to 16, the one added being Named.

Gates

• ruff check and ruff format --check: green. pyrefly check --python-interpreter-path <venv>: 0 errors.
• pytest -q -n auto: 1565 passed. python -m tools.schema and the golden generator re-run, no diff.
• prettier on the changed pages: applied.
• docs-build and compile-tex did not run: the session proxy refuses docs.python.org and pixi.sh, and typos, reuse and zizmor are not installed here.

What was left out

Folding the dim rules into the resolver, so that each node is built knowing its dims, is the next cut the design invites and a separate one. Namespace still mirrors Spec in five fields.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DwZZXWXoJfSMabvXTUndtn

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34716587 | 📁 Comparing f2675a2 against latest (f9cb305)

  🔍 Preview build  

24 files changed · ± 24 modified

± Modified

• CHANGELOG/index.html
• contributing/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/errors/index.html
• reference/language/expressions/index.html
• reference/math_spec/degree/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/expansion/index.html
• and 14 more...