--reserve-escapes: keep a way out open for every fine-pitch pin

Before routing, each crowded pin gets the shortest way from its pad to
open board, found against pads, keepouts and earlier escapes. While the
pin still has connections to route, no other net may put a trace or a
via there, nor within clearance of it; the reservation lifts once the
pin is routed.

bench/bench.py

@@ -24,9 +24,11 @@ off. Exits non-zero if any run crashed or timed out.
 from __future__ import annotations
 
 import argparse
+from concurrent.futures import ThreadPoolExecutor, as_completed
 import json
 import math
 import os
+from pathlib import Path
 import re
 import shlex
 import subprocess
@@ -34,8 +36,6 @@ import sys
 import tempfile
 import threading
 import time
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from pathlib import Path
 
 NOT_ROUTED = re.compile(r"freeroute: (\d+) connection\(s\) not routed")
 TO_ZONE = re.compile(r"freeroute: (\d+) more connection\(s\) left to a zone fill")

bench/diagnose.py

@@ -0,0 +1,266 @@
+"""Why did each connection fail? Sort the failures of one exact-engine run.
+
+    uv run python bench/diagnose.py board.dsn --edge-clearance 0.5 [--json out.json]
+
+Every connection the exact engine leaves unrouted lands in one bucket:
+
+rejected    the grid routed it, the exact geometry check refused its copper
+alone       it cannot be routed even on a board with no other routes: the
+            pads, keepouts or the grid itself are the limit, not congestion
+walled-in   in the routed board one of its pins has no way out: a flood from
+            the pin's end cells through free cells stops short (pin access)
+congestion  both pins can get out, but no free path joins them
+
+The board state is the one the result came from (the best pass), rebuilt by
+replaying that pass's paths. Diagnostic only: it reaches into the router.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+import json
+from pathlib import Path
+import sys
+
+from freeroute.board import build_board
+from freeroute.board.search_tree import ShapeSearchTree
+from freeroute.dsn import parse_dsn
+from freeroute.geometry.octagon import overlaps_2d
+from freeroute.route import grid_router
+from freeroute.route.exact_router import route_board_exact
+from freeroute.route.grid_router import GridRouter, _ends_of
+from freeroute.route.pipeline import (
+    _mm_to_board,
+    _rule_clearance_dsn,
+    _rule_width_dsn,
+    _via_half_board,
+)
+
+# a pin whose free neighbourhood holds fewer nodes than this is walled in
+FLOOD_LIMIT = 200
+
+
+def _capture_router():
+    """Patch GridRouter so the instance route_board_exact builds, and the paths
+    of its best pass, can be read back afterwards."""
+    seen: dict = {}
+    original_commit = GridRouter._commit
+    original_snapshot = GridRouter._snapshot
+
+    def commit(self, conn, path):
+        original_commit(self, conn, path)
+        self._diag_paths[conn.index] = (list(path), conn.a_end, conn.b_end)
+
+    def snapshot(self, conns):
+        self._diag_best = {c.index: self._diag_paths[c.index] for c in conns if c.routed}
+        seen["router"] = self
+        return original_snapshot(self, conns)
+
+    def init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        self._diag_paths = {}
+        self._diag_best = {}
+        seen["kwargs"] = kwargs
+        seen["args"] = args
+
+    original_init = GridRouter.__init__
+    GridRouter.__init__ = init
+    GridRouter._commit = commit
+    GridRouter._snapshot = snapshot
+    return seen
+
+
+def _capture_conflicts() -> list:
+    """Record each exact-check refusal: the copper box, its kind, and the
+    shape it came too close to. The check stops at a connection's first
+    conflict, so refusals and rejected connections line up in order."""
+    log: list = []
+    original = ShapeSearchTree.clearance_conflict
+
+    def conflict(self, box, net_no, layer, clearance, kind="wire"):
+        hit = original(self, box, net_no, layer, clearance, kind)
+        if hit:
+            # the shape that tripped the check, found the way the check does
+            other = None
+            expanded = box.offset(clearance)
+            for s in self.overlapping(expanded):
+                if s.net_no == net_no or not s.on_layer(layer):
+                    continue
+                if s.blocks != "all" and s.blocks != kind + "s":
+                    continue
+                if not s.clearance:
+                    if s.tile.overlaps(box):
+                        other = s
+                        break
+                    continue
+                if (s.exact is not None and overlaps_2d(s.exact, expanded)) or (
+                    s.exact is None and s.tile.overlaps(expanded)
+                ):
+                    other = s
+                    break
+            log.append((net_no, kind, layer, box, clearance, other))
+        return hit
+
+    ShapeSearchTree.clearance_conflict = conflict
+    return log
+
+
+def _gap(a, b) -> int:
+    dx = max(b.ll.x - a.ur.x, a.ll.x - b.ur.x, 0)
+    dy = max(b.ll.y - a.ur.y, a.ll.y - b.ur.y, 0)
+    return max(dx, dy)
+
+
+def _fresh(seen) -> GridRouter:
+    router = grid_router.GridRouter(*seen["args"], **seen["kwargs"])
+    router._conns = router._build_connections()
+    return router
+
+
+def _flood(router: GridRouter, pin, net_no: int, conns) -> tuple[int, Counter]:
+    """How many nodes a pin can reach through free cells (up to FLOOD_LIMIT),
+    and which other nets' copper bounds the region."""
+    walls: Counter = Counter()
+    # the search starts on every end node unconditionally (it may leave one
+    # inside a wire keepout by a via), so the flood does too
+    start = list(router._end_nodes(pin, net_no, conns))
+    seen = set(start)
+    frontier = list(start)
+    while frontier and len(seen) < FLOOD_LIMIT:
+        x, y, layer = frontier.pop()
+        steps = [(x + dx, y + dy, layer) for dx, dy in router._neighbours]
+        if router._via_placeable((x, y), net_no, conns):
+            steps += [(x, y, other) for other in router.layers if other != layer]
+        elif len(seen) == 1:
+            # the pin's own exit is a via that other copper leaves no room for
+            via_nodes = [(*c, lay) for c in router._via_cells((x, y)) for lay in router.layers]
+            for owner in router._crossed_owners(via_nodes, net_no, conns):
+                walls[conns[owner].net_no] += 1
+        for n in steps:
+            if n in seen or not (0 <= n[0] < router.cols and 0 <= n[1] < router.rows):
+                continue
+            if router._enter_cost(n[:2], n[2], net_no, False, conns) is None:
+                # trace, via footprint or clearance halo, as rip-up sees them
+                owners = router._crossed_owners([n], net_no, conns)
+                for owner in owners:
+                    walls[conns[owner].net_no] += 1
+                if not owners:
+                    walls[0] += 1  # a pad or keepout
+                continue
+            seen.add(n)
+            frontier.append(n)
+    return len(seen), walls
+
+
+def diagnose(
+    dsn_text: str, edge_clearance_mm: float | None, resolution: int = 2, shove: bool = False,
+    access_cost: float = 0.0,
+) -> dict:
+    dsn = parse_dsn(dsn_text)
+    names = {i + 1: n.name for i, n in enumerate(dsn.nets)}
+    scale = max(dsn.resolution.value, 1)
+    seen = _capture_router()
+    conflicts = _capture_conflicts()
+    exact = route_board_exact(
+        build_board(dsn),
+        trace_width=round(_rule_width_dsn(dsn) * scale),
+        clearance=round(_rule_clearance_dsn(dsn) * scale),
+        via_half=_via_half_board(dsn, scale),
+        edge_clearance=_mm_to_board(dsn, scale, edge_clearance_mm),
+        resolution=resolution,
+        shove=shove,
+        access_cost=access_cost,
+    )
+    routed = seen["router"]
+    best = routed._diag_best
+    grid_failed = {(c.net_no, *_ends_of(c)) for c in routed._conns if c.index not in best}
+
+    # the board as the best pass left it
+    state = _fresh(seen)
+    conns = state._conns
+    for idx, (path, a_end, b_end) in best.items():
+        conns[idx].a_end, conns[idx].b_end = a_end, b_end
+        state._commit(conns[idx], path)
+    empty = _fresh(seen)
+    # refusals in the order the check made them, one per rejected connection
+    per_net: dict[int, list] = {}
+    for net_no, kind, layer, box, clearance, other in conflicts:
+        if other is None:
+            what = "?"
+        elif other.net_no == -1:
+            what = "keepout" if other.clearance else "rule area"
+        else:
+            what = ("trace/via of " if other.routed else "pad of ") + names.get(other.net_no, "?")
+        need = clearance if other is None or other.clearance else 0
+        short = (need - _gap(box, other.tile)) / scale / 1000 if other is not None else 0
+        per_net.setdefault(net_no, []).append(
+            {"copper": kind, "layer": layer, "against": what, "short_mm": round(short, 4)}
+        )
+    by_key = {(c.net_no, *_ends_of(c)): c for c in conns}
+
+    rows = []
+    for failure in exact.result.failed:
+        net_no, a, b = failure[0], failure[1], failure[2]
+        zone = failure[3] if len(failure) > 3 else ""
+        if zone:
+            continue  # left to a zone fill, not a failure
+        key = (net_no, a, b)
+        row = {"net": names.get(net_no, str(net_no)), "a": a, "b": b}
+        conn = by_key.get(key)
+        if key not in grid_failed:
+            row["kind"] = "rejected"
+            if per_net.get(net_no):
+                row["conflict"] = per_net[net_no].pop(0)
+        elif conn is None:
+            row["kind"] = "unknown"
+        elif empty._search(empty._conns[conn.index], allow_ripup=False, conns=empty._conns) is None:
+            row["kind"] = "alone"
+        else:
+            walled = []
+            for end, group in ((a, conn.a_group), (b, conn.b_group)):
+                for pin in group[0][:1]:  # a group's first pin is its route end
+                    reach, walls = _flood(state, pin, net_no, conns)
+                    if reach < FLOOD_LIMIT:
+                        walled.append({
+                            "pin": end, "reach": reach,
+                            "walls": [names.get(n, "pads/keepouts") for n, _ in walls.most_common(4)],
+                        })
+            row["kind"] = "walled-in" if walled else "congestion"
+            if walled:
+                row["walled"] = walled
+        rows.append(row)
+    return {"failures": rows, "counts": dict(Counter(r["kind"] for r in rows))}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("dsn", type=Path)
+    ap.add_argument("--edge-clearance", type=float, metavar="MM")
+    ap.add_argument("--grid-resolution", type=int, default=2, metavar="K")
+    ap.add_argument("--shove", action="store_true", help="as mckicad routes")
+    ap.add_argument("--access-cost", type=float, default=0.0)
+    ap.add_argument("--json", type=Path, help="also write the full table here")
+    args = ap.parse_args(argv)
+
+    report = diagnose(args.dsn.read_text(), args.edge_clearance, args.grid_resolution, args.shove,
+                      args.access_cost)
+    for row in report["failures"]:
+        extra = ""
+        for w in row.get("walled", []):
+            extra += f"  [{w['pin']} reaches {w['reach']} cells, walled by {', '.join(w['walls'])}]"
+        if "conflict" in row:
+            c = row["conflict"]
+            extra += (f"  [{c['copper']} on layer {c['layer']} {c['short_mm']} mm too close"
+                      f" to {c['against']}]")
+        print(f"{row['kind']:11} {row['net']}: {row['a']} to {row['b']}{extra}")
+    total = sum(report["counts"].values())
+    print(f"\n{total} failed: " + ", ".join(f"{k} {v}" for k, v in sorted(report["counts"].items())),
+          file=sys.stderr)
+    if args.json:
+        args.json.write_text(json.dumps(report, indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/freeroute/board/build.py

@@ -333,10 +333,20 @@ def _insert_keepouts(dsn: DsnBoard, board: BasicBoard, transform: CoordinateTran
                     tiles=tiles,
                     blocks_wires=keepout.kind != "via_keepout",
                     blocks_vias=keepout.kind != "wire_keepout",
+                    clearance=not is_rule_area(keepout.area.name),
                 )
             )
 
 
+#: a structure keepout named with this prefix is a KiCad rule area (mckicad
+#: names them on export); it is checked for overlap only
+RULE_AREA_PREFIX = "rule_area"
+
+
+def is_rule_area(name: str | None) -> bool:
+    return bool(name) and name.startswith(RULE_AREA_PREFIX)
+
+
 def _area_border_tiles(shape: Shape, transform: CoordinateTransform) -> list:
     """Convex board tiles covering a keepout border shape.
 

src/freeroute/board/items.py

@@ -76,6 +76,11 @@ class ObstacleArea(Item):
     #: tracks" rule area, where vias are allowed), via_keepout only vias
     blocks_wires: bool = True
     blocks_vias: bool = True
+    #: False for a KiCad rule area: copper may not overlap it but may touch
+    #: it, since KiCad's DRC applies no clearance to a rule area. Every other
+    #: keepout may stand for copper (a net tie, a track kept as it is), so it
+    #: keeps the clearance unless named as a rule area.
+    clearance: bool = True
 
     def is_obstacle(self) -> bool:
         return True

src/freeroute/board/search_tree.py

@@ -50,6 +50,8 @@ class TreeShape:
     #: which copper a keepout tile stops: "all", "wires" (a wire_keepout,
     #: vias allowed) or "vias" (a via_keepout)
     blocks: str = "all"
+    #: False for a rule area: copper may touch it, only overlap counts
+    clearance: bool = True
 
     def on_layer(self, layer: int) -> bool:
         return layer in self.layers
@@ -129,6 +131,8 @@ class ShapeSearchTree:
 
         Uses a strict 2-D overlap of the ``clearance``-expanded box, so tiles
         exactly ``clearance`` apart (touching after expansion) are allowed.
+        A rule area (``clearance=False``) only has to be clear of the copper
+        itself.
         """
         expanded = box.offset(clearance)
         for shape in self.overlapping(expanded):
@@ -136,6 +140,10 @@ class ShapeSearchTree:
                 continue
             if shape.blocks != "all" and shape.blocks != kind + "s":
                 continue  # a wire-only keepout does not stop a via, and so on
+            if not shape.clearance:
+                if shape.tile.overlaps(box):
+                    return True
+                continue
             if shape.exact is not None:
                 if overlaps_2d(shape.exact, expanded):
                     return True
@@ -143,6 +151,17 @@ class ShapeSearchTree:
                 return True
         return False
 
+    def rule_area_overlap(self, box: IntBox, layer: int, kind: str = "wire") -> bool:
+        """True if ``box`` overlaps a rule area on ``layer`` that stops ``kind``."""
+        for shape in self.overlapping(box):
+            if shape.clearance or not shape.on_layer(layer):
+                continue
+            if shape.blocks != "all" and shape.blocks != kind + "s":
+                continue
+            if shape.tile.overlaps(box):
+                return True
+        return False
+
     def clearance_conflict_shape(
         self, region, net_no: int, layer: int
     ) -> bool:
@@ -178,6 +197,13 @@ class ShapeSearchTree:
                     continue  # static input pair (e.g. pad vs pad) — not a routing DRC
                 if not (shape.layers & other.layers):
                     continue
+                if not (shape.clearance and other.clearance):
+                    # a rule area: only an overlap is a violation
+                    mine = shape.exact if shape.exact is not None else shape.tile
+                    theirs = other.exact if other.exact is not None else other.tile
+                    if overlaps_2d(mine, theirs):
+                        return shape
+                    continue
                 if shape.exact is None and other.exact is None:
                     if other.tile.overlaps(expanded):  # byte-identical box path
                         return shape

src/freeroute/cli.py

@@ -30,8 +30,8 @@ from freeroute.ses import write_ses
 #: which optional flags each engine actually implements. Anything not listed for
 #: an engine is rejected by :func:`_validate` rather than quietly ignored.
 ENGINE_OPTIONS: dict[str, frozenset[str]] = {
-    "grid": frozenset({"rip_up", "max_passes", "seed", "orders", "promote"}),
-    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote"}),
+    "grid": frozenset({"rip_up", "max_passes", "seed", "orders", "promote", "access", "escapes"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed", "orders", "promote", "access", "escapes"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -45,6 +45,8 @@ _FLAG_NAMES = {
     "seed": "--seed",
     "orders": "--orders",
     "promote": "--promote-failures",
+    "access": "--access-cost",
+    "escapes": "--reserve-escapes",
 }
 
 
@@ -158,6 +160,19 @@ def build_parser() -> argparse.ArgumentParser:
         help="grid and exact engines: up to R rounds, each routing the connections that "
         "failed so far first; keeps the best round",
     )
+    parser.add_argument(
+        "--access-cost",
+        type=float,
+        metavar="C",
+        help="grid and exact engines: extra cost for a route to pass where it would close "
+        "another pin's way out while that pin still has connections to route (default 0: off)",
+    )
+    parser.add_argument(
+        "--reserve-escapes",
+        action="store_true",
+        help="grid and exact engines: before routing, reserve a way out for every fine-pitch "
+        "pin that no other net may use until that pin's connections are routed",
+    )
     parser.add_argument(
         "--jobs",
         type=int,
@@ -186,6 +201,8 @@ def main(argv: list[str] | None = None) -> int:
             ("seed", args.seed is not None),
             ("orders", args.orders is not None),
             ("promote", args.promote_failures is not None),
+            ("access", args.access_cost is not None),
+            ("escapes", args.reserve_escapes),
         )
         if asked
     ]
@@ -219,6 +236,8 @@ def main(argv: list[str] | None = None) -> int:
             "edge_clearance_mm": args.edge_clearance,
             "resolution": 2 if args.grid_resolution is None else args.grid_resolution,
             "heuristic_weight": args.heuristic_weight,
+            "access_cost": args.access_cost or 0.0,
+            "reserve_escapes": args.reserve_escapes,
         }
     elif args.engine == "grid":
         options = {
@@ -227,6 +246,8 @@ def main(argv: list[str] | None = None) -> int:
             "max_passes": max_passes,
             "edge_clearance_mm": args.edge_clearance,
             "resolution": 1 if args.grid_resolution is None else args.grid_resolution,
+            "access_cost": args.access_cost or 0.0,
+            "reserve_escapes": args.reserve_escapes,
         }
     if args.engine == "room":
         result = build_rooms_routing_result(

src/freeroute/dsn/reader.py

@@ -9,6 +9,8 @@ tolerant ``skip_scope`` behaviour.
 
 from __future__ import annotations
 
+import re
+
 from .model import (
     ClearanceRule,
     ComponentPlace,
@@ -481,12 +483,26 @@ def _read_network(node: SExp, board: DsnBoard) -> None:
 # --- top level ---------------------------------------------------------------
 
 
+_STRING_QUOTE = re.compile(r"\(\s*string_quote\s+(\S)\s*\)")
+
+
+def _declared_quote(text: str) -> str:
+    """The quote character the file declares in ``(string_quote X)``.
+
+    Only that character opens a string. Without a declaration both kinds are
+    accepted, as before: KiCad declares ``"`` and then writes a bare ``'``
+    where a value is a single quote mark, e.g. a keycap part number.
+    """
+    found = _STRING_QUOTE.search(text[:4096])
+    return found.group(1) if found else "\"'"
+
+
 def parse_dsn(text: str) -> DsnBoard:
     """Parse DSN ``text`` into a :class:`DsnBoard`.
 
     Raises :class:`DsnParseError` if the top-level scope is not ``(pcb ...)``.
     """
-    top = parse(text)
+    top = parse(text, _declared_quote(text))
     if top.head != "pcb":
         raise DsnParseError(
             f"not a Specctra DSN file: expected top-level '(pcb ...)', got '({top.head} ...)'"

src/freeroute/route/exact_router.py

@@ -42,6 +42,7 @@ from freeroute.geometry import (
     segment_octagon,
     shove_segment,
 )
+from freeroute.geometry.polyline import corner_box
 
 from .grid_router import RouteResult, route_board
 
@@ -96,6 +97,8 @@ def route_board_exact(
     heuristic_weight: float = 1.0,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> ExactRouteResult:
     """Route ``board`` orthogonally and verify the result with exact geometry.
 
@@ -126,6 +129,8 @@ def route_board_exact(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     edge = 0 if edge_clearance is None else edge_clearance
     outline = board.outline
@@ -155,7 +160,10 @@ def route_board_exact(
             box = tile.bounding_box()
             if not box.is_empty():
                 tree.insert(
-                    TreeShape(next(owner), -1, frozenset({obstacle.layer}), box, blocks=blocks)
+                    TreeShape(
+                        next(owner), -1, frozenset({obstacle.layer}), box,
+                        blocks=blocks, clearance=obstacle.clearance,
+                    )
                 )
 
     via_layers = frozenset(signal_layers)
@@ -176,7 +184,9 @@ def route_board_exact(
             )
             for i, (box, box_layers) in enumerate(boxes)
             for layer in box_layers
-        ) or (outline is not None and not all(outline.box_clear(b, edge) for b, _ in boxes)):
+        ) or _end_in_rule_area(tree, wires, half_width) or (
+            outline is not None and not all(outline.box_clear(b, edge) for b, _ in boxes)
+        ):
             rejected.append((net_no, *ends))
             continue  # exact-clearance conflict -> drop (may be recovered by shove)
         acc = accepted.get(net_no)
@@ -590,6 +600,17 @@ def _net_boxes(result, net_no, half_width, via_layers, via_half=None):
     )
 
 
+def _end_in_rule_area(tree, wires, half_width) -> bool:
+    """A wire's tiles stop at its end points, but a track ends in a round cap
+    half its width beyond them. Against other copper the pad or via there
+    covers it; a rule area has no clearance to absorb it, so check it."""
+    for layer, points in wires:
+        for end in (points[0], points[-1]):
+            if tree.rule_area_overlap(corner_box(end, half_width), layer):
+                return True
+    return False
+
+
 def _copper_boxes(wires, vias, half_width, via_layers, via_half=None):
     via_half = via_half or half_width
     boxes: list[tuple[IntBox, frozenset[int]]] = []

src/freeroute/route/grid_router.py

@@ -33,6 +33,7 @@ import random
 from freeroute.board.board import BasicBoard
 from freeroute.board.items import ConductionArea, ObstacleArea, Pin
 from freeroute.geometry import IntBox, IntPoint
+from freeroute.geometry.polyline import corner_box
 
 __all__ = ["GridRouter", "RouteResult", "route_board"]
 
@@ -157,8 +158,23 @@ class GridRouter:
         heuristic_weight: float = 1.0,
         seed: int | None = None,
         route_first: frozenset | None = None,
+        access_cost: float = 0.0,
+        reserve_escapes: bool = False,
     ) -> None:
         self.board = board
+        # Pin access: while a pin still has connections to route, the cells
+        # its route would leave by (its end cells, the via it may need there,
+        # and the clearance around both) cost other nets this much extra, so
+        # they route round a fine-pitch pin's way out instead of sealing it.
+        self.access_cost = max(float(access_cost), 0.0)
+        self._doorways: dict[Node, list[tuple[int, int]]] = {}
+        self._pending: dict[int, int] = {}
+        # Escape reservations: before routing, every crowded (fine-pitch) pin
+        # gets a short way out to open board, and while it still has
+        # connections to route no other net may use those cells (nor come
+        # within clearance of them).
+        self.reserve_escapes = bool(reserve_escapes)
+        self._reserved: dict[Node, list[tuple[int, int]]] = {}
         # None keeps the deterministic order; a seed shuffles which connection
         # routes first, to measure how much a result owes to the order
         self.seed = seed
@@ -289,6 +305,10 @@ class GridRouter:
         margin = self.clearance + self.half_width
         outline = self.board.outline
         self._via_edge_block: set[Cell] = set()
+        # wire keepouts as boxes, to check a pin stub the way the exact engine will
+        self._keepout_boxes: dict[int, list[tuple[IntBox, bool]]] = {}
+        # pin end nodes no wire can reach without entering a keepout
+        self._via_only: set[Node] = set()
         if outline is not None:
             # cells too close to the real outline (rounded corners included):
             # for a trace on every layer, and separately for a via's wider copper
@@ -325,7 +345,13 @@ class GridRouter:
                     if box.is_empty():
                         continue
                     # the same distance the exact engine verifies against
-                    for cell in self._cells_in_box(box, margin):
+                    if item.blocks_wires:
+                        self._keepout_boxes.setdefault(item.layer, []).append(
+                            (box, item.clearance)
+                        )
+                    # a rule area takes no clearance: a trace may touch it
+                    reach = margin if item.clearance else self.half_width
+                    for cell in self._cells_in_box(box, reach):
                         if item.blocks_wires:
                             self._keepout.add((*cell, item.layer))
                         if item.blocks_vias:
@@ -352,6 +378,10 @@ class GridRouter:
         node = (*cell, layer)
         if wire_keepout and node in self._keepout:
             return None
+        if self._reserved:
+            for pin_id, owner_net in self._reserved.get(node, ()):
+                if owner_net != net_no and self._pending.get(pin_id, 0) > 0:
+                    return None  # another pin's reserved way out
         pads = self._pad_block.get(node)
         if pads and any(n != net_no for n in pads) and net_no not in self._pad_own.get(node, ()):
             return None
@@ -463,23 +493,34 @@ class GridRouter:
                     return path
             cx, cy, cl = current
             base = g_score[current]
-            for dx, dy in self._neighbours:
+            # A cell inside a wire keepout (a pin there, or where a via
+            # landed) may only be left by another via: a wire from it would
+            # start inside the keepout.
+            blocked = current in self._keepout or current in self._via_only
+            neighbours = () if blocked else self._neighbours
+            for dx, dy in neighbours:
                 cell = (cx + dx, cy + dy)
                 if not (0 <= cell[0] < self.cols and 0 <= cell[1] < self.rows):
                     continue
                 nxt = (*cell, cl)
                 if nxt in goal_stub:  # a pin end; a zone end is entered normally
+                    if nxt in self._keepout or nxt in self._via_only:
+                        continue  # a pin inside a keepout is reached by a via only
                     enter = goal_stub[nxt]
                 else:
                     enter = self._enter_cost(cell, cl, net_no, allow_ripup, conns)
                     if enter is None:
                         continue
+                    if self._doorways:
+                        enter += self._access(nxt, net_no)
                 step = 1.0 if dx == 0 or dy == 0 else math.sqrt(2)
                 self._relax(
                     current, nxt, base + step + enter, goal_cell, g_score, came_from, open_heap
                 )
             if len(self.layers) > 1:
                 g_via = base + self.via_cost
+                if self._doorways:
+                    g_via += self._access(current, net_no)
                 for layer in self.layers:
                     if layer == cl:
                         continue
@@ -512,7 +553,27 @@ class GridRouter:
             if _point_segment(self._cell_center(c), pin_location, end) < reach
         ]
 
-    def _stub_clear(self, pin: Pin, cell: Cell, layer: int, net_no: int, conns) -> bool:
+    def _stub_clear(
+        self, pin: Pin, cell: Cell, layer: int, net_no: int, conns, keepouts_only: bool = False
+    ) -> bool:
+        keepouts = self._keepout_boxes.get(layer)
+        if keepouts:
+            # the stub is off the grid, so check it exactly, as the exact
+            # engine will: its copper grown by clearance must miss every keepout
+            from freeroute.geometry.polyline import Polyline, PolylineShape
+
+            end = self._cell_center(cell)
+            if end != pin.location:
+                for tile in PolylineShape(Polyline([pin.location, end]), self.half_width).tiles():
+                    grown = tile.offset(self.clearance)
+                    if any(k.overlaps(grown if needs else tile) for k, needs in keepouts):
+                        return False
+                # the track's round end at the pin, for a rule area
+                cap = corner_box(pin.location, self.half_width)
+                if any(not needs and k.overlaps(cap) for k, needs in keepouts):
+                    return False
+        if keepouts_only:
+            return True
         for c in self._stub_cells(pin.location, cell):
             owner = self._cell_owner.get((*c, layer))
             if owner is not None and conns[owner].net_no != net_no:
@@ -618,6 +679,13 @@ class GridRouter:
             nodes |= self._escape_nodes(pin, net_no, conns, layers, (cx, cy))
         if not nodes:  # nothing clear: fall back to the nearest cell, as before
             nodes = {(cx, cy, layer) for layer in layers}
+            if self._keepout_boxes and not any(
+                self._stub_clear(pin, (cx, cy), layer, net_no, conns, keepouts_only=True)
+                for layer in layers
+            ):
+                # no wire can reach the pin without entering a keepout: the
+                # route has to arrive by a via, which goes in the pad
+                self._via_only.update(nodes)
         return nodes
 
     def _crowded(self, pin: Pin, net_no: int) -> bool:
@@ -765,8 +833,21 @@ class GridRouter:
                 if node not in self._cell_owner:
                     self._cell_owner[node] = conn.index
                     conn.trace_cells.append((c, layer))
+        # A pin inside a wire keepout can only leave by a via. Its stub to the
+        # cell centre would be track inside the keepout, so the via goes on
+        # the pin itself (a via in its own pad) and the stub is left out.
+        in_pad: dict[int, IntPoint] = {}
+        if len(wire_segs) > 1:
+            for idx, pin in ((0, conn.a_end), (len(wire_segs) - 1, conn.b_end)):
+                layer, cells = wire_segs[idx]
+                node = (*cells[0], layer)
+                walled = node in self._keepout or node in self._via_only
+                if isinstance(pin, Pin) and len(cells) == 1 and walled:
+                    in_pad[idx] = pin.location
         conn.wires = []
         for idx, (layer, cells) in enumerate(wire_segs):
+            if idx in in_pad:
+                continue
             points = [self._cell_center(c) for c in cells]
             if idx == 0 and isinstance(conn.a_end, Pin):
                 points.insert(0, conn.a_end.location)
@@ -776,7 +857,11 @@ class GridRouter:
             if len(points) >= 2:
                 conn.wires.append((layer, points))
         conn.vias = [self._cell_center(c) for c in conn.via_cells]
+        for idx, location in in_pad.items():
+            # via k joins wire segments k and k + 1
+            conn.vias[0 if idx == 0 else idx - 1] = location
         conn.routed = True
+        self._settle(conn, -1)
 
     def _rip(self, conn: _Connection) -> None:
         for cell, layer in conn.trace_cells:
@@ -799,6 +884,7 @@ class GridRouter:
         conn.vias = []
         conn.routed = False
         conn.rip_count += 1
+        self._settle(conn, +1)
 
     def _crossed_owners(self, path: list[Node], net_no: int, conns: list[_Connection]) -> set[int]:
         owners: set[int] = set()
@@ -814,6 +900,119 @@ class GridRouter:
                     owners.add(i)
         return owners
 
+    # --- pin access ---------------------------------------------------------
+
+    @staticmethod
+    def _group_pins(conn: _Connection):
+        return [*conn.a_group[0], *conn.b_group[0]]
+
+    def _build_doorways(self, conns: list[_Connection]) -> None:
+        """Map every cell that would close a pin's way out to that pin."""
+        spread = [(0, 0), *self._halo_offsets]
+        done: set[int] = set()
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                if id(pin) in done:
+                    continue
+                done.add(id(pin))
+                claim = (id(pin), conn.net_no)
+                exits: set[Node] = set()
+                for x, y, layer in self._end_nodes(pin, conn.net_no, conns):
+                    exits.add((x, y, layer))
+                    for c in self._via_cells((x, y)):
+                        exits.update((*c, other) for other in self.layers)
+                cells: set[Node] = set()
+                for x, y, layer in exits:
+                    for dx, dy in spread:
+                        if 0 <= x + dx < self.cols and 0 <= y + dy < self.rows:
+                            cells.add((x + dx, y + dy, layer))
+                for node in cells:
+                    self._doorways.setdefault(node, []).append(claim)
+
+    def _count_pending(self, conns: list[_Connection]) -> None:
+        """How many unrouted connections each pin is an end of."""
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                self._pending[id(pin)] = self._pending.get(id(pin), 0) + 1
+
+    def _reserve_escapes(self, conns: list[_Connection]) -> None:
+        """Give every crowded pin a way out before anything is routed."""
+        blocked: set[Node] = set()  # earlier escapes and their clearance
+        spread = [(0, 0), *self._halo_offsets]
+        seen: set[int] = set()
+        for conn in conns:
+            for pin in self._group_pins(conn):
+                if id(pin) in seen or not self._crowded(pin, conn.net_no):
+                    continue
+                seen.add(id(pin))
+                path = self._escape_path(pin, conn.net_no, conns, blocked)
+                if not path:
+                    continue
+                claim = (id(pin), conn.net_no)
+                for x, y, layer in path:
+                    for dx, dy in spread:
+                        node = (x + dx, y + dy, layer)
+                        if 0 <= node[0] < self.cols and 0 <= node[1] < self.rows:
+                            self._reserved.setdefault(node, []).append(claim)
+                            blocked.add(node)
+
+    def _escape_path(self, pin: Pin, net_no: int, conns, blocked: set[Node]) -> list[Node]:
+        """The shortest way from a pin to a cell clear of other nets' pads,
+        against pads, keepouts and earlier escapes only (breadth first, on
+        the pin's own layers, at most ``2 * _escape_cells`` long)."""
+        starts = [n for n in self._end_nodes(pin, net_no, conns) if n not in blocked]
+        came: dict[Node, Node | None] = dict.fromkeys(starts)
+        frontier = list(starts)
+        limit = 2 * self._escape_cells
+        for _depth in range(limit):
+            nxt: list[Node] = []
+            for node in frontier:
+                if node not in starts and self._open_ground(node, net_no):
+                    path = [node]
+                    while came[path[-1]] is not None:
+                        path.append(came[path[-1]])
+                    return path[::-1]
+                x, y, layer = node
+                for dx, dy in self._neighbours:
+                    n = (x + dx, y + dy, layer)
+                    if n in came or n in blocked:
+                        continue
+                    if not (0 <= n[0] < self.cols and 0 <= n[1] < self.rows):
+                        continue
+                    if not self._static_open(n, net_no):
+                        continue
+                    came[n] = node
+                    nxt.append(n)
+            frontier = nxt
+            if not frontier:
+                break
+        return []
+
+    def _open_ground(self, node: Node, net_no: int) -> bool:
+        """Clear of every other net's pad by a full trace spacing all round."""
+        x, y, layer = node
+        for dx, dy in self._halo_offsets:
+            n = (x + dx, y + dy, layer)
+            if not (0 <= n[0] < self.cols and 0 <= n[1] < self.rows):
+                return False
+            if not self._static_open(n, net_no):
+                return False
+        return True
+
+    def _settle(self, conn: _Connection, delta: int) -> None:
+        if not self._pending:
+            return
+        for pin in self._group_pins(conn):
+            if id(pin) in self._pending:
+                self._pending[id(pin)] += delta
+
+    def _access(self, node: Node, net_no: int) -> float:
+        """Extra cost for ``net_no`` to use a cell another pin still needs."""
+        for pin_id, owner_net in self._doorways.get(node, ()):
+            if owner_net != net_no and self._pending.get(pin_id, 0) > 0:
+                return self.access_cost
+        return 0.0
+
     # --- passes -------------------------------------------------------------
 
     def route(self) -> RouteResult:
@@ -822,6 +1021,12 @@ class GridRouter:
         self._conns = conns
         if not conns:
             return RouteResult(self.half_width)
+        if self.access_cost or self.reserve_escapes:
+            self._count_pending(conns)
+        if self.access_cost:
+            self._build_doorways(conns)
+        if self.reserve_escapes:
+            self._reserve_escapes(conns)
 
         passes = self.max_passes if self.rip_up else 1
         best_count = -1
@@ -1067,6 +1272,8 @@ def route_board(
     heuristic_weight: float = 1.0,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RouteResult:
     """Convenience wrapper: build a :class:`GridRouter` and route the board."""
     router = GridRouter(
@@ -1084,5 +1291,7 @@ def route_board(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return router.route()

src/freeroute/route/pipeline.py

@@ -82,6 +82,8 @@ def route_dsn_board(
     max_passes: int = 10,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> tuple[RouteResult, int, list[str]]:
     """Route a parsed :class:`DsnBoard`; return the board-unit result, the scale,
     and the layer names. ``layers`` restricts routing to those signal-layer
@@ -104,6 +106,8 @@ def route_dsn_board(
         max_passes=max_passes,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return result, scale, [layer.name for layer in dsn.layers]
 
@@ -146,12 +150,16 @@ def build_routing_result(
     edge_clearance_mm: float | None = None,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RoutingResult:
     """Route ``dsn`` (grid track) and convert to a DSN-unit RoutingResult."""
     route, scale, layer_names = route_dsn_board(
         dsn, layers=layers, rip_up=rip_up, max_passes=max_passes,
         edge_clearance_mm=edge_clearance_mm, resolution=resolution, seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return _to_routing_result(route, dsn, scale, layer_names)
 
@@ -169,6 +177,8 @@ def route_dsn_board_exact(
     diagonal: bool = False,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> tuple[ExactRouteResult, int, list[str]]:
     """Route a parsed :class:`DsnBoard` with the exact-geometry (orthogonal,
     DRC-verified) track; return the exact result, the scale, and layer names.
@@ -195,6 +205,8 @@ def route_dsn_board_exact(
         diagonal=diagonal,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return exact, scale, [layer.name for layer in dsn.layers]
 
@@ -212,6 +224,8 @@ def build_exact_routing_result(
     edge_clearance_mm: float | None = None,
     seed: int | None = None,
     route_first: frozenset | None = None,
+    access_cost: float = 0.0,
+    reserve_escapes: bool = False,
 ) -> RoutingResult:
     """Route ``dsn`` (exact track) and convert to a DSN-unit RoutingResult."""
     exact, scale, layer_names = route_dsn_board_exact(
@@ -226,6 +240,8 @@ def build_exact_routing_result(
         heuristic_weight=heuristic_weight,
         seed=seed,
         route_first=route_first,
+        access_cost=access_cost,
+        reserve_escapes=reserve_escapes,
     )
     return _to_routing_result(exact.result, dsn, scale, layer_names)
 

tests/board/test_build.py

@@ -254,3 +254,37 @@ def test_via_size_comes_from_the_via_padstack():
     from freeroute.route.pipeline import _via_half_board
 
     assert _via_half_board(parse_dsn(_PAD_DSN), 10) == 3000   # 0.6 mm via, board units
+
+
+# --- rule areas: overlap only ------------------------------------------------
+
+_CHANNEL_DSN = """(pcb channel.dsn
+  (parser (string_quote ")) (resolution um 10) (unit um)
+  (structure
+    (layer F.Cu (type signal)) (layer B.Cu (type signal))
+    (boundary (path pcb 0  0 0  40000 0  40000 -30000  0 -30000  0 0))
+    (keepout "{name}top" (polygon signal 0  18000 0  22000 0  22000 -14750  18000 -14750))
+    (keepout "{name}bottom" (polygon signal 0  18000 -15250  22000 -15250  22000 -30000  18000 -30000))
+    (rule (width 250) (clearance 150)))
+  (placement (component P (place P1 5000 -15000 front 0) (place P2 35000 -15000 front 0)))
+  (library (image P (pin pad 1 0 0)) (padstack pad (shape (circle F.Cu 600)) (attach off)))
+  (network (net N (pins P1-1 P2-1))))"""
+
+
+def test_a_keepout_named_rule_area_takes_no_clearance():
+    named = _areas(_CHANNEL_DSN.format(name="rule_area_"))
+    plain = _areas(_CHANNEL_DSN.format(name=""))
+    assert named and not any(a.clearance for a in named)
+    assert plain and all(a.clearance for a in plain)
+
+
+def _route_channel(name):
+    from freeroute.route.pipeline import build_exact_routing_result
+
+    return build_exact_routing_result(parse_dsn(_CHANNEL_DSN.format(name=name)), resolution=2)
+
+
+def test_a_trace_may_run_beside_a_rule_area_closer_than_clearance():
+    # the 0.5 mm channel fits a 0.25 mm trace, but not with 0.15 mm each side
+    assert _route_channel("rule_area_").unrouted == []
+    assert _route_channel("").unrouted != []

tests/board/test_search_tree.py

@@ -62,3 +62,37 @@ def test_has_violation_ignores_static_pad_pairs():
     # a routed trace of net 3 within clearance of pad net 1 -> violation
     tree.insert(shape(2, 3, 0, IntBox(11, 0, 20, 10), routed=True))
     assert tree.has_violation(clearance=20) is not None
+
+
+def test_a_rule_area_conflicts_only_on_overlap():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    near = IntBox(0, 0, 95, 100)  # 5 short of the area, well inside clearance 50
+    over = IntBox(0, 0, 105, 100)
+    assert not tree.clearance_conflict(near, 7, 0, 50)
+    assert tree.clearance_conflict(over, 7, 0, 50)
+
+
+def test_an_ordinary_keepout_still_needs_clearance():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100)))
+    assert tree.clearance_conflict(IntBox(0, 0, 95, 100), 7, 0, 50)
+
+
+def test_the_routed_board_check_treats_a_rule_area_the_same_way():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    tree.insert(TreeShape(2, 7, frozenset({0}), IntBox(0, 0, 95, 100), routed=True))
+    assert tree.has_violation(50) is None
+    tree.insert(TreeShape(3, 7, frozenset({0}), IntBox(150, 0, 160, 100), routed=True))
+    assert tree.has_violation(50) is not None
+
+
+
+def test_rule_area_overlap_sees_only_rule_areas():
+    tree = ShapeSearchTree()
+    tree.insert(TreeShape(1, -1, frozenset({0}), IntBox(100, 0, 200, 100), clearance=False))
+    tree.insert(TreeShape(2, -1, frozenset({0}), IntBox(300, 0, 400, 100)))
+    assert tree.rule_area_overlap(IntBox(90, 40, 110, 60), 0)
+    assert not tree.rule_area_overlap(IntBox(290, 40, 310, 60), 0)
+    assert not tree.rule_area_overlap(IntBox(90, 40, 110, 60), 1)

tests/dsn/test_reader.py

@@ -156,3 +156,26 @@ def test_unplaced_component_has_no_coords():
     place = board.placements[0].places[0]
     assert place.name == "U9"
     assert place.x is None and place.y is None
+
+
+# --- string_quote ----------------------------------------------------------
+
+_QUOTED = """(pcb q.dsn
+  (parser (string_quote {q}) (space_in_quoted_tokens on))
+  (resolution um 10) (unit um)
+  (structure (layer F.Cu (type signal)) (boundary (path pcb 0 0 0 1000 0 1000 1000 0 1000 0 0)))
+  (placement (component "SW1" (place SW1 100 100 front 0 (PN {pn}))))
+  (library)
+  (network)
+)"""
+
+
+def test_a_bare_apostrophe_is_an_atom_when_the_file_quotes_with_double_quotes():
+    # KiCad declares " and writes a keycap's part number as a bare '
+    board = parse_dsn(_QUOTED.format(q='"', pn="'"))
+    assert board.parser.string_quote == '"'
+
+
+def test_the_declared_quote_character_is_the_one_that_opens_strings():
+    board = parse_dsn(_QUOTED.format(q="'", pn="'10k 1%'").replace('"SW1"', "'SW1'"))
+    assert board.parser.string_quote == "'"

tests/route/test_escapes.py

@@ -0,0 +1,65 @@
+"""--reserve-escapes: a crowded pin keeps a way out until it is routed."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from freeroute.board import build_board
+from freeroute.dsn import parse_dsn
+from freeroute.route.grid_router import GridRouter
+from freeroute.route.pipeline import (
+    _rule_clearance_dsn,
+    _rule_width_dsn,
+    build_exact_routing_result,
+)
+
+SMD = (Path(__file__).resolve().parent.parent / "dsn" / "fixtures" / "smd_demo.dsn").read_text()
+
+
+def _router():
+    dsn = parse_dsn(SMD)
+    s = dsn.resolution.value
+    router = GridRouter(
+        build_board(dsn),
+        trace_width=round(_rule_width_dsn(dsn) * s),
+        clearance=round(_rule_clearance_dsn(dsn) * s),
+        orthogonal=True,
+        resolution=2,
+        reserve_escapes=True,
+    )
+    conns = router._build_connections()
+    router._conns = conns
+    router._count_pending(conns)
+    router._reserve_escapes(conns)
+    return router, conns
+
+
+def test_a_reserved_escape_is_closed_to_other_nets_and_open_to_its_own():
+    router, conns = _router()
+    assert router._reserved
+    node, claims = next(iter(router._reserved.items()))
+    pin_id, owner = claims[0]
+    other = next(c.net_no for c in conns if c.net_no != owner)
+    cell, layer = node[:2], node[2]
+    assert router._enter_cost(cell, layer, other, True, conns) is None  # even for rip-up
+    assert router._enter_cost(cell, layer, owner, False, conns) is not None or node in router._keepout
+
+
+def test_the_escape_is_released_once_its_pin_is_routed():
+    router, conns = _router()
+    node, claims = next(iter(router._reserved.items()))
+    other = next(c.net_no for c in conns if c.net_no != claims[0][1])
+    cell, layer = node[:2], node[2]
+    assert router._enter_cost(cell, layer, other, False, conns) is None
+    for c in conns:  # every connection routed: no pin is pending any more
+        router._settle(c, -1)
+    released = router._enter_cost(cell, layer, other, False, conns)
+    reserved, router._reserved = router._reserved, {}
+    assert released == router._enter_cost(cell, layer, other, False, conns)
+    router._reserved = reserved
+
+
+def test_reserving_escapes_loses_nothing_on_the_demo_board():
+    plain = build_exact_routing_result(parse_dsn(SMD), resolution=2)
+    reserved = build_exact_routing_result(parse_dsn(SMD), resolution=2, reserve_escapes=True)
+    assert len(reserved.unrouted) <= len(plain.unrouted)

tests/test_cli.py

@@ -157,6 +157,8 @@ def test_cli_supported_combinations_are_accepted(tmp_path):
         "seed": ["--seed", "3"],
         "orders": ["--orders", "2"],
         "promote": ["--promote-failures", "2"],
+        "access": ["--access-cost", "5"],
+        "escapes": ["--reserve-escapes"],
     }
     for engine, options in ENGINE_OPTIONS.items():
         for option in options: