[Tool] tighten constraints on tool parameters

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