Python definitions registry: token expansion, the prompt index, and grain

[jat255]

Fifth PR of M2. Adds the definitions registry, the surface commons owns until data-dict provides one. Closes the registry issue plus the two items that moved to it from the dictionary reader.

Base is #255. Review that first; the diff here is only the registry.

What it does

• Expands {{name}} and {{table::name}} tokens in run_sql queries.
• Builds the kind index shown in the system prompt.
• Carries the grain metadata that call_metrics' mixed-grain guard needs.
• Checks at construction time that each definition's table is one its source exposes.
• Renders a table's definitions in the dictionary's first-touch entry and retrieval chunks, which the reader left as a marked seam.

Everything consumes ExportRecord; nothing reaches into an expression parser or a typed IR. When a shared data-dict interface arrives, swapping it in is a deletion rather than a rewrite. That is why the registry exists, and why it is tested before the compiler is.

First Python code to assert the shared contract

Tests run the registry over tests/shared/definitions.json as well as hand-built records. They check that every definition data-dict produced expands to its own compiled SQL, that every kind is one the index groups, and that the grain flags reach the records. #255 landed that fixture with only R asserting it; this is the Python half.

Four defects found in review

Each was reproduced before fixing.

• An expansion could widen scope for a later token. Tokens were resolved against SQL that earlier expansions had already rewritten, so a definition compiling to sum(returns.x) put returns in scope for a later bare token, defeating the check that keeps a token bound to its own table. Tokens now resolve against the query as written.
• Retrieval chunks named a token without saying what it expands to. They carried only the kind and type; they now carry the full gist, compiled SQL and notes, matching what first touch shows.
• An absent type reached the prompt as the word None. data-dict omits type when it cannot infer a single one, so it is left out of the prompt too.
• The index cap counted lines but not the newlines joining them, so the rendered index could exceed the cap.

Three R defects this surfaced

Filed rather than fixed here, since pkg-r is a separate package and each fix needs its own R reviewer summary. The first two mean the implementations disagree on observable behavior until R is fixed.

• R: an expanded definition can widen token scope for later tokens #260: R resolves each token after prior substitutions, so it accepts a query Python now refuses. Verified against expand_definitions() directly.
• R: a definition with no inferred type loses its whole gist #259: R's definition_gist() returns an empty string for a definition with no inferred type, dropping the compiled SQL and the notes rather than just the type.
• R: an expanded definition can widen token scope for later tokens #260 also covers R's index cap excluding newlines.

No shared fixture for these yet. A fixture would have to pin a single behavior, and R would fail it immediately; the plan is to fix R first and pin the agreement then.

Verification

325 tests, ruff and pyrefly clean.