fix(language): a piecewise block its expansion cannot write is refused as the model loads

[FBumann]

Prompt: "Review #630" … "Do a stacked or fixing those"

Note

The following content was generated by AI.

Stacked on #630. The model now refuses at load a walked link that at() refuses. It also refuses an empty over:/into: and a name two blocks both write. A where: over a joined dim loads. Two refusals now name a rewrite the block can take.

What this changes

Each change answers one finding of the review of #630. Each finding has a test that fails on #630's head.

#	Finding on #630	Now
1	Block a with link b_x and block a_b with link x both write a_b_x. Both loaded, and one row overwrote the other. The same happened with a_b_convexity and a_b_complete	emitted_name_errors refuses a name that two sets or curves both write. It names both blocks
2	A walk whose into is not on the key, whose read is not single-valued, or whose key column is joined on a dim outside dims: loaded. expand() then failed and named the emitted row	resolve_walks reads each walk through the resolver's direction(), the same code that at() uses. _walk_fits checks the walk against dims: and then calls pulled_back_dims, the dim rule of at(). Each refusal names the link
3	A where: over snapshot was refused when the relation is keyed on [flow, snapshot], although the walked row keeps snapshot	A walked row reads the mask through the relation only when the mask carries a dim the walk consumes
4	over: [] or into: [] loaded, and the expansion wrote at(..., over=[]), which does not parse	PiecewiseLink refuses an empty list
5	A block that has a where: over dims: was told to "declare where:"	The block is now told to let its where: test the breakpoint dim too
6	A where: over flow was told to add flow to dims:, which the walk then refuses	The refusal says to test dims: in the where:, or to mask the link's own variable
7	_piecewise_walk_shape rebuilt the relation's role-to-dim map, which piecewise._walk also built	Both copies are deleted. _row, _reads and _where_fits read the typed Direction
8, 9	Three assertions in tests/test_piecewise.py had no message	They now carry one

Why

Everything that can be decided without data is decided at load (AGENTS.md). Findings 1, 2 and 4 loaded and then failed or silently dropped a row in expand().

Message changes, and coverage that moved

• The refusals for an unknown column, a repeated column and an undeclared by: are now the refusals of at(), with the link as their context. Example: piecewise 'coupling' link 'power': at(by=generator_of): into=['flow', 'flow'] names a column twice. The a-repeated-column case now matches that text.
• A walk that lands off the key gets the text of at(), which ends in "Land on the key, or sum toward [...]". The "sum toward" half does not apply to a link. I left it because the text belongs to the shared resolver.
• The "over and into both reach" check is deleted. It cannot be reached: a shared dim is refused first as either "over reaches" or "into reaches". A probe with a relation from flow into flow gets the "into reaches ['flow']" refusal.
• _expression_resolver.ExpressionResolver._direction is renamed to direction, because piecewise.resolve_walks calls it.

Mutation table: each new guard deleted in turn, full suite

A script took this table. It refuses a dirty tree, and restores each file with git checkout --. It drops __pycache__ on both sides of every mutation. The tree came back clean after every row.

Guard deleted	Caught by
PiecewiseLink: empty over/into	[an-empty-over], [an-empty-into]
resolve_walks: by names a relation	[a-walk-through-an-undeclared-relation]
declaration_of: the _walk_fits call	5 cases of test_a_walked_block_the_language_cannot_read_is_refused
_walk_fits: over reaches dims:	[a-walk-consuming-a-dim-the-block-lacks]
_walk_fits: into is off dims:	[a-walk-into-a-dim-the-block-has]
_walk_fits: into is off along	[a-walk-into-the-breakpoint-dim]
_walk_fits: joined dims are in dims:	[a-walk-joining-on-a-dim-the-block-lacks]
_walk_fits: pulled_back_dims backstop	[a-walk-joining-on-the-dim-it-consumes]
_reads: joined dims counted as consumed (the rule on #630)	test_a_mask_over_a_dim_the_walk_joins_on_reaches_the_walked_row_as_written
_reads: partial-mask refusal	test_a_mask_carrying_part_of_what_a_walk_reads_through_is_refused
_where_fits: advice for a dim a walk produces	test_a_where_over_a_dim_a_link_walks_into_is_not_sent_to_dims
assumptions_of: advice for a where: over dims:	test_a_missing_breakpoint_names_a_rewrite_the_block_can_take[a-where-over-dims]
emitted_name_errors: the _shared call	the 3 cases of test_a_name_two_blocks_would_both_write_is_refused

Gates, and what was not run

The gates ran in a venv, not through pixi, which is not installed here. The tool versions match the pins in pixi.toml.

Gate	Result
pytest -q -n auto	1735 passed, 2 skipped (the bare-install guard)
ruff check, ruff format --check (0.16.1)	clean
pyrefly check (1.2.0)	0 errors
prettier --check on the changed page	clean
python -m tools.schema, python -m tests.typesetting.golden	regenerated, no diff
mkdocs build --strict	not run to the end: the proxy refuses docs.python.org, the same as on #630
compile-tex, typos, reuse	not run

Deliberately not done

• I did not merge main into this branch. main is four commits ahead of feat(language): a piecewise block states its dims and names its links, and its where reaches links that walk a relation #630, and bringing it in is feat(language): a piecewise block states its dims and names its links, and its where reaches links that walk a relation #630's work.
• The empty-list refusal is a model validator, not min_length=1 in the schema. With min_length, pydantic's own message would come first and would not name the rewrite. So the published schema does not change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WasiCKk1SebD7S1CsAFQog

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34739065 | 📁 Comparing 6163726 against latest (9c7c0a5)

  🔍 Preview build  

19 files changed · + 4 added · ± 14 modified · - 1 deleted

+ Added

• examples/piecewise/index.html
• examples/piecewise_adjacency/index.html
• examples/piecewise_lp/index.html
• examples/sos/index.html

± Modified

• CHANGELOG/index.html
• examples/index.html
• examples/dispatch/index.html
• examples/pypsa/index.html
• howto/see-an-expansion/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/piecewise/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/model/index.html
• and 4 more...

- Deleted

• howto/curve-by-hand/index.html