partforge 0.77.0 → 0.78.0

package/bin/cli.js

@@ -15,6 +15,8 @@ import { bootOcctKernel } from "../src/testing/occt.js";
 import { bootManifoldKernel } from "../src/testing/manifold.js";
 import { measure } from "../src/framework/oracle/measure.js";
 import { verify } from "../src/framework/oracle/verify.js";
+import { describe as describeMesh } from "../src/framework/oracle/describe.js";
+import { compactDescribe } from "../src/framework/oracle/describe/report.js";
 import { renderViews } from "../src/testing/render.js";
 import {
   createPickServer, requestPicks, formatPickResult,
@@ -25,7 +27,7 @@ import { matchPattern } from "../src/testing/error-patterns.js";
 import { lintPart } from "../src/lint.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
-const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|describe|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
@@ -186,6 +188,51 @@ const commands = {
     }
   },
 
+  async describe(args) {
+    const usage = "usage: partforge describe <part-module#importName> [--surfaces] [--json] [--budget N] [--out <file>]";
+    const { values: flags, positionals: [target] } = parse(args, {
+      surfaces: { type: "boolean" },
+      json: { type: "boolean" },
+      budget: { type: "string" },
+      out: { type: "string" },
+    }, usage);
+    if (!target) die(usage);
+    // `part.js#importName` — describe reads a FILE, and a file only reaches the kernel
+    // through a part's `imports` declaration, so the part is how we find it. A bare mesh
+    // path is deliberately not accepted in v1: it would need its own resolver, its own
+    // format sniffing, and its own unit assumptions, all of which the import pipeline
+    // already owns.
+    const [partPath, importName] = target.split("#");
+    if (!importName) die(`describe needs an import name: <part-module>#<importName>\n${usage}`);
+    try {
+      const part = await loadPart(partPath, usage);
+      if (!part.imports?.[importName]) {
+        die(`describe: "${importName}" is not a declared import of ${partPath} ` +
+            `(have: ${Object.keys(part.imports ?? {}).join(", ") || "none"})`);
+      }
+      const kernel = await bootKernel(part);
+      const solid = kernel.import(importName);
+      const report = describeMesh(kernel, solid, {
+        name: importName,
+        digest: kernel._importDigest?.(importName) ?? null,
+        budget: flags.budget ? Number(flags.budget) : undefined,
+      });
+      if (flags.out) {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+      }
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      else printDescribe(report, { surfaces: !!flags.surfaces });
+      if (flags.out) console.log(`\nwrote ${flags.out}`);
+      // A closed-set error exits non-zero; LOW COVERAGE does not. Coverage is a finding
+      // the caller must be able to read, and an exit code that conflated the two would
+      // train an agent to discard exactly the reports it most needs to look at.
+      process.exit(report.error ? 1 : 0);
+    } catch (e) {
+      crash("describe", e, !!flags.json);
+    }
+  },
+
   async render(args) {
     const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>] " +
       "[--params <json>] [--animation <name>] [--at <t[,t…]>] [--step <index|label>]";
@@ -395,6 +442,83 @@ function printVerify(v) {
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
 
+// Human/agent-readable summary. Features, patterns, symmetry, score, residual — the
+// compact shape (spec §3.4), because a 24k-triangle part yields hundreds of surfaces and
+// dumping them buries the reader in the noise the oracle exists to remove. `--surfaces`
+// opts back in; `--json` always has everything. Reads the SAME compactDescribe() output
+// a model reads (not a hand-rolled subset), so what a human sees here and what an agent
+// sees over `--json` cannot drift apart.
+function printDescribe(report, { surfaces }) {
+  if (report.error) {
+    console.error(`describe: ${report.error}${report.detail ? ` — ${report.detail}` : ""}`);
+    return;
+  }
+  const c = compactDescribe(report);
+  if (c.warning) console.log(`\n!! ${c.warning}\n`);
+  console.log(`${c.source.name ?? "mesh"} — ${c.source.triangles} triangles, ` +
+              `${c.bounds.size.map((v) => v.toFixed(2)).join(" x ")} mm, ${c.frame.up} up`);
+  // The `share` hint lives HERE, at the point of use, not several lines below beside
+  // Score (fix round 2, IMPORTANT 1 — a prior version printed the full `score.note`
+  // paragraph under Score and it dominated the report: measured at 36-43% of a typical
+  // run's line count, the single largest visual element, bigger than the feature list,
+  // banners, and score line combined — burying findings instead of clarifying them). One
+  // line, next to the column it explains; the full note is still in `--json` unabridged
+  // (`buildScore` in report.js attaches it unconditionally — nothing lost there).
+  console.log(`\nFeatures (${c.features.length}):` +
+              (c.features.length ? `   share = fraction of part volume this feature ` +
+                `accounts for — a size measure, not certainty` : ""));
+  // `volumeShareReason` (fix round 2, IMPORTANT 2): `volumeShare: null` alone doesn't
+  // say whether this feature type is never proposed at all, was proposed but never
+  // reached before the search ran out of budget, or was reached and built but simply
+  // didn't win — three different signals to a rebuilder deciding what to do next. See
+  // describe.js's own comment on the field for the exact three-way split.
+  const REASON_LABEL = { "not-proposed": "not proposed", budget: "budget", rejected: "rejected" };
+  for (const f of c.features) {
+    const dim = f.diameter ?? f.radius ?? f.width ?? f.thickness ?? f.depth;
+    const snap = f.snapped?.diameter?.note ? `  [${f.snapped.diameter.note}]` : "";
+    const share = f.volumeShare != null
+      ? `${(100 * f.volumeShare).toFixed(1)}%`
+      : `n/a (${REASON_LABEL[f.volumeShareReason] ?? f.volumeShareReason ?? "unknown"})`;
+    console.log(`  ${f.id.padEnd(5)} ${f.type.padEnd(14)} ` +
+                `${dim != null ? dim.toFixed(3) : ""}`.padEnd(10) +
+                `share ${share}${snap}`);
+  }
+  if (c.patterns.length) {
+    console.log(`\nPatterns (${c.patterns.length}):`);
+    for (const p of c.patterns) {
+      console.log(`  ${p.id.padEnd(5)} ${p.type.padEnd(9)} x${p.counts.join("x")} ` +
+                  `pitch ${p.pitch.map((v) => v.toFixed(2)).join(", ")}  [${p.members.length} members]`);
+    }
+  }
+  if (c.symmetry.length) {
+    console.log(`\nSymmetry:`);
+    for (const s of c.symmetry) console.log(`  ${s.type} coverage ${s.coverage}`);
+  }
+  if (surfaces) {
+    console.log(`\nSurfaces (${report.surfaces.length}):`);
+    for (const s of report.surfaces) {
+      console.log(`  ${s.id.padEnd(5)} ${s.type.padEnd(9)} area ${s.area.toFixed(2)}`.padEnd(40) +
+                  `rms ${s.rms.toExponential(2)}`);
+    }
+  }
+  // TWO DIFFERENT NUMBERS, printed as two: explainedArea is how much of the mesh's
+  // SURFACE segmentation fitted to some primitive; explainedVolumeFraction is how much
+  // of the part's actual SHAPE the accepted features reconstruct. They can diverge
+  // totally — a dome segments to ~100% area and 0% volume, since a sphere is not a
+  // candidate-eligible feature type — so printing only one (or a blended "xor%") would
+  // hide exactly the gap the LOW COVERAGE banner above exists to catch. The wording here
+  // ("surface area explained" vs. "volume reconstructed") already carries that
+  // distinction; `score.note`'s full prose (this point, plus the volumeShare aside now
+  // covered at the Features header instead) stays JSON-only — fix round 2, IMPORTANT 1.
+  console.log(`\nScore: ${(100 * c.score.explainedArea).toFixed(1)}% surface area explained, ` +
+              `${(100 * c.score.explainedVolumeFraction).toFixed(1)}% volume reconstructed ` +
+              `(residual xor ${(100 * c.score.xorFraction).toFixed(2)}% of volume)`);
+  console.log(`Residual: ${(100 * c.residual.areaFraction).toFixed(2)}% of area in ` +
+              `${c.residual.regions.length} region(s)`);
+  const truncated = Object.entries(report.truncated ?? {}).filter(([, v]) => v).map(([k]) => k);
+  if (truncated.length) console.log(`Truncated (caps hit): ${truncated.join(", ")}`);
+}
+
 function printLint(r) {
   const all = [...r.errors, ...r.warnings, ...(r.notes ?? [])];
   if (all.length === 0) { console.log("lint: clean"); return; }

package/docs/AUTHORING-PARTS.md

@@ -1494,6 +1494,166 @@ build: (k, p, d) => {
 
 **CLI:** `partforge measure|render|lint` work on an importing part exactly as on any other — the `imports` field resolves in the CLI's Node boot the same way `fonts` does, no extra flags.
 
+## Describing an imported mesh
+
+Before you write the parametric rebuild, ask the mesh itself what's in it: `partforge
+describe <part-module>#<importName>` reads an already-declared import (`k.import`'s own
+name, not a bare file path — the `imports` field is how the file gets to a kernel at
+all, so it's how `describe` finds it too) and emits a semantic feature report — holes,
+bosses, pockets, extrusions, patterns, symmetry — rather than a triangle soup. On
+`import-demo.js`, whose `scan` import is a plain 20×14×8mm block:
+
+```
+$ npx partforge describe src/parts/import-demo.js#scan
+
+scan — 12 triangles, 20.00 x 14.00 x 8.00 mm, +Z up
+
+Features (1):   share = fraction of part volume this feature accounts for — a size measure, not certainty
+  f0    extrusion      8.000     share 100.0%
+
+Score: 100.0% surface area explained, 100.0% volume reconstructed (residual xor 0.00% of volume)
+Residual: 0.00% of area in 0 region(s)
+```
+
+**Two report shapes, and which one is authoritative.** `describe()` (`src/framework/
+oracle/describe.js`) returns the FULL report — every surface, every fitted edge, every
+feature at full precision — and that is the archive: `--json` prints it whole, and
+`--out <file>` writes it whole. `compactDescribe()` (`src/framework/oracle/describe/
+report.js`) derives a second, smaller shape from it — features, patterns, symmetry,
+score, residual, and the suggested rebuild, with `surfaces`/`edges` reduced to counts —
+and that is what a model reads, and what the terminal printer above reads too: **the
+same `compactDescribe()` output**, not a hand-rolled subset, so what a human sees in the
+default summary and what an agent gets from a cloud turn cannot drift apart. The full
+report is authoritative for the facts (a fitted surface's rms, an edge's exact radius);
+the compact report is authoritative for what's worth paying attention to.
+
+**Computed once, reused for the session.** `describe` depends on nothing but the mesh's
+own bytes — no part params, no derived state — so unlike `measure`/`verify` it never
+needs to re-run on every parameter edit. The worker keys its memo on the import's
+content digest (`kernel._importDigest(name)`), so re-describing the same file, or asking
+again mid-session while you iterate on the parametric rebuild, is free after the first
+call. The CLI doesn't carry a memo across process invocations — each `partforge
+describe` run is its own process — but within one browser session or one long-running
+tool loop, the mesh is segmented once.
+
+**`--surfaces` and `--json`, and why the default elides.** A hand-modelled block
+segments to six surfaces; a real 24k-triangle CAD export segments to hundreds. Printing
+every one of them by default would bury the two or three that actually matter under
+exactly the noise this oracle exists to remove — so the plain-text summary shows
+features, patterns, symmetry, score, and residual only. Pass `--surfaces` to add the
+surface table back (`s0 plane area … rms …`, one line per fitted patch); pass `--json`
+to get everything, always, structured — the mode an agent should default to over
+scraping the text summary. `--out <file>` writes the full report to disk independently
+of either flag, so you can capture it once and read it multiple ways.
+
+**Low coverage exits zero — it's a finding, not a failure.** A poor segmentation (a
+dome, a free-form scan, anything the four feature detectors can't reconstruct) is
+exactly the situation an agent most needs to see, not one that should make itself
+harder to see. `describe` treats "the shape isn't well explained" and "the command
+failed" as different questions: a `LOW COVERAGE` banner at the top of the summary (and
+`compactDescribe()`'s own `warning` field in `--json` output) is how a poor result
+announces itself, and the process still exits 0. Only a genuine closed-set error — the
+mesh couldn't be read or segmented at all — exits 1. Coverage is gated on the WORSE of
+two numbers, both always printed rather than blended into one: `explainedArea` (how much
+of the mesh's *surface* a fitted primitive accounts for) and `explainedVolumeFraction`
+(how much of the part's actual *shape* the accepted features reconstruct). They can
+diverge totally — a dome segments to ~100% surface area (it fits a sphere cleanly) and
+0% volume (a sphere isn't a candidate-eligible feature type for any detector) — so
+printing only one of them, or an average, would hide precisely the gap the banner exists
+to catch. Each feature's own score is named `volumeShare`, never "confidence": it is the
+fraction of the part's volume that feature accounts for — a measure of *size* — so a
+small-but-certain feature (a precisely-fitted 3mm hole in a large plate) legitimately
+reports a small share. Read a feature's fitted surface `rms`/`maxDev` (under `--surfaces`
+or `--json`) for an actual certainty signal. The one-line hint at the `Features (N):`
+header states the size-not-certainty point at its point of use; the longer explanation
+(`score.note` — both this and the `explainedArea`/`explainedVolumeFraction` distinction
+above, spelled out for a reader who never gets this far) stays `--json`-only, since
+printing it in full under `Score:` used to be the single largest visual element in every
+plain-text run — measured at 36-43% of a typical report's line count, bigger than the
+feature list, the banners, and the score line combined.
+
+**Why a null `volumeShare` isn't always the same story.** A feature can carry
+`volumeShare: null` for three different reasons, distinguished by its sibling field
+`volumeShareReason` (`--surfaces`/`--json`; the text view renders it as `share n/a
+(<reason>)`):
+
+- `"not-proposed"` — this feature TYPE is never turned into an acceptance candidate at
+  all. Fillets, chamfers, revolves and shells fall here today; they're still reported as
+  features, just not yet reconstructable through this pipeline.
+- `"budget"` — a candidate WAS proposed, but the search ran out of `--budget` before
+  reaching it. Raise `--budget` and re-describe; the feature may resolve to a real share
+  once given the chance.
+- `"rejected"` — a candidate was proposed, built, and evaluated, but never won a round
+  (`accept.js`'s `MIN_GAIN_FRACTION` gate, or simply never the best candidate available).
+  Raising `--budget` will not change this outcome — the feature genuinely doesn't fit
+  well enough to explain a meaningful share of the part.
+
+`"budget"` and `"rejected"` are the two that matter most to get right, and the
+distinction is real, not cosmetic: "try a bigger budget" and "this doesn't fit" are
+different next actions for whoever is rebuilding the part.
+
+**What `describe` reconstructs today, and what it doesn't.** The FACTS layer — surfaces,
+arcs, holes, dress-ups, sweeps, patterns, symmetry — covers the tool's full detection
+vocabulary; a feature can be *reported* there regardless of shape. The RECONSTRUCTION
+score (`explainedVolumeFraction`, and every accepted feature's own `volumeShare`) is
+narrower: `toCandidate` only proposes box and cylinder footprints as acceptance
+candidates today, so it currently reconstructs prismatic parts built from roughly fewer
+than eight box/cylinder features well, and does not yet reconstruct round bosses,
+revolves, fillets, chamfers, or shells — those are detected and reported (with
+`volumeShareReason: "not-proposed"`) but never turned into a candidate that could win
+volume back. Measured directly on this repo's own reference parts: `demo.js`
+reconstructs 65.7% of its volume, `filleted-box.js` 36.2%, `bracket.js` 23.6%, a plain
+tube 0.0%, and a hollow box 1.9%. The low-coverage banner fires on every one of these, so
+nothing here is misreported — but a low `explainedVolumeFraction` on a turned or
+feature-dense part means **"not yet reconstructable by this tool"**, not "not
+understood" or "broken." Read the FACTS (features, surfaces, patterns) as the ground
+truth regardless of the volume score; read the volume score as a measure of how much of
+that ground truth also comes with a working, boolean-verified rebuild recipe.
+
+**Closed error set.** Anything short of a programming mistake comes back as
+`{error: "<code>", detail, diagnostic}` rather than a thrown exception — a CLI or an
+agent can act on a code far better than on a stack trace — and every code has an
+ERROR-PATTERNS.md entry:
+
+- `not-manifold` — the mesh still has open edges after repair; see
+  [ERROR-PATTERNS.md#describe-not-manifold](ERROR-PATTERNS.md#describe-not-manifold).
+- `too-large` — over the 400,000-triangle segmentation ceiling; see
+  [ERROR-PATTERNS.md#describe-too-large](ERROR-PATTERNS.md#describe-too-large).
+- `empty` — the mesh has zero triangles; see
+  [ERROR-PATTERNS.md#describe-empty](ERROR-PATTERNS.md#describe-empty).
+- `unreadable` — `solid.toMesh()` itself threw; see
+  [ERROR-PATTERNS.md#describe-unreadable](ERROR-PATTERNS.md#describe-unreadable).
+
+`not-manifold` and `empty` describe real states `describe()` itself checks for and can
+return through any caller that hands it a `Solid` directly, but through the CLI they are
+largely theoretical: `kernel.import()`'s own registration validation rejects an empty or
+a wide-open (non-manifold) mesh *before* a `Solid` ever exists to describe, so
+`partforge describe` on such a file fails earlier, as a generic import error (the
+`crash()` path every other verb shares — `describe: import "x": mesh is not a solid
+after repair…`) rather than as a structured `{error: "not-manifold"}` / `{error:
+"empty"}` report. See
+[ERROR-PATTERNS.md#import-mesh-not-solid](ERROR-PATTERNS.md#import-mesh-not-solid) for
+that failure. `describe-unreadable`'s own ERROR-PATTERNS entry already draws this same
+line for its own code (a `k.import` parse failure is a *different*, separately-thrown
+error, not `describe-unreadable`); this is the general version of that point.
+
+A `budget-exceeded` report (the acceptance loop ran out of boolean attempts before the
+residual converged) is not one of these — it's a `warning` on an otherwise-valid report,
+same tier as low coverage, not a reason to exit non-zero; raise `--budget` and re-run.
+`compactDescribe()` surfaces it exactly where the low-coverage banner lives, and shows
+both together if a report happens to earn both — an exhausted budget is exactly the kind
+of run that also leaves coverage low, and neither warning is allowed to mask the other.
+See [ERROR-PATTERNS.md#describe-budget-exceeded](ERROR-PATTERNS.md#describe-budget-exceeded).
+
+**The loop this completes.** `describe` exists to feed a specific workflow, the one
+"Importing geometry" above sets up and this closes: `describe` the import to get its
+feature list and a proposed reconstruction (`suggestion` in the full report); write a
+parametric part from that proposal; bind the rebuild's sub-part to the import with
+`reference: "scan"`; and let `verify`'s `ref*` gates (`refXorVolume`, `refVolumeDeltaPct`,
+`refBboxDelta` — "The `reference` field and the deviation gate", above) hold the rebuild
+to the scan on every future `measure`/`verify` run, long after the one-time `describe`
+call that suggested it. `describe` proposes; `verify` keeps you honest.
+
 ---
 
 ## Wiring a part into a runnable app

package/docs/ERROR-PATTERNS.md

@@ -601,6 +601,36 @@ between the Manifold preview and the OCCT STEP export.
 
   The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
 
+## describe-not-manifold
+
+- **Symptom:** `describe` returns `{"error": "not-manifold"}`.
+- **Cause:** The mesh still has open edges after vertex-merge and winding repair, so it does not bound a solid and acceptance cannot diff against it.
+- **Fix:** Repair the mesh before describing it — Meshmixer, `meshlabserver`, or the slicer's own repair. `describe` will not repair geometry it was asked to report on; silently sealing a hole would make the report a description of a mesh the user does not have.
+
+## describe-too-large
+
+- **Symptom:** `{"error": "too-large"}` naming a triangle count.
+- **Cause:** Above 400,000 triangles the segmentation pass stops being usable in an interactive loop.
+- **Fix:** Decimate first. A CAD-exported STL re-exported at a coarser chord tolerance loses nothing the describer uses; the feature vocabulary reads surfaces, not facets.
+
+## describe-empty
+
+- **Symptom:** `{"error": "empty"}`.
+- **Cause:** The mesh has zero triangles — usually an import that resolved to an empty file, or a `k.import` name that registered as an error entry.
+- **Fix:** Check the `imports` source actually resolves. See [import-unknown-name](#import-unknown-name).
+
+## describe-budget-exceeded
+
+- **Symptom:** The report carries `warning: "budget-exceeded"` and `score.xorFraction` is higher than expected.
+- **Cause:** The acceptance loop hit its boolean budget before the residual converged. The report is partial but honestly scored — not wrong, just incomplete.
+- **Fix:** Raise `--budget`, or accept the partial description. A part needing far more than the default is usually one where a residual region is being attacked by many near-identical candidates; check `residual.regions` first.
+
+## describe-unreadable
+
+- **Symptom:** `{"error": "unreadable"}`.
+- **Cause:** `solid.toMesh()` threw rather than returning geometry — a corrupt or otherwise unrepresentable solid.
+- **Fix:** Confirm the source file parses cleanly upstream (`k.import` itself throws separately for an unparseable STL/3MF/STEP — see [import-unknown-name](#import-unknown-name)); re-export the file if the kernel cannot read back what it just built. STL is assumed to be in millimetres (the format carries no unit metadata) — see the import section of AUTHORING-PARTS.md.
+
 ## control-default-not-literal
 
 - **Symptom:** A control works live — the slider moves, the geometry updates — but the user's panel edits are gone when the part is reopened. Nothing throws anywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/jobs.js

@@ -15,6 +15,15 @@ import { verify } from "./oracle/verify.js";
 import { buildView } from "./oracle/build.js";
 import { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./oracle/silhouette.js";
 import { matchViews } from "./oracle/match.js";
+import { describe as describeMesh, describeMemo } from "./oracle/describe.js";
+import { compactDescribe } from "./oracle/describe/report.js";
+
+// One describe memo for the life of this worker. Deliberately NOT swept on setPart the
+// way solid-cache is: describe is pure in the mesh bytes (spec §4.1), so an edit can
+// never invalidate it, and dropping it on rebind would throw away the single most
+// expensive thing this worker computes for no reason at all. Keyed by content digest, so
+// a genuinely changed file misses correctly.
+const DESCRIBE_MEMO = describeMemo();
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -375,6 +384,28 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
       if (match) report.match = match;
       post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
+    } else if (msg.type === "describe") {
+      // Semantic description of an IMPORTED mesh — not of the built part. The two are
+      // different questions: `inspect` asks "what did this source build?", `describe`
+      // asks "what is this file?". describe never touches the part's own geometry, which
+      // is why it takes an import name rather than a view.
+      //
+      // Manifold only, and not by choice on this path: mesh imports on OCCT are never
+      // attempted, so a describe job posted to an OCCT worker is a routing bug, not a
+      // fallback opportunity. It surfaces as an ordinary error rather than a reroute.
+      const solid = kernel.import(msg.importName);      // throws on an unknown name
+      // `_importDigest` is the backend's existing underscore side-channel (KERNEL-CONTRACT
+      // "Conformance classes") — the same digest already folded into every import cache key.
+      const digest = kernel._importDigest?.(msg.importName) ?? null;
+      const full = describeMesh(kernel, solid, {
+        name: msg.importName,
+        digest,
+        budget: msg.budget,
+        memo: DESCRIBE_MEMO,
+      });
+      // The compact shape is derived, never memoised separately: one memo entry per
+      // mesh, two views of it, no way for the two to drift.
+      post({ type: "describe-report", report: msg.compact ? compactDescribe(full) : full });
     }
   } catch (err) {
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the

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?.();
+  }
+}