fix: enforce the two rules a named offset or width was always said to obey

[FBumann]

Closes #58. Stacked on #59 → #56 — base is fix/window-partition.

What was wrong

The docs state two rules for a named width, both as load errors: it is integral, and it does not span the dimension being summed over. Neither was checked anywhere. within appeared in operators.py and a docstring, and in no pass.

A dtype: float parameter declared over the very axis being summed loaded clean and rendered as:

$$\sum_{t' \in \mathcal{T} ,:, 0 \le t - t' < w} x_{t'}$$

which reads as though w were constant along that axis. On a page whose subject is what a file means, typeset math that claims something the model doesn't say is the worst way to be wrong.

Scope: it was wider than the issue said

shift's offset= documents the same two rules in the same words, and they were unchecked too. Enforcing them for within= while offset= next door still accepted a spanning float would be half a fix, so this is one helper over all three operators.

I audited every documented load error for a named amount. Before this PR, all seven were dead:

rule	operator	status
integral	shift(offset=p)	fixed here
does not span the axis walked	shift(offset=p)	fixed here
integral	sum_back/sum_forward within=p	fixed here
does not span the axis summed	sum_back/sum_forward within=p	fixed here
varies only over readable dims	shift(offset=p)	left — see #62
a named offset requires edge=	shift(offset=p)	left — see #62
a negative named offset is refused	shift(offset=-p)	left — see #62, crashes

The last one matters most and is why #62 exists: offset=-lead loads clean and then raises a bare AssertionError out of walk.py, which is precisely the rule that file's docstring says it relies on.

Where the checks live

In the dim pass, because that is where the schema is in hand — a parameter's dtype and its dims come off one declaration, and splitting a documented pair across two passes would give one rule two voices. resolution.py carries dtypes but not parameter dims, so it could enforce one half and not the other.

A literal needs no check at all: it parses as a number, and a number carries no dims.

Review notes

• Error wording names the rewrite, as the neighbouring rules do — the integral one points at dtype: int "which binds only an integer column, so a fractional width has nowhere to arrive from", and the spanning one says what the operator stops being.
• Five rejection cases and three positive inference cases in test_dimensions.py; the fixture gains spinup (legal) and horizon (spans the axis) with a comment saying why.
• No docs changes — the rules were already documented. That was the problem.
• 446 passing, lint clean.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34218222 | 📁 Comparing 797be03 against latest (f1c207f)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

• examples/operators/index.html
• reference/notation/index.html
• reference/language/operators/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/operators/index.html
• reference/math_spec/typesetting/walk/index.html