From 09b131026fd58522bc1b0e0dffa7daefdbc6f206 Mon Sep 17 00:00:00 2001 From: Jan Petykiewicz Date: Sun, 12 Jul 2026 15:26:24 -0700 Subject: [PATCH] [Tool] tighten constraints on tool parameters --- masque/builder/tools.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/masque/builder/tools.py b/masque/builder/tools.py index 40097a0..702fe7c 100644 --- a/masque/builder/tools.py +++ b/masque/builder/tools.py @@ -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 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 solver may call `endpoint_at()`, `cost_at()`, and `bbox_at()` many times while 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)` is a closed singleton for fixed-size primitives. `None` and `"unk"` ptypes 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 out_ptype: str | None