feat(language): a named expression may declare the frame it is read over

[FBumann]

Prompt: "But maybe land that expression has dims or on main first? And make it the bottom of the stack? It's an independent feature that need to pay for itself on main. We need to discuss the dim rules etc…" — then "Yes" to the rules below.

Note

The following content was generated by AI.

A plain named expression may carry dims:, the frame it is read over. Its body may carry no dimension the frame does not name, and may carry fewer: the quantity is then constant along the rest. dims: now means one thing on every expression entry.

The bottom of the composition stack: #731 and #732 rebase onto it, and #732's empty sum is this rule with no body.

The rules

1. dims: on a plain entry is optional. Absent, the frame is what the body carries, in the order the dimensions are declared, as before. Declared, the frame is dims:, in the order written.
2. The body carries no dimension the frame does not name. One that does is refused at load, with the rewrite: add it to dims:, or take it out of the body.
3. The body may carry fewer. The quantity is constant along the rest of its frame, and a constraint over the whole frame reads it at every coordinate. A row that would have been refused as repeating on the body's own frame is accepted on the declared one.
4. A cased entry is unchanged: dims: required, every region within it. Rule 2 was already its rule.
5. Where the expression is read, its frame is what rule 1 says. Degree, masks and the canonical form do not change.
6. No body at all is still refused.

expressions:
  cap:
    dims: [snapshot, generator]
    expression: p_max
    description: the nominal capacity, the same in every snapshot

What this changes

• ExpressionBlock no longer refuses dims: without cases:; the schema's description says what the frame is. A plain entry with dims: serialises as a mapping, so it round-trips.
• lowering._frame_of takes the declared frame as written for any entry, and dimensions.check_schema holds a plain body to it the way it holds a cased region.
• The reference page on named expressions says what dims: means on a plain entry, and the table row for dims no longer says "refused without".

Why

Today a plain entry's frame is derived from its body and a cased entry's is declared, so dims: means two things. A stated frame is a claim the loader checks, a reader sees the frame the author meant, and a quantity constant along a dimension can say so. The composition PRs need exactly this rule for a sum other files fill, and it stands on its own without them.

Method, guards, gates, what was not done

Guards, each with the test that fails without it. test_a_body_outside_its_declared_frame_is_refused (rule 2). test_a_declared_frame_is_read_at_every_coordinate_where_the_body_is_narrower (rule 3), which also pins the refusal the same file gets without dims:. test_a_declared_frame_is_the_frame_as_written (rule 1 and the round trip). The dims-alone case of test_validation.py asserted the old refusal; its coverage moved to those three.

Gates. Pixi cannot be installed in this container. In a Python 3.12 uv virtualenv with the runtime pins of pixi.toml, against this branch's src/:

pytest tests -n 8                         1664 passed, 22 skipped
ruff check . / ruff format --check .      clean
pyrefly check                             0 errors (9 suppressed)
prettier --check docs CHANGELOG.md        clean
python -m tools.schema                    regenerated, committed (one description)
python -m tools.gallery --check / tools.notation --check   current

Not run: docs-build, compile-tex, typos, reuse lint, zizmor, taplo. The skips are the docs-feature tests, which the bare environment skips.

Not done.

• The golden model gains no plain entry with dims:; the construct prints as any definition, over its frame.
• limits.md is unchanged: no limit moves.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H1F2gprjeiGPnvDaWjZwBB

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34767407 | 📁 Comparing 42df148 against latest (0efbf59)

  🔍 Preview build  

2 files changed

± changelog/index.html
± reference/language/named/index.html