enginehall 2.0.0__py3-none-any.whl

pcba/adapters/altium_ops.py

@@ -0,0 +1,858 @@
+"""The operation catalogue: typed, validated requests rendered as bridge calls.
+
+An agent never sends DelphiScript. It sends operations such as
+`{"op": "sch_wire", "points": [[1000, 2000], [1500, 2000]]}`; this module checks each one
+against its schema and renders it as a call of a procedure in `altium_bridge/bridge.pas`
+with literal arguments. That keeps three promises the free-form script tool upstream could not:
+the code Altium runs is the hash-checked library, an argument can never become code, and a
+float can never meet a German decimal comma (every number reaches Altium as an integer).
+
+Units
+-----
+- Schematic and symbol coordinates: integer **mils** (use a 100 mil grid for pins and wires).
+- PCB and footprint coordinates and sizes: **millimetres** (floats), converted here to Altium's
+  internal units (1 mil = 10 000 units).
+- Angles: degrees.
+"""
+
+from __future__ import annotations
+
+import math
+import ntpath
+import re
+from typing import Any
+
+UNITS_PER_MM = 10000 / 0.0254  # Altium internal units per millimetre (1 mil = 10 000)
+
+ORIENT = {0: "eRotate0", 90: "eRotate90", 180: "eRotate180", 270: "eRotate270"}
+
+ELECTRICAL = {
+    "input": "eElectricInput",
+    "output": "eElectricOutput",
+    "io": "eElectricIO",
+    "passive": "eElectricPassive",
+    "power": "eElectricPower",
+    "oc": "eElectricOpenCollector",
+    "oe": "eElectricOpenEmitter",
+    "hiz": "eElectricHiZ",
+}
+
+POWER_STYLE = {
+    "bar": "ePowerBar",
+    "gnd": "ePowerGndPower",
+    "signal_gnd": "ePowerGndSignal",
+    "earth": "ePowerGndEarth",
+    "arrow": "ePowerArrow",
+    "circle": "ePowerCircle",
+    "wave": "ePowerWave",
+}
+
+SHEET = {s: f"eSheet{s}" for s in ("A4", "A3", "A2", "A1", "A0", "A", "B", "C", "D", "E")}
+
+# Ports and sheet entries: the signal direction, and a port's arrow shape (horizontal ports only).
+PORT_IO = {"unspecified": "ePortUnspecified", "output": "ePortOutput", "input": "ePortInput",
+           "bidirectional": "ePortBidirectional"}
+PORT_STYLE = {"none": "ePortNone", "left": "ePortLeft", "right": "ePortRight", "both": "ePortLeftRight"}
+ENTRY_SIDE = {"left": "False", "right": "True"}
+
+PAD_SHAPE = {
+    "rect": "eRectangular",
+    "round": "eRounded",
+    "oval": "eRounded",
+    "roundrect": "eRoundedRectangular",
+    "octagon": "eOctagonal",
+}
+
+# A Draftsman drawing's kind is PcbDrawing (measured): "PCBDWF" made a board saved under the
+# drawing's name, which Draftsman then refused as invalid data.
+DOC_KIND = {"SCH": "SCH", "PCB": "PCB", "SCHLIB": "SCHLIB", "PCBLIB": "PCBLIB", "OUTPUTJOB": "OUTPUTJOB",
+            "PCBDWF": "PcbDrawing", "PCBDRAWING": "PcbDrawing"}
+
+# Routing Corners style and Routing Topology, in Altium's enumeration order.
+CORNER = {"90": "0", "45": "1", "round": "2"}
+TOPOLOGY = {"shortest": "0", "horizontal": "1", "vertical": "2", "daisy_simple": "3", "daisy_mid_driven": "4",
+            "daisy_balanced": "5", "starburst": "6"}
+
+# Plane and polygon connect styles (TPlaneConnectStyle order) and relief spoke angles.
+CONNECT_STYLE = {"relief": "0", "direct": "1", "none": "2"}
+RELIEF_ENTRIES = {2: "2", 4: "4"}
+RELIEF_ANGLE = {45: "45", 90: "90"}
+
+# Altium rule kinds whose value is a single length (PcbRuleValue).
+RULE_KIND = {"plane_clearance": "12", "solder_mask_expansion": "13", "paste_mask_expansion": "14",
+             "component_clearance": "24", "hole_to_hole": "52"}
+ZOOM = {"": "", "Sch:Zoom": "Sch:Zoom", "PCB:Zoom": "PCB:Zoom"}
+
+
+def _layers() -> dict[str, str]:
+    layers = {
+        "top": "eTopLayer",
+        "bottom": "eBottomLayer",
+        "multi": "eMultiLayer",
+        "top_overlay": "eTopOverlay",
+        "bottom_overlay": "eBottomOverlay",
+        "top_paste": "eTopPaste",
+        "bottom_paste": "eBottomPaste",
+        "top_solder": "eTopSolder",
+        "bottom_solder": "eBottomSolder",
+        "keepout": "eKeepOutLayer",
+        "drill_guide": "eDrillGuide",
+        "drill_drawing": "eDrillDrawing",
+    }
+    layers.update({f"mid{i}": f"eMidLayer{i}" for i in range(1, 31)})
+    layers.update({f"plane{i}": f"eInternalPlane{i}" for i in range(1, 17)})
+    layers.update({f"mech{i}": f"eMechanical{i}" for i in range(1, 17)})
+    return layers
+
+
+LAYER = _layers()
+
+
+def _layer_numbers() -> dict[str, int]:
+    """Altium's TLayer numbers, as `O.Layer` reads them (pads report 74 for the multi-layer)."""
+    numbers = {"top": 1, "bottom": 32, "top_overlay": 33, "bottom_overlay": 34, "top_paste": 35,
+               "bottom_paste": 36, "top_solder": 37, "bottom_solder": 38, "drill_guide": 55, "keepout": 56,
+               "drill_drawing": 73, "multi": 74}
+    numbers.update({f"mid{i}": 1 + i for i in range(1, 31)})
+    numbers.update({f"plane{i}": 38 + i for i in range(1, 17)})
+    numbers.update({f"mech{i}": 56 + i for i in range(1, 17)})
+    return numbers
+
+
+LAYER_NUMBER = _layer_numbers()
+LAYER_BY_NUMBER = {v: k for k, v in LAYER_NUMBER.items()}
+PRIMITIVE_KINDS = ("track", "arc", "via", "fill", "region", "text")
+
+
+class OpError(ValueError):
+    """An operation failed validation. Raised before anything reaches Altium."""
+
+
+# --- literals ------------------------------------------------------------------------------
+
+
+def pascal_string(value: Any) -> str:
+    """A Pascal string literal. Printable ASCII is written as is; any other printable character
+    (a manufacturer name with an umlaut, a typographic apostrophe) as a Pascal character code
+    (`'W'#252'rth'`), so the script file itself stays ASCII. Control characters are refused."""
+    text = str(value)
+    if len(text) > 4000:
+        raise OpError("string longer than 4000 characters")
+    out, literal = [], []
+    for ch in text:
+        code = ord(ch)
+        if code < 32 or 0x7F <= code < 0xA0 or 0xD800 <= code <= 0xDFFF or code > 0xFFFF:
+            raise OpError(f"control or non-BMP character {ch!r} cannot reach Altium (in {text!r})")
+        if code > 126:
+            if literal:
+                out.append("'" + "".join(literal) + "'")
+                literal = []
+            out.append(f"#{code}")
+        else:
+            literal.append("''" if ch == "'" else ch)
+    if literal or not out:
+        out.append("'" + "".join(literal) + "'")
+    return "".join(out)
+
+
+def mm(value: Any, name: str) -> int:
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value):
+        raise OpError(f"{name} must be a number of millimetres, got {value!r}")
+    if abs(value) > 10000:
+        raise OpError(f"{name} = {value} mm is out of range")
+    return round(value * UNITS_PER_MM)
+
+
+def mils(value: Any, name: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise OpError(f"{name} must be an integer number of mils, got {value!r}")
+    if abs(value) > 200000:
+        raise OpError(f"{name} = {value} mil is out of range")
+    return value
+
+
+def integer(value: Any, name: str, lo: int = -(2**31), hi: int = 2**31 - 1) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not lo <= value <= hi:
+        raise OpError(f"{name} must be an integer in [{lo}, {hi}], got {value!r}")
+    return value
+
+
+def boolean(value: Any, name: str) -> str:
+    if not isinstance(value, bool):
+        raise OpError(f"{name} must be true or false, got {value!r}")
+    return "True" if value else "False"
+
+
+def signal_layers(value: Any, name: str) -> str:
+    """Signal layer names as Altium layer numbers between bars: ["top", "bottom"] -> "|1|32|"."""
+    numbers = {"top": 1, "bottom": 32, **{f"mid{i}": 1 + i for i in range(1, 31)}}
+    if not isinstance(value, list) or not value or any(v not in numbers for v in value):
+        raise OpError(f"{name} must be a non-empty list of signal layers (top, mid1..mid30, bottom), got {value!r}")
+    return "|" + "|".join(str(numbers[v]) for v in value) + "|"
+
+
+# Query functions that take one name. Altium needs the name quoted (`InNetClass('LED')`); a bare
+# name made a rule whose scope matched nothing, and the next ECO raised a script error (#41).
+QUERY_NAME_FUNCTIONS = (
+    "InNet", "InNetClass", "InNetClassComplete", "InComponent", "InComponentClass", "InDifferentialPair",
+    "InDifferentialPairClass", "InPadClass", "InPolygon", "InPolygonClass", "InRoom", "InLayerClass",
+    "InFromTo", "InFromToClass", "InXSignal", "InXSignalClass", "OnLayer", "HasFootprint",
+)
+_QUERY_BARE = re.compile(r"\b(" + "|".join(QUERY_NAME_FUNCTIONS) + r")\(\s*([^'\"()\s][^'\"()]*?)\s*\)")
+
+
+def query_scope(value: Any, name: str) -> str:
+    """An Altium query expression for a rule scope. A bare name in a one-name query function is
+    quoted (`InNetClass(LED)` -> `InNetClass('LED')`); unbalanced quotes or brackets are refused,
+    because Altium would take the rule and then fail it later, in the middle of an ECO."""
+    if not isinstance(value, str) or not value.strip():
+        raise OpError(f"{name} must be an Altium query such as All or InNetClass('PWR'), got {value!r}")
+    if len(value) > 4000:
+        raise OpError(f"{name} is longer than 4000 characters")
+    # Only outside quoted literals: a quoted class name stays exactly as given.
+    parts = re.split(r"('[^']*')", value.strip())
+    text = "".join(part if i % 2 else _QUERY_BARE.sub(lambda m: f"{m.group(1)}('{m.group(2)}')", part)
+                   for i, part in enumerate(parts))
+    if text.count("'") % 2:
+        raise OpError(f"{name} has an unclosed quote: {value!r}")
+    depth = 0
+    for ch in re.sub(r"'[^']*'", "", text):
+        depth += (ch == "(") - (ch == ")")
+        if depth < 0:
+            break
+    if depth:
+        raise OpError(f"{name} has unbalanced brackets: {value!r}")
+    return text
+
+
+def enum(table: dict, value: Any, name: str) -> str:
+    if value not in table:
+        raise OpError(f"{name} must be one of {sorted(map(str, table))}, got {value!r}")
+    return table[value]
+
+
+def angle(value: Any, name: str) -> int:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise OpError(f"{name} must be degrees")
+    return int(round(value)) % 360
+
+
+def points(value: Any, name: str, conv, minimum: int) -> str:
+    if not isinstance(value, list) or len(value) < minimum:
+        raise OpError(f"{name} must be a list of at least {minimum} [x, y] points")
+    flat = []
+    for i, pt in enumerate(value):
+        if not isinstance(pt, (list, tuple)) or len(pt) != 2:
+            raise OpError(f"{name}[{i}] must be [x, y]")
+        flat += [conv(pt[0], f"{name}[{i}].x"), conv(pt[1], f"{name}[{i}].y")]
+    return pascal_string(",".join(str(v) for v in flat))
+
+
+def _get(op: dict, key: str, default: Any = ...) -> Any:
+    if not isinstance(op, dict):
+        raise OpError(f"expected an object with {key!r}, got {type(op).__name__} {op!r}"[:200])
+    if key in op:
+        return op[key]
+    if default is ...:
+        raise OpError(f"operation {op.get('op')!r} needs {key!r}")
+    return default
+
+
+def _objects(op: dict, key: str, required: bool = False) -> list[dict]:
+    """A list argument whose items are objects (pins, pads, tracks, ...), checked item by item."""
+    items = _get(op, key) if required else _get(op, key, [])
+    if not isinstance(items, list) or (required and not items):
+        raise OpError(f"{key} must be a {'non-empty ' if required else ''}list of objects")
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise OpError(f"{key}[{i}] must be an object, got {type(item).__name__}")
+    return items
+
+
+def _call(name: str, *args: str) -> str:
+    return f"{name}({', '.join(args)});" if args else f"{name};"
+
+
+# --- renderers -----------------------------------------------------------------------------
+
+
+def _symbol(op: dict) -> list[str]:
+    calls = [
+        _call(
+            "SymBegin",
+            pascal_string(_get(op, "lib")),
+            pascal_string(_get(op, "name")),
+            pascal_string(_get(op, "description", "")),
+            pascal_string(_get(op, "prefix", "U")),
+            pascal_string(_get(op, "comment", _get(op, "name"))),
+            pascal_string(_get(op, "footprint", "")),
+            str(integer(_get(op, "part_count", 1), "part_count", 1, 64)),
+        )
+    ]
+    # Graphics first: Altium draws in insertion order, and a solid body drawn after the pins
+    # paints over their names.
+    for i, r in enumerate(_objects(op, "rects")):
+        calls.append(_call("SymRect", *(str(mils(_get(r, k), f"rects[{i}].{k}")) for k in ("x1", "y1", "x2", "y2")),
+                           str(integer(_get(r, "part", 1), "part", 0, 64))))
+    for i, ln in enumerate(_objects(op, "lines")):
+        calls.append(_call("SymLine", *(str(mils(_get(ln, k), f"lines[{i}].{k}")) for k in ("x1", "y1", "x2", "y2")),
+                           str(integer(_get(ln, "part", 1), "part", 0, 64))))
+    for i, t in enumerate(_objects(op, "texts")):
+        calls.append(_call("SymText", pascal_string(_get(t, "text")), str(mils(_get(t, "x"), "x")),
+                           str(mils(_get(t, "y"), "y")), str(integer(_get(t, "part", 1), "part", 0, 64))))
+    pins = _objects(op, "pins", required=True)
+    seen = set()
+    for i, pin in enumerate(pins):
+        number = str(_get(pin, "number"))
+        if number in seen:
+            raise OpError(f"pin number {number} appears twice")
+        seen.add(number)
+        calls.append(
+            _call(
+                "SymPin",
+                pascal_string(number),
+                pascal_string(_get(pin, "name", number)),
+                enum(ELECTRICAL, _get(pin, "electrical", "passive"), f"pins[{i}].electrical"),
+                str(mils(_get(pin, "x"), f"pins[{i}].x")),
+                str(mils(_get(pin, "y"), f"pins[{i}].y")),
+                enum(ORIENT, _get(pin, "orientation"), f"pins[{i}].orientation"),
+                str(mils(_get(pin, "length", 200), f"pins[{i}].length")),
+                str(integer(_get(pin, "part", 1), f"pins[{i}].part", 0, 64)),
+                boolean(_get(pin, "show_name", True), "show_name"),
+                boolean(_get(pin, "hidden", False), "hidden"),
+            )
+        )
+    params = _get(op, "params", {})
+    if not isinstance(params, dict):
+        raise OpError("params must be an object of name: value")
+    for key, value in params.items():
+        calls.append(_call("SymParam", pascal_string(key), pascal_string(value), "False"))
+    calls.append(_call("SymEnd"))
+    return calls
+
+
+def _sheet_symbol(op: dict) -> list[str]:
+    """A sheet symbol for a child sheet with its entries. Entries sit on the left or right edge,
+    `offset` mils below the top; their electrical points are reported back."""
+    name, file = _get(op, "designator"), _get(op, "file")
+    if not isinstance(name, str) or not name.strip():
+        raise OpError("designator must be the sheet symbol's name")
+    if not isinstance(file, str) or not file.lower().endswith(".schdoc"):
+        raise OpError(f"file must name the child .SchDoc as the project lists it, got {file!r}")
+    width = mils(_get(op, "width"), "width")
+    height = mils(_get(op, "height"), "height")
+    if width < 100 or height < 100:
+        raise OpError("width and height must be at least 100 mil")
+    calls = [_call("SchSheetSymBegin", pascal_string(name), pascal_string(file), str(mils(_get(op, "x"), "x")),
+                   str(mils(_get(op, "y"), "y")), str(width), str(height))]
+    seen = set()
+    for i, entry in enumerate(_objects(op, "entries")):
+        entry_name = _get(entry, "name")
+        if not isinstance(entry_name, str) or not entry_name.strip():
+            raise OpError(f"entries[{i}].name must be the net it carries")
+        if entry_name.upper() in seen:
+            raise OpError(f"entry {entry_name} appears twice")
+        seen.add(entry_name.upper())
+        offset = mils(_get(entry, "offset"), f"entries[{i}].offset")
+        if not 0 < offset < height:
+            raise OpError(f"entries[{i}].offset must lie inside the symbol (0 < offset < {height}), got {offset}")
+        calls.append(_call("SchSheetEntry", pascal_string(entry_name),
+                           enum(ENTRY_SIDE, _get(entry, "side", "left"), f"entries[{i}].side"), str(offset),
+                           enum(PORT_IO, _get(entry, "io", "unspecified"), f"entries[{i}].io")))
+    calls.append(_call("SchSheetSymEnd"))
+    return calls
+
+
+def _footprint(op: dict) -> list[str]:
+    calls = [
+        _call(
+            "FpBegin",
+            pascal_string(_get(op, "lib")),
+            pascal_string(_get(op, "name")),
+            pascal_string(_get(op, "description", "")),
+            str(mm(_get(op, "height", 0.0), "height")),
+        )
+    ]
+    pads = _objects(op, "pads", required=True)
+    for i, pad in enumerate(pads):
+        hole = _get(pad, "hole", 0.0)
+        layer = _get(pad, "layer", "multi" if hole else "top")
+        if hole and layer != "multi":
+            raise OpError(f"pads[{i}] has a hole, so its layer must be 'multi'")
+        calls.append(
+            _call(
+                "FpPad",
+                pascal_string(_get(pad, "name")),
+                str(mm(_get(pad, "x"), f"pads[{i}].x")),
+                str(mm(_get(pad, "y"), f"pads[{i}].y")),
+                enum(PAD_SHAPE, _get(pad, "shape", "rect"), f"pads[{i}].shape"),
+                str(mm(_get(pad, "w"), f"pads[{i}].w")),
+                str(mm(_get(pad, "h"), f"pads[{i}].h")),
+                str(angle(_get(pad, "rotation", 0), "rotation")),
+                enum(LAYER, layer, f"pads[{i}].layer"),
+                str(mm(hole, f"pads[{i}].hole")),
+                boolean(_get(pad, "plated", True), "plated"),
+                str(integer(_get(pad, "corner_pct", 25), "corner_pct", 0, 100)),
+                boolean(_get(pad, "mask_expansion", None) is not None, "mask_expansion"),
+                str(mm(_get(pad, "mask_expansion", None) or 0.0, f"pads[{i}].mask_expansion")),
+                boolean(_get(pad, "paste", True), "paste"),
+            )
+        )
+    for i, t in enumerate(_objects(op, "tracks")):
+        calls.append(_call("FpTrack", enum(LAYER, _get(t, "layer"), f"tracks[{i}].layer"),
+                           *(str(mm(_get(t, k), f"tracks[{i}].{k}")) for k in ("x1", "y1", "x2", "y2", "width"))))
+    for i, a in enumerate(_objects(op, "arcs")):
+        calls.append(_call("FpArc", enum(LAYER, _get(a, "layer"), f"arcs[{i}].layer"),
+                           str(mm(_get(a, "xc"), "xc")), str(mm(_get(a, "yc"), "yc")), str(mm(_get(a, "r"), "r")),
+                           str(angle(_get(a, "start", 0), "start")), str(angle(_get(a, "end", 360), "end") or 360),
+                           str(mm(_get(a, "width"), "width"))))
+    for i, b in enumerate(_objects(op, "bodies")):
+        calls.append(_call("FpBody", points(_get(b, "outline"), f"bodies[{i}].outline", mm, 3),
+                           str(mm(_get(b, "standoff", 0.0), "standoff")), str(mm(_get(b, "height"), "height")),
+                           enum(LAYER, _get(b, "layer", "mech13"), "layer")))
+    for i, m in enumerate(_objects(op, "models")):
+        calls.append(_model(m, f"models[{i}]"))
+    calls.append(_call("FpEnd"))
+    return calls
+
+
+def _triple(value: Any, name: str, conv) -> list:
+    if not isinstance(value, list) or len(value) != 3:
+        raise OpError(f"{name} must be a list of three numbers [x, y, z]")
+    return [conv(v, f"{name}[{k}]") for k, v in enumerate(value)]
+
+
+def _model(m: dict, where: str) -> str:
+    """A STEP model embedded in the footprint as a 3D body. Altium rotates the model about its own
+    origin, X then Y then Z, lifts it by the Z offset, then moves it by the X/Y offset."""
+    path = _get(m, "file")
+    if not isinstance(path, str) or not path.lower().endswith((".step", ".stp")):
+        raise OpError(f"{where}.file must be a .step or .stp path")
+    rx, ry, rz = _triple(_get(m, "rotation", [0, 0, 0]), f"{where}.rotation", angle)
+    dx, dy, dz = _triple(_get(m, "offset", [0, 0, 0]), f"{where}.offset", mm)
+    return _call("FpModel", pascal_string(path), str(rx), str(ry), str(rz), str(dx), str(dy), str(dz),
+                 enum(LAYER, _get(m, "layer", "mech13"), f"{where}.layer"))
+
+
+def _track(op: dict) -> list[str]:
+    pts = _get(op, "points")
+    if not isinstance(pts, list) or len(pts) < 2:
+        raise OpError("pcb_track needs at least two points")
+    net = pascal_string(_get(op, "net", ""))
+    layer = enum(LAYER, _get(op, "layer"), "layer")
+    width = str(mm(_get(op, "width"), "width"))
+    locked = boolean(_get(op, "locked", False), "locked")
+    calls = []
+    for i in range(len(pts) - 1):
+        (x1, y1), (x2, y2) = pts[i], pts[i + 1]
+        calls.append(_call("PcbTrack", net, layer, str(mm(x1, "x")), str(mm(y1, "y")),
+                           str(mm(x2, "x")), str(mm(y2, "y")), width, locked))
+    return calls
+
+
+def _text_set(op: dict) -> list[str]:
+    """Change one free PCB text, found by its whole text (and `layer`, if given). Only the keys
+    present are changed: x and y together, height, rotation, mirror, text."""
+    fields = ""
+    if "x" in op or "y" in op:
+        _get(op, "x"), _get(op, "y")
+        fields += "p"
+    for key, flag in (("height", "h"), ("rotation", "r"), ("mirror", "m"), ("text", "t")):
+        if key in op:
+            fields += flag
+    if not fields:
+        raise OpError("pcb_text_set changes nothing: give x and y, height, rotation, mirror or text")
+    layer = _get(op, "layer", None)
+    if layer is not None:
+        enum(LAYER, layer, "layer")
+    return [_call(
+        "PcbTextSet",
+        pascal_string(_get(op, "match")),
+        "-1" if layer is None else str(LAYER_NUMBER[layer]),
+        pascal_string(fields),
+        str(mm(_get(op, "x", 0.0), "x")),
+        str(mm(_get(op, "y", 0.0), "y")),
+        str(mm(_get(op, "height", 1.0), "height")),
+        str(angle(_get(op, "rotation", 0), "rotation")),
+        boolean(_get(op, "mirror", False), "mirror"),
+        pascal_string(_get(op, "text", "")),
+    )]
+
+
+def _simple(name: str, *spec):
+    """Renderer for an op whose arguments map one-to-one to a bridge procedure."""
+
+    def render(op: dict) -> list[str]:
+        args = []
+        for key, kind, default in spec:
+            value = _get(op, key, default)
+            if kind == "str":
+                args.append(pascal_string(value))
+            elif kind == "mils":
+                args.append(str(mils(value, key)))
+            elif kind == "mm":
+                args.append(str(mm(value, key)))
+            elif kind == "int":
+                args.append(str(integer(value, key)))
+            elif kind == "angle":
+                args.append(str(angle(value, key)))
+            elif kind == "end_angle":  # 360 is a full sweep, not 0
+                args.append(str(angle(value, key) or 360))
+            elif kind == "bool":
+                args.append(boolean(value, key))
+            elif kind == "orient":
+                args.append(enum(ORIENT, value, key))
+            elif kind == "layer":
+                args.append(enum(LAYER, value, key))
+            elif kind == "power":
+                args.append(enum(POWER_STYLE, value, key))
+            elif kind == "sheet":
+                args.append(enum(SHEET, value, key))
+            elif kind == "part":  # one part of a (multi-part) component
+                args.append(str(integer(value, key, 1, 64)))
+            elif kind == "part_any":  # 0: every part, or the only one
+                args.append(str(integer(value, key, 0, 64)))
+            elif kind == "length_mils":
+                if mils(value, key) < 100:
+                    raise OpError(f"{key} must be at least 100 mil, got {value!r}")
+                args.append(str(value))
+            elif kind == "scope":
+                args.append(pascal_string(query_scope(value, key)))
+            elif kind == "connect_style":
+                args.append(enum(CONNECT_STYLE, value, key))
+            elif kind == "relief_entries":
+                args.append(enum(RELIEF_ENTRIES, value, key))
+            elif kind == "relief_angle":
+                args.append(enum(RELIEF_ANGLE, value, key))
+            elif kind == "port_io":
+                args.append(enum(PORT_IO, value, key))
+            elif kind == "port_style":
+                args.append(enum(PORT_STYLE, value, key))
+            elif kind == "kind":
+                args.append(pascal_string(enum(DOC_KIND, str(value).upper(), key)))
+            elif kind == "zoom":
+                args.append(pascal_string(enum(ZOOM, value, key)))
+            elif kind == "rule_kind":
+                args.append(enum(RULE_KIND, value, key))
+            elif kind == "corner":
+                args.append(enum(CORNER, str(value), key))
+            elif kind == "topology":
+                args.append(enum(TOPOLOGY, value, key))
+            elif kind == "priority":
+                args.append(str(integer(value, key, 0, 100)))
+            elif kind == "side":
+                args.append(boolean(enum({"top": False, "bottom": True}, value, key), key))
+            elif kind == "mils_points":
+                args.append(points(value, key, mils, 2))
+            elif kind == "mm_points":
+                args.append(points(value, key, mm, 3))
+            elif kind == "signal_layers":
+                args.append(pascal_string(signal_layers(value, key)))
+            elif kind == "csv":
+                if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                    raise OpError(f"{key} must be a list of names")
+                args.append(pascal_string(",".join(value)))
+            elif kind == "save_mode":
+                args.append(boolean(enum({"all": True, "none": False}, value, key), key))
+            elif kind == "primitive_kinds":
+                if not isinstance(value, list) or not value or any(v not in PRIMITIVE_KINDS for v in value):
+                    raise OpError(f"{key} must be a non-empty list of {sorted(PRIMITIVE_KINDS)}, got {value!r}")
+                args.append(pascal_string(",".join(dict.fromkeys(value))))
+            elif kind == "layer_filter":
+                if not isinstance(value, list) or any(v not in LAYER for v in value):
+                    raise OpError(f"{key} must be a list of layer names (empty for every layer), got {value!r}")
+                args.append(pascal_string("".join(f"|{LAYER_NUMBER[v]}" for v in value) + ("|" if value else "")))
+            elif kind == "layer_or_any":
+                if value is not None:
+                    enum(LAYER, value, key)
+                args.append("-1" if value is None else str(LAYER_NUMBER[value]))
+            else:  # pragma: no cover - programming error
+                raise AssertionError(kind)
+        return [_call(name, *args)]
+
+    return render
+
+
+OPS: dict[str, Any] = {
+    # workspace and documents
+    "project_open": _simple("ProjectOpen", ("path", "str", ...)),
+    "project_close": _simple("ProjectClose", ("path", "str", ...), ("save", "save_mode", "all")),
+    "project_state": _simple("ProjectState", ("path", "str", "")),
+    "project_save": _simple("ProjectSave", ("path", "str", ...)),
+    "project_netlist": _simple("ProjectNetlist", ("path", "str", ...), ("reopen", "bool", False)),
+    "doc_create": _simple("DocCreate", ("kind", "kind", ...), ("path", "str", ...), ("project", "str", "")),
+    "doc_save": _simple("DocSave", ("path", "str", ...)),
+    "doc_close": _simple("DocClose", ("path", "str", ...), ("save", "bool", True)),
+    "doc_focus": _simple("DocFocus", ("kind", "kind", ...), ("path", "str", ...), ("zoom", "zoom", "")),
+    # libraries
+    "symbol": _symbol,
+    "footprint": _footprint,
+    # schematic
+    "sch_open": _simple("SchOpen", ("path", "str", ...)),
+    "sch_clear": _simple("SchClear"),
+    "sch_clear_wiring": _simple("SchClearWiring"),
+    "sch_move": _simple("SchMove", ("designator", "str", ...), ("x", "mils", ...), ("y", "mils", ...),
+                        ("orientation", "orient", 0), ("mirrored", "bool", False), ("part", "part_any", 0)),
+    "sch_part_texts": _simple("SchPartTexts", ("designator", "str", ...), ("dx", "mils", ...), ("dy", "mils", ...),
+                              ("x", "mils", ...), ("y", "mils", ...), ("step", "mils", 100)),
+    "sch_sheet": _simple("SchSheet", ("size", "sheet", "A3"), ("title", "str", ""),
+                         ("revision", "str", ""), ("document_number", "str", ""), ("sheet_number", "str", "1"),
+                         ("sheet_total", "str", "1")),
+    "sch_delete": _simple("SchDelete", ("designator", "str", ...), ("part", "part_any", 0)),
+    "sch_unique_id": _simple("SchUniqueId", ("designator", "str", ...), ("unique_id", "str", ...)),
+    "sch_sheet_param": _simple("SchAddSheetParam", ("name", "str", ...), ("value", "str", ...)),
+    "sch_place": _simple("SchPlace", ("lib", "str", ...), ("lib_ref", "str", ...), ("designator", "str", ...),
+                         ("x", "mils", ...), ("y", "mils", ...), ("orientation", "orient", 0),
+                         ("comment", "str", ""), ("part", "part", 1)),
+    "sch_param": _simple("SchParam", ("designator", "str", ...), ("name", "str", ...), ("value", "str", ...),
+                         ("visible", "bool", False)),
+    "sch_param_remove": _simple("SchParamRemove", ("designator", "str", ...), ("name", "str", ...)),
+    "sch_component_kind": _simple("SchComponentKind", ("designator", "str", ...), ("no_bom", "bool", ...)),
+    "sch_wire": _simple("SchWire", ("points", "mils_points", ...)),
+    "sch_label": _simple("SchLabel", ("text", "str", ...), ("x", "mils", ...), ("y", "mils", ...),
+                         ("orientation", "orient", 0)),
+    "sch_power": _simple("SchPower", ("text", "str", ...), ("x", "mils", ...), ("y", "mils", ...),
+                         ("style", "power", "bar"), ("orientation", "orient", 90)),
+    "sch_noerc": _simple("SchNoErc", ("x", "mils", ...), ("y", "mils", ...)),
+    "sch_junction": _simple("SchJunction", ("x", "mils", ...), ("y", "mils", ...)),
+    "sch_text": _simple("SchText", ("text", "str", ...), ("x", "mils", ...), ("y", "mils", ...),
+                        ("orientation", "orient", 0)),
+    "sch_sheet_symbol": _sheet_symbol,
+    "sch_port": _simple("SchPort", ("name", "str", ...), ("x", "mils", ...), ("y", "mils", ...),
+                        ("width", "length_mils", 600), ("style", "port_style", "right"),
+                        ("io", "port_io", "unspecified")),
+    "sch_save": _simple("SchSave"),
+    "sch_pins": _simple("SchPins", ("designator", "str", ...), ("part", "part_any", 0)),
+    "sch_components": _simple("SchComponents"),
+    # PCB
+    "pcb_open": _simple("PcbOpen", ("path", "str", ...)),
+    "pcb_origin": _simple("PcbOrigin", ("x", "mm", ...), ("y", "mm", ...)),
+    "pcb_outline": _simple("PcbOutline", ("points", "mm_points", ...)),
+    "pcb_place": _simple("PcbPlace", ("designator", "str", ...), ("x", "mm", ...), ("y", "mm", ...),
+                         ("rotation", "angle", 0), ("side", "side", "top")),
+    "pcb_track": _track,
+    "pcb_arc": _simple("PcbArc", ("net", "str", ""), ("layer", "layer", ...), ("xc", "mm", ...), ("yc", "mm", ...),
+                       ("r", "mm", ...), ("start", "angle", 0), ("end", "end_angle", 360), ("width", "mm", ...)),
+    "pcb_via": _simple("PcbVia", ("net", "str", ""), ("x", "mm", ...), ("y", "mm", ...), ("hole", "mm", 0.3),
+                       ("diameter", "mm", 0.6), ("locked", "bool", False)),
+    "pcb_polygon": _simple("PcbPolygon", ("net", "str", ""), ("layer", "layer", ...), ("points", "mm_points", ...),
+                           ("name", "str", ""), ("clearance", "mm", 0.0)),
+    "pcb_region": _simple("PcbRegion", ("net", "str", ""), ("layer", "layer", ...), ("points", "mm_points", ...)),
+    "pcb_text_replace": _simple("PcbTextReplace", ("old", "str", ...), ("new", "str", ...)),
+    "pcb_text_set": _text_set,
+    "pcb_text": _simple("PcbText", ("layer", "layer", ...), ("x", "mm", ...), ("y", "mm", ...), ("height", "mm", 1.0),
+                        ("rotation", "angle", 0), ("text", "str", ...), ("mirror", "bool", False)),
+    "pcb_rule_clearance": _simple("PcbRuleClearance", ("name", "str", ...), ("scope1", "scope", "All"),
+                                  ("scope2", "scope", "All"), ("gap", "mm", ...)),
+    "pcb_rule_width": _simple("PcbRuleWidth", ("name", "str", ...), ("scope", "scope", ...), ("min", "mm", ...),
+                              ("preferred", "mm", ...), ("max", "mm", ...)),
+    "pcb_rule_via": _simple("PcbRuleVia", ("name", "str", ...), ("scope", "scope", "All"), ("hole_min", "mm", ...),
+                            ("hole", "mm", ...), ("hole_max", "mm", ...), ("diameter_min", "mm", ...),
+                            ("diameter", "mm", ...), ("diameter_max", "mm", ...)),
+    "pcb_rule_delete": _simple("PcbRuleDelete", ("name", "str", ...)),
+    "pcb_rule_value": _simple("PcbRuleValue", ("name", "str", ...), ("kind", "rule_kind", ...),
+                              ("scope1", "scope", "All"), ("scope2", "scope", "All"), ("value", "mm", ...),
+                              ("vertical", "mm", 0.0)),
+    "pcb_rule_routing_layers": _simple("PcbRuleRoutingLayers", ("name", "str", "RoutingLayers"),
+                                       ("scope", "scope", "All"), ("layers", "signal_layers", ...)),
+    "pcb_rule_hole_size": _simple("PcbRuleHoleSize", ("name", "str", "HoleSize"), ("min", "mm", ...),
+                                  ("max", "mm", ...)),
+    "pcb_rule_silk_to_silk": _simple("PcbRuleSilkToSilk", ("name", "str", "SilkToSilkClearance"), ("gap", "mm", ...)),
+    "pcb_rule_mask_sliver": _simple("PcbRuleMaskSliver", ("name", "str", "MinimumSolderMaskSliver"),
+                                    ("gap", "mm", ...)),
+    "pcb_rule_corners": _simple("PcbRuleCorners", ("name", "str", "RoutingCorners"), ("scope", "scope", "All"),
+                                ("style", "corner", "45"), ("setback_min", "mm", 0.1), ("setback_max", "mm", 0.1)),
+    "pcb_rule_priority": _simple("PcbRulePriority", ("name", "str", ...), ("scope", "scope", ...),
+                                 ("priority", "priority", ...)),
+    "pcb_rule_topology": _simple("PcbRuleTopology", ("name", "str", "RoutingTopology"), ("scope", "scope", "All"),
+                                 ("topology", "topology", "shortest")),
+    "pcb_diff_pairs": _simple("PcbDiffPairs"),
+    "pcb_diff_pair": _simple("PcbDiffPair", ("name", "str", ...), ("positive", "str", ...), ("negative", "str", ...)),
+    "pcb_rule_diff_pair": _simple("PcbRuleDiffPair", ("name", "str", ...), ("scope", "scope", "IsDifferentialPair"),
+                                  ("width_min", "mm", ...), ("width", "mm", ...), ("width_max", "mm", ...),
+                                  ("gap_min", "mm", ...), ("gap", "mm", ...), ("gap_max", "mm", ...),
+                                  ("uncoupled_max", "mm", 6.0)),
+    "pcb_rule_plane_connect": _simple("PcbRulePlaneConnect", ("name", "str", "PlaneConnect"), ("scope", "scope", "All"),
+                                      ("style", "connect_style", "relief"), ("conductor_width", "mm", 0.254),
+                                      ("entries", "relief_entries", 4), ("air_gap", "mm", 0.254),
+                                      ("expansion", "mm", 0.508)),
+    "pcb_rule_polygon_connect": _simple("PcbRulePolygonConnect", ("name", "str", "PolygonConnect"),
+                                        ("scope", "scope", "All"), ("style", "connect_style", "relief"),
+                                        ("conductor_width", "mm", 0.254), ("entries", "relief_entries", 4),
+                                        ("angle", "relief_angle", 90), ("air_gap", "mm", 0.254)),
+    "pcb_tent_vias": _simple("PcbTentVias", ("top", "bool", True), ("bottom", "bool", True)),
+    "pcb_remove_components": _simple("PcbRemoveComponents", ("designators", "csv", ...)),
+    "pcb_clear_texts": _simple("PcbClearTexts", ("layer", "layer", ...)),
+    "pcb_clear_layer": _simple("PcbClearLayer", ("layer", "layer", ...)),
+    "pcb_designator": _simple("PcbDesignator", ("designator", "str", ...), ("show", "bool", True), ("x", "mm", 0.0),
+                              ("y", "mm", 0.0), ("height", "mm", 0.8), ("rotation", "angle", 0)),
+    "pcb_netclass": _simple("PcbNetClass", ("name", "str", ...), ("nets", "csv", ...)),
+    "pcb_plane_net": _simple("PcbPlaneNet", ("layer", "layer", ...), ("net", "str", ...), ("pullback", "mm", 0.5)),
+    "pcb_copper": _simple("PcbCopper", ("layer", "layer", ...), ("copper", "mm", ...)),
+    "pcb_dielectric": _simple("PcbDielectric", ("layer", "layer", ...), ("height", "mm", ...), ("copper", "mm", 0.035)),
+    "pcb_unroute": _simple("PcbUnroute", ("nets", "csv", ...), ("include_locked", "bool", False)),
+    "pcb_delete_track": _simple("PcbDeleteTrack", ("layer", "layer", ...), ("x1", "mm", ...), ("y1", "mm", ...),
+                                ("x2", "mm", ...), ("y2", "mm", ...)),
+    "pcb_delete_polygon": _simple("PcbDeletePolygon", ("name", "str", ...)),
+    "pcb_delete_via": _simple("PcbDeleteVia", ("x", "mm", ...), ("y", "mm", ...), ("net", "str", "")),
+    "pcb_track_end": _simple("PcbTrackEnd", ("net", "str", ...), ("layer", "layer", ...), ("x", "mm", ...),
+                             ("y", "mm", ...), ("to_x", "mm", ...), ("to_y", "mm", ...)),
+    "pcb_repour": _simple("PcbRepour"),
+    "pcb_save": _simple("PcbSave"),
+    "pcb_components": _simple("PcbComponents"),
+    "pcb_pads": _simple("PcbPads"),
+    "pcb_nets": _simple("PcbNets"),
+    "pcb_layers": _simple("PcbLayers"),
+    "pcb_board_outline": _simple("PcbBoardOutline"),
+    "pcb_bodies": _simple("PcbBodies"),
+    "pcb_rules": _simple("PcbRules"),
+    "pcb_polygons": _simple("PcbPolygons"),
+    "pcb_primitives": _simple("PcbPrimitives", ("kinds", "primitive_kinds", list(PRIMITIVE_KINDS)),
+                              ("layers", "layer_filter", []), ("offset", "int", 0), ("limit", "int", 2000)),
+    "pcb_add_layer": _simple("PcbAddLayer", ("layer", "layer", ...)),
+    # outputs
+    "outjob_run": _simple("OutJobRun", ("outjob", "str", ...), ("project", "str", ""),
+                          ("medium", "str", "Folder Structure")),
+}
+
+READ_ONLY = {
+    "project_netlist", "sch_pins", "sch_components", "pcb_components", "pcb_pads", "pcb_nets",
+    "pcb_layers", "pcb_board_outline", "pcb_rules", "pcb_bodies", "doc_focus", "project_open", "sch_open", "pcb_open",
+    "project_state", "pcb_polygons", "pcb_primitives", "pcb_diff_pairs",
+}
+
+# Operations that remove design content in bulk, or give a placed part a new identity. A plan
+# with any of them needs `allow_destructive`: a full rebuild for a local change once replaced a
+# board's reviewed routing.
+DESTRUCTIVE = {
+    "pcb_unroute": "removes the routing of whole nets",
+    "pcb_remove_components": "removes placed components and their copper links",
+    "pcb_clear_layer": "removes every free primitive of a layer",
+    "pcb_clear_texts": "removes every free text of a layer",
+    "pcb_delete_polygon": "removes a polygon pour",
+    "sch_clear": "removes everything on the sheet",
+    "sch_clear_wiring": "removes the sheet's wires, labels and ports",
+    "sch_delete": "removes a schematic part: the PCB link to it is lost",
+}
+
+
+def destructive(ops: list[dict]) -> list[dict]:
+    """The operations of a plan that need `allow_destructive`, with what each removes."""
+    return [{"op": i, "name": op["op"], "removes": DESTRUCTIVE[op["op"]]}
+            for i, op in enumerate(ops) if op.get("op") in DESTRUCTIVE]
+
+
+# Operation fields that name a file. Altium compares open projects and documents by their path text
+# (SameText): an op naming "C:/a/b.PrjPcb" did not find the project open as "C:\a\b.PrjPcb" and
+# opened it a second time, after which reads, DRC and outputs met either copy (measured).
+PATH_KEYS = frozenset({"path", "project", "lib", "outjob"})
+_ABSOLUTE = re.compile(r"^(?:[A-Za-z]:[\\/]|[\\/]{2})")
+
+
+def windows_path(value: Any) -> Any:
+    """An absolute path as Altium writes it: backslashes, no `.`, `..` or doubled separators.
+    Anything else (names such as "Free Documents", empty defaults) passes unchanged."""
+    return ntpath.normpath(value) if isinstance(value, str) and _ABSOLUTE.match(value) else value
+
+
+def normalise_paths(ops: list[dict]) -> list[dict]:
+    """The operations with every file field in Windows form; the input is not changed."""
+    return [{key: windows_path(value) if key in PATH_KEYS else value for key, value in op.items()}
+            if isinstance(op, dict) else op for op in ops]
+
+
+def _folder(path: str) -> str:
+    return str(path).replace("/", "\\").rsplit("\\", 1)[0] if "\\" in str(path).replace("/", "\\") else ""
+
+
+def folder_of(path: str) -> str:
+    """The folder of a project or document path, in the Windows form answer rules compare against."""
+    return _folder(path)
+
+
+def server_prompt_answers(folder: str, save_none: bool) -> list[dict]:
+    """Answers to Altium 365's server prompts only, for closes that must neither save nor commit
+    anything: "Save changes to Server?" gets "Do nothing"; "Confirm Save to Server" gets "Do nothing"
+    (or "Save None", when the caller's documents were saved first), then OK."""
+    confirm = [["Do nothing", "Save None"], ["OK"]] if save_none else [["Do nothing"], ["OK"]]
+    return [{"title": "Unsaved Changes", "press": [["Do nothing"]], "folder": folder},
+            {"title": "Confirm Save to Server", "press": confirm, "folder": folder},
+            {"title": "Confirm Not Saving", "press": [["OK"]], "folder": folder, "documents": "optional"}]
+
+
+def prompt_answers(ops: list[dict]) -> list[dict]:
+    """The prompts a request may answer, derived from what its operations do.
+
+    Each rule names a dialog (by the start of its title), the check boxes to clear first, the
+    steps to press in order (each step lists alternative captions; the first one the dialog has
+    is pressed), and the folder every document the dialog names must sit in. A prompt no rule
+    covers is captured and cancelled, as before. Nothing here ever commits to a server: "Save to
+    Server" is always cleared, and server prompts are answered "Do nothing".
+
+    "Unsaved Changes" comes in two forms, measured on Altium Designer Develop 26.10: a document
+    modified in memory ("Save changes?": Save, Don't Save, Cancel, with a "Save to Server" box),
+    and, in an Altium 365 working copy, a document saved but not committed ("Save changes to
+    Server?": Save, Do nothing, Cancel). "Save" there commits to the server.
+
+    "Confirm Save to Server for (n) Modified Documents" lists documents with a decision each. With
+    two documents it offered "Do nothing"; with six (drawings and BOM changed in memory, OutJobs on
+    disk) its buttons were Save All, Save None, Save All to Server, OK and Cancel (measured). "Save
+    None" saves nothing and commits nothing; "Save All to Server" is never pressed.
+    """
+    discard = [["Don't Save", "Do nothing"]]
+    rules: list[dict] = []
+    for op in ops:
+        name = op.get("op")
+        if name == "project_close":
+            folder = _folder(op.get("path", ""))
+            if op.get("save", "all") == "none":
+                rules.append({"title": "Unsaved Changes", "uncheck": ["Save to Server"], "press": discard,
+                              "folder": folder})
+            else:
+                # Everything was saved first; only the server form can come, and it is not a commit.
+                rules.append({"title": "Unsaved Changes", "press": [["Do nothing"]], "folder": folder})
+            rules.append({"title": "Confirm Save to Server", "press": [["Do nothing", "Save None"], ["OK"]],
+                          "folder": folder})
+            # It confirms the answer just given to a dialog that named the documents; it names none itself.
+            rules.append({"title": "Confirm Not Saving", "press": [["OK"]], "folder": folder, "documents": "optional"})
+        elif name == "doc_close" and op.get("save") is False:
+            # Only this document: another sheet's prompt in the same folder is not this request's to answer.
+            rules.append({"title": "Unsaved Changes", "uncheck": ["Save to Server"], "press": discard,
+                          "folder": _folder(op.get("path", "")), "files": [str(op.get("path", ""))]})
+        elif name == "project_netlist" and op.get("reopen"):
+            # The reopen saves every document first; only the server's prompts can follow.
+            rules += server_prompt_answers(_folder(op.get("path", "")), save_none=True)
+        elif name == "outjob_run" and op.get("project"):
+            # Generating outputs leaves in-memory changes only (new GUIDs on load); the server refuses
+            # a run while the project holds unsaved edits, so discarding here loses no work.
+            rules.append({"title": "Unsaved Changes", "uncheck": ["Save to Server"], "press": discard,
+                          "folder": _folder(op["project"])})
+    return rules
+
+
+def validate(ops: Any) -> list[dict]:
+    if not isinstance(ops, list) or not ops:
+        raise OpError("ops must be a non-empty list")
+    for i, op in enumerate(ops):
+        if not isinstance(op, dict) or op.get("op") not in OPS:
+            raise OpError(f"ops[{i}]: unknown operation {op.get('op') if isinstance(op, dict) else op!r}")
+    return ops
+
+
+def render(ops: list[dict]) -> str:
+    """Render a validated list of operations as the generated `Body` procedure."""
+    validate(ops)
+    lines = ["procedure Body;", "begin"]
+    for index, op in enumerate(ops):
+        try:
+            calls = OPS[op["op"]](op)
+        except OpError as exc:
+            raise OpError(f"ops[{index}] ({op['op']}): {exc}") from None
+        lines.append(f"    OpBegin({index}, {pascal_string(op['op'])});")
+        lines += [f"    {call}" for call in calls]
+    lines += ["    Done;", "end;"]
+    return "\n".join(lines)
+
+
+def is_read_only(ops: list[dict]) -> bool:
+    return all(op.get("op") in READ_ONLY for op in ops)