chore: #275's three lookup proposals, side by side on five models

[FBumann]

Prompt: "We need a document or PR that showcases the 3 discussed proposals from #275. How can we create a document that helps the maintainers of mathspec decide which of the proposals to take? I want use 2-4 math problems/formulations and showcase how each would look in either proposal." — "A published html artifact, but as part of the repo. In a dedicated branch" — "Lets find easy to understand use cases for the different use cases of relations and explain it like im 5 years old" — "Can we have it as a regular html file and link it in the pr description instead?"

Note

The following content was generated by AI.

This is a review surface, not a proposal to merge. It is a draft so the models and the prose can take line comments. Two of the three proposals close as not planned once #275 is decided, and this directory closes with them.

Read the page

comparison/index.html is a standalone HTML document. It needs no server and no build step.

git fetch origin claude/mathspec-proposals-comparison-ebn7dv
git switch claude/mathspec-proposals-comparison-ebn7dv
open comparison/index.html      # xdg-open on Linux, start on Windows

GitHub shows the file as source rather than rendering it. To read it without a checkout, a raw-HTML viewer renders it from the branch: raw.githack.com. The page fetches MathJax and two typefaces from public CDNs; with no network the equations stay as TeX source and everything else reads as it should.

What this changes

Adds comparison/, which writes one page comparing #428, #433 and #437 on five models. Each model is written three times, once per proposal, and every file is loaded on the branch that proposes it. Four of the five load under all three proposals. The fifth loads under one.

Nothing on the page is typed by hand except the prose. comparison/verify.py makes a worktree per branch, loads every model in a child interpreter under that branch's src/, and writes evidence.json. comparison/build.py writes index.html from it. So every YAML block, every list of dimensions, every equation and every refusal message is the branch's own output.

Two findings came out of building it, and both are on the page verbatim:

1. A dtype: bool flag cannot be multiplied. The stand-in for an unweighted relation is a table of ones, multiplied into the sum, so the ones have to be declared dtype: int. The message says A flag masks rather than scales.
2. The rewrite feat(language): a lookup may map into its own dimension, so a representative snapshot is sayable #436's description prescribes does not load. It sends an undirected neighbour relation to "a parameter over [bus, bus]". Measured on feat(language): a lookup may map into its own dimension, so a representative snapshot is sayable #436's own head: Parameter 'adjacent' names dimension 'region' twice. A frame is a product of distinct dimensions. That is the fifth model, and the one place a column is empty rather than clumsy.

The five models, and what each proposal does with them

Model	per: #428	keys and a dot #433	relations #437
A zone that changes by period	one table	one table	one table
A cap across a stay in a zone	two declarations	one table	one table
Nodal balance over lines	two tables	two tables	one table
A cap per bus and technology	two tables	two tables	one table
Neighbouring regions	refused	refused	one table

Outside the five, a masked sum — the produced dimension already carried — is refused by #428 and #433 and accepted by #437.

The page also carries a primer of seven cards, one per kind of pairing, in everyday terms first and then in a model. Each says which proposals spell it and how.

Files

• comparison/models/p1…p5/{per,keys,relations}.yaml — 15 models, 13 of which load. The two refusals are the evidence for the fifth row.
• comparison/probes/ — files that are refused, so the page can print the message whole.
• comparison/verify.py, comparison/_load.py — fetch four branches (feat(language): a lookup may be conditioned on a second dimension, so a generator's zone can change by period #428, feat(language): a lookup keyed by several dimensions, walked along the key a call names #433, feat(language): a relation between dimensions, walked in the direction each call names #437, and feat(language): a lookup may map into its own dimension, so a representative snapshot is sayable #436 for the self-map claims), load every file under the branch that proposes it, write evidence.json.
• comparison/build.py, comparison/template.html — write comparison/index.html.
• comparison/README.md — how to read it, how to rebuild it, and why this is not for main.
• pyproject.toml — one per-file-ignores entry, the same exemption tools/ has: these scripts are generators that print what they wrote, and the page prints a set as the script capital the typesetter uses (𝒢), which RUF001 reads as a typo for G.
• REUSE.toml — one entry for evidence.json, which is generated JSON and carries no comment.

Verified

pixi is not installable in this environment, so the gates ran from a uv venv on Python 3.13 with the repository installed, and from the pinned tool versions where they were reachable.

• All 15 models reloaded on their branches after every change: 13 load, 2 refuse, and the refusals are the two the page prints.
• ruff check and ruff format --check clean on comparison/ (ruff 0.14.0).
• prettier --check clean on comparison/**/*.md, with the repository's own .prettierrc.yaml.
• reuse lint passes on the whole tree: 240 / 240 files with copyright and licence information.
• No trailing whitespace and a final newline in every file the branch adds, which is what trailing-whitespace-fixer and end-of-file-fixer check.
• The page opened from the file system in a headless Chromium: standards mode, no script errors, and all 15 comparison panels laid out.
• The prose was measured with the sentence script in .claude/skills/docs-writing, adapted to read the built page's prose blocks: n 193, avg 11.0, median 10, one sentence over 25 words.

Not run: pixi run ci as a whole, and inside it pytest, pyrefly, typos, taplo, zizmor, docs-build and compile-tex. pyrefly reads project-includes = ["src/math_spec"], so it does not reach this directory; docs-build does not either, since the page is not under docs/ and has no nav entry. One thing could not be checked here: this sandbox's proxy blocks cdnjs, so MathJax was never fetched and the equations were only seen as TeX source.

Why

#275 has three open pull requests and exactly one will be merged. Each PR body argues its own case, and the capability table in #437 is the only place they are compared — by the author of one of them. This directory compares them on models instead, with the loader on each branch as the witness, so a claim about what a proposal can say is a file that loads or a message that says why not.

The commit type departs from the table in AGENTS.md: the diff touches pyproject.toml, which the table sends to build, but the change is a decision aid and the two config lines exist only so lint passes on it. Both types hide from the changelog, so this names the change honestly rather than telling a changelog reader a build story.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W4kdrj2n7tESNrgYmfXkAq

[FBumann]

Prompt: "#437 was merged / Close all related issues and stale PRs"

Note

The following content was generated by AI.

Closed having done its job. This carried #275's three proposals side by side on five loadable models so the choice could be made on what each could say rather than on how each read. #437 won and merged as 3284926, released in v0.0.0-alpha.89; #428 and #433 are closed.

It was never for main — a decision aid, like #454's comparison-gams/, and the decision is made. The branch goes with it.

Worth knowing if anyone reaches for it again: the models here are written in the pre-#477 spelling, so they use lookups:, consume= and produce= where main now takes relations:, over= and into=, and along= on shift and sum_back. They no longer load.

---

Generated by Claude Code