# v1.6 Track A — P&ID Expert and Reader Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make the server a P&ID expert (code-authored ISO 10628-2 / ISA-5.1 symbol catalogue as real blocks with tags and ports, orthogonal line drawing with ISA-5.1 line classes, an ISA-5.1 tag grammar) and a P&ID reader (`pid_graph` turns any P&ID into a connectivity graph; instrument index, line list and equipment list derive from it; six critique focuses join `drawing_finalize`).

**Architecture:** Two new generic backend contracts (`block_define`, `entity_get/set_xdata`) implemented on both engines; everything else composes existing primitives from a new `engineering/pid/` package (symbols as data, pure routing, pure tag grammar, a graph builder that reads the drawing back). Nine `pid_*` tools in a new `SECTION 17` of `server.py`, gated by a new `TOOL_PACKS` mechanism.

**Tech Stack:** Python 3.11+, FastMCP 3, ezdxf 1.4, pywin32 (COM, fake-tested + live smoke), pytest-asyncio.

**Spec:** `docs/superpowers/specs/2026-09-15-v1.6-pid-design.md` (parent: `docs/superpowers/specs/2026-09-15-v1.6-roadmap-design.md`, track A).

## Global Constraints

- Run every command through the project environment: `uv run --frozen pytest ...`, `uv run --frozen python ...` (the shell's default `python` is 3.14 without the project's dependencies).
- Every coordinate in or out of a tool is WCS on both engines; symbol geometry is authored in symbol-local mm and transformed at insertion.
- Every new tool needs: a `@cad_tool(summary=..., cost=...)` line above its `@mcp.tool(...)`, `tags={...}`, an alias record in `discovery/aliases.py` (the gate `tests/test_discovery_aliases.py::test_every_registered_tool_has_an_alias_record` fails otherwise), a regenerated `docs/tool-inventory.json` (`uv run --frozen python scripts/generate_tool_inventory.py`), the README release-snapshot line updated to the new tool count, and the `SECTION` header comment count updated (`tests/test_release_consistency.py::test_section_header_counts_match_decorators` parses decorators per section).
- The README release-snapshot line today reads `> **v1.5 release snapshot:** 154 tools · 6 resources · 5 prompt templates · 1369 collected tests.` — bump the tool/resource counts in the same task that adds them; leave the minor version at `v1.5` until the release task (a `v1.6` label there requires `pyproject.toml` to say 1.6).
- Both engines implement every new contract method as `@abstractmethod` (no `@capability` in this track). COM paths are unit-tested against fake ActiveX objects (the `tests/test_block_from_entities.py` pattern) and executed once live by `scripts/smoke_pid_com.py` in the last task.
- Validation happens **before** any write: a malformed request raises `TypeError`/`ValueError` naming the offending index/key, and nothing is created.
- Authored standards data (symbols, ISA letter tables) is pinned by tests a reader can check against the standard.
- P&ID critique focuses return `[]` on a drawing with no P&ID nodes.
- Reference sizes (symbol-local mm): instrument bubble Ø10; valve body 8 × 4; pump Ø8; grid 5; equipment `TAG` text height 2.5; bubble `FUNC`/`LOOP` height 2.0; stub 5.
- Commit after every task with a conventional-commit message; end every commit message with the two attribution lines this session's harness requires (`Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>` and `Claude-Session: https://claude.ai/code/session_01FKFStjEFzpGyLq5bMpWxTd`). If `git commit` reports "Author identity unknown", pass `-c user.name="Umut CAN" -c user.email="umutcan.edizaslan@gmail.com"` (the repository's existing author) — do not change global git config.

## File Structure

| Path | Responsibility |
|---|---|
| `backends/block_specs.py` (new) | Validation/normalisation of `block_define` primitive and ATTDEF specs; SOLID vertex order. Shared by both engines. |
| `backends/xdata_specs.py` (new) | XDATA app-name validation, value ↔ (group code, value) encoding, size limits, per-app splitting. Shared by both engines. |
| `backends/contracts/blocks.py` | `+ block_define` |
| `backends/contracts/entity_query.py` | `+ entity_get_xdata`, `+ entity_set_xdata` |
| `backends/ezdxf_backend.py` | `block_insert` attribute fix; `block_define`; XDATA methods |
| `backends/com_backend.py` | `block_define`; XDATA methods |
| `engineering/pid/__init__.py` (new) | Public re-exports |
| `engineering/pid/geometry.py` (new) | Primitive-spec helpers (line/circle/arc/polyline/text/solid/dashed_line/regular_polygon/bbox_of/attdef) |
| `engineering/pid/symbols.py` (new) | `Port`, `SymbolSpec`, registry, `resolve`, `list_symbols`, `all_specs`, `transform_port`, instrument/marker/connector builders |
| `engineering/pid/symbols_valves.py` (new) | 11 valve bodies × 6 actuators |
| `engineering/pid/symbols_equipment.py` (new) | rotating (6), heat (4), misc (7) |
| `engineering/pid/symbols_vessels.py` (new) | 6 parametric vessels |
| `engineering/pid/xdata.py` (new) | `ACADMCP_PID` payload encode/decode/read/write, payload builders |
| `engineering/pid/tags.py` (new) | ISA-5.1 grammar + tables, equipment prefix map, `parse_tag`, `split_instrument_tag` |
| `engineering/pid/insert.py` (new) | `ensure_layer`, `ensure_block`, `insert_symbol` |
| `engineering/pid/lines.py` (new) | `LINE_CLASSES`, `route`, `label_placement`, `marker_positions`, `count_crossings`, `format_line_number` (pure) |
| `engineering/pid/drawlines.py` (new) | `draw_line(backend, ...)` orchestration |
| `engineering/pid/graph.py` (new) | `build_graph(backend, ...)` |
| `engineering/pid/deliverables.py` (new) | `instrument_index`, `line_list`, `equipment_list`, `write_csv` |
| `engineering/pid/critique.py` (new) | six `pid_*` focus checks over one cached graph |
| `engineering/pid/spec.py` (new) | `validate_spec`, `run_spec(backend, spec, dry_run)` |
| `engineering/layers.py` | `PID_LAYERS` + `PROCESS-LINE-TEXT` |
| `engineering/plan_spec.py` | `CritiqueFocus` + 6 values |
| `engineering/critique.py` | shared-context dispatch for the pid focuses |
| `engineering/preflight.py` | `LAYER_SET_INTENT_MISMATCH` conflict |
| `config.py` | `tool_packs` |
| `server.py` | SECTION 5 (+2), SECTION 7 (+1), SECTION 17 (9 tools), `TOOL_PACKS`, 2 resources, prompt rewrite, `drawing_plan` warning |
| `discovery/aliases.py` | 12 alias records |
| `benchmarks/tasks_v4.py` (new), `benchmarks/adapters/autocad_mcp_pro.py`, `benchmarks/correctness_suite.py`, `benchmarks/run_competitors.py`, `benchmarks/render_matrix_chart.py` | `pid_roundtrip` task, +3 correctness checks |
| `scripts/render_pid_catalog.py`, `scripts/render_readme_pid.py`, `scripts/smoke_pid_com.py` (new) | contact sheet, README showcase, live COM smoke |
| `tests/test_block_insert_attributes.py`, `tests/test_block_specs.py`, `tests/test_block_define.py`, `tests/test_xdata.py`, `tests/test_pid_xdata.py`, `tests/test_pid_tags.py`, `tests/test_pid_symbols.py`, `tests/test_pid_insert.py`, `tests/test_pid_lines.py`, `tests/test_pid_line_draw.py`, `tests/test_pid_graph.py`, `tests/test_pid_deliverables.py`, `tests/test_pid_critique.py`, `tests/test_pid_from_spec.py`, `tests/test_tool_packs.py`, `tests/test_pid_resources_prompt.py`, `tests/test_benchmark_v4.py`, `tests/data/isa51_tags.json` | tests and fixtures |

---

### Task 1: Fix `block_insert(attributes=…)` on the headless engine

The ezdxf `block_insert` uses `msp.add_auto_blockref`, which wraps the INSERT in an anonymous `*U…` block: the returned handle references `*U1`, and `block_get_attributes` on it returns `{}`. Verified 2026-09-15 on v1.5.1. Everything in this track reads attributes back, so this goes first.

**Files:**
- Modify: `backends/ezdxf_backend.py` (`block_insert`, around line 4436)
- Test: `tests/test_block_insert_attributes.py`

**Interfaces:**
- Produces: `block_insert(name, x, y, scale_x, scale_y, rotation, attributes, layer) -> EntityInfo` whose `properties["block_name"] == name` and whose ATTRIBs are attached to the INSERT itself.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_block_insert_attributes.py
"""block_insert(attributes=...) must reference the named block, not an anonymous wrapper.

ezdxf's `add_auto_blockref` wraps the INSERT in an anonymous `*U` block. The
handle it returns then reports block_name `*U1`, and `block_get_attributes`
finds no ATTRIBs on it — an insert with attributes silently lost them.
"""

from __future__ import annotations

import pytest

pytestmark = pytest.mark.asyncio


def _define_tagged_block(backend, name: str = "TB") -> None:
    blk = backend._doc.blocks.new(name=name)
    blk.add_line((0, 0), (10, 0))
    blk.add_attdef("TAG", insert=(0, 3), text="", dxfattribs={"height": 2.5})


async def test_insert_with_attributes_references_the_named_block(backend):
    _define_tagged_block(backend)
    ref = await backend.block_insert("TB", 10, 10, attributes={"TAG": "P-101"})

    info = await backend.entity_get(ref.handle)
    assert info.properties["block_name"] == "TB"
    assert await backend.block_get_attributes(ref.handle) == {"TAG": "P-101"}
    anonymous = [b.name for b in backend._doc.blocks if b.name.startswith("*U")]
    assert anonymous == [], "no anonymous wrapper block may be created"


async def test_insert_ignores_values_for_tags_the_block_does_not_define(backend):
    _define_tagged_block(backend)
    ref = await backend.block_insert("TB", 0, 0, attributes={"TAG": "V-1", "NOPE": "x"})
    assert await backend.block_get_attributes(ref.handle) == {"TAG": "V-1"}


async def test_insert_without_attributes_is_unchanged(backend):
    _define_tagged_block(backend)
    ref = await backend.block_insert("TB", 0, 0)
    info = await backend.entity_get(ref.handle)
    assert info.properties["block_name"] == "TB"
    assert await backend.block_get_attributes(ref.handle) == {}
```

- [ ] **Step 2: Run it to verify it fails**

Run: `uv run --frozen pytest tests/test_block_insert_attributes.py -v`
Expected: the first two tests FAIL (`block_name == '*U1'`, attributes `{}`); the third passes.

- [ ] **Step 3: Replace `add_auto_blockref` with `add_blockref(...).add_auto_attribs(...)`**

In `backends/ezdxf_backend.py::block_insert`, replace the `if attributes: ... else: ...` pair with:

```python
            ref = msp.add_blockref(name, (float(x), float(y)), dxfattribs=attribs)
            if attributes:
                # `add_auto_blockref` wraps the INSERT in an anonymous *U block,
                # so the returned handle names `*U1` and carries no ATTRIBs.
                # `add_auto_attribs` attaches ATTRIBs to this INSERT for every
                # ATTDEF the definition has; values for tags it lacks are ignored.
                ref.add_auto_attribs({str(k): str(v) for k, v in attributes.items()})
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `uv run --frozen pytest tests/test_block_insert_attributes.py tests/test_layer_block.py tests/test_block_from_entities.py -v`
Expected: all PASS.

- [ ] **Step 5: Commit**

```bash
git add backends/ezdxf_backend.py tests/test_block_insert_attributes.py
git commit -m "fix(ezdxf): block_insert with attributes referenced an anonymous *U block and lost its ATTRIBs"
```

---

### Task 2: Shared primitive/ATTDEF spec validation (`backends/block_specs.py`)

**Files:**
- Create: `backends/block_specs.py`
- Test: `tests/test_block_specs.py`

**Interfaces:**
- Produces:
  - `ALLOWED_TYPES = ("line", "circle", "arc", "polyline", "text", "solid")`, `TEXT_ALIGNMENTS = ("left", "center", "right", "middle_center")`
  - `validate_entity_specs(entities: list[dict]) -> list[dict]` — normalised copies (floats; `layer` default `"0"`; polyline `points: list[tuple[float, float]]`, `closed: bool`, `bulges: list[float] | None`; text `rotation_deg`, `align`; solid `points` 3–4 pairs). Raises `ValueError` when empty, `TypeError` naming `entities[i]` and the key otherwise.
  - `validate_attdef_specs(attdefs: list[dict]) -> list[dict]` — keys `tag, prompt, default, x, y, height, rotation_deg, align, invisible`; tag `^[A-Z][A-Z0-9_]{0,30}$` and unique.
  - `solid_vertices(points) -> list[tuple[float, float]]` — DXF SOLID bow-tie order (`[a, b, d, c]` for a quad, unchanged for a triangle).

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_block_specs.py
"""block_define request validation: refuse the whole request before any write."""

from __future__ import annotations

import pytest

from backends.block_specs import (
    ALLOWED_TYPES,
    solid_vertices,
    validate_attdef_specs,
    validate_entity_specs,
)


def test_allowed_types_are_the_documented_six():
    assert ALLOWED_TYPES == ("line", "circle", "arc", "polyline", "text", "solid")


def test_empty_entities_is_refused():
    with pytest.raises(ValueError, match="empty"):
        validate_entity_specs([])


def test_each_type_normalises_to_floats_and_layer_zero():
    out = validate_entity_specs(
        [
            {"type": "line", "x1": 0, "y1": 0, "x2": 1, "y2": 0},
            {"type": "circle", "cx": 0, "cy": 0, "r": 2},
            {"type": "arc", "cx": 0, "cy": 0, "r": 2, "start_deg": 0, "end_deg": 180},
            {"type": "polyline", "points": [[0, 0], [1, 0], [1, 1]], "closed": True},
            {"type": "text", "text": "M", "x": 0, "y": 0, "height": 2},
            {"type": "solid", "points": [[0, 0], [1, 0], [0, 1]]},
        ]
    )
    assert [e["type"] for e in out] == list(ALLOWED_TYPES)
    assert out[0] == {"type": "line", "layer": "0", "x1": 0.0, "y1": 0.0, "x2": 1.0, "y2": 0.0}
    assert out[3]["points"] == [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0)]
    assert out[3]["closed"] is True and out[3]["bulges"] is None
    assert out[4]["align"] == "left" and out[4]["rotation_deg"] == 0.0
    assert out[5]["points"] == [(0.0, 0.0), (1.0, 0.0), (0.0, 1.0)]


@pytest.mark.parametrize(
    "bad, fragment",
    [
        ({"type": "square"}, "type"),
        ({"type": "line", "x1": 0, "y1": 0, "x2": 1}, "y2"),
        ({"type": "circle", "cx": 0, "cy": 0, "r": 0}, "r"),
        ({"type": "circle", "cx": 0, "cy": 0, "r": float("nan")}, "finite"),
        ({"type": "text", "text": "M", "x": 0, "y": 0, "height": -1}, "height"),
        ({"type": "text", "text": 5, "x": 0, "y": 0, "height": 1}, "text"),
        ({"type": "text", "text": "M", "x": 0, "y": 0, "height": 1, "align": "top"}, "align"),
        ({"type": "polyline", "points": [[0, 0]]}, "points"),
        ({"type": "polyline", "points": [[0, 0], [1]]}, "points[1]"),
        ({"type": "polyline", "points": [[0, 0], [1, 1]], "bulges": [0.5]}, "bulges"),
        ({"type": "polyline", "points": [[0, 0], [1, 1]], "closed": "yes"}, "closed"),
        ({"type": "solid", "points": [[0, 0], [1, 0]]}, "points"),
        ({"type": "solid", "points": [[0, 0], [1, 0], [1, 1], [0, 1], [2, 2]]}, "at most 4"),
        ({"type": "line", "x1": 0, "y1": 0, "x2": 1, "y2": 0, "layer": ""}, "layer"),
        ({"type": "line", "x1": True, "y1": 0, "x2": 1, "y2": 0}, "x1"),
    ],
)
def test_bad_entity_names_the_index_and_key(bad, fragment):
    good = {"type": "line", "x1": 0, "y1": 0, "x2": 1, "y2": 0}
    with pytest.raises(TypeError, match=r"entities\[1\]") as exc:
        validate_entity_specs([good, bad])
    assert fragment in str(exc.value)


def test_attdefs_normalise_and_default():
    out = validate_attdef_specs([{"tag": "TAG", "x": 0, "y": 3, "height": 2.5}])
    assert out == [
        {
            "tag": "TAG",
            "prompt": "TAG",
            "default": "",
            "x": 0.0,
            "y": 3.0,
            "height": 2.5,
            "rotation_deg": 0.0,
            "align": "left",
            "invisible": False,
        }
    ]


@pytest.mark.parametrize(
    "bad, fragment",
    [
        ({"tag": "tag", "x": 0, "y": 0, "height": 1}, "tag"),
        ({"tag": "T-1", "x": 0, "y": 0, "height": 1}, "tag"),
        ({"tag": "TAG", "x": 0, "y": 0, "height": 0}, "height"),
        ({"tag": "TAG", "x": 0, "y": 0, "height": 1, "invisible": 1}, "invisible"),
        ({"tag": "TAG", "x": 0, "y": 0, "height": 1, "default": 3}, "default"),
    ],
)
def test_bad_attdef_names_the_index_and_key(bad, fragment):
    with pytest.raises(TypeError, match=r"attdefs\[0\]") as exc:
        validate_attdef_specs([bad])
    assert fragment in str(exc.value)


def test_duplicate_attdef_tags_are_refused():
    with pytest.raises(TypeError, match="duplicate"):
        validate_attdef_specs(
            [
                {"tag": "TAG", "x": 0, "y": 0, "height": 1},
                {"tag": "TAG", "x": 0, "y": 5, "height": 1},
            ]
        )


def test_solid_vertices_use_dxf_bowtie_order():
    quad = [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)]
    assert solid_vertices(quad) == [(0.0, 0.0), (1.0, 0.0), (0.0, 1.0), (1.0, 1.0)]
    tri = [(0.0, 0.0), (1.0, 0.0), (0.0, 1.0)]
    assert solid_vertices(tri) == tri
```

- [ ] **Step 2: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_block_specs.py -v`
Expected: FAIL with `ModuleNotFoundError: No module named 'backends.block_specs'`.

- [ ] **Step 3: Write the module**

```python
# backends/block_specs.py
"""Typed primitive specs for ``block_define``, validated before any write.

Both engines consume the same normalised specs, so a malformed request is
refused identically on COM and ezdxf and nothing is written on either. Every
error names the offending entry (``entities[i]`` / ``attdefs[i]``) and key.
"""

from __future__ import annotations

import math
import re

ALLOWED_TYPES = ("line", "circle", "arc", "polyline", "text", "solid")
TEXT_ALIGNMENTS = ("left", "center", "right", "middle_center")
ATTDEF_TAG_RE = re.compile(r"^[A-Z][A-Z0-9_]{0,30}$")

_REQUIRED = {
    "line": ("x1", "y1", "x2", "y2"),
    "circle": ("cx", "cy", "r"),
    "arc": ("cx", "cy", "r", "start_deg", "end_deg"),
    "polyline": ("points",),
    "text": ("text", "x", "y", "height"),
    "solid": ("points",),
}
_POSITIVE = {"r", "height"}


def _scalar(value, where: str, *, positive: bool = False) -> float:
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise TypeError(f"{where} must be a number, got {value!r}")
    number = float(value)
    if not math.isfinite(number):
        raise TypeError(f"{where} must be finite")
    if positive and number <= 0:
        raise TypeError(f"{where} must be > 0, got {number}")
    return number


def _number(spec: dict, key: str, where: str) -> float:
    return _scalar(spec.get(key), f"{where}: {key!r}", positive=key in _POSITIVE)


def _points(
    spec: dict, where: str, *, minimum: int, maximum: int | None = None
) -> list[tuple[float, float]]:
    raw = spec.get("points")
    if not isinstance(raw, (list, tuple)) or len(raw) < minimum:
        raise TypeError(f"{where}: 'points' must be a list of at least {minimum} [x, y] pairs")
    if maximum is not None and len(raw) > maximum:
        raise TypeError(f"{where}: 'points' must have at most {maximum} pairs")
    out: list[tuple[float, float]] = []
    for i, pt in enumerate(raw):
        if not isinstance(pt, (list, tuple)) or len(pt) != 2:
            raise TypeError(f"{where}: points[{i}] must be an [x, y] pair")
        out.append(
            (
                _scalar(pt[0], f"{where}: points[{i}].x"),
                _scalar(pt[1], f"{where}: points[{i}].y"),
            )
        )
    return out


def _align(spec: dict, where: str) -> str:
    align = spec.get("align", "left")
    if align not in TEXT_ALIGNMENTS:
        raise TypeError(f"{where}: 'align' must be one of {TEXT_ALIGNMENTS}, got {align!r}")
    return align


def _layer(spec: dict, where: str) -> str:
    layer = spec.get("layer", "0")
    if not isinstance(layer, str) or not layer.strip():
        raise TypeError(f"{where}: 'layer' must be a non-empty string")
    return layer.strip()


def validate_entity_specs(entities) -> list[dict]:
    """Normalise ``block_define`` primitive specs; refuse the whole list on the first defect."""
    if not isinstance(entities, (list, tuple)) or not entities:
        raise ValueError(
            "block_define: 'entities' is empty — a block that draws nothing is refused"
        )
    out: list[dict] = []
    for i, spec in enumerate(entities):
        where = f"entities[{i}]"
        if not isinstance(spec, dict):
            raise TypeError(f"{where}: must be an object")
        kind = spec.get("type")
        if kind not in ALLOWED_TYPES:
            raise TypeError(f"{where}: 'type' must be one of {ALLOWED_TYPES}, got {kind!r}")
        for key in _REQUIRED[kind]:
            if key not in spec:
                raise TypeError(f"{where}: {kind} requires {key!r}")
        norm: dict = {"type": kind, "layer": _layer(spec, where)}
        if kind == "line":
            for key in ("x1", "y1", "x2", "y2"):
                norm[key] = _number(spec, key, where)
        elif kind == "circle":
            for key in ("cx", "cy", "r"):
                norm[key] = _number(spec, key, where)
        elif kind == "arc":
            for key in ("cx", "cy", "r", "start_deg", "end_deg"):
                norm[key] = _number(spec, key, where)
        elif kind == "polyline":
            pts = _points(spec, where, minimum=2)
            closed = spec.get("closed", False)
            if not isinstance(closed, bool):
                raise TypeError(f"{where}: 'closed' must be a boolean")
            bulges = spec.get("bulges")
            if bulges is not None:
                if not isinstance(bulges, (list, tuple)) or len(bulges) != len(pts):
                    raise TypeError(f"{where}: 'bulges' must list one value per point")
                bulges = [_scalar(b, f"{where}: bulges[{j}]") for j, b in enumerate(bulges)]
            norm.update(points=pts, closed=closed, bulges=list(bulges) if bulges else None)
        elif kind == "text":
            text = spec.get("text")
            if not isinstance(text, str):
                raise TypeError(f"{where}: 'text' must be a string")
            norm.update(
                text=text,
                x=_number(spec, "x", where),
                y=_number(spec, "y", where),
                height=_number(spec, "height", where),
                rotation_deg=_scalar(spec.get("rotation_deg", 0.0), f"{where}: 'rotation_deg'"),
                align=_align(spec, where),
            )
        elif kind == "solid":
            norm["points"] = _points(spec, where, minimum=3, maximum=4)
        out.append(norm)
    return out


def validate_attdef_specs(attdefs) -> list[dict]:
    """Normalise ATTDEF specs: tag pattern, uniqueness, numeric fields, flags."""
    if attdefs is None:
        return []
    if not isinstance(attdefs, (list, tuple)):
        raise TypeError("block_define: 'attdefs' must be a list")
    out: list[dict] = []
    seen: set[str] = set()
    for i, spec in enumerate(attdefs):
        where = f"attdefs[{i}]"
        if not isinstance(spec, dict):
            raise TypeError(f"{where}: must be an object")
        tag = spec.get("tag")
        if not isinstance(tag, str) or not ATTDEF_TAG_RE.match(tag):
            raise TypeError(f"{where}: 'tag' must match {ATTDEF_TAG_RE.pattern}, got {tag!r}")
        if tag in seen:
            raise TypeError(f"{where}: duplicate tag {tag!r}")
        seen.add(tag)
        prompt = spec.get("prompt", tag)
        default = spec.get("default", "")
        invisible = spec.get("invisible", False)
        if not isinstance(prompt, str):
            raise TypeError(f"{where}: 'prompt' must be a string")
        if not isinstance(default, str):
            raise TypeError(f"{where}: 'default' must be a string")
        if not isinstance(invisible, bool):
            raise TypeError(f"{where}: 'invisible' must be a boolean")
        out.append(
            {
                "tag": tag,
                "prompt": prompt,
                "default": default,
                "x": _number(spec, "x", where),
                "y": _number(spec, "y", where),
                "height": _number(spec, "height", where),
                "rotation_deg": _scalar(spec.get("rotation_deg", 0.0), f"{where}: 'rotation_deg'"),
                "align": _align(spec, where),
                "invisible": invisible,
            }
        )
    return out


def solid_vertices(points: list[tuple[float, float]]) -> list[tuple[float, float]]:
    """DXF SOLID draws vtx0→vtx1→vtx3→vtx2, so a quad given in polygon order
    (a, b, c, d) is stored as (a, b, d, c). Triangles are stored as given."""
    pts = [(float(x), float(y)) for x, y in points]
    if len(pts) == 4:
        return [pts[0], pts[1], pts[3], pts[2]]
    return pts
```

- [ ] **Step 4: Run the tests**

Run: `uv run --frozen pytest tests/test_block_specs.py -v`
Expected: all PASS.

- [ ] **Step 5: Commit**

```bash
git add backends/block_specs.py tests/test_block_specs.py
git commit -m "feat(blocks): shared validation for block_define primitive and ATTDEF specs"
```

---

### Task 3: `block_define` on both engines + tool + gates

**Files:**
- Modify: `backends/contracts/blocks.py` (append abstract method)
- Modify: `backends/ezdxf_backend.py` (after `block_create_from_entities`)
- Modify: `backends/com_backend.py` (after `block_create_from_entities`)
- Modify: `server.py` (SECTION 7 header `(7 tools)` → `(8 tools)`; new tool after `block_create_from_entities`)
- Modify: `discovery/aliases.py` (record `block_define`)
- Modify: `README.md` snapshot line `154 tools` → `155 tools`; regenerate `docs/tool-inventory.json`
- Test: `tests/test_block_define.py`

**Interfaces:**
- Consumes: `validate_entity_specs`, `validate_attdef_specs`, `solid_vertices` (Task 2); `sanitize_symbol_name` (`security.py`).
- Produces: `await backend.block_define(name, entities, attdefs=None, base_x=0.0, base_y=0.0, overwrite=False) -> {"ok": True, "name", "entity_count", "attdef_count", "replaced": bool, "backend"}`; MCP tool `block_define` with the same parameters.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_block_define.py
"""block_define: a definition with ATTDEFs from typed specs, on both engines."""

from __future__ import annotations

import types

import pytest

pytestmark = pytest.mark.asyncio

VALVE = [
    {"type": "polyline", "points": [[-4, -2], [-4, 2], [0, 0]], "closed": True},
    {"type": "polyline", "points": [[4, -2], [4, 2], [0, 0]], "closed": True},
    {"type": "circle", "cx": 0, "cy": 0, "r": 1.5},
    {"type": "arc", "cx": 0, "cy": 2, "r": 2, "start_deg": 0, "end_deg": 180},
    {"type": "line", "x1": 0, "y1": 0, "x2": 0, "y2": 4},
    {"type": "text", "text": "M", "x": 0, "y": 6, "height": 2, "align": "middle_center"},
    {"type": "solid", "points": [[0, 0], [-3, 1.2], [-3, -1.2]]},
]
ATTDEFS = [
    {"tag": "TAG", "x": 0, "y": 5.5, "height": 2.5, "align": "center"},
    {"tag": "LINK", "x": 0, "y": -5, "height": 2.0, "invisible": True, "default": "L-1"},
]


# ── headless engine ─────────────────────────────────────────────────────────


async def test_defines_geometry_and_attdefs(backend):
    result = await backend.block_define("PID_VALVE_TEST", VALVE, ATTDEFS)
    assert result == {
        "ok": True,
        "name": "PID_VALVE_TEST",
        "entity_count": 7,
        "attdef_count": 2,
        "replaced": False,
        "backend": "ezdxf",
    }
    blk = backend._doc.blocks.get("PID_VALVE_TEST")
    types_ = sorted(e.dxftype() for e in blk)
    assert types_ == [
        "ARC",
        "ATTDEF",
        "ATTDEF",
        "CIRCLE",
        "LINE",
        "LWPOLYLINE",
        "LWPOLYLINE",
        "SOLID",
        "TEXT",
    ]
    attdefs = {e.dxf.tag: e for e in blk if e.dxftype() == "ATTDEF"}
    assert attdefs["LINK"].is_invisible is True
    assert attdefs["LINK"].dxf.text == "L-1"
    assert attdefs["TAG"].is_invisible is False
    for e in blk:
        assert e.dxf.layer == "0"
        assert e.dxf.color == 0, "ByBlock colour so the INSERT's layer drives it"


async def test_insert_after_define_carries_the_attributes(backend):
    await backend.block_define("PID_VALVE_TEST", VALVE, ATTDEFS)
    ref = await backend.block_insert("PID_VALVE_TEST", 10, 10, attributes={"TAG": "HV-101"})
    assert await backend.block_get_attributes(ref.handle) == {"TAG": "HV-101", "LINK": "L-1"}


async def test_name_clash_is_refused_unless_overwrite(backend):
    await backend.block_define("PID_X", VALVE)
    with pytest.raises(ValueError, match="overwrite"):
        await backend.block_define("PID_X", VALVE)
    result = await backend.block_define("PID_X", VALVE[:1], overwrite=True)
    assert result["replaced"] is True and result["entity_count"] == 1
    assert len(list(backend._doc.blocks.get("PID_X"))) == 1


async def test_overwrite_keeps_existing_inserts_pointing_at_the_name(backend):
    await backend.block_define("PID_X", VALVE)
    ref = await backend.block_insert("PID_X", 0, 0)
    await backend.block_define(
        "PID_X", [{"type": "circle", "cx": 0, "cy": 0, "r": 9}], overwrite=True
    )
    info = await backend.entity_get(ref.handle)
    assert info.properties["block_name"] == "PID_X"
    virtual = list(backend._doc.entitydb[ref.handle].virtual_entities())
    assert [e.dxftype() for e in virtual] == ["CIRCLE"]


async def test_invalid_request_writes_nothing(backend):
    with pytest.raises(TypeError, match=r"entities\[1\]"):
        await backend.block_define("PID_BAD", [VALVE[0], {"type": "circle", "cx": 0, "cy": 0}])
    assert "PID_BAD" not in backend._doc.blocks
    with pytest.raises(ValueError, match="empty"):
        await backend.block_define("PID_EMPTY", [])
    assert "PID_EMPTY" not in backend._doc.blocks


async def test_anonymous_names_are_refused(backend):
    with pytest.raises(ValueError, match="anonymous"):
        await backend.block_define("*U9", VALVE)


async def test_solid_uses_bowtie_order(backend):
    await backend.block_define(
        "PID_SOLID", [{"type": "solid", "points": [[0, 0], [1, 0], [1, 1], [0, 1]]}]
    )
    solid = next(e for e in backend._doc.blocks.get("PID_SOLID") if e.dxftype() == "SOLID")
    assert tuple(solid.dxf.vtx2)[:2] == (0.0, 1.0)
    assert tuple(solid.dxf.vtx3)[:2] == (1.0, 1.0)


# ── live engine, against a fake ActiveX surface ──────────────────────────────


class _Recorder:
    """Records every method call made on it, returns a styled child."""

    def __init__(self, name):
        self.Name = name
        self.calls: list[tuple[str, tuple]] = []
        self.Count = 0

    def __getattr__(self, attr):
        if attr.startswith("Add"):

            def _call(*args):
                self.calls.append((attr, args))
                return types.SimpleNamespace()

            return _call
        raise AttributeError(attr)


class _FakeBlocks:
    def __init__(self):
        self.blocks: dict[str, _Recorder] = {}

    def Add(self, base_point, name):
        self.blocks[name] = _Recorder(name)
        self.blocks[name].base_point = tuple(base_point.value)
        return self.blocks[name]

    def Item(self, name):
        if name not in self.blocks:
            raise RuntimeError(f"no block {name}")
        return self.blocks[name]


@pytest.fixture
def com_backend(monkeypatch):
    pytest.importorskip("win32com.client", reason="pywin32 not installed")
    from backends import com_backend as module

    document = types.SimpleNamespace(Blocks=_FakeBlocks())
    monkeypatch.setattr(module, "_acad_doc", lambda: document)
    monkeypatch.setattr(module, "_regen", lambda: None)
    backend = module.ComBackend()

    async def _run_inline(func, *args, **kwargs):
        return func(*args, **kwargs)

    monkeypatch.setattr(backend, "_run", _run_inline)
    return backend, document


async def test_com_issues_one_activex_call_per_primitive_and_attdef(com_backend):
    backend, document = com_backend
    result = await backend.block_define("PID_VALVE_TEST", VALVE, ATTDEFS, 1.0, 2.0)
    assert result["ok"] is True and result["backend"] == "com" and result["replaced"] is False
    block = document.Blocks.blocks["PID_VALVE_TEST"]
    assert block.base_point == (1.0, 2.0, 0.0)
    names = [name for name, _ in block.calls]
    assert names == [
        "AddLightWeightPolyline",
        "AddLightWeightPolyline",
        "AddCircle",
        "AddArc",
        "AddLine",
        "AddText",
        "AddSolid",
        "AddAttribute",
        "AddAttribute",
    ]
    tag_call = block.calls[7][1]
    link_call = block.calls[8][1]
    assert tag_call[0] == 2.5 and tag_call[1] == 0 and tag_call[4] == "TAG"
    assert link_call[1] == 1, "invisible ATTDEF uses acAttributeModeInvisible"
    assert link_call[5] == "L-1"


async def test_com_refuses_a_clash_without_overwrite(com_backend):
    backend, document = com_backend
    await backend.block_define("PID_X", VALVE[:1])
    with pytest.raises(ValueError, match="overwrite"):
        await backend.block_define("PID_X", VALVE[:1])


async def test_com_validates_before_touching_activex(com_backend):
    backend, document = com_backend
    with pytest.raises(TypeError):
        await backend.block_define("PID_BAD", [{"type": "circle", "cx": 0}])
    assert document.Blocks.blocks == {}
```

- [ ] **Step 2: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_block_define.py -v`
Expected: FAIL with `AttributeError: 'EzdxfBackend' object has no attribute 'block_define'`.

- [ ] **Step 3: Add the contract method**

Append to `BlockContract` in `backends/contracts/blocks.py`:

```python
    @abstractmethod
    async def block_define(
        self,
        name: str,
        entities: list[dict],
        attdefs: list[dict] | None = None,
        base_x: float = 0.0,
        base_y: float = 0.0,
        overwrite: bool = False,
    ) -> dict:
        """Create (or with ``overwrite`` replace the contents of) a block
        definition from typed primitive specs and ATTDEF specs — see
        ``backends/block_specs.py`` for the spec vocabulary. Returns
        ``{ok, name, entity_count, attdef_count, replaced, backend}``."""
        ...
```

- [ ] **Step 4: Implement on ezdxf**

Add after `block_create_from_entities` in `backends/ezdxf_backend.py`:

```python
async def block_define(
    self,
    name,
    entities,
    attdefs=None,
    base_x=0.0,
    base_y=0.0,
    overwrite=False,
) -> dict:
    """A block definition with ATTDEFs from typed specs.

    Validation runs before any write, so a malformed entry leaves no
    definition behind. ``overwrite`` replaces the *contents* of an existing
    definition rather than deleting it: existing INSERTs keep pointing at
    the name and show the new geometry (deleting a referenced block is
    refused by both engines; replacing contents works on both).
    """
    from ezdxf.enums import TextEntityAlignment

    from backends.block_specs import (
        solid_vertices,
        validate_attdef_specs,
        validate_entity_specs,
    )
    from security import sanitize_symbol_name

    clean_name = sanitize_symbol_name(name, kind="block")
    if clean_name.startswith("*"):
        raise ValueError("block_define: anonymous block names (*...) are refused")
    ents = validate_entity_specs(entities)
    atts = validate_attdef_specs(attdefs or [])
    align_map = {
        "left": TextEntityAlignment.LEFT,
        "center": TextEntityAlignment.CENTER,
        "right": TextEntityAlignment.RIGHT,
        "middle_center": TextEntityAlignment.MIDDLE_CENTER,
    }

    def _sync():
        doc = self._require_doc()
        existing = doc.blocks.get(clean_name) if clean_name in doc.blocks else None
        if existing is not None and not overwrite:
            raise ValueError(
                f"block_define: block {clean_name!r} already exists; "
                "pass overwrite=true to replace its contents"
            )
        replaced = existing is not None
        base = (float(base_x), float(base_y), 0.0)
        if existing is None:
            blk = doc.blocks.new(name=clean_name, base_point=base)
        else:
            blk = existing
            blk.delete_all_entities()
            blk.block.dxf.base_point = base
        for spec in ents:
            attribs = {"layer": spec["layer"], "color": 0, "linetype": "ByBlock"}
            kind = spec["type"]
            if kind == "line":
                blk.add_line((spec["x1"], spec["y1"]), (spec["x2"], spec["y2"]), dxfattribs=attribs)
            elif kind == "circle":
                blk.add_circle((spec["cx"], spec["cy"]), spec["r"], dxfattribs=attribs)
            elif kind == "arc":
                blk.add_arc(
                    (spec["cx"], spec["cy"]),
                    spec["r"],
                    spec["start_deg"],
                    spec["end_deg"],
                    dxfattribs=attribs,
                )
            elif kind == "polyline":
                bulges = spec["bulges"] or [0.0] * len(spec["points"])
                blk.add_lwpolyline(
                    [(x, y, b) for (x, y), b in zip(spec["points"], bulges)],
                    format="xyb",
                    close=spec["closed"],
                    dxfattribs=attribs,
                )
            elif kind == "text":
                txt = blk.add_text(
                    spec["text"],
                    dxfattribs={
                        **attribs,
                        "height": spec["height"],
                        "rotation": spec["rotation_deg"],
                    },
                )
                txt.set_placement((spec["x"], spec["y"]), align=align_map[spec["align"]])
            elif kind == "solid":
                blk.add_solid(solid_vertices(spec["points"]), dxfattribs=attribs)
        for att in atts:
            attdef = blk.add_attdef(
                att["tag"],
                insert=(att["x"], att["y"]),
                text=att["default"],
                dxfattribs={
                    "layer": "0",
                    "color": 0,
                    "height": att["height"],
                    "rotation": att["rotation_deg"],
                    "prompt": att["prompt"],
                },
            )
            attdef.set_placement((att["x"], att["y"]), align=align_map[att["align"]])
            if att["invisible"]:
                attdef.is_invisible = True
        self._mark_dirty()
        return {
            "ok": True,
            "name": clean_name,
            "entity_count": len(ents),
            "attdef_count": len(atts),
            "replaced": replaced,
            "backend": "ezdxf",
        }

    return await self._async(_sync)
```

- [ ] **Step 5: Implement on COM**

Add after `block_create_from_entities` in `backends/com_backend.py` (module already imports `deg2rad`, `win32com`, `pythoncom`, `_apoint`, `_av`, `_acad_doc`, `_regen`):

```python
    async def block_define(
        self,
        name,
        entities,
        attdefs=None,
        base_x=0.0,
        base_y=0.0,
        overwrite=False,
    ) -> dict:
        """A block definition with ATTDEFs from typed specs, through ActiveX.

        ``Blocks.Add`` creates the definition; each primitive is one ``Add*``
        call on the Block object, each ATTDEF one ``AddAttribute``. Overwrite
        deletes the existing definition's members and re-adds — the name and
        its INSERTs survive. Unit-tested against a fake ActiveX surface;
        executed live by ``scripts/smoke_pid_com.py``.
        """
        from backends.block_specs import (
            solid_vertices,
            validate_attdef_specs,
            validate_entity_specs,
        )
        from security import sanitize_symbol_name

        clean_name = sanitize_symbol_name(name, kind="block")
        if clean_name.startswith("*"):
            raise ValueError("block_define: anonymous block names (*...) are refused")
        ents = validate_entity_specs(entities)
        atts = validate_attdef_specs(attdefs or [])
        # acAlignmentLeft / Center / Right / MiddleCenter
        align_map = {"left": 0, "center": 1, "right": 2, "middle_center": 10}

        def _style(obj, layer: str) -> None:
            obj.Layer = layer
            obj.Color = 0  # acByBlock
            obj.Linetype = "ByBlock"

        def _sync():
            doc = _acad_doc()
            try:
                existing = doc.Blocks.Item(clean_name)
            except Exception:
                existing = None
            if existing is not None and not overwrite:
                raise ValueError(
                    f"block_define: block {clean_name!r} already exists; "
                    "pass overwrite=true to replace its contents"
                )
            replaced = existing is not None
            base = _apoint(float(base_x), float(base_y), 0.0)
            if existing is None:
                block = doc.Blocks.Add(base, clean_name)
            else:
                block = existing
                members = [block.Item(i) for i in range(block.Count)]
                for member in members:
                    member.Delete()
                block.Origin = base
            for spec in ents:
                kind = spec["type"]
                if kind == "line":
                    obj = block.AddLine(
                        _apoint(spec["x1"], spec["y1"]), _apoint(spec["x2"], spec["y2"])
                    )
                elif kind == "circle":
                    obj = block.AddCircle(_apoint(spec["cx"], spec["cy"]), float(spec["r"]))
                elif kind == "arc":
                    obj = block.AddArc(
                        _apoint(spec["cx"], spec["cy"]),
                        float(spec["r"]),
                        deg2rad(spec["start_deg"]),
                        deg2rad(spec["end_deg"]),
                    )
                elif kind == "polyline":
                    flat = [coord for pt in spec["points"] for coord in pt]
                    obj = block.AddLightWeightPolyline(_av(flat))
                    obj.Closed = bool(spec["closed"])
                    for index, bulge in enumerate(spec["bulges"] or []):
                        if bulge:
                            obj.SetBulge(index, float(bulge))
                elif kind == "text":
                    obj = block.AddText(
                        spec["text"], _apoint(spec["x"], spec["y"]), float(spec["height"])
                    )
                    obj.Rotation = deg2rad(spec["rotation_deg"])
                    if spec["align"] != "left":
                        obj.Alignment = align_map[spec["align"]]
                        obj.TextAlignmentPoint = _apoint(spec["x"], spec["y"])
                elif kind == "solid":
                    verts = solid_vertices(spec["points"])
                    verts = verts + [verts[-1]] * (4 - len(verts))
                    obj = block.AddSolid(*[_apoint(x, y) for x, y in verts])
                _style(obj, spec["layer"])
            for att in atts:
                mode = 1 if att["invisible"] else 0  # acAttributeModeInvisible / Normal
                obj = block.AddAttribute(
                    float(att["height"]),
                    mode,
                    att["prompt"],
                    _apoint(att["x"], att["y"]),
                    att["tag"],
                    att["default"],
                )
                obj.Rotation = deg2rad(att["rotation_deg"])
                if att["align"] != "left":
                    obj.Alignment = align_map[att["align"]]
                    obj.TextAlignmentPoint = _apoint(att["x"], att["y"])
                _style(obj, "0")
            _regen()
            return {
                "ok": True,
                "name": clean_name,
                "entity_count": len(ents),
                "attdef_count": len(atts),
                "replaced": replaced,
                "backend": "com",
            }

        return await self._run(_sync)
```

- [ ] **Step 6: Run the tests**

Run: `uv run --frozen pytest tests/test_block_define.py tests/test_capability_contract.py -v`
Expected: all PASS (the capability-contract test proves both backends still instantiate).

- [ ] **Step 7: Register the tool, alias, header count, inventory, README**

In `server.py`, change the header `# ── SECTION 7: Block Operations (7 tools)` to `(8 tools)` and add after `block_create_from_entities`:

```python
@cad_tool(
    summary="Define a block from typed primitives and attribute definitions, on both engines.",
    cost="mutate",
)
@mcp.tool(
    annotations={"title": "Define Block", "readOnlyHint": False},
    tags={"block", "create"},
)
async def block_define(
    name: Annotated[str, "New block definition name"],
    entities: Annotated[
        list[dict],
        "Primitives in block-local coordinates. type=line {x1,y1,x2,y2} | circle {cx,cy,r} | "
        "arc {cx,cy,r,start_deg,end_deg} | polyline {points,closed,bulges?} | "
        "text {text,x,y,height,rotation_deg?,align?} | solid {points (3-4)}. Optional layer (default 0).",
    ],
    attdefs: Annotated[
        list[dict] | None,
        "Attribute definitions: {tag, x, y, height, prompt?, default?, rotation_deg?, align?, invisible?}",
    ] = None,
    base_x: Annotated[float, "Block base point X"] = 0.0,
    base_y: Annotated[float, "Block base point Y"] = 0.0,
    overwrite: Annotated[
        bool, "Replace the contents of an existing definition of this name"
    ] = False,
    ctx: Context = None,
) -> dict:
    """Create a block definition with attribute definitions from typed specs.

    The whole request is validated before anything is written: one malformed
    entry refuses the call and leaves no definition behind. `overwrite=true`
    replaces the *contents* of an existing block so its INSERTs keep pointing
    at the name and show the new geometry; `replaced` reports it. Geometry
    inside the block is ByBlock so the INSERT's layer supplies colour and
    lineweight. Insert with `block_insert(attributes={TAG: value})`.
    """
    await ctx.info(f"Defining block '{name}' from {len(entities)} primitives")
    return await _backend(ctx).block_define(name, entities, attdefs, base_x, base_y, overwrite)
```

In `discovery/aliases.py`, add to `TOOL_ALIASES` next to `block_create_from_entities`:

```python
    "block_define": ToolAliases(
        acad=("BLOCK", "BEDIT", "ATTDEF"),
        synonyms=(
            "define a block",
            "make a symbol",
            "block with attributes",
            "attribute definition",
            "create a block definition from scratch",
        ),
    ),
```

Then: `uv run --frozen python scripts/generate_tool_inventory.py` and change the README snapshot line to `155 tools`.

- [ ] **Step 8: Run the gates**

Run: `uv run --frozen pytest tests/test_block_define.py tests/test_discovery_aliases.py tests/test_tool_inventory.py tests/test_release_consistency.py tests/test_tool_registry.py -v`
Expected: all PASS. (If `test_document_numbers_match_the_tree` fails only on the README `collected tests` figure, that drift predates this track — leave it for Task 21.)

- [ ] **Step 9: Commit**

```bash
git add backends/contracts/blocks.py backends/ezdxf_backend.py backends/com_backend.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_block_define.py
git commit -m "feat(blocks): block_define — typed primitives + ATTDEFs on both engines"
```

---

### Task 4: XDATA read/write on both engines + tools

**Files:**
- Create: `backends/xdata_specs.py`
- Modify: `backends/contracts/entity_query.py` (append two abstract methods)
- Modify: `backends/ezdxf_backend.py`, `backends/com_backend.py`
- Modify: `server.py` (SECTION 5 header `(7 tools)` → `(9 tools)`; two tools after `entity_set_properties`)
- Modify: `discovery/aliases.py`, `README.md` (`155 tools` → `157 tools`), regenerate `docs/tool-inventory.json`
- Test: `tests/test_xdata.py`

**Interfaces:**
- Produces:
  - `backends/xdata_specs.py`: `validate_app_name(app) -> str`; `encode_values(values: list) -> list[tuple[int, object]]` (`str`→1000, `int`→1071, `float`→1040, `[x, y(, z)]`→1010 as `(x, y, z)`); `decode_values(tags) -> list` (inverse; 1010 → `[x, y, z]`); `split_by_app(codes, values) -> dict[str, list]`; `MAX_STRING = 255`, `MAX_BYTES = 16384`.
  - `await backend.entity_get_xdata(handle, app_name=None) -> {"handle", "xdata": {app: [values]}, "backend"}`
  - `await backend.entity_set_xdata(handle, app_name, values) -> {"ok": True, "handle", "app_name", "value_count", "bytes", "removed": bool, "backend"}` — empty `values` removes the app's XDATA.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_xdata.py
"""XDATA round trips, typing by group code, limits, removal — both engines."""

from __future__ import annotations

import types

import pytest

from backends.xdata_specs import (
    MAX_BYTES,
    MAX_STRING,
    decode_values,
    encode_values,
    split_by_app,
    validate_app_name,
)

pytestmark = pytest.mark.asyncio


# ── pure encoding ────────────────────────────────────────────────────────────


def test_values_are_typed_by_group_code():
    assert encode_values(["json", 7, 2.5, [1, 2], [1, 2, 3]]) == [
        (1000, "json"),
        (1071, 7),
        (1040, 2.5),
        (1010, (1.0, 2.0, 0.0)),
        (1010, (1.0, 2.0, 3.0)),
    ]


def test_decode_is_the_inverse():
    tags = encode_values(["a", 1, 1.5, [3, 4]])
    assert decode_values(tags) == ["a", 1, 1.5, [3.0, 4.0, 0.0]]


@pytest.mark.parametrize("bad", [True, None, {"a": 1}, [1], [1, 2, 3, 4], ["x", "y"], 2**31])
def test_untypeable_values_are_refused(bad):
    with pytest.raises((TypeError, ValueError)):
        encode_values([bad])


def test_string_over_255_is_refused():
    encode_values(["x" * MAX_STRING])
    with pytest.raises(ValueError, match="255"):
        encode_values(["x" * (MAX_STRING + 1)])


def test_total_size_over_16k_is_refused():
    with pytest.raises(ValueError, match="16"):
        encode_values(["x" * 255] * (MAX_BYTES // 255 + 1))


@pytest.mark.parametrize("bad", ["", "1abc", "a-b", "a" * 32, "ACAD"])
def test_bad_app_names_are_refused(bad):
    with pytest.raises(ValueError):
        validate_app_name(bad)


def test_split_by_app_groups_a_flat_activex_stream():
    codes = [1001, 1000, 1071, 1001, 1040]
    values = ["APP_A", "hello", 3, "APP_B", 1.5]
    assert split_by_app(codes, values) == {"APP_A": ["hello", 3], "APP_B": [1.5]}


# ── headless engine ─────────────────────────────────────────────────────────


async def test_roundtrip_registers_the_appid(backend):
    line = await backend.entity_create_line(0, 0, 1, 1)
    result = await backend.entity_set_xdata(line.handle, "ACADMCP_PID", ["json", 42, 1.5, [1, 2]])
    assert result["ok"] is True and result["value_count"] == 4 and result["removed"] is False
    assert "ACADMCP_PID" in backend._doc.appids
    got = await backend.entity_get_xdata(line.handle, "ACADMCP_PID")
    assert got["xdata"] == {"ACADMCP_PID": ["json", 42, 1.5, [1.0, 2.0, 0.0]]}


async def test_get_without_app_returns_every_app(backend):
    line = await backend.entity_create_line(0, 0, 1, 1)
    await backend.entity_set_xdata(line.handle, "APP_A", ["a"])
    await backend.entity_set_xdata(line.handle, "APP_B", ["b"])
    got = await backend.entity_get_xdata(line.handle)
    assert got["xdata"] == {"APP_A": ["a"], "APP_B": ["b"]}


async def test_unknown_app_is_empty_not_an_error(backend):
    line = await backend.entity_create_line(0, 0, 1, 1)
    got = await backend.entity_get_xdata(line.handle, "NOPE")
    assert got["xdata"] == {}


async def test_set_replaces_and_empty_removes(backend):
    line = await backend.entity_create_line(0, 0, 1, 1)
    await backend.entity_set_xdata(line.handle, "APP_A", ["one", "two"])
    await backend.entity_set_xdata(line.handle, "APP_A", ["three"])
    assert (await backend.entity_get_xdata(line.handle, "APP_A"))["xdata"] == {"APP_A": ["three"]}
    result = await backend.entity_set_xdata(line.handle, "APP_A", [])
    assert result["removed"] is True
    assert (await backend.entity_get_xdata(line.handle))["xdata"] == {}


async def test_limits_are_enforced_before_writing(backend):
    line = await backend.entity_create_line(0, 0, 1, 1)
    with pytest.raises(ValueError, match="255"):
        await backend.entity_set_xdata(line.handle, "APP_A", ["x" * 256])
    assert (await backend.entity_get_xdata(line.handle))["xdata"] == {}


# ── live engine, fake ActiveX ────────────────────────────────────────────────


class _FakeEntity:
    def __init__(self):
        self.stored: tuple | None = None

    def SetXData(self, types_, values):
        self.stored = (list(types_.value), list(values.value))

    def GetXData(self, app):
        if self.stored is None:
            return ([], [])
        codes, values = self.stored
        if app:
            return (codes, values)
        return (codes, values)


@pytest.fixture
def com_backend(monkeypatch):
    pytest.importorskip("win32com.client", reason="pywin32 not installed")
    from backends import com_backend as module

    entity = _FakeEntity()
    registered: list[str] = []
    document = types.SimpleNamespace(
        HandleToObject=lambda handle: entity,
        RegisteredApplications=types.SimpleNamespace(Add=registered.append),
    )
    monkeypatch.setattr(module, "_acad_doc", lambda: document)
    backend = module.ComBackend()

    async def _run_inline(func, *args, **kwargs):
        return func(*args, **kwargs)

    monkeypatch.setattr(backend, "_run", _run_inline)
    return backend, entity, registered


async def test_com_set_writes_the_1001_marker_first(com_backend):
    backend, entity, registered = com_backend
    await backend.entity_set_xdata("2F", "ACADMCP_PID", ["json", 3, [1, 2]])
    assert registered == ["ACADMCP_PID"]
    codes, values = entity.stored
    assert codes == [1001, 1000, 1071, 1010]
    assert values[0] == "ACADMCP_PID" and values[1] == "json" and values[2] == 3
    assert tuple(values[3].value) == (1.0, 2.0, 0.0)


async def test_com_get_splits_by_app(com_backend):
    backend, entity, _ = com_backend
    await backend.entity_set_xdata("2F", "ACADMCP_PID", ["json"])
    got = await backend.entity_get_xdata("2F", "ACADMCP_PID")
    assert got["xdata"] == {"ACADMCP_PID": ["json"]}


async def test_com_empty_values_write_only_the_marker(com_backend):
    backend, entity, _ = com_backend
    result = await backend.entity_set_xdata("2F", "ACADMCP_PID", [])
    assert result["removed"] is True
    assert entity.stored == ([1001], ["ACADMCP_PID"])
```

- [ ] **Step 2: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_xdata.py -v`
Expected: FAIL with `ModuleNotFoundError: No module named 'backends.xdata_specs'`.

- [ ] **Step 3: Write `backends/xdata_specs.py`**

```python
# backends/xdata_specs.py
"""XDATA value typing and limits, shared by both engines.

DXF XDATA is a list of (group code, value) pairs under a registered APPID.
This module is the one place that decides how a JSON value becomes a group
code and enforces the two limits AutoCAD enforces silently: 255 characters
per string and 16 KB per entity.
"""

from __future__ import annotations

import re

APP_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,30}$")
RESERVED_APPS = {"ACAD"}
MAX_STRING = 255
MAX_BYTES = 16 * 1024
INT_MIN, INT_MAX = -(2**31), 2**31 - 1


def validate_app_name(app) -> str:
    if not isinstance(app, str) or not APP_NAME_RE.match(app):
        raise ValueError(f"xdata: app name must match {APP_NAME_RE.pattern}, got {app!r}")
    if app.upper() in RESERVED_APPS:
        raise ValueError(f"xdata: app name {app!r} is reserved")
    return app


def encode_values(values) -> list[tuple[int, object]]:
    """JSON values → (group code, value). Raises TypeError/ValueError; writes nothing."""
    if not isinstance(values, (list, tuple)):
        raise TypeError("xdata: values must be a list")
    tags: list[tuple[int, object]] = []
    size = 0
    for i, value in enumerate(values):
        where = f"values[{i}]"
        if isinstance(value, bool):
            raise TypeError(f"xdata: {where} booleans have no XDATA group code")
        if isinstance(value, str):
            if len(value) > MAX_STRING:
                raise ValueError(
                    f"xdata: {where} is {len(value)} characters; the limit is {MAX_STRING}"
                )
            tags.append((1000, value))
            size += len(value.encode("utf-8")) + 2
        elif isinstance(value, int):
            if not INT_MIN <= value <= INT_MAX:
                raise ValueError(f"xdata: {where} is outside the 32-bit integer range")
            tags.append((1071, int(value)))
            size += 6
        elif isinstance(value, float):
            tags.append((1040, float(value)))
            size += 10
        elif isinstance(value, (list, tuple)) and len(value) in (2, 3):
            try:
                coords = tuple(float(c) for c in value)
            except (TypeError, ValueError) as exc:
                raise TypeError(f"xdata: {where} point coordinates must be numbers") from exc
            if any(isinstance(c, bool) for c in value):
                raise TypeError(f"xdata: {where} point coordinates must be numbers")
            if len(coords) == 2:
                coords = (coords[0], coords[1], 0.0)
            tags.append((1010, coords))
            size += 26
        else:
            raise TypeError(f"xdata: {where} must be a string, int, float or [x, y(, z)] point")
    if size > MAX_BYTES:
        raise ValueError(f"xdata: encoded size {size} bytes exceeds the 16 KB per-entity limit")
    return tags


def decode_values(tags) -> list:
    """(group code, value) → JSON values. Skips the 1001 app marker and 1002 braces."""
    out: list = []
    for code, value in tags:
        if code in (1001, 1002):
            continue
        if code == 1010 or code in (1011, 1012, 1013):
            out.append([float(c) for c in value])
        elif code in (1040, 1041, 1042):
            out.append(float(value))
        elif code in (1070, 1071):
            out.append(int(value))
        else:
            out.append(str(value))
    return out


def split_by_app(codes, values) -> dict[str, list]:
    """A flat ActiveX GetXData stream (1001 markers inline) → {app: values}."""
    out: dict[str, list] = {}
    current: str | None = None
    pending: list[tuple[int, object]] = []
    for code, value in zip(codes, values):
        if code == 1001:
            if current is not None:
                out[current] = decode_values(pending)
            current, pending = str(value), []
        else:
            pending.append((code, value))
    if current is not None:
        out[current] = decode_values(pending)
    return out
```

- [ ] **Step 4: Add the contract methods**

Append to the query contract class in `backends/contracts/entity_query.py`:

```python
@abstractmethod
async def entity_get_xdata(self, handle: str, app_name: str | None = None) -> dict:
    """Extended entity data as ``{"handle", "xdata": {app: [values]}, "backend"}``.
    ``app_name=None`` returns every app; an absent app is ``{}``, not an error."""
    ...


@abstractmethod
async def entity_set_xdata(self, handle: str, app_name: str, values: list) -> dict:
    """Replace the app's XDATA (registering the APPID if needed). Values are typed
    by ``backends/xdata_specs.py``; an empty list removes the app's XDATA."""
    ...
```

- [ ] **Step 5: Implement on ezdxf** (add near `block_get_attributes`)

```python
async def entity_get_xdata(self, handle, app_name=None) -> dict:
    from backends.xdata_specs import decode_values, validate_app_name

    wanted = validate_app_name(app_name) if app_name else None

    def _sync():
        ent = self._get_entity(handle)
        out: dict[str, list] = {}
        if ent.xdata is not None:
            apps = [wanted] if wanted else list(ent.xdata.data.keys())
            for app in apps:
                if not ent.has_xdata(app):
                    continue
                tags = ent.get_xdata(app)
                out[app] = decode_values((tag.code, tag.value) for tag in tags)
        return {"handle": handle, "xdata": out, "backend": "ezdxf"}

    return await self._async(_sync)


async def entity_set_xdata(self, handle, app_name, values) -> dict:
    from backends.xdata_specs import encode_values, validate_app_name

    app = validate_app_name(app_name)
    tags = encode_values(values)

    def _sync():
        doc = self._require_doc()
        ent = self._get_entity(handle)
        if not tags:
            ent.discard_xdata(app)
            self._mark_dirty()
            return {
                "ok": True,
                "handle": handle,
                "app_name": app,
                "value_count": 0,
                "bytes": 0,
                "removed": True,
                "backend": "ezdxf",
            }
        if app not in doc.appids:
            doc.appids.add(app)
        ent.set_xdata(app, tags)
        self._mark_dirty()
        return {
            "ok": True,
            "handle": handle,
            "app_name": app,
            "value_count": len(tags),
            "bytes": sum(len(str(v)) for _, v in tags),
            "removed": False,
            "backend": "ezdxf",
        }

    return await self._async(_sync)
```

- [ ] **Step 6: Implement on COM** (add near `block_get_attributes`)

```python
async def entity_get_xdata(self, handle, app_name=None) -> dict:
    from backends.xdata_specs import split_by_app, validate_app_name

    wanted = validate_app_name(app_name) if app_name else ""

    def _sync():
        doc = _acad_doc()
        ent = doc.HandleToObject(str(handle).strip().upper())
        codes, values = ent.GetXData(wanted)
        grouped = split_by_app(list(codes or []), list(values or []))
        if wanted:
            grouped = {k: v for k, v in grouped.items() if k == wanted}
        return {"handle": handle, "xdata": grouped, "backend": "com"}

    return await self._run(_sync)


async def entity_set_xdata(self, handle, app_name, values) -> dict:
    from backends.xdata_specs import encode_values, validate_app_name

    app = validate_app_name(app_name)
    tags = encode_values(values)

    def _sync():
        doc = _acad_doc()
        ent = doc.HandleToObject(str(handle).strip().upper())
        try:
            doc.RegisteredApplications.Add(app)
        except Exception as exc:  # already registered
            log.debug("RegisteredApplications.Add(%s): %s", app, exc)
        codes = [1001] + [code for code, _ in tags]
        payload = [app] + [_apoint(*value) if code == 1010 else value for code, value in tags]
        ent.SetXData(
            _ai(codes),
            win32com.client.VARIANT(pythoncom.VT_ARRAY | pythoncom.VT_VARIANT, payload),
        )
        return {
            "ok": True,
            "handle": handle,
            "app_name": app,
            "value_count": len(tags),
            "bytes": sum(len(str(v)) for _, v in tags),
            "removed": not tags,
            "backend": "com",
        }

    return await self._run(_sync)
```

- [ ] **Step 7: Run the tests**

Run: `uv run --frozen pytest tests/test_xdata.py tests/test_capability_contract.py -v`
Expected: all PASS.

- [ ] **Step 8: Tools, aliases, header, inventory, README**

`server.py`: SECTION 5 header `(7 tools)` → `(9 tools)`; add after `entity_set_properties`:

```python
@cad_tool(summary="Read an entity's extended data (XDATA) by application name.", cost="read")
@mcp.tool(
    annotations={"title": "Get Entity XDATA", "readOnlyHint": True},
    tags={"entity", "query"},
)
async def entity_get_xdata(
    handle: Annotated[str, "Entity handle"],
    app_name: Annotated[str | None, "Registered application name; omit for every app"] = None,
    ctx: Context = None,
) -> dict:
    """Extended entity data as {app: [values]}. An app with no XDATA is simply absent."""
    return await _backend(ctx).entity_get_xdata(handle, app_name)


@cad_tool(summary="Attach or replace extended data (XDATA) on an entity.", cost="safe")
@mcp.tool(
    annotations={"title": "Set Entity XDATA", "readOnlyHint": False},
    tags={"entity", "modify"},
)
async def entity_set_xdata(
    handle: Annotated[str, "Entity handle"],
    app_name: Annotated[str, "Registered application name (created if missing)"],
    values: Annotated[
        list,
        "Values typed by kind: strings (≤255 chars) → 1000, ints → 1071, floats → 1040, [x,y] → 1010",
    ],
    ctx: Context = None,
) -> dict:
    """Replace the named app's XDATA on one entity; an empty list removes it.

    Limits are AutoCAD's and are enforced before writing: 255 characters per
    string and 16 KB per entity.
    """
    return await _backend(ctx).entity_set_xdata(handle, app_name, values)
```

`discovery/aliases.py`, two records:

```python
    "entity_get_xdata": ToolAliases(
        acad=("XDATA", "XDLIST"),
        synonyms=("extended data", "read xdata", "entity metadata", "registered application data"),
    ),
    "entity_set_xdata": ToolAliases(
        acad=("XDATA",),
        synonyms=("attach extended data", "write xdata", "tag an entity with metadata"),
    ),
```

Regenerate the inventory; README snapshot `157 tools`.

- [ ] **Step 9: Run the gates and commit**

Run: `uv run --frozen pytest tests/test_xdata.py tests/test_discovery_aliases.py tests/test_tool_inventory.py tests/test_release_consistency.py -v`
Expected: PASS (same caveat about the pre-existing collected-tests drift).

```bash
git add backends/xdata_specs.py backends/contracts/entity_query.py backends/ezdxf_backend.py backends/com_backend.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_xdata.py
git commit -m "feat(entity): entity_get_xdata / entity_set_xdata on both engines"
```

---
### Task 5: `engineering/pid` package + `ACADMCP_PID` payloads

**Files:**
- Create: `engineering/pid/__init__.py`, `engineering/pid/xdata.py`
- Test: `tests/test_pid_xdata.py`

**Interfaces:**
- Consumes: `backend.entity_get_xdata`, `backend.entity_set_xdata` (Task 4).
- Produces (`engineering/pid/xdata.py`): `APP_NAME = "ACADMCP_PID"`, `MARKER = "json"`, `CHUNK = 255`, `encode_payload(payload: dict) -> list[str]`, `decode_payload(values: list) -> dict | None`, `async write_payload(backend, handle, payload) -> dict`, `async read_payload(backend, handle) -> dict | None`, `symbol_payload(spec, params=None) -> dict`, `line_payload(line_class, number, size, service, spec, insulation, seq, from_ref, to_ref) -> dict`, `marker_payload(line_handle) -> dict`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_xdata.py
"""ACADMCP_PID payloads survive the 255-character XDATA string limit."""

from __future__ import annotations

import pytest

from engineering.pid.xdata import (
    APP_NAME,
    MARKER,
    decode_payload,
    encode_payload,
    line_payload,
    marker_payload,
    read_payload,
    write_payload,
)

pytestmark = pytest.mark.asyncio


def test_short_payload_is_marker_plus_one_chunk():
    values = encode_payload({"v": 1, "kind": "marker", "line": "3A"})
    assert values[0] == MARKER and len(values) == 2
    assert decode_payload(values) == {"kind": "marker", "line": "3A", "v": 1}


def test_long_payload_is_chunked_at_255_and_rejoined():
    payload = {"v": 1, "kind": "symbol", "ports": {f"N{i}": [i, i, 90] for i in range(60)}}
    values = encode_payload(payload)
    assert all(len(v) <= 255 for v in values)
    assert len(values) > 2
    assert decode_payload(values) == payload


def test_decode_rejects_foreign_or_broken_values():
    assert decode_payload([]) is None
    assert decode_payload(["not-json", "{}"]) is None
    assert decode_payload([MARKER, "{not json"]) is None


def test_builders_carry_the_documented_keys():
    line = line_payload(
        "process_major",
        "100-P-1001",
        "100",
        "P",
        "CS1",
        "IH",
        1001,
        {"handle": "2F", "port": "discharge"},
        {"handle": "31", "port": "N1"},
    )
    assert line["kind"] == "line" and line["class"] == "process_major"
    assert line["from"] == {"handle": "2F", "port": "discharge"} and line["seq"] == 1001
    assert marker_payload("3A") == {"v": 1, "kind": "marker", "line": "3A"}


async def test_roundtrip_through_a_backend(backend):
    line = await backend.entity_create_line(0, 0, 10, 0)
    payload = {"v": 1, "kind": "line", "class": "electric", "number": None}
    await write_payload(backend, line.handle, payload)
    assert await read_payload(backend, line.handle) == payload
    got = await backend.entity_get_xdata(line.handle, APP_NAME)
    assert got["xdata"][APP_NAME][0] == MARKER


async def test_read_payload_is_none_without_xdata(backend):
    line = await backend.entity_create_line(0, 0, 10, 0)
    assert await read_payload(backend, line.handle) is None
```

- [ ] **Step 2: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_pid_xdata.py -v`
Expected: FAIL with `ModuleNotFoundError: No module named 'engineering.pid'`.

- [ ] **Step 3: Write the package init and the module**

```python
# engineering/pid/__init__.py
"""P&ID expert and reader: symbol catalogue, lines, ISA-5.1 tags, graph."""
```

```python
# engineering/pid/xdata.py
"""``ACADMCP_PID`` XDATA payloads.

XDATA strings are capped at 255 characters, so a JSON payload is stored as
``["json", chunk, chunk, ...]`` and re-joined on read. Every symbol INSERT and
every P&ID line carries one, so a reader without the catalogue (another tool,
a later catalogue version) still sees ports, classes and numbers.
"""

from __future__ import annotations

import json
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

APP_NAME = "ACADMCP_PID"
MARKER = "json"
CHUNK = 255
PAYLOAD_VERSION = 1


def encode_payload(payload: dict) -> list[str]:
    text = json.dumps(payload, separators=(",", ":"), sort_keys=True, ensure_ascii=True)
    return [MARKER] + [text[i : i + CHUNK] for i in range(0, len(text), CHUNK)]


def decode_payload(values: list) -> dict | None:
    if not values or values[0] != MARKER:
        return None
    parts = [v for v in values[1:] if isinstance(v, str)]
    try:
        decoded = json.loads("".join(parts))
    except json.JSONDecodeError:
        return None
    return decoded if isinstance(decoded, dict) else None


async def write_payload(backend: AutoCADBackend, handle: str, payload: dict) -> dict:
    return await backend.entity_set_xdata(handle, APP_NAME, encode_payload(payload))


async def read_payload(backend: AutoCADBackend, handle: str) -> dict | None:
    result = await backend.entity_get_xdata(handle, APP_NAME)
    return decode_payload(result.get("xdata", {}).get(APP_NAME, []))


def symbol_payload(spec: Any, params: dict | None = None) -> dict:
    """``spec`` is an ``engineering.pid.symbols.SymbolSpec`` (typed loosely to
    avoid an import cycle). Ports are symbol-local ``[x, y, direction, kind, radius]``."""
    from .symbols import CATALOG_VERSION

    return {
        "v": PAYLOAD_VERSION,
        "kind": "symbol",
        "catalog": CATALOG_VERSION,
        "name": spec.name,
        "family": spec.family,
        "symbol": spec.symbol,
        "variant": spec.variant,
        "params": dict(params or spec.params),
        "ports": {p.name: [p.x, p.y, p.direction_deg, p.kind, p.radius] for p in spec.ports},
    }


def line_payload(
    line_class: str,
    number: str | None,
    size: str | None,
    service: str | None,
    spec: str | None,
    insulation: str | None,
    seq: int | None,
    from_ref: dict | None,
    to_ref: dict | None,
) -> dict:
    return {
        "v": PAYLOAD_VERSION,
        "kind": "line",
        "class": line_class,
        "number": number,
        "size": size,
        "service": service,
        "spec": spec,
        "insulation": insulation,
        "seq": seq,
        "from": from_ref,
        "to": to_ref,
    }


def marker_payload(line_handle: str) -> dict:
    return {"v": PAYLOAD_VERSION, "kind": "marker", "line": line_handle}
```

- [ ] **Step 4: Run the tests (the `symbol_payload` import of `CATALOG_VERSION` is exercised in Task 7)**

Run: `uv run --frozen pytest tests/test_pid_xdata.py -v`
Expected: all PASS.

- [ ] **Step 5: Commit**

```bash
git add engineering/pid/__init__.py engineering/pid/xdata.py tests/test_pid_xdata.py
git commit -m "feat(pid): ACADMCP_PID payload encoding with 255-char chunking"
```

---

### Task 6: ISA-5.1 tag grammar (`engineering/pid/tags.py`)

**Files:**
- Create: `engineering/pid/tags.py`, `tests/data/isa51_tags.json`
- Test: `tests/test_pid_tags.py`

**Interfaces:**
- Produces: `parse_tag(tag: str, kind: str = "auto", equipment_prefixes: dict | None = None) -> dict` (shape in spec §8), `split_instrument_tag(tag) -> tuple[str, str]` (`("FIC", "101A")`; area kept out, suffix kept in the loop text), `DEFAULT_EQUIPMENT_PREFIXES`, `FIRST_LETTERS`, `MODIFIERS`, `READOUT`, `OUTPUT`, `TRAILING`, `describe_tables() -> dict` (for the resource).

- [ ] **Step 1: Write the fixture**

```json
// tests/data/isa51_tags.json  (JSON has no comments — drop this line when writing the file)
{
  "valid": [
    ["FIC-101", "Flow Indicating Controller", "101"],
    ["FT-101", "Flow Transmitter", "101"],
    ["FE-101", "Flow Element", "101"],
    ["FQI-102", "Flow Totalizing Indicator", "102"],
    ["FFC-103", "Flow Ratio Controller", "103"],
    ["FY-104", "Flow Relay", "104"],
    ["FCV-105", "Flow Control Valve", "105"],
    ["FIT-106", "Flow Indicating Transmitter", "106"],
    ["PT-201", "Pressure Transmitter", "201"],
    ["PI-201", "Pressure Indicator", "201"],
    ["PG-202", "Pressure Gauge", "202"],
    ["PDT-203", "Pressure Differential Transmitter", "203"],
    ["PDI-203", "Pressure Differential Indicator", "203"],
    ["PDIC-204", "Pressure Differential Indicating Controller", "204"],
    ["PSV-205", "Pressure Safety Valve", "205"],
    ["PSL-206", "Pressure Switch Low", "206"],
    ["PSHH-207", "Pressure Switch High-high", "207"],
    ["PCV-208", "Pressure Control Valve", "208"],
    ["PIC-209", "Pressure Indicating Controller", "209"],
    ["LT-301", "Level Transmitter", "301"],
    ["LG-302", "Level Gauge", "302"],
    ["LAHH-303", "Level Alarm High-high", "303"],
    ["LAL-304", "Level Alarm Low", "304"],
    ["LSLL-305", "Level Switch Low-low", "305"],
    ["LIC-306", "Level Indicating Controller", "306"],
    ["LCV-307", "Level Control Valve", "307"],
    ["LS-308", "Level Switch", "308"],
    ["TE-401", "Temperature Element", "401"],
    ["TW-402", "Temperature Well", "402"],
    ["TIC-403", "Temperature Indicating Controller", "403"],
    ["TSE-404", "Temperature Safety Element", "404"],
    ["TAH-405", "Temperature Alarm High", "405"],
    ["TT-406", "Temperature Transmitter", "406"],
    ["TCV-407", "Temperature Control Valve", "407"],
    ["AIT-501", "Analysis Indicating Transmitter", "501"],
    ["HV-601", "Hand Valve", "601"],
    ["HS-602", "Hand Switch", "602"],
    ["HIC-603", "Hand Indicating Controller", "603"],
    ["ZSO-701", "Position Switch Open", "701"],
    ["ZSC-702", "Position Switch Closed", "702"],
    ["ZT-703", "Position Transmitter", "703"],
    ["SIC-801", "Speed Indicating Controller", "801"],
    ["WIT-802", "Weight Indicating Transmitter", "802"],
    ["VT-803", "Vibration Transmitter", "803"],
    ["JI-804", "Power Indicator", "804"],
    ["EI-805", "Voltage Indicator", "805"],
    ["II-806", "Current Indicator", "806"],
    ["BE-807", "Burner Element", "807"],
    ["RE-808", "Radiation Element", "808"],
    ["UY-809", "Multivariable Relay", "809"],
    ["PL-810", "Pressure Light", "810"]
  ],
  "user_defined": [
    ["XV-901", "Unclassified Valve", "901"],
    ["NV-902", "Valve", "902"],
    ["CIC-903", "Indicating Controller", "903"]
  ],
  "invalid": [
    ["FCI-101", "I"],
    ["FIH-102", "H"],
    ["F-103", "function"],
    ["FICC-104", "repeated"],
    ["PSVX-105", "X"],
    ["ABCDEF-106", "D"],
    ["FQQ-107", "Q"],
    ["1FC", "format"],
    ["FIC", "format"],
    ["fic-101-", "format"],
    ["LSO-108", "O"]
  ],
  "formats": [
    ["10-FIC-101A", "10", "FIC", "101", "A"],
    ["FIC 101", null, "FIC", "101", null],
    ["FIC101", null, "FIC", "101", null],
    ["fic-101b", null, "FIC", "101", "B"]
  ],
  "equipment": [
    ["P-101A", "pump", "101", "A"],
    ["V-201", "vessel", "201", ""],
    ["E-301", "exchanger", "301", ""],
    ["10-K-401", "compressor", "401", ""]
  ]
}
```

- [ ] **Step 2: Write the failing tests**

```python
# tests/test_pid_tags.py
"""ISA-5.1 identification-letter grammar, pinned against a reader-checkable fixture."""

from __future__ import annotations

import json
from pathlib import Path

import pytest

from engineering.pid.tags import (
    DEFAULT_EQUIPMENT_PREFIXES,
    describe_tables,
    parse_tag,
    split_instrument_tag,
)

FIXTURE = json.loads((Path(__file__).parent / "data" / "isa51_tags.json").read_text("utf-8"))


@pytest.mark.parametrize("tag, description, loop", FIXTURE["valid"])
def test_valid_tags_parse_with_the_standard_description(tag, description, loop):
    out = parse_tag(tag)
    assert out["valid"] is True, out["errors"]
    assert out["kind"] == "instrument"
    assert out["description"] == description
    assert out["loop"] == loop
    assert out["user_defined"] is False


@pytest.mark.parametrize("tag, description, loop", FIXTURE["user_defined"])
def test_user_choice_letters_parse_as_user_defined(tag, description, loop):
    out = parse_tag(tag)
    assert out["valid"] is True and out["user_defined"] is True
    assert out["description"] == description


@pytest.mark.parametrize("tag, fragment", FIXTURE["invalid"])
def test_invalid_tags_name_the_offending_letter(tag, fragment):
    out = parse_tag(tag, kind="instrument")
    assert out["valid"] is False
    assert out["tag"] == tag
    assert any(fragment in err for err in out["errors"]), out["errors"]


@pytest.mark.parametrize("tag, area, letters, loop, suffix", FIXTURE["formats"])
def test_tag_formats(tag, area, letters, loop, suffix):
    out = parse_tag(tag)
    assert (out["area"], out["letters"], out["loop"], out["suffix"]) == (
        area,
        letters,
        loop,
        suffix,
    )


@pytest.mark.parametrize("tag, kind, number, suffix", FIXTURE["equipment"])
def test_equipment_tags(tag, kind, number, suffix):
    out = parse_tag(tag)
    assert out["kind"] == "equipment" and out["valid"] is True
    assert out["equipment_kind"] == kind and out["number"] == number and out["suffix"] == suffix


def test_equipment_prefixes_can_be_replaced_per_call():
    out = parse_tag("Q-1", kind="equipment", equipment_prefixes={"Q": "quench tower"})
    assert out["valid"] is True and out["equipment_kind"] == "quench tower"
    default = parse_tag("Q-1", kind="equipment")
    assert default["valid"] is False and "prefix" in default["errors"][0]
    assert DEFAULT_EQUIPMENT_PREFIXES["P"] == "pump"


def test_auto_kind_prefers_instrument_then_equipment_then_reports_instrument_errors():
    assert parse_tag("PT-1")["kind"] == "instrument"
    assert parse_tag("P-1")["kind"] == "equipment"
    bad = parse_tag("FCI-1")
    assert bad["kind"] == "instrument" and bad["valid"] is False


def test_split_instrument_tag_feeds_func_and_loop_attributes():
    assert split_instrument_tag("10-FIC-101A") == ("FIC", "101A")
    assert split_instrument_tag("PT 7") == ("PT", "7")
    assert split_instrument_tag("garbage") == ("GARBAGE", "")


def test_describe_tables_is_json_serialisable_and_names_every_first_letter():
    tables = describe_tables()
    json.dumps(tables)
    assert set(tables["first_letters"]) == set("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
```

- [ ] **Step 3: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_pid_tags.py -v`
Expected: FAIL with `ModuleNotFoundError: No module named 'engineering.pid.tags'`.

- [ ] **Step 4: Write the module**

```python
# engineering/pid/tags.py
"""ISA-5.1-2009 identification letters (Table 4.1) as a deterministic grammar.

    tag      := first modifier? readout* output* trailing?
    modifier := D | F | K | Q | S
    readout  := A | B | E | G | I | L | N | O | P | R | U | W | X
    output   := C | K | S | T | U | V | X | Y | Z
    trailing := HH | LL | H | L | M | O | C

The disambiguation rules (safety S vs switch S, trailing L vs light L, ZSO/ZSC,
ratio F only after F, rate-of-change K only before an output) are the ones in
the design spec; the fixture ``tests/data/isa51_tags.json`` pins every one of
them against the standard's own examples.
"""

from __future__ import annotations

import re

#: First letter → measured/initiating variable. ``None`` = user's choice.
FIRST_LETTERS: dict[str, str | None] = {
    "A": "Analysis",
    "B": "Burner",
    "C": None,
    "D": None,
    "E": "Voltage",
    "F": "Flow",
    "G": None,
    "H": "Hand",
    "I": "Current",
    "J": "Power",
    "K": "Time",
    "L": "Level",
    "M": None,
    "N": None,
    "O": None,
    "P": "Pressure",
    "Q": "Quantity",
    "R": "Radiation",
    "S": "Speed",
    "T": "Temperature",
    "U": "Multivariable",
    "V": "Vibration",
    "W": "Weight",
    "X": "Unclassified",
    "Y": "Event",
    "Z": "Position",
}
MODIFIERS: dict[str, str] = {
    "D": "Differential",
    "F": "Ratio",
    "K": "Rate of change",
    "Q": "Totalizing",
    "S": "Safety",
}
#: Readout / passive function letters → (adjective form, noun form). ``None`` = user's choice.
READOUT: dict[str, tuple[str, str] | None] = {
    "A": ("Alarm", "Alarm"),
    "B": None,
    "E": ("Element", "Element"),
    "G": ("Gauge", "Gauge"),
    "I": ("Indicating", "Indicator"),
    "L": ("Light", "Light"),
    "N": None,
    "O": ("Orifice", "Orifice"),
    "P": ("Test point", "Test point"),
    "R": ("Recording", "Recorder"),
    "U": ("Multifunction", "Multifunction"),
    "W": ("Well", "Well"),
    "X": None,
}
#: Output / active function letters → word. ``None`` = user's choice.
OUTPUT: dict[str, str | None] = {
    "C": "Controller",
    "K": "Control station",
    "S": "Switch",
    "T": "Transmitter",
    "U": "Multifunction",
    "V": "Valve",
    "X": None,
    "Y": "Relay",
    "Z": "Driver",
}
TRAILING: dict[str, str] = {
    "HH": "High-high",
    "LL": "Low-low",
    "H": "High",
    "L": "Low",
    "M": "Middle",
    "O": "Open",
    "C": "Closed",
}
DEFAULT_EQUIPMENT_PREFIXES: dict[str, str] = {
    "P": "pump",
    "V": "vessel",
    "T": "tank",
    "E": "exchanger",
    "K": "compressor",
    "C": "column",
    "R": "reactor",
    "F": "filter",
    "D": "drum",
    "M": "mixer",
    "H": "heater",
    "S": "separator",
    "B": "blower",
    "X": "package",
}

_INSTRUMENT_RE = re.compile(
    r"^(?:(?P<area>\d{1,4})-)?(?P<letters>[A-Z]{1,5})[- ]?(?P<loop>\d{1,5})(?:[- ]?(?P<suffix>[A-Z]))?$"
)
_EQUIPMENT_RE = re.compile(
    r"^(?:(?P<area>\d{1,4})-)?(?P<prefix>[A-Z]{1,3})-(?P<number>\d{1,5})(?P<suffix>[A-Z]{0,2})$"
)


def _normalise(tag) -> str:
    return str(tag or "").strip().upper()


def _parse_letters(letters: str) -> dict:
    """Split ``letters`` into first/modifier/readout/output/trailing or report the first error."""
    errors: list[str] = []
    first = letters[0]
    i, n = 1, len(letters)
    if n == 1:
        return {"errors": [f"{letters}: a tag needs at least one function letter after {first}"]}
    modifier = None
    if letters[i] in MODIFIERS:
        candidate = letters[i]
        following = letters[i + 1] if i + 1 < n else ""
        take = (
            candidate in ("D", "Q")
            or (candidate == "S" and following in ("V", "E"))
            or (candidate == "F" and first == "F")
            or (candidate == "K" and following in OUTPUT)
        )
        if take:
            modifier = candidate
            i += 1
    readout: list[str] = []
    while i < n and letters[i] in READOUT:
        letter = letters[i]
        if letter in ("H", "L", "M") and readout and readout[-1] == "A":
            break  # trailing high/low/middle after an alarm
        if readout and readout[-1] == letter:
            errors.append(f"{letters}: repeated letter {letter} at position {i + 1}")
            return {"errors": errors}
        readout.append(letter)
        i += 1
    output: list[str] = []
    while i < n and letters[i] in OUTPUT:
        letter = letters[i]
        if letter == "C" and output and output[-1] == "S" and i == n - 1:
            break  # ZSC: closed, not controller
        if output and output[-1] == letter:
            errors.append(f"{letters}: repeated letter {letter} at position {i + 1}")
            return {"errors": errors}
        output.append(letter)
        i += 1
    trailing = letters[i:]
    if trailing:
        if trailing not in TRAILING:
            errors.append(f"{letters}: unexpected letter {trailing[0]} at position {i + 1}")
            return {"errors": errors}
        after_alarm = bool(readout) and readout[-1] == "A" and not output
        after_switch = bool(output) and output[-1] == "S"
        if trailing in ("O", "C") and not after_switch:
            errors.append(
                f"{letters}: trailing {trailing} (open/closed) is only valid after a switch"
            )
            return {"errors": errors}
        if trailing in ("H", "L", "M", "HH", "LL") and not (after_alarm or after_switch):
            errors.append(
                f"{letters}: trailing {trailing} needs an alarm (A) or switch (S) before it"
            )
            return {"errors": errors}
    return {
        "first": first,
        "modifier": modifier,
        "readout": readout,
        "output": output,
        "trailing": trailing or None,
        "errors": [],
    }


def _describe(parts: dict) -> tuple[str, bool]:
    words: list[str] = []
    user_defined = False
    first_word = FIRST_LETTERS[parts["first"]]
    if first_word is None:
        user_defined = True
    else:
        words.append(first_word)
    if parts["modifier"]:
        words.append(MODIFIERS[parts["modifier"]])
    readout, output = parts["readout"], parts["output"]
    for index, letter in enumerate(readout):
        forms = READOUT[letter]
        if forms is None:
            user_defined = True
            continue
        last_function = index == len(readout) - 1 and not output
        words.append(forms[1] if last_function else forms[0])
    for index, letter in enumerate(output):
        word = OUTPUT[letter]
        if word is None:
            user_defined = True
            continue
        if letter == "C" and index + 1 < len(output) and output[index + 1] == "V":
            word = "Control"
        words.append(word)
    if parts["trailing"]:
        words.append(TRAILING[parts["trailing"]])
    return " ".join(words), user_defined


def _parse_instrument(raw: str) -> dict:
    out = {
        "tag": raw,
        "valid": False,
        "kind": "instrument",
        "area": None,
        "letters": None,
        "first": None,
        "modifier": None,
        "readout": [],
        "output": [],
        "trailing": None,
        "loop": None,
        "suffix": None,
        "description": None,
        "user_defined": False,
        "errors": [],
    }
    tag = _normalise(raw)
    match = _INSTRUMENT_RE.match(tag)
    if not match:
        out["errors"] = [f"{raw!r}: not in [area-]LETTERS[-]loop[suffix] format"]
        return out
    out.update(
        area=match.group("area"),
        letters=match.group("letters"),
        loop=match.group("loop"),
        suffix=match.group("suffix"),
    )
    parts = _parse_letters(match.group("letters"))
    if parts["errors"]:
        out["errors"] = parts["errors"]
        return out
    description, user_defined = _describe(parts)
    out.update(
        valid=True,
        first={"letter": parts["first"], "meaning": FIRST_LETTERS[parts["first"]]},
        modifier=(
            {"letter": parts["modifier"], "meaning": MODIFIERS[parts["modifier"]]}
            if parts["modifier"]
            else None
        ),
        readout=[
            {"letter": l, "meaning": (READOUT[l] or (None, None))[1]} for l in parts["readout"]
        ],
        output=[{"letter": l, "meaning": OUTPUT[l]} for l in parts["output"]],
        trailing=parts["trailing"],
        description=description,
        user_defined=user_defined,
    )
    return out


def _parse_equipment(raw: str, prefixes: dict[str, str]) -> dict:
    out = {
        "tag": raw,
        "valid": False,
        "kind": "equipment",
        "area": None,
        "prefix": None,
        "equipment_kind": None,
        "number": None,
        "suffix": "",
        "errors": [],
    }
    match = _EQUIPMENT_RE.match(_normalise(raw))
    if not match:
        out["errors"] = [f"{raw!r}: not in [area-]PREFIX-number[suffix] format"]
        return out
    prefix = match.group("prefix")
    out.update(
        area=match.group("area"),
        prefix=prefix,
        number=match.group("number"),
        suffix=match.group("suffix") or "",
    )
    kind = prefixes.get(prefix)
    if kind is None:
        out["errors"] = [f"{raw!r}: prefix {prefix} is not in the equipment prefix map"]
        return out
    out.update(valid=True, equipment_kind=kind)
    return out


def parse_tag(tag: str, kind: str = "auto", equipment_prefixes: dict | None = None) -> dict:
    """Parse an ISA-5.1 instrument tag or an equipment tag.

    ``kind``: ``"instrument"``, ``"equipment"`` or ``"auto"`` (instrument first,
    then equipment, else the instrument parse with its errors).
    """
    prefixes = {k.upper(): v for k, v in (equipment_prefixes or DEFAULT_EQUIPMENT_PREFIXES).items()}
    if kind == "instrument":
        return _parse_instrument(tag)
    if kind == "equipment":
        return _parse_equipment(tag, prefixes)
    if kind != "auto":
        raise ValueError("kind must be 'auto', 'instrument' or 'equipment'")
    instrument = _parse_instrument(tag)
    if instrument["valid"]:
        return instrument
    equipment = _parse_equipment(tag, prefixes)
    return equipment if equipment["valid"] else instrument


def split_instrument_tag(tag: str) -> tuple[str, str]:
    """``FUNC`` and ``LOOP`` attribute texts for a bubble: letters, and loop+suffix.
    Anything unparseable goes wholesale into ``FUNC`` so nothing is dropped."""
    match = _INSTRUMENT_RE.match(_normalise(tag))
    if not match:
        return _normalise(tag), ""
    return match.group("letters"), match.group("loop") + (match.group("suffix") or "")


def describe_tables() -> dict:
    """The letter tables, for the ``autocad://standards/isa51`` resource."""
    return {
        "standard": "ISA-5.1-2009 Table 4.1",
        "grammar": "first modifier? readout* output* trailing?",
        "first_letters": {k: v or "user's choice" for k, v in FIRST_LETTERS.items()},
        "modifiers": dict(MODIFIERS),
        "readout": {k: (v[1] if v else "user's choice") for k, v in READOUT.items()},
        "output": {k: v or "user's choice" for k, v in OUTPUT.items()},
        "trailing": dict(TRAILING),
        "equipment_prefixes": dict(DEFAULT_EQUIPMENT_PREFIXES),
        "rules": [
            "S in second position is the safety modifier only before V or E (PSV, TSE); otherwise a switch.",
            "D in second position is always differential.",
            "F in second position is ratio only when the first letter is F (FFC).",
            "K in second position is rate of change only before an output letter.",
            "H/L/M after an alarm (A) or switch (S) are trailing high/low/middle; L elsewhere is a light.",
            "O/C as the last letter after a switch are open/closed (ZSO, ZSC).",
        ],
    }
```

- [ ] **Step 5: Run the tests**

Run: `uv run --frozen pytest tests/test_pid_tags.py -v`
Expected: all PASS. If a fixture row fails, check the row against ISA-5.1 Table 4.1 before touching the grammar — the fixture is the reader's contract.

- [ ] **Step 6: Commit**

```bash
git add engineering/pid/tags.py tests/data/isa51_tags.json tests/test_pid_tags.py
git commit -m "feat(pid): ISA-5.1 identification-letter grammar with a pinned fixture"
```

---

### Task 7: Symbol catalogue framework, instruments, markers, connectors

**Files:**
- Create: `engineering/pid/geometry.py`, `engineering/pid/symbols.py`
- Test: `tests/test_pid_symbols.py`

**Interfaces:**
- Produces (`geometry.py`): `line(x1,y1,x2,y2)`, `circle(cx,cy,r)`, `arc(cx,cy,r,start_deg,end_deg)`, `polyline(points, closed=True, bulges=None)`, `text(t,x,y,height,align="middle_center",rotation_deg=0.0)`, `solid(points)`, `dashed_line(x1,y1,x2,y2,on=1.0,off=1.0) -> list[dict]`, `regular_polygon(cx,cy,r,n,start_deg=0.0) -> list[tuple]`, `attdef(tag,x,y,height,align="center",invisible=False,default="")`, `bbox_of(primitives) -> tuple`.
- Produces (`symbols.py`): `Port`, `SymbolSpec`, `CATALOG_VERSION = "1"`, `FAMILY_LAYER`, `INSTRUMENT_TYPES`, `INSTRUMENT_LOCATIONS`, `BUBBLE_RADIUS = 5.0`, `register(symbol, family, builder, variants=())`, `resolve(symbol, **options) -> SymbolSpec`, `list_symbols(family=None) -> list[dict]`, `all_specs() -> list[SymbolSpec]`, `transform_port(port, x, y, rotation_deg, scale) -> dict`, `build_instrument(type, location)`, `build_marker(which)`, `build_connector(which, direction="out")`, `tag_attdefs(ymax, with_desc=True)`.
- Later tasks add builders by importing `register` from this module (`symbols_valves.py`, `symbols_equipment.py`, `symbols_vessels.py`) and `symbols.py` imports them at the bottom so `resolve` sees the whole catalogue.

- [ ] **Step 1: Write the failing tests (the harness parametrises over `all_specs()`, so Tasks 8–10 extend coverage without new test code)**

```python
# tests/test_pid_symbols.py
"""Every catalogue symbol: valid primitives, honest bbox, ports on the boundary."""

from __future__ import annotations

import math
import re

import pytest

from backends.block_specs import validate_attdef_specs, validate_entity_specs
from engineering.pid import symbols
from engineering.pid.geometry import bbox_of
from engineering.pid.symbols import (
    BUBBLE_RADIUS,
    CATALOG_VERSION,
    INSTRUMENT_LOCATIONS,
    INSTRUMENT_TYPES,
    Port,
    all_specs,
    list_symbols,
    resolve,
    transform_port,
)

NAME_RE = re.compile(r"^PID_[A-Z0-9_]+$")
SOURCE_RE = re.compile(r"^(ISO 10628-2|ISA-5\.1|PIP PIC001)")
EPS = 1e-6


def _ids():
    return [spec.name for spec in all_specs()]


@pytest.mark.parametrize("spec", all_specs(), ids=_ids())
def test_primitives_and_attdefs_validate(spec):
    validate_entity_specs(list(spec.primitives))
    validate_attdef_specs(list(spec.attdefs))


@pytest.mark.parametrize("spec", all_specs(), ids=_ids())
def test_declared_bbox_contains_every_primitive(spec):
    xmin, ymin, xmax, ymax = bbox_of(spec.primitives)
    dxmin, dymin, dxmax, dymax = spec.bbox
    assert dxmin - EPS <= xmin and dymin - EPS <= ymin
    assert xmax <= dxmax + EPS and ymax <= dymax + EPS
    assert dxmax > dxmin and dymax > dymin


@pytest.mark.parametrize("spec", all_specs(), ids=_ids())
def test_ports_sit_on_the_boundary_or_at_the_centre(spec):
    if spec.family == "marker":
        assert spec.ports == ()
        return
    assert spec.ports, "every non-marker symbol needs at least one port"
    xmin, ymin, xmax, ymax = spec.bbox
    for port in spec.ports:
        if port.direction_deg is None:
            assert port.radius > 0 and (port.x, port.y) == (0.0, 0.0)
            continue
        on_edge = (
            abs(port.x - xmin) < EPS
            or abs(port.x - xmax) < EPS
            or abs(port.y - ymin) < EPS
            or abs(port.y - ymax) < EPS
        )
        assert on_edge, (
            f"{spec.name}.{port.name} at ({port.x}, {port.y}) is inside bbox {spec.bbox}"
        )
        assert port.direction_deg in (0.0, 90.0, 180.0, 270.0)
        assert port.kind in ("process", "signal")


@pytest.mark.parametrize("spec", all_specs(), ids=_ids())
def test_naming_source_and_layer(spec):
    assert NAME_RE.match(spec.name)
    assert SOURCE_RE.match(spec.source), spec.source
    assert spec.layer_class in ("PROCESS-VALVES", "PROCESS-EQUIPMENT", "INSTRUMENT-SYMBOL", "line")
    tags = [a["tag"] for a in spec.attdefs]
    assert len(tags) == len(set(tags))
    for prim in spec.primitives:
        assert prim.get("layer", "0") == "0"


def test_catalogue_names_are_unique_and_versioned():
    names = [s.name for s in all_specs()]
    assert len(names) == len(set(names))
    assert CATALOG_VERSION == "1"


def test_instrument_generator_covers_four_types_by_five_locations():
    specs = {
        (t, loc): resolve("instrument", type=t, location=loc)
        for t in INSTRUMENT_TYPES
        for loc in INSTRUMENT_LOCATIONS
    }
    assert len(specs) == 20
    field = specs[("discrete", "field")]
    assert field.name == "PID_INST_DISCRETE_FIELD"
    assert [a["tag"] for a in field.attdefs] == ["FUNC", "LOOP"]
    assert field.ports == (Port("signal", 0.0, 0.0, None, "signal", BUBBLE_RADIUS),)
    assert sum(1 for p in field.primitives if p["type"] == "circle") == 1
    primary = specs[("discrete", "primary")]
    assert sum(1 for p in primary.primitives if p["type"] == "line") == 1
    aux_rear = specs[("plc", "auxiliary_rear")]
    assert sum(1 for p in aux_rear.primitives if p["type"] == "line") > 2, "dashed pair"
    assert sum(1 for p in aux_rear.primitives if p["type"] == "polyline") == 2, "square + diamond"
    hexagon = next(p for p in specs[("computer", "field")].primitives if p["type"] == "polyline")
    assert len(hexagon["points"]) == 6


def test_unknown_symbol_or_option_names_the_valid_values():
    with pytest.raises(ValueError, match="instrument"):
        resolve("thermometer")
    with pytest.raises(ValueError, match="field"):
        resolve("instrument", type="dcs", location="ceiling")


def test_markers_and_connectors():
    arrow = resolve("arrow_flow")
    assert arrow.family == "marker" and arrow.layer_class == "line"
    assert any(p["type"] == "solid" for p in arrow.primitives)
    for which in ("mark_pneumatic", "mark_capillary", "mark_hydraulic", "mark_data"):
        assert resolve(which).family == "marker"
    out = resolve("offpage", direction="out")
    inn = resolve("offpage", direction="in")
    assert out.name == "PID_CONNECTOR_OFFPAGE_OUT" and inn.name == "PID_CONNECTOR_OFFPAGE_IN"
    assert out.ports[0] == Port("process", -8.0, 0.0, 180.0, "process")
    assert inn.ports[0] == Port("process", 8.0, 0.0, 0.0, "process")
    assert [a["tag"] for a in out.attdefs] == ["TAG", "LINK"]
    assert next(a for a in out.attdefs if a["tag"] == "LINK")["invisible"] is True


def test_transform_port_applies_rotation_and_scale_about_the_insertion():
    port = Port("out", 4.0, 0.0, 0.0, "process")
    moved = transform_port(port, 100.0, 50.0, 90.0, 2.0)
    assert moved["x"] == pytest.approx(100.0) and moved["y"] == pytest.approx(58.0)
    assert moved["direction_deg"] == pytest.approx(90.0)
    radial = transform_port(Port("signal", 0.0, 0.0, None, "signal", 5.0), 10.0, 10.0, 45.0, 3.0)
    assert radial["direction_deg"] is None and radial["radius"] == pytest.approx(15.0)


def test_list_symbols_reports_variants_and_ports():
    rows = {row["symbol"]: row for row in list_symbols()}
    assert rows["instrument"]["variants"] == {
        "type": list(INSTRUMENT_TYPES),
        "location": list(INSTRUMENT_LOCATIONS),
    }
    assert rows["offpage"]["variants"] == {"direction": ["in", "out"]}
    assert rows["arrow_flow"]["ports"] == []
    assert list_symbols(family="marker") and all(
        r["family"] == "marker" for r in list_symbols(family="marker")
    )
```

- [ ] **Step 2: Run them to verify they fail**

Run: `uv run --frozen pytest tests/test_pid_symbols.py -v`
Expected: FAIL with `ModuleNotFoundError`.

- [ ] **Step 3: Write `geometry.py`**

```python
# engineering/pid/geometry.py
"""Primitive-spec helpers for authoring symbols (block-local millimetres)."""

from __future__ import annotations

import math


def line(x1: float, y1: float, x2: float, y2: float) -> dict:
    return {"type": "line", "x1": float(x1), "y1": float(y1), "x2": float(x2), "y2": float(y2)}


def circle(cx: float, cy: float, r: float) -> dict:
    return {"type": "circle", "cx": float(cx), "cy": float(cy), "r": float(r)}


def arc(cx: float, cy: float, r: float, start_deg: float, end_deg: float) -> dict:
    return {
        "type": "arc",
        "cx": float(cx),
        "cy": float(cy),
        "r": float(r),
        "start_deg": float(start_deg),
        "end_deg": float(end_deg),
    }


def polyline(points, closed: bool = True, bulges=None) -> dict:
    spec = {
        "type": "polyline",
        "points": [[float(x), float(y)] for x, y in points],
        "closed": closed,
    }
    if bulges is not None:
        spec["bulges"] = [float(b) for b in bulges]
    return spec


def text(
    t: str,
    x: float,
    y: float,
    height: float,
    align: str = "middle_center",
    rotation_deg: float = 0.0,
) -> dict:
    return {
        "type": "text",
        "text": t,
        "x": float(x),
        "y": float(y),
        "height": float(height),
        "align": align,
        "rotation_deg": float(rotation_deg),
    }


def solid(points) -> dict:
    return {"type": "solid", "points": [[float(x), float(y)] for x, y in points]}


def dashed_line(
    x1: float, y1: float, x2: float, y2: float, on: float = 1.0, off: float = 1.0
) -> list[dict]:
    """A dashed line as short LINE primitives, so the block needs no linetype."""
    length = math.hypot(x2 - x1, y2 - y1)
    ux, uy = (x2 - x1) / length, (y2 - y1) / length
    out: list[dict] = []
    pos = 0.0
    while pos < length - 1e-9:
        end = min(pos + on, length)
        out.append(line(x1 + ux * pos, y1 + uy * pos, x1 + ux * end, y1 + uy * end))
        pos = end + off
    return out


def regular_polygon(
    cx: float, cy: float, r: float, n: int, start_deg: float = 0.0
) -> list[tuple[float, float]]:
    return [
        (
            cx + r * math.cos(math.radians(start_deg + 360.0 * i / n)),
            cy + r * math.sin(math.radians(start_deg + 360.0 * i / n)),
        )
        for i in range(n)
    ]


def attdef(
    tag: str,
    x: float,
    y: float,
    height: float,
    align: str = "center",
    invisible: bool = False,
    default: str = "",
) -> dict:
    return {
        "tag": tag,
        "prompt": tag,
        "default": default,
        "x": float(x),
        "y": float(y),
        "height": float(height),
        "align": align,
        "invisible": invisible,
    }


def _arc_extent(cx, cy, r, start_deg, end_deg):
    pts = []
    sweep = (end_deg - start_deg) % 360.0 or 360.0
    for k in range(0, int(sweep) + 1):
        a = math.radians(start_deg + k)
        pts.append((cx + r * math.cos(a), cy + r * math.sin(a)))
    a = math.radians(end_deg)
    pts.append((cx + r * math.cos(a), cy + r * math.sin(a)))
    return pts


def bbox_of(primitives) -> tuple[float, float, float, float]:
    """Extent of the drawn geometry (text counts by its insertion point only)."""
    xs: list[float] = []
    ys: list[float] = []
    for p in primitives:
        kind = p["type"]
        if kind == "line":
            xs += [p["x1"], p["x2"]]
            ys += [p["y1"], p["y2"]]
        elif kind == "circle":
            xs += [p["cx"] - p["r"], p["cx"] + p["r"]]
            ys += [p["cy"] - p["r"], p["cy"] + p["r"]]
        elif kind == "arc":
            for x, y in _arc_extent(p["cx"], p["cy"], p["r"], p["start_deg"], p["end_deg"]):
                xs.append(x)
                ys.append(y)
        elif kind in ("polyline", "solid"):
            for x, y in p["points"]:
                xs.append(x)
                ys.append(y)
        elif kind == "text":
            xs.append(p["x"])
            ys.append(p["y"])
    if not xs:
        return (0.0, 0.0, 0.0, 0.0)
    return (min(xs), min(ys), max(xs), max(ys))
```

- [ ] **Step 4: Write `symbols.py`**

```python
# engineering/pid/symbols.py
"""The P&ID symbol catalogue: symbols as data, blocks on demand.

Every symbol is a ``SymbolSpec`` — typed primitives in symbol-local mm, ATTDEFs,
named ports with an outward direction, a declared bbox — authored from
ISO 10628-2 (equipment, valves) or ISA-5.1 (instrumentation). Builders live in
``symbols_valves.py``, ``symbols_equipment.py`` and ``symbols_vessels.py`` and
register here; this module holds the framework plus the instrument bubble,
markers and connectors.
"""

from __future__ import annotations

import hashlib
import json
import math
from collections.abc import Callable
from dataclasses import dataclass, field

from .geometry import attdef, bbox_of, circle, dashed_line, line, polyline, regular_polygon, solid

CATALOG_VERSION = "1"
BUBBLE_RADIUS = 5.0
FAMILY_LAYER = {
    "valve": "PROCESS-VALVES",
    "rotating": "PROCESS-EQUIPMENT",
    "vessel": "PROCESS-EQUIPMENT",
    "heat": "PROCESS-EQUIPMENT",
    "misc": "PROCESS-EQUIPMENT",
    "instrument": "INSTRUMENT-SYMBOL",
    "connector": "PROCESS-EQUIPMENT",
    "marker": "line",
}
INSTRUMENT_TYPES = ("discrete", "dcs", "computer", "plc")
INSTRUMENT_LOCATIONS = ("field", "primary", "auxiliary", "primary_rear", "auxiliary_rear")
TAG_HEIGHT = 2.5
DESC_HEIGHT = 2.0


@dataclass(frozen=True)
class Port:
    name: str
    x: float
    y: float
    direction_deg: float | None  # outward direction a line leaves along; None = radial
    kind: str = "process"  # "process" | "signal"
    radius: float = 0.0  # radial ports only

    def to_dict(self) -> dict:
        return {
            "name": self.name,
            "x": self.x,
            "y": self.y,
            "direction_deg": self.direction_deg,
            "kind": self.kind,
            "radius": self.radius,
        }


@dataclass(frozen=True)
class SymbolSpec:
    name: str
    family: str
    symbol: str
    variant: str | None
    primitives: tuple[dict, ...]
    attdefs: tuple[dict, ...]
    ports: tuple[Port, ...]
    bbox: tuple[float, float, float, float]
    layer_class: str
    source: str
    parametric: bool = False
    params: dict = field(default_factory=dict)

    def to_dict(self) -> dict:
        return {
            "name": self.name,
            "family": self.family,
            "symbol": self.symbol,
            "variant": self.variant,
            "ports": [p.to_dict() for p in self.ports],
            "bbox": list(self.bbox),
            "layer_class": self.layer_class,
            "source": self.source,
            "parametric": self.parametric,
            "params": dict(self.params),
        }


Builder = Callable[..., SymbolSpec]
_REGISTRY: dict[str, tuple[str, Builder, dict[str, list[str]], dict | None]] = {}


def register(
    symbol: str,
    family: str,
    builder: Builder,
    variants: dict[str, list[str]] | None = None,
    params_schema: dict | None = None,
) -> None:
    if family not in FAMILY_LAYER:
        raise ValueError(f"unknown family {family!r}")
    _REGISTRY[symbol] = (family, builder, dict(variants or {}), params_schema)


def resolve(symbol: str, **options) -> SymbolSpec:
    """Build the SymbolSpec for ``symbol`` with the given variant options."""
    if symbol not in _REGISTRY:
        raise ValueError(
            f"unknown symbol {symbol!r}; valid symbols: {', '.join(sorted(_REGISTRY))}"
        )
    family, builder, variants, schema = _REGISTRY[symbol]
    for key, value in options.items():
        if value is None:
            continue
        if key == "params":
            if schema is None:
                raise ValueError(f"{symbol} is not parametric; 'params' is only for vessels")
            continue
        if key not in variants:
            raise ValueError(f"{symbol} takes no option {key!r}")
        if value not in variants[key]:
            raise ValueError(
                f"{symbol}: {key} must be one of {', '.join(variants[key])}, got {value!r}"
            )
    return builder(**{k: v for k, v in options.items() if v is not None})


def list_symbols(family: str | None = None) -> list[dict]:
    rows = []
    for symbol, (fam, builder, variants, schema) in sorted(_REGISTRY.items()):
        if family and fam != family:
            continue
        base = builder()
        rows.append(
            {
                "symbol": symbol,
                "family": fam,
                "variants": variants,
                "ports": [p.to_dict() for p in base.ports],
                "parametric": base.parametric,
                "params_schema": schema or {},
                "source": base.source,
                "block_name": base.name,
            }
        )
    return rows


def all_specs() -> list[SymbolSpec]:
    """Every base symbol plus every enumerable variant (for tests and the contact sheet)."""
    specs: list[SymbolSpec] = []
    for symbol, (_fam, builder, variants, _schema) in sorted(_REGISTRY.items()):
        if not variants:
            specs.append(builder())
            continue
        keys = sorted(variants)
        combos: list[dict] = [{}]
        for key in keys:
            combos = [{**c, key: v} for c in combos for v in variants[key]]
        for combo in combos:
            try:
                specs.append(builder(**combo))
            except ValueError:
                continue  # a combination the builder refuses (e.g. an actuator on a check valve)
    return specs


def transform_port(port: Port, x: float, y: float, rotation_deg: float, scale: float) -> dict:
    """Symbol-local port → WCS, for an INSERT at (x, y) rotated by ``rotation_deg`` and uniformly scaled."""
    a = math.radians(rotation_deg)
    lx, ly = port.x * scale, port.y * scale
    wx = x + lx * math.cos(a) - ly * math.sin(a)
    wy = y + lx * math.sin(a) + ly * math.cos(a)
    direction = None if port.direction_deg is None else (port.direction_deg + rotation_deg) % 360.0
    return {
        "name": port.name,
        "x": wx,
        "y": wy,
        "direction_deg": direction,
        "kind": port.kind,
        "radius": port.radius * scale,
        "inferred": False,
    }


def params_hash(params: dict) -> str:
    return (
        hashlib.sha256(json.dumps(params, sort_keys=True, separators=(",", ":")).encode())
        .hexdigest()[:8]
        .upper()
    )


def tag_attdefs(ymax: float, with_desc: bool = True) -> tuple[dict, ...]:
    out = [attdef("TAG", 0.0, ymax + 3.5, TAG_HEIGHT)]
    if with_desc:
        out.append(attdef("DESC", 0.0, ymax + 6.5, DESC_HEIGHT))
    return tuple(out)


def make_spec(
    name: str,
    family: str,
    symbol: str,
    variant: str | None,
    primitives,
    attdefs,
    ports,
    source: str,
    bbox=None,
    parametric: bool = False,
    params: dict | None = None,
) -> SymbolSpec:
    prims = tuple(primitives)
    return SymbolSpec(
        name=name,
        family=family,
        symbol=symbol,
        variant=variant,
        primitives=prims,
        attdefs=tuple(attdefs),
        ports=tuple(ports),
        bbox=tuple(bbox) if bbox else bbox_of(prims),
        layer_class=FAMILY_LAYER[family],
        source=source,
        parametric=parametric,
        params=dict(params or {}),
    )


# ── instrument bubble (ISA-5.1-2009 Table 5.4.1) ─────────────────────────────


def build_instrument(type: str = "discrete", location: str = "field") -> SymbolSpec:
    r = BUBBLE_RADIUS
    prims: list[dict] = [circle(0, 0, r)]
    square = polyline([(-r, -r), (r, -r), (r, r), (-r, r)])
    if type == "dcs":
        prims.append(square)
    elif type == "computer":
        prims.append(polyline(regular_polygon(0, 0, r, 6, 0.0)))
    elif type == "plc":
        prims += [square, polyline([(0, r), (r, 0), (0, -r), (-r, 0)])]
    ys = {
        "field": [],
        "primary": [0.0],
        "auxiliary": [0.8, -0.8],
        "primary_rear": [0.0],
        "auxiliary_rear": [0.8, -0.8],
    }[location]
    for y in ys:
        prims += dashed_line(-r, y, r, y) if location.endswith("_rear") else [line(-r, y, r, y)]
    attdefs = (
        attdef("FUNC", 0.0, 2.0, DESC_HEIGHT, align="middle_center"),
        attdef("LOOP", 0.0, -2.0, DESC_HEIGHT, align="middle_center"),
    )
    ports = (Port("signal", 0.0, 0.0, None, "signal", r),)
    return make_spec(
        f"PID_INST_{type.upper()}_{location.upper()}",
        "instrument",
        "instrument",
        f"{type}_{location}",
        prims,
        attdefs,
        ports,
        "ISA-5.1-2009 Table 5.4.1",
        bbox=(-r, -r, r, r),
    )


register(
    "instrument",
    "instrument",
    build_instrument,
    variants={"type": list(INSTRUMENT_TYPES), "location": list(INSTRUMENT_LOCATIONS)},
)


# ── markers (decoration on a line; never graph nodes) ────────────────────────


def build_marker(which: str) -> SymbolSpec:
    shapes = {
        "arrow_flow": [solid([(0, 0), (-3, 1.2), (-3, -1.2)])],
        "mark_pneumatic": [line(-1.5, -1.5, 0, 1.5), line(0.5, -1.5, 2, 1.5)],
        "mark_capillary": [line(-1.2, -1.2, 1.2, 1.2), line(-1.2, 1.2, 1.2, -1.2)],
        "mark_hydraulic": [line(-1, 1.5, -1, -1.5), line(-1, -1.5, 1.5, -1.5)],
        "mark_data": [circle(0, 0, 0.8)],
    }
    return make_spec(
        f"PID_MARKER_{which.upper()}",
        "marker",
        which,
        None,
        shapes[which],
        (),
        (),
        "ISA-5.1-2009 Table 5.3.1",
    )


for _which in ("arrow_flow", "mark_pneumatic", "mark_capillary", "mark_hydraulic", "mark_data"):
    register(_which, "marker", (lambda w: lambda: build_marker(w))(_which))


# ── connectors ───────────────────────────────────────────────────────────────


def build_connector(which: str = "offpage", direction: str = "out") -> SymbolSpec:
    if which == "offpage":
        if direction == "out":
            pts = [(-8, -3), (4, -3), (8, 0), (4, 3), (-8, 3)]
            port = Port("process", -8.0, 0.0, 180.0, "process")
        else:
            pts = [(8, -3), (-4, -3), (-8, 0), (-4, 3), (8, 3)]
            port = Port("process", 8.0, 0.0, 0.0, "process")
        attdefs = (
            attdef(
                "TAG", -2.0 if direction == "out" else 2.0, 0.0, DESC_HEIGHT, align="middle_center"
            ),
            attdef("LINK", 0.0, -5.0, DESC_HEIGHT, invisible=True),
        )
        return make_spec(
            f"PID_CONNECTOR_OFFPAGE_{direction.upper()}",
            "connector",
            "offpage",
            direction,
            [polyline(pts)],
            attdefs,
            (port,),
            "PIP PIC001 off-page connector",
            bbox=(-8, -3, 8, 3),
        )
    if which == "tie_in":
        return make_spec(
            "PID_CONNECTOR_TIE_IN",
            "connector",
            "tie_in",
            None,
            [circle(0, 0, 3)],
            (attdef("TAG", 0.0, 0.0, DESC_HEIGHT, align="middle_center"),),
            (Port("in", -3.0, 0.0, 180.0), Port("out", 3.0, 0.0, 0.0)),
            "PIP PIC001 tie-in point",
        )
    if which == "spec_break":
        return make_spec(
            "PID_CONNECTOR_SPEC_BREAK",
            "connector",
            "spec_break",
            None,
            [line(0, -3, 0, 3)],
            (attdef("TAG", 0.0, 4.5, DESC_HEIGHT),),
            (Port("in", -0.3, 0.0, 180.0), Port("out", 0.3, 0.0, 0.0)),
            "PIP PIC001 specification break",
            bbox=(-0.3, -3, 0.3, 4.5),
        )
    raise ValueError(f"unknown connector {which!r}")


register(
    "offpage",
    "connector",
    lambda direction="out": build_connector("offpage", direction),
    variants={"direction": ["in", "out"]},
)
register("tie_in", "connector", lambda: build_connector("tie_in"))
register("spec_break", "connector", lambda: build_connector("spec_break"))

# Builders for valves, equipment and vessels register themselves on import.
from . import symbols_equipment as _symbols_equipment  # noqa: E402,F401
from . import symbols_valves as _symbols_valves  # noqa: E402,F401
from . import symbols_vessels as _symbols_vessels  # noqa: E402,F401
```

Until Tasks 8–10 exist, create the three builder modules as empty stubs so the import succeeds:

```python
# engineering/pid/symbols_valves.py   (replaced in Task 8)
"""Valve bodies and actuators — filled in by Task 8."""
```
(same one-line docstring for `symbols_equipment.py` and `symbols_vessels.py`).

- [ ] **Step 5: Run the tests**

Run: `uv run --frozen pytest tests/test_pid_symbols.py tests/test_pid_xdata.py -v`
Expected: all PASS (29 catalogue specs so far: 20 bubbles, 5 markers, 4 connectors).

- [ ] **Step 6: Commit**

```bash
git add engineering/pid/geometry.py engineering/pid/symbols.py engineering/pid/symbols_valves.py engineering/pid/symbols_equipment.py engineering/pid/symbols_vessels.py tests/test_pid_symbols.py
git commit -m "feat(pid): symbol catalogue framework — instruments, markers, connectors"
```

---

### Task 8: Valve bodies × actuators

**Files:**
- Replace: `engineering/pid/symbols_valves.py`
- Test: `tests/test_pid_symbols.py` (append the valve-specific tests below)

**Interfaces:**
- Produces: `VALVE_BODIES = ("gate","globe","ball","butterfly","check","needle","plug","diaphragm","three_way","angle","relief")`, `ACTUATORS = ("none","diaphragm","piston","motor","solenoid","hand")`, `build_valve(body, actuator="none") -> SymbolSpec`; symbols registered as `resolve(body, actuator=...)` (one registry entry per body; variant key `actuator`).

- [ ] **Step 1: Append the failing tests**

```python
# append to tests/test_pid_symbols.py
from engineering.pid.symbols_valves import ACTUATORS, VALVE_BODIES, build_valve


def test_valve_bodies_and_actuators_enumerate():
    assert len(VALVE_BODIES) == 11 and len(ACTUATORS) == 6
    gate = build_valve("gate")
    assert gate.name == "PID_VALVE_GATE" and gate.bbox == (-4.0, -2.0, 4.0, 2.0)
    assert {p.name: (p.x, p.y, p.direction_deg) for p in gate.ports} == {
        "in": (-4.0, 0.0, 180.0),
        "out": (4.0, 0.0, 0.0),
    }
    assert [a["tag"] for a in gate.attdefs] == ["TAG", "DESC"]


def test_actuators_add_a_signal_port_and_a_fail_attribute():
    cv = build_valve("globe", "diaphragm")
    assert cv.name == "PID_VALVE_GLOBE_DIAPHRAGM" and cv.variant == "diaphragm"
    signal = next(p for p in cv.ports if p.name == "signal")
    assert (signal.x, signal.y, signal.direction_deg, signal.kind) == (0.0, 9.0, 90.0, "signal")
    assert cv.bbox[3] == 9.0
    assert "FAIL" in [a["tag"] for a in cv.attdefs]
    hand = build_valve("gate", "hand")
    assert all(p.name != "signal" for p in hand.ports) and "FAIL" not in [
        a["tag"] for a in hand.attdefs
    ]


def test_check_and_relief_refuse_actuators():
    for body in ("check", "relief"):
        with pytest.raises(ValueError, match="actuator"):
            build_valve(body, "motor")


def test_three_way_angle_and_relief_ports():
    assert {p.name for p in build_valve("three_way").ports} == {"in", "out", "branch"}
    angle = build_valve("angle")
    assert {p.name: p.direction_deg for p in angle.ports} == {"in": 180.0, "out": 270.0}
    relief = build_valve("relief")
    assert {p.name: p.direction_deg for p in relief.ports} == {"in": 270.0, "out": 0.0}
```

- [ ] **Step 2: Run to verify they fail**

Run: `uv run --frozen pytest tests/test_pid_symbols.py -k "valve or actuator or relief" -v`
Expected: FAIL (`ImportError: cannot import name 'ACTUATORS'`).

- [ ] **Step 3: Write the module**

Actuator placement is body-relative: the stem starts at the body's `axis_top` (where its own geometry on x = 0 ends) and the glyph base sits `STEM_CLEARANCE` above the body's top edge, so the needle body (top 5.6) is never overprinted and the diaphragm dome's base coincides with the stem top (no floating dome).

```python
# engineering/pid/symbols_valves.py
"""Valve bodies (ISO 10628-2) composed with actuators (ISA-5.1 Table 5.5).

Every body is authored once in symbol-local mm (reference size 8 × 4, process
ports on the ``in`` / ``out`` faces) and any actuator stacks on top of it along
the stem at x = 0: the stem starts where the body's own geometry on that axis
ends (``axis_top``) and the actuator glyph sits ``STEM_CLEARANCE`` above the
body's top edge, so a tall body (needle, diaphragm) pushes the actuator up
instead of being overprinted by it. An actuated valve gains a ``signal`` port
on its topmost edge and a ``FAIL`` attribute; check and relief valves take no
actuator.
"""

from __future__ import annotations

from .geometry import arc, attdef, bbox_of, circle, line, polyline, text
from .symbols import DESC_HEIGHT, Port, SymbolSpec, make_spec, register, tag_attdefs

VALVE_BODIES = (
    "gate",
    "globe",
    "ball",
    "butterfly",
    "check",
    "needle",
    "plug",
    "diaphragm",
    "three_way",
    "angle",
    "relief",
)
ACTUATORS = ("none", "diaphragm", "piston", "motor", "solenoid", "hand")
NO_ACTUATOR = frozenset({"check", "relief"})
SOURCE = "ISO 10628-2:2012 valves; ISA-5.1-2009 Table 5.5 actuators"

_LEFT = polyline([(-4, -2), (-4, 2), (0, 0)])
_RIGHT = polyline([(4, -2), (4, 2), (0, 0)])
_BOTTOM = polyline([(-2, -4), (2, -4), (0, 0)])
_IN = Port("in", -4.0, 0.0, 180.0)
_OUT = Port("out", 4.0, 0.0, 0.0)
_BOX = (-4.0, -2.0, 4.0, 2.0)
# Gap between a body's top edge and the actuator glyph — the visible stem on the
# reference 8 × 4 body (stem 0..4, glyph from y = 4).
STEM_CLEARANCE = 2.0
# Extra stem (the yoke) between the clearance point and a diaphragm dome's base.
DIAPHRAGM_YOKE = 2.0

# (primitives, process ports, declared bbox, axis_top) — ``axis_top`` is the y
# where the body's own geometry on the x = 0 axis ends, i.e. where an actuator
# stem may start without overprinting it.
Body = tuple[list[dict], tuple[Port, ...], tuple[float, float, float, float], float]


def _body(body: str) -> Body:
    """Primitives, process ports, declared bbox and axis top of a bare valve body."""
    std = [_LEFT, _RIGHT]
    if body == "gate":
        return std, (_IN, _OUT), _BOX, 0.0
    if body == "globe":
        return std + [circle(0, 0, 1.0)], (_IN, _OUT), _BOX, 1.0
    if body == "ball":
        return std + [circle(0, 0, 1.8)], (_IN, _OUT), _BOX, 1.8
    if body == "butterfly":
        return std + [line(0, -2, 0, 2), circle(0, 0, 0.8)], (_IN, _OUT), _BOX, 2.0
    if body == "check":
        return std + [arc(0, 0, 2.5, 20, 160)], (_IN, _OUT), (-4.0, -2.0, 4.0, 2.5), 2.5
    if body == "needle":
        prims = std + [line(0, 0, 0, 5), circle(0, 5, 0.6)]
        return prims, (_IN, _OUT), (-4.0, -2.0, 4.0, 5.6), 5.6
    if body == "plug":
        return std + [polyline([(-1, -1), (1, -1), (1, 1), (-1, 1)])], (_IN, _OUT), _BOX, 1.0
    if body == "diaphragm":
        return std + [arc(0, 2, 2, 0, 180)], (_IN, _OUT), (-4.0, -2.0, 4.0, 4.0), 4.0
    if body == "three_way":
        ports = (_IN, _OUT, Port("branch", 0.0, -4.0, 270.0))
        return std + [_BOTTOM], ports, (-4.0, -4.0, 4.0, 2.0), 0.0
    if body == "angle":
        ports = (_IN, Port("out", 0.0, -4.0, 270.0))
        return [_LEFT, _BOTTOM], ports, (-4.0, -4.0, 2.0, 2.0), 0.0
    if body == "relief":
        spring = polyline(
            [(0, 0), (-1, 1.5), (1, 2.5), (-1, 3.5), (1, 4.5), (0, 6)],
            closed=False,
        )
        ports = (Port("in", 0.0, -4.0, 270.0), _OUT)
        return [_BOTTOM, _RIGHT, spring], ports, (-2.0, -4.0, 4.0, 6.0), 6.0
    raise ValueError(f"unknown valve body {body!r}; valid: {', '.join(VALVE_BODIES)}")


def _actuator(
    actuator: str, body_top: float, axis_top: float = 0.0
) -> tuple[list[dict], Port | None, float]:
    """Primitives above the body, the signal port (or None), and the new top y.

    The stem (always the first primitive) runs from ``axis_top`` — where the
    body's axial geometry ends — to the glyph base at
    ``body_top + STEM_CLEARANCE``; every glyph's lowest edge sits exactly on
    the stem's top, so an actuator is never drawn detached from, or over, its
    body.
    """
    if actuator == "none":
        return [], None, body_top
    base = body_top + STEM_CLEARANCE
    if actuator == "hand":
        return [line(0, axis_top, 0, base), line(-2.5, base, 2.5, base)], None, base
    if actuator == "diaphragm":
        dome = base + DIAPHRAGM_YOKE
        prims = [line(0, axis_top, 0, dome), arc(0, dome, 3, 0, 180), line(-3, dome, 3, dome)]
        return prims, Port("signal", 0.0, dome + 3.0, 90.0, "signal"), dome + 3.0
    stem = line(0, axis_top, 0, base)
    if actuator == "piston":
        top = base + 4.0
        prims = [stem, polyline([(-2, base), (2, base), (2, top), (-2, top)])]
        return prims, Port("signal", 0.0, top, 90.0, "signal"), top
    if actuator == "motor":
        top = base + 4.0
        prims = [stem, circle(0, base + 2.0, 2), text("M", 0, base + 2.0, 2.0)]
        return prims, Port("signal", 0.0, top, 90.0, "signal"), top
    if actuator == "solenoid":
        top = base + 3.0
        box = polyline([(-1.5, base), (1.5, base), (1.5, top), (-1.5, top)])
        prims = [stem, box, text("S", 0, base + 1.5, 1.8)]
        return prims, Port("signal", 0.0, top, 90.0, "signal"), top
    raise ValueError(f"unknown actuator {actuator!r}; valid: {', '.join(ACTUATORS)}")


def build_valve(body: str = "gate", actuator: str = "none") -> SymbolSpec:
    """Compose ``body`` with ``actuator`` into a ``SymbolSpec``.

    Raises ``ValueError`` for an unknown body or actuator, and for an actuator
    on a check or relief valve (they are self-acting).
    """
    prims, ports, box, axis_top = _body(body)
    if actuator not in ACTUATORS:
        raise ValueError(f"unknown actuator {actuator!r}; valid: {', '.join(ACTUATORS)}")
    if actuator != "none" and body in NO_ACTUATOR:
        raise ValueError(f"{body} valves take no actuator (got {actuator!r})")
    glyph_base = box[3] + STEM_CLEARANCE
    extra, signal, top = _actuator(actuator, box[3], axis_top)
    prims = list(prims) + extra
    ports = tuple(ports) + ((signal,) if signal else ())
    if extra:
        # An actuator can be wider than a narrow body (angle: xmax 2 vs. a hand
        # bar at ±2.5 or a diaphragm at ±3), so union its real extent, not just y.
        ax0, ay0, ax1, ay1 = bbox_of(extra)
        box = (min(box[0], ax0), min(box[1], ay0), max(box[2], ax1), max(box[3], top, ay1))
    attdefs = list(tag_attdefs(box[3]))
    if signal is not None:
        # Beside the actuator glyph (spec 4.7): right of its widest extent (±3
        # for a dome), 1.5 above the glyph base.
        attdefs.append(attdef("FAIL", 3.5, glyph_base + 1.5, DESC_HEIGHT, align="left"))
    variant = None if actuator == "none" else actuator
    name = f"PID_VALVE_{body.upper()}" + (f"_{actuator.upper()}" if variant else "")
    return make_spec(name, "valve", body, variant, prims, attdefs, ports, SOURCE, bbox=box)


def _valve_builder(body: str):
    def build(actuator: str = "none") -> SymbolSpec:
        return build_valve(body, actuator)

    return build


for _body_name in VALVE_BODIES:
    register(
        _body_name, "valve", _valve_builder(_body_name), variants={"actuator": list(ACTUATORS)}
    )
```

- [ ] **Step 4: Run the whole catalogue harness**

Run: `uv run --frozen pytest tests/test_pid_symbols.py -v`
Expected: all PASS — the harness now covers 11 bodies × 6 actuators minus the refused combinations (2 bodies × 5 actuators) = 56 valve specs plus the 29 from Task 7.

- [ ] **Step 5: Commit**

```bash
git add engineering/pid/symbols_valves.py tests/test_pid_symbols.py
git commit -m "feat(pid): 11 ISO 10628-2 valve bodies composed with 6 ISA-5.1 actuators"
```

---

### Task 9: Rotating equipment, heat transfer, miscellaneous inline symbols

**Files:**
- Replace: `engineering/pid/symbols_equipment.py`
- Test: `tests/test_pid_symbols.py` (append)

**Interfaces:**
- Produces: `ROTATING = ("centrifugal_pump","pd_pump","compressor","fan","agitator","ejector")`, `HEAT = ("shell_tube_hx","plate_hx","air_cooler","fired_heater")`, `MISC = ("filter","strainer_y","reducer","flange_pair","spectacle_blind","orifice_plate","drain_vent")`, `build_equipment(symbol, **options)`; `reducer` has variant `shape ∈ {concentric, eccentric}`.

- [ ] **Step 1: Append the failing tests**

```python
# append to tests/test_pid_symbols.py
from engineering.pid.symbols_equipment import HEAT, MISC, ROTATING


def test_equipment_families_register():
    assert len(ROTATING) == 6 and len(HEAT) == 4 and len(MISC) == 7
    pump = resolve("centrifugal_pump")
    assert pump.family == "rotating" and pump.layer_class == "PROCESS-EQUIPMENT"
    assert {p.name: p.direction_deg for p in pump.ports} == {"suction": 180.0, "discharge": 90.0}
    hx = resolve("shell_tube_hx")
    assert {p.name for p in hx.ports} == {"shell_in", "shell_out", "tube_in", "tube_out"}
    orifice = resolve("orifice_plate")
    assert next(p for p in orifice.ports if p.name == "signal").kind == "signal"
    ecc = resolve("reducer", shape="eccentric")
    assert ecc.name == "PID_MISC_REDUCER_ECCENTRIC"
    assert next(p for p in ecc.ports if p.name == "out").y == pytest.approx(-1.0)
    assert resolve("reducer").name == "PID_MISC_REDUCER_CONCENTRIC"
    assert resolve("agitator").ports[0] == Port("shaft", 0.0, 0.0, 270.0, "process")
```

- [ ] **Step 2: Run to verify they fail** — `uv run --frozen pytest tests/test_pid_symbols.py -k equipment -v` → ImportError.

- [ ] **Step 3: Write the module**

```python
# engineering/pid/symbols_equipment.py
"""Rotating equipment, heat transfer and inline miscellany (ISO 10628-2)."""

from __future__ import annotations

from .geometry import circle, line, polyline, solid, text
from .symbols import Port, SymbolSpec, make_spec, register, tag_attdefs

ROTATING = ("centrifugal_pump", "pd_pump", "compressor", "fan", "agitator", "ejector")
HEAT = ("shell_tube_hx", "plate_hx", "air_cooler", "fired_heater")
MISC = (
    "filter",
    "strainer_y",
    "reducer",
    "flange_pair",
    "spectacle_blind",
    "orifice_plate",
    "drain_vent",
)
_SRC = "ISO 10628-2:2012"
_IN, _OUT = Port("in", -4.0, 0.0, 180.0), Port("out", 4.0, 0.0, 0.0)


def _rotating(symbol: str):
    if symbol == "centrifugal_pump":
        return (
            [circle(0, 0, 4), line(0, 4, 0, 6), polyline([(-2, -1), (-2, 1), (1, 0)])],
            (Port("suction", -4.0, 0.0, 180.0), Port("discharge", 0.0, 6.0, 90.0)),
            (-4, -4, 4, 6),
        )
    if symbol == "pd_pump":
        return (
            [circle(0, 0, 4), polyline([(-2, -1.5), (2, -1.5), (0, 2)])],
            (_IN, _OUT),
            (-4, -4, 4, 4),
        )
    if symbol == "compressor":
        return ([polyline([(-4, -3), (4, -1.5), (4, 1.5), (-4, 3)])], (_IN, _OUT), (-4, -3, 4, 3))
    if symbol == "fan":
        return (
            [circle(0, 0, 4), line(-2.8, -2.8, 2.8, 2.8), line(-2.8, 2.8, 2.8, -2.8)],
            (_IN, _OUT),
            (-4, -4, 4, 4),
        )
    if symbol == "agitator":
        return (
            [line(0, 0, 0, 8), circle(0, 10, 2), text("M", 0, 10, 2.0), line(-3, 0, 3, 0)],
            (Port("shaft", 0.0, 0.0, 270.0),),
            (-3, 0, 3, 12),
        )
    if symbol == "ejector":
        return (
            [
                polyline([(-4, -1.5), (0, -1.5), (4, -0.75), (4, 0.75), (0, 1.5), (-4, 1.5)]),
                line(0, -1.5, 0, -4),
            ],
            (Port("motive", -4.0, 0.0, 180.0), Port("suction", 0.0, -4.0, 270.0), _OUT),
            (-4, -4, 4, 1.5),
        )
    raise ValueError(symbol)


def _heat(symbol: str):
    if symbol == "shell_tube_hx":
        return (
            [
                polyline([(-12, -4), (12, -4), (12, 4), (-12, 4)]),
                line(-9, -4, -9, 4),
                line(9, -4, 9, 4),
            ],
            (
                Port("tube_in", -12.0, 0.0, 180.0),
                Port("tube_out", 12.0, 0.0, 0.0),
                Port("shell_in", -4.0, 4.0, 90.0),
                Port("shell_out", 4.0, -4.0, 270.0),
            ),
            (-12, -4, 12, 4),
        )
    if symbol == "plate_hx":
        return (
            [
                polyline([(-4, -6), (4, -6), (4, 6), (-4, 6)]),
                line(-4, -6, 4, 6),
                line(-4, 6, 4, -6),
            ],
            (
                Port("hot_in", -4.0, 3.0, 180.0),
                Port("hot_out", 4.0, -3.0, 0.0),
                Port("cold_in", 4.0, 3.0, 0.0),
                Port("cold_out", -4.0, -3.0, 180.0),
            ),
            (-4, -6, 4, 6),
        )
    if symbol == "air_cooler":
        return (
            [
                polyline([(-10, -3), (10, -3), (10, 3), (-10, 3)]),
                circle(0, -6, 2.5),
                line(-1.8, -7.8, 1.8, -4.2),
                line(-1.8, -4.2, 1.8, -7.8),
            ],
            (Port("in", -10.0, 0.0, 180.0), Port("out", 10.0, 0.0, 0.0)),
            (-10, -8.5, 10, 3),
        )
    if symbol == "fired_heater":
        return (
            [
                polyline([(-6, -8), (6, -8), (6, 4), (2, 4), (2, 10), (-2, 10), (-2, 4), (-6, 4)]),
                polyline([(-4, -6), (4, -4), (-4, -2), (4, 0), (-4, 2)], closed=False),
            ],
            (
                Port("in", -6.0, -4.0, 180.0),
                Port("out", 6.0, 2.0, 0.0),
                Port("flue", 0.0, 10.0, 90.0),
            ),
            (-6, -8, 6, 10),
        )
    raise ValueError(symbol)


def _misc(symbol: str, shape: str = "concentric"):
    if symbol == "filter":
        return (
            [polyline([(-4, -4), (4, -4), (4, 4), (-4, 4)]), line(-4, 4, 4, -4)],
            (_IN, _OUT),
            (-4, -4, 4, 4),
        )
    if symbol == "strainer_y":
        return (
            [line(-4, 0, 4, 0), line(0, 0, 3, -4), line(2, -4.7, 4, -3.3)],
            (_IN, _OUT),
            (-4, -5, 4, 0),
        )
    if symbol == "reducer":
        if shape == "eccentric":
            return (
                [polyline([(-3, -2), (3, -2), (3, 0), (-3, 2)])],
                (Port("in", -3.0, 0.0, 180.0), Port("out", 3.0, -1.0, 0.0)),
                (-3, -2, 3, 2),
            )
        return (
            [polyline([(-3, -2), (3, -1), (3, 1), (-3, 2)])],
            (Port("in", -3.0, 0.0, 180.0), Port("out", 3.0, 0.0, 0.0)),
            (-3, -2, 3, 2),
        )
    if symbol == "flange_pair":
        return (
            [line(-0.6, -2.5, -0.6, 2.5), line(0.6, -2.5, 0.6, 2.5)],
            (Port("in", -0.6, 0.0, 180.0), Port("out", 0.6, 0.0, 0.0)),
            (-0.6, -2.5, 0.6, 2.5),
        )
    if symbol == "spectacle_blind":
        return (
            [
                line(0, -3.5, 0, 3.5),
                circle(0, 2, 1.5),
                solid([(0, -0.5), (1.5, -2), (0, -3.5), (-1.5, -2)]),
            ],
            (Port("in", -1.5, 0.0, 180.0), Port("out", 1.5, 0.0, 0.0)),
            (-1.5, -3.5, 1.5, 3.5),
        )
    if symbol == "orifice_plate":
        return (
            [line(-0.5, -3, -0.5, 3), line(0.5, -3, 0.5, 3)],
            (
                Port("in", -0.5, 0.0, 180.0),
                Port("out", 0.5, 0.0, 0.0),
                Port("signal", 0.0, 3.0, 90.0, "signal"),
            ),
            (-0.5, -3, 0.5, 3),
        )
    if symbol == "drain_vent":
        return (
            [line(0, 0, 0, -4), line(-1.5, -4, 1.5, -4)],
            (Port("in", 0.0, 0.0, 90.0),),
            (-1.5, -4, 1.5, 0),
        )
    raise ValueError(symbol)


def build_equipment(symbol: str, shape: str = "concentric") -> SymbolSpec:
    if symbol in ROTATING:
        family, (prims, ports, box) = "rotating", _rotating(symbol)
    elif symbol in HEAT:
        family, (prims, ports, box) = "heat", _heat(symbol)
    elif symbol in MISC:
        family, (prims, ports, box) = "misc", _misc(symbol, shape)
    else:
        raise ValueError(f"unknown equipment {symbol!r}")
    variant = shape if symbol == "reducer" else None
    name = f"PID_{family.upper()}_{symbol.upper()}" + (f"_{variant.upper()}" if variant else "")
    return make_spec(
        name, family, symbol, variant, prims, tag_attdefs(box[3]), ports, _SRC, bbox=box
    )


for _name in ROTATING + HEAT + MISC:
    if _name == "reducer":
        register(
            _name,
            "misc",
            lambda shape="concentric": build_equipment("reducer", shape),
            variants={"shape": ["concentric", "eccentric"]},
        )
    else:
        _family = "rotating" if _name in ROTATING else ("heat" if _name in HEAT else "misc")
        register(_name, _family, (lambda s: lambda: build_equipment(s))(_name))
```

- [ ] **Step 4: Run the harness** — `uv run --frozen pytest tests/test_pid_symbols.py -v` → all PASS (the `agitator` bbox `(-3, 0, 3, 12)` puts its shaft port on the bottom edge; `strainer_y`'s ports sit on its top edge `y = 0`).

- [ ] **Step 5: Commit**

```bash
git add engineering/pid/symbols_equipment.py tests/test_pid_symbols.py
git commit -m "feat(pid): rotating, heat-transfer and inline equipment symbols"
```

---

### Task 10: Parametric vessels

**Files:**
- Replace: `engineering/pid/symbols_vessels.py`
- Test: `tests/test_pid_symbols.py` (append)

**Interfaces:**
- Produces: `VESSELS = ("vertical_vessel","horizontal_vessel","tank","column","reactor","hopper")`, `build_vessel(symbol, params=None) -> SymbolSpec` with `parametric=True`, `params` validated (`validate_vessel_params(symbol, params) -> dict` raising `ValueError` naming the key), block name `PID_VESSEL_<SYMBOL>_<8 hex>`; default nozzles `N1 top 0.5, N2 bottom 0.5, N3 left 0.7, N4 right 0.3`.
- Registry: `resolve("vertical_vessel", params={...})`; `list_symbols()` rows carry `params_schema`.

- [ ] **Step 1: Append the failing tests**

```python
# append to tests/test_pid_symbols.py
from engineering.pid.symbols_vessels import VESSELS, build_vessel, validate_vessel_params


def test_vessels_are_parametric_and_hash_named():
    assert len(VESSELS) == 6
    v = build_vessel("vertical_vessel")
    assert v.parametric is True and v.name.startswith("PID_VESSEL_VERTICAL_VESSEL_")
    assert len(v.name.rsplit("_", 1)[1]) == 8
    assert {p.name: p.direction_deg for p in v.ports} == {
        "N1": 90.0,
        "N2": 270.0,
        "N3": 180.0,
        "N4": 0.0,
    }
    same = build_vessel("vertical_vessel", {"width": 20, "height": 40})
    assert same.name == v.name, "identical parameters share one definition"
    other = build_vessel("vertical_vessel", {"width": 30})
    assert other.name != v.name


def test_vessel_nozzles_are_where_the_parameters_say():
    v = build_vessel(
        "vertical_vessel",
        {"width": 20, "height": 40, "nozzles": [{"name": "F", "side": "right", "fraction": 0.25}]},
    )
    port = v.ports[0]
    assert (port.name, port.x, port.y, port.direction_deg) == ("F", 13.0, -10.0, 0.0)
    assert v.bbox == (-10.0, -20.0, 13.0, 20.0)


def test_vessel_variants_draw_their_features():
    column = build_vessel("column", {"trays": 5})
    assert sum(1 for p in column.primitives if p["type"] == "line") >= 5 + 2
    cone = build_vessel("tank", {"roof": "cone"})
    assert any(p["type"] == "polyline" and not p["closed"] for p in cone.primitives)
    jacketed = build_vessel("reactor", {"jacketed": True})
    assert jacketed.bbox[2] == pytest.approx(12.0 + 5.0), "half width 12 + jacket 2 + stub 3"
    hopper = build_vessel("hopper")
    assert {p.direction_deg for p in hopper.ports} == {90.0, 270.0}


@pytest.mark.parametrize(
    "params, key",
    [
        ({"width": 0}, "width"),
        ({"height": -1}, "height"),
        ({"nozzles": [{"name": "A", "side": "up", "fraction": 0.5}]}, "side"),
        ({"nozzles": [{"name": "A", "side": "top", "fraction": 1.5}]}, "fraction"),
        (
            {
                "nozzles": [
                    {"name": "A", "side": "top", "fraction": 0.5},
                    {"name": "A", "side": "top", "fraction": 0.2},
                ]
            },
            "name",
        ),
        ({"trays": -2}, "trays"),
        ({"roof": "dome"}, "roof"),
        ({"bogus": 1}, "bogus"),
    ],
)
def test_vessel_params_are_validated(params, key):
    symbol = "column" if "trays" in params else ("tank" if "roof" in params else "vertical_vessel")
    with pytest.raises(ValueError, match=key):
        validate_vessel_params(symbol, params)
```

- [ ] **Step 2: Run to verify they fail** — ImportError.

- [ ] **Step 3: Write the module**

```python
# engineering/pid/symbols_vessels.py
"""Parametric vessels (ISO 10628-2): size and nozzles come from the caller."""

from __future__ import annotations

from .geometry import arc, line, polyline
from .symbols import Port, SymbolSpec, make_spec, params_hash, register, tag_attdefs

VESSELS = ("vertical_vessel", "horizontal_vessel", "tank", "column", "reactor", "hopper")
SIDES = ("top", "bottom", "left", "right")
DEFAULT_NOZZLES = [
    {"name": "N1", "side": "top", "fraction": 0.5},
    {"name": "N2", "side": "bottom", "fraction": 0.5},
    {"name": "N3", "side": "left", "fraction": 0.7},
    {"name": "N4", "side": "right", "fraction": 0.3},
]
_DEFAULTS = {
    "vertical_vessel": {"width": 20.0, "height": 40.0},
    "horizontal_vessel": {"width": 40.0, "height": 20.0},
    "tank": {"width": 24.0, "height": 24.0, "roof": "flat"},
    "column": {"width": 16.0, "height": 60.0, "trays": 0},
    "reactor": {"width": 24.0, "height": 36.0, "jacketed": False},
    "hopper": {"width": 24.0, "height": 24.0},
}
PARAMS_SCHEMA = {
    "width": "float > 0 (mm)",
    "height": "float > 0 (mm)",
    "nozzles": "[{name, side: top|bottom|left|right, fraction: 0..1}]",
    "roof": "tank only: flat | cone",
    "trays": "column only: int >= 0",
    "jacketed": "reactor only: bool",
}
STUB = 3.0


def validate_vessel_params(symbol: str, params: dict | None) -> dict:
    if symbol not in VESSELS:
        raise ValueError(f"unknown vessel {symbol!r}; valid: {', '.join(VESSELS)}")
    merged = dict(_DEFAULTS[symbol])
    merged["nozzles"] = [dict(n) for n in DEFAULT_NOZZLES]
    if symbol == "hopper":
        merged["nozzles"] = [dict(n) for n in DEFAULT_NOZZLES[:2]]
    for key, value in (params or {}).items():
        if key not in merged:
            raise ValueError(
                f"{symbol}: unknown parameter {key!r}; valid: {', '.join(sorted(merged))}"
            )
        merged[key] = value
    for key in ("width", "height"):
        v = merged[key]
        if isinstance(v, bool) or not isinstance(v, (int, float)) or v <= 0:
            raise ValueError(f"{symbol}: {key} must be a number > 0")
        merged[key] = float(v)
    if "roof" in merged and merged["roof"] not in ("flat", "cone"):
        raise ValueError(f"{symbol}: roof must be 'flat' or 'cone'")
    if "trays" in merged and (
        isinstance(merged["trays"], bool)
        or not isinstance(merged["trays"], int)
        or merged["trays"] < 0
    ):
        raise ValueError(f"{symbol}: trays must be an int >= 0")
    if "jacketed" in merged and not isinstance(merged["jacketed"], bool):
        raise ValueError(f"{symbol}: jacketed must be a bool")
    nozzles = merged["nozzles"]
    if not isinstance(nozzles, list):
        raise ValueError(f"{symbol}: nozzles must be a list")
    names: set[str] = set()
    clean = []
    for i, n in enumerate(nozzles):
        if not isinstance(n, dict) or not isinstance(n.get("name"), str) or not n["name"]:
            raise ValueError(f"{symbol}: nozzles[{i}].name must be a non-empty string")
        if n["name"] in names:
            raise ValueError(f"{symbol}: nozzles[{i}].name {n['name']!r} is repeated")
        names.add(n["name"])
        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)
        if isinstance(f, bool) or not isinstance(f, (int, float)) or not 0.0 <= f <= 1.0:
            raise ValueError(f"{symbol}: nozzles[{i}].fraction must be within 0..1")
        clean.append({"name": n["name"], "side": n["side"], "fraction": float(f)})
    merged["nozzles"] = clean
    return merged


def _nozzles(params: dict, half_w: float, half_h: float, extra: float = 0.0):
    """Nozzle stub primitives and ports on a box of ±half_w × ±half_h."""
    prims, ports = [], []
    stub = STUB + extra
    for n in params["nozzles"]:
        side, f = n["side"], n["fraction"]
        if side == "top":
            x, y0, y1, d = -half_w + f * 2 * half_w, half_h, half_h + stub, 90.0
            prims.append(line(x, y0, x, y1))
            ports.append(Port(n["name"], x, y1, d))
        elif side == "bottom":
            x, y0, y1, d = -half_w + f * 2 * half_w, -half_h, -half_h - stub, 270.0
            prims.append(line(x, y0, x, y1))
            ports.append(Port(n["name"], x, y1, d))
        elif side == "left":
            y, x0, x1, d = -half_h + f * 2 * half_h, -half_w, -half_w - stub, 180.0
            prims.append(line(x0, y, x1, y))
            ports.append(Port(n["name"], x1, y, d))
        else:
            y, x0, x1, d = -half_h + f * 2 * half_h, half_w, half_w + stub, 0.0
            prims.append(line(x0, y, x1, y))
            ports.append(Port(n["name"], x1, y, d))
    return prims, ports


def _capsule_vertical(w: float, h: float) -> list[dict]:
    r = w / 2
    body = h / 2 - r
    return [
        line(-r, -body, -r, body),
        line(r, -body, r, body),
        arc(0, body, r, 0, 180),
        arc(0, -body, r, 180, 360),
    ]


def _capsule_horizontal(w: float, h: float) -> list[dict]:
    r = h / 2
    body = w / 2 - r
    return [
        line(-body, -r, body, -r),
        line(-body, r, body, r),
        arc(body, 0, r, 270, 90),
        arc(-body, 0, r, 90, 270),
    ]


def build_vessel(symbol: str = "vertical_vessel", params: dict | None = None) -> SymbolSpec:
    p = validate_vessel_params(symbol, params)
    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)
    elif symbol == "horizontal_vessel":
        prims = _capsule_horizontal(w, h)
    elif symbol == "tank":
        roof = w / 6 if p["roof"] == "cone" else 0.0
        prims = [
            polyline(
                [
                    (-half_w, -half_h),
                    (half_w, -half_h),
                    (half_w, half_h - roof),
                    (-half_w, half_h - roof),
                ]
            )
        ]
        if roof:
            prims.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)
        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 - 2, -body, -half_w - 2, body),
                line(half_w + 2, -body, half_w + 2, body),
            ]
            extra = 2.0
    else:  # hopper
        prims = [
            polyline([(-half_w, half_h), (half_w, half_h), (w / 6, -half_h), (-w / 6, -half_h)])
        ]
    nozzle_prims, ports = _nozzles(p, 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]
    box = (min(xs), min(ys), max(xs), max(ys))
    return make_spec(
        f"PID_VESSEL_{symbol.upper()}_{params_hash(p)}",
        "vessel",
        symbol,
        None,
        prims,
        tag_attdefs(box[3]),
        ports,
        "ISO 10628-2:2012 vessels",
        bbox=box,
        parametric=True,
        params=p,
    )


for _name in VESSELS:
    register(
        _name,
        "vessel",
        (lambda s: lambda params=None: build_vessel(s, params))(_name),
        params_schema=PARAMS_SCHEMA,
    )
```

- [ ] **Step 4: Run the harness** — `uv run --frozen pytest tests/test_pid_symbols.py -v` → all PASS.

- [ ] **Step 5: Commit**

```bash
git add engineering/pid/symbols_vessels.py tests/test_pid_symbols.py
git commit -m "feat(pid): six parametric vessel symbols with nozzle ports"
```

---
### Task 11: Symbol insertion service + `pid_symbol_list` / `pid_symbol_insert` (SECTION 17 opens)

**Files:**
- Modify: `engineering/layers.py` (`PID_LAYERS` + `PROCESS-LINE-TEXT`)
- Create: `engineering/pid/insert.py`
- Modify: `server.py` (new `SECTION 17: P&ID (2 tools)` header before the RESOURCES block; the count grows in later tasks), `discovery/aliases.py`, `README.md` (`157 tools` → `159 tools`), regenerate inventory
- Modify: `engineering/pid/__init__.py` (re-exports)
- Test: `tests/test_pid_insert.py`

**Interfaces:**
- Consumes: `resolve`, `transform_port`, `FAMILY_LAYER` (Task 7), `symbol_payload`, `write_payload`, `marker_payload` (Task 5), `parse_tag`, `split_instrument_tag` (Task 6), `backend.block_define`, `backend.block_insert`, `backend.block_list`, `backend.layer_list`, `backend.layer_create`.
- Produces (`engineering/pid/insert.py`):
  - `async ensure_layer(backend, layer_name) -> bool` (True when created; P&ID layers get their `PID_LAYERS` definition, anything else colour 7 / Continuous)
  - `async ensure_block(backend, spec) -> bool` (True when defined now)
  - `async insert_symbol(backend, spec, x, y, rotation=0.0, scale=1.0, attributes=None, layer=None, payload=None) -> dict` with keys `handle, block_name, defined, layers_created, ports, layer`
  - `async place_symbol(backend, symbol, x, y, rotation=0.0, scale=1.0, tag=None, desc=None, fail=None, link=None, layer=None, **options) -> dict` — the tool body; adds `tag`, `tag_warnings`, `backend`.
  - `FAIL_POSITIONS = ("", "FO", "FC", "FL")`

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_insert.py
"""pid_symbol_insert: define on first use, insert with attributes, WCS ports, XDATA."""

from __future__ import annotations

import pytest

from engineering.pid.insert import ensure_layer, place_symbol
from engineering.pid.symbols import resolve
from engineering.pid.xdata import read_payload

pytestmark = pytest.mark.asyncio


async def test_first_insert_defines_the_block_and_creates_its_layer(backend):
    result = await place_symbol(backend, "gate", 100.0, 50.0, tag="HV-101")
    assert result["defined"] is True and result["layers_created"] == ["PROCESS-VALVES"]
    assert result["block_name"] == "PID_VALVE_GATE" and result["layer"] == "PROCESS-VALVES"
    assert result["ports"]["in"] == {
        "name": "in",
        "x": 96.0,
        "y": 50.0,
        "direction_deg": 180.0,
        "kind": "process",
        "radius": 0.0,
        "inferred": False,
    }
    assert result["tag"] == "HV-101" and result["tag_warnings"] == []
    assert await backend.block_get_attributes(result["handle"]) == {"TAG": "HV-101", "DESC": ""}
    again = await place_symbol(backend, "gate", 200.0, 50.0, tag="HV-102")
    assert again["defined"] is False and again["layers_created"] == []


async def test_rotation_and_scale_move_the_ports(backend):
    result = await place_symbol(
        backend, "centrifugal_pump", 0.0, 0.0, rotation=90.0, scale=2.0, tag="P-101"
    )
    discharge = result["ports"]["discharge"]
    assert (discharge["x"], discharge["y"], discharge["direction_deg"]) == pytest.approx(
        (-12.0, 0.0, 180.0)
    )


async def test_instrument_tag_splits_into_func_and_loop(backend):
    result = await place_symbol(
        backend, "instrument", 10, 10, tag="10-FIC-101A", type="dcs", location="primary"
    )
    assert await backend.block_get_attributes(result["handle"]) == {"FUNC": "FIC", "LOOP": "101A"}
    assert result["block_name"] == "PID_INST_DCS_PRIMARY" and result["layer"] == "INSTRUMENT-SYMBOL"
    assert (
        result["ports"]["signal"]["radius"] == 5.0
        and result["ports"]["signal"]["direction_deg"] is None
    )


async def test_invalid_tag_is_written_and_warned_not_refused(backend):
    result = await place_symbol(backend, "instrument", 0, 0, tag="FCI-9")
    assert await backend.block_get_attributes(result["handle"]) == {"FUNC": "FCI", "LOOP": "9"}
    assert result["tag_warnings"] and "I" in result["tag_warnings"][0]


async def test_actuator_fail_and_offpage_link_attributes(backend):
    cv = await place_symbol(backend, "globe", 0, 0, tag="FCV-105", actuator="diaphragm", fail="FC")
    assert (await backend.block_get_attributes(cv["handle"]))["FAIL"] == "FC"
    assert "signal" in cv["ports"]
    with pytest.raises(ValueError, match="FO, FC, FL"):
        await place_symbol(backend, "globe", 0, 0, actuator="diaphragm", fail="XX")
    off = await place_symbol(
        backend, "offpage", 0, 0, tag="TO P&ID-002", link="L-17", direction="out"
    )
    assert (await backend.block_get_attributes(off["handle"]))["LINK"] == "L-17"
    with pytest.raises(ValueError, match="link"):
        await place_symbol(backend, "gate", 0, 0, link="L-1")


async def test_xdata_payload_carries_ports_and_params(backend):
    result = await place_symbol(
        backend, "vertical_vessel", 0, 0, tag="V-201", params={"width": 20, "height": 40}
    )
    payload = await read_payload(backend, result["handle"])
    assert payload["kind"] == "symbol" and payload["catalog"] == "1"
    assert payload["params"]["width"] == 20.0 and set(payload["ports"]) == {"N1", "N2", "N3", "N4"}


async def test_refusals(backend):
    with pytest.raises(ValueError, match="scale"):
        await place_symbol(backend, "gate", 0, 0, scale=0)
    with pytest.raises(ValueError, match="pid_line_draw"):
        await place_symbol(backend, "arrow_flow", 0, 0)
    with pytest.raises(ValueError, match="params"):
        await place_symbol(backend, "gate", 0, 0, params={"width": 1})
    with pytest.raises(ValueError, match="actuator"):
        await place_symbol(backend, "check", 0, 0, actuator="motor")


async def test_layer_override_and_ensure_layer(backend):
    assert await ensure_layer(backend, "PROCESS-LINE-TEXT") is True
    assert await ensure_layer(backend, "PROCESS-LINE-TEXT") is False
    layers = {lyr.name: lyr for lyr in await backend.layer_list()}
    assert layers["PROCESS-LINE-TEXT"].lineweight == 25.0, (
        "LayerInfo reports DXF hundredths of a millimetre"
    )
    result = await place_symbol(backend, "gate", 0, 0, layer="MY-VALVES")
    assert result["layer"] == "MY-VALVES" and result["layers_created"] == ["MY-VALVES"]
    spec = resolve("gate")
    assert spec.name in {b.name for b in await backend.block_list()}
```

- [ ] **Step 2: Run to verify they fail** — `uv run --frozen pytest tests/test_pid_insert.py -v` → ModuleNotFoundError.

- [ ] **Step 3: Add the layer and write the service**

In `engineering/layers.py`, insert into `PID_LAYERS` after the `INSTRUMENT-TAG-TEXT` entry:

```python
(("PROCESS-LINE-TEXT", 7, "Continuous", 0.25, "line numbers"),)
```

```python
# engineering/pid/insert.py
"""Placing catalogue symbols: define the block on first use, insert with
attributes, write the ACADMCP_PID payload, return the ports in WCS."""

from __future__ import annotations

from typing import TYPE_CHECKING

from engineering.layers import PID_LAYERS

from .symbols import FAMILY_LAYER, SymbolSpec, resolve, transform_port
from .tags import parse_tag, split_instrument_tag
from .xdata import symbol_payload, write_payload

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

FAIL_POSITIONS = ("", "FO", "FC", "FL")
_PID_LAYER_DEFS = {name: (color, linetype, lw) for name, color, linetype, lw, _desc in PID_LAYERS}


async def ensure_layer(backend: AutoCADBackend, layer_name: str) -> bool:
    """Create ``layer_name`` if missing — from PID_LAYERS when it is one of ours."""
    existing = {lyr.name.lower() for lyr in await backend.layer_list()}
    if layer_name.lower() in existing:
        return False
    color, linetype, lineweight = _PID_LAYER_DEFS.get(layer_name, (7, "Continuous", 0.25))
    await backend.layer_create(
        name=layer_name, color=color, linetype=linetype, lineweight=lineweight
    )
    return True


async def ensure_block(backend: AutoCADBackend, spec: SymbolSpec) -> bool:
    names = {blk.name for blk in await backend.block_list()}
    if spec.name in names:
        return False
    await backend.block_define(
        spec.name, list(spec.primitives), list(spec.attdefs), 0.0, 0.0, False
    )
    return True


async def insert_symbol(
    backend: AutoCADBackend,
    spec: SymbolSpec,
    x: float,
    y: float,
    rotation: float = 0.0,
    scale: float = 1.0,
    attributes: dict | None = None,
    layer: str | None = None,
    payload: dict | None = None,
) -> dict:
    layer_name = layer or FAMILY_LAYER[spec.family]
    if layer_name == "line":
        raise ValueError(f"{spec.name}: markers need an explicit layer (the line's)")
    created = await ensure_layer(backend, layer_name)
    defined = await ensure_block(backend, spec)
    values = {att["tag"]: att["default"] for att in spec.attdefs}
    values.update({k: str(v) for k, v in (attributes or {}).items()})
    ref = await backend.block_insert(
        spec.name, x, y, scale, scale, rotation, values or None, layer_name
    )
    await write_payload(backend, ref.handle, payload or symbol_payload(spec))
    ports = {p.name: transform_port(p, x, y, rotation, scale) for p in spec.ports}
    return {
        "handle": ref.handle,
        "block_name": spec.name,
        "defined": defined,
        "layers_created": [layer_name] if created else [],
        "ports": ports,
        "layer": layer_name,
    }


async def place_symbol(
    backend: AutoCADBackend,
    symbol: str,
    x: float,
    y: float,
    rotation: float = 0.0,
    scale: float = 1.0,
    tag: str | None = None,
    desc: str | None = None,
    fail: str | None = None,
    link: str | None = None,
    layer: str | None = None,
    **options,
) -> dict:
    """The ``pid_symbol_insert`` tool body."""
    if scale <= 0:
        raise ValueError("scale must be > 0")
    spec = resolve(symbol, **options)
    if spec.family == "marker":
        raise ValueError(f"{symbol} is a line marker; pid_line_draw places markers and arrows")
    tags_present = {att["tag"] for att in spec.attdefs}
    attributes: dict[str, str] = {}
    warnings: list[str] = []
    tag_text: str | None = None
    if tag:
        tag_text = tag.strip()
        if spec.family == "instrument":
            parsed = parse_tag(tag_text, kind="instrument")
            func, loop = split_instrument_tag(tag_text)
            attributes.update(FUNC=func, LOOP=loop)
        else:
            parsed = parse_tag(tag_text, kind="auto")
            attributes["TAG"] = tag_text
        if not parsed["valid"]:
            warnings.extend(parsed["errors"])
    if desc is not None:
        if "DESC" not in tags_present:
            warnings.append(f"{symbol} has no DESC attribute; description ignored")
        else:
            attributes["DESC"] = desc
    if fail is not None:
        if "FAIL" not in tags_present:
            raise ValueError(f"{symbol}: 'fail' needs an actuator (no FAIL attribute)")
        if fail.upper() not in FAIL_POSITIONS:
            raise ValueError("fail must be one of FO, FC, FL (or empty)")
        attributes["FAIL"] = fail.upper()
    if link is not None:
        if "LINK" not in tags_present:
            raise ValueError(f"{symbol}: 'link' is only valid for offpage connectors")
        attributes["LINK"] = link
    result = await insert_symbol(backend, spec, x, y, rotation, scale, attributes, layer)
    result.update(tag=tag_text, tag_warnings=warnings, backend=backend.name)
    return result
```

Add to `engineering/pid/__init__.py`:

```python
from .insert import ensure_block, ensure_layer, insert_symbol, place_symbol  # noqa: F401
from .symbols import CATALOG_VERSION, Port, SymbolSpec, all_specs, list_symbols, resolve  # noqa: F401
from .tags import parse_tag, split_instrument_tag  # noqa: F401
```

- [ ] **Step 4: Run the tests** — `uv run --frozen pytest tests/test_pid_insert.py tests/test_pid_symbols.py -v` → all PASS. (`backend.name` is the existing backend name property used by `system_status`; it returns `"ezdxf"` / `"com"`.)

- [ ] **Step 5: Register the two tools**

In `server.py`, before the `# ── RESOURCES` block, add:

```python
# ---------------------------------------------------------------------------
# ── SECTION 17: P&ID (2 tools) ──────────────────────────────────────────────
# ---------------------------------------------------------------------------


@cad_tool(
    summary="List the P&ID symbol catalogue: families, variants, ports, parameters.", cost="read"
)
@mcp.tool(
    annotations={"title": "P&ID: Symbol Catalogue", "readOnlyHint": True},
    tags={"pid", "query"},
)
async def pid_symbol_list(
    family: Annotated[
        str | None,
        "valve | rotating | vessel | heat | misc | instrument | connector | marker; omit for all",
    ] = None,
    ctx: Context = None,
) -> dict:
    """The symbols `pid_symbol_insert` can place, with their ports and variant options.

    Authored from ISO 10628-2 (equipment, valves) and ISA-5.1 (instrumentation);
    each row's `source` names the figure. Symbol-local sizes are millimetres at
    A3/A1 paper scale (bubble Ø10, valve 8×4); `scale` at insertion rescales.
    """
    from engineering.pid.symbols import CATALOG_VERSION, list_symbols

    return {"catalog_version": CATALOG_VERSION, "symbols": list_symbols(family)}


@cad_tool(
    summary="Place a P&ID symbol (valve, pump, vessel, instrument bubble, connector) as a tagged block with ports.",
    cost="mutate",
)
@mcp.tool(
    annotations={"title": "P&ID: Insert Symbol", "readOnlyHint": False},
    tags={"pid", "create"},
)
async def pid_symbol_insert(
    symbol: Annotated[
        str,
        "Catalogue symbol name, e.g. gate, centrifugal_pump, vertical_vessel, instrument, offpage",
    ],
    x: Annotated[float, "Insertion X (WCS)"],
    y: Annotated[float, "Insertion Y (WCS)"],
    rotation: Annotated[float, "Rotation in degrees; 0 = flow left to right"] = 0.0,
    scale: Annotated[float, Field(default=1.0, gt=0, description="Uniform scale")] = 1.0,
    tag: Annotated[
        str | None, "Tag: equipment P-101, valve HV-101, instrument FIC-101 (split into FUNC/LOOP)"
    ] = None,
    desc: Annotated[str | None, "Description attribute"] = None,
    actuator: Annotated[
        str | None, "Valves: none | diaphragm | piston | motor | solenoid | hand"
    ] = None,
    fail: Annotated[str | None, "Actuated valves: FO | FC | FL"] = None,
    type: Annotated[str | None, "Instruments: discrete | dcs | computer | plc"] = None,
    location: Annotated[
        str | None, "Instruments: field | primary | auxiliary | primary_rear | auxiliary_rear"
    ] = None,
    params: Annotated[
        dict | None,
        "Parametric vessels: {width, height, nozzles: [{name, side, fraction}], roof, trays, jacketed}",
    ] = None,
    shape: Annotated[str | None, "Reducer: concentric | eccentric"] = None,
    direction: Annotated[str | None, "Off-page connector: in | out"] = None,
    link: Annotated[str | None, "Off-page connector link id shared by both ends"] = None,
    layer: Annotated[str | None, "Override the family layer"] = None,
    ctx: Context = None,
) -> dict:
    """Insert a catalogue symbol as a real block with TAG attributes and named ports.

    Defines the block on first use (`defined`), creates a missing family layer
    from the P&ID layer set (`layers_created`), writes an ACADMCP_PID payload
    so readers without the catalogue still see the ports, and returns every
    port in WCS — connect them with `pid_line_draw`. An invalid ISA-5.1 tag is
    written and reported in `tag_warnings`; `drawing_critique` flags it.
    """
    from engineering.pid.insert import place_symbol

    await ctx.info(f"P&ID symbol {symbol} at ({x}, {y})")
    return await place_symbol(
        _backend(ctx),
        symbol,
        x,
        y,
        rotation,
        scale,
        tag,
        desc,
        fail,
        link,
        layer,
        actuator=actuator,
        type=type,
        location=location,
        params=params,
        shape=shape,
        direction=direction,
    )
```

Also insert `"pid"` at the **front** of `_GROUP_TAG_PRIORITY` and add `"pid": "pid"` to `_GROUP_TAG_LABELS`.

Alias records:

```python
    "pid_symbol_list": ToolAliases(
        acad=(),
        synonyms=("p&id symbols", "pid symbol catalogue", "which valves can i draw", "instrument bubble types"),
    ),
    "pid_symbol_insert": ToolAliases(
        acad=("INSERT",),
        synonyms=("p&id symbol", "insert a valve", "place a pump", "draw a vessel", "instrument bubble",
                  "control valve", "off-page connector", "process equipment symbol"),
    ),
```

Regenerate the inventory; README `159 tools`.

- [ ] **Step 6: Run the gates and commit**

Run: `uv run --frozen pytest tests/test_pid_insert.py tests/test_discovery_aliases.py tests/test_tool_inventory.py tests/test_release_consistency.py tests/test_tool_registry.py -v`

```bash
git add engineering/layers.py engineering/pid/insert.py engineering/pid/__init__.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_pid_insert.py
git commit -m "feat(pid): pid_symbol_list and pid_symbol_insert — blocks with tags, ports and XDATA"
```

---

### Task 12: Pure routing, labels, markers, crossings, line numbers (`engineering/pid/lines.py`)

**Files:**
- Create: `engineering/pid/lines.py`
- Test: `tests/test_pid_lines.py`

**Interfaces:**
- Produces: `LineClass(layer, linetype, marker, arrow, kind)`, `LINE_CLASSES: dict[str, LineClass]`, `LAYER_TO_CLASS`, `PID_LINE_LAYERS`, `AXIS`, `snap_axis(dx, dy) -> float`, `route(start, start_dir, end, end_dir, stub=5.0, mode="auto") -> list[tuple[float, float]]`, `simplify(points)`, `path_length(points)`, `label_placement(vertices, offset=1.5) -> (x, y, rotation_deg, segment_index)`, `marker_positions(vertices, min_len=15.0) -> list[(x, y, rotation_deg)]`, `segments_cross(p1, p2, q1, q2) -> bool`, `count_crossings(vertices, others) -> int`, `format_line_number(fmt, **fields) -> str`, `DEFAULT_NUMBER_FORMAT`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_lines.py
"""Routing is geometry, so it is tested without a backend."""

from __future__ import annotations

import pytest

from engineering.pid.lines import (
    DEFAULT_NUMBER_FORMAT,
    LINE_CLASSES,
    count_crossings,
    format_line_number,
    label_placement,
    marker_positions,
    route,
    snap_axis,
)


def test_line_classes_map_to_layers_and_markers():
    assert set(LINE_CLASSES) == {
        "process_major",
        "process_minor",
        "utility",
        "pneumatic",
        "electric",
        "hydraulic",
        "capillary",
        "data",
    }
    assert LINE_CLASSES["process_major"].layer == "PROCESS-PIPING-MAIN"
    assert (
        LINE_CLASSES["electric"].layer == "INSTRUMENT-LINE-SIGNAL"
        and LINE_CLASSES["electric"].linetype is None
    )
    assert (
        LINE_CLASSES["pneumatic"].linetype == "Continuous"
        and LINE_CLASSES["pneumatic"].marker == "mark_pneumatic"
    )
    assert LINE_CLASSES["process_major"].arrow is True and LINE_CLASSES["pneumatic"].arrow is False
    assert LINE_CLASSES["utility"].kind == "process" and LINE_CLASSES["data"].kind == "signal"


def test_snap_axis_picks_the_dominant_component():
    assert snap_axis(10, 1) == 0.0 and snap_axis(-10, 1) == 180.0
    assert snap_axis(1, 10) == 90.0 and snap_axis(1, -10) == 270.0


def test_straight_when_aligned_and_facing():
    assert route((0, 0), 0.0, (50, 0), 180.0) == [(0.0, 0.0), (50.0, 0.0)]


def test_l_route_when_perpendicular():
    path = route((0, 0), 0.0, (50, 30), 270.0)
    assert path == [(0.0, 0.0), (50.0, 0.0), (50.0, 30.0)]


def test_z_route_when_parallel_and_offset():
    path = route((0, 0), 0.0, (60, 20), 180.0, stub=5.0)
    assert path == [(0.0, 0.0), (30.0, 0.0), (30.0, 20.0), (60.0, 20.0)]


def test_ports_facing_away_on_one_axis_need_waypoints():
    with pytest.raises(ValueError, match="waypoints"):
        route((0, 0), 180.0, (40, 0), 0.0, stub=5.0)
    path = route((0, 0), 180.0, (40, 0), 0.0, mode=[(-5, 0), (-5, -10), (45, -10), (45, 0)])
    assert len(path) == 6


def test_stub_is_honoured_or_refused():
    with pytest.raises(ValueError, match="stub"):
        route((0, 0), 0.0, (3, 8), 180.0, stub=5.0)
    assert route((0, 0), 0.0, (3, 0), 180.0, stub=5.0) == [(0.0, 0.0), (3.0, 0.0)], (
        "a straight run is exempt"
    )


def test_radial_ends_take_the_axis_towards_the_other_end():
    path = route((0, 0), None, (0, 40), None)
    assert path == [(0.0, 0.0), (0.0, 40.0)]


def test_direct_and_waypoints():
    assert route((0, 0), 0.0, (10, 7), 90.0, mode="direct") == [(0.0, 0.0), (10.0, 7.0)]
    assert route((0, 0), 0.0, (10, 7), 90.0, mode=[(10, 0)]) == [
        (0.0, 0.0),
        (10.0, 0.0),
        (10.0, 7.0),
    ]
    with pytest.raises(ValueError, match="repeat"):
        route((0, 0), 0.0, (10, 7), 90.0, mode=[(0, 0)])
    with pytest.raises(ValueError, match="zero"):
        route((0, 0), 0.0, (0, 0), 90.0)


def test_label_sits_left_of_the_longest_segment_and_never_upside_down():
    x, y, rot, index = label_placement([(0, 0), (10, 0), (10, 40), (0, 40)])
    assert index == 1 and rot == 90.0
    assert (x, y) == pytest.approx((8.5, 20.0))
    x, y, rot, index = label_placement([(50, 0), (0, 0)])
    assert rot == 0.0 and y == pytest.approx(1.5)


def test_markers_only_on_segments_long_enough():
    marks = marker_positions([(0, 0), (10, 0), (10, 40)], min_len=15.0)
    assert marks == [(10.0, 20.0, 90.0)]
    assert marker_positions([(0, 0), (30, 0)]) == [(15.0, 0.0, 0.0)]


def test_crossings_count_proper_intersections_only():
    others = [[(5, -5), (5, 5)], [(20, 0), (20, 10)], [(0, 3), (8, 3)]]
    assert count_crossings([(0, 0), (10, 0)], others) == 1
    assert count_crossings([(0, 0), (20, 0)], [[(20, 0), (20, 10)]]) == 0, (
        "touching an endpoint is a junction"
    )


def test_line_number_format_drops_empty_fields():
    assert DEFAULT_NUMBER_FORMAT == "{size}-{service}-{seq}-{spec}-{insulation}"
    assert (
        format_line_number(
            DEFAULT_NUMBER_FORMAT, size="100", service="P", seq=1001, spec="CS1", insulation="IH"
        )
        == "100-P-1001-CS1-IH"
    )
    assert (
        format_line_number(DEFAULT_NUMBER_FORMAT, size="100", service="P", seq=1001) == "100-P-1001"
    )
    assert format_line_number("L-{seq}", seq=7) == "L-7"
    with pytest.raises(ValueError, match="unknown"):
        format_line_number("{bogus}", seq=1)
```

- [ ] **Step 2: Run to verify they fail** — ModuleNotFoundError.

- [ ] **Step 3: Write the module**

```python
# engineering/pid/lines.py
"""Line classes (ISA-5.1 Table 5.3.1), orthogonal routing, labels, markers, crossings."""

from __future__ import annotations

import math
import re
from dataclasses import dataclass


@dataclass(frozen=True)
class LineClass:
    layer: str
    linetype: str | None  # None = ByLayer
    marker: str | None  # marker symbol placed on long segments
    arrow: bool  # flow arrow at the end by default
    kind: str  # "process" | "signal"


LINE_CLASSES: dict[str, LineClass] = {
    "process_major": LineClass("PROCESS-PIPING-MAIN", None, None, True, "process"),
    "process_minor": LineClass("PROCESS-PIPING-SECONDARY", None, None, True, "process"),
    "utility": LineClass("UTILITY-LINE", None, None, True, "process"),
    "pneumatic": LineClass(
        "INSTRUMENT-LINE-SIGNAL", "Continuous", "mark_pneumatic", False, "signal"
    ),
    "electric": LineClass("INSTRUMENT-LINE-SIGNAL", None, None, False, "signal"),
    "hydraulic": LineClass(
        "INSTRUMENT-LINE-SIGNAL", "Continuous", "mark_hydraulic", False, "signal"
    ),
    "capillary": LineClass(
        "INSTRUMENT-LINE-SIGNAL", "Continuous", "mark_capillary", False, "signal"
    ),
    "data": LineClass("INSTRUMENT-LINE-SIGNAL", "Continuous", "mark_data", False, "signal"),
}
#: Layer → class when a line carries no payload. ``None`` = decide by linetype.
LAYER_TO_CLASS: dict[str, str | None] = {
    "PROCESS-PIPING-MAIN": "process_major",
    "PROCESS-PIPING-SECONDARY": "process_minor",
    "UTILITY-LINE": "utility",
    "ELECTRICAL-LINE": "electric",
    "INSTRUMENT-LINE-SIGNAL": None,
}
PID_LINE_LAYERS = frozenset(LAYER_TO_CLASS)
AXIS = {0.0: (1.0, 0.0), 90.0: (0.0, 1.0), 180.0: (-1.0, 0.0), 270.0: (0.0, -1.0)}
DEFAULT_NUMBER_FORMAT = "{size}-{service}-{seq}-{spec}-{insulation}"
_EPS = 1e-9

Point = tuple[float, float]


def snap_axis(dx: float, dy: float) -> float:
    if abs(dx) >= abs(dy):
        return 0.0 if dx >= 0 else 180.0
    return 90.0 if dy >= 0 else 270.0


def _unit(direction_deg: float) -> Point:
    return AXIS[float(direction_deg) % 360.0]


def _dist(a: Point, b: Point) -> float:
    return math.hypot(b[0] - a[0], b[1] - a[1])


def path_length(points) -> float:
    return sum(_dist(a, b) for a, b in zip(points, points[1:]))


def simplify(points) -> list[Point]:
    """Drop repeated points and merge collinear consecutive segments."""
    pts: list[Point] = []
    for p in points:
        q = (float(p[0]), float(p[1]))
        if not pts or _dist(pts[-1], q) > _EPS:
            pts.append(q)
    out: list[Point] = []
    for p in pts:
        if len(out) >= 2:
            a, b = out[-2], out[-1]
            cross = (b[0] - a[0]) * (p[1] - b[1]) - (b[1] - a[1]) * (p[0] - b[0])
            dot = (b[0] - a[0]) * (p[0] - b[0]) + (b[1] - a[1]) * (p[1] - b[1])
            if abs(cross) < _EPS and dot > 0:
                out[-1] = p
                continue
        out.append(p)
    return out


def _direction(a: Point, b: Point) -> Point:
    length = _dist(a, b)
    return ((b[0] - a[0]) / length, (b[1] - a[1]) / length)


def _same(u: Point, v: Point) -> bool:
    return abs(u[0] - v[0]) < 1e-6 and abs(u[1] - v[1]) < 1e-6


def _validate(candidate, ds: float | None, de: float | None, stub: float) -> list[Point] | None:
    pts = simplify(candidate)
    if len(pts) < 2:
        return None
    segs = list(zip(pts, pts[1:]))
    straight = len(segs) == 1
    if ds is not None and not _same(_direction(*segs[0]), _unit(ds)):
        return None
    if de is not None:
        ue = _unit(de)
        if not _same(_direction(*segs[-1]), (-ue[0], -ue[1])):
            return None
    minimum = 0.01 if straight else max(stub, 0.01)
    if any(_dist(a, b) < minimum - _EPS for a, b in segs):
        return None
    for (a1, b1), (a2, b2) in zip(segs, segs[1:]):
        u, v = _direction(a1, b1), _direction(a2, b2)
        if abs(u[0] * v[0] + u[1] * v[1]) > 1e-6:
            return None
    return pts


def route(start, start_dir, end, end_dir, stub: float = 5.0, mode="auto") -> list[Point]:
    """Orthogonal path from ``start`` (leaving along ``start_dir``) to ``end``
    (arriving against ``end_dir``). ``None`` directions are radial: the axis
    towards the other end. Raises ``ValueError`` when no candidate honours the stub."""
    s: Point = (float(start[0]), float(start[1]))
    e: Point = (float(end[0]), float(end[1]))
    if isinstance(mode, (list, tuple)):
        path = [s] + [(float(p[0]), float(p[1])) for p in mode] + [e]
        for a, b in zip(path, path[1:]):
            if _dist(a, b) < 0.01:
                raise ValueError("waypoints repeat a point (segment shorter than 0.01 mm)")
        return path
    if _dist(s, e) < 0.01:
        raise ValueError("zero-length line: both ends are the same point")
    if mode == "direct":
        return [s, e]
    if mode != "auto":
        raise ValueError("route must be 'auto', 'direct' or a list of waypoints")
    if stub < 0:
        raise ValueError("stub must be >= 0")
    ds = snap_axis(e[0] - s[0], e[1] - s[1]) if start_dir is None else float(start_dir) % 360.0
    de = snap_axis(s[0] - e[0], s[1] - e[1]) if end_dir is None else float(end_dir) % 360.0
    us, ue = _unit(ds), _unit(de)
    s1 = (s[0] + us[0] * stub, s[1] + us[1] * stub)
    e1 = (e[0] + ue[0] * stub, e[1] + ue[1] * stub)
    xm, ym = (s1[0] + e1[0]) / 2.0, (s1[1] + e1[1]) / 2.0
    candidates = [
        [s, e],
        [s, (e[0], s[1]), e],
        [s, (s[0], e[1]), e],
        [s, (xm, s[1]), (xm, e[1]), e],
        [s, (s[0], ym), (e[0], ym), e],
        [s, s1, (s1[0], e1[1]), e1, e],
        [s, s1, (e1[0], s1[1]), e1, e],
    ]
    valid = [p for p in (_validate(c, ds, de, stub) for c in candidates) if p]
    if not valid:
        raise ValueError(
            f"no orthogonal route from {s} to {e} honours a {stub} mm stub on both ports; "
            "shorten `stub` or pass waypoints"
        )
    valid.sort(key=lambda p: (len(p) - 2, path_length(p)))
    return valid[0]


def label_placement(vertices, offset: float = 1.5) -> tuple[float, float, float, int]:
    """Midpoint of the longest segment, offset to its left, readable rotation."""
    pts = [(float(x), float(y)) for x, y in vertices]
    segs = list(zip(pts, pts[1:]))
    index = max(range(len(segs)), key=lambda i: _dist(*segs[i]))
    (x0, y0), (x1, y1) = segs[index]
    angle = math.degrees(math.atan2(y1 - y0, x1 - x0)) % 360.0
    if 90.0 < angle <= 270.0:
        angle = (angle - 180.0) % 360.0
    ux, uy = math.cos(math.radians(angle)), math.sin(math.radians(angle))
    mx, my = (x0 + x1) / 2.0, (y0 + y1) / 2.0
    return (mx - uy * offset, my + ux * offset, round(angle, 6), index)


def marker_positions(vertices, min_len: float = 15.0) -> list[tuple[float, float, float]]:
    pts = [(float(x), float(y)) for x, y in vertices]
    out = []
    for (x0, y0), (x1, y1) in zip(pts, pts[1:]):
        if _dist((x0, y0), (x1, y1)) < min_len:
            continue
        angle = math.degrees(math.atan2(y1 - y0, x1 - x0)) % 360.0
        out.append(((x0 + x1) / 2.0, (y0 + y1) / 2.0, round(angle, 6)))
    return out


def _orient(a: Point, b: Point, c: Point) -> float:
    return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])


def segments_cross(p1, p2, q1, q2) -> bool:
    """Proper crossing only: shared endpoints and T-touches are junctions, not crossings."""
    d1, d2 = _orient(q1, q2, p1), _orient(q1, q2, p2)
    d3, d4 = _orient(p1, p2, q1), _orient(p1, p2, q2)
    return d1 * d2 < -_EPS and d3 * d4 < -_EPS


def count_crossings(vertices, others) -> int:
    pts = [(float(x), float(y)) for x, y in vertices]
    count = 0
    for a, b in zip(pts, pts[1:]):
        for other in others:
            opts = [(float(x), float(y)) for x, y in other]
            for c, d in zip(opts, opts[1:]):
                if segments_cross(a, b, c, d):
                    count += 1
    return count


_FIELD_RE = re.compile(r"^\{(\w+)\}$")
_KNOWN_FIELDS = {"size", "service", "seq", "spec", "insulation", "area", "unit"}


def format_line_number(fmt: str, **fields) -> str:
    """Fill ``fmt`` (``-``-separated tokens) and drop the empty fields with their separators."""
    kept: list[str] = []
    for token in fmt.split("-"):
        match = _FIELD_RE.match(token)
        if not match:
            kept.append(token)
            continue
        name = match.group(1)
        if name not in _KNOWN_FIELDS:
            raise ValueError(
                f"unknown line-number field {{{name}}}; known: {', '.join(sorted(_KNOWN_FIELDS))}"
            )
        value = fields.get(name)
        if value is None or value == "":
            continue
        kept.append(str(value))
    return "-".join(kept)
```

- [ ] **Step 4: Run the tests** — `uv run --frozen pytest tests/test_pid_lines.py -v` → all PASS. (Ports facing away along one axis have no orthogonal route: every U candidate collapses to a reversal after `simplify`, which the perpendicular check rejects — that is why the test expects the refusal and passes waypoints. The U candidates still serve ports facing away on *different* axes.)

- [ ] **Step 5: Commit**

```bash
git add engineering/pid/lines.py tests/test_pid_lines.py
git commit -m "feat(pid): line classes, orthogonal routing, labels, markers, crossings"
```

---

### Task 13: `pid_line_draw`

**Files:**
- Create: `engineering/pid/drawlines.py`
- Modify: `server.py` (SECTION 17 header → `(3 tools)`), `discovery/aliases.py`, `README.md` (`160 tools`), inventory
- Test: `tests/test_pid_line_draw.py`

**Interfaces:**
- Consumes: `route`, `label_placement`, `marker_positions`, `count_crossings`, `format_line_number`, `LINE_CLASSES`, `PID_LINE_LAYERS`, `snap_axis`, `AXIS` (Task 12); `insert_symbol`, `ensure_layer` (Task 11); `read_payload`, `write_payload`, `line_payload`, `marker_payload` (Task 5); `resolve`, `Port`, `transform_port` (Task 7); backend `entity_get`, `entity_list`, `entity_create_polyline`, `entity_set_properties`, `entity_create_text`.
- Produces: `async resolve_endpoint(backend, ref) -> dict` (`x, y, direction_deg, kind, radius, handle, port, block_name`), `async existing_pid_lines(backend) -> list[dict]` (`handle, vertices, payload`), `async draw_line(backend, from_, to, line_class="process_major", route_mode="auto", stub=5.0, line_number=None, size=None, service=None, spec=None, insulation=None, number_format=None, label=True, arrow=None) -> dict` with keys `handle, vertices, line_class, layer, line_number, from, to, port_reuse, crossings, label_handle, arrow_handle, marker_handles, backend`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_line_draw.py
"""pid_line_draw: port-to-port orthogonal lines with class, number, markers, arrows."""

from __future__ import annotations

import pytest

from engineering.pid.drawlines import draw_line
from engineering.pid.insert import place_symbol
from engineering.pid.xdata import read_payload

pytestmark = pytest.mark.asyncio


async def _pump_and_vessel(backend):
    pump = await place_symbol(backend, "centrifugal_pump", 100, 100, tag="P-101")
    vessel = await place_symbol(backend, "vertical_vessel", 220, 120, tag="V-201")
    return pump, vessel


async def test_process_line_between_ports(backend):
    pump, vessel = await _pump_and_vessel(backend)
    result = await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": vessel["handle"], "port": "N3"},
        line_class="process_major",
        size="100",
        service="P",
        spec="CS1",
    )
    assert result["layer"] == "PROCESS-PIPING-MAIN" and result["line_class"] == "process_major"
    assert result["vertices"][0] == [100.0, 106.0] and result["vertices"][-1] == [207.0, 128.0]
    assert result["line_number"] == "100-P-1-CS1" and result["label_handle"]
    assert result["arrow_handle"] and result["marker_handles"] == []
    assert result["crossings"] == 0 and result["port_reuse"] == []
    info = await backend.entity_get(result["handle"])
    assert info.type == "LWPOLYLINE" and info.layer == "PROCESS-PIPING-MAIN"
    payload = await read_payload(backend, result["handle"])
    assert payload["kind"] == "line" and payload["from"] == {
        "handle": pump["handle"],
        "port": "discharge",
    }
    assert payload["seq"] == 1
    label = await backend.entity_get(result["label_handle"])
    assert label.layer == "PROCESS-LINE-TEXT" and label.properties["text"] == "100-P-1-CS1"
    arrow = await backend.entity_get(result["arrow_handle"])
    assert (
        arrow.properties["block_name"] == "PID_MARKER_ARROW_FLOW"
        and arrow.layer == "PROCESS-PIPING-MAIN"
    )


async def test_sequence_increments_and_number_can_be_given(backend):
    pump, vessel = await _pump_and_vessel(backend)
    first = await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": vessel["handle"], "port": "N3"},
        size="100",
        service="P",
    )
    second = await draw_line(
        backend,
        {"handle": vessel["handle"], "port": "N4"},
        {"x": 300, "y": 128},
        size="80",
        service="P",
    )
    assert (first["line_number"], second["line_number"]) == ("100-P-1", "80-P-2")
    third = await draw_line(
        backend,
        {"handle": vessel["handle"], "port": "N1"},
        {"x": 210, "y": 200},
        line_number="VENT-01",
    )
    assert third["line_number"] == "VENT-01"


async def test_signal_line_from_a_bubble_gets_markers_and_no_arrow(backend):
    cv = await place_symbol(backend, "globe", 100, 100, tag="FCV-1", actuator="diaphragm")
    fic = await place_symbol(
        backend, "instrument", 100, 160, tag="FIC-1", type="dcs", location="primary"
    )
    result = await draw_line(
        backend,
        {"handle": fic["handle"]},
        {"handle": cv["handle"], "port": "signal"},
        line_class="pneumatic",
    )
    assert result["vertices"][0] == [100.0, 155.0], "the line starts on the bubble's circle"
    assert result["vertices"][-1] == [100.0, 109.0]
    assert result["arrow_handle"] is None and len(result["marker_handles"]) == 1
    mark = await backend.entity_get(result["marker_handles"][0])
    assert mark.properties["block_name"] == "PID_MARKER_MARK_PNEUMATIC"
    assert mark.layer == "INSTRUMENT-LINE-SIGNAL"
    line = await backend.entity_get(result["handle"])
    assert line.linetype == "Continuous"
    electric = await draw_line(
        backend, {"handle": fic["handle"]}, {"x": 160, "y": 160}, line_class="electric"
    )
    assert (await backend.entity_get(electric["handle"])).linetype == "ByLayer"


async def test_port_reuse_and_crossings_are_reported_not_refused(backend):
    pump, vessel = await _pump_and_vessel(backend)
    await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": vessel["handle"], "port": "N3"},
    )
    again = await draw_line(
        backend, {"handle": pump["handle"], "port": "discharge"}, {"x": 100, "y": 200}
    )
    assert again["port_reuse"] == [{"handle": pump["handle"], "port": "discharge"}]
    crossing = await draw_line(
        backend, {"x": 150, "y": 90}, {"x": 150, "y": 140}, line_class="utility"
    )
    assert crossing["crossings"] == 1


async def test_refusals(backend):
    pump, vessel = await _pump_and_vessel(backend)
    with pytest.raises(ValueError, match="same"):
        await draw_line(
            backend,
            {"handle": pump["handle"], "port": "discharge"},
            {"handle": pump["handle"], "port": "discharge"},
        )
    with pytest.raises(ValueError, match="discharge, suction"):  # payload ports are JSON-sorted
        await draw_line(backend, {"handle": pump["handle"], "port": "outlet"}, {"x": 0, "y": 0})
    with pytest.raises(ValueError, match="choose a port"):
        await draw_line(backend, {"handle": pump["handle"]}, {"x": 0, "y": 0})
    with pytest.raises(ValueError, match="line_class"):
        await draw_line(backend, {"x": 0, "y": 0}, {"x": 10, "y": 0}, line_class="steam")
    first = await draw_line(
        backend, {"handle": pump["handle"], "port": "discharge"}, {"x": 100, "y": 200}
    )
    with pytest.raises(ValueError, match="decoration"):
        await draw_line(backend, {"handle": first["arrow_handle"], "port": "in"}, {"x": 0, "y": 0})
    with pytest.raises(ValueError, match="not a P&ID symbol"):
        line = await backend.entity_create_line(0, 0, 1, 1)
        await draw_line(backend, {"handle": line.handle, "port": "in"}, {"x": 0, "y": 0})
```

- [ ] **Step 2: Run to verify they fail** — ModuleNotFoundError.

- [ ] **Step 3: Write the orchestration**

```python
# engineering/pid/drawlines.py
"""``pid_line_draw``: resolve ports, route, draw, label, mark, tag with XDATA."""

from __future__ import annotations

from typing import TYPE_CHECKING

from .insert import ensure_layer, insert_symbol
from .lines import (
    AXIS,
    DEFAULT_NUMBER_FORMAT,
    LINE_CLASSES,
    PID_LINE_LAYERS,
    count_crossings,
    format_line_number,
    label_placement,
    marker_positions,
    route,
    snap_axis,
)
from .symbols import Port, resolve, transform_port
from .xdata import line_payload, marker_payload, read_payload, write_payload

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

TEXT_HEIGHT = 2.5
LABEL_LAYER = "PROCESS-LINE-TEXT"
_INSERT_TYPES = {"INSERT", "BLOCKREFERENCE"}


async def resolve_endpoint(backend: AutoCADBackend, ref: dict) -> dict:
    """``{handle, port}`` → the port in WCS (payload ports + INSERT transform); ``{x, y}`` → a free point."""
    if not isinstance(ref, dict):
        raise ValueError("endpoint must be {handle, port} or {x, y}")
    if "handle" in ref:
        handle = str(ref["handle"])
        info = await backend.entity_get(handle)
        block_name = str(info.properties.get("block_name", ""))
        if block_name.startswith("PID_MARKER_"):
            raise ValueError(f"{handle} is a marker/arrow — decoration on a line, not an endpoint")
        payload = await read_payload(backend, handle)
        if info.type not in _INSERT_TYPES or payload is None or payload.get("kind") != "symbol":
            raise ValueError(f"{handle} is not a P&ID symbol placed by pid_symbol_insert")
        ports = payload["ports"]
        port_name = ref.get("port")
        if port_name is None:
            if len(ports) == 1:
                port_name = next(iter(ports))
            elif payload.get("family") == "instrument" and "signal" in ports:
                port_name = "signal"
            else:
                raise ValueError(f"{handle}: choose a port: {', '.join(ports)}")
        if port_name not in ports:
            raise ValueError(f"{handle} has no port {port_name!r}; ports: {', '.join(ports)}")
        lx, ly, ldir, kind, radius = ports[port_name]
        ins = info.properties["insertion"]
        world = transform_port(
            Port(port_name, float(lx), float(ly), ldir, kind, float(radius)),
            float(ins[0]),
            float(ins[1]),
            float(info.properties.get("rotation_deg", 0.0)),
            float(info.properties.get("x_scale", 1.0)),
        )
        return {**world, "handle": handle, "port": port_name, "block_name": block_name}
    if "x" in ref and "y" in ref:
        return {
            "name": None,
            "x": float(ref["x"]),
            "y": float(ref["y"]),
            "direction_deg": None,
            "kind": None,
            "radius": 0.0,
            "inferred": False,
            "handle": None,
            "port": None,
            "block_name": None,
        }
    raise ValueError("endpoint must be {handle, port} or {x, y}")


def _vertices(info) -> list[tuple[float, float]]:
    if info.type == "LINE":
        s, e = info.properties["start"], info.properties["end"]
        return [(float(s[0]), float(s[1])), (float(e[0]), float(e[1]))]
    return [(float(p[0]), float(p[1])) for p in info.properties.get("points", [])]


async def existing_pid_lines(backend: AutoCADBackend) -> list[dict]:
    """Every LINE/LWPOLYLINE on a P&ID line layer, with its payload when it has one."""
    out = []
    for type_filter in ("LWPOLYLINE", "LINE"):
        offset = 0
        while True:
            page = await backend.entity_list(type_filter=type_filter, limit=1000, offset=offset)
            for info in page:
                if info.layer.upper() not in PID_LINE_LAYERS:
                    continue
                payload = (
                    await read_payload(backend, info.handle) if info.type == "LWPOLYLINE" else None
                )
                out.append({"handle": info.handle, "vertices": _vertices(info), "payload": payload})
            if len(page) < 1000:
                break
            offset += 1000
    return out


def _anchor(endpoint: dict, other: dict) -> tuple[tuple[float, float], float | None]:
    """Where the line actually starts/ends: on the circle for radial ports."""
    if endpoint["radius"] > 0:
        axis = snap_axis(other["x"] - endpoint["x"], other["y"] - endpoint["y"])
        ux, uy = AXIS[axis]
        return (
            endpoint["x"] + ux * endpoint["radius"],
            endpoint["y"] + uy * endpoint["radius"],
        ), axis
    return (endpoint["x"], endpoint["y"]), endpoint["direction_deg"]


def _ref(endpoint: dict) -> dict | None:
    return {"handle": endpoint["handle"], "port": endpoint["port"]} if endpoint["handle"] else None


async def draw_line(
    backend: AutoCADBackend,
    from_: dict,
    to: dict,
    line_class: str = "process_major",
    route_mode="auto",
    stub: float = 5.0,
    line_number: str | None = None,
    size: str | None = None,
    service: str | None = None,
    spec: str | None = None,
    insulation: str | None = None,
    number_format: str | None = None,
    label: bool = True,
    arrow: bool | None = None,
) -> dict:
    if line_class not in LINE_CLASSES:
        raise ValueError(f"line_class must be one of {', '.join(LINE_CLASSES)}, got {line_class!r}")
    cls = LINE_CLASSES[line_class]
    start = await resolve_endpoint(backend, from_)
    end = await resolve_endpoint(backend, to)
    if start["handle"] and start["handle"] == end["handle"] and start["port"] == end["port"]:
        raise ValueError("from and to are the same port")
    s_point, s_dir = _anchor(start, end)
    e_point, e_dir = _anchor(end, start)
    path = route(s_point, s_dir, e_point, e_dir, stub=stub, mode=route_mode)

    existing = await existing_pid_lines(backend)
    crossings = count_crossings(path, [ln["vertices"] for ln in existing])
    used: set[tuple[str, str]] = set()
    max_seq = 0
    for ln in existing:
        payload = ln["payload"] or {}
        for key in ("from", "to"):
            ref = payload.get(key)
            if ref:
                used.add((ref["handle"], ref["port"]))
        if isinstance(payload.get("seq"), int):
            max_seq = max(max_seq, payload["seq"])
    port_reuse = [
        {"handle": ep["handle"], "port": ep["port"]}
        for ep in (start, end)
        if ep["handle"] and (ep["handle"], ep["port"]) in used
    ]
    seq = max_seq + 1
    if line_number is None:
        fmt = number_format or DEFAULT_NUMBER_FORMAT
        fields = {
            "size": size,
            "service": service,
            "seq": seq,
            "spec": spec,
            "insulation": insulation,
        }
        line_number = format_line_number(fmt, **fields) or None

    await ensure_layer(backend, cls.layer)
    poly = await backend.entity_create_polyline(
        [list(p) for p in path], closed=False, layer=cls.layer
    )
    if cls.linetype:
        await backend.entity_set_properties(poly.handle, linetype=cls.linetype)
    await write_payload(
        backend,
        poly.handle,
        line_payload(
            line_class, line_number, size, service, spec, insulation, seq, _ref(start), _ref(end)
        ),
    )

    label_handle = None
    if label and line_number:
        await ensure_layer(backend, LABEL_LAYER)
        lx, ly, rot, _index = label_placement(path)
        import math

        shift = len(line_number) * TEXT_HEIGHT * 0.7 / 2.0
        lx -= math.cos(math.radians(rot)) * shift
        ly -= math.sin(math.radians(rot)) * shift
        text = await backend.entity_create_text(
            line_number, lx, ly, TEXT_HEIGHT, rot, layer=LABEL_LAYER
        )
        label_handle = text.handle

    want_arrow = cls.arrow if arrow is None else arrow
    arrow_handle = None
    if want_arrow:
        (ax0, ay0), (ax1, ay1) = path[-2], path[-1]
        angle = (
            snap_axis(ax1 - ax0, ay1 - ay0)
            if abs(ax1 - ax0) < 1e-9 or abs(ay1 - ay0) < 1e-9
            else math.degrees(math.atan2(ay1 - ay0, ax1 - ax0)) % 360.0
        )
        placed = await insert_symbol(
            backend,
            resolve("arrow_flow"),
            ax1,
            ay1,
            angle,
            1.0,
            None,
            cls.layer,
            marker_payload(poly.handle),
        )
        arrow_handle = placed["handle"]

    marker_handles: list[str] = []
    if cls.marker:
        for mx, my, angle in marker_positions(path):
            placed = await insert_symbol(
                backend,
                resolve(cls.marker),
                mx,
                my,
                angle,
                1.0,
                None,
                cls.layer,
                marker_payload(poly.handle),
            )
            marker_handles.append(placed["handle"])

    return {
        "handle": poly.handle,
        "vertices": [[x, y] for x, y in path],
        "line_class": line_class,
        "layer": cls.layer,
        "line_number": line_number,
        "from": {
            "handle": start["handle"],
            "port": start["port"],
            "x": s_point[0],
            "y": s_point[1],
        },
        "to": {"handle": end["handle"], "port": end["port"], "x": e_point[0], "y": e_point[1]},
        "port_reuse": port_reuse,
        "crossings": crossings,
        "label_handle": label_handle,
        "arrow_handle": arrow_handle,
        "marker_handles": marker_handles,
        "backend": backend.name,
    }
```

Move `import math` to the module's top-level imports (it is used in two places).

- [ ] **Step 4: Run the tests** — `uv run --frozen pytest tests/test_pid_line_draw.py -v` → all PASS. The geometry behind the first test: the pump's `discharge` at rotation 0 is `(100, 106)` leaving along +Y; the vessel's `N3` (left side, fraction 0.7 of height 40, 3 mm stub) is `(220 - 10 - 3, 120 - 20 + 28) = (207, 128)` entered travelling +X; the one-bend route `[(100,106), (100,128), (207,128)]` satisfies both directions and the stub, so it is chosen.

- [ ] **Step 5: Register the tool**

`server.py` SECTION 17 header → `(3 tools)`; add after `pid_symbol_insert`:

```python
@cad_tool(
    summary="Draw a P&ID line port-to-port: orthogonal route, ISA-5.1 class, line number, markers, arrow.",
    cost="mutate",
)
@mcp.tool(
    annotations={"title": "P&ID: Draw Line", "readOnlyHint": False},
    tags={"pid", "create"},
)
async def pid_line_draw(
    from_: Annotated[dict, "{handle, port} of a placed symbol, or {x, y}"],
    to: Annotated[dict, "{handle, port} of a placed symbol, or {x, y}"],
    line_class: Annotated[
        str,
        "process_major | process_minor | utility | pneumatic | electric | hydraulic | capillary | data",
    ] = "process_major",
    route: Annotated[str | list, "auto (orthogonal) | direct | [[x, y], ...] waypoints"] = "auto",
    stub: Annotated[
        float, Field(default=5.0, ge=0, description="Minimum straight run leaving each port (mm)")
    ] = 5.0,
    line_number: Annotated[
        str | None, "Verbatim line number; omit to build one from the fields"
    ] = None,
    size: Annotated[str | None, "Nominal size, e.g. 100"] = None,
    service: Annotated[str | None, "Service code, e.g. P"] = None,
    spec: Annotated[str | None, "Piping spec, e.g. CS1"] = None,
    insulation: Annotated[str | None, "Insulation code, e.g. IH"] = None,
    number_format: Annotated[
        str | None, "Default {size}-{service}-{seq}-{spec}-{insulation}; empty fields drop out"
    ] = None,
    label: Annotated[bool, "Write the line number along the longest segment"] = True,
    arrow: Annotated[
        bool | None, "Flow arrow at the end; default per class (process yes, signal no)"
    ] = None,
    ctx: Context = None,
) -> dict:
    """Connect two ports with one LWPOLYLINE on the class's layer.

    Ports come from `pid_symbol_insert`; a bubble's radial port is entered
    without a name. `auto` picks the shortest orthogonal route that leaves each
    port straight for `stub` mm; when none exists the call refuses and says so
    — pass waypoints. `crossings` counts existing P&ID lines the new one cuts
    (reported, never refused) and `port_reuse` names ports that already had a
    line (branching is legal). Signal classes get ISA-5.1 markers (`//`, `X`,
    `L`, `o`) as small blocks on segments ≥ 15 mm; electric is dashed by layer.
    """
    from engineering.pid.drawlines import draw_line

    await ctx.info(f"P&ID line {line_class}")
    return await draw_line(
        _backend(ctx),
        from_,
        to,
        line_class,
        route,
        stub,
        line_number,
        size,
        service,
        spec,
        insulation,
        number_format,
        label,
        arrow,
    )
```

Alias record:

```python
    "pid_line_draw": ToolAliases(
        acad=("PLINE",),
        synonyms=("process line", "pipe run", "signal line", "connect equipment", "instrument line",
                  "line number", "connect the pump to the vessel", "pneumatic signal"),
    ),
```

Regenerate inventory; README `160 tools`.

- [ ] **Step 6: Gates and commit**

Run: `uv run --frozen pytest tests/test_pid_line_draw.py tests/test_discovery_aliases.py tests/test_tool_inventory.py tests/test_release_consistency.py -v`

```bash
git add engineering/pid/drawlines.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_pid_line_draw.py
git commit -m "feat(pid): pid_line_draw — port-to-port orthogonal lines with class, number, markers"
```

---

### Task 14: The reader — `engineering/pid/graph.py` + `pid_graph`

**Files:**
- Create: `engineering/pid/graph.py`
- Modify: `server.py` (SECTION 17 → `(4 tools)`), `discovery/aliases.py`, `README.md` (`161 tools`), inventory
- Test: `tests/test_pid_graph.py`

**Interfaces:**
- Consumes: `read_payload`, `Port`, `transform_port`, `LAYER_TO_CLASS`, `PID_LINE_LAYERS`, `parse_tag`, backend `entity_list`, `entity_get_xdata`, `block_get_attributes`, `layer_list`, `layout_list`, `layout_set_current`.
- Produces: `async build_graph(backend, tolerance=0.5, label_search=15.0, scope="current_space", include_foreign=True, include_geometry=False) -> dict` with keys `nodes, edges, junctions, dangling, unclassified, offpage_links, stats, tolerance, scope, backend` (shapes in spec §9.1). Node `ports[name]` carries `edges: [edge handles]`. Edge `from`/`to` are `{"node": handle, "port": name}`, `{"junction": id}` or `None`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_graph.py
"""pid_graph reads the drawing back: our symbols exactly, foreign ones with confidence."""

from __future__ import annotations

import pytest

from engineering.pid.drawlines import draw_line
from engineering.pid.graph import build_graph
from engineering.pid.insert import place_symbol

pytestmark = pytest.mark.asyncio


async def _small_pid(backend):
    pump = await place_symbol(backend, "centrifugal_pump", 100, 100, tag="P-101", desc="Feed pump")
    hv = await place_symbol(backend, "gate", 160, 104, tag="HV-101", actuator="hand")
    vessel = await place_symbol(backend, "vertical_vessel", 220, 120, tag="V-201")
    fic = await place_symbol(
        backend, "instrument", 160, 160, tag="FIC-101", type="dcs", location="primary"
    )
    l1 = await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": hv["handle"], "port": "in"},
        size="100",
        service="P",
        spec="CS1",
    )
    l2 = await draw_line(
        backend,
        {"handle": hv["handle"], "port": "out"},
        {"handle": vessel["handle"], "port": "N3"},
        line_number=l1["line_number"],
    )
    sig = await draw_line(
        backend, {"handle": fic["handle"]}, {"x": 160, "y": 112}, line_class="electric"
    )
    return {"pump": pump, "hv": hv, "vessel": vessel, "fic": fic, "l1": l1, "l2": l2, "sig": sig}


async def test_tool_drawn_pid_is_read_back_exactly(backend):
    ids = await _small_pid(backend)
    graph = await build_graph(backend)
    nodes = {n["id"]: n for n in graph["nodes"]}
    assert set(nodes) == {
        ids["pump"]["handle"],
        ids["hv"]["handle"],
        ids["vessel"]["handle"],
        ids["fic"]["handle"],
    }
    assert (
        nodes[ids["pump"]["handle"]]["kind"] == "equipment"
        and nodes[ids["pump"]["handle"]]["tag"] == "P-101"
    )
    assert nodes[ids["pump"]["handle"]]["description"] == "Feed pump"
    assert (
        nodes[ids["fic"]["handle"]]["kind"] == "instrument"
        and nodes[ids["fic"]["handle"]]["tag"] == "FIC-101"
    )
    assert nodes[ids["fic"]["handle"]]["tag_parsed"]["description"] == "Flow Indicating Controller"
    assert all(n["source"] == "catalog" and n["confidence"] == 1.0 for n in graph["nodes"])
    edges = {e["id"]: e for e in graph["edges"]}
    assert set(edges) == {ids["l1"]["handle"], ids["l2"]["handle"], ids["sig"]["handle"]}
    l1 = edges[ids["l1"]["handle"]]
    assert l1["from"] == {"node": ids["pump"]["handle"], "port": "discharge"}
    assert l1["to"] == {"node": ids["hv"]["handle"], "port": "in"}
    assert (
        l1["line_number"] == "100-P-1-CS1"
        and l1["number_source"] == "xdata"
        and l1["class_source"] == "xdata"
    )
    assert nodes[ids["hv"]["handle"]]["ports"]["in"]["edges"] == [ids["l1"]["handle"]]
    sig = edges[ids["sig"]["handle"]]
    assert (
        sig["from"] == {"node": ids["fic"]["handle"], "port": "signal"}
        and sig["line_class"] == "electric"
    )
    assert len(graph["dangling"]) == 1 and graph["dangling"][0]["edge"] == ids["sig"]["handle"]
    assert graph["stats"]["nodes_by_kind"] == {"equipment": 2, "instrument": 1, "valve": 1}
    assert graph["stats"]["confidence_min"] == 1.0 and graph["stats"]["dangling"] == 1
    assert graph["junctions"] == [] and graph["unclassified"] == []


async def test_a_nudged_symbol_makes_its_line_dangle_with_a_hint(backend):
    ids = await _small_pid(backend)
    await backend.entity_move(ids["hv"]["handle"], 0.0, 1.0)
    graph = await build_graph(backend, tolerance=0.5)
    dangling = {d["edge"]: d for d in graph["dangling"]}
    assert ids["l1"]["handle"] in dangling and ids["l2"]["handle"] in dangling
    hint = dangling[ids["l1"]["handle"]]["nearest"]
    assert (
        hint["node"] == ids["hv"]["handle"]
        and hint["port"] == "in"
        and hint["distance"] == pytest.approx(1.0)
    )
    assert await _no_dangling_after(backend, tolerance=1.5)


async def _no_dangling_after(backend, tolerance):
    graph = await build_graph(backend, tolerance=tolerance)
    return graph["stats"]["dangling"] == 1  # only the deliberately open signal line


async def test_branch_onto_a_line_becomes_a_junction(backend):
    ids = await _small_pid(backend)
    # l1 runs (100,106)->(100,111)->(151,111)->(151,104)->(156,104); (130,111) is on its second segment
    branch = await draw_line(
        backend, {"x": 130, "y": 111}, {"x": 130, "y": 60}, line_class="process_minor"
    )
    graph = await build_graph(backend)
    edge = next(e for e in graph["edges"] if e["id"] == branch["handle"])
    assert edge["from"] and "junction" in edge["from"]
    junction = next(j for j in graph["junctions"] if j["id"] == edge["from"]["junction"])
    assert (junction["x"], junction["y"]) == pytest.approx((130.0, 111.0))
    assert set(junction["edges"]) == {branch["handle"], ids["l1"]["handle"]}


async def test_rotated_and_scaled_symbols_are_measured_not_assumed(backend):
    pump = await place_symbol(
        backend, "centrifugal_pump", 0, 0, rotation=90.0, scale=2.0, tag="P-1"
    )
    graph = await build_graph(backend)
    node = graph["nodes"][0]
    assert node["ports"]["discharge"]["x"] == pytest.approx(-12.0)
    assert node["ports"]["discharge"]["direction_deg"] == pytest.approx(180.0)
    assert node["rotation_deg"] == pytest.approx(90.0) and node["scale"] == pytest.approx(2.0)


async def test_foreign_blocks_classify_with_reduced_confidence_and_inferred_ports(backend):
    blk = backend._doc.blocks.new(name="GATE_VALVE")
    blk.add_lwpolyline([(-4, -2), (-4, 2), (0, 0)], close=True)
    blk.add_lwpolyline([(4, -2), (4, 2), (0, 0)], close=True)
    blk.add_attdef("TAG", insert=(0, 4), text="", dxfattribs={"height": 2.5})
    logo = backend._doc.blocks.new(name="COMPANY_LOGO")
    logo.add_circle((0, 0), 5)
    await backend.block_insert("GATE_VALVE", 50, 50, attributes={"TAG": "HV-9"})
    await backend.block_insert("COMPANY_LOGO", 300, 300)
    await backend.entity_create_line(10, 50, 46, 50, layer="PROCESS-PIPING-MAIN")
    graph = await build_graph(backend)
    assert len(graph["nodes"]) == 1
    node = graph["nodes"][0]
    assert node["kind"] == "valve" and node["source"] == "heuristic" and node["confidence"] == 0.6
    assert node["tag"] == "HV-9" and node["tag_source"] == "attribute"
    port = next(iter(node["ports"].values()))
    assert port["inferred"] is True and (port["x"], port["y"]) == pytest.approx((46.0, 50.0))
    assert graph["stats"]["confidence_min"] == 0.6
    edge = graph["edges"][0]
    assert edge["line_class"] == "process_major" and edge["class_source"] == "layer"
    assert graph["stats"]["entities_scanned"] >= 3


async def test_include_foreign_false_ignores_untagged_blocks(backend):
    blk = backend._doc.blocks.new(name="GATE_VALVE")
    blk.add_line((0, 0), (1, 0))
    await backend.block_insert("GATE_VALVE", 50, 50)
    graph = await build_graph(backend, include_foreign=False)
    assert graph["nodes"] == [] and graph["edges"] == []


async def test_line_number_and_tags_from_nearby_text(backend):
    await backend.entity_create_line(0, 0, 100, 0, layer="PROCESS-PIPING-MAIN")
    await backend.entity_create_text('6"-P-1234-CS1', 40, 2, 2.5, layer="PROCESS-LINE-TEXT")
    graph = await build_graph(backend)
    edge = graph["edges"][0]
    assert edge["line_number"] == '6"-P-1234-CS1' and edge["number_source"] == "label"


async def test_scope_all_walks_every_layout_and_restores_the_current_one(backend):
    await place_symbol(backend, "gate", 0, 0, tag="HV-1")
    await backend.layout_create("SHEET-2")
    await backend.layout_set_current("SHEET-2")
    await place_symbol(backend, "gate", 0, 0, tag="HV-2")
    await backend.layout_set_current("Model")
    graph = await build_graph(backend, scope="all")
    assert sorted(n["tag"] for n in graph["nodes"]) == ["HV-1", "HV-2"]
    assert sorted(n["space"] for n in graph["nodes"]) == ["Model", "SHEET-2"]
    assert (await backend.layout_list())["current"] == "Model"


async def test_offpage_links_pair_by_link_id(backend):
    out = await place_symbol(backend, "offpage", 0, 0, tag="TO 002", link="L-17", direction="out")
    inn = await place_symbol(
        backend, "offpage", 100, 0, tag="FROM 001", link="L-17", direction="in"
    )
    graph = await build_graph(backend)
    assert graph["offpage_links"] == [
        {"link": "L-17", "nodes": sorted([out["handle"], inn["handle"]])}
    ]


async def test_geometry_is_optional(backend):
    await _small_pid(backend)
    lean = await build_graph(backend)
    assert "vertices" not in lean["edges"][0]
    full = await build_graph(backend, include_geometry=True)
    assert len(full["edges"][0]["vertices"]) >= 2
```

- [ ] **Step 2: Run to verify they fail** — ModuleNotFoundError.

- [ ] **Step 3: Write the graph builder**

```python
# engineering/pid/graph.py
"""Read a P&ID back as a graph: nodes (symbols), edges (lines), junctions, dangling ends.

Rules the reader keeps (spec §9.4): it never modifies the drawing, it reads
geometry from the drawing rather than the catalogue, and confidence is the
minimum of its inputs — never raised by agreement between heuristics.
"""

from __future__ import annotations

import math
import re
from dataclasses import dataclass, field
from typing import TYPE_CHECKING

from .lines import LAYER_TO_CLASS, PID_LINE_LAYERS
from .symbols import Port, transform_port
from .tags import parse_tag
from .xdata import read_payload

if TYPE_CHECKING:
    from backends.base import AutoCADBackend, EntityInfo

INSERT_TYPES = {"INSERT", "BLOCKREFERENCE"}
POLY_TYPES = {"LWPOLYLINE", "POLYLINE", "2DPOLYLINE"}
LINE_TYPES = {"LINE"}
TEXT_TYPES = {"TEXT", "MTEXT"}
ATTRIBUTE_TAGS = ("TAG", "TAGNO", "TAGNUMBER", "EQUIP_TAG", "EQUIPMENT_TAG", "INST_TAG", "INSTTAG")
KEYWORDS = {
    "VALVE": "valve",
    "VLV": "valve",
    "PUMP": "equipment",
    "TANK": "equipment",
    "VESSEL": "equipment",
    "DRUM": "equipment",
    "INST": "instrument",
    "BUBBLE": "instrument",
    "HX": "equipment",
    "EXCH": "equipment",
    "FILTER": "equipment",
    "COMP": "equipment",
}
FAMILY_KIND = {"instrument": "instrument", "valve": "valve", "connector": "connector"}
LINE_NUMBER_RE = re.compile(r'^\d+(?:"|MM)?-[A-Z]{1,4}-\d+', re.IGNORECASE)
CONFIDENCE = {"catalog": 1.0, "xdata": 0.95, "heuristic": 0.6, "inferred": 0.3}


@dataclass
class _Node:
    id: str
    kind: str
    block_name: str
    family: str | None
    symbol: str | None
    x: float
    y: float
    rotation_deg: float
    scale: float
    layer: str
    space: str
    bbox: tuple[float, float, float, float] | None
    source: str
    confidence: float
    attributes: dict
    ports: dict = field(default_factory=dict)
    tag: str | None = None
    tag_source: str | None = None

    def to_dict(self) -> dict:
        parsed = None
        if self.tag:
            parsed = parse_tag(self.tag, kind="instrument" if self.kind == "instrument" else "auto")
        return {
            "id": self.id,
            "kind": self.kind,
            "block_name": self.block_name,
            "family": self.family,
            "symbol": self.symbol,
            "tag": self.tag,
            "tag_parsed": parsed,
            "tag_source": self.tag_source,
            "x": self.x,
            "y": self.y,
            "rotation_deg": self.rotation_deg,
            "scale": self.scale,
            "layer": self.layer,
            "space": self.space,
            "ports": self.ports,
            "description": self.attributes.get("DESC") or None,
            "source": self.source,
            "confidence": self.confidence,
        }


@dataclass
class _Edge:
    id: str
    vertices: list[tuple[float, float]]
    layer: str
    linetype: str
    space: str
    payload: dict | None
    source: str
    line_class: str | None = None
    class_source: str | None = None
    line_number: str | None = None
    number_source: str | None = None
    from_ref: dict | None = None
    to_ref: dict | None = None

    def to_dict(self, include_geometry: bool) -> dict:
        p = self.payload or {}
        out = {
            "id": self.id,
            "line_class": self.line_class,
            "class_source": self.class_source,
            "line_number": self.line_number,
            "number_source": self.number_source,
            "size": p.get("size"),
            "service": p.get("service"),
            "spec": p.get("spec"),
            "insulation": p.get("insulation"),
            "from": self.from_ref,
            "to": self.to_ref,
            "length": round(
                sum(math.dist(a, b) for a, b in zip(self.vertices, self.vertices[1:])), 6
            ),
            "layer": self.layer,
            "space": self.space,
            "source": self.source,
        }
        if include_geometry:
            out["vertices"] = [[x, y] for x, y in self.vertices]
        return out


class _Grid:
    """Uniform grid for nearest-within-tolerance queries."""

    def __init__(self, cell: float):
        self.cell = cell
        self.cells: dict[tuple[int, int], list] = {}

    def _key(self, x: float, y: float) -> tuple[int, int]:
        return (int(math.floor(x / self.cell)), int(math.floor(y / self.cell)))

    def add(self, x: float, y: float, item) -> None:
        self.cells.setdefault(self._key(x, y), []).append((x, y, item))

    def near(self, x: float, y: float, radius: float):
        kx, ky = self._key(x, y)
        reach = int(math.ceil(radius / self.cell))
        for dx in range(-reach, reach + 1):
            for dy in range(-reach, reach + 1):
                for px, py, item in self.cells.get((kx + dx, ky + dy), []):
                    d = math.hypot(px - x, py - y)
                    if d <= radius:
                        yield d, item


def _vertices(info: EntityInfo) -> list[tuple[float, float]]:
    if info.type in LINE_TYPES:
        s, e = info.properties["start"], info.properties["end"]
        return [(float(s[0]), float(s[1])), (float(e[0]), float(e[1]))]
    return [(float(p[0]), float(p[1])) for p in info.properties.get("points", [])]


def _point_segment_distance(p, a, b) -> float:
    ax, ay = a
    bx, by = b
    px, py = p
    dx, dy = bx - ax, by - ay
    if dx == 0 and dy == 0:
        return math.hypot(px - ax, py - ay)
    t = max(0.0, min(1.0, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)))
    return math.hypot(px - (ax + t * dx), py - (ay + t * dy))


def _bbox(info: EntityInfo):
    bb = info.properties.get("bounding_box")
    if not bb:
        return None
    return (float(bb["min"][0]), float(bb["min"][1]), float(bb["max"][0]), float(bb["max"][1]))


def _on_bbox_boundary(p, bbox, tolerance) -> bool:
    x, y = p
    xmin, ymin, xmax, ymax = bbox
    inside_x = xmin - tolerance <= x <= xmax + tolerance
    inside_y = ymin - tolerance <= y <= ymax + tolerance
    near_vertical = min(abs(x - xmin), abs(x - xmax)) <= tolerance and inside_y
    near_horizontal = min(abs(y - ymin), abs(y - ymax)) <= tolerance and inside_x
    return near_vertical or near_horizontal


async def _collect(backend: AutoCADBackend, scope: str) -> list[tuple[EntityInfo, str]]:
    async def page_all(space: str):
        out = []
        offset = 0
        while True:
            page = await backend.entity_list(limit=1000, offset=offset)
            out.extend((info, space) for info in page)
            if len(page) < 1000:
                return out
            offset += 1000

    layouts = await backend.layout_list()
    current = layouts.get("current") or "Model"
    if scope != "all":
        return await page_all(current)
    entities = []
    try:
        for name in layouts.get("layouts", [current]):
            await backend.layout_set_current(name)
            entities.extend(await page_all(name))
    finally:
        await backend.layout_set_current(current)
    return entities


async def build_graph(
    backend: AutoCADBackend,
    tolerance: float = 0.5,
    label_search: float = 15.0,
    scope: str = "current_space",
    include_foreign: bool = True,
    include_geometry: bool = False,
) -> dict:
    if tolerance <= 0:
        raise ValueError("tolerance must be > 0")
    if scope not in ("current_space", "all"):
        raise ValueError("scope must be 'current_space' or 'all'")
    entities = await _collect(backend, scope)
    layer_linetypes = {lyr.name.upper(): lyr.linetype.upper() for lyr in await backend.layer_list()}

    # 1 — classify INSERTs
    nodes: dict[str, _Node] = {}
    candidates: dict[str, _Node] = {}  # unknown blocks kept only if a line touches them
    for info, space in entities:
        if info.type not in INSERT_TYPES:
            continue
        name = str(info.properties.get("block_name", ""))
        if name.startswith("PID_MARKER_"):
            continue
        payload = await read_payload(backend, info.handle)
        try:
            attributes = await backend.block_get_attributes(info.handle)
        except Exception:
            attributes = {}
        ins = info.properties.get("insertion", [0.0, 0.0])
        rotation = float(info.properties.get("rotation_deg", 0.0))
        scale = float(info.properties.get("x_scale", 1.0))
        base = dict(
            id=info.handle,
            block_name=name,
            x=float(ins[0]),
            y=float(ins[1]),
            rotation_deg=rotation,
            scale=scale,
            layer=info.layer,
            space=space,
            bbox=_bbox(info),
            attributes=attributes,
        )
        if payload and payload.get("kind") == "symbol":
            source = "catalog" if name.startswith("PID_") else "xdata"
            family = payload.get("family")
            node = _Node(
                kind=FAMILY_KIND.get(family, "equipment"),
                family=family,
                symbol=payload.get("symbol"),
                source=source,
                confidence=CONFIDENCE[source],
                **base,
            )
            for pname, (lx, ly, ldir, kind, radius) in payload.get("ports", {}).items():
                port = transform_port(
                    Port(pname, float(lx), float(ly), ldir, kind, float(radius)),
                    node.x,
                    node.y,
                    rotation,
                    scale,
                )
                node.ports[pname] = {**port, "edges": []}
            nodes[node.id] = node
            continue
        if not include_foreign:
            continue
        upper = name.upper()
        keyword_kind = next((k for word, k in KEYWORDS.items() if word in upper), None)
        tag_key = next((k for k in ATTRIBUTE_TAGS if k in attributes), None)
        if keyword_kind or tag_key:
            node = _Node(
                kind=keyword_kind or "equipment",
                family=None,
                symbol=None,
                source="heuristic",
                confidence=CONFIDENCE["heuristic"],
                **base,
            )
            nodes[node.id] = node
        elif base["bbox"] is not None:
            candidates[info.handle] = _Node(
                kind="unknown_block",
                family=None,
                symbol=None,
                source="inferred",
                confidence=CONFIDENCE["inferred"],
                **base,
            )

    # 2 — candidate edges
    edges: dict[str, _Edge] = {}
    foreign_edges: dict[str, _Edge] = {}
    for info, space in entities:
        if info.type not in POLY_TYPES | LINE_TYPES:
            continue
        verts = _vertices(info)
        if len(verts) < 2:
            continue
        payload = await read_payload(backend, info.handle) if info.type in POLY_TYPES else None
        layer = info.layer.upper()
        edge = _Edge(
            id=info.handle,
            vertices=verts,
            layer=info.layer,
            linetype=info.linetype,
            space=space,
            payload=payload if payload and payload.get("kind") == "line" else None,
            source="touch",
        )
        if edge.payload:
            edge.source = "xdata"
            edge.line_class, edge.class_source = edge.payload.get("class"), "xdata"
            edge.line_number = edge.payload.get("number")
            edge.number_source = "xdata" if edge.line_number else None
            edges[edge.id] = edge
        elif layer in PID_LINE_LAYERS:
            edge.source = "layer"
            cls = LAYER_TO_CLASS[layer]
            if cls is None:
                effective = (
                    info.linetype.upper()
                    if info.linetype.upper() != "BYLAYER"
                    else layer_linetypes.get(layer, "")
                )
                cls = "electric" if "DASH" in effective else "signal_unknown"
            edge.line_class, edge.class_source = cls, "layer"
            edges[edge.id] = edge
        elif include_foreign:
            foreign_edges[edge.id] = edge

    # 3 — spatial index of ports and vertices
    grid = _Grid(cell=10.0 * tolerance)
    radial_ports: list[tuple[str, str, float, float, float]] = []
    for node in nodes.values():
        for pname, port in node.ports.items():
            if port.get("radius", 0.0) > 0:
                # a bubble's line starts on its circle, not at its centre
                radial_ports.append((node.id, pname, port["x"], port["y"], port["radius"]))
            else:
                grid.add(port["x"], port["y"], ("port", node.id, pname))
    all_edges = {**edges, **foreign_edges}
    for edge in all_edges.values():
        for v in edge.vertices:
            grid.add(v[0], v[1], ("vertex", edge.id))

    # 4 — resolve endpoints
    junctions: list[dict] = []
    dangling: list[dict] = []

    def _junction_at(x, y, edge_id, other_id) -> dict:
        for j in junctions:
            if math.hypot(j["x"] - x, j["y"] - y) <= tolerance:
                for e in (edge_id, other_id):
                    if e not in j["edges"]:
                        j["edges"].append(e)
                return {"junction": j["id"]}
        j = {"id": f"J{len(junctions) + 1}", "x": x, "y": y, "edges": [edge_id, other_id]}
        junctions.append(j)
        return {"junction": j["id"]}

    def _resolve(edge: _Edge, end: str) -> dict | None:
        x, y = edge.vertices[0] if end == "from" else edge.vertices[-1]
        for node_id, pname, cx, cy, r in radial_ports:
            if abs(math.hypot(x - cx, y - cy) - r) <= tolerance:
                nodes[node_id].ports[pname]["edges"].append(edge.id)
                return {"node": node_id, "port": pname}
        best = None
        for d, item in grid.near(x, y, tolerance):
            if item[0] == "port" and (best is None or d < best[0]):
                best = (d, item)
        if best:
            _, (_kind, node_id, pname) = best
            nodes[node_id].ports[pname]["edges"].append(edge.id)
            return {"node": node_id, "port": pname}
        for node in list(nodes.values()) + list(candidates.values()):
            if (
                node.source in ("heuristic", "inferred")
                and node.bbox
                and _on_bbox_boundary((x, y), node.bbox, tolerance)
            ):
                if node.id in candidates:
                    nodes[node.id] = candidates.pop(node.id)
                pname = f"p{len(node.ports) + 1}"
                node.ports[pname] = {
                    "name": pname,
                    "x": x,
                    "y": y,
                    "direction_deg": None,
                    "kind": "process",
                    "radius": 0.0,
                    "inferred": True,
                    "edges": [edge.id],
                }
                grid.add(x, y, ("port", node.id, pname))
                return {"node": node.id, "port": pname}
        for d, item in grid.near(x, y, tolerance):
            if item[0] == "vertex" and item[1] != edge.id:
                return _junction_at(x, y, edge.id, item[1])
        for other in all_edges.values():
            if other.id == edge.id:
                continue
            for a, b in zip(other.vertices, other.vertices[1:]):
                if _point_segment_distance((x, y), a, b) <= tolerance:
                    return _junction_at(x, y, edge.id, other.id)
        nearest = None
        for d, item in grid.near(x, y, 10.0 * tolerance):
            if item[0] == "port" and (nearest is None or d < nearest[0]):
                nearest = (d, item)
        dangling.append(
            {
                "edge": edge.id,
                "end": end,
                "x": x,
                "y": y,
                "nearest": (
                    {"node": nearest[1][1], "port": nearest[1][2], "distance": round(nearest[0], 6)}
                    if nearest
                    else None
                ),
            }
        )
        return None

    for edge in list(edges.values()):
        edge.from_ref = _resolve(edge, "from")
        edge.to_ref = _resolve(edge, "to")
    for edge in list(foreign_edges.values()):
        # a foreign line joins the graph only through a node
        probe_from = _resolve(edge, "from")
        probe_to = _resolve(edge, "to")
        attached = any(ref and "node" in ref for ref in (probe_from, probe_to))
        if attached:
            edge.from_ref, edge.to_ref = probe_from, probe_to
            edges[edge.id] = edge
        else:
            dangling[:] = [d for d in dangling if d["edge"] != edge.id]
            for j in junctions:
                if edge.id in j["edges"]:
                    j["edges"].remove(edge.id)
    junctions[:] = [j for j in junctions if len(j["edges"]) >= 2]

    # 5 — tags and line numbers from attributes or nearby text
    texts = [(info, space) for info, space in entities if info.type in TEXT_TYPES]

    def _text_near(x, y, radius, pattern=None):
        best = None
        for info, _space in texts:
            ins = info.properties.get("insertion")
            content = str(info.properties.get("text", "")).strip()
            if not ins or not content or (pattern and not pattern.match(content)):
                continue
            d = math.hypot(float(ins[0]) - x, float(ins[1]) - y)
            if d <= radius and (best is None or d < best[0]):
                best = (d, content)
        return best[1] if best else None

    for node in nodes.values():
        attrs = node.attributes
        if node.kind == "instrument" and attrs.get("FUNC"):
            node.tag, node.tag_source = f"{attrs['FUNC']}-{attrs['LOOP']}".rstrip("-"), "attribute"
        else:
            key = next((k for k in ATTRIBUTE_TAGS if attrs.get(k)), None)
            if key:
                node.tag, node.tag_source = str(attrs[key]).strip(), "attribute"
        if node.tag is None:
            radius = max((p.get("radius", 0.0) for p in node.ports.values()), default=0.0)
            if node.kind == "instrument" and radius:
                found = _text_near(node.x, node.y, radius)
            else:
                cx = ((node.bbox[0] + node.bbox[2]) / 2.0) if node.bbox else node.x
                top = node.bbox[3] if node.bbox else node.y
                found = _text_near(cx, top, label_search)
            if found:
                node.tag, node.tag_source = found, "text"
    for edge in edges.values():
        if edge.line_number:
            continue
        a, b = max(zip(edge.vertices, edge.vertices[1:]), key=lambda s: math.dist(*s))
        found = _text_near((a[0] + b[0]) / 2.0, (a[1] + b[1]) / 2.0, label_search, LINE_NUMBER_RE)
        if found:
            edge.line_number, edge.number_source = found, "label"

    # 6 — off-page links
    links: dict[str, list[str]] = {}
    for node in nodes.values():
        link = node.attributes.get("LINK")
        if node.kind == "connector" and link:
            links.setdefault(str(link), []).append(node.id)
    offpage_links = [{"link": k, "nodes": sorted(v)} for k, v in sorted(links.items())]

    # 7 — assemble
    node_rows = [n.to_dict() for n in nodes.values()]
    edge_rows = [e.to_dict(include_geometry) for e in edges.values()]
    by_kind: dict[str, int] = {}
    for n in node_rows:
        by_kind[n["kind"]] = by_kind.get(n["kind"], 0) + 1
    by_class: dict[str, int] = {}
    for e in edge_rows:
        key = e["line_class"] or "unknown"
        by_class[key] = by_class.get(key, 0) + 1
    return {
        "nodes": node_rows,
        "edges": edge_rows,
        "junctions": junctions,
        "dangling": dangling,
        "unclassified": [{"handle": c.id, "block_name": c.block_name} for c in candidates.values()],
        "offpage_links": offpage_links,
        "stats": {
            "nodes_by_kind": dict(sorted(by_kind.items())),
            "edges_by_class": dict(sorted(by_class.items())),
            "dangling": len(dangling),
            "unclassified": len(candidates),
            "confidence_min": min((n["confidence"] for n in node_rows), default=1.0),
            "entities_scanned": len(entities),
        },
        "tolerance": tolerance,
        "scope": scope,
        "backend": backend.name,
    }
```

- [ ] **Step 4: Run the tests** — `uv run --frozen pytest tests/test_pid_graph.py -v` → PASS. Note for the foreign test: the INSERT of `GATE_VALVE` at (50, 50) has a bounding box of x ∈ [46, 54]; the line ends at (46, 50), on its left edge, so `_on_bbox_boundary` accepts it and creates `p1`.

- [ ] **Step 5: Register `pid_graph`**

SECTION 17 header → `(4 tools)`; add:

```python
@cad_tool(
    summary="Read the P&ID back as a graph: symbols, lines, junctions, dangling ends, confidence.",
    cost="read",
)
@mcp.tool(
    annotations={"title": "P&ID: Connectivity Graph", "readOnlyHint": True},
    tags={"pid", "query"},
)
async def pid_graph(
    tolerance: Annotated[
        float, Field(default=0.5, gt=0, description="Endpoint-to-port snap distance (mm)")
    ] = 0.5,
    label_search: Annotated[
        float,
        Field(default=15.0, gt=0, description="How far to look for tag/line-number text (mm)"),
    ] = 15.0,
    scope: Annotated[
        str, "current_space | all (every layout, current restored afterwards)"
    ] = "current_space",
    include_foreign: Annotated[
        bool, "Classify blocks not placed by this server (confidence < 1)"
    ] = True,
    include_geometry: Annotated[bool, "Include edge vertices"] = False,
    ctx: Context = None,
) -> dict:
    """Connectivity of the drawing as it *is*, not as it was drawn.

    Nodes are block references classified by catalogue name (confidence 1.0),
    ACADMCP_PID payload (0.95), tag attributes / block-name keywords (0.6) or
    a line touching an unknown block (0.3); every node says which. Ports are
    measured from the INSERT's real rotation and scale. Edges are lines and
    polylines; each end resolves to a port, a junction on another line, or
    `dangling` with the nearest port as a hint. `stats.confidence_min` is the
    number to read before trusting a foreign drawing.
    """
    from engineering.pid.graph import build_graph

    return await build_graph(
        _backend(ctx), tolerance, label_search, scope, include_foreign, include_geometry
    )
```

Alias:

```python
    "pid_graph": ToolAliases(
        acad=(),
        synonyms=("p&id connectivity", "what is connected to", "trace the line", "read the p&id",
                  "dangling lines", "instrument loop graph", "process graph"),
    ),
```

Inventory; README `161 tools`.

- [ ] **Step 6: Gates and commit**

```bash
git add engineering/pid/graph.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_pid_graph.py
git commit -m "feat(pid): pid_graph reads the drawing back with ports, junctions, dangling ends and confidence"
```

---

### Task 15: Deliverables — instrument index, line list, equipment list

**Files:**
- Create: `engineering/pid/deliverables.py`
- Modify: `server.py` (SECTION 17 → `(7 tools)`), `discovery/aliases.py`, `README.md` (`164 tools`), inventory
- Test: `tests/test_pid_deliverables.py`

**Interfaces:**
- Consumes: `build_graph` (Task 14), `validate_path` (`security.py`).
- Produces: `instrument_index(graph) -> list[dict]`, `line_list(graph) -> list[dict]`, `equipment_list(graph) -> list[dict]`, `natural_key(tag)`, `write_csv(rows, path) -> str`, `async deliverable(backend, which, csv_path=None, **graph_kwargs) -> dict` (`rows, count, csv_path, graph_stats`). Row keys exactly as spec §9.5.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_deliverables.py
"""Instrument index, line list and equipment list are derived from the graph."""

from __future__ import annotations

import csv

import pytest

from engineering.pid.deliverables import (
    deliverable,
    equipment_list,
    instrument_index,
    line_list,
    natural_key,
)
from engineering.pid.drawlines import draw_line
from engineering.pid.graph import build_graph
from engineering.pid.insert import place_symbol

pytestmark = pytest.mark.asyncio

INDEX_KEYS = [
    "tag",
    "func",
    "loop",
    "description",
    "type",
    "location",
    "connected_to",
    "signal_lines",
    "handle",
    "confidence",
]
LINE_KEYS = [
    "line_number",
    "line_class",
    "size",
    "service",
    "spec",
    "insulation",
    "from_tag",
    "from_port",
    "to_tag",
    "to_port",
    "length_mm",
    "handle",
    "number_source",
]
EQUIP_KEYS = [
    "tag",
    "kind",
    "symbol",
    "description",
    "ports",
    "connected_lines",
    "unconnected_ports",
    "handle",
    "confidence",
]


async def _pid(backend):
    pump = await place_symbol(backend, "centrifugal_pump", 100, 100, tag="P-101", desc="Feed pump")
    vessel = await place_symbol(backend, "vertical_vessel", 220, 120, tag="V-201")
    cv = await place_symbol(backend, "globe", 160, 106, tag="FCV-101", actuator="diaphragm")
    fic = await place_symbol(
        backend, "instrument", 160, 160, tag="FIC-101", type="dcs", location="primary"
    )
    await place_symbol(
        backend, "instrument", 100, 160, tag="PT-10", type="discrete", location="field"
    )
    await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": cv["handle"], "port": "in"},
        size="100",
        service="P",
        spec="CS1",
    )
    await draw_line(
        backend,
        {"handle": cv["handle"], "port": "out"},
        {"handle": vessel["handle"], "port": "N3"},
        size="100",
        service="P",
        spec="CS1",
    )
    await draw_line(
        backend,
        {"handle": fic["handle"]},
        {"handle": cv["handle"], "port": "signal"},
        line_class="pneumatic",
    )
    return await build_graph(backend)


async def test_instrument_index_rows(backend):
    graph = await _pid(backend)
    rows = instrument_index(graph)
    assert [list(r) for r in rows] == [INDEX_KEYS] * 2
    assert [r["tag"] for r in rows] == ["FIC-101", "PT-10"]
    fic = rows[0]
    assert (
        fic["description"] == "Flow Indicating Controller"
        and fic["type"] == "dcs"
        and fic["location"] == "primary"
    )
    assert fic["connected_to"] == "FCV-101" and fic["signal_lines"] == 1
    assert rows[1]["signal_lines"] == 0 and rows[1]["connected_to"] == ""


async def test_line_list_rows(backend):
    graph = await _pid(backend)
    rows = line_list(graph)
    assert [list(r) for r in rows] == [LINE_KEYS] * 3
    numbered = [r for r in rows if r["line_number"]]
    assert [r["line_number"] for r in numbered] == ["100-P-1-CS1", "100-P-2-CS1"]
    assert numbered[0]["from_tag"] == "P-101" and numbered[0]["from_port"] == "discharge"
    assert numbered[0]["to_tag"] == "FCV-101" and numbered[0]["length_mm"] > 0
    assert rows[-1]["line_number"] is None, "untagged rows sort last"


async def test_equipment_list_rows(backend):
    graph = await _pid(backend)
    rows = equipment_list(graph)
    assert [list(r) for r in rows] == [EQUIP_KEYS] * 3
    assert [r["tag"] for r in rows] == ["FCV-101", "P-101", "V-201"]
    pump = next(r for r in rows if r["tag"] == "P-101")
    assert (
        pump["description"] == "Feed pump" and pump["ports"] == 2 and pump["connected_lines"] == 1
    )
    assert pump["unconnected_ports"] == "suction"


def test_natural_sort():
    assert sorted(["P-10", "P-2", "P-1A"], key=natural_key) == ["P-1A", "P-2", "P-10"]
    assert natural_key(None) > natural_key("Z-999"), "untagged rows sort last"


async def test_csv_is_written_inside_allowed_paths(backend, tmp_path, monkeypatch):
    import config

    monkeypatch.setattr(config.settings, "allowed_paths", [tmp_path.resolve()])
    await _pid(backend)
    target = tmp_path / "index.csv"
    result = await deliverable(backend, "instrument_index", csv_path=str(target))
    assert result["count"] == 2 and result["csv_path"] == str(target.resolve())
    with target.open(newline="", encoding="utf-8") as fh:
        reader = list(csv.reader(fh))
    assert reader[0] == INDEX_KEYS and reader[1][0] == "FIC-101"
    with pytest.raises(Exception):
        await deliverable(backend, "line_list", csv_path=str(tmp_path.parent / "outside.csv"))
```

- [ ] **Step 2: Run to verify they fail** — ModuleNotFoundError.

- [ ] **Step 3: Write the module**

```python
# engineering/pid/deliverables.py
"""Instrument index, line list and equipment list — rows derived from the graph."""

from __future__ import annotations

import csv
import re
from pathlib import Path
from typing import TYPE_CHECKING

from .graph import build_graph

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

_NUM = re.compile(r"(\d+)")


def natural_key(tag):
    if tag is None:
        return (1, [])
    return (0, [int(part) if part.isdigit() else part for part in _NUM.split(str(tag))])


def _node_map(graph: dict) -> dict[str, dict]:
    return {n["id"]: n for n in graph["nodes"]}


def _tag_of(ref: dict | None, nodes: dict) -> tuple[str | None, str | None]:
    if not ref:
        return None, None
    if "node" in ref:
        return nodes[ref["node"]].get("tag"), ref.get("port")
    return ref.get("junction"), None


def instrument_index(graph: dict) -> list[dict]:
    nodes = _node_map(graph)
    edges = {e["id"]: e for e in graph["edges"]}
    rows = []
    for node in graph["nodes"]:
        if node["kind"] != "instrument":
            continue
        parsed = node.get("tag_parsed") or {}
        connected = []
        signal_lines = 0
        for port in node["ports"].values():
            for edge_id in port["edges"]:
                edge = edges[edge_id]
                signal_lines += 1
                for ref in (edge["from"], edge["to"]):
                    if ref and "node" in ref and ref["node"] != node["id"]:
                        other = nodes[ref["node"]]
                        connected.append(
                            other.get("tag") or (edge.get("line_number") or other["id"])
                        )
        variant = (node.get("symbol") or "", node.get("block_name") or "")
        rows.append(
            {
                "tag": node.get("tag"),
                "func": parsed.get("letters"),
                "loop": parsed.get("loop"),
                "description": parsed.get("description"),
                "type": _bubble_part(node, 2),
                "location": _bubble_part(node, 3),
                "connected_to": ", ".join(dict.fromkeys(connected)),
                "signal_lines": signal_lines,
                "handle": node["id"],
                "confidence": node["confidence"],
            }
        )
    rows.sort(key=lambda r: natural_key(r["tag"]))
    return rows


def _bubble_part(node: dict, index: int) -> str | None:
    """PID_INST_<TYPE>_<LOCATION...> → type (index 2) or location (index 3+)."""
    name = node.get("block_name") or ""
    if not name.startswith("PID_INST_"):
        return None
    parts = name.split("_")
    if index == 2:
        return parts[2].lower() if len(parts) > 2 else None
    return "_".join(parts[3:]).lower() if len(parts) > 3 else None


def line_list(graph: dict) -> list[dict]:
    nodes = _node_map(graph)
    rows = []
    for edge in graph["edges"]:
        from_tag, from_port = _tag_of(edge["from"], nodes)
        to_tag, to_port = _tag_of(edge["to"], nodes)
        rows.append(
            {
                "line_number": edge.get("line_number"),
                "line_class": edge.get("line_class"),
                "size": edge.get("size"),
                "service": edge.get("service"),
                "spec": edge.get("spec"),
                "insulation": edge.get("insulation"),
                "from_tag": from_tag,
                "from_port": from_port,
                "to_tag": to_tag,
                "to_port": to_port,
                "length_mm": round(float(edge.get("length") or 0.0), 1),
                "handle": edge["id"],
                "number_source": edge.get("number_source"),
            }
        )
    rows.sort(key=lambda r: natural_key(r["line_number"]))
    return rows


def equipment_list(graph: dict) -> list[dict]:
    rows = []
    for node in graph["nodes"]:
        if node["kind"] not in ("equipment", "valve", "connector", "unknown_block"):
            continue
        ports = node["ports"]
        connected = sum(1 for p in ports.values() if p["edges"])
        rows.append(
            {
                "tag": node.get("tag"),
                "kind": node["kind"],
                "symbol": node.get("symbol"),
                "description": node.get("description")
                or (node.get("tag_parsed") or {}).get("equipment_kind"),
                "ports": len(ports),
                "connected_lines": sum(len(p["edges"]) for p in ports.values()),
                "unconnected_ports": ", ".join(name for name, p in ports.items() if not p["edges"]),
                "handle": node["id"],
                "confidence": node["confidence"],
            }
        )
    rows.sort(key=lambda r: natural_key(r["tag"]))
    return rows


def write_csv(rows: list[dict], path: str) -> str:
    from security import validate_path

    target = validate_path(path, allow_write=True)
    Path(target).parent.mkdir(parents=True, exist_ok=True)
    with open(target, "w", newline="", encoding="utf-8") as fh:
        writer = csv.writer(fh)
        if rows:
            writer.writerow(list(rows[0]))
            for row in rows:
                writer.writerow(["" if v is None else v for v in row.values()])
    return str(target)


_BUILDERS = {
    "instrument_index": instrument_index,
    "line_list": line_list,
    "equipment_list": equipment_list,
}


async def deliverable(
    backend: AutoCADBackend, which: str, csv_path: str | None = None, **graph_kwargs
) -> dict:
    graph = await build_graph(backend, **graph_kwargs)
    rows = _BUILDERS[which](graph)
    written = write_csv(rows, csv_path) if csv_path else None
    return {"rows": rows, "count": len(rows), "csv_path": written, "graph_stats": graph["stats"]}
```

- [ ] **Step 4: Run the tests** — `uv run --frozen pytest tests/test_pid_deliverables.py tests/test_pid_graph.py -v` → PASS.

- [ ] **Step 5: Register the three tools** (SECTION 17 → `(7 tools)`)

```python
@cad_tool(
    summary="Instrument index derived from the P&ID graph (tag, function, loop, connections); optional CSV.",
    cost="read",
)
@mcp.tool(
    annotations={"title": "P&ID: Instrument Index", "readOnlyHint": True}, tags={"pid", "query"}
)
async def pid_instrument_index(
    csv_path: Annotated[str | None, "Write the rows as CSV here (inside ALLOWED_PATHS)"] = None,
    tolerance: Annotated[float, Field(default=0.5, gt=0)] = 0.5,
    scope: Annotated[str, "current_space | all"] = "current_space",
    ctx: Context = None,
) -> dict:
    """Every instrument bubble with its ISA-5.1 reading and what it connects to.

    Rows come from `pid_graph`, never from typed-in lists; the drawing is not
    modified. `csv_path` is the only file this tool writes.
    """
    from engineering.pid.deliverables import deliverable

    return await deliverable(
        _backend(ctx), "instrument_index", csv_path, tolerance=tolerance, scope=scope
    )


@cad_tool(
    summary="Line list derived from the P&ID graph (number, class, size, spec, from/to); optional CSV.",
    cost="read",
)
@mcp.tool(annotations={"title": "P&ID: Line List", "readOnlyHint": True}, tags={"pid", "query"})
async def pid_line_list(
    csv_path: Annotated[str | None, "Write the rows as CSV here (inside ALLOWED_PATHS)"] = None,
    tolerance: Annotated[float, Field(default=0.5, gt=0)] = 0.5,
    scope: Annotated[str, "current_space | all"] = "current_space",
    ctx: Context = None,
) -> dict:
    """Every P&ID line with its number, class, size/service/spec/insulation and endpoints."""
    from engineering.pid.deliverables import deliverable

    return await deliverable(_backend(ctx), "line_list", csv_path, tolerance=tolerance, scope=scope)


@cad_tool(
    summary="Equipment list derived from the P&ID graph (tag, kind, ports, connections); optional CSV.",
    cost="read",
)
@mcp.tool(
    annotations={"title": "P&ID: Equipment List", "readOnlyHint": True}, tags={"pid", "query"}
)
async def pid_equipment_list(
    csv_path: Annotated[str | None, "Write the rows as CSV here (inside ALLOWED_PATHS)"] = None,
    tolerance: Annotated[float, Field(default=0.5, gt=0)] = 0.5,
    scope: Annotated[str, "current_space | all"] = "current_space",
    ctx: Context = None,
) -> dict:
    """Every equipment, valve and connector node with its ports and how many lines reach them."""
    from engineering.pid.deliverables import deliverable

    return await deliverable(
        _backend(ctx), "equipment_list", csv_path, tolerance=tolerance, scope=scope
    )
```

Aliases:

```python
    "pid_instrument_index": ToolAliases(acad=(), synonyms=("instrument index", "instrument list", "loop list", "tag list")),
    "pid_line_list": ToolAliases(acad=(), synonyms=("line list", "pipe list", "line schedule", "line numbers")),
    "pid_equipment_list": ToolAliases(acad=(), synonyms=("equipment list", "equipment schedule", "valve list")),
```

Inventory; README `164 tools`.

- [ ] **Step 6: Gates and commit**

```bash
git add engineering/pid/deliverables.py server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_pid_deliverables.py
git commit -m "feat(pid): instrument index, line list and equipment list from the graph"
```

---
### Task 16: Critique focuses, refine hints, plan/preflight rule

**Files:**
- Modify: `engineering/plan_spec.py` (`CritiqueFocus`, `ALL_CRITIQUE_FOCUSES`)
- Create: `engineering/pid/critique.py`
- Modify: `engineering/critique.py` (`_FOCUS_DISPATCH` registration + shared context in `run_critique`)
- Modify: `engineering/preflight.py` (`LAYER_SET_INTENT_MISMATCH`), `server.py` (`drawing_plan` warnings; `drawing_critique`/`drawing_finalize` docstrings list the new focuses)
- Test: `tests/test_pid_critique.py`

**Interfaces:**
- Consumes: `build_graph` (Task 14), `LINE_CLASSES` (Task 12), `parse_tag` (Task 6), `Issue`.
- Produces: `PID_FOCUSES = ("pid_dangling_line", "pid_duplicate_tag", "pid_incompatible_connection", "pid_untagged_instrument", "pid_illegal_tag", "pid_unconnected_equipment")`; pure checks `issues_for(focus, graph) -> list[Issue]`; async dispatch entries `check(backend, shared)` with `check.needs_shared = True`; `engineering/preflight.py::PID_INTENT_RE`, `intent_reads_as_pid(intent) -> bool`, `pid_plan_warnings(intent, layer_set_id) -> list[str]`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_critique.py
"""Six P&ID focuses; all silent on a drawing with no P&ID content."""

from __future__ import annotations

import pytest

from engineering.pid.drawlines import draw_line
from engineering.pid.insert import place_symbol
from engineering.plan_spec import ALL_CRITIQUE_FOCUSES
from engineering.preflight import pid_plan_warnings, preflight_drawing

pytestmark = pytest.mark.asyncio

PID_FOCUSES = (
    "pid_dangling_line",
    "pid_duplicate_tag",
    "pid_incompatible_connection",
    "pid_untagged_instrument",
    "pid_illegal_tag",
    "pid_unconnected_equipment",
)


def test_focuses_are_in_the_closed_enum():
    for focus in PID_FOCUSES:
        assert focus in ALL_CRITIQUE_FOCUSES


async def _clean(backend):
    pump = await place_symbol(backend, "centrifugal_pump", 100, 100, tag="P-101")
    cv = await place_symbol(backend, "globe", 160, 106, tag="FCV-101", actuator="diaphragm")
    fic = await place_symbol(
        backend, "instrument", 160, 140, tag="FIC-101", type="dcs", location="primary"
    )
    await draw_line(
        backend,
        {"handle": pump["handle"], "port": "discharge"},
        {"handle": cv["handle"], "port": "in"},
    )
    await draw_line(backend, {"handle": cv["handle"], "port": "out"}, {"x": 220, "y": 106})
    await draw_line(
        backend,
        {"handle": fic["handle"]},
        {"handle": cv["handle"], "port": "signal"},
        line_class="electric",
    )
    return pump, cv, fic


async def test_clean_pid_has_no_pid_issues_except_the_free_end(backend):
    await _clean(backend)
    issues = await backend.drawing_critique(list(PID_FOCUSES))
    focuses = [i.focus for i in issues]
    assert focuses == ["pid_dangling_line"], "the line to a free point is the only finding"
    assert issues[0].severity == "error" and "hint" in issues[0].detail


async def test_dangling_carries_the_nearest_port_hint(backend):
    pump, cv, _ = await _clean(backend)
    await backend.entity_move(cv["handle"], 0.0, 1.0)
    issues = await backend.drawing_critique(["pid_dangling_line"])
    hinted = [i for i in issues if i.detail.get("nearest")]
    assert hinted and hinted[0].detail["nearest"]["node"] == cv["handle"]
    assert "pid_line_draw" in hinted[0].detail["hint"]


async def test_duplicate_and_illegal_and_untagged(backend):
    await place_symbol(backend, "instrument", 0, 0, tag="FIC-101")
    await place_symbol(backend, "instrument", 30, 0, tag="FIC-101")
    await place_symbol(backend, "instrument", 60, 0, tag="FCI-102")
    await place_symbol(backend, "instrument", 90, 0)
    await place_symbol(backend, "gate", 120, 0, tag="FIC-101")
    issues = await backend.drawing_critique(
        ["pid_duplicate_tag", "pid_illegal_tag", "pid_untagged_instrument"]
    )
    by_focus = {}
    for issue in issues:
        by_focus.setdefault(issue.focus, []).append(issue)
    assert (
        len(by_focus["pid_duplicate_tag"]) == 1
        and len(by_focus["pid_duplicate_tag"][0].handles) == 3
    )
    assert by_focus["pid_duplicate_tag"][0].severity == "error"
    assert (
        len(by_focus["pid_illegal_tag"]) == 1
        and by_focus["pid_illegal_tag"][0].severity == "warning"
    )
    assert len(by_focus["pid_untagged_instrument"]) == 1


async def test_incompatible_connection(backend):
    pump = await place_symbol(backend, "centrifugal_pump", 100, 100, tag="P-101")
    fic = await place_symbol(backend, "instrument", 100, 160, tag="FIC-1")
    await draw_line(
        backend,
        {"handle": fic["handle"]},
        {"handle": pump["handle"], "port": "discharge"},
        line_class="electric",
    )
    issues = await backend.drawing_critique(["pid_incompatible_connection"])
    assert len(issues) == 1 and issues[0].severity == "error"
    assert issues[0].detail == {
        "expected": "signal",
        "actual": "process",
        "port": "discharge",
        "line_class": "electric",
        "hint": issues[0].detail["hint"],
    }


async def test_unconnected_equipment_is_informational(backend):
    await place_symbol(backend, "vertical_vessel", 0, 0, tag="V-1")
    issues = await backend.drawing_critique(["pid_unconnected_equipment"])
    assert len(issues) == 1 and issues[0].severity == "info"


async def test_mechanical_drawing_is_untouched_by_pid_focuses(backend):
    from engineering.layers import ensure_engineering_layers

    await ensure_engineering_layers(backend)
    await backend.entity_create_circle(0, 0, 20, layer="GEOMETRY")
    await backend.entity_create_line(-30, 0, 30, 0, layer="CENTER")
    assert await backend.drawing_critique(list(PID_FOCUSES)) == []


async def test_refine_reports_pid_issues_as_manual_and_moves_nothing(backend):
    await _clean(backend)
    before = await backend.entity_count()
    result = await backend.drawing_refine(
        max_rounds=1, min_score=100.0, focus=list(PID_FOCUSES), dry_run=True
    )
    assert all(a["status"] == "manual_required" for r in result["rounds"] for a in r["actions"])
    assert await backend.entity_count() == before


def test_preflight_flags_a_pid_intent_on_the_wrong_layer_set():
    result = preflight_drawing(
        "P&ID for the feed section",
        {"units": "mm", "part_type": "pid", "dimensions": {}, "tolerance_policy": "none"},
        layer_set_id="mech",
    )
    codes = [c.code for c in result.conflicts]
    assert "LAYER_SET_INTENT_MISMATCH" in codes
    ok = preflight_drawing(
        "P&ID for the feed section",
        {"units": "mm", "part_type": "pid", "dimensions": {}, "tolerance_policy": "none"},
        layer_set_id="pid",
    )
    assert "LAYER_SET_INTENT_MISMATCH" not in [c.code for c in ok.conflicts]
    assert pid_plan_warnings("Bearing housing", "mech") == []
    assert pid_plan_warnings("piping and instrumentation diagram", "mech")
```

- [ ] **Step 2: Run to verify they fail** — `uv run --frozen pytest tests/test_pid_critique.py -v` → the enum test fails first.

- [ ] **Step 3: Extend the enum**

In `engineering/plan_spec.py` add to both `CritiqueFocus` and `ALL_CRITIQUE_FOCUSES`, after `"gdt"`:

```python
("pid_dangling_line",)
("pid_duplicate_tag",)
("pid_incompatible_connection",)
("pid_untagged_instrument",)
("pid_illegal_tag",)
("pid_unconnected_equipment",)
```

- [ ] **Step 4: Write the checks**

```python
# engineering/pid/critique.py
"""Six P&ID focuses over one graph per critique run.

Every check is pure over the graph dict; ``run_critique`` builds the graph once
into the per-run ``shared`` context so six focuses cost one read. A drawing
with no P&ID nodes yields no issues — mechanical sheets are never scored here.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

from engineering.plan_spec import Issue

from .graph import build_graph
from .lines import LINE_CLASSES
from .tags import parse_tag

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

PID_FOCUSES = (
    "pid_dangling_line",
    "pid_duplicate_tag",
    "pid_incompatible_connection",
    "pid_untagged_instrument",
    "pid_illegal_tag",
    "pid_unconnected_equipment",
)
_KEY = "pid_graph"


def _dangling(graph: dict) -> list[Issue]:
    out = []
    for d in graph["dangling"]:
        nearest = d.get("nearest")
        if nearest:
            hint = (
                f"pid_line_draw(from_={{'handle': ..., 'port': ...}}, to={{'handle': '{nearest['node']}', "
                f"'port': '{nearest['port']}'}}) — nearest port {nearest['distance']} mm away"
            )
        else:
            hint = "no port within reach; connect this end with pid_line_draw or delete the line"
        out.append(
            Issue(
                "error",
                "pid_dangling_line",
                f"Line {d['edge']} {d['end']} end at ({d['x']:.2f}, {d['y']:.2f}) connects to nothing.",
                [d["edge"]],
                {"end": d["end"], "x": d["x"], "y": d["y"], "nearest": nearest, "hint": hint},
            )
        )
    return out


def _duplicate_tags(graph: dict) -> list[Issue]:
    seen: dict[str, list[str]] = {}
    for node in graph["nodes"]:
        if (
            node.get("tag") and node["kind"] != "connector"
        ):  # connectors carry free text ("TO P&ID-002")
            seen.setdefault(node["tag"].upper(), []).append(node["id"])
    return [
        Issue(
            "error",
            "pid_duplicate_tag",
            f"Tag {tag} is carried by {len(handles)} symbols.",
            handles,
            {
                "tag": tag,
                "hint": "block_set_attributes(handle, {'TAG'|'FUNC'/'LOOP': ...}) on all but one",
            },
        )
        for tag, handles in seen.items()
        if len(handles) > 1
    ]


def _incompatible(graph: dict) -> list[Issue]:
    nodes = {n["id"]: n for n in graph["nodes"]}
    out = []
    for edge in graph["edges"]:
        cls = LINE_CLASSES.get(edge.get("line_class") or "")
        if cls is None:
            continue
        for ref in (edge["from"], edge["to"]):
            if not ref or "node" not in ref:
                continue
            port = nodes[ref["node"]]["ports"].get(ref["port"], {})
            actual = port.get("kind")
            if actual in ("process", "signal") and actual != cls.kind:
                out.append(
                    Issue(
                        "error",
                        "pid_incompatible_connection",
                        f"{cls.kind} line {edge['id']} ends on {actual} port {ref['port']} of {ref['node']}.",
                        [edge["id"], ref["node"]],
                        {
                            "expected": cls.kind,
                            "actual": actual,
                            "port": ref["port"],
                            "line_class": edge["line_class"],
                            "hint": f"redraw with a {actual} line class or connect to a {cls.kind} port",
                        },
                    )
                )
    return out


def _untagged(graph: dict) -> list[Issue]:
    return [
        Issue(
            "warning",
            "pid_untagged_instrument",
            f"Instrument {n['id']} has no tag.",
            [n["id"]],
            {"hint": "block_set_attributes(handle, {'FUNC': 'FIC', 'LOOP': '101'})"},
        )
        for n in graph["nodes"]
        if n["kind"] == "instrument" and not n.get("tag")
    ]


def _illegal(graph: dict) -> list[Issue]:
    out = []
    for n in graph["nodes"]:
        if not n.get("tag") or n["kind"] == "connector":
            continue
        parsed = parse_tag(n["tag"], kind="instrument" if n["kind"] == "instrument" else "auto")
        if not parsed["valid"]:
            out.append(
                Issue(
                    "warning",
                    "pid_illegal_tag",
                    f"Tag {n['tag']} on {n['id']} is not ISA-5.1: {parsed['errors'][0]}",
                    [n["id"]],
                    {"errors": parsed["errors"], "hint": "block_set_attributes with a valid tag"},
                )
            )
    return out


def _unconnected(graph: dict) -> list[Issue]:
    return [
        Issue(
            "info",
            "pid_unconnected_equipment",
            f"{n['kind']} {n.get('tag') or n['id']} has no line on any port.",
            [n["id"]],
            {"hint": "informational — connect it with pid_line_draw or leave it if intended"},
        )
        for n in graph["nodes"]
        if n["kind"] in ("equipment", "valve")
        and n["ports"]
        and not any(p["edges"] for p in n["ports"].values())
    ]


_CHECKS = {
    "pid_dangling_line": _dangling,
    "pid_duplicate_tag": _duplicate_tags,
    "pid_incompatible_connection": _incompatible,
    "pid_untagged_instrument": _untagged,
    "pid_illegal_tag": _illegal,
    "pid_unconnected_equipment": _unconnected,
}


def issues_for(focus: str, graph: dict) -> list[Issue]:
    if not graph["nodes"]:
        return []
    return _CHECKS[focus](graph)


def _make(focus: str):
    async def check(backend: AutoCADBackend, shared: dict) -> list[Issue]:
        graph = shared.get(_KEY)
        if graph is None:
            graph = shared[_KEY] = await build_graph(backend, include_foreign=True)
        return issues_for(focus, graph)

    check.needs_shared = True  # type: ignore[attr-defined]
    check.__name__ = f"check_{focus}"
    return check


PID_DISPATCH = {focus: _make(focus) for focus in PID_FOCUSES}
```

In `engineering/critique.py`: after `_FOCUS_DISPATCH = {...}` add

```python
from .pid.critique import PID_DISPATCH  # noqa: E402  (registered after the mechanical focuses)

_FOCUS_DISPATCH.update(PID_DISPATCH)
```

and change the dispatch loop in `run_critique` to

```python
    shared: dict = {}
    for f in foci:
        check = _FOCUS_DISPATCH.get(f)
        if check is None:
            ...  # unchanged
            continue
        if getattr(check, "needs_shared", False):
            issues.extend(await check(backend, shared))
        else:
            issues.extend(await check(backend))
    return issues
```

(`engineering/pid/critique.py` imports `engineering.plan_spec`, not `engineering.critique`, so there is no cycle.)

- [ ] **Step 5: Preflight conflict and plan warning**

In `engineering/preflight.py` add near the top:

```python
PID_INTENT_RE = re.compile(
    r"\b(p&id|pid|piping and instrumentation|process flow|instrument)\b", re.IGNORECASE
)


def intent_reads_as_pid(intent: str) -> bool:
    return bool(PID_INTENT_RE.search(str(intent or "")))


def pid_plan_warnings(intent: str, layer_set_id: str) -> list[str]:
    if intent_reads_as_pid(intent) and str(layer_set_id).strip().lower() != "pid":
        return [
            f"intent reads as a P&ID but the layer set is '{layer_set_id}'; pass layer_set_id='pid'"
        ]
    return []
```

(add `import re` to the module imports), and inside `preflight_drawing` after the `parameter_rules` loop:

```python
for message in pid_plan_warnings(intent, normalized_layer_set):
    conflicts.append(
        PreflightConflict(
            "LAYER_SET_INTENT_MISMATCH", "layer_set_id", [layer_set_id, "pid"], message
        )
    )
```

In `server.py::drawing_plan`, replace `return _dc(plan)` with

```python
    from engineering.preflight import pid_plan_warnings

    out = _dc(plan)
    warnings = pid_plan_warnings(intent, layer_set_id)
    if warnings:
        out["warnings"] = warnings
    return out
```

Update the `drawing_critique` `focus` description and the `drawing_finalize` docstring to list the six `pid_*` focuses (both currently enumerate the mechanical ones).

- [ ] **Step 6: Run the tests** — `uv run --frozen pytest tests/test_pid_critique.py tests/test_meta_tools.py tests/test_refiner.py tests/test_preflight.py -v` → PASS.

- [ ] **Step 7: Commit**

```bash
git add engineering/plan_spec.py engineering/pid/critique.py engineering/critique.py engineering/preflight.py server.py tests/test_pid_critique.py
git commit -m "feat(pid): six P&ID critique focuses join drawing_finalize; plan/preflight flag a P&ID intent on the wrong layer set"
```

---

### Task 17: `pid_from_spec` + README showcase render

**Files:**
- Create: `engineering/pid/spec.py`, `scripts/render_readme_pid.py`
- Modify: `server.py` (SECTION 17 → `(8 tools)`), `discovery/aliases.py`, `README.md` (`165 tools`), inventory
- Test: `tests/test_pid_from_spec.py`

**Interfaces:**
- Consumes: `place_symbol`, `draw_line`, `build_graph`, `issues_for`/`PID_FOCUSES`, `resolve`, `transform_port`, `route`, `count_crossings`, backend `transaction_begin/commit/rollback`, `drawing_plan`, `get_plan_spec`.
- Produces: `EXAMPLE_SPEC: dict` (the spec §10 example), `validate_spec(spec) -> dict`, `async run_spec(backend, spec, dry_run=False) -> dict`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_from_spec.py
"""pid_from_spec: one call, one transaction, graph + critique back."""

from __future__ import annotations

import copy

import pytest
import pytest_asyncio
from fastmcp import Client

import server
from engineering.pid.spec import EXAMPLE_SPEC, run_spec, validate_spec

pytestmark = pytest.mark.asyncio


async def test_example_draws_a_connected_pid(backend):
    result = await run_spec(backend, EXAMPLE_SPEC)
    assert set(result["handles"]) == {"P-101", "V-201", "FCV-101", "FIC-101", "OP-1"}
    graph = result["graph"]
    assert graph["stats"]["nodes_by_kind"] == {
        "connector": 1,
        "equipment": 2,
        "instrument": 1,
        "valve": 1,
    }
    assert len(graph["edges"]) == 4 and graph["stats"]["dangling"] == 0
    assert result["critique"] == [] and result["crossings_total"] == 0
    assert backend.get_plan_spec()["layer_set_id"] == "pid"


async def test_bad_reference_rolls_back(backend):
    before = await backend.entity_count()
    bad = copy.deepcopy(EXAMPLE_SPEC)
    bad["lines"].append({"from": "P-101.discharge", "to": "V-201.NOPE", "class": "process_major"})
    with pytest.raises(ValueError, match=r"lines\[3\]"):
        await run_spec(backend, bad)
    assert await backend.entity_count() == before


async def test_dry_run_routes_in_memory_and_writes_nothing(backend):
    before = await backend.entity_count()
    result = await run_spec(backend, EXAMPLE_SPEC, dry_run=True)
    assert result["dry_run"] is True and len(result["lines"]) == 4
    assert all(len(line["vertices"]) >= 2 for line in result["lines"])
    assert await backend.entity_count() == before


@pytest.mark.parametrize(
    "mutate, fragment",
    [
        (
            lambda s: s["equipment"].append({"id": "P-101", "symbol": "fan", "x": 0, "y": 0}),
            "equipment[2].id",
        ),
        (lambda s: s["lines"][0].update({"class": "steam"}), "lines[0].class"),
        (lambda s: s["instruments"][0].pop("x"), "instruments[0].x"),
        (lambda s: s.update({"bogus": []}), "bogus"),
        (lambda s: s["connectors"][0].update({"to": "V-201.N1"}), "connectors[0]"),
    ],
)
def test_validation_names_the_path(mutate, fragment):
    spec = copy.deepcopy(EXAMPLE_SPEC)
    mutate(spec)
    with pytest.raises(ValueError) as exc:
        validate_spec(spec)
    assert fragment in str(exc.value)


@pytest_asyncio.fixture
async def client(monkeypatch):
    monkeypatch.setenv("AUTOCAD_MCP_BACKEND", "ezdxf")
    async with Client(server.mcp) as connected:
        await connected.call_tool("drawing_new", {})
        yield connected


async def test_finalize_scores_the_example_at_ninety_or_better(client):
    result = (await client.call_tool("pid_from_spec", {"spec": EXAMPLE_SPEC})).structured_content
    assert result["graph"]["stats"]["dangling"] == 0
    final = (await client.call_tool("drawing_finalize", {})).structured_content
    assert final["score"] >= 90, final
    assert not [i for i in final.get("critique", []) if str(i.get("focus", "")).startswith("pid_")]
```

- [ ] **Step 2: Run to verify they fail** — ModuleNotFoundError.

- [ ] **Step 3: Write the module**

```python
# engineering/pid/spec.py
"""``pid_from_spec``: a whole P&ID from one declarative document, in one transaction."""

from __future__ import annotations

import copy
from typing import TYPE_CHECKING

from .critique import PID_FOCUSES, issues_for
from .drawlines import draw_line
from .graph import build_graph
from .insert import place_symbol
from .lines import LINE_CLASSES, count_crossings, route, snap_axis, AXIS
from .symbols import resolve, transform_port

if TYPE_CHECKING:
    from backends.base import AutoCADBackend

EXAMPLE_SPEC: dict = {
    "sheet": {"layer_set": "pid", "sheet_size": "A3", "scale": 1.0, "intent": "Feed section P&ID"},
    "equipment": [
        {
            "id": "P-101",
            "symbol": "centrifugal_pump",
            "x": 100,
            "y": 100,
            "rotation": 0,
            "tag": "P-101",
            "desc": "Feed pump",
        },
        {
            "id": "V-201",
            "symbol": "vertical_vessel",
            "x": 220,
            "y": 120,
            "tag": "V-201",
            "params": {
                "width": 20,
                "height": 40,
                "nozzles": [
                    {"name": "N1", "side": "top", "fraction": 0.5},
                    {"name": "N2", "side": "left", "fraction": 0.3},
                ],
            },
        },
    ],
    "valves": [
        {
            "id": "FCV-101",
            "symbol": "globe",
            "actuator": "diaphragm",
            "x": 160,
            "y": 104,
            "tag": "FCV-101",
            "fail": "FC",
        },
    ],
    "instruments": [
        {
            "id": "FIC-101",
            "type": "dcs",
            "location": "primary",
            "x": 160,
            "y": 140,
            "tag": "FIC-101",
        },
    ],
    "lines": [
        {
            "from": "P-101.discharge",
            "to": "FCV-101.in",
            "class": "process_major",
            "number": "100-P-1001-CS1",
        },
        {
            "from": "FCV-101.out",
            "to": "V-201.N2",
            "class": "process_major",
            "number": "100-P-1001-CS1",
        },
        {"from": "FIC-101", "to": "FCV-101.signal", "class": "electric"},
    ],
    "connectors": [
        {
            "id": "OP-1",
            "direction": "out",
            "x": 300,
            "y": 120,
            "tag": "TO P&ID-002",
            "link": "L-17",
            "from": "V-201.N1",
            "class": "process_major",
        },
    ],
}

_TOP_KEYS = {"sheet", "equipment", "valves", "instruments", "lines", "connectors"}
_ITEM_OPTIONS = {
    "equipment": {"symbol", "x", "y", "rotation", "scale", "tag", "desc", "params", "shape"},
    "valves": {"symbol", "x", "y", "rotation", "scale", "tag", "desc", "actuator", "fail"},
    "instruments": {"x", "y", "rotation", "scale", "tag", "type", "location"},
    "connectors": {
        "x",
        "y",
        "rotation",
        "scale",
        "tag",
        "link",
        "direction",
        "from",
        "to",
        "class",
        "number",
    },
}
_LINE_KEYS = {
    "from",
    "to",
    "class",
    "number",
    "size",
    "service",
    "spec",
    "insulation",
    "route",
    "stub",
    "label",
    "arrow",
}


def _num(value, where):
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise ValueError(f"{where} must be a number")
    return float(value)


def _ref(value, where, ids: set[str]) -> tuple[str, str | None]:
    if not isinstance(value, str) or not value:
        raise ValueError(f"{where} must be 'ID' or 'ID.port'")
    item_id, _, port = value.partition(".")
    if item_id not in ids:
        raise ValueError(f"{where}: unknown id {item_id!r}")
    return item_id, port or None


def validate_spec(spec: dict) -> dict:
    if not isinstance(spec, dict):
        raise ValueError("spec must be an object")
    unknown = set(spec) - _TOP_KEYS
    if unknown:
        raise ValueError(f"unknown top-level key(s): {', '.join(sorted(unknown))}")
    out = {key: copy.deepcopy(spec.get(key) or ([] if key != "sheet" else {})) for key in _TOP_KEYS}
    if not isinstance(out["sheet"], dict):
        raise ValueError("sheet must be an object")
    ids: set[str] = set()
    for section in ("equipment", "valves", "instruments", "connectors"):
        items = out[section]
        if not isinstance(items, list):
            raise ValueError(f"{section} must be a list")
        for i, item in enumerate(items):
            where = f"{section}[{i}]"
            if not isinstance(item, dict):
                raise ValueError(f"{where} must be an object")
            item_id = item.get("id")
            if not isinstance(item_id, str) or not item_id:
                raise ValueError(f"{where}.id must be a non-empty string")
            if item_id in ids:
                raise ValueError(f"{where}.id {item_id!r} is repeated")
            ids.add(item_id)
            bad = set(item) - _ITEM_OPTIONS[section] - {"id"}
            if bad:
                raise ValueError(f"{where}: unknown key(s) {', '.join(sorted(bad))}")
            for key in ("x", "y"):
                if key not in item:
                    raise ValueError(f"{where}.{key} is required")
                item[key] = _num(item[key], f"{where}.{key}")
            if section in ("equipment", "valves") and not isinstance(item.get("symbol"), str):
                raise ValueError(f"{where}.symbol is required")
            if section == "connectors":
                if item.get("direction") not in ("in", "out"):
                    raise ValueError(f"{where}.direction must be 'in' or 'out'")
                has_from, has_to = "from" in item, "to" in item
                if item["direction"] == "out" and (not has_from or has_to):
                    raise ValueError(f"{where}: an 'out' connector carries exactly 'from'")
                if item["direction"] == "in" and (not has_to or has_from):
                    raise ValueError(f"{where}: an 'in' connector carries exactly 'to'")
    lines = out["lines"]
    if not isinstance(lines, list):
        raise ValueError("lines must be a list")
    for i, line in enumerate(lines):
        where = f"lines[{i}]"
        if not isinstance(line, dict):
            raise ValueError(f"{where} must be an object")
        bad = set(line) - _LINE_KEYS
        if bad:
            raise ValueError(f"{where}: unknown key(s) {', '.join(sorted(bad))}")
        for key in ("from", "to"):
            if key not in line:
                raise ValueError(f"{where}.{key} is required")
            _ref(line[key], f"{where}.{key}", ids)
        cls = line.get("class", "process_major")
        if cls not in LINE_CLASSES:
            raise ValueError(f"{where}.class must be one of {', '.join(LINE_CLASSES)}")
        line["class"] = cls
    for i, conn in enumerate(out["connectors"]):
        key = "from" if conn["direction"] == "out" else "to"
        _ref(conn[key], f"connectors[{i}].{key}", ids)
        cls = conn.get("class", "process_major")
        if cls not in LINE_CLASSES:
            raise ValueError(f"connectors[{i}].class must be one of {', '.join(LINE_CLASSES)}")
        conn["class"] = cls
    return out


def _spec_for(section: str, item: dict):
    """Resolve the SymbolSpec an item would place (no backend)."""
    if section == "instruments":
        return resolve("instrument", type=item.get("type"), location=item.get("location"))
    if section == "connectors":
        return resolve("offpage", direction=item["direction"])
    return resolve(
        item["symbol"],
        actuator=item.get("actuator"),
        params=item.get("params"),
        shape=item.get("shape"),
    )


def _plan_lines(norm: dict) -> list[dict]:
    """Route every line in memory from catalogue ports — the dry run."""
    placed: dict[str, dict] = {}
    for section in ("equipment", "valves", "instruments", "connectors"):
        for item in norm[section]:
            spec = _spec_for(section, item)
            ports = {
                p.name: transform_port(
                    p, item["x"], item["y"], item.get("rotation", 0.0), item.get("scale", 1.0)
                )
                for p in spec.ports
            }
            placed[item["id"]] = {"family": spec.family, "ports": ports}

    def endpoint(ref: str) -> dict:
        item_id, port = ref.partition(".")[::2]
        entry = placed[item_id]
        if not port:
            if len(entry["ports"]) == 1:
                port = next(iter(entry["ports"]))
            elif entry["family"] == "instrument":
                port = "signal"
            else:
                raise ValueError(f"{ref}: choose a port: {', '.join(entry['ports'])}")
        if port not in entry["ports"]:
            raise ValueError(f"{ref}: no port {port!r}; ports: {', '.join(entry['ports'])}")
        return entry["ports"][port]

    def anchor(ep: dict, other: dict):
        if ep["radius"] > 0:
            axis = snap_axis(other["x"] - ep["x"], other["y"] - ep["y"])
            ux, uy = AXIS[axis]
            return (ep["x"] + ux * ep["radius"], ep["y"] + uy * ep["radius"]), axis
        return (ep["x"], ep["y"]), ep["direction_deg"]

    all_lines = list(norm["lines"]) + [
        {"from": c["from"], "to": f"{c['id']}", "class": c["class"]}
        if c["direction"] == "out"
        else {"from": f"{c['id']}", "to": c["to"], "class": c["class"]}
        for c in norm["connectors"]
    ]
    planned: list[dict] = []
    for i, line in enumerate(all_lines):
        start, end = endpoint(line["from"]), endpoint(line["to"])
        s, sd = anchor(start, end)
        e, ed = anchor(end, start)
        vertices = route(
            s, sd, e, ed, stub=float(line.get("stub", 5.0)), mode=line.get("route", "auto")
        )
        crossings = count_crossings(vertices, [p["vertices"] for p in planned])
        planned.append(
            {
                "index": i,
                "from": line["from"],
                "to": line["to"],
                "class": line["class"],
                "vertices": [[x, y] for x, y in vertices],
                "crossings": crossings,
            }
        )
    return planned


async def run_spec(backend: AutoCADBackend, spec: dict, dry_run: bool = False) -> dict:
    norm = validate_spec(spec)
    if dry_run:
        planned = _plan_lines(norm)
        return {
            "dry_run": True,
            "items": sum(
                len(norm[s]) for s in ("equipment", "valves", "instruments", "connectors")
            ),
            "lines": planned,
            "crossings_total": sum(p["crossings"] for p in planned),
        }
    sheet = norm["sheet"]
    if backend.get_plan_spec() is None:
        await backend.drawing_plan(
            sheet.get("intent", "P&ID"),
            sheet.get("sheet_size", "A3"),
            float(sheet.get("scale", 1.0)),
            sheet.get("layer_set", "pid"),
        )
    begun = await backend.transaction_begin()
    if not isinstance(begun, dict) or not begun.get("ok"):
        raise RuntimeError(f"pid_from_spec: could not open a transaction: {begun}")
    handles: dict[str, str] = {}
    crossings_total = 0
    try:
        for section in ("equipment", "valves", "instruments", "connectors"):
            for i, item in enumerate(norm[section]):
                where = f"{section}[{i}]"
                try:
                    if section == "instruments":
                        placed = await place_symbol(
                            backend,
                            "instrument",
                            item["x"],
                            item["y"],
                            item.get("rotation", 0.0),
                            item.get("scale", 1.0),
                            item.get("tag"),
                            None,
                            None,
                            None,
                            None,
                            type=item.get("type"),
                            location=item.get("location"),
                        )
                    elif section == "connectors":
                        placed = await place_symbol(
                            backend,
                            "offpage",
                            item["x"],
                            item["y"],
                            item.get("rotation", 0.0),
                            item.get("scale", 1.0),
                            item.get("tag"),
                            None,
                            None,
                            item.get("link"),
                            None,
                            direction=item["direction"],
                        )
                    else:
                        placed = await place_symbol(
                            backend,
                            item["symbol"],
                            item["x"],
                            item["y"],
                            item.get("rotation", 0.0),
                            item.get("scale", 1.0),
                            item.get("tag"),
                            item.get("desc"),
                            item.get("fail"),
                            None,
                            None,
                            actuator=item.get("actuator"),
                            params=item.get("params"),
                            shape=item.get("shape"),
                        )
                except ValueError as exc:
                    raise ValueError(f"{where}: {exc}") from exc
                handles[item["id"]] = placed["handle"]

        def ref(value: str) -> dict:
            item_id, _, port = value.partition(".")
            return (
                {"handle": handles[item_id], "port": port} if port else {"handle": handles[item_id]}
            )

        all_lines = [(f"lines[{i}]", line) for i, line in enumerate(norm["lines"])]
        for i, conn in enumerate(norm["connectors"]):
            if conn["direction"] == "out":
                all_lines.append(
                    (
                        f"connectors[{i}]",
                        {
                            "from": conn["from"],
                            "to": conn["id"],
                            "class": conn["class"],
                            "number": conn.get("number"),
                        },
                    )
                )
            else:
                all_lines.append(
                    (
                        f"connectors[{i}]",
                        {
                            "from": conn["id"],
                            "to": conn["to"],
                            "class": conn["class"],
                            "number": conn.get("number"),
                        },
                    )
                )
        for where, line in all_lines:
            try:
                drawn = await draw_line(
                    backend,
                    ref(line["from"]),
                    ref(line["to"]),
                    line["class"],
                    line.get("route", "auto"),
                    float(line.get("stub", 5.0)),
                    line.get("number"),
                    line.get("size"),
                    line.get("service"),
                    line.get("spec"),
                    line.get("insulation"),
                    None,
                    bool(line.get("label", True)),
                    line.get("arrow"),
                )
            except ValueError as exc:
                raise ValueError(f"{where}: {exc}") from exc
            crossings_total += drawn["crossings"]
    except Exception:
        await backend.transaction_rollback()
        raise
    await backend.transaction_commit()
    graph = await build_graph(backend)
    critique = [issue.to_dict() for focus in PID_FOCUSES for issue in issues_for(focus, graph)]
    return {
        "handles": handles,
        "graph": graph,
        "critique": critique,
        "crossings_total": crossings_total,
    }
```

- [ ] **Step 4: Register the tool** (SECTION 17 → `(8 tools)`)

```python
@cad_tool(
    summary="Draw a whole P&ID from one declarative spec in one transaction; returns graph + critique.",
    cost="mutate",
)
@mcp.tool(
    annotations={"title": "P&ID: From Spec", "readOnlyHint": False},
    tags={"pid", "create", "batch"},
)
async def pid_from_spec(
    spec: Annotated[
        dict,
        "{sheet, equipment[], valves[], instruments[], lines[], connectors[]} — see the P&ID prompt",
    ],
    dry_run: Annotated[bool, "Validate and route in memory; draw nothing"] = False,
    ctx: Context = None,
) -> dict:
    """Equipment, valves, instruments and connectors placed, then every line
    drawn port-to-port, inside one transaction: any bad item rolls the whole
    sheet back and the error names it (`lines[2].to`). The response carries the
    graph read back from the drawing and the P&ID critique issues, so the
    caller sees dangling ends or duplicate tags in the same round trip.
    `dry_run` returns the planned vertices and crossings without touching the
    drawing.
    """
    from engineering.pid.spec import run_spec

    await ctx.info("P&ID from spec" + (" (dry run)" if dry_run else ""))
    return await run_spec(_backend(ctx), spec, dry_run)
```

Alias:

```python
    "pid_from_spec": ToolAliases(
        acad=(),
        synonyms=("whole p&id in one call", "p&id from json", "draw the process from a spec", "batch p&id"),
    ),
```

Inventory; README `165 tools`.

- [ ] **Step 5: README showcase render script**

```python
# scripts/render_readme_pid.py
"""Render the P&ID the README shows, using only the server's own tools.

AUTOCAD_MCP_BACKEND=ezdxf uv run --frozen python scripts/render_readme_pid.py
"""

from __future__ import annotations

import argparse
import asyncio
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))

DEFAULT_OUTPUT = ROOT / "docs" / "assets" / "pid-showcase.png"


async def render(output: Path) -> dict:
    from backends.ezdxf_backend import EzdxfBackend
    from engineering.layers import apply_layer_set
    from engineering.pid.spec import EXAMPLE_SPEC, run_spec

    backend = EzdxfBackend()
    await backend.connect()
    try:
        await backend.drawing_new()
        await apply_layer_set(backend, "pid")
        result = await run_spec(backend, EXAMPLE_SPEC)
        png = await backend.view_screenshot()
        output.parent.mkdir(parents=True, exist_ok=True)
        output.write_bytes(png)
        return {
            "output": str(output),
            "bytes": len(png),
            "dangling": result["graph"]["stats"]["dangling"],
            "critique": len(result["critique"]),
        }
    finally:
        await backend.disconnect()


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
    args = parser.parse_args()
    print(asyncio.run(render(args.output)))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
```

Run it once (`uv run --frozen python scripts/render_readme_pid.py`) and commit the PNG.

- [ ] **Step 6: Gates and commit**

Run: `uv run --frozen pytest tests/test_pid_from_spec.py tests/test_discovery_aliases.py tests/test_tool_inventory.py tests/test_release_consistency.py -v`

```bash
git add engineering/pid/spec.py scripts/render_readme_pid.py docs/assets/pid-showcase.png server.py discovery/aliases.py docs/tool-inventory.json README.md tests/test_pid_from_spec.py
git commit -m "feat(pid): pid_from_spec — a whole P&ID in one transaction, graph and critique returned"
```

---

### Task 18: Tool packs (`TOOL_PACKS`)

**Files:**
- Modify: `config.py` (`tool_packs`), `server.py` (`TOOL_PACK_NAMES`, `PACK_TOOL_NAMES`, `_enabled_packs`, `_profile_enabled_names`, `_apply_tool_profile`, `system_about`, the `unknown_tool` rejection text, `LEAN_TOOL_NAMES` + 3), `.env.example`, `README.md` (Configuration table row)
- Test: `tests/test_tool_packs.py`

**Interfaces:**
- Produces: `config.settings.tool_packs: str` (default `"all"`); `server.TOOL_PACK_NAMES = ("core", "pid")`; `server.PACK_TOOL_NAMES = {"pid": frozenset({...9 tools...})}`; `server._enabled_packs() -> tuple[set[str], list[str]]` (enabled, ignored); `_active_tool_profile["tool_packs"] = {"enabled": [...], "available": [...], "ignored": [...]}`; `system_about()["tool_packs"]`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_tool_packs.py
"""TOOL_PACKS: advertise only the vertical packs a client uses; core is always on."""

from __future__ import annotations

import logging

import pytest
import pytest_asyncio

import config
import server

pytestmark = pytest.mark.asyncio

PID_TOOLS = {
    "pid_symbol_list",
    "pid_symbol_insert",
    "pid_line_draw",
    "pid_tag_parse",
    "pid_graph",
    "pid_instrument_index",
    "pid_line_list",
    "pid_equipment_list",
    "pid_from_spec",
}


@pytest_asyncio.fixture(autouse=True)
async def _restore(monkeypatch):
    yield
    monkeypatch.setattr(config.settings, "tool_packs", "all")
    await server._apply_tool_profile("full")


def test_pack_registry_names_real_tools_and_only_pid_ones():
    assert server.TOOL_PACK_NAMES == ("core", "pid")
    assert server.PACK_TOOL_NAMES["pid"] == frozenset(PID_TOOLS)


async def test_core_only_hides_every_pid_tool_but_keeps_block_define(monkeypatch):
    monkeypatch.setattr(config.settings, "tool_packs", "core")
    info = await server._apply_tool_profile("full")
    disabled = set(info["disabled_tools"])
    assert PID_TOOLS <= disabled
    assert "block_define" not in disabled and "entity_set_xdata" not in disabled
    assert info["tool_packs"] == {"enabled": ["core"], "available": ["core", "pid"], "ignored": []}


async def test_all_is_the_default_and_enables_pid(monkeypatch):
    monkeypatch.setattr(config.settings, "tool_packs", "all")
    info = await server._apply_tool_profile("full")
    assert not (PID_TOOLS & set(info["disabled_tools"]))
    assert info["tool_packs"]["enabled"] == ["core", "pid"]


async def test_unknown_pack_is_ignored_with_a_warning_and_core_cannot_be_dropped(
    monkeypatch, caplog
):
    monkeypatch.setattr(config.settings, "tool_packs", "pid,mech3000")
    with caplog.at_level(logging.WARNING, logger="autocad_mcp"):
        info = await server._apply_tool_profile("full")
    assert info["tool_packs"] == {
        "enabled": ["core", "pid"],
        "available": ["core", "pid"],
        "ignored": ["mech3000"],
    }
    assert "mech3000" in caplog.text


async def test_lean_intersects_with_packs(monkeypatch):
    assert {"pid_symbol_insert", "pid_line_draw", "pid_graph"} <= server.LEAN_TOOL_NAMES
    monkeypatch.setattr(config.settings, "tool_packs", "core")
    info = await server._apply_tool_profile("lean")
    assert (
        "pid_graph" in info["disabled_tools"] and "entity_create_line" not in info["disabled_tools"]
    )


async def test_system_about_reports_packs():
    from fastmcp import Client

    async with Client(server.mcp) as client:
        about = (await client.call_tool("system_about", {})).structured_content
    assert about["tool_packs"]["available"] == ["core", "pid"]
```

- [ ] **Step 2: Run to verify they fail** — `AttributeError: module 'server' has no attribute 'TOOL_PACK_NAMES'`.

- [ ] **Step 3: Implement**

`config.py`, next to `tool_profile`:

```python
        # Tool packs: "all" (default) advertises every vertical pack; a comma
        # list ("core,pid") advertises only those. core cannot be disabled.
        self.tool_packs: str = os.environ.get("TOOL_PACKS", "all").lower().strip()
```

`server.py`, after `SOLID_TOOL_NAMES`:

```python
# Tool packs: vertical domains a client can opt out of advertising. `core` is
# everything not claimed by another pack and is always on. ~300 tools would
# push the full catalog to ~80k idle tokens; a client that only drafts
# mechanically should not pay for the P&ID surface.
TOOL_PACK_NAMES = ("core", "pid")
PACK_TOOL_NAMES: dict[str, frozenset[str]] = {
    "pid": frozenset(
        {
            "pid_symbol_list",
            "pid_symbol_insert",
            "pid_line_draw",
            "pid_tag_parse",
            "pid_graph",
            "pid_instrument_index",
            "pid_line_list",
            "pid_equipment_list",
            "pid_from_spec",
        }
    ),
}


def _enabled_packs() -> tuple[set[str], list[str]]:
    raw = (config.settings.tool_packs or "all").lower()
    requested = [p.strip() for p in raw.split(",") if p.strip()]
    if not requested or "all" in requested:
        return set(TOOL_PACK_NAMES), []
    enabled = {"core"}
    ignored: list[str] = []
    for pack in requested:
        if pack in TOOL_PACK_NAMES:
            enabled.add(pack)
        else:
            ignored.append(pack)
            log.warning(
                "Unknown TOOL_PACKS entry %r ignored. Valid packs: %s.",
                pack,
                ", ".join(TOOL_PACK_NAMES),
            )
    return enabled, ignored
```

Change `_profile_enabled_names`:

```python
def _profile_enabled_names(profile: str, registered: set[str]) -> set[str]:
    packs, _ignored = _enabled_packs()
    hidden_by_pack = set().union(
        *(names for pack, names in PACK_TOOL_NAMES.items() if pack not in packs)
    )
    enabled = set(registered) - hidden_by_pack
    if profile == "lean":
        enabled &= LEAN_TOOL_NAMES
    if not config.settings.enable_3d:
        enabled -= SOLID_TOOL_NAMES
    return enabled
```

In `_apply_tool_profile`, after building `_active_tool_profile`, add:

```python
    packs, ignored = _enabled_packs()
    _active_tool_profile["tool_packs"] = {
        "enabled": sorted(packs),
        "available": list(TOOL_PACK_NAMES),
        "ignored": ignored,
    }
```

In `system_about`, add `"tool_packs": (_active_tool_profile or {}).get("tool_packs") or {"enabled": sorted(_enabled_packs()[0]), "available": list(TOOL_PACK_NAMES), "ignored": _enabled_packs()[1]}`. Add the three pid tools to `LEAN_TOOL_NAMES`. Find the `unknown_tool` rejection text (`server.py` ~line 4059: "the active TOOL_PROFILE / ENABLE_3D gate") and make it "the active TOOL_PROFILE / TOOL_PACKS / ENABLE_3D gate".

`.env.example`, after `TOOL_PROFILE=full`:

```
# Tool packs: all (default) | comma list of core,pid — advertise only the
# vertical packs this client uses. core is always on.
TOOL_PACKS=all
```

README Configuration table: a row `| TOOL_PACKS | all | Vertical packs to advertise: core,pid (core always on) |` matching the table's existing column layout.

- [ ] **Step 4: Run** — `uv run --frozen pytest tests/test_tool_packs.py tests/test_tool_profiles.py tests/test_tool_registry.py -v` → PASS.

- [ ] **Step 5: Commit**

```bash
git add config.py server.py .env.example README.md tests/test_tool_packs.py
git commit -m "feat(server): TOOL_PACKS — advertise only the vertical packs a client uses"
```

---

### Task 19: `pid_tag_parse` tool, prompt rewrite, two resources, catalogue contact sheet

**Files:**
- Modify: `server.py` (SECTION 17 → `(9 tools)`; `prompt_pid_diagram` rewritten; two `@mcp.resource`), `discovery/aliases.py`, `README.md` (`166 tools`, `8 resources`), inventory
- Create: `scripts/render_pid_catalog.py`, `docs/assets/pid-catalog.png`
- Test: `tests/test_pid_resources_prompt.py`

**Interfaces:**
- Produces: MCP tool `pid_tag_parse(tag, kind="auto", equipment_prefixes=None)`; resources `autocad://pid/symbols`, `autocad://standards/isa51`; `scripts/render_pid_catalog.py::render(output) -> dict`.

- [ ] **Step 1: Write the failing tests**

```python
# tests/test_pid_resources_prompt.py
from __future__ import annotations

import json

import pytest
import pytest_asyncio
from fastmcp import Client

import server

pytestmark = pytest.mark.asyncio


@pytest_asyncio.fixture
async def client(monkeypatch):
    monkeypatch.setenv("AUTOCAD_MCP_BACKEND", "ezdxf")
    async with Client(server.mcp) as connected:
        yield connected


async def test_tag_parse_tool(client):
    out = (await client.call_tool("pid_tag_parse", {"tag": "10-FIC-101A"})).structured_content
    assert out["valid"] is True and out["description"] == "Flow Indicating Controller"
    out = (
        await client.call_tool(
            "pid_tag_parse",
            {"tag": "Q-1", "kind": "equipment", "equipment_prefixes": {"Q": "quench"}},
        )
    ).structured_content
    assert out["equipment_kind"] == "quench"


async def test_resources_serve_the_catalogue_and_the_letter_tables(client):
    uris = {str(r.uri) for r in await client.list_resources()}
    assert {"autocad://pid/symbols", "autocad://standards/isa51"} <= uris
    symbols = json.loads((await client.read_resource("autocad://pid/symbols"))[0].text)
    assert symbols["catalog_version"] == "1" and any(
        s["symbol"] == "gate" for s in symbols["symbols"]
    )
    isa = json.loads((await client.read_resource("autocad://standards/isa51"))[0].text)
    assert isa["first_letters"]["F"] == "Flow" and "rules" in isa


async def test_prompt_walks_the_tool_workflow(client):
    prompt = await client.get_prompt(
        "prompt_pid_diagram", {"project_name": "Unit 7", "revision": "B"}
    )
    text = "\n".join(m.content.text for m in prompt.messages)
    for needle in (
        "drawing_plan",
        'layer_set_id="pid"',
        "pid_symbol_insert",
        "pid_line_draw",
        "pid_graph",
        "drawing_critique",
        "drawing_finalize",
        "pid_from_spec",
        "Unit 7",
        "Ø10",
    ):
        assert needle in text, needle
    assert "circle with triangle" not in text, "no hand-drawn symbols"


def test_catalog_contact_sheet_renders_every_symbol(tmp_path):
    pytest.importorskip("matplotlib")
    from scripts.render_pid_catalog import render

    result = render(tmp_path / "sheet.png")
    assert result["symbols"] >= 100 and result["bytes"] > 10_000
```

- [ ] **Step 2: Run to verify they fail**.

- [ ] **Step 3: Tool, resources, prompt**

SECTION 17 → `(9 tools)`; add:

```python
@cad_tool(
    summary="Parse an ISA-5.1 instrument tag or an equipment tag; explains every letter.",
    cost="read",
)
@mcp.tool(annotations={"title": "P&ID: Parse Tag", "readOnlyHint": True}, tags={"pid", "query"})
async def pid_tag_parse(
    tag: Annotated[str, "e.g. FIC-101, 10-PDT-203A, P-101A"],
    kind: Annotated[str, "auto | instrument | equipment"] = "auto",
    equipment_prefixes: Annotated[
        dict | None, "Replace the default equipment prefix map, e.g. {'Q': 'quench tower'}"
    ] = None,
    ctx: Context = None,
) -> dict:
    """ISA-5.1-2009 Table 4.1 as a grammar: first letter, modifier, readout and
    output functions, trailing high/low, loop number and suffix — with the
    standard's description ("Flow Indicating Controller") or the first
    offending letter. Equipment prefixes are not standardised, so the default
    map (P pump, V vessel, E exchanger, ...) can be replaced per call.
    """
    from engineering.pid.tags import parse_tag

    return parse_tag(tag, kind, equipment_prefixes)
```

Alias: `"pid_tag_parse": ToolAliases(acad=(), synonyms=("what does FIC mean", "isa 5.1 tag", "instrument tag letters", "decode the tag", "loop number"))`.

Resources (in the RESOURCES block):

```python
@mcp.resource(
    "autocad://pid/symbols",
    name="P&ID Symbol Catalogue",
    description="Every P&ID symbol pid_symbol_insert can place: families, variants, ports, parameters",
    mime_type="application/json",
    annotations={"readOnlyHint": True},
    tags={"pid"},
)
async def resource_pid_symbols() -> str:
    from engineering.pid.symbols import CATALOG_VERSION, list_symbols

    return json.dumps({"catalog_version": CATALOG_VERSION, "symbols": list_symbols()}, indent=2)


@mcp.resource(
    "autocad://standards/isa51",
    name="ISA-5.1 Identification Letters",
    description="ISA-5.1-2009 Table 4.1 letter tables, the tag grammar and its disambiguation rules",
    mime_type="application/json",
    annotations={"readOnlyHint": True},
    tags={"pid", "standards"},
)
async def resource_isa51() -> str:
    from engineering.pid.tags import describe_tables

    return json.dumps(describe_tables(), indent=2)
```

Replace the body of `prompt_pid_diagram` with:

```python
    return f"""You are creating a P&ID for '{project_name}' ({revision}) with the server's P&ID tools.
Never hand-draw a symbol from lines and circles: every valve, pump, vessel and instrument is a
catalogue block with ports, and every line is drawn port-to-port.

REFERENCE SIZES (symbol-local mm at A3/A1 paper scale): instrument bubble Ø10, valve body 8×4,
pump Ø8, grid 5. Keep equipment ≥ 40 mm apart so line numbers and tags have room.

WORKFLOW
1. drawing_plan(intent="{project_name} P&ID", sheet_size="A3", layer_set_id="pid")
2. drawing_apply_iso_layers("pid")
3. pid_symbol_list() — read the catalogue once; pid_tag_parse(tag) when unsure about ISA-5.1 letters
4. pid_symbol_insert(symbol, x, y, tag=...) for each item:
     equipment  tag P-101 / V-201 / E-301 (desc="Feed pump")
     valves     symbol=gate|globe|ball|... with actuator=diaphragm|piston|motor|solenoid|hand and fail=FO|FC|FL
     instruments symbol="instrument", type=discrete|dcs|computer|plc, location=field|primary|auxiliary|..., tag="FIC-101"
     vessels    params={{"width", "height", "nozzles": [{{"name": "N1", "side": "top", "fraction": 0.5}}]}}
   Each call returns the block's ports in WCS — use them, never guess coordinates.
5. pid_line_draw(from_={{"handle", "port"}}, to={{"handle", "port"}}, line_class=process_major|process_minor|
   utility|pneumatic|electric|hydraulic|capillary|data, size="100", service="P", spec="CS1")
   A bubble's radial port needs no name. Read `crossings` and `port_reuse` in the response.
6. pid_graph() — `dangling` must be empty and `stats.confidence_min` 1.0 for a drawing you made.
7. drawing_critique(focus=None) — must return [] (pid_dangling_line, pid_duplicate_tag,
   pid_incompatible_connection, pid_untagged_instrument, pid_illegal_tag, pid_unconnected_equipment
   are part of it).
8. pid_instrument_index() / pid_line_list() / pid_equipment_list() for the deliverables.
9. drawing_finalize(save_path=...) — the score is the objective quality metric.

ONE-CALL ALTERNATIVE: pid_from_spec(spec) draws the whole sheet in one transaction from
{{sheet, equipment[], valves[], instruments[], lines[], connectors[]}} and returns the graph and the
critique; use dry_run=true first to see the planned routes and crossings.

OFF-PAGE: pid_symbol_insert("offpage", direction="out"|"in", tag="TO P&ID-002", link="L-17"); two connectors
sharing a link are paired by pid_graph.
"""
```

Regenerate the inventory (now 8 resources); README snapshot `166 tools · 8 resources`.

- [ ] **Step 4: Contact-sheet script**

```python
# scripts/render_pid_catalog.py
"""Render every catalogue symbol on one labelled sheet (docs/assets/pid-catalog.png).

uv run --frozen python scripts/render_pid_catalog.py
"""

from __future__ import annotations

import argparse
import asyncio
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))

DEFAULT_OUTPUT = ROOT / "docs" / "assets" / "pid-catalog.png"
CELL = 80.0  # the tallest vessel spans 66 mm with its nozzle stubs
COLUMNS = 10


async def _render(output: Path) -> dict:
    from backends.ezdxf_backend import EzdxfBackend
    from engineering.layers import apply_layer_set
    from engineering.pid.insert import insert_symbol
    from engineering.pid.symbols import all_specs

    backend = EzdxfBackend()
    await backend.connect()
    try:
        await backend.drawing_new()
        await apply_layer_set(backend, "pid")
        specs = all_specs()
        for index, spec in enumerate(specs):
            col, row = index % COLUMNS, index // COLUMNS
            x, y = col * CELL, -row * CELL
            layer = "PROCESS-PIPING-MAIN" if spec.family == "marker" else None
            await insert_symbol(backend, spec, x, y, 0.0, 1.0, {}, layer)
            await backend.entity_create_text(
                spec.name.replace("PID_", ""),
                x - CELL / 2 + 2,
                y - CELL / 2 + 2,
                1.6,
                layer="TEXT-NOTES",
            )
        png = await backend.view_screenshot()
        output.parent.mkdir(parents=True, exist_ok=True)
        output.write_bytes(png)
        return {"output": str(output), "symbols": len(specs), "bytes": len(png)}
    finally:
        await backend.disconnect()


def render(output: Path) -> dict:
    return asyncio.run(_render(output))


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
    print(render(parser.parse_args().output))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
```

Run it and commit the PNG. (`scripts/` has no `__init__.py`; the test imports `scripts.render_pid_catalog` — add an empty `scripts/__init__.py` if the import fails, and keep it out of the wheel: check `pyproject.toml`'s hatch `include` list does not pick it up.)

- [ ] **Step 5: Run** — `uv run --frozen pytest tests/test_pid_resources_prompt.py tests/test_tool_inventory.py tests/test_release_consistency.py tests/test_discovery_aliases.py -v`.

- [ ] **Step 6: Commit**

```bash
git add server.py discovery/aliases.py docs/tool-inventory.json README.md scripts/render_pid_catalog.py docs/assets/pid-catalog.png tests/test_pid_resources_prompt.py
git commit -m "feat(pid): pid_tag_parse, catalogue and ISA-5.1 resources, prompt rewritten onto the tools"
```

---

### Task 20: Benchmark matrix v4 (`pid_roundtrip`) + three correctness checks

**Files:**
- Create: `benchmarks/tasks_v4.py`, `tests/test_benchmark_v4.py`
- Modify: `benchmarks/adapters/autocad_mcp_pro.py` (`_task_pid_roundtrip`), `benchmarks/run_competitors.py` and `benchmarks/render_matrix_chart.py` (import from `tasks_v4`), `benchmarks/correctness_suite.py` (+3 checks), `scripts/check_doc_numbers.py` (task-count pattern → v4), `CLAUDE.md`/`README.md`/`benchmarks/README.md` numbers (26 → 29 checks; 15 → 16 tasks)

**Interfaces:**
- Produces: `benchmarks.tasks_v4.NEW_TASKS_V4`, `TASKS_V4 = TASKS_V3 + NEW_TASKS_V4`, `MATRICES = {"v2", "v3", "v4"}`, `DEFAULT_MATRIX = "v4"`, `task_by_id`; correctness checks `pid_block_define_attdef_roundtrip`, `pid_tag_parse_fic`, `pid_graph_edge_count` under group `"P&ID"`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_benchmark_v4.py
from __future__ import annotations

from benchmarks.tasks_v3 import TASKS_V3
from benchmarks.tasks_v4 import DEFAULT_MATRIX, MATRICES, NEW_TASKS_V4, TASKS_V4, task_by_id


def test_v4_extends_v3_without_touching_it():
    assert TASKS_V4[: len(TASKS_V3)] == TASKS_V3
    assert [t.task_id for t in NEW_TASKS_V4] == ["pid_roundtrip"]
    assert MATRICES["v3"] == TASKS_V3 and MATRICES["v4"] == TASKS_V4 and DEFAULT_MATRIX == "v4"
    assert task_by_id("pid_roundtrip").category == "pid"


def test_the_adapter_implements_every_v4_task():
    from benchmarks.adapters.autocad_mcp_pro import AutoCADMCPProAdapter

    for task in TASKS_V4:
        assert hasattr(AutoCADMCPProAdapter, f"_task_{task.task_id}"), task.task_id


def test_correctness_suite_has_the_pid_checks():
    from benchmarks.correctness_suite import CHECKS

    for name in ("pid_block_define_attdef_roundtrip", "pid_tag_parse_fic", "pid_graph_edge_count"):
        assert CHECKS[name][1] == "P&ID"
    assert len(CHECKS) == 29
```

- [ ] **Step 2: Run to verify it fails** — ModuleNotFoundError.

- [ ] **Step 3: Write the matrix, the adapter task, the checks**

```python
# benchmarks/tasks_v4.py
"""The v4 task matrix: v3 plus the P&ID round trip (v1.6, track A).

``pid_roundtrip`` draws a five-item P&ID through the same code the tools call
and reads it back: the edge count, the absence of dangling ends and the
instrument index are each derived independently of the drawing code. The
published competitor reports were never asked this question; the chart shows
``not_run`` for them, not zero.
"""

from __future__ import annotations

from benchmarks.tasks_v2 import TASKS_V2, TaskSpec
from benchmarks.tasks_v3 import TASKS_V3

NEW_TASKS_V4: tuple[TaskSpec, ...] = (
    TaskSpec(
        "pid_roundtrip",
        "pid",
        "Draw a P&ID from a spec and read back a matching graph, index and line list",
        1.0,
    ),
)
TASKS_V4: tuple[TaskSpec, ...] = TASKS_V3 + NEW_TASKS_V4
MATRICES: dict[str, tuple[TaskSpec, ...]] = {"v2": TASKS_V2, "v3": TASKS_V3, "v4": TASKS_V4}
DEFAULT_MATRIX = "v4"


def task_by_id(task_id: str, matrix: str = DEFAULT_MATRIX) -> TaskSpec:
    for task in MATRICES[matrix]:
        if task.task_id == task_id:
            return task
    raise KeyError(f"{task_id} is not in matrix {matrix}")
```

Adapter method (in `benchmarks/adapters/autocad_mcp_pro.py`, after `_task_measure_from_handle`):

```python
async def _task_pid_roundtrip(self):
    """Five symbols, four lines, read back with nothing dangling."""
    from engineering.layers import apply_layer_set
    from engineering.pid.deliverables import instrument_index, line_list
    from engineering.pid.spec import EXAMPLE_SPEC, run_spec

    await apply_layer_set(self.backend, "pid")
    result = await run_spec(self.backend, EXAMPLE_SPEC)
    graph = result["graph"]
    index = instrument_index(graph)
    lines = line_list(graph)
    passed = (
        len(graph["nodes"]) == 5
        and len(graph["edges"]) == 4
        and graph["stats"]["dangling"] == 0
        and graph["stats"]["confidence_min"] == 1.0
        and result["critique"] == []
        and [r["tag"] for r in index] == ["FIC-101"]
        and index[0]["connected_to"] == "FCV-101"
        and sorted(r["line_number"] for r in lines if r["line_number"])
        == ["100-P-1001-CS1", "100-P-1001-CS1"]
    )
    return (
        passed,
        {
            "nodes": len(graph["nodes"]),
            "edges": len(graph["edges"]),
            "dangling": graph["stats"]["dangling"],
            "confidence_min": graph["stats"]["confidence_min"],
            "critique_issues": len(result["critique"]),
        },
        [],
    )
```

`run_competitors.py` and `render_matrix_chart.py`: change `from benchmarks.tasks_v3 import ...` to `from benchmarks.tasks_v4 import ...` (the chart renders `TASKS_V4` rows; competitor rows for the v3/v4 additions render `not_run` exactly as they do today for v3's five).

Correctness checks (append to `benchmarks/correctness_suite.py` before `CHECKS`):

```python
async def pid_block_define_attdef_roundtrip():
    b = await _b()
    await b.block_define(
        "PID_T",
        [{"type": "line", "x1": 0, "y1": 0, "x2": 8, "y2": 0}],
        [{"tag": "TAG", "x": 0, "y": 3, "height": 2.5}],
    )
    ref = await b.block_insert("PID_T", 5, 5, attributes={"TAG": "HV-1"})
    return await b.block_get_attributes(ref.handle) == {"TAG": "HV-1"}


async def pid_tag_parse_fic():
    from engineering.pid.tags import parse_tag

    return parse_tag("FIC-101")["description"] == "Flow Indicating Controller"


async def pid_graph_edge_count():
    from engineering.pid.spec import EXAMPLE_SPEC, run_spec

    b = await _b()
    result = await run_spec(b, EXAMPLE_SPEC)
    return len(result["graph"]["edges"]) == 4 and result["graph"]["stats"]["dangling"] == 0
```

and the three `CHECKS` entries with group `"P&ID"`.

- [ ] **Step 4: Doc numbers**

`uv run --frozen python scripts/check_doc_numbers.py` lists every drift. Update: README "26 deterministic headless checks" → 29 and the A/B table (see Task 21 for the table re-run); `benchmarks/README.md` "26 checks, ezdxf backend" → 29; `CLAUDE.md` "`correctness_suite.py` (26 checks)" → 29 and "`benchmarks/tasks_v3.py` is the current set (15 tasks; `--matrix v2` reproduces the v1.4 ten)" → "`benchmarks/tasks_v4.py` is the current set (16 tasks; `--matrix v3` / `--matrix v2` reproduce the earlier sets)"; in `scripts/check_doc_numbers.py` change the `v3_tasks` source to `from benchmarks.tasks_v4 import TASKS_V4` and the CLAUDE.md pattern to `r"the current set \((\d+) tasks"` (unchanged text shape).

- [ ] **Step 5: Run** — `uv run --frozen pytest tests/test_benchmark_v4.py tests/test_benchmark_v3.py tests/test_benchmark_v2.py -v` and `uv run --frozen python benchmarks/run_competitors.py --matrix v4 --server autocad-mcp-pro --task pid_roundtrip` → `pid_roundtrip: pass`.

- [ ] **Step 6: Commit**

```bash
git add benchmarks/tasks_v4.py benchmarks/adapters/autocad_mcp_pro.py benchmarks/run_competitors.py benchmarks/render_matrix_chart.py benchmarks/correctness_suite.py scripts/check_doc_numbers.py CLAUDE.md README.md benchmarks/README.md tests/test_benchmark_v4.py
git commit -m "bench: matrix v4 adds pid_roundtrip; correctness suite grows to 29 with three P&ID checks"
```

---

### Task 21: Live COM smoke, documentation, A/B re-run, full gate

**Files:**
- Create: `scripts/smoke_pid_com.py`
- Modify: `CLAUDE.md` (§17 P&ID, contracts, `TOOL_PACKS`, reader rules), `README.md` (What-you-get row, catalogue + showcase images, token table per pack, A/B table), `CHANGELOG.md` (`Unreleased` entry), `docs/superpowers/specs/2026-09-15-v1.6-pid-design.md` (status line → implemented)

- [ ] **Step 1: Live COM smoke script**

```python
# scripts/smoke_pid_com.py
"""Exercise the P&ID track once against the live AutoCAD on this machine.

Creates a NEW document (never touches the operator's open drawing), then runs
block_define -> pid_symbol_insert -> xdata -> pid_line_draw -> pid_graph and
prints the graph stats. Exit 2 when no AutoCAD is reachable.

    AUTOCAD_MCP_BACKEND=com uv run --frozen python scripts/smoke_pid_com.py
"""

from __future__ import annotations

import asyncio
import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))


async def main() -> int:
    try:
        from backends.com_backend import ComBackend
    except ImportError as exc:
        print(f"pywin32 not available: {exc}")
        return 2
    backend = ComBackend()
    try:
        await backend.connect()
    except Exception as exc:
        print(f"no live AutoCAD reachable: {exc}")
        return 2
    try:
        await backend.drawing_new()
        status = await backend.system_status()
        from engineering.layers import apply_layer_set
        from engineering.pid.spec import EXAMPLE_SPEC, run_spec

        await apply_layer_set(backend, "pid")
        result = await run_spec(backend, EXAMPLE_SPEC)
        got = await backend.entity_get_xdata(result["handles"]["P-101"], "ACADMCP_PID")
        report = {
            "autocad": status.get("autocad_version") or status.get("cad_progid"),
            "graph_stats": result["graph"]["stats"],
            "critique_issues": len(result["critique"]),
            "xdata_chunks": len(got["xdata"].get("ACADMCP_PID", [])),
        }
        print(json.dumps(report, indent=2))
        return 0 if result["graph"]["stats"]["dangling"] == 0 else 1
    finally:
        await backend.disconnect()


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))
```

Run it with AutoCAD open: `AUTOCAD_MCP_BACKEND=com uv run --frozen python scripts/smoke_pid_com.py`. Paste the printed report into the CHANGELOG entry. If it exits 2, the CHANGELOG says the COM paths are fake-tested only. If a COM call fails (a wrong ActiveX member name, a variant shape), fix the backend, re-run the fake tests, and re-run the smoke until it passes — that is the point of running it.

- [ ] **Step 2: CLAUDE.md**

Add to the tool sections list:

```
17. P&ID (9 tools, pack `pid`): `pid_symbol_list/insert` (ISO 10628-2 + ISA-5.1 catalogue authored in code, real blocks with TAG attributes, named ports, ACADMCP_PID XDATA), `pid_line_draw` (port-to-port orthogonal routing, ISA-5.1 line classes → layer/linetype/marker blocks, line numbers), `pid_tag_parse` (ISA-5.1 grammar), the reader `pid_graph` and its deliverables `pid_instrument_index/line_list/equipment_list`, and `pid_from_spec` (whole sheet, one transaction). Six `pid_*` critique focuses run under `focus=None` and inside `drawing_finalize`; they return nothing on a drawing without P&ID nodes.
```

Add to Key Conventions:

```
- **Generic contracts added in 1.6:** `block_define(name, entities, attdefs)` (typed primitives + ATTDEFs, both engines; `overwrite` replaces contents so INSERTs keep the name) and `entity_get/set_xdata` (typed by group code; 255-char strings, 16 KB per entity, enforced before writing).
- **P&ID reader rules:** `pid_graph` never modifies the drawing, reads geometry from the drawing (an INSERT's real rotation/scale) rather than the catalogue, and reports `source`/`confidence` per node (catalog 1.0, xdata 0.95, heuristic 0.6, inferred 0.3) — never raised by agreement between heuristics. Read `stats.confidence_min` before trusting a foreign drawing.
- **`TOOL_PACKS=all|core,pid`** advertises only the packs a client uses; `core` is always on; `system_about` reports `tool_packs`.
```

- [ ] **Step 3: README**

- "What you get" table: a row `| P&ID | catalogue blocks with ports and tags (ISO 10628-2 / ISA-5.1), port-to-port lines with ISA-5.1 classes and line numbers, `pid_graph` reads any P&ID back with confidence, instrument index / line list / equipment list, `pid_from_spec` one-call sheets |`.
- Under the hero image add the catalogue and P&ID showcase images (`docs/assets/pid-catalog.png`, `docs/assets/pid-showcase.png`) with a one-line caption each, the same `<sub>` style as the hero.
- Token table: measure `uv run --frozen python benchmarks/token_suite.py` once with `TOOL_PACKS=core` and once with the default and add a row `| TOOL_PACKS=core (full profile) | <N> | <tokens> |`.
- A/B table: run `uv run --frozen python benchmarks/compare_versions.py v1.5.1`; rewrite the rows as `v1.5.1 *(baseline)*` and `v1.6.0-dev *(this branch)*` with the printed numbers (expect `26 / 29` → `29 / 29`, three `miss → pass`), and update the two `v1.5.0`/`v1.5.1` regexes in `scripts/check_doc_numbers.py` to the new labels so the gate keeps matching.
- Snapshot line: `166 tools · 8 resources · 5 prompt templates · <collected> collected tests` — take `<collected>` from `uv run --frozen pytest --collect-only -q | tail -1` on this machine, and note in the CHANGELOG if it differs from the number CI reports on Linux (the 1369 vs 1363 drift found on 2026-09-15 predates this track; resolve it now by using the CI number if CI is green, else this machine's).

- [ ] **Step 4: CHANGELOG `Unreleased`**

Headings: **Added** (the nine tools with the measured refusals from the tests — the 255-char/16 KB XDATA limits, the stub refusal, the crossing count, the confidence ladder, the `*U1` fix), **Fixed** (`block_insert` with attributes lost its ATTRIBs headlessly — Task 1, with the reproduction), **Changed** (`TOOL_PACKS`, `PID_LAYERS` + `PROCESS-LINE-TEXT`, prompt rewrite, critique enum +6, benchmark v4, correctness 29), and the live COM smoke report verbatim.

- [ ] **Step 5: Full gate**

Run, in order, and fix anything red before committing:

```
uv run --frozen ruff check . && uv run --frozen ruff format --check .
uv run --frozen pytest -x -q
uv run --frozen python scripts/generate_tool_inventory.py --check
uv run --frozen python scripts/check_doc_numbers.py
uv run --frozen python benchmarks/compare_versions.py v1.5.1
```

Expected: ruff clean; pytest green (every new test file included); inventory unchanged; doc numbers agree; A/B `29 / 29` with zero regressions.

- [ ] **Step 6: Commit and mark the spec implemented**

```bash
git add scripts/smoke_pid_com.py CLAUDE.md README.md CHANGELOG.md scripts/check_doc_numbers.py docs/superpowers/specs/2026-09-15-v1.6-pid-design.md
git commit -m "docs(pid): track A shipped — CLAUDE.md, README, changelog with the live COM smoke record"
```

Track A is done when the gate in Step 5 is green and the roadmap's criteria 1 and 2 are demonstrated by `tests/test_pid_from_spec.py::test_finalize_scores_the_example_at_ninety_or_better` and `tests/test_pid_graph.py::test_foreign_blocks_classify_with_reduced_confidence_and_inferred_ports`.