@protoboardai/ext-harness-cad 0.0.0-stage → 0.2.1

package/lib/job.ts

@@ -0,0 +1,273 @@
+/**
+ * UHD project → harness routing job.
+ *
+ * The job is everything the Python router needs and nothing it has to know
+ * about UHD: the assembled model as placed GLB bodies (obstacles), and for
+ * each wire harness its conductors, length and ends, each end resolved to
+ * the world positions its conductors land on (the linked part's pads, or the
+ * pins of the socket its plug goes into).
+ *
+ * Placement is UHD `assemble`, with the project's display placements for
+ * modules no mechanical link reaches (battery, receiver, capacitor): the same
+ * assembly the viewer draws.
+ *
+ * The job always holds every routable harness of the system: the router
+ * routes them in the system's order, each around the ones before it, and
+ * writes routes only for the job's `targets`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  assemble,
+  bodyKey,
+  combineFrames,
+  isConnector,
+  linkEndFrames,
+  type Assembly,
+  type GeometryFrame,
+  type InterfaceDef,
+  type InterfaceLink,
+  type Mat4,
+  type ModuleDef,
+} from "@deltarobotics/uhd";
+import type { Project } from "@protoboardai/core";
+import { SILICONE_OD_MM, WIRE_COLORS, termination, type Termination } from "./connectors.ts";
+
+export const JOB_SCHEMA = "protoboard.harness-cad.job/v0";
+type Vec3 = [number, number, number];
+
+export interface CableBuild {
+  /** Insulation colour per position of the first end (names from WIRE_COLORS or #rrggbb). */
+  colors: string[];
+  /** twisted: helix around the route; parallel: side by side (ribbon-like). */
+  bundle: "twisted" | "parallel";
+  /** mm per full turn when twisted. */
+  twist_pitch_mm?: number;
+  /** Conductor outside diameter override (mm); default from wire_gauge_awg. */
+  od_mm?: number;
+  /** Bare (uninsulated) conductors: component leads. */
+  bare?: boolean;
+  /** Stripped, tinned length at a soldered end (mm). */
+  strip_mm?: number;
+  /** Centre spacing of parallel conductors (mm); default: touching. */
+  spacing_mm?: number;
+}
+
+export interface JobEnd {
+  interfaceId: string;
+  linkId: string;
+  counterpart: string;
+  connector: string;
+  termination: Termination;
+  /** Where each position lands (world, mm) and the direction the conductor arrives from (outward from the part). */
+  pins: { position: string; at: Vec3; out: Vec3 }[];
+  /** The frame the harness end must carry: the counterpart's combined frame, normal reversed. */
+  frame: GeometryFrame;
+  /** Counterpart frame (outward). */
+  counterpartFrame: GeometryFrame;
+}
+
+export interface JobHarness {
+  id: string;
+  path: string;
+  name: string;
+  length_mm: number;
+  awg?: number;
+  conductors: { position: string; color: string; od: number; bare: boolean }[];
+  /** Conductor k connects ends[0].pins[k] to ends[1].pins[pair[k]]. */
+  pairs: number[];
+  build: Required<Pick<CableBuild, "bundle">> & CableBuild;
+  ends: JobEnd[];
+}
+
+export interface Job {
+  schema: typeof JOB_SCHEMA;
+  bodies: { key: string; glb: string; matrix: Mat4 }[];
+  harnesses: JobHarness[];
+  /** Harness definition ids whose routes the router writes (default: all). */
+  targets?: string[];
+  problems: string[];
+}
+
+const neg = (v: Vec3): Vec3 => [-v[0], -v[1], -v[2]];
+const add = (a: Vec3, b: Vec3, s = 1): Vec3 => [a[0] + b[0] * s, a[1] + b[1] * s, a[2] + b[2] * s];
+
+export function displayHints(p: Project): { root?: string; fixed: Record<string, Mat4> } {
+  const file = join(p.root, p.config.display ?? ".protoboard/display.json");
+  if (!existsSync(file)) return { fixed: {} };
+  const d = JSON.parse(readFileSync(file, "utf8")) as { spatial?: { root?: string; placements?: Record<string, { matrix: Mat4 }> } };
+  return { root: d.spatial?.root, fixed: Object.fromEntries(Object.entries(d.spatial?.placements ?? {}).map(([k, v]) => [k, v.matrix])) };
+}
+
+/** The assembly the viewer draws: UHD assemble from the display root, with display placements. */
+export function projectAssembly(p: Project): Assembly {
+  const { root, fixed } = displayHints(p);
+  const rootPath = root ? root.split("/") : [p.instances.find((i) => i.parent === "" && p.lookup(i.definition)?.interfaces.some((f) => f.geometry?.frame))?.path ?? ""];
+  return assemble(p.rootDef!, p.lookup, { root: rootPath, fixed });
+}
+
+/** Every link below the root with the module that declares it and its path. */
+function allLinks(root: ModuleDef, lookup: Project["lookup"]) {
+  const out: { owner: ModuleDef; prefix: string[]; link: InterfaceLink }[] = [];
+  const walk = (d: ModuleDef, prefix: string[]) => {
+    for (const link of d.links ?? []) out.push({ owner: d, prefix, link });
+    for (const c of d.children ?? []) {
+      const def = lookup(c.moduleDefId);
+      if (def && def.kind !== "harness" && def.children?.length) walk(def, [...prefix, c.id]);
+    }
+  };
+  walk(root, []);
+  return out;
+}
+
+export const cableBuild = (def: ModuleDef): CableBuild | undefined => def.traits?.find((t) => t.type === "cable_build")?.params as CableBuild | undefined;
+export const cableLength = (def: ModuleDef): number | undefined => {
+  const t = def.traits?.find((x) => x.type === "performance" && x.params?.kind === "cable");
+  return typeof t?.params?.length_mm === "number" ? (t.params.length_mm as number) : undefined;
+};
+const cableAwg = (def: ModuleDef): number | undefined => {
+  const t = def.traits?.find((x) => x.type === "performance" && x.params?.kind === "cable");
+  return typeof t?.params?.wire_gauge_awg === "number" ? (t.params.wire_gauge_awg as number) : undefined;
+};
+const connectorType = (i: InterfaceDef) => String(i.traits?.find((t) => t.type === "connector")?.params?.connector_type ?? "");
+
+/** Wire harness instances: kind harness with connector-composite ends and a cable_build trait. */
+export function wireHarnesses(asm: Assembly, only?: string[]) {
+  return asm.instances.filter(
+    (i) => i.kind === "harness" && i.def.interfaces.some(isConnector) && cableBuild(i.def) && (!only?.length || only.includes(i.def.id) || only.includes(i.path.join("/"))),
+  );
+}
+
+export function buildJob(p: Project): Job {
+  const problems: string[] = [];
+  const asm = projectAssembly(p);
+  const placed = new Map(asm.placements.map((x) => [x.key, x]));
+  const art = (def: string, id: string) => p.artifacts.find((a) => a.definition === def && a.id === id);
+
+  // obstacles: every placed body with a GLB, and every placed piece of hardware
+  const bodies: Job["bodies"] = [];
+  const defAt = new Map(asm.instances.map((i) => [bodyKey(i.path), i.def]));
+  // a placed module with children (a board carrying its components, a housing carrying its inserts) is not a leaf instance
+  const innerAt = (path: string[]): ModuleDef | undefined => {
+    let d: ModuleDef | undefined = p.rootDef;
+    for (const id of path) {
+      const ref: { moduleDefId: string } | undefined = d?.children?.find((c) => c.id === id);
+      d = ref ? p.lookup(ref.moduleDefId) : undefined;
+    }
+    return d;
+  };
+  for (const pl of asm.placements) {
+    const inner = defAt.has(bodyKey(pl.path)) ? undefined : innerAt(pl.path);
+    const def = defAt.get(bodyKey(pl.path)) ?? (inner?.artifacts?.some((a) => a.format === "glb" && a.role === "body") ? inner : undefined);
+    if (!def) continue;
+    const glb = (def.artifacts ?? []).find((a) => a.format === "glb" && a.role === "body" && (pl.body ? a.id === pl.body || a.provenance?.generatedFrom === pl.body : true));
+    const file = glb && art(def.id, glb.id);
+    if (file?.resolved && existsSync(file.resolved)) bodies.push({ key: pl.key, glb: file.resolved, matrix: pl.matrix });
+    else problems.push(`${pl.key}: no GLB body to route around (${glb?.filePath ?? "none declared"})`);
+  }
+  for (const hw of asm.hardware) {
+    const glb = (hw.def.artifacts ?? []).find((a) => a.format === "glb" && a.role === "body");
+    const file = glb && art(hw.def.id, glb.id);
+    if (file?.resolved && existsSync(file.resolved)) bodies.push({ key: `${hw.harness}/${hw.child}`, glb: file.resolved, matrix: hw.matrix });
+  }
+
+  const links = allLinks(p.rootDef!, p.lookup);
+  const harnesses: JobHarness[] = [];
+  for (const inst of wireHarnesses(asm)) {
+    const def = inst.def;
+    const build = cableBuild(def)!;
+    const length = cableLength(def);
+    const pathKey = inst.path.join("/");
+    if (!length) {
+      problems.push(`${pathKey} (${def.id}): no cable length (performance trait { kind: "cable", length_mm })`);
+      continue;
+    }
+    const parent = inst.path.slice(0, -1).join("/");
+    const childId = inst.path[inst.path.length - 1];
+    const ends: JobEnd[] = [];
+    for (const { owner, prefix, link } of links) {
+      if (prefix.join("/") !== parent) continue;
+      for (const [mine, theirs] of [[link.a, link.b], [link.b, link.a]] as const) {
+        if (!("child" in mine) || mine.child !== childId) continue;
+        const own = def.interfaces.find((i) => i.id === mine.interfaceId);
+        if (!own || !isConnector(own)) continue;
+        const other = linkEndFrames(owner, theirs, p.lookup, prefix, placed);
+        const linkId = [...prefix, link.id].join("/");
+        if (!other || !other.frames.length || !other.combined) {
+          problems.push(`${pathKey}.${own.id}: ${other?.label ?? "its counterpart"} has no geometry frame (link ${linkId})`);
+          continue;
+        }
+        if (!other.placed) {
+          problems.push(`${pathKey}.${own.id}: ${other.label} is not placed (no mate and no display placement)`);
+          continue;
+        }
+        const positions = (own.slots ?? []).map((s) => s.id);
+        const t = termination(connectorType(own), positions.length);
+        const c = other.combined;
+        let pins: JobEnd["pins"];
+        if (other.frames.length === positions.length) {
+          // one frame per position: a composed end (pads in slot order) or a parent port's leaves
+          pins = positions.map((pos, k) => ({ position: pos, at: other.frames[k].frame.origin as Vec3, out: other.frames[k].frame.normal as Vec3 }));
+        } else if (other.frames.length === 1 && c.xAxis) {
+          // a socket: positions along its xAxis at the connector's pitch
+          const pitch = t.pitch ?? 1;
+          pins = positions.map((pos, k) => ({ position: pos, at: add(c.origin as Vec3, c.xAxis as Vec3, (k - (positions.length - 1) / 2) * pitch), out: c.normal as Vec3 }));
+        } else {
+          problems.push(`${pathKey}.${own.id}: ${other.frames.length} frame(s) on ${other.label} for ${positions.length} position(s)`);
+          continue;
+        }
+        ends.push({
+          interfaceId: own.id,
+          linkId,
+          counterpart: other.label,
+          connector: connectorType(own),
+          termination: t,
+          pins,
+          counterpartFrame: c,
+          frame: { origin: c.origin, normal: neg(c.normal as Vec3), ...(c.xAxis ? { xAxis: c.xAxis } : {}) },
+        });
+      }
+    }
+    if (ends.length !== 2) {
+      problems.push(`${pathKey} (${def.id}): ${ends.length} routable end(s); the router handles point-to-point cables (2)`);
+      continue;
+    }
+    // conductor pairing from the harness's internal link (straight through unless childLinks say otherwise)
+    const wires = (def.links ?? []).find((l) => "self" in l.a && "self" in l.b);
+    const [ea, eb] = "self" in (wires?.a ?? {}) && wires!.a.interfaceId === ends[1].interfaceId ? [ends[1], ends[0]] : [ends[0], ends[1]];
+    const pairs = ea.pins.map((pin, k) => {
+      const cl = wires?.childLinks?.find((x) => x.a === pin.position);
+      const target = cl?.b ?? pin.position;
+      const idx = eb.pins.findIndex((q) => q.position === target);
+      return idx < 0 ? k : idx;
+    });
+    const awg = cableAwg(def);
+    const od = build.od_mm ?? (awg ? SILICONE_OD_MM[awg] : undefined);
+    if (!od) {
+      problems.push(`${pathKey} (${def.id}): no conductor diameter (wire_gauge_awg or cable_build.od_mm)`);
+      continue;
+    }
+    if (build.colors.length !== ea.pins.length) problems.push(`${pathKey}: ${build.colors.length} colour(s) for ${ea.pins.length} conductor(s)`);
+    harnesses.push({
+      id: def.id,
+      path: pathKey,
+      name: def.name ?? def.id,
+      length_mm: length,
+      awg,
+      conductors: ea.pins.map((pin, k) => ({ position: pin.position, color: WIRE_COLORS[build.colors[k]] ?? build.colors[k] ?? "#888888", od, bare: !!build.bare })),
+      pairs,
+      build: { ...build, bundle: build.bundle ?? "parallel" },
+      ends: [ea, eb],
+    });
+  }
+  // thickest cables first: they have the fewest ways through
+  harnesses.sort((a, b) => b.conductors[0].od * b.conductors.length - a.conductors[0].od * a.conductors.length);
+  return { schema: JOB_SCHEMA, bodies, harnesses, problems };
+}
+
+/** The harness end frames a route manifest records, as UHD frames. */
+export function endFrames(h: JobHarness): Record<string, GeometryFrame> {
+  return Object.fromEntries(h.ends.map((e) => [e.interfaceId, e.frame]));
+}
+
+export { combineFrames };

package/lib/route.ts

@@ -0,0 +1,216 @@
+/**
+ * Routed wire harnesses as a `cad` provider (docs/specs/tool-integrations.md
+ * §2–§4, PB-822).
+ *
+ *   generate  the assembled model → native design <dir>/harness-cad/route.json:
+ *             conductor paths, centreline, length fit, bend limits, clearance
+ *   export    route.json → out/body.glb, body.step, body.manifest.json
+ *   extract   the end frames the route was generated for, plus the artifacts
+ *   check     model vs route (ends, conductors, length changed), route vs
+ *             out/ (an export older than the route), and the route report:
+ *             length fit, the generator's notes, ends that no longer meet
+ *             their parts in the assembly
+ *
+ * Routing order is a property of the system (rigid ends first, then
+ * thickest), and each cable is routed around the ones before it. Generating
+ * one harness routes the harnesses before it again, in memory, so its route
+ * is the one a run over the whole system gives, whatever was generated
+ * before.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ArtifactDef, GeometryFrame, ModuleDef } from "@deltarobotics/uhd";
+import { sha256, stableStringify, type CapabilityBinding, type OperationContext, type Project, type ProjectDiagnostic } from "@protoboardai/core";
+import { HARNESS_CAD_TOOL, harnessCadArtifacts } from "./artifacts.ts";
+import { buildJob, cableLength, projectAssembly, wireHarnesses, type JobHarness } from "./job.ts";
+
+export const GENERATOR = fileURLToPath(new URL("../py/harness_cad.py", import.meta.url));
+export const python = () => process.env.PROTOBOARD_PYTHON || "python3";
+export const PROVIDER = "@protoboardai/ext-harness-cad";
+const TOOL = HARNESS_CAD_TOOL;
+
+/** What generate and export need from their context (a capability context, or the harness-cad alias's). */
+export type Writer = Pick<OperationContext, "project" | "writeOutput" | "log">;
+
+/** A harness definition and its provider directory. */
+export interface HarnessTarget {
+  id: string;
+  binding: Pick<CapabilityBinding, "dir" | "native" | "out">;
+}
+
+export interface RouteResult {
+  id: string;
+  path: string;
+  status: "ok" | "warning" | "failed";
+  notes: string[];
+  [k: string]: unknown;
+}
+
+/** The route file the router writes (py/harness_cad.py, ROUTE_SCHEMA). */
+export interface RouteFile {
+  schema: string;
+  harness: JobHarness;
+  notes: string[];
+}
+
+type Outcome<T> = { ok: true; value: T } | { ok: false; summary: string; problems?: string[] };
+
+export const harnessFiles = (b: Pick<CapabilityBinding, "native" | "out">) => ({ route: `${b.native}/route.json`, manifest: `${b.out}/body.manifest.json` });
+
+/** The harness's cad binding to this provider (its `cad.config.ts`), when it has a usable one. */
+export function harnessBinding(p: Project, id: string): CapabilityBinding | undefined {
+  return p.capabilities.find((b) => b.capability === "cad" && b.module === id && b.provider === PROVIDER && !b.problem && b.native);
+}
+
+function runPython(args: string[]): Outcome<{ harnesses: RouteResult[]; context?: RouteResult[]; map?: unknown }> {
+  try {
+    const stdout = execFileSync(python(), [GENERATOR, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 1800000, maxBuffer: 64 << 20, env: { ...process.env, PYTHONHASHSEED: "0" } });
+    return { ok: true, value: JSON.parse(stdout.trim().split("\n").pop()!) };
+  } catch (e) {
+    const err = e as { stderr?: string; message: string };
+    return { ok: false, summary: `generator failed: ${(err.stderr ?? err.message).trim().split("\n").slice(-3).join(" | ")}` };
+  }
+}
+
+/** generate: route the system's harnesses up to the last target and write each target's route.json. */
+export function routeHarnesses(ctx: Writer, targets: HarnessTarget[]) {
+  const p = ctx.project;
+  if (!p.rootDef) return { ok: false as const, summary: "the project has no root system" };
+  const job = buildJob(p);
+  for (const t of targets) {
+    const entries = job.harnesses.filter((h) => h.id === t.id);
+    if (!entries.length) {
+      const why = job.problems.filter((x) => x.includes(`(${t.id})`) || x.includes(t.id));
+      return { ok: false as const, summary: `${t.id} cannot be routed: ${why.join("; ") || "it is not a placed wire harness with connector ends and a cable_build trait"}`, problems: job.problems };
+    }
+    if (entries.length > 1) return { ok: false as const, summary: `${t.id} is used ${entries.length} times (${entries.map((h) => h.path).join(", ")}); routes are written per definition, so give each cable its own definition` };
+  }
+  job.targets = targets.map((t) => t.id);
+  const scratch = join(p.root, ".protoboard", "cache", "harness-cad", "route");
+  rmSync(scratch, { recursive: true, force: true });
+  mkdirSync(scratch, { recursive: true });
+  writeFileSync(join(scratch, "job.json"), stableStringify(job));
+  const run = runPython(["route", join(scratch, "job.json"), join(scratch, "routes")]);
+  if (!run.ok) return run;
+  const summary = run.value;
+  for (const r of summary.harnesses) {
+    const t = targets.find((x) => x.id === r.id)!;
+    if (r.status !== "failed") ctx.writeOutput(harnessFiles(t.binding).route, readFileSync(join(scratch, "routes", `${r.id}.route.json`)), `${r.path}: route (native design)`);
+    ctx.log(`${r.path}: ${r.status}${r.notes?.length ? ` — ${r.notes.join("; ")}` : ""}`);
+  }
+  if (summary.context?.length) ctx.log(`routed first, in memory: ${summary.context.map((r) => r.path).join(", ")}`);
+  rmSync(scratch, { recursive: true, force: true });
+  return { ok: true as const, value: { ...summary, problems: job.problems } };
+}
+
+/** export: build each target's bodies from its route.json and write the standard outputs. */
+export function exportHarnesses(ctx: Writer, targets: HarnessTarget[]) {
+  const p = ctx.project;
+  const missing = targets.filter((t) => !existsSync(join(p.root, harnessFiles(t.binding).route)));
+  if (missing.length) return { ok: false as const, summary: `${missing.map((t) => t.id).join(", ")}: no route (${harnessFiles(missing[0].binding).route}); run \`protoboard run cad:generate --module ${missing[0].id}\` first` };
+  const scratch = join(p.root, ".protoboard", "cache", "harness-cad", "export");
+  rmSync(scratch, { recursive: true, force: true });
+  mkdirSync(scratch, { recursive: true });
+  // one process per harness: OpenCascade numbers STEP assembly occurrences with a
+  // process-wide counter, so this keeps each body.step the same as its own cad:export gives
+  const results: RouteResult[] = [];
+  for (const t of targets) {
+    const run = runPython(["export", scratch, join(p.root, harnessFiles(t.binding).route)]);
+    if (!run.ok) return run;
+    results.push(...run.value.harnesses);
+  }
+  for (const r of results) {
+    if (r.status === "failed") continue;
+    const t = targets.find((x) => x.id === r.id)!;
+    const files = harnessFiles(t.binding);
+    const out = t.binding.out;
+    ctx.writeOutput(`${out}/body.glb`, readFileSync(join(scratch, `${r.id}.glb`)), `${r.path}: viewer mesh`);
+    if (existsSync(join(scratch, `${r.id}.step`))) ctx.writeOutput(`${out}/body.step`, readFileSync(join(scratch, `${r.id}.step`)), `${r.path}: swept solids`);
+    // the generator's manifest, named for out/: it describes body.*, and records the route it was exported from
+    const manifest = JSON.parse(readFileSync(join(scratch, `${r.id}.manifest.json`), "utf8")) as Record<string, unknown>;
+    const standard = { ...manifest, artifact: "body", exportedFrom: { file: files.route, digest: sha256(readFileSync(join(p.root, files.route))) } };
+    ctx.writeOutput(files.manifest, JSON.stringify(standard, null, 2) + "\n", `${r.path}: route manifest (end frames, lengths, bends, clearance)`);
+    ctx.log(`${r.path}: exported to ${out}${r.step !== "ok" ? ` (STEP ${r.step})` : ""}`);
+  }
+  rmSync(scratch, { recursive: true, force: true });
+  return { ok: true as const, value: { harnesses: results } };
+}
+
+const readJson = <T>(file: string): T | undefined => (existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as T) : undefined);
+
+/** extract: the frames the route gives the harness's end interfaces, and the artifacts that exist. */
+export function extractHarness(root: string, t: HarnessTarget) {
+  const route = readJson<RouteFile>(join(root, harnessFiles(t.binding).route));
+  if (!route) return { ok: false as const, summary: `${t.id} has no route (${harnessFiles(t.binding).route}); run \`protoboard run cad:generate --module ${t.id}\` first` };
+  const frames: Record<string, GeometryFrame> = Object.fromEntries(route.harness.ends.map((e) => [e.interfaceId, e.frame]));
+  const artifacts: ArtifactDef[] = harnessCadArtifacts({ dir: t.binding.dir, name: t.id, tool: TOOL }).filter((a) => a.filePath && existsSync(join(root, a.filePath)));
+  return { ok: true as const, value: { frames, artifacts } };
+}
+
+interface RouteManifest {
+  length_mm: number;
+  route_length_mm: number;
+  status: string;
+  notes: string[];
+  exportedFrom?: { digest?: string };
+}
+
+/** check: the harness's route against the model, its export against the route, and the route report. */
+export function harnessDiagnostics(p: Project, def: ModuleDef, t: HarnessTarget): Omit<ProjectDiagnostic, "validator">[] {
+  const out: Omit<ProjectDiagnostic, "validator">[] = [];
+  const source = p.definitions.get(def.id)?.origin.source;
+  if (!p.rootDef) return out;
+  const asm = projectAssembly(p);
+  const inst = wireHarnesses(asm).find((i) => i.def.id === def.id);
+  if (!inst) {
+    out.push({ code: "HARNESS_NOT_ROUTABLE", severity: "error", entity: { kind: "definition", id: def.id }, message: `${def.id} is not a wire harness ext-harness-cad can route (kind harness, connector ends, a cable_build trait, used in the system)`, source });
+    return out;
+  }
+  const key = inst.path.join("/");
+  const entity = { kind: "instance" as const, id: key };
+  const files = harnessFiles(t.binding);
+  const regenerate = `protoboard run cad:generate --module ${def.id}, then cad:export`;
+  const routeBytes = existsSync(join(p.root, files.route)) ? readFileSync(join(p.root, files.route)) : undefined;
+  if (!routeBytes) {
+    out.push({ code: "HARNESS_NOT_ROUTED", severity: "info", entity, message: `${key} (${def.id}) has no routed geometry; run \`${regenerate}\``, source });
+    return out;
+  }
+  const route = JSON.parse(routeBytes.toString("utf8")) as RouteFile;
+  const job = buildJob(p);
+  const now = job.harnesses.find((h) => h.id === def.id);
+  if (!now) {
+    out.push({ code: "HARNESS_ROUTE_STALE", severity: "warning", entity, message: `${key}: no longer routable (${job.problems.filter((x) => x.includes(def.id)).join("; ") || "see the model"}); its route was generated for an earlier model`, source });
+  } else if (stableStringify(now) !== stableStringify(route.harness)) {
+    const changed = (Object.keys(now) as (keyof JobHarness)[]).filter((k) => stableStringify(now[k]) !== stableStringify(route.harness[k]));
+    out.push({ code: "HARNESS_ROUTE_STALE", severity: "warning", entity, message: `${key}: the route was generated for a different ${changed.join(", ")}; regenerate (${regenerate})`, source });
+  }
+
+  const m = readJson<RouteManifest>(join(p.root, files.manifest));
+  if (!m) return out; // never exported: the standard-outputs check says so
+  if (m.exportedFrom?.digest !== sha256(routeBytes)) {
+    out.push({ code: "HARNESS_EXPORT_STALE", severity: "warning", entity, message: `${key}: ${t.binding.out}/ was exported from an earlier route than ${files.route}; run \`protoboard run cad:export --module ${def.id}\``, source });
+  }
+  const length = cableLength(def);
+  if (length !== undefined && Math.abs(length - m.length_mm) > 0.5) {
+    out.push({ code: "HARNESS_ROUTE_LENGTH", severity: "warning", entity, message: `${key}: modelled length ${length} mm, routed at ${m.length_mm} mm; regenerate (${regenerate})`, source });
+  }
+  if (Math.abs(m.route_length_mm - m.length_mm) > 1.5) {
+    out.push({ code: "HARNESS_ROUTE_LENGTH", severity: "warning", entity, message: `${key}: the routed cable is ${m.route_length_mm} mm, not its ${m.length_mm} mm (${m.route_length_mm > m.length_mm ? "too short to reach" : "the slack could not be laid clear"})`, source });
+  }
+  for (const note of m.notes ?? []) out.push({ code: "HARNESS_ROUTE_WARNING", severity: "warning", entity, message: `${key}: ${note}`, source });
+  const placed = asm.harnesses.find((h) => h.key === key);
+  if (!placed) {
+    out.push({ code: "HARNESS_ROUTE_STALE", severity: "warning", entity, message: `${key}: routed, but no end lands on a placed part`, source });
+    return out;
+  }
+  for (const e of placed.ends) {
+    if (e.status === "stale") {
+      out.push({ code: "HARNESS_ROUTE_STALE", severity: "warning", entity, message: `${key}.${e.interfaceId} is ${e.offsetMm} mm / ${e.angleDeg}° from ${e.counterpart}: regenerate (${regenerate})`, source });
+    } else if (e.status === "unplaced" || e.status === "no_geometry") {
+      out.push({ code: "HARNESS_ROUTE_STALE", severity: "info", entity, message: `${key}.${e.interfaceId}: ${e.counterpart} ${e.status === "unplaced" ? "is not placed" : "has no frame"}, so this end is not checked`, source });
+    }
+  }
+  return out;
+}

package/ops/cad.ts

@@ -0,0 +1,45 @@
+/**
+ * The `cad` capability for routed wire harnesses (tool-integrations §2–§4,
+ * PB-822): `protoboard run cad:<generate|export|extract|check> --module <id>`
+ * on a harness whose `cad.config.ts` names @protoboardai/ext-harness-cad. The
+ * work is in lib/route.ts, shared with the `harness-cad` alias.
+ */
+import type { CapabilityContext, CapabilityOperationFn, ExtractedFacts } from "@protoboardai/core";
+import { exportHarnesses, extractHarness, harnessDiagnostics, routeHarnesses, type HarnessTarget } from "../lib/route.ts";
+
+const target = (ctx: CapabilityContext): HarnessTarget => ({ id: ctx.module.id, binding: { dir: ctx.module.dir, native: ctx.module.native, out: ctx.module.out } });
+
+export const generate: CapabilityOperationFn = (ctx) => {
+  const r = routeHarnesses(ctx, [target(ctx)]);
+  if (!r.ok) return { status: "failed", summary: r.summary, ...(r.problems ? { data: { problems: r.problems } } : {}) };
+  const h = r.value.harnesses[0];
+  const before = r.value.context ?? [];
+  return {
+    status: h.status === "failed" ? "failed" : "succeeded",
+    summary: `${h.path}: ${h.status}${h.notes.length ? ` (${h.notes.join("; ")})` : ""}; routed around the parts${before.length ? ` and ${before.length} cable(s) routed before it` : ""}`,
+    data: { generator: "@protoboardai/ext-harness-cad/py/harness_cad.py", ...r.value },
+  };
+};
+
+export const exportOutputs: CapabilityOperationFn = (ctx) => {
+  const r = exportHarnesses(ctx, [target(ctx)]);
+  if (!r.ok) return { status: "failed", summary: r.summary };
+  const h = r.value.harnesses[0];
+  return {
+    status: h.status === "failed" ? "failed" : "succeeded",
+    summary: h.status === "failed" ? `${ctx.module.id}: ${h.notes.join("; ")}` : `${h.path}: body.glb, body.step${h.step === "ok" ? "" : ` (${h.step})`} and body.manifest.json in ${ctx.module.out}`,
+    data: h,
+  };
+};
+
+export const extract: CapabilityOperationFn = (ctx) => {
+  const r = extractHarness(ctx.project.root, target(ctx));
+  if (!r.ok) return { status: "failed", summary: r.summary };
+  const facts: ExtractedFacts = r.value;
+  return { status: "succeeded", summary: `${Object.keys(facts.frames!).length} end frames, ${facts.artifacts!.length} artifacts`, data: facts };
+};
+
+export const check: CapabilityOperationFn = (ctx) => {
+  const diagnostics = harnessDiagnostics(ctx.project, ctx.module.definition, target(ctx));
+  return { status: "succeeded", summary: `${diagnostics.length} finding(s)`, diagnostics };
+};

package/ops/harness-cad.ts

@@ -0,0 +1,91 @@
+import { loadProject, operationRecordFile, runCapabilityOperation, runCapabilityStep, type OperationFn, type OperationRecord } from "@protoboardai/core";
+import { projectAssembly, wireHarnesses } from "../lib/job.ts";
+import { PROVIDER, harnessBinding, harnessFiles, routeHarnesses, type HarnessTarget, type RouteResult } from "../lib/route.ts";
+
+const GENERATOR_ID = "@protoboardai/ext-harness-cad/py/harness_cad.py";
+
+/** One harness's step, as the alias reports it. */
+interface AliasStep {
+  module: string;
+  operation: string;
+  status: OperationRecord["status"];
+  summary: string;
+  /** The step's operation record (project-relative). */
+  record: string;
+  outputs: string[];
+}
+const aliasStep = (module: string, r: OperationRecord): AliasStep => ({ module, operation: r.operation, status: r.status, summary: r.summary, record: operationRecordFile(r), outputs: r.outputs.map((o) => o.path) });
+
+export { GENERATOR, python } from "../lib/route.ts";
+
+/**
+ * harness-cad: the `cad` capability's generate and export for every wire
+ * harness (or the named ones), in one routing run. Each harness needs a
+ * `cad.config.ts` naming @protoboardai/ext-harness-cad; its route goes to
+ * `<dir>/harness-cad/route.json` and its bodies to `<dir>/out/`, exactly as
+ * `protoboard run cad:generate` and `cad:export --module <id>` write them,
+ * and each is recorded as that harness's own `cad:generate` and `cad:export`
+ * run, so the release traces every cable's `out/` (the alias's own record
+ * writes nothing and lists them). The routes are written first; the project
+ * is then loaded anew, so each export records the harness as its new route
+ * makes it.
+ * The `routes` check and each harness's `cad:check` then confirm that every
+ * routed end still meets its part.
+ */
+export const harnessCad: OperationFn = async (ctx) => {
+  const p = ctx.project;
+  if (!p.rootDef) return { status: "failed", summary: "the project has no root system" };
+  const only = ctx.inputs.harness?.split(",").map((s) => s.trim()).filter(Boolean);
+  const found = wireHarnesses(projectAssembly(p), only);
+  if (!found.length) return { status: "failed", summary: only?.length ? `no wire harness ${only.join(", ")} (definition id or instance path) with a cable_build trait` : "no wire harness with a cable_build trait to route" };
+  const targets: HarnessTarget[] = [];
+  const unbound: string[] = [];
+  for (const inst of found) {
+    if (targets.some((t) => t.id === inst.def.id)) continue;
+    const binding = harnessBinding(p, inst.def.id);
+    if (binding) targets.push({ id: inst.def.id, binding });
+    else unbound.push(`${inst.path.join("/")} (${inst.def.id}) has no cad.config.ts naming ${PROVIDER}; add one in its provider directory, e.g. src/harnesses/${inst.def.id}/cad.config.ts: export default defineCapabilityConfig({ provider: "${PROVIDER}", module: "${inst.def.id}" })`);
+  }
+  if (!targets.length) return { status: "failed", summary: unbound[0], data: { problems: unbound } };
+
+  // one routing run over every target, held in memory; then each target's route is written by its own cad:generate step
+  const held = new Map<string, { content: string | Buffer; description?: string }>();
+  const routed = routeHarnesses({ project: p, log: ctx.log, writeOutput: (path, content, description) => held.set(path, { content, description }) }, targets);
+  if (!routed.ok) return { status: "failed", summary: routed.summary, data: { problems: [...(routed.problems ?? []), ...unbound] } };
+  const steps: AliasStep[] = [];
+  const generated = new Set<string>();
+  for (const r of routed.value.harnesses) {
+    const t = targets.find((x) => x.id === r.id)!;
+    const rec = await runCapabilityStep(p, "cad", "generate", t.id, (sctx) => {
+      const route = harnessFiles(t.binding).route;
+      const file = held.get(route);
+      if (r.status === "failed" || !file) return { status: "failed", summary: `${r.path}: failed${r.notes.length ? ` (${r.notes.join("; ")})` : ""}`, data: { generator: GENERATOR_ID, harnesses: [r] } };
+      sctx.writeOutput(route, file.content, file.description);
+      return { status: "succeeded", summary: `${r.path}: ${r.status}${r.notes.length ? ` (${r.notes.join("; ")})` : ""}; routed in one run with ${targets.length - 1} other cable(s) (run harness-cad)`, data: { generator: GENERATOR_ID, harnesses: [r], problems: routed.value.problems } };
+    });
+    steps.push(aliasStep(t.id, rec));
+    if (rec.status === "succeeded") generated.add(t.id);
+  }
+  // the routes just written are what each harness definition reads (routedHarness): export from the project as it is now
+  const now = generated.size ? await loadProject(p.root, { checks: false, fresh: true }) : p;
+  const exported = new Map<string, RouteResult>();
+  for (const t of targets.filter((x) => generated.has(x.id))) {
+    const rec = await runCapabilityOperation(now, "cad", "export", t.id);
+    steps.push(aliasStep(t.id, rec));
+    if (rec.status === "succeeded") exported.set(t.id, rec.data as RouteResult);
+  }
+
+  const results = routed.value.harnesses.map((r) => {
+    const e = exported.get(r.id);
+    if (e) return { ...e, search_s: r.search_s };
+    return generated.has(r.id) ? { ...r, status: "failed" as const, notes: [...r.notes, "export failed (see its cad:export record)"] } : r;
+  });
+  const failed = results.filter((h) => h.status === "failed");
+  const warned = results.filter((h) => h.status === "warning");
+  const problems = [...routed.value.problems, ...unbound];
+  return {
+    status: failed.length === results.length ? "failed" : "succeeded",
+    summary: `${results.length - failed.length}/${results.length} harness(es) routed and exported, each with its cad:generate and cad:export record${warned.length ? `; ${warned.length} with warnings (${warned.map((h) => h.path).join(", ")})` : ""}${failed.length ? `; failed: ${failed.map((h) => h.path).join(", ")}` : ""}${problems.length ? `; ${problems.length} problem(s) in the model` : ""}`,
+    data: { generator: GENERATOR_ID, problems, map: routed.value.map, harnesses: results, outputs: Object.fromEntries(targets.map((t) => [t.id, t.binding.dir])), steps },
+  };
+};