partforge 0.77.0 → 0.79.0

package/src/framework/oracle/describe/accept.js

@@ -0,0 +1,188 @@
+// The confirm half of propose-then-confirm (spec §2.8). Segmentation and the feature
+// rules produce CANDIDATES; this decides which are real, in what order, and how sure
+// we are — by building each one and measuring it against the source mesh.
+//
+// Three properties are load-bearing.
+//
+// ONE CACHE BRACKET. geometry/solid-cache.js scopes retention to the current build's
+// graph: each begin()/end() pair rebuilds the retained set and DISPOSES anything not
+// re-used that round. A search loop that opened a bracket per candidate would evict its
+// own shared subtrees on every iteration — quadratic rebuilds and WASM churn on a part
+// that should be nearly free. So the whole loop runs inside exactly one bracket, and
+// every candidate's geometry stays warm and shared for its duration.
+//
+// HARD BUDGET. Booleans are the cost centre and the candidate list is attacker-shaped
+// (it grows with mesh complexity, not with anything we control). The budget counts
+// CANDIDATE ATTEMPTS, not raw boolean calls — see the loop's own comment below for
+// exactly what one attempt costs in real booleans, which varies by case — and running
+// out DEGRADES INTO RESIDUAL rather than throwing: an over-budget describe returns a
+// partial, honestly-scored report, which is exactly what a caller can act on.
+//
+// CONFIDENCE IS THE GAIN. A feature's confidence is the marginal xor reduction that
+// admitted it, not a separate estimate invented afterwards. That is what makes the
+// number falsifiable — it is a measurement of how much of the part that feature
+// explains.
+//
+// The ONLY kernel-touching file in describe/.
+
+// Named for what it actually counts (see the loop's own comment): CANDIDATE ATTEMPTS,
+// not boolean operations. One attempt costs 0-2 real booleans depending on the
+// candidate's op and whether a base body exists yet, so this is a bound on search
+// WORK, not a boolean-op budget a caller could size against a WASM-call cost model.
+export const DEFAULT_ATTEMPT_BUDGET = 48;
+// A candidate must explain at least this fraction of the source volume to be worth a
+// line in the report. Below it, the "feature" is tessellation noise.
+const MIN_GAIN_FRACTION = 1e-4;
+
+// Symmetric-difference volume — the same measure measure.js uses for the `reference`
+// deviation fact, so a describe score and a verify ref-gate are directly comparable.
+// One boolean and two volume reads; no meshing, no rasterisation. `cut`/`union`/
+// `intersect` are binary methods ON A SOLID (`a.intersect(b)`), not kernel-level free
+// functions — kernel.js's own JSDoc has the full Solid method table; there is no
+// `kernel.intersect(a, b)`. Neither operand needs `.clone()` first: unlike the OCCT
+// backend (whose replicad shapes ARE consumed by a transform — see AGENTS.md),
+// Manifold's boolean methods return a new solid and leave both operands live and
+// reusable, exactly as measure.js's own `solid.intersect(ref).volume()` and
+// assembly.js's pairwise overlap check already rely on.
+function xorVolume(a, b) {
+  const inter = a.intersect(b).volume();
+  return a.volume() + b.volume() - 2 * inter;
+}
+
+export function acceptCandidates(kernel, source, candidates, opts = {}) {
+  const budget = opts.budget ?? DEFAULT_ATTEMPT_BUDGET;
+  const sourceVolume = source.volume();
+  const accepted = [];
+  // Counts CANDIDATE ATTEMPTS (one per pass through the `for` loop below), not real
+  // boolean calls — see that loop's own comment for the exact per-attempt cost, which
+  // is 0, 1, or 2 real booleans depending on the candidate's op and whether `current`
+  // is null. Reported back as `budgetSpent` (name kept as-is — see that field's own
+  // comment on why) rather than renamed to `attemptsSpent`.
+  let attempts = 0;
+  // Every candidate object that reached the loop body at least once — keyed by
+  // reference, not by `cand.key`/`cand.featureKey`, since this file never assumes a
+  // candidate carries either (test/describe-accept.test.js's own fixtures only give
+  // theirs a bare `key`, and other callers may give none at all). This is what lets a
+  // caller (describe.js) tell "budget ran out before this candidate ever got a turn"
+  // apart from "this candidate got a turn — every round it was in — and never won
+  // one" for whatever's left in `pending` at the end (fix round 2, IMPORTANT 2): a
+  // rejected feature and a budget-starved one both report `volumeShare: null` and
+  // are otherwise indistinguishable, which matters to a rebuilder deciding whether to
+  // retry with a bigger `--budget` or accept that a feature genuinely doesn't fit.
+  // NOTE on the one case this deliberately does NOT collapse (round 3 CRITICAL fix): a
+  // `cut` candidate that gets a turn while `current === null` (`"nothing to cut from
+  // yet"`, below) never has a gain computed for it, so it is NOT added here — only a
+  // candidate that actually ran a boolean (a real gain measurement) or whose `.build()`
+  // genuinely threw counts as attempted. Earlier this Set included the no-base-yet case
+  // too, which made a starved `--budget` report `"rejected"` for a feature the search
+  // simply never reached with a base to cut from — provably wrong, since raising the
+  // budget alone (no code change) turned that same feature into a real, positive share.
+  const attempted = new Set();
+
+  // The single bracket. `describe:accept` is deliberately its own partition name, not a
+  // display sub-part's: the cross-partition hash index still lets it ADOPT geometry the
+  // viewer already built, while its own eviction at end() cannot throw away what the
+  // viewer is showing. Same reasoning as oracle/build.js's `oracle:view:` naming.
+  kernel.beginSubPart?.("describe:accept");
+  try {
+    let current = null;                  // the reconstruction so far
+    let currentXor = sourceVolume;       // an empty reconstruction differs by the whole part
+    const pending = [...candidates];
+
+    while (pending.length && attempts < budget) {
+      let best = null;
+      for (const cand of pending) {
+        if (attempts >= budget) break;
+        // Real boolean cost of THIS attempt, not the `attempts` counter below (that
+        // counts the attempt itself, always by 1, regardless of how many WASM
+        // booleans it took) — spelled out here because it is not uniform and a
+        // reader sizing the budget against boolean-call cost needs the real number:
+        //   • op "cut",   current === null → 0 booleans (trial is set to null with
+        //     no kernel call at all — "nothing to cut from yet" — and skipped below)
+        //   • op "union", current === null → 1 boolean (no union call needed either,
+        //     trial IS piece; the only boolean is xorVolume's own intersect below)
+        //   • either op,  current !== null → 2 booleans (the cut/union that builds
+        //     `trial`, plus xorVolume's intersect)
+        // So budget=N bounds attempts, and — once any candidate has been accepted,
+        // which is the common case for a multi-feature part — real boolean work at
+        // roughly 2N, not N. Verified directly: a 4-candidate, 2-op-type search
+        // (1 accepted union then 1 accepted cut) reports `budgetSpent: 9` against
+        // 12 real boolean calls counted by wrapping the kernel.
+        let trial;
+        let noBaseYet = false;               // "nothing to cut from yet" — no gain measured
+        try {
+          const piece = cand.build();
+          if (current === null && cand.op === "cut") {
+            trial = null;
+            noBaseYet = true;
+          } else {
+            trial = current === null ? piece
+              : cand.op === "cut" ? current.cut(piece)
+              : current.union(piece);
+          }
+        } catch {
+          // A candidate whose geometry will not build is not an error — it is simply
+          // not a description of this mesh. Drop it and keep going.
+          trial = null;
+        }
+        attempts++;
+        // Only count this as a real attempt (accept.js's own contract with describe.js
+        // — see the Set's declaration comment) when a gain was actually measured or the
+        // candidate's own geometry genuinely failed to build. `noBaseYet` is neither: no
+        // boolean ever ran and no verdict was reached, so leaving it out of `attempted`
+        // is what lets describe.js report `"budget"` instead of `"rejected"` for a cut
+        // candidate that only ever got a turn before any base body existed — round 3's
+        // CRITICAL finding: with the old blanket `attempted.add(cand)` above, THIS is
+        // exactly the case that reported `"rejected"` (`--budget 2`, the washer fixture)
+        // for a feature that becomes a real 19% share at `--budget 3` — the search never
+        // rejected it, it just never got there.
+        if (!noBaseYet) attempted.add(cand);
+        if (!trial) continue;
+        const xor = xorVolume(trial, source);
+        const gain = currentXor - xor;
+        if (gain > sourceVolume * MIN_GAIN_FRACTION && (!best || gain > best.gain)) {
+          best = { cand, trial, xor, gain };
+        }
+      }
+      if (!best) break;                  // nothing left improves the reconstruction
+
+      current = best.trial;
+      currentXor = best.xor;
+      accepted.push({
+        candidate: best.cand,
+        gain: best.gain / sourceVolume,          // normalised: comparable across parts
+        cumulativeXor: currentXor,
+        order: accepted.length,
+      });
+      pending.splice(pending.indexOf(best.cand), 1);
+    }
+
+    const xorFraction = sourceVolume > 0 ? currentXor / sourceVolume : 1;
+    return {
+      accepted,
+      residual: { xorVolume: currentXor, xorFraction },
+      score: {
+        explainedVolumeFraction: Math.max(0, 1 - xorFraction),
+        xorFraction,
+        xorVolume: currentXor,
+      },
+      // Candidate attempts, not real boolean calls — see `attempts`'s own comment
+      // above and the per-attempt cost breakdown in the loop. Kept as `budgetSpent`
+      // (not renamed to `attemptsSpent`) because it is a documented cross-task
+      // interface field T12's orchestrator consumes by this exact name (SDD
+      // progress ledger, T10→T12 interface row); the field's MEANING is what moved,
+      // not its shape, so a rename here would be a breaking, undocumented surprise
+      // for that consumer rather than a fix.
+      budgetSpent: attempts,
+      budgetExceeded: attempts >= budget && pending.length > 0,
+      // Candidate OBJECTS (not keys) that reached at least one build+evaluate attempt
+      // — see this Set's own declaration comment above for why by-reference and what
+      // it does and doesn't distinguish. Every accepted candidate is trivially a
+      // member too (it can't have been accepted without at least one attempt); the
+      // caller only needs to consult this for candidates NOT in `accepted`.
+      attempted,
+    };
+  } finally {
+    kernel.endSubPart?.();
+  }
+}

package/src/framework/oracle/describe/features/dressups.js

@@ -0,0 +1,173 @@
+// Fillet and chamfer rules.
+//
+// Both are TRANSITION surfaces: narrow strips whose job is to soften the meeting of
+// two larger neighbours. That is what distinguishes them from a small functional
+// face, and it is why the rules test the strip's relationship to its neighbours
+// rather than its size alone. A 2mm-wide plane between two walls is a chamfer; a
+// 2mm-wide plane bounded by four other 2mm planes is just a small face.
+//
+// Fillet:  cylinder or torus, tangent to both of two PRIMARY neighbours (the arc
+//          convexity gives inside vs outside rounding).
+// Chamfer: plane OR cone (a countersink is a revolved chamfer), meeting each
+//          primary neighbour at a consistent angle that is neither ~0 nor ~90
+//          degrees.
+//
+// PRIMARY neighbours are the two LONGEST-shared-boundary arcs, not "however many
+// arcs this surface has total" (round 1 review: the original premise required
+// `arcs.length === 2`, which no finite straight chamfer/fillet can ever satisfy —
+// a chamfer cut along a box edge of finite length necessarily terminates against
+// two more end faces besides the two walls it actually blends, giving FOUR arcs,
+// not two; verified directly against a chamfered box, whose bevel plane has arcs
+// of length ~30mm to the two walls it blends and ~4.2mm to the two end caps it
+// merely runs into). Selecting by length picks out the two it actually blends and
+// treats the incidental end walls as exactly that: incidental, not disqualifying.
+//
+// TANGENCY, for a cylinder candidate, means its two PRIMARY arcs are STRAIGHT
+// (`kind === "line"`): a constant-radius fillet run along a straight edge is
+// tangent to its neighbours along a line parallel to its own axis. A CIRCULAR
+// primary arc between a cylinder and a plane means the opposite: the cylinder's
+// axis runs perpendicular to that plane, punching straight through it — a bore's
+// or a boss's mouth, not a tangent blend (verified directly against
+// annulusPlate(10,4,3,48): its bore is a plain cylinder with exactly two circular
+// arcs to the two larger cap planes, and without this check it satisfies every
+// other test here and gets reported as a fillet). A doubly-curved torus fillet's
+// own tangent arcs ARE genuinely circular (it blends a curved edge), so this
+// guard is cylinder-only.
+//
+// WIDTH is compared against the primary neighbours' own EXTENT as a length, not
+// an area (round 1 review: the original area-ratio test — this surface's area
+// against each neighbour's — silently drops an ordinary torus fillet as it grows,
+// because the neighbouring end cap shrinks by 2x the fillet radius as the fillet
+// widens, which erodes the AREA ratio far faster than the actual geometry
+// justifies; measured directly: r/R = 0.125 and 0.25 fillets, both completely
+// normal roundovers, missed entirely under the old area test). A dress-up is
+// narrow in ONE dimension, so the comparison is a length against a length: this
+// surface's own width (a fillet's radius; a chamfer's or countersink's area
+// divided by its longest primary arc) against the LARGER of the two primary
+// arcs' own measured radius (circular arcs — the natural "how big is the thing
+// this blends" reference; e.g. a fillet's tangent seam to its shaft lands almost
+// exactly on the shaft's own radius) or length (straight arcs, which have no
+// radius). Reusing the larger of the two, rather than requiring both
+// individually, matters because a fillet's two neighbours differ in this exact
+// reference by very close to the fillet's own radius (a torus fillet's tangent
+// circle on the flat-cap side is smaller than on the shaft side by ~r) — testing
+// against the smaller one would make the threshold tighter than the geometry
+// warrants.
+//
+// Pure leaf. See spec §2.5.
+import { arcsOf } from "../surface-graph.js";
+
+// A dress-up must be materially narrower than what it joins, or it is a face in
+// its own right. Ratio, not an absolute size, so it scales with the part.
+// Verified against a torus fillet sweep at r/R = 0.0625, 0.125 and 0.25 (all
+// pass with this threshold; the largest, r=2 against a shaft radius R=8, checks
+// 2 <= 8*0.34 = 2.72) while the washer bore (rejected by the tangency guard
+// above, not by this ratio) stays rejected regardless.
+const MAX_WIDTH_RATIO = 0.34;
+// Chamfer angle band: outside this it is a tangent continuation or a square corner.
+const MIN_CHAMFER_RAD = 0.15, MAX_CHAMFER_RAD = Math.PI / 2 - 0.15;
+const round3 = (v) => Math.round(v * 1000) / 1000;
+
+const byId = (graph) => new Map(graph.surfaces.map((s) => [s.id, s]));
+const other = (arc, id) => (arc.between[0] === id ? arc.between[1] : arc.between[0]);
+const dot = (a, b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2];
+// A primary arc's own reference length: its measured circle radius when curved,
+// or its own run length when straight (a straight arc has no radius to offer).
+const arcExtent = (arc) => arc.radius ?? arc.length;
+
+// A neighbour's own fitted geometry, not its segmentation surface id (round 2
+// review: `s0`/`s1` are assigned in triangle-DISCOVERY order — the same defect
+// prismatic.js's key had — so they renumber under a triangle-order permutation
+// of the same geometry, which must never change what a fillet/chamfer's own
+// key is). Covers every surface type a dress-up's primary neighbour can be;
+// `round3` absorbs the float-associativity noise a permuted summation/fit
+// order introduces (Task 4's own ruling, R29) — real geometry never differs at
+// 3-decimal precision, only float dust does.
+const vec3 = (a) => a.map(round3).join(",");
+function surfaceSignature(s) {
+  if (s.type === "plane") return `plane:${round3(s.fit.offset)}:${vec3(s.fit.normal)}`;
+  if (s.type === "cylinder") return `cylinder:${round3(s.fit.radius)}:${vec3(s.fit.axis.direction)}:${vec3(s.fit.axis.origin)}`;
+  if (s.type === "cone") return `cone:${round3(s.fit.halfAngle)}:${vec3(s.fit.apex)}:${vec3(s.fit.direction)}`;
+  if (s.type === "torus") return `torus:${round3(s.fit.majorRadius)}:${round3(s.fit.minorRadius)}:${vec3(s.fit.center)}`;
+  return `${s.type}:${round3(s.area)}`;   // any future surface type
+}
+// "|", not "-": a signature can itself contain "-" (a negative coordinate), and
+// this only ever needs to be a stable SORT key, never parsed back apart.
+const sortSignatures = (nbrs) => nbrs.map(surfaceSignature).sort().join("|");
+
+export function detectDressups(graph) {
+  const surfaces = byId(graph);
+  const out = [];
+
+  for (const s of graph.surfaces) {
+    const arcs = arcsOf(graph, s.id);
+    if (arcs.length < 2) continue;
+
+    // The two PRIMARY neighbours: the longest-shared-boundary arcs. Any other
+    // arcs (a finite chamfer/fillet's incidental end walls) are ignored below.
+    const primary = [...arcs].sort((a, b) => b.length - a.length).slice(0, 2);
+    const nbrs = primary.map((a) => surfaces.get(other(a, s.id)));
+    if (nbrs.some((n) => !n)) continue;
+
+    if (s.type === "cylinder" && !primary.every((a) => a.kind === "line")) continue;
+
+    const extent = Math.max(...primary.map(arcExtent));
+    const fitsAsStrip = (width) => width <= extent * MAX_WIDTH_RATIO;
+
+    if (s.type === "cylinder" || s.type === "torus") {
+      const radius = s.type === "cylinder" ? s.fit.radius : s.fit.minorRadius;
+      if (!fitsAsStrip(radius)) continue;
+      out.push({
+        id: null,
+        key: `fillet:${round3(radius)}:${sortSignatures(nbrs)}`,
+        type: "fillet", radius,
+        between: nbrs.map((n) => n.id),
+        convexity: primary[0].convexity,
+        surfaces: [s.id],
+        evidence: { arcs: arcs.length, widthRatio: round3(radius / extent), fitRms: s.fit.rms },
+      });
+      continue;
+    }
+
+    if (s.type === "plane" && nbrs.every((n) => n.type === "plane")) {
+      const angles = nbrs.map((n) => Math.acos(Math.max(-1, Math.min(1, Math.abs(dot(s.fit.normal, n.fit.normal))))));
+      if (!angles.every((a) => a > MIN_CHAMFER_RAD && a < MAX_CHAMFER_RAD)) continue;
+      // Strip width from the area and the longer of the two arcs — a chamfer is a
+      // ribbon, so area/length is its width.
+      const width = s.area / Math.max(primary[0].length, primary[1].length, 1e-9);
+      if (!fitsAsStrip(width)) continue;
+      out.push({
+        id: null,
+        key: `chamfer:${round3(width)}:${sortSignatures(nbrs)}`,
+        type: "chamfer", width, angle: (angles[0] + angles[1]) / 2,
+        between: nbrs.map((n) => n.id),
+        convexity: primary[0].convexity,
+        surfaces: [s.id],
+        evidence: { arcs: arcs.length, angles: angles.map(round3), fitRms: s.fit.rms },
+      });
+      continue;
+    }
+
+    // A countersink is a REVOLVED chamfer: a cone blending a bore into a face
+    // (or another cone) instead of a plane blending two walls. Its own conical
+    // half-angle already IS its blend angle (fit.js's fitCone recovers it
+    // directly), so unlike the plane branch above there's no pair of face
+    // normals to average — the cone's `halfAngle` cashes out to the same
+    // "angle from the material" the plane branch measures.
+    if (s.type === "cone") {
+      const width = s.area / Math.max(primary[0].length, primary[1].length, 1e-9);
+      if (!fitsAsStrip(width)) continue;
+      out.push({
+        id: null,
+        key: `chamfer:${round3(width)}:${sortSignatures(nbrs)}`,
+        type: "chamfer", width, angle: s.fit.halfAngle,
+        between: nbrs.map((n) => n.id),
+        convexity: primary[0].convexity,
+        surfaces: [s.id],
+        evidence: { arcs: arcs.length, halfAngle: round3(s.fit.halfAngle), fitRms: s.fit.rms },
+      });
+    }
+  }
+
+  return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}

package/src/framework/oracle/describe/features/holes.js

@@ -0,0 +1,129 @@
+// Hole rules over the attributed adjacency graph.
+//
+// The primary test is the cylinder's own CURVATURE, not the convexity of its arcs
+// (controller ruling R10). A bore is a concave cylinder — outward normals pointing back
+// toward its axis. A shaft or a boss is a convex one. Arc convexity cannot make this call:
+// a through-hole's rim and a plate's outer edge are both plain 90-degree convex corners,
+// because in both cases the material leaves a 90-degree wedge at the seam.
+//
+// Arc convexity still does the SECOND half of the job, once curvature has established we
+// are looking at a bore: a convex circular arc to a plane is a MOUTH (the bore breaking
+// out through a face), and a concave arc to a plane or cone is a FLOOR (the bore
+// bottoming out). Two mouths on anti-parallel planes is a through hole; one mouth plus a
+// floor is a blind hole. Everything else — radius, extent, axis — fit.js already measured.
+//
+// `id` is deliberately null: feature numbering is the orchestrator's job (Task 12),
+// because ids must be assigned once across ALL feature families in a stable order.
+// A `key` derived from rounded geometry gives that ordering something deterministic
+// to sort on, so the same mesh always numbers its features the same way.
+//
+// Pure leaf. See spec §2.5.
+import { arcsOf } from "../surface-graph.js";
+
+// Two planes count as "parallel" (a through hole's two mouths) within this band.
+const PARALLEL_DOT = 0.98;
+// `arcsOf` is imported for the mouth/floor split; curvature comes off the surface itself.
+const round3 = (v) => Math.round(v * 1000) / 1000;
+
+const byId = (graph) => new Map(graph.surfaces.map((s) => [s.id, s]));
+const other = (arc, id) => (arc.between[0] === id ? arc.between[1] : arc.between[0]);
+
+export function detectHoles(graph) {
+  const surfaces = byId(graph);
+  const out = [];
+
+  for (const s of graph.surfaces) {
+    if (s.type !== "cylinder") continue;
+    if (s.curvature !== "concave") continue;                  // a boss, a shaft, an outer wall
+
+    const arcs = arcsOf(graph, s.id);
+    // A mouth is where the bore breaks out through a face: a convex seam to a plane.
+    // But the seam can also lead to a CONE first — a countersink or counterbore,
+    // the machining used to chamfer a hole's entrance — in which case the cone is
+    // incidental (it's on the way out, not the exit itself) and the true mouth is
+    // whatever PLANE the cone in turn opens onto one step further out. Round 1
+    // review: a plain through-bore with a 45-degree countersunk entrance reported
+    // ZERO holes before this, because the direct neighbour at that end is a cone,
+    // not a plane, and the old plane-only filter dropped that mouth entirely —
+    // leaving one planar mouth and no concave floor, so neither branch below fired.
+    const mouths = [];
+    for (const a of arcs) {
+      if (a.convexity !== "convex") continue;
+      const nbr = surfaces.get(other(a, s.id));
+      if (!nbr) continue;
+      if (nbr.type === "plane") { mouths.push({ arc: a, face: nbr, via: null }); continue; }
+      if (nbr.type === "cone") {
+        const beyond = arcsOf(graph, nbr.id)
+          .map((a2) => surfaces.get(other(a2, nbr.id)))
+          .find((far) => far && far.id !== s.id && far.type === "plane");
+        if (beyond) mouths.push({ arc: a, face: beyond, via: nbr });
+      }
+    }
+    if (mouths.length === 0) continue;
+
+    const dir = s.fit.axis.direction;
+    const depth = Math.abs(s.fit.extent[1] - s.fit.extent[0]);
+    const diameter = s.fit.radius * 2;
+    const origin = s.fit.axis.origin;
+
+    // Through: two planar mouths on parallel planes, both perpendicular to the bore
+    // axis. Blind: one mouth, with the far end closed by a surface the bore also
+    // touches (planar floor or conical drill point).
+    //
+    // NOTE: this checks |dot| against PARALLEL_DOT, not dot <= -PARALLEL_DOT (which
+    // is what "anti-parallel outward normals" would suggest and what a first draft
+    // of this rule used). fitPlane() (fit.js) is pure PCA over a point cloud with no
+    // reference to the mesh's own winding/face normals, so a plane surface's
+    // `fit.normal` sign is an arbitrary artifact of the eigensolver, not tied to the
+    // true outward direction — confirmed directly against annulusPlate(10,4,3,48),
+    // whose two caps (translated copies of the same ring shape, hence identical PCA
+    // covariance) both come back with fit.normal = (0,0,1), not the physically
+    // anti-parallel (0,0,-1)/(0,0,1) the caps actually have. A dot <= -PARALLEL_DOT
+    // test against that ambiguous sign found zero through holes on this fixture.
+    // The physical invariant that survives the sign ambiguity is just that the two
+    // mouth planes are PARALLEL to each other (their normals share a line, whichever
+    // way each happens to point) — a bore's own axis is perpendicular to a mouth
+    // plane at each end it breaks through, so two such planes at opposite ends of a
+    // straight bore cannot help but be parallel to one another.
+    let type = null, entryFace = null, exitFace = null, floorFace = null;
+    if (mouths.length >= 2) {
+      const [m0, m1] = mouths;
+      const d = m0.face.fit.normal[0]*m1.face.fit.normal[0]
+              + m0.face.fit.normal[1]*m1.face.fit.normal[1]
+              + m0.face.fit.normal[2]*m1.face.fit.normal[2];
+      if (Math.abs(d) >= PARALLEL_DOT) { type = "throughHole"; entryFace = m0.face.id; exitFace = m1.face.id; }
+    }
+    if (!type) {
+      // A floor is the opposite seam: CONCAVE, because the bore bottoming out leaves 270
+      // degrees of material there. Planar for a flat-bottomed bore, conical for a drill point.
+      const floor = arcs
+        .filter((a) => a.convexity === "concave")
+        .map((a) => surfaces.get(other(a, s.id)))
+        .find((n) => n && n.id !== mouths[0].face.id && (n.type === "plane" || n.type === "cone"));
+      if (floor) { type = "blindHole"; entryFace = mouths[0].face.id; floorFace = floor.id; }
+    }
+    if (!type) continue;
+
+    // Any cone(s) walked through to resolve a mouth are part of this hole too —
+    // countersink machining, not a separate feature — so they're folded into
+    // `surfaces` (and named in `evidence`) rather than silently dropped.
+    const viaCones = [...new Set(mouths.filter((m) => m.via).map((m) => m.via.id))];
+
+    out.push({
+      id: null,
+      key: `hole:${round3(diameter)}:${round3(origin[0])},${round3(origin[1])},${round3(origin[2])}`,
+      type, diameter, depth,
+      axis: { origin, direction: dir },
+      entryFace, exitFace, floorFace,
+      surfaces: [s.id, ...viaCones],
+      // What the rule actually saw. The report carries this so a wrong call can be
+      // argued with rather than merely disbelieved.
+      evidence: {
+        curvature: s.curvature, planarMouths: mouths.length, arcs: arcs.length, fitRms: s.fit.rms,
+        countersunk: viaCones.length > 0, viaCones,
+      },
+    });
+  }
+
+  return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}