Add PCB decoupling-proximity check from datasheet layout_rules.

PS-PLC-001 fires only with a LayoutGraph: 15 mm vs a 2 mm rule is an error, a 1 mm cap is silent, and a null millimetre uses the declared 3 mm default as WARNING.

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/pinscopex/eval_report.py

@@ -30,6 +30,7 @@ from backend.pinscopex.dnp_check import check_dnp_enables
 from backend.pinscopex.lifecycle import check_lifecycle
 from backend.pinscopex.errata_check import check_errata
 from backend.pinscopex.internal_features_check import check_internal_features
+from backend.pinscopex.placement_check import check_placement
 
 
 class EvalScores(BaseModel):
@@ -99,6 +100,7 @@ def run_deterministic_on_graph(graph: DesignGraph) -> list[Finding]:
     out.extend(check_lifecycle(graph, {}))
     out.extend(check_errata(graph, cmap))
     out.extend(check_internal_features(graph, cmap))
+    out.extend(check_placement(graph, cmap, None))
     return out
 
 

backend/pinscopex/placement_check.py

@@ -0,0 +1,129 @@
+"""G2: decoupling proximity on the PCB vs datasheet layout_rules.
+
+Runs only when a LayoutGraph is present. Empty layout_rules skip the IC.
+No capacitor on the rail does not invent a distance. A null
+max_distance_mm uses the declared DEFAULT_MAX_DISTANCE_MM (3 mm) as
+WARNING, never as an invented datasheet number.
+"""
+
+from __future__ import annotations
+
+import math
+
+from backend.pinscopex.models import (
+    ComponentConstraints,
+    ComponentType,
+    DesignGraph,
+    Finding,
+    LayoutGraph,
+    LayoutPad,
+)
+from backend.pinscopex.validate import _match_constraints
+
+DEFAULT_MAX_DISTANCE_MM = 3.0
+
+
+def _pad_for(layout: LayoutGraph, ref: str, number: str) -> LayoutPad | None:
+    fp = layout.footprints.get(ref)
+    if not fp:
+        return None
+    for pad in fp.pads:
+        if pad.number == str(number):
+            return pad
+    return None
+
+
+def _pin_number(cons: ComponentConstraints, token: str) -> str | None:
+    want = str(token).strip()
+    if not want:
+        return None
+    for pin in cons.pintable:
+        if str(pin.number) == want or (pin.name or "").upper() == want.upper():
+            return str(pin.number)
+    return None
+
+
+def _dist(a: LayoutPad, b: LayoutPad) -> float:
+    return math.hypot(a.x - b.x, a.y - b.y)
+
+
+def _net_for_pin(graph: DesignGraph, ref: str, pin_no: str) -> str | None:
+    for net in graph.nets.values():
+        for pc in net.pins:
+            if pc.component_ref == ref and str(pc.pin_number) == str(pin_no):
+                return net.name
+    return graph.pin_net(ref, pin_no)
+
+
+def check_placement(
+    graph: DesignGraph,
+    constraints_map: dict,
+    layout: LayoutGraph | None,
+) -> list[Finding]:
+    if layout is None or not layout.footprints:
+        return []
+    findings: list[Finding] = []
+    for ref, comp in graph.components.items():
+        if comp.component_type != ComponentType.IC:
+            continue
+        cons = _match_constraints(comp.mpn, constraints_map)
+        if not cons or not cons.layout_rules:
+            continue
+        for rule in cons.layout_rules:
+            if rule.get("kind") != "decoupling_proximity":
+                continue
+            pin_no = _pin_number(cons, str(rule.get("pin") or ""))
+            if not pin_no:
+                continue
+            net = _net_for_pin(graph, ref, pin_no)
+            if not net:
+                continue
+            ic_pad = _pad_for(layout, ref, pin_no)
+            if not ic_pad:
+                continue
+            caps = graph.capacitors_on_net(net)
+            cap_pads: list[LayoutPad] = []
+            for cref in caps:
+                fp = layout.footprints.get(cref)
+                if not fp:
+                    continue
+                for pad in fp.pads:
+                    if pad.net == net or pad.net == ic_pad.net:
+                        cap_pads.append(pad)
+            if not cap_pads:
+                continue
+            nearest = min(_dist(ic_pad, p) for p in cap_pads)
+            extracted = rule.get("max_distance_mm")
+            if extracted is None:
+                limit = DEFAULT_MAX_DISTANCE_MM
+                used_default = True
+                status = "WARNING"
+            else:
+                limit = float(extracted)
+                used_default = False
+                status = "ERROR"
+            if nearest <= limit:
+                continue
+            why = (
+                f"Datasheet does not specify mm; used default {DEFAULT_MAX_DISTANCE_MM:g} mm."
+                if used_default
+                else f"Datasheet max_distance_mm={limit:g}."
+            )
+            findings.append(Finding(
+                designator=ref,
+                mpn=comp.mpn or cons.mpn,
+                aspect="placement",
+                finding=(
+                    f"Decoupling on {net} is {nearest:.1f} mm from {ref}.{pin_no} "
+                    f"(limit {limit:g} mm)."
+                ),
+                why=why,
+                status=status,
+                recommendation="Place the decoupling capacitor closer to the supply pin.",
+                source="placement_check",
+                rule_id="PS-PLC-001",
+                net=net,
+                pins=[pin_no],
+                source_page=rule.get("source_page"),
+            ))
+    return findings

backend/services/validation.py

@@ -26,6 +26,7 @@ from backend.pinscopex.models import (
     ComponentType,
     DesignGraph,
     Finding,
+    LayoutGraph,
     NetType,
     ValidationReport,
 )
@@ -60,6 +61,7 @@ from backend.pinscopex.dnp_check import check_dnp_enables
 from backend.pinscopex.lifecycle import check_lifecycle, load_lifecycle_dir
 from backend.pinscopex.errata_check import check_errata
 from backend.pinscopex.internal_features_check import check_internal_features
+from backend.pinscopex.placement_check import check_placement
 
 TRACE_VERSION = 1
 
@@ -72,6 +74,7 @@ def _is_deterministic(f: Finding) -> bool:
 def _run_deterministic_checks(
     graph: DesignGraph, constraints_map: dict,
     lifecycle_map: dict | None = None,
+    layout: LayoutGraph | None = None,
 ) -> list[Finding]:
     """Run the deterministic graph checks, fail-soft per check — a check bug
     can never break the review or the report."""
@@ -94,6 +97,7 @@ def _run_deterministic_checks(
         ("lifecycle_check", lambda: check_lifecycle(graph, lifecycle_map)),
         ("errata_check", lambda: check_errata(graph, constraints_map)),
         ("internal_features_check", lambda: check_internal_features(graph, constraints_map)),
+        ("placement_check", lambda: check_placement(graph, constraints_map, layout)),
     ):
         try:
             out.extend(fn())
@@ -102,6 +106,17 @@ def _run_deterministic_checks(
     return out
 
 
+def _load_layout_graph(graph_path: str) -> LayoutGraph | None:
+    path = Path(graph_path).with_name("layout_graph.json")
+    if not path.is_file():
+        return None
+    try:
+        return LayoutGraph.model_validate_json(path.read_text())
+    except Exception:
+        log.exception("layout_graph.json invalid — skipping placement_check")
+        return None
+
+
 def _assistant_text(blocks) -> str:
     """Best-effort extraction of text content from a completion's raw
     assistant blocks. Provider-agnostic and never raises."""
@@ -709,7 +724,7 @@ async def validate_design_async(
         if loaded:
             lifecycle_map.update(loaded)
     deterministic_findings = _run_deterministic_checks(
-        graph, constraints_map, lifecycle_map,
+        graph, constraints_map, lifecycle_map, layout=_load_layout_graph(graph_path),
     )
 
     pdf_dir_path = Path(pdf_dir)