partforge 0.77.0 → 0.79.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
@@ -1788,7 +1948,11 @@ access. It's harmless to leave in when partforge is a normal install.)
 ## Testing a part
 
 Tests run under **Node 24** (`nvm use` first; the default shell Node is too old) via
-`npx vitest run`. Build geometry directly off your part with a Manifold kernel:
+`npx vitest run`. The oracle half of this surface — `measure`, `verify`,
+`describe`, gaps, match scoring — is also published on its own as
+`partforge/oracle` (browser-safe import closure); `partforge/testing` re-exports
+it, so either import works. Build geometry directly off your part with a Manifold
+kernel:
 
 ```js
 import { bootManifoldKernel, resolveDerived } from "partforge/testing";

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.79.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",
@@ -45,6 +45,10 @@
       "types": "./types/derive.d.ts",
       "default": "./src/framework/derive.js"
     },
+    "./oracle": {
+      "types": "./types/oracle.d.ts",
+      "default": "./src/oracle.js"
+    },
     "./testing": {
       "types": "./types/testing.d.ts",
       "default": "./src/testing.js"
@@ -66,6 +70,9 @@
       "derive": [
         "./types/derive.d.ts"
       ],
+      "oracle": [
+        "./types/oracle.d.ts"
+      ],
       "testing": [
         "./types/testing.d.ts"
       ]

package/src/framework/jobs.js

@@ -10,11 +10,32 @@ import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
-import { measure } from "./oracle/measure.js";
-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";
+
+// The oracle loads LAZILY, per job family, never at worker boot. It is the largest
+// JS payload in the worker's graph (measure/verify/build, silhouette/match, and the
+// describe stack), and only the `inspect` and `describe` jobs run any of it — the
+// generate/export hot path touches none. Each family below is a literal dynamic
+// import(), which Vite splits into its own chunk under `worker.format: "es"` (this
+// repo's config and partforge-cloud's both), so a user who never runs an oracle job
+// never downloads or parses one. The module loader caches the namespace after the
+// first await, so repeat jobs pay a resolved-promise tick, not a re-fetch.
+// test/worker-layering.test.js's eager-closure guard holds this in place.
+const loadInspect = () => Promise.all([
+  import("./oracle/build.js"),
+  import("./oracle/measure.js"),
+  import("./oracle/verify.js"),
+]);
+const loadDescribe = () => Promise.all([
+  import("./oracle/describe.js"),
+  import("./oracle/describe/report.js"),
+]);
+
+// One describe memo for the life of this worker, created alongside the stack's first
+// load. 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.
+let DESCRIBE_MEMO = null;
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -38,7 +59,7 @@ const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 // cannot cost the others their scores (or the caller their geometry report).
 //   {kind: "profile", rings: [[[x,y], ...], ...]}  — millimetres, so it carries scale
 //   {kind: "image",   mask: {data, width, height}} — a photo, so it carries none
-function referenceMask(target) {
+function referenceMask(target, rasterizeRingsMask) {
   if (target?.kind === "profile") return Array.isArray(target.rings) ? rasterizeRingsMask(target.rings) : null;
   if (target?.kind === "image") {
     const m = target.mask;
@@ -61,9 +82,15 @@ function referenceMask(target) {
 //
 // The six mesh masks are rasterized ONCE and shared across every target — the targets
 // are the cheap side of this (a couple of reference masks), the part is not.
-function scoreMatchTargets(built, targets, onProgress) {
+async function scoreMatchTargets(built, targets, onProgress) {
   if (!targets?.length) return null;
   try {
+    // Loaded here, past the early return: an inspect with no matchTargets — the
+    // common case — never pays for the rasterizer.
+    const [{ MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask }, { matchViews }] = await Promise.all([
+      import("./oracle/silhouette.js"),
+      import("./oracle/match.js"),
+    ]);
     const meshes = built.map((b) => b.mesh);
     const viewMasks = {};
     for (const view of MATCH_VIEWS) viewMasks[view] = rasterizeMeshMask(meshes, view);
@@ -71,7 +98,7 @@ function scoreMatchTargets(built, targets, onProgress) {
     const out = [];
     for (const target of targets) {
       try {
-        const reference = referenceMask(target);
+        const reference = referenceMask(target, rasterizeRingsMask);
         if (!reference) continue;
         // scaleAware is the CALLER's promise that both sides are in millimetres, and
         // this is the caller: rings are mm and the mesh masks carry mmPerPx, so a
@@ -356,6 +383,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // unrecognized value must never quietly buy less checking than the caller
       // asked for.
       const quick = msg.checks === "quick";
+      const [{ buildView }, { measure }, { verify }] = await loadInspect();
       const view = msg.view ?? Object.keys(part.views)[0];
       const built = buildView(kernel, part, view, msg.params ?? {});
       const measured = measure(kernel, part, view, msg.params ?? {},
@@ -366,15 +394,44 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           // The defaulted view, not msg.view: the seed below was measured on it, and
           // verify's seed reuse is only sound when both name the same view.
           view,
+          // This job's own (lazily-imported) measure, not verify's static fallback:
+          // the two are different module instances once measure.js loads through a
+          // dynamic import, and the seeding test's call-count mock only sees this
+          // one. One binding for the whole inspect keeps that countable — and true.
+          measureFn: measure,
           quick,
           seed: { params: msg.params ?? {}, result: measured },
         }),
       };
       // `match` is present only when the caller asked for it AND something scored, so
       // an inspect with no `matchTargets` answers on exactly the shape it always has.
-      const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
+      const match = await 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 [{ describe: describeMesh, describeMemo }, { compactDescribe }] = await loadDescribe();
+      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;
+      DESCRIBE_MEMO ??= describeMemo();
+      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