feat(program): a sum through a relation is a sum over a join

[FBumann]

Prompt: Would it be clearer if we do a larger refactor along this rename? [...] Do this as a follow up! [...] Stacked PR

Note

The following content was generated by AI.

What this changes

The program has one relation node, Join. at(x, by=R, over=a, into=b) lowers to Join(x, columns). sum(x, by=R, over=a, into=b) lowers to Sum(Join(x, columns), over=<the dims the join drops>), the Sum node that already exists. The YAML surface is unchanged.

Stacked on #605, which it needs for the words. Both carry main at alpha.111; its new Program.names_read branch over the relation nodes takes the one Join.

The break. GroupSum and Lookup are gone. The struct #605 called Join is JoinColumns, since the node takes the name; JoinNode.join is JoinNode.columns. fan_in reports Join as one-to-one and the Sum over it as many-to-one, as before. No alias and no deprecation, per the alpha stream. lpspec follows on its own branch once this is released.

Why it is the same model

The absence page already describes the composition. Out of a Sum, an absent summand is one term fewer and the row stands; out of a bare join, absence spreads. Those are today's sum(by=) and at semantics, so nothing on that page moves. The frame rule composes the same way: the join adds the grouped dims and keeps the joined ones, the sum drops the dims over= named. The dim checker and the typesetter read the resolved AST, not the program, so neither changed beyond the struct's name.

Separability keeps its verdicts: a Sum whose operand is a Join reports the grouping message for the dims it drops, and that Join is not also reported as an undecided coordinate read. tests/test_separability.py passes unchanged.

Coverage that moved

• test_lowering.py: the lowering cases and test_a_relation_lowers_with_the_join_each_call_names assert Sum(Join(...), over) and Join(...); the fan-in table has the same two rows in the new shape; test_a_divisor_under_a_join_is_still_named descends through Join.
• tests/fixtures/every_program_node.yaml is unchanged: grouped and looked_up both reach Join, and reduced reaches Sum, so test_every_program_node_is_one_some_file_lowers_to holds with one node fewer.
• test_golden.CARRIERS names JoinColumns.

Gates

pixi is unavailable here, so the gates ran from a uv venv on Python 3.12, on the head with main merged.

gate	result
pytest	1534 passed, 6 skipped
ruff check, ruff format --check	clean
mkdocs build --strict	clean before the merge, with the unreachable docs.python.org inventory dropped for the run; tests/test_docs.py holds every generated page current after it
prettier --check	clean on the two touched pages
tools.schema and the page generators	re-run; nothing moved
compile-tex, typos, reuse lint, pyrefly	not run, not installed here

Why

After #605 the two nodes carried the same Join and differed only in whether a group-by followed, decided at resolution. That welded the join and the sum into a third kind of reduction. With the join as its own node, the program is the relational algebra the words describe: one join, and the sum you already have over it. lpspec already computes it that way, one join with no aggregate and a drop of dims, both collapsing in the terminal group-by, so its engine loses a branch rather than gaining one.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SWBcNGLjNH2i4AqRsfyxaN

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34695794 | 📁 Comparing 5514df8 against latest (4641714)

  🔍 Preview build  

15 files changed · + 1 added · ± 14 modified

+ Added

• about/relations-as-linear-maps/index.html

± Modified

• contributing/index.html
• about/what-counts-as-language/index.html
• examples/operators/index.html
• howto/declare-a-column/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/expressions/index.html
• reference/language/operators/index.html
• reference/language/relations/index.html
• reference/math_spec/model/index.html
• and 4 more...