refactor(language): each named expression is resolved once, and every use reads that node

[FBumann]

Prompt: Review the packages code as a whole. Do you see room for simplififcation? Or reuction of concepts? … Do both

Note

The following content was generated by AI.

Namespace.named resolves each expressions: entry once. Every use then reads that node: expansion inlines it, and the resolver passes it through. Before, every use parsed, expanded and resolved the entry again. Stacked on #631.

Warning

Found in review, fixed at #643: a fault in a macro or an entry hides every other fault in the file (the early raise below); a cycle closed through a macro reports a -> a without the macro; a chain of 120 entries declared deepest first is a RecursionError. Fixed at #638 and pinned at #643: a piecewise link through a refused entry said "Its refusal is listed with it" and nothing listed it. Pinned at #643: a cycle through a case's when, a RecursionError on the base branch, is refused here.

Method, gate output, alternatives

What this changes

• Namespace.named / named_entry. The first read resolves an entry under its own context and stores the node and its refusals. The expression cycle check moves here. The macro cycle check stays in expansion.
• Resolution owns _named, moved from validation with _constant_arm. _value is the "stands for a value" parse, which _check_expression did for named entries before.
• Expansion takes the Namespace, not the Spec. _parse_named, _parse_cased and _parse_body are gone, and so is the pyrefly: ignore for the unresolved CaseArm.when.
• The resolver passes a CasesNode or a DefinitionNode through unchanged. _Resolver._cases is gone.
• Validation drops _once: an arm error now has only one source. Validation raises after the expressions: entries if any fails. 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 removes that raise: the memo already reports an arm's fault once, so nothing needs the other declarations held back.

Behaviour a user sees

• A use of a refused named expression reads named expression 'b' does not load. Its refusal is listed with it.. Before, it got the entry's fault again under its own context.
• Here, if a named expression fails, the refusal lists only the expressions: faults (and any macro fault). 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 every declaration's fault is listed together.

Tests

• test_a_named_expression_is_resolved_once_however_many_uses and test_a_use_of_a_refused_named_expression_names_it_rather_than_repeating_its_fault fail on the base branch and pass here.
• Guards, each deleted in turn with the suite run:
  • The memo check: 4 tests fail.
  • The cycle check: a-cycle fails with a RecursionError.
  • The early raise: test_a_fault_in_an_arm_names_the_declaration_and_is_reported_once fails.
• test_a_call_expands_to_core_ast now compares resolved trees, because an inlined body arrives resolved.

Gates

• pixi run lint: green.
• pixi run test: 1562 passed.
• docs-build and compile-tex did not run: the session proxy blocks their downloads.

Where this departs from the house rule

src/ grows by 8 lines net (171 added, 163 removed), because the memo is new code. The number of concepts goes down: _once, three expansion parsers, _Resolver._cases and the expression stack in expansion are removed, and one memo is added. AGENTS.md says a cleanup ends in fewer lines and fewer concepts, so this PR does not meet the lines half of that rule.

🤖 Generated with Claude Code

https://claude.ai/code/session_017XwKgY5wZXv1bKgkfCW2q1

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34716573 | 📁 Comparing 8ca80c2 against latest (f9cb305)

  🔍 Preview build  

15 files changed · ± 15 modified

± Modified

• CHANGELOG/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/expressions/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/expansion/index.html
• reference/math_spec/program/index.html
• reference/math_spec/resolution/index.html
• reference/math_spec/sos/index.html
• reference/math_spec/validation/index.html
• and 5 more...