jan/masque
1
1
Fork 0
Code Issues Pull requests Releases Wiki Activity

[Tool] tighten constraints on tool parameters

Browse source
This commit is contained in:
Jan Petykiewicz 2026-07-12 15:26:24 -07:00
commit 09b131026f
1 changed files with 16 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

16
masque/builder/tools.py
View file

@ -15,6 +15,15 @@ jog is left of travel; returned endpoint ports describe the primitive output in
that same local frame. The planner transforms selected endpoints into layout that same local frame. The planner transforms selected endpoints into layout
coordinates only after a complete route has been chosen. coordinates only after a complete route has been chosen.
Primitive parameters are also the basis for route-failure diagnostics. Tools
must keep endpoint topology stable across each offer domain: length-like
Straight/Bend offers use a finite, attained, nonnegative minimum and advance
their local x coordinate by the selected length; S/U offers move their local y
coordinate by the selected jog. Endpoint rotation and output ptype must not
vary with the parameter and must agree with the concrete offer kind and its
declared `out_ptype`. These are Tool contract requirements rather than
exhaustively runtime-checked properties.
Tool authors should treat offer planning callbacks as pure descriptions. The Tool authors should treat offer planning callbacks as pure descriptions. The
solver may call `endpoint_at()`, `cost_at()`, and `bbox_at()` many times while solver may call `endpoint_at()`, `cost_at()`, and `bbox_at()` many times while
enumerating candidate compositions, ptype adapters, and parameter solutions. enumerating candidate compositions, ptype adapters, and parameter solutions.
@ -166,6 +175,13 @@ class PrimitiveOffer(ABC):
Parameter domains are half-open `[min, max)` ranges, except `(value, value)` Parameter domains are half-open `[min, max)` ranges, except `(value, value)`
is a closed singleton for fixed-size primitives. `None` and `"unk"` ptypes is a closed singleton for fixed-size primitives. `None` and `"unk"` ptypes
are wildcards; incompatible concrete ptypes are rejected by `Pather`. are wildcards; incompatible concrete ptypes are rejected by `Pather`.
Custom offers must have stable endpoint ptype and rotation throughout their
domain. Straight/Bend length domains must have a finite, attained,
nonnegative minimum and produce local `x == parameter`; S/U offers produce
local `y == parameter`. The planner relies on these invariants when it
diagnoses whether a failed constrained route has a preferred minimum-length
alternative or is unsupported at every legal length.
""" """
in_ptype: str | None in_ptype: str | None
out_ptype: str | None out_ptype: str | None