feat(understand): drawing_understand - units, extents, clusters, layers, tags, rooms

A drawing somebody else made, read back as one report in which every
claim carries its evidence and a confidence; the drawing is never
modified.

- units.py: $INSUNITS against the unit the geometry implies (text
  heights, wall thickness, door swings, labelled room areas, overall
  size). The header is overruled only when the evidence outweighs it,
  and then with a warning that quotes the numbers. Robust extents grow
  from the quartile box of entity centres; what never joins is an
  outlier, named by handle.
- clusters.py: separate bodies of model-space content by raster,
  8-connectivity and box absorption - two copies of one plan are two
  clusters.
- describe.py: layers with drawn length and the vocabulary's meaning
  (name keyword, else the texts on the layer), equipment tags (one tag
  lettered twice beside its symbol merged, repeats flagged ambiguous),
  room labels in the wall-layer faces of engineering.arch.faces, text
  languages by character class, blocks, layouts, the title block.
- server.py opens SECTION 26 (Understanding & QA) with
  drawing_understand: core, read-only, tagged analysis/query. Alias
  record, inventory, README release snapshot 242, frozen group sizes
  (analysis 13).

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

README.md

@@ -27,8 +27,8 @@ Live through COM on Windows, or headless through ezdxf anywhere — one typed co
 
 </div>
 
-> **v1.5 release snapshot:** 241 tools · 8 resources · 5 prompt templates · 4516 collected tests.
+> **v1.5 release snapshot:** 242 tools · 8 resources · 5 prompt templates · 4516 collected tests.
-> 241 is the **registered** count; a default install advertises 236 over `tools/list`,
+> 242 is the **registered** count; a default install advertises 237 over `tools/list`,
 > because `ENABLE_3D` is unset. `system_about` is the runtime authority.
 
 ## Why this exists
@@ -122,7 +122,7 @@ Claude Desktop, Cursor, or any stdio MCP host. For HTTP: `autocad-mcp --transpor
 | Quality loop | `drawing_preflight` → `drawing_plan` → `drawing_critique` → `drawing_refine` → `drawing_finalize` (0–100 score) |
 | Delivery | `drawing_deliver`: DXF/PDF/PNG + SHA-256 manifest + reopen-parity checks |
 
-<sub>241 tools in 26 groups; <code>TOOL_PACKS=core</code> hides the nine <code>pid_*</code> tools, the 22 environment tools, the 14 mechanical tools and the 12 architectural tools (<code>TOOL_PACKS=core,mech</code> keeps the mechanical ones, <code>TOOL_PACKS=core,arch</code> the architectural ones) from a client that needs none of them. Plus 8 resources that cost nothing in the tool budget (<code>autocad://drawing/info</code>, <code>layers</code>, <code>blocks</code>, <code>entities/stats</code>, <code>entities/{layer_name}</code>, <code>system/status</code>, <code>pid/symbols</code>, <code>standards/isa51</code>) and 5 prompt templates.</sub>
+<sub>242 tools in 26 groups; <code>TOOL_PACKS=core</code> hides the nine <code>pid_*</code> tools, the 22 environment tools, the 14 mechanical tools and the 12 architectural tools (<code>TOOL_PACKS=core,mech</code> keeps the mechanical ones, <code>TOOL_PACKS=core,arch</code> the architectural ones) from a client that needs none of them. Plus 8 resources that cost nothing in the tool budget (<code>autocad://drawing/info</code>, <code>layers</code>, <code>blocks</code>, <code>entities/stats</code>, <code>entities/{layer_name}</code>, <code>system/status</code>, <code>pid/symbols</code>, <code>standards/isa51</code>) and 5 prompt templates.</sub>
 
 **Two rules worth knowing.** Every coordinate in and out of a tool is WCS on both engines — the one exception is TEXT `rotation`, which stays in the entity frame because a mirrored TEXT is mirror-imaged and no scalar angle expresses that. And never read vertices back and shoelace them: that loses **28.2%** of the area on a semicircular edge, silently. `analysis_measure_entity(handle)` reads the real geometry and states its own accuracy.
 

discovery/aliases.py

@@ -2465,6 +2465,35 @@ TOOL_ALIASES: dict[str, ToolAliases] = {
             "mimari plan",
         ),
     ),
+    # ── Understanding & QA (SECTION 26, track H group U) ────────────────────
+    # No AutoCAD command reads a foreign drawing back as a report, so `acad`
+    # is empty. UNITS stays with drawing_settings (it sets units; this reads
+    # what the geometry implies), and no synonym here says "layers", "blocks"
+    # or "how big", the words the golden layer_list / block_list /
+    # analysis_bounding_box queries lean on.
+    "drawing_understand": ToolAliases(
+        acad=(),
+        synonyms=(
+            "understand this drawing",
+            "read a foreign drawing",
+            "summarise a client drawing",
+            "drawing report",
+            "which unit is this drawing really in",
+            "wrong insunits",
+            "inches or millimetres",
+            "two copies of the plan",
+            "stray entity far away",
+            "what is on this p&id",
+            "birim",
+            "birimi ne",
+            "çizimi anla",
+            "cizimi anla",
+            "çizim raporu",
+            "cizim raporu",
+            "yabancı çizim",
+            "yabanci cizim",
+        ),
+    ),
 }
 
 

docs/tool-inventory.json

@@ -3,13 +3,13 @@
   "schema_version": 1,
   "package_version": "1.5.1",
   "totals": {
-    "tools": 241,
+    "tools": 242,
     "resources": 8,
     "prompts": 5,
     "groups": 26
   },
   "groups": {
-    "analysis": 12,
+    "analysis": 13,
     "architecture": 12,
     "batch": 3,
     "blocks": 9,
@@ -1161,6 +1161,20 @@
         "destructiveHint": false
       }
     },
+    {
+      "name": "drawing_understand",
+      "group": "analysis",
+      "cost": "read",
+      "summary": "Read a foreign drawing: units, extents, clusters, layers, tags, rooms, languages.",
+      "tags": [
+        "analysis",
+        "query"
+      ],
+      "annotations": {
+        "title": "Understand: Describe Drawing",
+        "readOnlyHint": true
+      }
+    },
     {
       "name": "drawing_undo",
       "group": "drawing",

engineering/understand/clusters.py

@@ -0,0 +1,194 @@
+"""Separate bodies of model-space content: sheets, plan copies, details.
+
+A foreign model space is often several drawings side by side - two copies of
+one plan, a detail beside it, a legend. Every reader after this one must know
+which body a tag or a room belongs to, or it matches a tag in one copy against
+the same tag in the other.
+
+The algorithm, in the order it runs:
+
+1. **Raster.** The box of the records is divided into square cells of
+   ``cell`` drawing units (default :data:`CELL_FRACTION` of its diagonal, so
+   the grid never exceeds about 50 x 50 cells). Every record marks the cells
+   its box covers.
+2. **Connect.** Occupied cells that touch, corners included, are one
+   component; a record belongs to the component of its cells. Two bodies stay
+   apart when an empty cell separates them - a gap of two cells is always
+   enough.
+3. **Absorb.** Components whose boxes intersect are merged, repeatedly: a tag
+   floating in the middle of a room lies inside the plan's box and belongs to
+   the plan, not to a cluster of its own.
+
+Ids are ``C1``, ``C2``, ... by entity count, largest first (ties left to right,
+then bottom to top). Outliers are the caller's to exclude: one entity thousands of
+kilometres away would otherwise set the cell size. Pure; the drawing is never touched.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Sequence
+
+from engineering.understand.snapshot import EntityRecord
+from engineering.understand.units import entity_box
+
+__all__ = ["CELL_FRACTION", "find_clusters"]
+
+#: Cell side as a fraction of the content's diagonal.
+CELL_FRACTION = 0.02
+#: Labels listed per cluster.
+LABELS_PER_CLUSTER = 5
+
+_TEXT_TYPES = frozenset({"TEXT", "MTEXT", "MULTILEADER"})
+
+
+def _intersect(a, b) -> bool:
+    return a[0] <= b[2] and b[0] <= a[2] and a[1] <= b[3] and b[1] <= a[3]
+
+
+def _merge(a, b):
+    return (min(a[0], b[0]), min(a[1], b[1]), max(a[2], b[2]), max(a[3], b[3]))
+
+
+def _root(parent: list[int], i: int) -> int:
+    """Union-find root with path halving."""
+    while parent[i] != i:
+        parent[i] = parent[parent[i]]
+        i = parent[i]
+    return i
+
+
+def _absorb(bodies: list[tuple[tuple, list[int]]]) -> list[tuple[tuple, list[int]]]:
+    """Merge bodies whose boxes intersect until none do.
+
+    One pass is a sweep over boxes sorted by their left edge (a pair can only
+    intersect while the next left edge is inside the current box) feeding a
+    union-find; a merged box can reach a body it did not touch before, so
+    passes repeat until one merges nothing.
+    """
+    while True:
+        order = sorted(range(len(bodies)), key=lambda i: bodies[i][0][0])
+        parent = list(range(len(bodies)))
+        joined = False
+        for n, i in enumerate(order):
+            box = bodies[i][0]
+            for j in order[n + 1 :]:
+                if bodies[j][0][0] > box[2]:
+                    break
+                ri, rj = _root(parent, i), _root(parent, j)
+                if ri != rj and _intersect(box, bodies[j][0]):
+                    parent[rj] = ri
+                    joined = True
+        if not joined:
+            return bodies
+        merged: dict[int, tuple[tuple, list[int]]] = {}
+        for i, (box, members) in enumerate(bodies):
+            r = _root(parent, i)
+            if r in merged:
+                merged[r] = (_merge(merged[r][0], box), merged[r][1] + members)
+            else:
+                merged[r] = (box, list(members))
+        bodies = list(merged.values())
+
+
+def find_clusters(
+    records: Sequence[EntityRecord],
+    *,
+    exclude: Iterable[str] = (),
+    cell: float | None = None,
+) -> tuple[list[dict], dict[str, str]]:
+    """``(clusters, membership)``: one row per body of content, and handle -> id.
+
+    A row is ``{"id", "box": [x0, y0, x1, y1], "size": [w, h], "entities",
+    "layers": [the three commonest], "labels": [the tallest texts]}``.
+    ``exclude`` names handles to leave out (the outliers). A record without a
+    box (no geometry the snapshot could read) belongs to no cluster.
+    """
+    skip = set(exclude)
+    items = [(rec, box) for rec in records if rec.handle not in skip and (box := entity_box(rec))]
+    if not items:
+        return [], {}
+    x0 = min(b[0] for _r, b in items)
+    y0 = min(b[1] for _r, b in items)
+    x1 = max(b[2] for _r, b in items)
+    y1 = max(b[3] for _r, b in items)
+    if cell is None:
+        diag = math.hypot(x1 - x0, y1 - y0)
+        cell = diag * CELL_FRACTION if diag > 0.0 else 1.0
+    if not cell > 0.0:
+        raise ValueError(f"cell: must be greater than zero, got {cell!r}")
+
+    def span(lo: float, hi: float, origin: float) -> range:
+        return range(
+            int(math.floor((lo - origin) / cell)), int(math.floor((hi - origin) / cell)) + 1
+        )
+
+    owner: dict[tuple[int, int], list[int]] = {}
+    first_cell: list[tuple[int, int]] = []
+    for k, (_rec, b) in enumerate(items):
+        cols, rows = span(b[0], b[2], x0), span(b[1], b[3], y0)
+        first_cell.append((cols[0], rows[0]))
+        for i in cols:
+            for j in rows:
+                owner.setdefault((i, j), []).append(k)
+
+    component: dict[tuple[int, int], int] = {}
+    count = 0
+    for start in owner:
+        if start in component:
+            continue
+        component[start] = count
+        stack = [start]
+        while stack:
+            ci, cj = stack.pop()
+            for di in (-1, 0, 1):
+                for dj in (-1, 0, 1):
+                    nxt = (ci + di, cj + dj)
+                    if nxt in owner and nxt not in component:
+                        component[nxt] = count
+                        stack.append(nxt)
+        count += 1
+
+    groups: dict[int, list[int]] = {}
+    for k in range(len(items)):
+        groups.setdefault(component[first_cell[k]], []).append(k)
+    bodies = []
+    for members in groups.values():
+        box = items[members[0]][1]
+        for k in members[1:]:
+            box = _merge(box, items[k][1])
+        bodies.append((box, members))
+    bodies = _absorb(bodies)
+
+    bodies.sort(key=lambda body: (-len(body[1]), body[0][0], body[0][1]))
+    clusters: list[dict] = []
+    membership: dict[str, str] = {}
+    for n, (box, members) in enumerate(bodies, start=1):
+        cid = f"C{n}"
+        layers: dict[str, int] = {}
+        texts = []
+        for k in members:
+            rec = items[k][0]
+            membership[rec.handle] = cid
+            layers[rec.layer] = layers.get(rec.layer, 0) + 1
+            if rec.type in _TEXT_TYPES and rec.text and rec.text.strip():
+                texts.append((-(rec.height or 0.0), rec.text.strip()))
+        labels: list[str] = []
+        for _h, text in sorted(texts):
+            if text not in labels:
+                labels.append(text)
+            if len(labels) == LABELS_PER_CLUSTER:
+                break
+        clusters.append(
+            {
+                "id": cid,
+                "box": list(box),
+                "size": [box[2] - box[0], box[3] - box[1]],
+                "entities": len(members),
+                "layers": [
+                    name for name, _c in sorted(layers.items(), key=lambda kv: (-kv[1], kv[0]))[:3]
+                ],
+                "labels": labels,
+            }
+        )
+    return clusters, membership

engineering/understand/describe.py

@@ -0,0 +1,463 @@
+"""drawing_understand: one read of a foreign drawing, every claim with its evidence.
+
+`describe` assembles the report from the pure readers - units and extents
+(`units`), bodies of content (`clusters`), and here: layers and what they
+carry, equipment tags, rooms, text languages, blocks, layouts and the title
+block. Each claim carries its evidence (what was measured or matched) and a
+confidence; nothing is corrected silently, and the drawing is never modified
+(the snapshot is a frozen copy).
+
+Confidences, in one place:
+
+* a layer name matching the vocabulary: `vocab.classify_layer`'s own (0.9 for
+  a direct keyword); the texts on an unnamed layer voting instead:
+  :data:`TEXT_VOTE_CONFIDENCE` when most of them agree, :data:`WEAK_VOTE_CONFIDENCE`
+  otherwise;
+* a tag read from a block attribute :data:`ATTRIBUTE_TAG_CONFIDENCE`, from a
+  text :data:`TEXT_TAG_CONFIDENCE`;
+* a room label that sits in a face of the wall layers
+  :data:`ROOM_FACE_CONFIDENCE`, a label alone :data:`ROOM_LABEL_CONFIDENCE`;
+* a title block whose name says so :data:`TITLE_NAME_CONFIDENCE`, one chosen by
+  its attribute count alone :data:`TITLE_ATTRIBUTE_CONFIDENCE`;
+* character classes are exact: a text either holds a Cyrillic letter or not.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from collections.abc import Sequence
+
+from engineering.arch.faces import Face, face_containing, planar_faces
+from engineering.pid.graph import ATTRIBUTE_TAGS, KEYWORDS
+from engineering.understand.clusters import find_clusters
+from engineering.understand.labels import parse_tag
+from engineering.understand.snapshot import EntityRecord, Snapshot, length_of
+from engineering.understand.units import infer_units, robust_extents, wall_segments
+from engineering.understand.vocab import classify_layer, room_label
+
+__all__ = [
+    "describe",
+    "find_rooms",
+    "prepare",
+    "tag_occurrences",
+    "text_language",
+]
+
+TEXT_VOTE_CONFIDENCE = 0.6
+WEAK_VOTE_CONFIDENCE = 0.4
+ATTRIBUTE_TAG_CONFIDENCE = 0.95
+TEXT_TAG_CONFIDENCE = 0.8
+ROOM_FACE_CONFIDENCE = 0.9
+ROOM_LABEL_CONFIDENCE = 0.6
+TITLE_NAME_CONFIDENCE = 0.9
+TITLE_ATTRIBUTE_CONFIDENCE = 0.6
+#: The face finder pairs every wall segment with every other; above this many
+#: the rooms are listed without faces and a warning says so.
+FACE_SEGMENT_CAP = 3000
+#: Endpoints closer than this fraction of the robust diagonal are one corner
+#: (1 mm on a 50 m plan drawn in millimetres).
+FACE_TOL_FRACTION = 2e-5
+#: The same tag lettered twice closer than this fraction of the robust diagonal
+#: (an attribute and a text beside one symbol) is one occurrence.
+TAG_MERGE_FRACTION = 0.01
+#: Rows listed for named blocks, most inserted first.
+BLOCK_ROW_CAP = 100
+#: Block-name words that mark a title block (EN / NL / DE / TR / RU).
+TITLE_WORDS = ("TITLE", "TITEL", "STEMPEL", "SCHRIFTFELD", "ANTET", "ШТАМП")
+
+_TEXT_TYPES = frozenset({"TEXT", "MTEXT", "MULTILEADER"})
+_TOKEN_RE = re.compile(r"[A-Z]+")
+_CYRILLIC = re.compile(r"[\u0400-\u04FF]")  # the Cyrillic block
+#: Letters only Turkish (of the five languages) writes; ç, ö and ü are shared
+#: with German and French and are not evidence on their own.
+_TURKISH = re.compile(r"[ĞğİıŞş]")
+_LATIN = re.compile(r"[A-Za-z\u00C0-\u024F]")  # ASCII and Latin-1 to Latin Extended-B
+
+
+def _anchor(rec: EntityRecord) -> tuple[float, float] | None:
+    if rec.points:
+        return (float(rec.points[0][0]), float(rec.points[0][1]))
+    if rec.bbox is not None:
+        b = rec.bbox
+        return ((b[0] + b[2]) / 2.0, (b[1] + b[3]) / 2.0)
+    return None
+
+
+def prepare(snap: Snapshot) -> dict:
+    """The shared first pass: model-space records, extents and outliers, the
+    records kept, clusters and membership. `describe` and `scale.scale_check`
+    both start here, so they agree on which entity is an outlier and which
+    cluster a tag sits in."""
+    model = [r for r in snap.records if r.space == "Model"]
+    extents = robust_extents(model)
+    outliers = {o["handle"] for o in extents["outliers"]}
+    kept = [r for r in model if r.handle not in outliers]
+    clusters, membership = find_clusters(kept)
+    robust = extents["robust"]
+    diag = math.hypot(robust[2] - robust[0], robust[3] - robust[1]) if robust else 0.0
+    return {
+        "model": model,
+        "extents": extents,
+        "kept": kept,
+        "clusters": clusters,
+        "membership": membership,
+        "diag": diag,
+    }
+
+
+def tag_occurrences(snap: Snapshot, *, prep: dict | None = None) -> list[dict]:
+    """Every equipment tag on the drawing, one row per occurrence.
+
+    A tag is read with `labels.parse_tag` from a TEXT / MTEXT / MULTILEADER,
+    or from an INSERT attribute named like a tag (`pid.graph.ATTRIBUTE_TAGS`).
+    Two readings of one tag in one space closer than
+    :data:`TAG_MERGE_FRACTION` of the diagonal are one occurrence (the
+    attribute's position and confidence win). Rows carry ``tag``, ``handle``,
+    ``at``, ``space``, ``layer``, ``cluster`` (model space only), ``source``
+    and ``confidence``.
+    """
+    prep = prep or prepare(snap)
+    radius = prep["diag"] * TAG_MERGE_FRACTION
+    found: list[dict] = []
+    for rec in snap.records:
+        at = _anchor(rec)
+        if at is None:
+            continue
+        readings = []
+        if rec.type in _TEXT_TYPES and rec.text:
+            readings.append((parse_tag(rec.text), "text", TEXT_TAG_CONFIDENCE))
+        elif rec.type == "INSERT":
+            for name, value in rec.attribs:
+                if name.upper() in ATTRIBUTE_TAGS and value:
+                    readings.append((parse_tag(value), "attribute", ATTRIBUTE_TAG_CONFIDENCE))
+        for tag, source, confidence in readings:
+            if not tag:
+                continue
+            found.append(
+                {
+                    "tag": tag,
+                    "handle": rec.handle,
+                    "at": [at[0], at[1]],
+                    "space": rec.space,
+                    "layer": rec.layer,
+                    "cluster": prep["membership"].get(rec.handle) if rec.space == "Model" else None,
+                    "source": source,
+                    "confidence": confidence,
+                }
+            )
+    found.sort(key=lambda o: (-o["confidence"], o["tag"], o["handle"]))
+    kept: list[dict] = []
+    for occ in found:
+        twin = next(
+            (
+                k
+                for k in kept
+                if k["tag"] == occ["tag"]
+                and k["space"] == occ["space"]
+                and math.dist(k["at"], occ["at"]) <= radius
+            ),
+            None,
+        )
+        if twin is None:
+            kept.append(occ)
+    kept.sort(key=lambda o: (o["tag"], o["space"], o["at"][0], o["at"][1]))
+    return kept
+
+
+def find_rooms(records: Sequence[EntityRecord], *, tol: float, membership: dict) -> dict:
+    """Room labels and the faces of the wall layers they sit in.
+
+    A label is any text `vocab.room_label` recognises. Wall layers are the
+    ones `vocab.classify_layer` files under ``architecture``; their straight
+    segments go through `engineering.arch.faces.planar_faces` (arcs are left
+    out and counted). ``labelled`` pairs each room row with its `Face` for a
+    caller that needs the geometry; ``rooms`` is JSON-ready.
+    """
+    labels = []
+    for rec in records:
+        if rec.type in _TEXT_TYPES and rec.text:
+            parsed = room_label(rec.text)
+            at = _anchor(rec)
+            if parsed and at is not None:
+                labels.append((rec, parsed, at))
+    segments, bulged = wall_segments(records)
+    faces: tuple[Face, ...] = ()
+    skipped = None
+    if len(segments) > FACE_SEGMENT_CAP:
+        skipped = (
+            f"{len(segments)} wall segments exceed the {FACE_SEGMENT_CAP}-segment cap of the "
+            "face finder; rooms are listed by label only"
+        )
+    elif segments:
+        faces = planar_faces(segments, tol=tol)
+    rooms: list[dict] = []
+    labelled: list[tuple[dict, Face]] = []
+    used: set[int] = set()
+    for rec, parsed, at in labels:
+        face = face_containing(faces, at) if faces else None
+        row = {
+            "number": parsed.get("number"),
+            "name": parsed.get("name"),
+            "language": parsed.get("language"),
+            "text": rec.text,
+            "handle": rec.handle,
+            "at": [at[0], at[1]],
+            "cluster": membership.get(rec.handle),
+            "face": None,
+            "source": "label",
+            "confidence": ROOM_LABEL_CONFIDENCE,
+        }
+        if face is not None:
+            used.add(id(face))
+            row["face"] = {
+                "area": face.area,
+                "polygon": [[p[0], p[1]] for p in face.loop],
+                "centroid": [face.centroid[0], face.centroid[1]],
+            }
+            row["source"] = "label+face"
+            row["confidence"] = ROOM_FACE_CONFIDENCE
+            labelled.append((row, face))
+        rooms.append(row)
+    rooms.sort(key=lambda r: (r["cluster"] or "", r["number"] or "", r["name"] or "", r["at"]))
+    return {
+        "rooms": rooms,
+        "labelled": labelled,
+        "faces": len(faces),
+        "faces_unlabelled": sum(1 for f in faces if id(f) not in used),
+        "wall_segments": len(segments),
+        "arcs_skipped": bulged,
+        "skipped": skipped,
+    }
+
+
+def text_language(text: str) -> str:
+    """``cyrillic`` | ``turkish`` | ``latin`` | ``none`` by character class, in
+    that precedence (a Russian label with a Latin tag in it is Cyrillic)."""
+    if _CYRILLIC.search(text):
+        return "cyrillic"
+    if _TURKISH.search(text):
+        return "turkish"
+    if _LATIN.search(text):
+        return "latin"
+    return "none"
+
+
+def _layers(snap: Snapshot, unit_mm: float | None) -> list[dict]:
+    counts: Counter = Counter()
+    lengths: dict[str, float] = {}
+    texts: dict[str, list[str]] = {}
+    for rec in snap.records:
+        counts[rec.layer] += 1
+        lengths[rec.layer] = lengths.get(rec.layer, 0.0) + length_of(rec)
+        if rec.type in _TEXT_TYPES and rec.text:
+            texts.setdefault(rec.layer, []).append(rec.text)
+    rows = []
+    for name in sorted(set(snap.layers) | set(counts)):
+        props = snap.layers.get(name, {})
+        c = classify_layer(name)
+        row = {
+            "name": name,
+            "entities": counts.get(name, 0),
+            "length": lengths.get(name, 0.0),
+            "length_m": lengths.get(name, 0.0) * unit_mm / 1000.0 if unit_mm else None,
+            "color": props.get("color"),
+            "linetype": props.get("linetype"),
+            "discipline": c.get("discipline", "unknown"),
+            "service": c.get("service", "unknown"),
+            "keyword": c.get("keyword"),
+            "language": c.get("language"),
+            "confidence": c.get("confidence", 0.0),
+            "evidence": f"layer name keyword {c.get('keyword')!r}" if c.get("keyword") else None,
+        }
+        if row["discipline"] == "unknown" and row["service"] == "unknown":
+            votes: Counter = Counter()
+            said = texts.get(name, [])
+            for text in said:
+                t = classify_layer(text)
+                if (
+                    t.get("discipline", "unknown") != "unknown"
+                    or t.get("service", "unknown") != "unknown"
+                ):
+                    votes[(t.get("discipline", "unknown"), t.get("service", "unknown"))] += 1
+            if votes:
+                (discipline, service), n = sorted(votes.items(), key=lambda kv: (-kv[1], kv[0]))[0]
+                row.update(
+                    discipline=discipline,
+                    service=service,
+                    confidence=(
+                        TEXT_VOTE_CONFIDENCE if n * 2 > len(said) else WEAK_VOTE_CONFIDENCE
+                    ),
+                    evidence=f"{n} of {len(said)} texts on the layer read as {service} / {discipline}",
+                )
+        rows.append(row)
+    rows.sort(key=lambda r: (-r["entities"], r["name"]))
+    return rows
+
+
+def _block_kind(name: str) -> str | None:
+    for token in _TOKEN_RE.findall(name.upper()):
+        kind = KEYWORDS.get(token)
+        if kind:
+            return kind
+    return None
+
+
+def _blocks(snap: Snapshot) -> dict:
+    inserts = [r for r in snap.records if r.type == "INSERT" and r.block]
+    named = Counter(r.block for r in inserts if not r.block.startswith("*"))
+    anonymous = Counter(r.block for r in inserts if r.block.startswith("*"))
+    rows = [
+        {
+            "name": name,
+            "inserts": n,
+            "kind": _block_kind(name),
+            "discipline": classify_layer(name).get("discipline", "unknown"),
+        }
+        for name, n in sorted(named.items(), key=lambda kv: (-kv[1], kv[0]))
+    ]
+    kinds = Counter(row["kind"] for row in rows if row["kind"])
+    return {
+        "inserts": len(inserts),
+        "named": rows[:BLOCK_ROW_CAP],
+        "named_total": len(rows),
+        "anonymous": {"names": len(anonymous), "inserts": sum(anonymous.values())},
+        "kinds": dict(sorted(kinds.items())),
+    }
+
+
+def _title_block(snap: Snapshot) -> dict:
+    best = None
+    for rec in snap.records:
+        if rec.type != "INSERT" or len(rec.attribs) < 3:
+            continue
+        upper = (rec.block or "").upper()
+        named = any(word in upper for word in TITLE_WORDS)
+        key = (named, rec.space != "Model", len(rec.attribs))
+        if best is None or key > best[0]:
+            best = (key, rec, named)
+    if best is None:
+        return {"found": False, "reason": "no block reference with three or more attributes"}
+    _key, rec, named = best
+    return {
+        "found": True,
+        "handle": rec.handle,
+        "block": rec.block,
+        "space": rec.space,
+        "attributes": {tag: value for tag, value in rec.attribs},
+        "confidence": TITLE_NAME_CONFIDENCE if named else TITLE_ATTRIBUTE_CONFIDENCE,
+        "evidence": (
+            f"block name {rec.block!r} reads as a title block"
+            if named
+            else f"the block reference with the most attributes ({len(rec.attribs)})"
+        ),
+    }
+
+
+def _languages(snap: Snapshot, layer_rows: list[dict]) -> dict:
+    by_class: Counter = Counter()
+    samples: dict[str, list[str]] = {}
+    for rec in snap.records:
+        if rec.type in _TEXT_TYPES and rec.text:
+            lang = text_language(rec.text)
+            by_class[lang] += 1
+            if len(samples.setdefault(lang, [])) < 3:
+                samples[lang].append(rec.handle)
+    total = sum(by_class.values())
+    layer_langs = Counter(row["language"] for row in layer_rows if row.get("language"))
+    return {
+        "texts": total,
+        "by_class": {k: by_class.get(k, 0) for k in ("latin", "turkish", "cyrillic", "none")},
+        "share": {
+            k: (by_class.get(k, 0) / total if total else 0.0)
+            for k in ("latin", "turkish", "cyrillic", "none")
+        },
+        "samples": samples,
+        "layer_name_languages": dict(sorted(layer_langs.items())),
+        "confidence": 1.0,
+    }
+
+
+def describe(snap: Snapshot) -> dict:
+    """The whole report; see the module docstring for the confidences."""
+    prep = prepare(snap)
+    warnings: list[str] = []
+    tol = prep["diag"] * FACE_TOL_FRACTION if prep["diag"] > 0 else 1.0
+    rooms = find_rooms(prep["kept"], tol=tol, membership=prep["membership"])
+    units = infer_units(
+        snap,
+        records=prep["kept"],
+        room_areas=[row["face"]["area"] for row, _face in rooms["labelled"]],
+    )
+    if units["warning"]:
+        warnings.append(units["warning"])
+    extents = dict(prep["extents"])
+    extents["declared"] = (
+        {"min": list(snap.extmin), "max": list(snap.extmax)}
+        if snap.extmin is not None and snap.extmax is not None
+        else None
+    )
+    if extents["outliers"]:
+        handles = ", ".join(o["handle"] for o in extents["outliers"][:5])
+        stretch = extents["stretch"]
+        warnings.append(
+            f"{len(extents['outliers'])} entit{'y' if len(extents['outliers']) == 1 else 'ies'} "
+            f"far outside the content stretch the extents"
+            + (f" {stretch:.3g}x" if stretch else "")
+            + f": {handles}"
+        )
+    if rooms["skipped"]:
+        warnings.append(rooms["skipped"])
+
+    occurrences = tag_occurrences(snap, prep=prep)
+    by_tag: dict[str, list[dict]] = {}
+    for occ in occurrences:
+        by_tag.setdefault(occ["tag"], []).append(occ)
+    tags = [
+        {
+            "tag": tag,
+            "count": len(rows),
+            "ambiguous": len(rows) > 1,
+            "confidence": max(r["confidence"] for r in rows),
+            "occurrences": [
+                {k: r[k] for k in ("handle", "at", "space", "cluster", "layer", "source")}
+                for r in rows
+            ],
+        }
+        for tag, rows in sorted(by_tag.items())
+    ]
+    repeated = [t["tag"] for t in tags if t["ambiguous"]]
+    if repeated:
+        warnings.append(
+            f"{len(repeated)} tag(s) appear more than once (plan copies, legends, second "
+            f"sheets): {', '.join(repeated[:5])}"
+        )
+
+    layer_rows = _layers(snap, units["mm_per_unit"])
+    layout_names = list(snap.layouts)
+    if "Model" not in layout_names:
+        layout_names.insert(0, "Model")
+    space_counts = Counter(r.space for r in snap.records)
+    return {
+        "source": snap.source,
+        "entities": len(snap.records),
+        "units": units,
+        "extents": extents,
+        "clusters": prep["clusters"],
+        "layers": layer_rows,
+        "equipment_tags": tags,
+        "rooms": rooms["rooms"],
+        "room_faces": {
+            "faces": rooms["faces"],
+            "unlabelled": rooms["faces_unlabelled"],
+            "wall_segments": rooms["wall_segments"],
+            "arcs_skipped": rooms["arcs_skipped"],
+            "tolerance": tol,
+        },
+        "languages": _languages(snap, layer_rows),
+        "blocks": _blocks(snap),
+        "layouts": [{"name": n, "entities": space_counts.get(n, 0)} for n in layout_names],
+        "title_block": _title_block(snap),
+        "warnings": warnings,
+    }

engineering/understand/units.py

@@ -0,0 +1,399 @@
+"""Declared versus inferred drawing units, and extents that one stray entity cannot stretch.
+
+`$INSUNITS` is a claim the drawing makes about itself, and a foreign drawing
+can make it wrongly: a layout that declares inches over millimetre geometry
+reads 25.4 times too large if the header is believed. This module never corrects
+the claim silently. It measures what the geometry implies and reports both,
+with the numbers that decided it.
+
+**Evidence.** Each item is one median measured in drawing units and the band a
+real drawing puts it in, in metres. A candidate unit is *plausible* for an item
+when the measurement, converted by that unit, lands in the band. An item that
+every candidate or no candidate satisfies says nothing and is dropped as
+inconclusive.
+
+========================  ======================  ======  ====================================
+item                      band                    weight  basis
+========================  ======================  ======  ====================================
+``room_area``             1 m² … 5 000 m²         1.0     a labelled room's face (this reader's
+                                                          heuristic)
+``wall_thickness``        0.05 m … 1.0 m          1.0     nearest parallel wall line (heuristic)
+``door_leaf``             0.5 m … 1.5 m           1.0     radius of a quarter-circle arc, a door
+                                                          swing (heuristic)
+``text_height``           1.8 mm … 4.0 m          0.5     ISO 3098-0 lettering heights 1.8-20 mm
+                                                          at ISO 5455 scales 1:1 to 1:200 (the
+                                                          1:200 ceiling is this reader's choice
+                                                          for plant drawings)
+``overall_size``          0.01 m … 2 000 m        0.25    the larger side of the robust extents
+                                                          (heuristic: a plant or a building)
+========================  ======================  ======  ====================================
+
+**Decision.** A candidate scores the weights of the items it is plausible for;
+the header is evidence too and adds :data:`HEADER_WEIGHT` to the declared unit.
+The highest score wins and a tie goes to the declared unit, then to the order of
+:data:`PREFERENCE`. So the header is overruled only when the geometry
+outweighs it - one weak item (the overall size) never does.
+
+**Extents.** The body of the drawing is grown from its middle: the seed is
+the quartile box of the entity centres (Q1..Q3 on each axis), and every
+entity whose box lies within :data:`OUTLIER_REACH` body diagonals of the body
+joins it, pass after pass, until a pass adds nothing. What never joins is an
+outlier - an entity farther from everything else than the drawing is large.
+The robust extents are the body's box. This is this reader's heuristic, not
+a statistical standard: a per-axis fence on centres (Tukey's) flags the edge
+walls of a plan whose centres crowd its middle, and a quantile range is
+dragged by the outlier itself in a small drawing. Fewer than four entities
+have no outliers.
+
+Pure: records in, dicts out. The drawing is never touched.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from collections.abc import Iterable, Sequence
+
+from ezdxf import units as ezdxf_units
+
+from engineering.understand.snapshot import EntityRecord, Snapshot
+from engineering.understand.vocab import classify_layer
+
+__all__ = [
+    "BANDS",
+    "CANDIDATES",
+    "HEADER_WEIGHT",
+    "MM_PER_UNIT",
+    "PREFERENCE",
+    "entity_box",
+    "infer_units",
+    "robust_extents",
+    "wall_segments",
+]
+
+#: Millimetres per drawing unit, exact by definition: the SI prefixes, and the
+#: inch (25.4 mm) and foot (304.8 mm) of the 1959 international yard and pound
+#: agreement. ezdxf's own ``METER_FACTOR`` is rounded (39.37007874 in/m), so it
+#: is not used for conversion.
+MM_PER_UNIT: dict[str, float] = {"mm": 1.0, "cm": 10.0, "m": 1000.0, "in": 25.4, "ft": 304.8}
+CANDIDATES: tuple[str, ...] = ("mm", "cm", "m", "in", "ft")
+#: Tie-break after the declared unit.
+PREFERENCE: tuple[str, ...] = ("mm", "m", "cm", "in", "ft")
+#: What the header's own claim weighs against the geometry.
+HEADER_WEIGHT = 0.5
+#: (low, high, weight, power): the band in metres (m² for power 2).
+BANDS: dict[str, tuple[float, float, float, int]] = {
+    "room_area": (1.0, 5000.0, 1.0, 2),
+    "wall_thickness": (0.05, 1.0, 1.0, 1),
+    "door_leaf": (0.5, 1.5, 1.0, 1),
+    "text_height": (0.0018, 4.0, 0.5, 1),
+    "overall_size": (0.01, 2000.0, 0.25, 1),
+}
+#: How far (in body diagonals) an entity may lie from the body and still join it.
+OUTLIER_REACH = 1.0
+#: A door swing is a quarter circle; the sweep may be drawn a little off.
+DOOR_SWEEP = (85.0, 95.0)
+#: Wall-thickness pairing reads at most this many wall segments.
+WALL_SEGMENT_CAP = 3000
+
+_TEXT_TYPES = frozenset({"TEXT", "MTEXT"})
+_POLY_TYPES = frozenset({"LWPOLYLINE", "POLYLINE"})
+
+
+def entity_box(rec: EntityRecord) -> tuple[float, float, float, float] | None:
+    """The record's WCS box: its own ``bbox``, else its points (a circle or arc
+    grown by its radius about its centre), else None."""
+    if rec.bbox is not None:
+        return tuple(float(v) for v in rec.bbox)
+    if not rec.points:
+        return None
+    xs = [float(p[0]) for p in rec.points]
+    ys = [float(p[1]) for p in rec.points]
+    grow = float(rec.radius) if rec.type in ("CIRCLE", "ARC") and rec.radius else 0.0
+    return (min(xs) - grow, min(ys) - grow, max(xs) + grow, max(ys) + grow)
+
+
+def _union(boxes: Iterable[tuple[float, float, float, float]]):
+    boxes = list(boxes)
+    if not boxes:
+        return None
+    return (
+        min(b[0] for b in boxes),
+        min(b[1] for b in boxes),
+        max(b[2] for b in boxes),
+        max(b[3] for b in boxes),
+    )
+
+
+def _diag(box) -> float:
+    return math.hypot(box[2] - box[0], box[3] - box[1]) if box else 0.0
+
+
+def _box_gap(a, b) -> float:
+    """Distance between two boxes; 0 when they touch or overlap."""
+    dx = max(a[0] - b[2], b[0] - a[2], 0.0)
+    dy = max(a[1] - b[3], b[1] - a[3], 0.0)
+    return math.hypot(dx, dy)
+
+
+def _grow_body(boxes: Sequence[tuple[float, float, float, float]]) -> set[int]:
+    """Indices of the boxes that never join the body grown from the centre."""
+    if len(boxes) < 4:
+        return set()
+    xs = [(b[0] + b[2]) / 2.0 for b in boxes]
+    ys = [(b[1] + b[3]) / 2.0 for b in boxes]
+    qx = statistics.quantiles(xs, n=4, method="inclusive")
+    qy = statistics.quantiles(ys, n=4, method="inclusive")
+    body = (qx[0], qy[0], qx[2], qy[2])
+    floor = statistics.median(_diag(b) for b in boxes)
+    pending = set(range(len(boxes)))
+    while pending:
+        reach = OUTLIER_REACH * max(_diag(body), floor)
+        joined = [i for i in pending if _box_gap(boxes[i], body) <= reach]
+        if not joined:
+            break
+        for i in joined:
+            body = _union([body, boxes[i]])
+        pending.difference_update(joined)
+    return pending
+
+
+def _distance_to_box(x: float, y: float, box) -> float:
+    dx = max(box[0] - x, 0.0, x - box[2])
+    dy = max(box[1] - y, 0.0, y - box[3])
+    return math.hypot(dx, dy)
+
+
+def robust_extents(records: Sequence[EntityRecord]) -> dict:
+    """Computed and robust extents of ``records`` and the outliers between them.
+
+    ``outliers`` are sorted farthest first, each with its handle, type, layer,
+    centre and its distance from the robust box. ``stretch`` is the computed
+    diagonal over the robust one (None when the robust box is a point).
+    """
+    items = [(rec, box) for rec in records if (box := entity_box(rec)) is not None]
+    centres = [((b[0] + b[2]) / 2.0, (b[1] + b[3]) / 2.0) for _rec, b in items]
+    skip = _grow_body([b for _rec, b in items])
+    outside = sorted(skip)
+    computed = _union(b for _rec, b in items)
+    robust = _union(b for i, (_rec, b) in enumerate(items) if i not in skip)
+    outliers = []
+    for i in outside:
+        rec, _box = items[i]
+        cx, cy = centres[i]
+        outliers.append(
+            {
+                "handle": rec.handle,
+                "type": rec.type,
+                "layer": rec.layer,
+                "at": [cx, cy],
+                "distance": _distance_to_box(cx, cy, robust) if robust else None,
+                "confidence": 0.9,
+            }
+        )
+    outliers.sort(key=lambda o: (-(o["distance"] or 0.0), o["handle"]))
+    robust_diag = _diag(robust)
+    return {
+        "computed": list(computed) if computed else None,
+        "robust": list(robust) if robust else None,
+        "outliers": outliers,
+        "stretch": (_diag(computed) / robust_diag) if robust_diag > 0.0 else None,
+        "method": (
+            "body grown from the quartile box of entity centres; an entity farther from it "
+            f"than {OUTLIER_REACH:g} body diagonal(s) never joins and is an outlier"
+        ),
+    }
+
+
+def wall_segments(
+    records: Sequence[EntityRecord], *, is_wall=None
+) -> tuple[list[tuple[tuple[float, float], tuple[float, float]]], int]:
+    """Straight segments of LINE and polyline records on wall layers, plus the
+    number of bulged (arc) polyline segments left out.
+
+    ``is_wall(layer)`` defaults to `vocab.classify_layer` naming the
+    ``architecture`` discipline.
+    """
+    cache: dict[str, bool] = {}
+
+    def wall(layer: str) -> bool:
+        if layer not in cache:
+            if is_wall is not None:
+                cache[layer] = bool(is_wall(layer))
+            else:
+                cache[layer] = classify_layer(layer).get("discipline") == "architecture"
+        return cache[layer]
+
+    segments: list[tuple[tuple[float, float], tuple[float, float]]] = []
+    bulged = 0
+    for rec in records:
+        if not wall(rec.layer):
+            continue
+        if rec.type == "LINE" and len(rec.points) >= 2:
+            segments.append((tuple(rec.points[0]), tuple(rec.points[1])))
+        elif rec.type in _POLY_TYPES and len(rec.points) >= 2:
+            pts = list(rec.points)
+            count = len(pts) if rec.closed else len(pts) - 1
+            for i in range(count):
+                a, b = pts[i], pts[(i + 1) % len(pts)]
+                bulge = rec.bulges[i] if i < len(rec.bulges) else 0.0
+                if abs(bulge) > 1e-12:
+                    bulged += 1
+                    continue
+                if a != b:
+                    segments.append((tuple(a), tuple(b)))
+    return segments, bulged
+
+
+def _wall_thickness(segments) -> tuple[float | None, int]:
+    """Median distance from an axis-parallel wall segment to its nearest parallel
+    neighbour on either side that overlaps it; (None, 0) without a pair.
+
+    Both sides, because the inner face of a double-line wall has the room on
+    one side and its own outer face on the other: looking one way only reads
+    half the faces as room widths and the median lands on neither."""
+    horizontal: list[tuple[float, float, float]] = []  # (y, x0, x1)
+    vertical: list[tuple[float, float, float]] = []  # (x, y0, y1)
+    for (ax, ay), (bx, by) in segments[:WALL_SEGMENT_CAP]:
+        length = math.hypot(bx - ax, by - ay)
+        if length <= 0.0:
+            continue
+        if abs(by - ay) <= 1e-9 * length:
+            horizontal.append((ay, min(ax, bx), max(ax, bx)))
+        elif abs(bx - ax) <= 1e-9 * length:
+            vertical.append((ax, min(ay, by), max(ay, by)))
+    gaps: list[float] = []
+    for group in (horizontal, vertical):
+        group.sort()
+        for i, (c, lo, hi) in enumerate(group):
+            best = None
+            for step in (1, -1):
+                j = i + step
+                while 0 <= j < len(group):
+                    c2, lo2, hi2 = group[j]
+                    d = abs(c2 - c)
+                    if best is not None and d >= best:
+                        break
+                    if d > 0.0 and lo2 < hi and lo < hi2:
+                        best = d
+                    j += step
+            if best is not None:
+                gaps.append(best)
+    if not gaps:
+        return None, 0
+    return statistics.median(gaps), len(gaps)
+
+
+def _declared(code: int) -> dict:
+    try:
+        name = ezdxf_units.decode(int(code))
+        label = ezdxf_units.unit_name(int(code))
+    except (IndexError, ValueError, TypeError):
+        name, label = None, None
+    return {"code": int(code), "name": name, "label": label or "Unitless"}
+
+
+def infer_units(
+    snap: Snapshot,
+    *,
+    records: Sequence[EntityRecord] | None = None,
+    room_areas: Sequence[float] = (),
+) -> dict:
+    """The unit the geometry implies, against the one ``$INSUNITS`` declares.
+
+    ``records`` defaults to the snapshot's model-space records; pass the ones
+    left after the outliers are removed. ``room_areas`` are labelled room faces
+    in square drawing units. Every item of ``evidence`` carries its median,
+    its sample count, what it is in metres under each candidate, the
+    candidates it is plausible for and whether it was informative.
+    """
+    recs = [r for r in snap.records if r.space == "Model"] if records is None else list(records)
+    measured: dict[str, tuple[float, int]] = {}
+
+    heights = [float(r.height) for r in recs if r.type in _TEXT_TYPES and r.height and r.height > 0]
+    if heights:
+        measured["text_height"] = (statistics.median(heights), len(heights))
+    radii = []
+    for r in recs:
+        if r.type == "ARC" and r.radius and r.angles:
+            sweep = (float(r.angles[1]) - float(r.angles[0])) % 360.0
+            if DOOR_SWEEP[0] <= sweep <= DOOR_SWEEP[1]:
+                radii.append(float(r.radius))
+    if radii:
+        measured["door_leaf"] = (statistics.median(radii), len(radii))
+    thickness, pairs = _wall_thickness(wall_segments(recs)[0])
+    if thickness is not None:
+        measured["wall_thickness"] = (thickness, pairs)
+    areas = [float(a) for a in room_areas if a and a > 0]
+    if areas:
+        measured["room_area"] = (statistics.median(areas), len(areas))
+    box = robust_extents(recs)["robust"]
+    if box:
+        side = max(box[2] - box[0], box[3] - box[1])
+        if side > 0:
+            measured["overall_size"] = (side, len(recs))
+
+    evidence = []
+    for kind, (value, count) in measured.items():
+        low, high, weight, power = BANDS[kind]
+        physical = {u: value * (MM_PER_UNIT[u] / 1000.0) ** power for u in CANDIDATES}
+        plausible = [u for u in CANDIDATES if low <= physical[u] <= high]
+        evidence.append(
+            {
+                "kind": kind,
+                "value": value,
+                "count": count,
+                "band": [low, high],
+                "band_unit": "m2" if power == 2 else "m",
+                "weight": weight,
+                "as": physical,
+                "plausible": plausible,
+                "informative": 0 < len(plausible) < len(CANDIDATES),
+            }
+        )
+
+    declared = _declared(snap.insunits)
+    name = declared["name"]
+    informative = [e for e in evidence if e["informative"]]
+    scores = {u: sum(e["weight"] for e in informative if u in e["plausible"]) for u in CANDIDATES}
+    if name in scores:
+        scores[name] += HEADER_WEIGHT
+    if informative:
+        best = max(scores.values())
+        order = ([name] if name in scores else []) + [u for u in PREFERENCE if u != name]
+        inferred = next(u for u in order if scores[u] == best)
+        total = sum(e["weight"] for e in informative) + (HEADER_WEIGHT if name in scores else 0.0)
+        confidence = round(0.9 * scores[inferred] / total, 2)
+    elif name in MM_PER_UNIT:
+        inferred, confidence = name, 0.4
+    else:
+        inferred, confidence = None, 0.0
+
+    warning = None
+    if inferred is not None and inferred != name:
+        support = [e for e in informative if inferred in e["plausible"]]
+        detail = "; ".join(
+            f"{e['kind']} {e['value']:g} = {e['as'][inferred]:.4g} {e['band_unit']} as {inferred}"
+            + (f", {e['as'][name]:.4g} {e['band_unit']} as {name}" if name in MM_PER_UNIT else "")
+            for e in support
+        )
+        warning = (
+            f"INSUNITS declares {declared['label']} ({declared['code']}) but the geometry reads "
+            f"as {inferred}: {detail}. Lengths are measured in {inferred}; the header is not "
+            "changed."
+        )
+    elif inferred is None:
+        warning = (
+            f"INSUNITS declares {declared['label']} ({declared['code']}) and no measurement "
+            "settles the unit; lengths stay in drawing units."
+        )
+    return {
+        "declared": declared,
+        "inferred": inferred,
+        "mm_per_unit": MM_PER_UNIT.get(inferred) if inferred else None,
+        "agree": inferred is not None and inferred == name,
+        "confidence": confidence,
+        "scores": scores,
+        "evidence": evidence,
+        "warning": warning,
+    }

server.py

@@ -10554,6 +10554,80 @@ async def arch_plan_from_spec(
         raise ToolError(str(exc)) from exc
 
 
+# ---------------------------------------------------------------------------
+# ── SECTION 26: Understanding & QA (1 tool) ─────────────────────────────────
+# ---------------------------------------------------------------------------
+
+
+@cad_tool(
+    summary="Read a foreign drawing: units, extents, clusters, layers, tags, rooms, languages.",
+    cost="read",
+)
+@mcp.tool(
+    annotations={"title": "Understand: Describe Drawing", "readOnlyHint": True},
+    tags={"analysis", "query"},
+)
+async def drawing_understand(
+    path: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="DXF file to read (a DWG only on a live seat); omitted: the current "
+            "document.",
+        ),
+    ] = None,
+    ctx: Context = None,
+) -> dict:
+    """One report on a drawing somebody else made, every claim with its evidence
+    and a confidence. Never modifies the drawing: a file is read as it is, and
+    the current document through a snapshot (headless: the document in memory;
+    live: a `Document.Export` DXF copy in a temporary folder, deleted after).
+    An xref's own entities are not read - the host drawing is.
+
+    - `units`: `$INSUNITS` as declared against the unit the geometry implies
+      (text heights, wall thickness, door swings, labelled room areas, overall
+      size - each item with its median and its value under every candidate
+      unit). A disagreement is a warning with the numbers, never a silent
+      correction.
+    - `extents`: declared, computed and robust boxes and the `outliers` that
+      stretch them, farthest first, by handle.
+    - `clusters`: separate bodies of model-space content (plan copies, sheets,
+      details), each with its box, entity count, commonest layers and tallest
+      labels.
+    - `layers`: entity count, drawn length (and metres in the inferred unit)
+      and the discipline / service each most likely carries - the vocabulary's
+      confidence (0.9) for a name keyword, 0.6 when most texts on the layer
+      agree, 0.4 when fewer do.
+    - `equipment_tags` (a tag found more than once is `ambiguous`), `rooms`
+      (room labels in five languages, each with the wall-layer face it sits in
+      and its measured area), `languages` (Latin / Turkish / Cyrillic character
+      classes), `blocks` (named / anonymous, kinds by name), `layouts`,
+      `title_block` and `warnings`.
+
+    Refused before anything is read: a `path` that does not exist, a DXF over
+    `MAX_DXF_BYTES` (the refusal names the size and the variable), and a file
+    the engine cannot parse (a DWG headlessly: ezdxf reads DXF only).
+    """
+    import asyncio
+
+    from ezdxf.lldxf.const import DXFError
+
+    from engineering.understand.describe import describe
+    from engineering.understand.snapshot import take_snapshot
+
+    target = None
+    if path:
+        target = validate_path(path)
+        if not target.is_file():
+            raise ToolError(f"path: no such file {str(target)!r}")
+    await ctx.info(f"drawing_understand: {target or 'current document'}")
+    try:
+        snap = await take_snapshot(_backend(ctx), str(target) if target else None)
+    except (ValueError, OSError, RuntimeError, DXFError) as exc:
+        raise ToolError(str(exc)) from exc
+    return await asyncio.to_thread(describe, snap)
+
+
 # ---------------------------------------------------------------------------
 # ── RESOURCES ───────────────────────────────────────────────────────────────
 # ---------------------------------------------------------------------------

tests/test_tool_registry.py

@@ -495,7 +495,7 @@ async def test_tool_groups_is_byte_identical_to_the_source_declared_grouping():
 
 
 async def test_tool_group_sizes_are_unchanged():
-    """Frozen snapshot of the surface (241 tools, 26 groups).
+    """Frozen snapshot of the surface (242 tools, 26 groups).
 
     Taken before @cad_tool landed at 131 tools; `batch` moved 2 -> 3 when
     v1.5.0's `cad_batch` joined `entity_batch_create`/`entity_batch_modify`, and
@@ -591,10 +591,17 @@ async def test_tool_group_sizes_are_unchanged():
     exactly `PACK_TOOL_NAMES["arch"]`, and every group the track-F branches
     had grown while the tag was unranked on them returned to its
     pre-track-F value.
+
+    Track H group U opened SECTION 26 (Understanding & QA) with
+    `drawing_understand`, tagged `analysis` and `query`: `analysis` outranks
+    `query` in `_GROUP_TAG_PRIORITY`, so the reader files under `analysis`
+    (12 -> 13) beside the other whole-drawing queries. This snapshot is
+    branch-local: the track H merge task recomputes it once the understand,
+    network and diff branches have landed.
     """
     sizes = {label: len(names) for label, names in (await server._tool_groups()).items()}
     assert sizes == {
-        "analysis": 12,
+        "analysis": 13,
         "architecture": 12,
         "batch": 3,
         "blocks": 9,
@@ -621,4 +628,4 @@ async def test_tool_group_sizes_are_unchanged():
         "validation": 1,
         "view": 4,
     }
-    assert sum(sizes.values()) == 241
+    assert sum(sizes.values()) == 242

tests/test_understand_clusters.py

@@ -0,0 +1,86 @@
+"""Bodies of model-space content: two plan copies are two clusters."""
+
+from __future__ import annotations
+
+import pytest
+
+from engineering.understand.clusters import find_clusters
+from engineering.understand.snapshot import EntityRecord
+
+EPS = 1e-9
+
+
+def line(handle, a, b, layer="WALL"):
+    return EntityRecord(handle=handle, type="LINE", layer=layer, space="Model", points=(a, b))
+
+
+def text(handle, value, x, y, height=250.0):
+    return EntityRecord(
+        handle=handle,
+        type="TEXT",
+        layer="TEXT",
+        space="Model",
+        points=((x, y),),
+        text=value,
+        height=height,
+    )
+
+
+def plan(prefix, dx):
+    """A 20 000 x 12 000 outline with a partition, a tag in each half and a
+    title under it, shifted ``dx`` along x. The tags float 4 000 from every
+    line - far more than one cell - so only the absorb step keeps them in."""
+    return [
+        line(f"{prefix}1", (dx, 0.0), (dx + 20000.0, 0.0)),
+        line(f"{prefix}2", (dx + 20000.0, 0.0), (dx + 20000.0, 12000.0)),
+        line(f"{prefix}3", (dx + 20000.0, 12000.0), (dx, 12000.0)),
+        line(f"{prefix}4", (dx, 12000.0), (dx, 0.0)),
+        line(f"{prefix}5", (dx + 10000.0, 0.0), (dx + 10000.0, 12000.0)),
+        text(f"{prefix}T1", "T4100", dx + 4000.0, 6000.0),
+        text(f"{prefix}T2", "T4200", dx + 14000.0, 6000.0),
+        text(f"{prefix}T3", "PLANT LAYOUT", dx + 2000.0, 12500.0, height=500.0),
+    ]
+
+
+def test_two_plan_copies_side_by_side_are_two_clusters():
+    # Copy A spans x 0..20 000, copy B 40 000..60 000: a 20 000 gap. The
+    # content box is 60 000 x 12 500 (the title's point box ends at its
+    # insertion, y 12 500), so a cell is 2 % (CELL_FRACTION) of the
+    # hypot(60 000, 12 500) = 61 288 diagonal, about 1 226 units, and the gap
+    # is over 16 empty cells.
+    clusters, membership = find_clusters([*plan("A", 0.0), *plan("B", 40000.0)])
+    assert len(clusters) == 2
+    left, right = sorted(clusters, key=lambda c: c["box"][0])
+    assert left["entities"] == right["entities"] == 8
+    assert left["box"] == pytest.approx([0.0, 0.0, 20000.0, 12500.0], abs=EPS)
+    assert right["box"] == pytest.approx([40000.0, 0.0, 60000.0, 12500.0], abs=EPS)
+    assert membership["AT1"] == membership["A1"] == left["id"]
+    assert membership["BT2"] == membership["B5"] == right["id"]
+    # The tallest text leads the labels.
+    assert left["labels"][0] == "PLANT LAYOUT"
+    assert left["layers"][0] == "WALL"
+
+
+def test_ids_run_largest_first_then_left_to_right():
+    small = [line("S1", (100000.0, 0.0), (100500.0, 0.0))]
+    clusters, _ = find_clusters([*small, *plan("A", 40000.0), *plan("B", 0.0)])
+    assert [c["id"] for c in clusters] == ["C1", "C2", "C3"]
+    assert [c["box"][0] for c in clusters] == pytest.approx([0.0, 40000.0, 100000.0], abs=EPS)
+    assert [c["entities"] for c in clusters] == [8, 8, 1]
+
+
+def test_excluded_handles_take_no_part():
+    far = line("FAR", (-5_000_000_000.0, 0.0), (-4_999_999_000.0, 0.0))
+    clusters, membership = find_clusters([*plan("A", 0.0), far], exclude={"FAR"})
+    assert len(clusters) == 1
+    assert "FAR" not in membership
+    assert clusters[0]["box"] == pytest.approx([0.0, 0.0, 20000.0, 12500.0], abs=EPS)
+
+
+def test_nothing_to_cluster_is_an_empty_answer():
+    assert find_clusters([]) == ([], {})
+
+
+def test_a_non_positive_cell_is_refused():
+    with pytest.raises(ValueError, match="cell: must be greater than zero"):
+        find_clusters(plan("A", 0.0), cell=-1.0)

tests/test_understand_describe.py

@@ -0,0 +1,301 @@
+"""drawing_understand's report: the synthetic plant pair, then hand-built snapshots.
+
+The plant-pair facts come from the generator's truth dict (Task 2), never from
+a real drawing; the hand-built cases compute their expectations in comments.
+"""
+
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from engineering.understand.describe import describe, tag_occurrences, text_language
+from engineering.understand.labels import parse_tag
+from engineering.understand.snapshot import EntityRecord, Snapshot, read_snapshot
+from engineering.understand.vocab import classify_layer, room_label
+from tests.fixtures.plant_pair import build_plant_pair
+
+EPS = 1e-9
+
+
+def shoelace(polygon):
+    total = 0.0
+    for (x1, y1), (x2, y2) in zip(polygon, polygon[1:] + polygon[:1], strict=True):
+        total += x1 * y2 - x2 * y1
+    return abs(total) / 2.0
+
+
+@pytest.fixture(scope="module")
+def plant(tmp_path_factory):
+    truth = build_plant_pair(tmp_path_factory.mktemp("plant"))
+    return {
+        "truth": truth,
+        "pid": describe(read_snapshot(truth["pid"])),
+        "layout": describe(read_snapshot(truth["layout"])),
+    }
+
+
+# ── the synthetic plant pair ────────────────────────────────────────────────
+
+
+def test_the_layout_declares_inches_over_millimetre_geometry(plant):
+    units = plant["layout"]["units"]
+    assert units["declared"]["code"] == plant["truth"]["layout_insunits"]
+    assert units["inferred"] == plant["truth"]["layout_true_unit"]
+    assert units["agree"] is False
+    assert any(w.startswith("INSUNITS declares Inches (1)") for w in plant["layout"]["warnings"])
+
+
+def test_the_far_outlier_is_named_by_handle(plant):
+    outliers = plant["layout"]["extents"]["outliers"]
+    assert outliers[0]["handle"] == plant["truth"]["outlier_handle"]
+    assert any(plant["truth"]["outlier_handle"] in w for w in plant["layout"]["warnings"])
+
+
+def test_the_two_plan_copies_are_two_clusters(plant):
+    assert len(plant["layout"]["clusters"]) == plant["truth"]["cluster_count"]
+
+
+def test_service_layers_are_classified(plant):
+    rows = {r["name"]: r for r in plant["layout"]["layers"]}
+    rows.update({r["name"]: r for r in plant["pid"]["layers"]})
+    for layer, service in plant["truth"]["layer_services"].items():
+        assert rows[layer]["service"] == service, layer
+        assert rows[layer]["confidence"] > 0.0, layer
+
+
+def test_every_equipment_tag_of_the_truth_is_found_on_the_pid(plant):
+    found = {t["tag"] for t in plant["pid"]["equipment_tags"]}
+    expected = {tag for run in plant["truth"]["pipe_runs"] for tag in run["tags"]}
+    expected |= {row["tag"] for row in plant["truth"]["cable_rows"]}
+    assert expected <= found
+
+
+def test_layout_rooms_carry_the_truth_numbers_names_and_measured_faces(plant):
+    for room in plant["truth"]["rooms"]:
+        rows = [
+            r
+            for r in plant["layout"]["rooms"]
+            if r["number"] == room["number"] and r["name"] == room["name"]
+        ]
+        assert rows, room["number"]
+        expected = shoelace([tuple(p) for p in room["polygon"]])
+        for row in rows:
+            assert row["face"] is not None, room["number"]
+            assert abs(row["face"]["area"] - expected) <= 1e-9 * expected, room["number"]
+            assert row["confidence"] == 0.9
+
+
+def test_the_pid_texts_are_read_as_cyrillic(plant):
+    assert plant["pid"]["languages"]["by_class"]["cyrillic"] > 0
+
+
+# ── hand-built snapshots ────────────────────────────────────────────────────
+
+
+def line(handle, a, b, layer="WALL", space="Model"):
+    return EntityRecord(handle=handle, type="LINE", layer=layer, space=space, points=(a, b))
+
+
+def text(handle, value, x, y, layer="TEXT", height=250.0):
+    return EntityRecord(
+        handle=handle,
+        type="TEXT",
+        layer=layer,
+        space="Model",
+        points=((x, y),),
+        text=value,
+        height=height,
+    )
+
+
+def insert(handle, block, x, y, attribs=(), space="Model"):
+    return EntityRecord(
+        handle=handle,
+        type="INSERT",
+        layer="0",
+        space=space,
+        points=((x, y),),
+        block=block,
+        attribs=tuple(attribs),
+    )
+
+
+def rect(prefix, x0, y0, x1, y1, layer="WALL"):
+    return [
+        line(f"{prefix}1", (x0, y0), (x1, y0), layer),
+        line(f"{prefix}2", (x1, y0), (x1, y1), layer),
+        line(f"{prefix}3", (x1, y1), (x0, y1), layer),
+        line(f"{prefix}4", (x0, y1), (x0, y0), layer),
+    ]
+
+
+def snapshot(records, insunits=4, layers=None, layouts=("Model",)):
+    return Snapshot(
+        source="test",
+        insunits=insunits,
+        extmin=None,
+        extmax=None,
+        layers=layers or {},
+        layouts=layouts,
+        records=tuple(records),
+    )
+
+
+def test_a_room_label_inside_the_wall_faces_is_measured():
+    assert classify_layer("WALL")["discipline"] == "architecture"
+    parsed = room_label("ROOM 101 PROCESS")
+    assert parsed is not None
+    # Inner face (200,200)-(6200,4200): 6000 x 4000 = 24 000 000 unit^2.
+    records = [
+        *rect("O", 0.0, 0.0, 6400.0, 4400.0),
+        *rect("I", 200.0, 200.0, 6200.0, 4200.0),
+        text("R", "ROOM 101 PROCESS", 1000.0, 2000.0),
+    ]
+    report = describe(snapshot(records))
+    (room,) = report["rooms"]
+    assert room["number"] == parsed["number"]
+    assert room["name"] == parsed["name"]
+    assert room["face"]["area"] == pytest.approx(24_000_000.0, abs=EPS)
+    assert room["face"]["polygon"] == [
+        [200.0, 200.0],
+        [6200.0, 200.0],
+        [6200.0, 4200.0],
+        [200.0, 4200.0],
+    ]
+    assert room["source"] == "label+face"
+    assert room["confidence"] == 0.9
+    # The wall ring between the outlines is the one unlabelled face.
+    assert report["room_faces"]["faces"] == 2
+    assert report["room_faces"]["unlabelled"] == 1
+
+
+def test_an_attribute_and_a_text_of_one_tag_are_one_occurrence_and_a_copy_is_two():
+    assert parse_tag("T4100") == "T4100"
+    records = [
+        line("L", (0.0, 0.0), (20000.0, 0.0), "0"),
+        insert("B1", "TANK", 1000.0, 0.0, attribs=[("TAG", "T4100")]),
+        # 150 units away: inside 1 % of the 20 000 diagonal (200), so the same one.
+        text("X1", "T4100", 1150.0, 0.0),
+        # 18 000 away: a second occurrence.
+        text("X2", "T4100", 19000.0, 0.0),
+    ]
+    snap = snapshot(records)
+    occurrences = tag_occurrences(snap)
+    assert [(o["handle"], o["source"]) for o in occurrences] == [
+        ("B1", "attribute"),
+        ("X2", "text"),
+    ]
+    report = describe(snap)
+    (row,) = report["equipment_tags"]
+    assert row["tag"] == "T4100"
+    assert row["count"] == 2
+    assert row["ambiguous"] is True
+    assert row["confidence"] == 0.95
+    assert any("appear more than once" in w for w in report["warnings"])
+
+
+def test_text_languages_are_counted_by_character_class():
+    assert text_language("ПОДАЧА CIP") == "cyrillic"
+    assert text_language("DÖNÜŞ") == "turkish"
+    assert text_language("DÖNÜS") == "latin"  # ö and ü alone are German too
+    assert text_language("SUPPLY") == "latin"
+    assert text_language("3,5") == "none"
+    records = [
+        text("A", "ПОДАЧА", 0.0, 0.0),
+        text("B", "BESLEME DÖNÜŞ", 0.0, 500.0),
+        text("C", "SUPPLY", 0.0, 1000.0),
+        text("D", "12", 0.0, 1500.0),
+    ]
+    languages = describe(snapshot(records))["languages"]
+    assert languages["by_class"] == {"latin": 1, "turkish": 1, "cyrillic": 1, "none": 1}
+    assert languages["share"]["cyrillic"] == 0.25
+    assert languages["samples"]["cyrillic"] == ["A"]
+
+
+def test_blocks_are_split_named_and_anonymous_with_kinds_by_name():
+    records = [
+        insert("A1", "*U12", 0.0, 0.0),
+        insert("A2", "*U12", 100.0, 0.0),
+        insert("G1", "GATE_VALVE", 200.0, 0.0),
+        insert("G2", "GATE_VALVE", 300.0, 0.0),
+        insert("G3", "GATE_VALVE", 400.0, 0.0),
+        insert("P1", "PUMP_A", 500.0, 0.0),
+    ]
+    blocks = describe(snapshot(records))["blocks"]
+    assert blocks["inserts"] == 6
+    assert [(r["name"], r["inserts"], r["kind"]) for r in blocks["named"]] == [
+        ("GATE_VALVE", 3, "valve"),
+        ("PUMP_A", 1, "equipment"),
+    ]
+    assert blocks["anonymous"] == {"names": 1, "inserts": 2}
+    assert blocks["kinds"] == {"equipment": 1, "valve": 1}
+
+
+def test_the_title_block_is_the_named_paper_space_block_with_its_attributes():
+    title = insert(
+        "TB",
+        "A1_TITLE",
+        0.0,
+        0.0,
+        attribs=[("DWG_NO", "001"), ("REV", "B"), ("SCALE", "1:100"), ("DATE", "2026-09-24")],
+        space="Layout1",
+    )
+    other = insert(
+        "M",
+        "NOTE_BOX",
+        0.0,
+        0.0,
+        attribs=[("A", "1"), ("B", "2"), ("C", "3"), ("D", "4"), ("E", "5")],
+    )
+    report = describe(snapshot([title, other], layouts=("Model", "Layout1")))
+    block = report["title_block"]
+    assert block["found"] is True
+    assert block["handle"] == "TB"
+    assert block["attributes"] == {
+        "DWG_NO": "001",
+        "REV": "B",
+        "SCALE": "1:100",
+        "DATE": "2026-09-24",
+    }
+    assert block["confidence"] == 0.9
+    assert report["layouts"] == [
+        {"name": "Model", "entities": 1},
+        {"name": "Layout1", "entities": 1},
+    ]
+
+
+def test_no_title_block_is_said_not_invented():
+    block = describe(snapshot([insert("M", "X", 0.0, 0.0, attribs=[("A", "1")])]))["title_block"]
+    assert block == {"found": False, "reason": "no block reference with three or more attributes"}
+
+
+def test_a_layer_without_a_keyword_is_classified_by_its_texts():
+    expected = classify_layer("CIP SUPPLY")
+    assert expected["service"] != "unknown"
+    assert classify_layer("L-17")["service"] == "unknown"
+    assert classify_layer("L-17")["discipline"] == "unknown"
+    records = [
+        line("P1", (0.0, 0.0), (3000.0, 0.0), "L-17"),
+        line("P2", (3000.0, 0.0), (3000.0, 4000.0), "L-17"),
+        text("T1", "CIP SUPPLY", 1000.0, 100.0, layer="L-17"),
+        text("T2", "CIP SUPPLY", 3100.0, 2000.0, layer="L-17"),
+    ]
+    layers = {r["name"]: r for r in describe(snapshot(records))["layers"]}
+    row = layers["L-17"]
+    assert row["service"] == expected["service"]
+    assert row["discipline"] == expected["discipline"]
+    assert row["confidence"] == 0.6
+    assert row["entities"] == 4
+    assert row["length"] == pytest.approx(7000.0, abs=EPS)  # 3000 + 4000
+    assert row["length_m"] == pytest.approx(7.0, abs=EPS)
+    assert row["evidence"].startswith("2 of 2 texts on the layer read as")
+
+
+def test_describe_leaves_the_snapshot_as_it_was():
+    records = [*rect("O", 0.0, 0.0, 6400.0, 4400.0), text("R", "T4100", 100.0, 100.0)]
+    snap = snapshot(records)
+    before = copy.deepcopy(snap)
+    describe(snap)
+    assert snap == before

tests/test_understand_tools.py

@@ -0,0 +1,82 @@
+"""drawing_understand over the MCP wire, on a fresh headless document."""
+
+from __future__ import annotations
+
+import pytest
+import pytest_asyncio
+from fastmcp import Client
+
+import server
+from tests.fixtures.plant_pair import build_plant_pair
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest_asyncio.fixture
+async def client(monkeypatch):
+    """In-memory client on a fresh headless document - never the operator's AutoCAD."""
+    monkeypatch.setenv("AUTOCAD_MCP_BACKEND", "ezdxf")
+    async with Client(server.mcp) as connected:
+        status = (await connected.call_tool("system_status", {})).structured_content or {}
+        assert status.get("backend") == "ezdxf", "these tests must never touch live AutoCAD"
+        await connected.call_tool("drawing_new", {})
+        yield connected
+
+
+async def test_drawing_understand_reads_the_synthetic_layout_file(client, tmp_path):
+    truth = build_plant_pair(tmp_path)
+    result = await client.call_tool("drawing_understand", {"path": truth["layout"]})
+    report = result.structured_content
+    assert report["units"]["declared"]["code"] == truth["layout_insunits"]
+    assert report["units"]["inferred"] == truth["layout_true_unit"]
+    assert report["extents"]["outliers"][0]["handle"] == truth["outlier_handle"]
+    assert len(report["clusters"]) == truth["cluster_count"]
+
+
+async def test_drawing_understand_reads_the_current_document_and_leaves_it_alone(client):
+    # A 6400 x 4400 outline on WALL (perimeter 2 x (6400 + 4400) = 21 600) and
+    # one tag.
+    corners = [(0.0, 0.0), (6400.0, 0.0), (6400.0, 4400.0), (0.0, 4400.0)]
+    for (x1, y1), (x2, y2) in zip(corners, corners[1:] + corners[:1], strict=True):
+        await client.call_tool(
+            "entity_create_line", {"x1": x1, "y1": y1, "x2": x2, "y2": y2, "layer": "WALL"}
+        )
+    await client.call_tool(
+        "entity_create_text",
+        {"text": "T4100", "x": 1000.0, "y": 1000.0, "height": 250.0, "layer": "TAGS"},
+    )
+    before = (await client.call_tool("analysis_entity_stats", {})).structured_content
+    report = (await client.call_tool("drawing_understand", {})).structured_content
+    after = (await client.call_tool("analysis_entity_stats", {})).structured_content
+    assert after == before
+    layers = {row["name"]: row for row in report["layers"]}
+    assert layers["WALL"]["entities"] == 4
+    assert layers["WALL"]["length"] == pytest.approx(21600.0, abs=1e-9)
+    assert [t["tag"] for t in report["equipment_tags"]] == ["T4100"]
+
+
+async def test_a_missing_file_is_refused_by_path(client, tmp_path):
+    missing = tmp_path / "nowhere.dxf"
+    result = await client.call_tool(
+        "drawing_understand", {"path": str(missing)}, raise_on_error=False
+    )
+    assert result.is_error is True
+    assert "path: no such file" in result.content[0].text
+    assert "nowhere.dxf" in result.content[0].text
+
+
+async def test_a_file_the_engine_cannot_parse_is_refused(client, tmp_path):
+    # Not a DXF: the snapshot's parse error comes back as a tool error that
+    # names the file, never as a traceback.
+    garbage = tmp_path / "not_a_drawing.dxf"
+    garbage.write_text("this is not a drawing", encoding="utf-8")
+    result = await client.call_tool(
+        "drawing_understand", {"path": str(garbage)}, raise_on_error=False
+    )
+    assert result.is_error is True
+    assert "not_a_drawing.dxf" in result.content[0].text
+
+
+async def test_drawing_understand_is_advertised_read_only(client):
+    tools = {tool.name: tool for tool in await client.list_tools()}
+    assert tools["drawing_understand"].annotations.readOnlyHint is True

tests/test_understand_units.py

@@ -0,0 +1,161 @@
+"""Declared versus inferred units, and robust extents, on hand-built snapshots.
+
+Every expected number is worked out in the comment beside it from the
+coordinates written here; nothing is read back from the implementation.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+
+from engineering.understand.snapshot import EntityRecord, Snapshot
+from engineering.understand.units import entity_box, infer_units, robust_extents
+
+EPS = 1e-9
+
+
+def line(handle, a, b, layer="WALL"):
+    return EntityRecord(handle=handle, type="LINE", layer=layer, space="Model", points=(a, b))
+
+
+def text(handle, value, x, y, height, layer="TEXT"):
+    return EntityRecord(
+        handle=handle,
+        type="TEXT",
+        layer=layer,
+        space="Model",
+        points=((x, y),),
+        text=value,
+        height=height,
+    )
+
+
+def rect(prefix, x0, y0, x1, y1, layer="WALL"):
+    return [
+        line(f"{prefix}1", (x0, y0), (x1, y0), layer),
+        line(f"{prefix}2", (x1, y0), (x1, y1), layer),
+        line(f"{prefix}3", (x1, y1), (x0, y1), layer),
+        line(f"{prefix}4", (x0, y1), (x0, y0), layer),
+    ]
+
+
+def snapshot(records, insunits):
+    return Snapshot(
+        source="test",
+        insunits=insunits,
+        extmin=None,
+        extmax=None,
+        layers={},
+        layouts=("Model",),
+        records=tuple(records),
+    )
+
+
+def room_in_mm():
+    """One 6000 x 4000 room between 200 mm double-line walls, labelled with
+    250-unit text: outer outline (0,0)-(6400,4400), inner (200,200)-(6200,4200)."""
+    return [
+        *rect("O", 0.0, 0.0, 6400.0, 4400.0),
+        *rect("I", 200.0, 200.0, 6200.0, 4200.0),
+        text("T1", "ROOM 101 PROCESS", 1000.0, 2000.0, 250.0),
+        text("T2", "T4100", 3000.0, 1000.0, 250.0),
+    ]
+
+
+def test_inches_declared_over_millimetre_geometry_is_flagged():
+    # Inner room face 6000 x 4000 = 2.4e7 unit^2: 24 m2 as mm (plausible),
+    # 15 484 m2 as inches (out of the 1-5000 m2 band). Wall pairs 200 apart:
+    # 0.2 m as mm, 5.08 m as inches. Text 250: 0.25 m as mm, 6.35 m as inches.
+    result = infer_units(snapshot(room_in_mm(), insunits=1), room_areas=[6000.0 * 4000.0])
+    assert result["declared"] == {"code": 1, "name": "in", "label": "Inches"}
+    assert result["inferred"] == "mm"
+    assert result["mm_per_unit"] == 1.0
+    assert result["agree"] is False
+    assert result["warning"].startswith("INSUNITS declares Inches (1) but the geometry reads as mm")
+    kinds = {e["kind"]: e for e in result["evidence"]}
+    assert kinds["wall_thickness"]["value"] == pytest.approx(200.0, abs=EPS)
+    assert kinds["wall_thickness"]["plausible"] == ["mm"]
+    assert kinds["room_area"]["as"]["mm"] == pytest.approx(24.0, abs=EPS)
+    assert kinds["room_area"]["as"]["in"] == pytest.approx(24_000_000.0 * 0.0254**2, abs=EPS)
+    assert "in" not in kinds["text_height"]["plausible"]  # 6.35 m of lettering
+
+
+def test_millimetres_declared_over_the_same_geometry_agree():
+    result = infer_units(snapshot(room_in_mm(), insunits=4), room_areas=[24_000_000.0])
+    assert result["inferred"] == "mm"
+    assert result["agree"] is True
+    assert result["warning"] is None
+    assert 0.0 < result["confidence"] <= 0.9
+
+
+def test_one_weak_item_never_overrules_the_header():
+    # Only an overall size: 20 000 units is 20 m as mm, 200 m as cm, 508 m as
+    # inches (all in the 0.01-2000 m band) and 20 km as metres (out of it).
+    # mm, cm and in score the size's 0.25 each; "m" scores the header's 0.5
+    # alone and still wins - the declared metre stands.
+    records = [
+        line("A", (0.0, 0.0), (20000.0, 0.0), "0"),
+        line("B", (0.0, 0.0), (0.0, 5000.0), "0"),
+    ]
+    result = infer_units(snapshot(records, insunits=6))
+    assert result["inferred"] == "m"
+    assert result["agree"] is True
+
+
+def test_no_evidence_keeps_the_declared_unit_at_low_confidence():
+    result = infer_units(snapshot([], insunits=4))
+    assert result["inferred"] == "mm"
+    assert result["confidence"] == 0.4
+    assert result["evidence"] == []
+
+
+def test_unitless_with_no_evidence_settles_nothing():
+    result = infer_units(snapshot([], insunits=0))
+    assert result["inferred"] is None
+    assert result["mm_per_unit"] is None
+    assert result["warning"].endswith("lengths stay in drawing units.")
+
+
+def test_a_far_outlier_is_found_by_handle_and_left_out_of_the_robust_box():
+    records = [
+        line(f"L{i}", (i * 1000.0, 0.0), (i * 1000.0 + 500.0, 800.0), "0") for i in range(12)
+    ]
+    far = line("FAR", (-5_000_000_000.0, 0.0), (-5_000_000_000.0 + 10.0, 0.0), "0")
+    result = robust_extents([*records, far])
+    assert [o["handle"] for o in result["outliers"]] == ["FAR"]
+    # Robust box: x from 0 to 11 * 1000 + 500 = 11500, y from 0 to 800.
+    assert result["robust"] == pytest.approx([0.0, 0.0, 11500.0, 800.0], abs=EPS)
+    assert result["computed"][0] == pytest.approx(-5_000_000_000.0, abs=EPS)
+    # The outlier's centre (-4 999 999 995, 0) is 4 999 999 995 from the box.
+    assert result["outliers"][0]["distance"] == pytest.approx(4_999_999_995.0, abs=1e-3)
+    # Stretch: hypot(5 000 011 500, 800) / hypot(11 500, 800) - the computed
+    # diagonal over the robust one.
+    expected = math.hypot(5_000_011_500.0, 800.0) / math.hypot(11500.0, 800.0)
+    assert result["stretch"] == pytest.approx(expected, rel=1e-12)
+
+
+def test_the_edge_walls_of_a_plan_are_not_outliers():
+    # The room's centres crowd its middle (the vertical walls centre on
+    # y 2200, the label on y 2000), so a per-axis fence on centres would cut
+    # the top and bottom walls off; grown from the middle, every wall joins.
+    result = robust_extents(room_in_mm())
+    assert result["outliers"] == []
+    assert result["robust"] == pytest.approx([0.0, 0.0, 6400.0, 4400.0], abs=EPS)
+    assert result["stretch"] == pytest.approx(1.0, abs=EPS)
+
+
+def test_fewer_than_four_entities_have_no_outliers():
+    records = [line("A", (0.0, 0.0), (1.0, 0.0), "0"), line("B", (1e9, 0.0), (1e9 + 1.0, 0.0), "0")]
+    assert robust_extents(records)["outliers"] == []
+
+
+def test_entity_box_grows_a_circle_by_its_radius():
+    circle = EntityRecord(
+        handle="C", type="CIRCLE", layer="0", space="Model", points=((10.0, 20.0),), radius=5.0
+    )
+    assert entity_box(circle) == (5.0, 15.0, 15.0, 25.0)
+    boxed = EntityRecord(handle="B", type="INSERT", layer="0", space="Model", bbox=(1, 2, 3, 4))
+    assert entity_box(boxed) == (1.0, 2.0, 3.0, 4.0)
+    assert entity_box(EntityRecord(handle="N", type="HATCH", layer="0", space="Model")) is None