partforge 0.80.0 → 0.82.0

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

@@ -1,391 +0,0 @@
-// Efficient RANSAC (Schnabel/Wahl/Klein 2007) over the faces region growing could
-// not claim. Growth is connectivity-driven and therefore blind to a surface split
-// into disjoint islands by a feature crossing it — a plane interrupted by a boss,
-// a wall broken by a slot. RANSAC is consensus-driven and does not care whether its
-// inliers touch, so the two are complementary rather than redundant.
-//
-// DETERMINISM IS A HARD REQUIREMENT, not a nicety. Oracle output feeds a
-// content-hash memo (spec §4.1) and the framework's purity rule forbids Math.random
-// outright, so candidate sampling is built from the mesh's own topology and
-// quantized normals instead of drawing randomly. Same input (same faces, in the
-// same order — see `ransacPatches`'s own header note on that), same patches,
-// every run, in every process.
-//
-// Pure leaf. See spec §2.3.
-import { fitPlane, fitCylinder, fitCone, fitSphere, fitTorus, deviationOf } from "./fit.js";
-import { facePoints } from "./segment.js";
-
-const dot = (a, b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2];
-const unit = (a) => { const n = Math.hypot(a[0], a[1], a[2]); return n > 0 ? [a[0]/n, a[1]/n, a[2]/n] : [0, 0, 0]; };
-
-// A minimal sample is 2 FACES (6 vertices, 6 normals — three per triangle). Two,
-// not three, because this mop-up's own primary target (per the file header — a
-// plane cut by a boss, a wall cut by a slot) is a flat CAD face reduced by
-// tessellation to as few as TWO triangles, so a threshold of three would make
-// that exact, common case unrecoverable by construction, not by any real
-// shortfall of consensus: three DISTINCT triangles drawn from a mesh where a
-// real plane is only ever two triangles wide can never all land on that one
-// plane (verified directly on `boxMesh`: every 3-triangle sample mixes at least
-// two different quads, and the least-squares plane through two different box
-// faces' points misses tolerance by millimetres, never by noise). `minInliers`
-// is the same number, for the same reason.
-const SAMPLE_FACES = 2;
-const MIN_INLIERS = SAMPLE_FACES;
-
-// Quantization for "same normal direction, bucket together" — deliberately the
-// same 1/24 grid `segment.js`'s own `seedOrder` uses for the identical purpose
-// (grouping faces by Gauss-map direction), not a fresh constant invented here.
-const NORMAL_BUCKET_SCALE = 24;
-// Within one normal bucket, exhaustively pair only the first this-many members.
-// A genuinely single real surface only needs ONE pair from its bucket to
-// bootstrap (consensus then scans the WHOLE pool, not just the bucket, so it
-// recovers every matching face regardless of which pair started it) — this cap
-// only bounds the rarer case of one bucket holding several DIFFERENT parallel
-// planes (same normal, different offset), where exhaustive intra-bucket
-// pairing is what guarantees at least one same-offset pair is tried.
-const BUCKET_PAIR_CAP = 24;
-// Hard ceiling on total candidate pairs handed to the round below, applied
-// AFTER generating the topological and normal-bucket pairs (see
-// `candidatePairs`) — a cap on how much work gets EVALUATED, never a switch to
-// a different, lossier way of choosing which pairs to generate. A prior
-// version of this file used a coprime-stride walk as a fallback once the pool
-// exceeded a budget, and that walk could — provably, not just theoretically —
-// skip every same-facet pair a plane hypothesis needs (see `candidatePairs`'s
-// own comment for the measured cylinder-wall regression this caused). The
-// fix is not a bigger or smarter stride, it is to make the GENERATION itself
-// structurally incapable of missing those pairs, and only THEN bound the
-// total.
-const PAIR_BUDGET = 65536;
-
-// Controller ruling R28: `ransacPatches` measures at roughly O(n^2.7) in its face
-// count — 80ms at 400 faces, 1.8s at 1600, 23.8s at 4000, ~60s around 5,500. That
-// has been safe so far only because its one caller (`segment()`'s mop-up, below)
-// hands it a small RESIDUAL — the faces region growing couldn't already claim, not
-// the whole mesh. A future caller offering an unfiltered face list (the whole
-// candidate surface of a complex mesh) could walk straight into the cliff above
-// with no warning. `maxFaces` is that guardrail: past it, this function degrades —
-// it processes a bounded, deterministic prefix of the pool and reports the rest as
-// unassigned — rather than either refusing to run or silently taking minutes.
-// 2000 is chosen to sit comfortably under the 1600-faces/1.8s point measured above
-// (the worst case inside one bucket-pair/topology-neighbour pass is still bounded
-// by PAIR_BUDGET regardless of pool size, but the per-candidate consensus SCAN is
-// O(pool) per pair, which is where the n^2.7 comes from).
-const DEFAULT_MAX_FACES = 2000;
-
-// Angle band for "this face's own normal is compatible with the fit's local
-// surface normal here", radians (30°) — reuses segment.js's own smoothness
-// ceiling (`SMOOTH_DIHEDRAL_MAX`) rather than inventing a second unrelated
-// constant for what is conceptually the same question: how much a face's flat
-// normal may disagree with a claimed smooth surface before the two are
-// considered different surfaces. Not re-imported (segment.js doesn't export
-// it) because the two live in siblings with no shared parent to hoist a
-// constant into without ransac.js importing FROM segment.js — a leaf importing
-// its own caller — so the value is restated here with this comment as the
-// tether between them.
-const NORMAL_COS_MIN = Math.cos(Math.PI / 6);
-
-const faceNormalOf = (topo, t) => [topo.faceNormal[3*t], topo.faceNormal[3*t+1], topo.faceNormal[3*t+2]];
-function faceCentroid(topo, t) {
-  const c = [0, 0, 0];
-  for (let k = 0; k < 3; k++) {
-    const v = topo.tris[3*t + k] * 3;
-    c[0] += topo.verts[v]; c[1] += topo.verts[v+1]; c[2] += topo.verts[v+2];
-  }
-  return [c[0]/3, c[1]/3, c[2]/3];
-}
-// Worst distance from a face's three vertices to a fitted primitive. Exported because
-// segment.js's growth predicate needs exactly the same question answered exactly the same
-// way; the point-to-primitive distance itself lives in fit.js (ruling R19), so there is
-// one definition and neither consumer can drift from it.
-export function faceDeviation(topo, t, fit) {
-  let worst = 0;
-  for (let k = 0; k < 3; k++) {
-    const v = topo.tris[3*t + k] * 3;
-    const d = Math.abs(deviationOf(fit, [topo.verts[v], topo.verts[v+1], topo.verts[v+2]]));
-    if (d > worst) worst = d;
-  }
-  return worst;
-}
-
-// GRAD_H: the step of a central-difference gradient of `deviationOf`, taken as the
-// fit's local unit outward normal. Not five hand-derived per-type normal formulas
-// (one per fit in fit.js) — that would be five MORE places a normal convention
-// could quietly drift from `deviationOf`'s own sign convention, exactly the
-// duplication ruling R19 already forbids for distance. `deviationOf` is a smooth
-// signed-distance-like field for every one of the five types by construction
-// (fit.js's own docstring on the function), so its gradient anywhere near the
-// surface IS that surface's local normal, generically, with no per-type case
-// analysis needed. Fixed, not scaled to the fit's own size or the mesh's bbox:
-// determinism forbids a step that depends on anything but the two arguments
-// given, the same reason candidate generation below is built from the mesh's
-// own topology and quantized normals rather than anything data-adaptive.
-const GRAD_H = 1e-4;
-function fitNormalAt(fit, point) {
-  // Plane fast path: `deviationOf`'s plane branch is `dot(normal, point) -
-  // offset`, exactly linear, so its gradient is `normal` EVERYWHERE, not just
-  // near the surface — this isn't an approximation for the plane case, it's
-  // the same answer the finite difference below converges to, without six
-  // extra `deviationOf` calls per face checked. Consensus in this file only
-  // ever calls this with a plane fit (`planeHypothesis` never hands back
-  // anything else), so this is the path actually taken; the general
-  // finite-difference fallback stays for `opts`/future callers that might
-  // pass a converged non-plane fit through the same check.
-  if (fit.type === "plane") return fit.normal;
-  const g = [0, 0, 0];
-  for (let a = 0; a < 3; a++) {
-    const hi = [...point], lo = [...point];
-    hi[a] += GRAD_H; lo[a] -= GRAD_H;
-    g[a] = deviationOf(fit, hi) - deviationOf(fit, lo);
-  }
-  return unit(g);
-}
-
-// Why consensus needs BOTH a distance test and this one, not distance alone: a
-// box's 8 corners lie, EXACTLY (to floating-point noise), on infinitely many
-// circumscribing cylinders and spheres — any axis through the centroid parallel
-// to a principal direction gives a cylinder every corner sits on; the
-// circumsphere every corner sits on is a further such case. That is not a
-// tessellation artifact, it is elementary solid geometry (a rectangular box's
-// vertices are, by definition, equidistant from its centroid along suitably
-// chosen axes), so it recurs on every rectangular fixture, not a fluke of one
-// mesh — measured directly against all 60 cross-quad pairs of `boxMesh`'s 12
-// triangles (the 66 total pairs of 12 triangles, less the 6 same-quad pairs):
-// every one of those 60 fits a cylinder AND a sphere to machine precision. A
-// distance-only consensus test can't tell that coincidence apart from a real
-// surface. A real surface's own faces have flat
-// normals that track the surface's local tangent as it's actually built; a box
-// face dropped onto someone else's circumscribing sphere has a flat normal
-// (say, straight down off the bottom) that has nothing to do with that
-// sphere's local outward direction there (radially away from a center nowhere
-// near below it) — measured directly at tens of degrees apart, well outside
-// any plausible smoothness band. This is the standard Efficient RANSAC
-// safeguard (Schnabel/Wahl/Klein score every inlier on normal compatibility,
-// not distance alone), restated here because the immediate trigger for adding
-// it was exactly this box fixture.
-function faceNormalConsistent(topo, t, fit) {
-  return dot(fitNormalAt(fit, faceCentroid(topo, t)), faceNormalOf(topo, t)) >= NORMAL_COS_MIN;
-}
-
-// The minimal-sample hypothesis is PLANE ONLY, never cylinder/cone/sphere/torus,
-// even though every fit is available (and used) once a consensus set has grown —
-// see the REFIT step below. This is not a simplification of convenience: two
-// faces supply only two independent surface-normal directions, and that is
-// structurally too little to trust a 5-DOF ruled-surface fit (a cylinder's or
-// cone's axis) with. Measured directly on `boxMesh`: EVERY pair of triangles
-// drawn from two different, unrelated quads satisfies `fitCylinder` (and
-// `fitSphere`) to machine-precision residual — a rectangular box's vertices are
-// always equidistant from its centroid along the right axis, so a "cylinder"
-// or "sphere" hypothesis born from almost any two unrelated flat facets isn't
-// evidence of curvature at all, it's an artifact of how much freedom two
-// normal directions leave a 5-DOF fit. No fixed normal-consistency or distance
-// threshold closes this reliably (the more elongated a box's cross-section,
-// the closer two unrelated facets' radial deviation drifts toward zero,
-// eliminating any fixed-angle margin as the aspect ratio grows), so the
-// principled fix is not to widen the FILTER but to narrow what a minimal
-// sample is trusted to CLAIM: a plane needs only three points to be exactly
-// determined (fit.js's own MIN_PTS), so two flat facets are already enough
-// data to trust a plane hypothesis with no analogous coincidence risk (two
-// unrelated, non-coplanar quads do NOT satisfy a common plane to any close
-// tolerance — verified on the same fixture). This mirrors segment.js's own
-// seed/grow split (a lone seed triangle is only ever classified provisionally,
-// never asked to prove a curved type) rather than inventing a new principle.
-function planeHypothesis(topo, sample, tol) {
-  const { pts, normals } = facePoints(topo, sample);
-  const f = fitPlane(pts);
-  if (!f || f.maxDev > tol) return null;
-  // fitPlane's normal is an eigenvector of a covariance matrix, and an
-  // eigenvector's sign is arbitrary — fit.js never canonicalizes it, because
-  // nothing in a bare point cloud says which side is "outward". A mesh face
-  // does say: `topo.faceNormal` is the winding-derived outward direction, the
-  // one thing `faceNormalConsistent` actually needs the fitted plane's normal
-  // to agree with. Without this, the two ends up antiparallel roughly half the
-  // time (whichever way the eigensolver happened to land), and
-  // `faceNormalConsistent` then rejects the SAME faces that produced the
-  // hypothesis in the first place — reproduced directly: `boxMesh`'s bottom
-  // quad fit a plane with normal (0,0,1) while its own triangles carry (0,0,-1),
-  // and the consensus step threw away the seed pair itself. Flipping both
-  // `normal` and `offset` together (so `dot(normal,p) = offset` still holds)
-  // re-expresses the identical plane with the sign the mesh's own winding
-  // agrees with; summing agreement across the whole sample rather than
-  // checking one face keeps the corrected sign robust to a single face's
-  // winding being the unusual one.
-  let agree = 0;
-  for (const n of normals) agree += dot(f.normal, n);
-  return agree < 0 ? { ...f, normal: [-f.normal[0], -f.normal[1], -f.normal[2]], offset: -f.offset } : f;
-}
-
-// FINAL classification of a converged consensus set, once RANSAC has stopped
-// growing it: the full ascending-DOF ladder (plane, then cylinder/cone, then
-// sphere/torus), first candidate within tolerance — same policy, and the same
-// justification, as segment.js's `bestFit`. By the time this runs, `sample`
-// is the WHOLE inlier set (already filtered on both distance and normal
-// consistency against the seed plane), not a bare minimal sample, so it carries
-// far more independent constraint than the two-facet hypothesis above and does
-// not share that hypothesis's degenerate-fit risk.
-function candidateFrom(topo, sample, tol) {
-  const { pts, normals } = facePoints(topo, sample);
-  for (const f of [fitPlane(pts), fitCylinder(pts, normals), fitCone(pts, normals),
-                   fitSphere(pts), fitTorus(pts, normals)]) {
-    if (f && f.maxDev <= tol) return f;
-  }
-  return null;
-}
-
-// Every candidate pair worth trying a plane hypothesis on, deterministically
-// ordered. A plane needs matching normal direction (two faces from unrelated
-// directions never fit one to any close tolerance — see `planeHypothesis`'s
-// own comment), so the pairs that can EVER succeed are already a narrow,
-// structured subset of all C(n,2) — this generates exactly that subset from
-// two cheap, complementary sources instead of guessing at it with a stride:
-//
-// 1. TOPOLOGICAL NEIGHBOURS (`topo.faceEdges`): O(3n), and — this is the part
-//    a coprime-stride walk got wrong — GUARANTEED to include the diagonal
-//    pair of any single real flat facet still whole in the pool (a box quad's
-//    own two triangles, a cylinder wall segment's own two triangles: they
-//    share an edge by construction). A prior version of this file fell back
-//    to a stride walk once the pool exceeded a budget, and that walk could
-//    (measured directly: a 100-segment cylinder's 200 wall triangles, handed
-//    to `ransacPatches` with no adjacency hint, at that budget) skip EVERY
-//    one of the wall's 100 same-facet diagonal pairs, recovering only the two
-//    caps and leaving the entire wall — exactly half the mesh — unassigned,
-//    silently, with no error. Topological adjacency has no such blind spot:
-//    it doesn't sample a subset hoping to land on the right pairs, it reads
-//    the one relationship (shared edge) a real facet's own two triangles
-//    always have, for every face in the pool, unconditionally.
-// 2. NORMAL BUCKETS (see `NORMAL_BUCKET_SCALE`): reaches a face with NO
-//    topological neighbour left in the pool at all — a genuinely isolated
-//    sliver, or one half of a plane a crossing feature disconnected from its
-//    other half — by pairing it with whatever ELSE in the pool shares its
-//    (quantized) normal direction, the one thing any two pieces of the same
-//    real flat surface are guaranteed to share. Bounded per bucket (see
-//    `BUCKET_PAIR_CAP`) rather than fully exhaustive, because a bucket that
-//    holds one real, already-topologically-connected surface already got its
-//    bootstrap pair from source 1 above — this only needs to guarantee
-//    covering pairs ACROSS disconnected pieces, which is cheap by
-//    construction (few faces per genuine disconnected remainder).
-//
-// `PAIR_BUDGET` truncates the COMBINED result as a hard cap on total pairs
-// evaluated, applied last and only as a cap — never as a reason to swap in a
-// worse generator (see `PAIR_BUDGET`'s own comment).
-function candidatePairs(topo, pool) {
-  const seen = new Set();
-  const pairs = [];
-  const push = (a, b) => {
-    if (a === b) return;
-    const key = a < b ? `${a}:${b}` : `${b}:${a}`;
-    if (seen.has(key)) return;
-    seen.add(key);
-    pairs.push(a < b ? [a, b] : [b, a]);
-  };
-
-  const inPool = new Set(pool);
-  for (const t of pool) {
-    for (const ei of topo.faceEdges[t]) {
-      const e = topo.edges[ei];
-      if (e.triB < 0) continue;
-      const nb = e.triA === t ? e.triB : e.triA;
-      if (inPool.has(nb)) push(t, nb);
-    }
-  }
-
-  const buckets = new Map();
-  for (const t of pool) {
-    const n = faceNormalOf(topo, t);
-    const key = `${Math.round(n[0]*NORMAL_BUCKET_SCALE)},${Math.round(n[1]*NORMAL_BUCKET_SCALE)},${Math.round(n[2]*NORMAL_BUCKET_SCALE)}`;
-    let bucket = buckets.get(key);
-    if (!bucket) buckets.set(key, bucket = []);
-    bucket.push(t);
-  }
-  for (const bucket of buckets.values()) {
-    const m = Math.min(bucket.length, BUCKET_PAIR_CAP);
-    for (let i = 0; i < m; i++) for (let j = i + 1; j < m; j++) push(bucket[i], bucket[j]);
-  }
-
-  return pairs.length > PAIR_BUDGET ? pairs.slice(0, PAIR_BUDGET) : pairs;
-}
-
-export function ransacPatches(topo, faces, tol, opts = {}) {
-  const minInliers = opts.minInliers ?? MIN_INLIERS;
-  const maxFaces = opts.maxFaces ?? DEFAULT_MAX_FACES;
-  // Over the cap: split off a deterministic, order-independent prefix to actually
-  // process and defer the rest straight to `unassigned` (folded in below, after the
-  // main loop, alongside whatever the consensus search itself couldn't claim).
-  // Sorted by face INDEX — a property of the mesh, not of the caller's array — so
-  // which faces get processed vs deferred does not depend on the order `faces` was
-  // handed in, the same order-independence the rest of this function already
-  // guarantees (see the canonicalization comments below).
-  let overflow = [];
-  let bounded = faces;
-  if (faces.length > maxFaces) {
-    const sorted = [...faces].sort((a, b) => a - b);
-    bounded = sorted.slice(0, maxFaces);
-    overflow = sorted.slice(maxFaces);
-  }
-  let pool = [...bounded];
-  const patches = [];
-
-  while (pool.length >= minInliers) {
-    let best = null;
-    // Deterministic minimal samples: every pair `candidatePairs` generates, not
-    // drawn at random (see the file header — determinism is a hard requirement,
-    // not a style preference) and not a coprime-stride subset either (see
-    // `candidatePairs` for why that seemed reasonable and provably was not).
-    for (const sample of candidatePairs(topo, pool)) {
-      const fit = planeHypothesis(topo, sample, tol);
-      if (!fit) continue;
-      const inliers = pool.filter((t) => faceDeviation(topo, t, fit) <= tol && faceNormalConsistent(topo, t, fit));
-      if (inliers.length >= minInliers && (!best || inliers.length > best.inliers.length)) best = { fit, inliers };
-    }
-    if (!best) break;
-    // Refit and reclassify on the full consensus set: the minimal sample only
-    // located a plane, and every subsequent consumer reads these parameters as
-    // measurements. `candidateFrom` here can, and sometimes should, come back
-    // with a NON-plane type — an island whose faces all satisfy the seed plane's
-    // distance+normal test can still turn out to be better described some other
-    // way once every one of its faces (not just two) is fitted at once. Falls
-    // back to the minimal-sample fit (never null: the loop above only records
-    // `best` when `fit` succeeded) if the larger set fails every candidate
-    // outright — that can happen when the consensus set's extra faces are within
-    // `tol` of the seed plane individually but their combined least-squares
-    // refit drifts just past it.
-    const refit = candidateFrom(topo, best.inliers, tol) ?? best.fit;
-    patches.push({
-      faces: best.inliers, fit: refit,
-      area: best.inliers.reduce((a, t) => a + topo.faceArea[t], 0),
-    });
-    const claimed = new Set(best.inliers);
-    pool = pool.filter((t) => !claimed.has(t));
-  }
-
-  // Canonicalize order before numbering: the WHILE loop above discovers
-  // patches in an order driven by `pool`'s own current arrangement (ties in
-  // consensus size are broken by whichever candidate the pair generator
-  // happened to try first), and `pool`'s arrangement starts from whatever
-  // order the caller passed `faces` in. The set of faces in each patch is
-  // provably order-invariant (region growing's own connectivity doesn't
-  // enter into this file at all, and neither does array order — only which
-  // faces satisfy a fitted plane's distance+normal test, which doesn't
-  // depend on iteration order); the SEQUENCE they were discovered in is not,
-  // and this file's own header claims "same input, same patches, every
-  // run" — a claim that is only true if "same input" means the same SET of
-  // faces, not the same order too, unless output order is made to not
-  // depend on input order either. Sorting by each patch's own smallest face
-  // index — a property of the mesh's topology, not of the caller's array —
-  // gives a canonical order with no dependency on how `faces` happened to
-  // be listed, closing that gap rather than merely documenting it.
-  for (const p of patches) p.faces.sort((a, b) => a - b);
-  patches.sort((a, b) => a.faces[0] - b.faces[0]);
-  patches.forEach((p, i) => { p.id = `r${i}`; });
-
-  // Same reasoning for the residual: its CONTENT (which faces went unclaimed)
-  // is order-invariant, but `pool` carries whatever relative order the
-  // caller's `faces` had. `overflow` (the maxFaces deferral above, empty on
-  // the common in-budget path) folds in here rather than earlier, so a face
-  // the consensus search never even looked at is reported the same way as one
-  // it looked at and couldn't claim — both are just "unassigned" to the
-  // caller. A plain ascending sort is the canonical form for a bare list of
-  // face indices.
-  pool = pool.concat(overflow).sort((a, b) => a - b);
-
-  return { patches, unassigned: pool };
-}

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

@@ -1,217 +0,0 @@
-// The two report shapes, defined together on purpose.
-//
-// FULL is the archive: everything measured, written to disk by `partforge describe
-// --json`. COMPACT is what a model reads: features, patterns, symmetry, score,
-// residual, and the suggestion, with surfaces and edges elided to counts.
-//
-// Both live here rather than compact being invented by each consumer. A 24k-triangle
-// part yields hundreds of surfaces, and every consumer that trims them independently
-// trims them differently — cloud's model-facing view and the CLI's summary would drift
-// apart within a release. mountManager.js's compactReport is the precedent for the
-// principle (a full oracle report is not a model-facing artefact) and the warning: it
-// lives downstream, and its field renames have to be kept in sync by hand.
-//
-// Pure leaf. See spec §3.
-
-import { DESCRIBE_LIMITS } from "./limits.js";
-
-// Below this fraction the geometry is not trustworthy as a description of the part,
-// and saying so quietly is worse than saying nothing: an agent will build against a
-// confident-looking list that covers 61% of the geometry. See compactDescribe's own
-// comment for what "this fraction" is measured against (fix round 1: it's the worse
-// of two independent numbers, not just one of them).
-export const LOW_COVERAGE = 0.85;
-
-// Caps are CEILINGS, not targets: slicing an oversized array is not a failure, it is
-// the report doing its job. `flags[name]` records whether THIS array actually hit its
-// ceiling, so `buildReport`'s `truncated` block only ever claims what really happened.
-const cap = (arr, max, flags, name) => {
-  const a = arr ?? [];
-  flags[name] = a.length > max;
-  return a.slice(0, max);
-};
-
-// score is passed straight through except for one added field: a plain-language note
-// distinguishing its two coverage numbers. `explainedArea` (segment.js/surface-graph.js
-// territory) is how much of the mesh's SURFACE was fit by a surface type; it says
-// nothing about whether that surface was ever turned into a reconstructable feature.
-// `explainedVolumeFraction` (accept.js) is how much of the part's VOLUME the accepted
-// candidates actually rebuild — the number that matters to an agent deciding whether it
-// can trust the feature list to rebuild the part. They can diverge totally: a sphere
-// segments at explainedArea ~1 (it fits a sphere surface cleanly) while contributing
-// explainedVolumeFraction 0 (no detector treats a sphere as a candidate-eligible
-// feature type, so accept.js never gets a candidate to build from it at all). Spelled
-// out here, in the data, because the consumer is an LLM that cannot go read accept.js's
-// comments to work out that these are different measurements (fix round 1, IMPORTANT 5).
-//
-// Also covers each feature's own `volumeShare` (describe.js), the SAME underlying
-// accept.js gain measurement applied per-feature rather than summed: how much of the
-// part's volume THAT feature accounts for, not how sure the description is (round 2
-// review, IMPORTANT). A small-but-certain feature legitimately reports a small share —
-// spelled out here for the same reason the area/volume distinction is: the consumer
-// cannot go read accept.js's comments to learn that "small" and "uncertain" are not
-// the same axis.
-const SCORE_NOTE =
-  "explainedArea is surface coverage from segmentation (how much of the mesh's area " +
-  "was fit by a surface); explainedVolumeFraction is shape coverage from " +
-  "reconstruction (how much of the part's volume the accepted features actually " +
-  "rebuild). These are different measurements and can diverge totally — a part can " +
-  "be ~100% segmented and 0% reconstructed. The LOW COVERAGE banner, if present, " +
-  "reflects whichever of the two is worse. Each feature's own volumeShare is the " +
-  "same reconstruction measurement applied per-feature: the fraction of the part's " +
-  "volume THAT feature accounts for. It is a measure of SIZE, not certainty — a " +
-  "small-but-certain feature (e.g. a precisely-fitted 3mm hole in a large plate) " +
-  "legitimately reports a small volumeShare because it is small, not because it is " +
-  "doubtful. For a genuine fit-quality/certainty signal, read that feature's own " +
-  "fitted surface rms/maxDev instead.";
-
-function buildScore(score) {
-  return { ...(score ?? {}), note: SCORE_NOTE };
-}
-
-export function buildReport(input) {
-  // Every array this report might cap gets a flag here, initialised false, before any
-  // capping happens — so the shape is TOTAL. A cap never hit, and an array the input
-  // never supplied at all (e.g. no suggestion yet, before Task 12's orchestrator is
-  // wired in), must both report `false`, not an absent key: a consumer that walks
-  // `Object.values(truncated)` needs every flag present every time, or "nothing was
-  // truncated" and "the flag is just missing" become indistinguishable (fix round 1,
-  // IMPORTANT 4).
-  const truncated = {
-    surfaces: false,
-    edges: false,
-    features: false,
-    patterns: false,
-    residualRegions: false,
-    suggestionSteps: false,
-  };
-
-  const surfaces = cap(input.surfaces, DESCRIBE_LIMITS.MAX_SURFACES, truncated, "surfaces");
-  // input.arcs are the fitted edges between surface pairs (Tasks 6-7); reported here
-  // as "edges" since that is what a reader of the report calls them. Each carries a
-  // `convexity` of "convex" or "concave" — settled empirically to mean whether the
-  // edge rounds an outside or an inside corner of the PART, nothing about how a
-  // torus's own tube radius is parametrised. Easy to misread as the latter; it isn't.
-  const edges = cap(input.arcs, DESCRIBE_LIMITS.MAX_EDGES, truncated, "edges");
-  const features = cap(input.features, DESCRIBE_LIMITS.MAX_FEATURES, truncated, "features");
-  const patterns = cap(input.patterns, DESCRIBE_LIMITS.MAX_PATTERNS, truncated, "patterns");
-  const residualRegions = cap(
-    input.residual?.regions, DESCRIBE_LIMITS.MAX_RESIDUAL_REGIONS, truncated, "residualRegions"
-  );
-  // Capped even when there is no suggestion yet (input.suggestion null/undefined) so
-  // `truncated.suggestionSteps` is always `false` in that case, never absent — see the
-  // flag block's own comment above.
-  const suggestionSteps = cap(
-    input.suggestion?.steps, DESCRIBE_LIMITS.MAX_SUGGESTION_STEPS, truncated, "suggestionSteps"
-  );
-
-  return {
-    source: {
-      name: input.source?.name ?? null,
-      digest: input.source?.digest ?? null,
-      triangles: input.source?.triangles ?? 0,
-      watertight: input.source?.watertight ?? null,
-      units: "mm",
-    },
-    // Stated explicitly, every time. Z-up/Y-up confusion is a documented LLM failure
-    // mode (research doc §5) and one line defuses it. "as-imported" is the honest
-    // claim: describe never realigns, so the frame is whatever the file carried.
-    frame: { up: "+Z", note: "as-imported; no realignment applied" },
-    bounds: {
-      min: input.bounds.min,
-      max: input.bounds.max,
-      size: [0, 1, 2].map((i) => input.bounds.max[i] - input.bounds.min[i]),
-    },
-    // Pre-cap magnitudes, computed from the INPUT, not from `surfaces`/`edges` below.
-    // Those two arrays are what compactDescribe elides to counts, and a cap that fires
-    // must not also erase how big the thing it capped really was: 500 input surfaces
-    // against MAX_SURFACES=200 must still say 500 here, not silently report 200 as if
-    // that were the whole part (fix round 1, IMPORTANT 3).
-    counts: {
-      surfaces: (input.surfaces ?? []).length,
-      edges: (input.arcs ?? []).length,
-    },
-    surfaces,
-    edges,
-    features,
-    patterns,
-    symmetry: input.symmetry ?? [],
-    residual: {
-      areaFraction: input.residual?.areaFraction ?? 0,
-      regions: residualRegions,
-    },
-    score: buildScore(input.score),
-    suggestion: input.suggestion ? { ...input.suggestion, steps: suggestionSteps } : null,
-    truncated,
-  };
-}
-
-export function compactDescribe(full) {
-  // Gate on the WORSE of the two coverage numbers (see SCORE_NOTE above), not just
-  // explainedArea. Reproduced directly against the real pipeline with a 2304-triangle
-  // hemisphere: one sphere surface plus one flat base segment cleanly
-  // (explainedArea 1.0, zero unassigned triangles) but sphere is not a
-  // candidate-eligible type for any of the four feature detectors, so accept.js is
-  // handed zero candidates and explainedVolumeFraction is 0.0. Gating on explainedArea
-  // alone let a report that reconstructs NONE of the part's shape present as clean —
-  // exactly backwards for a banner whose whole job is to catch that (fix round 1,
-  // CRITICAL 1). `?? 0` on each side means a missing number reads as unexplained, not
-  // as "fine" — the fail-safe direction for a report whose job is to not overclaim.
-  const explainedArea = full.score?.explainedArea ?? 0;
-  const explainedVolume = full.score?.explainedVolumeFraction ?? 0;
-  const coverage = Math.min(explainedArea, explainedVolume);
-
-  const out = {};
-  // Assigned FIRST — and therefore serialized first, both by Object.keys() and by
-  // JSON.stringify(), which both preserve insertion order for string keys — so an LLM
-  // reading the raw JSON hits the banner before anything it might otherwise take at
-  // face value. (Fix round 1, CRITICAL 2: this used to be assigned after the rest of
-  // `out` was built, which put it last in both orders — exactly backwards for a banner
-  // whose entire job is to be seen first.)
-  //
-  // Two INDEPENDENT warning sources feed this one field (fix round 2, IMPORTANT 1):
-  // low coverage (computed here, from `score`) and `full.warning === "budget-exceeded"`
-  // (set by describe.js when acceptCandidates ran out of boolean attempts before the
-  // residual converged — see that assignment's own comment). Before this fix
-  // `full.warning` was silently dropped: `compactDescribe` only ever set `out.warning`
-  // from its own LOW_COVERAGE check, so a report that hit BOTH conditions — a real,
-  // documented case, since an exhausted budget is exactly the kind of run that also
-  // leaves coverage low — presented as a clean report in every consumer that reads only
-  // the compact shape (the CLI's default text view among them). Both fire independently
-  // and neither may mask the other, so both are collected and joined rather than one
-  // overwriting the other.
-  const warnings = [];
-  if (coverage < LOW_COVERAGE) {
-    warnings.push(
-      `LOW COVERAGE: only ${(100 * coverage).toFixed(1)}% of this part is explained ` +
-      `(the worse of ${(100 * explainedArea).toFixed(1)}% surface area fit and ` +
-      `${(100 * explainedVolume).toFixed(1)}% shape reconstructed). Treat the feature ` +
-      `list as incomplete in BOTH directions — do not assume a feature is absent ` +
-      `because it is not listed, AND do not assume every listed feature is real: a ` +
-      `low-coverage segmentation can also type tessellation fragments (e.g. noise at ` +
-      `fillet corners) as their own small bosses/pockets. See residual.regions for ` +
-      `where the unexplained geometry is.`);
-  }
-  if (full.warning === "budget-exceeded") {
-    warnings.push(
-      `BUDGET EXCEEDED: the acceptance loop hit its boolean-attempt budget before the ` +
-      `residual converged. This report is honestly scored, not wrong — but it may be ` +
-      `incomplete for the same reason low coverage would be. Raise --budget and ` +
-      `re-describe, or treat the current feature list as partial.`);
-  }
-  if (warnings.length) out.warning = warnings.join("\n\n");
-  out.source = full.source;
-  out.frame = full.frame;
-  out.bounds = full.bounds;
-  // Pre-cap counts, straight from `full.counts` — see buildReport's own comment on why
-  // these must not be derived from the (possibly-capped) `full.surfaces`/`full.edges`.
-  out.counts = full.counts;
-  out.features = full.features;
-  out.patterns = full.patterns;
-  out.symmetry = full.symmetry;
-  out.residual = full.residual;
-  out.score = full.score;
-  out.suggestion = full.suggestion;
-  out.truncated = full.truncated;
-  return out;
-}