fix(task-10): nozzle stubs meet the drawn outline, impossible capsules and nozzle typos refused

Nozzle stubs started at the bounding-box edge, so on a dished head, a
hopper's sloped wall or a cone roof they floated off the vessel (default
horizontal_vessel N3/N4 by 0.8 mm, reactor N3/N4 by 0.06 mm, unbounded for
user fractions). The port now stays STUB outside the bbox and the stub is
drawn from there in to where its axis-aligned line meets the outline, via a
new geometry.scan_hits helper; jacketed reactors' stubs pass through the
jacket to the wall.

validate_vessel_params refuses height <= width for vertical capsules
(vertical_vessel, column, reactor), width <= height for horizontal_vessel
and height <= width/6 for a cone-roof tank: those folded the heads through
each other and produced geometry outside the declared bbox. Unknown keys
inside a nozzle dict are refused naming nozzles[i] and the key, like the
top-level parameters already were.

Tests: a fuzz over every accepted vessel shape x 28 nozzle positions checks
the declared bbox and that each stub's inner end lies on the outline (exact
point-to-arc/segment distance); the default-symbol repros and the refusals
are pinned. 137 of the new cases fail against the previous module.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FKFStjEFzpGyLq5bMpWxTd

engineering/pid/geometry.py

@@ -128,6 +128,62 @@ def _arc_extent(cx, cy, r, start_deg, end_deg):
     return pts
 
 
+def scan_hits(primitives, axis: str, c: float, eps: float = 1e-9) -> list[float]:
+    """Where the scan line ``x = c`` (``axis="x"``) or ``y = c`` (``axis="y"``)
+    meets the drawn geometry: the *other* coordinate of every crossing.
+
+    A segment lying on the scan line contributes both of its ends; a tangent
+    arc contributes its touching point. Text has no outline and is skipped;
+    bulged polylines are refused rather than silently flattened to chords.
+    """
+    if axis not in ("x", "y"):
+        raise ValueError(f"scan_hits: axis must be 'x' or 'y', got {axis!r}")
+    along_x = axis == "x"
+    hits: list[float] = []
+
+    def segment(x1: float, y1: float, x2: float, y2: float) -> None:
+        # a = scanned coordinate, b = reported coordinate
+        a1, b1, a2, b2 = (x1, y1, x2, y2) if along_x else (y1, x1, y2, x2)
+        if abs(a2 - a1) <= eps:
+            if abs(a1 - c) <= eps:
+                hits.extend((b1, b2))
+            return
+        t = (c - a1) / (a2 - a1)
+        if -eps <= t <= 1.0 + eps:
+            hits.append(b1 + t * (b2 - b1))
+
+    def circle_arc(cx: float, cy: float, r: float, start: float, end: float) -> None:
+        ca, cb = (cx, cy) if along_x else (cy, cx)
+        d2 = r * r - (c - ca) ** 2
+        if d2 < -eps:
+            return
+        s = math.sqrt(max(d2, 0.0))
+        sweep = (end - start) % 360.0 or 360.0
+        for b in {cb - s, cb + s}:
+            x, y = (c, b) if along_x else (b, c)
+            rel = (math.degrees(math.atan2(y - cy, x - cx)) - start) % 360.0
+            if rel <= sweep + 1e-6 or rel >= 360.0 - 1e-6:
+                hits.append(b)
+
+    for p in primitives:
+        kind = p["type"]
+        if kind == "line":
+            segment(p["x1"], p["y1"], p["x2"], p["y2"])
+        elif kind == "circle":
+            circle_arc(p["cx"], p["cy"], p["r"], 0.0, 360.0)
+        elif kind == "arc":
+            circle_arc(p["cx"], p["cy"], p["r"], p["start_deg"], p["end_deg"])
+        elif kind in ("polyline", "solid"):
+            if kind == "polyline" and p.get("bulges"):
+                raise ValueError("scan_hits: bulged polylines are not supported")
+            pts = list(p["points"])
+            if kind == "solid" or p["closed"]:
+                pts.append(pts[0])
+            for (x1, y1), (x2, y2) in zip(pts, pts[1:], strict=False):
+                segment(x1, y1, x2, y2)
+    return hits
+
+
 def bbox_of(primitives) -> tuple[float, float, float, float]:
     """Extent of the drawn geometry (text counts by its insertion point only)."""
     xs: list[float] = []

engineering/pid/symbols_vessels.py

@@ -6,11 +6,16 @@ parameters, so the block name carries an 8-hex hash of the validated parameter
 set (spec 4.5): identical parameters share one definition, different ones get
 their own. Nozzles become stub lines plus named ports; the default set is
 ``N1`` top, ``N2`` bottom, ``N3`` left (0.7 up the wall), ``N4`` right (0.3).
+
+A nozzle's port sits ``STUB`` outside the vessel's bounding box on the side it
+was asked for; its stub is drawn from the port inward to the point where that
+axis-aligned line meets the *drawn* outline (a dished head, a hopper's sloped
+wall, a cone roof), so no stub ever floats off the vessel or pierces it.
 """
 
 from __future__ import annotations
 
-from .geometry import arc, line, polyline
+from .geometry import arc, line, polyline, scan_hits
 from .symbols import Port, SymbolSpec, make_spec, params_hash, register, tag_attdefs
 
 VESSELS = ("vertical_vessel", "horizontal_vessel", "tank", "column", "reactor", "hopper")
@@ -29,15 +34,18 @@ _DEFAULTS: dict[str, dict] = {
     "reactor": {"width": 24.0, "height": 36.0, "jacketed": False},
     "hopper": {"width": 24.0, "height": 24.0},
 }
+#: Capsule bodies (cylinder with two dished heads) whose axis is vertical.
+_VERTICAL_CAPSULES = ("vertical_vessel", "column", "reactor")
 PARAMS_SCHEMA = {
-    "width": "float > 0 (mm)",
-    "height": "float > 0 (mm)",
+    "width": "float > 0 (mm); vertical_vessel/column/reactor need width < height",
+    "height": "float > 0 (mm); horizontal_vessel needs height < width; cone tank height > width/6",
     "nozzles": "[{name, side: top|bottom|left|right, fraction: 0..1}]",
     "roof": "tank only: flat | cone",
     "trays": "column only: int >= 0",
     "jacketed": "reactor only: bool",
 }
-#: Nozzle stub length beyond the vessel wall (symbol-local mm).
+#: Distance of a nozzle port beyond the vessel's bounding box (symbol-local mm);
+#: the stub runs from there in to the drawn outline, so it is at least this long.
 STUB = 3.0
 #: Gap between a jacketed reactor's wall and its jacket line.
 JACKET = 2.0
@@ -73,8 +81,23 @@ def validate_vessel_params(symbol: str, params: dict | None) -> dict:
         if not _is_number(v) or v <= 0:
             raise ValueError(f"{symbol}: {key} must be a number > 0")
         merged[key] = float(v)
+    w, h = merged["width"], merged["height"]
+    if symbol in _VERTICAL_CAPSULES and h <= w:
+        raise ValueError(
+            f"{symbol}: height {h} must exceed width {w} — the dished heads are half-circles "
+            "of the width, so a shorter axis folds them through each other"
+        )
+    if symbol == "horizontal_vessel" and w <= h:
+        raise ValueError(
+            f"{symbol}: width {w} must exceed height {h} — the dished heads are half-circles "
+            "of the height, so a shorter axis folds them through each other"
+        )
     if "roof" in merged and merged["roof"] not in ("flat", "cone"):
         raise ValueError(f"{symbol}: roof must be 'flat' or 'cone'")
+    if merged.get("roof") == "cone" and h <= w / 6:
+        raise ValueError(
+            f"{symbol}: height {h} must exceed width/6 ({w / 6}) — the cone roof is that tall"
+        )
     if "trays" in merged:
         trays = merged["trays"]
         if isinstance(trays, bool) or not isinstance(trays, int) or trays < 0:
@@ -92,6 +115,11 @@ def validate_vessel_params(symbol: str, params: dict | None) -> dict:
         if n["name"] in names:
             raise ValueError(f"{symbol}: nozzles[{i}].name {n['name']!r} is repeated")
         names.add(n["name"])
+        for key in n:
+            if key not in ("name", "side", "fraction"):
+                raise ValueError(
+                    f"{symbol}: nozzles[{i}]: unknown key {key!r}; valid: fraction, name, side"
+                )
         if n.get("side") not in SIDES:
             raise ValueError(f"{symbol}: nozzles[{i}].side must be one of {', '.join(SIDES)}")
         f = n.get("fraction", 0.5)
@@ -103,34 +131,42 @@ def validate_vessel_params(symbol: str, params: dict | None) -> dict:
 
 
 def _nozzles(
-    params: dict, half_w: float, half_h: float, extra: float = 0.0
+    nozzles: list[dict], shell: list[dict], half_w: float, half_h: float, extra: float = 0.0
 ) -> tuple[list[dict], list[Port]]:
-    """Nozzle stub primitives and ports on a box of ±half_w × ±half_h.
+    """Nozzle stub primitives and ports for a vessel whose outline is ``shell``.
 
-    ``extra`` lengthens the stubs (a jacketed reactor's nozzles pass through
-    the jacket) so every port still sits on the symbol's outer edge.
+    The port sits ``STUB + extra`` outside the ±half_w × ±half_h box (``extra``
+    is a jacketed reactor's jacket, which the stub passes through so the port
+    still sits on the symbol's outer edge); the stub starts where the port's
+    axis-aligned line meets the outermost point of the drawn outline.
     """
     prims: list[dict] = []
     ports: list[Port] = []
     stub = STUB + extra
-    for n in params["nozzles"]:
+    for n in nozzles:
         side, f = n["side"], n["fraction"]
-        if side == "top":
-            x, y0, y1 = -half_w + f * 2 * half_w, half_h, half_h + stub
+        if side in ("top", "bottom"):
+            x = -half_w + f * 2 * half_w
+            hits = scan_hits(shell, "x", x)
+            if not hits:
+                raise RuntimeError(f"nozzle {n['name']!r}: x={x} meets no outline")
+            if side == "top":
+                y0, y1, d = max(hits), half_h + stub, 90.0
+            else:
+                y0, y1, d = min(hits), -half_h - stub, 270.0
             prims.append(line(x, y0, x, y1))
-            ports.append(Port(n["name"], x, y1, 90.0))
-        elif side == "bottom":
-            x, y0, y1 = -half_w + f * 2 * half_w, -half_h, -half_h - stub
-            prims.append(line(x, y0, x, y1))
-            ports.append(Port(n["name"], x, y1, 270.0))
-        elif side == "left":
-            y, x0, x1 = -half_h + f * 2 * half_h, -half_w, -half_w - stub
+            ports.append(Port(n["name"], x, y1, d))
+        else:
+            y = -half_h + f * 2 * half_h
+            hits = scan_hits(shell, "y", y)
+            if not hits:
+                raise RuntimeError(f"nozzle {n['name']!r}: y={y} meets no outline")
+            if side == "left":
+                x0, x1, d = min(hits), -half_w - stub, 180.0
+            else:
+                x0, x1, d = max(hits), half_w + stub, 0.0
             prims.append(line(x0, y, x1, y))
-            ports.append(Port(n["name"], x1, y, 180.0))
-        else:  # right
-            y, x0, x1 = -half_h + f * 2 * half_h, half_w, half_w + stub
-            prims.append(line(x0, y, x1, y))
-            ports.append(Port(n["name"], x1, y, 0.0))
+            ports.append(Port(n["name"], x1, y, d))
     return prims, ports
 
 
@@ -162,13 +198,13 @@ def build_vessel(symbol: str = "vertical_vessel", params: dict | None = None) ->
     w, h = p["width"], p["height"]
     half_w, half_h = w / 2, h / 2
     extra = 0.0
-    if symbol == "vertical_vessel":
-        prims = _capsule_vertical(w, h)
+    if symbol in _VERTICAL_CAPSULES:
+        shell = _capsule_vertical(w, h)
     elif symbol == "horizontal_vessel":
-        prims = _capsule_horizontal(w, h)
+        shell = _capsule_horizontal(w, h)
     elif symbol == "tank":
         roof = w / 6 if p["roof"] == "cone" else 0.0
-        prims = [
+        shell = [
             polyline(
                 [
                     (-half_w, -half_h),
@@ -179,32 +215,30 @@ def build_vessel(symbol: str = "vertical_vessel", params: dict | None = None) ->
             )
         ]
         if roof:
-            prims.append(
+            shell.append(
                 polyline(
                     [(-half_w, half_h - roof), (0, half_h), (half_w, half_h - roof)],
                     closed=False,
                 )
             )
-    elif symbol == "column":
-        prims = _capsule_vertical(w, h)
+    else:  # hopper: flat top, walls converging to a narrow outlet
+        shell = [
+            polyline([(-half_w, half_h), (half_w, half_h), (w / 6, -half_h), (-w / 6, -half_h)])
+        ]
+    prims = list(shell)
+    if symbol == "column":
         trays = p["trays"]
         for i in range(trays):
             y = -half_h + (i + 1) * h / (trays + 1)
             prims.append(line(-half_w + 1, y, half_w - 1, y))
-    elif symbol == "reactor":
-        prims = _capsule_vertical(w, h)
-        if p["jacketed"]:
-            body = half_h - half_w
-            prims += [
-                line(-half_w - JACKET, -body, -half_w - JACKET, body),
-                line(half_w + JACKET, -body, half_w + JACKET, body),
-            ]
-            extra = JACKET
-    else:  # hopper: flat top, walls converging to a narrow outlet
-        prims = [
-            polyline([(-half_w, half_h), (half_w, half_h), (w / 6, -half_h), (-w / 6, -half_h)])
+    elif symbol == "reactor" and p["jacketed"]:
+        body = half_h - half_w
+        prims += [
+            line(-half_w - JACKET, -body, -half_w - JACKET, body),
+            line(half_w + JACKET, -body, half_w + JACKET, body),
         ]
-    nozzle_prims, ports = _nozzles(p, half_w, half_h, extra)
+        extra = JACKET
+    nozzle_prims, ports = _nozzles(p["nozzles"], shell, half_w, half_h, extra)
     prims += nozzle_prims
     xs = [-half_w - extra, half_w + extra] + [pt.x for pt in ports]
     ys = [-half_h, half_h] + [pt.y for pt in ports]