partforge 0.79.0 → 0.81.0

package/bin/cli.js

@@ -15,8 +15,6 @@ 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,
@@ -27,6 +25,25 @@ import { matchPattern } from "../src/testing/error-patterns.js";
 import { lintPart } from "../src/lint.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
+
+// The semantic mesh oracle (`describe`) lives in a separate, closed package — this
+// CLI names it only here, and resolves it at CALL time so every other verb works
+// without it installed. PARTFORGE_ORACLE overrides the specifier (a path or module
+// name) — how the oracle package's own repo points this CLI at its working tree.
+const ORACLE_PACKAGE = "@pixiteapps/partforge-oracle";
+async function loadOracle() {
+  const spec = process.env.PARTFORGE_ORACLE ?? ORACLE_PACKAGE;
+  const target = spec.startsWith(".") || spec.startsWith("/")
+    ? pathToFileURL(resolve(process.cwd(), spec)).href
+    : spec;
+  try {
+    return await import(target);
+  } catch (e) {
+    die(`describe needs the mesh-oracle package (${ORACLE_PACKAGE}), which is not installed.\n` +
+        `Install it from the private registry (or set PARTFORGE_ORACLE to a local path) and retry.\n` +
+        `(import of ${spec} failed: ${e?.message ?? e})`);
+  }
+}
 const USAGE = "usage: partforge <lint|measure|render|describe|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
@@ -210,6 +227,7 @@ const commands = {
         die(`describe: "${importName}" is not a declared import of ${partPath} ` +
             `(have: ${Object.keys(part.imports ?? {}).join(", ") || "none"})`);
       }
+      const { describe: describeMesh, compactDescribe } = await loadOracle();
       const kernel = await bootKernel(part);
       const solid = kernel.import(importName);
       const report = describeMesh(kernel, solid, {
@@ -222,7 +240,7 @@ const commands = {
         writeFileSync(flags.out, JSON.stringify(report, null, 2));
       }
       if (flags.json) console.log(JSON.stringify(report, null, 2));
-      else printDescribe(report, { surfaces: !!flags.surfaces });
+      else printDescribe(report, { surfaces: !!flags.surfaces }, compactDescribe);
       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
@@ -448,7 +466,7 @@ function printVerify(v) {
 // 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 }) {
+function printDescribe(report, { surfaces }, compactDescribe) {
   if (report.error) {
     console.error(`describe: ${report.error}${report.detail ? ` — ${report.detail}` : ""}`);
     return;

package/docs/AUTHORING-PARTS.md

@@ -1496,165 +1496,29 @@ build: (k, p, d) => {
 
 ## 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 <part-module>#<importName>` reads an already-declared import
+and emits a semantic feature report — holes, bosses, pockets, extrusions, patterns,
+symmetry — rather than a triangle soup, so an agent can rebuild an STL parametrically.
+
+The engine behind it — the semantic mesh oracle — is **not part of this package**: it
+ships as a separate, closed package (`@pixiteapps/partforge-oracle`) whose docs carry
+the full report contract (the two report shapes, feature vocabulary, `volumeShare`
+semantics, coverage scores, budget behavior, and the closed error set). This repo
+keeps only the seams:
+
+- **CLI** — `partforge describe` resolves the oracle package at call time and prints
+  an install pointer when it is absent (`PARTFORGE_ORACLE` overrides the module
+  specifier, which is how the oracle's own repo points this CLI at its working tree).
+- **Worker** — the `describe` job runs whatever `runWorker(part, { loadOracle })`
+  injected; without a loader it answers a structured
+  `{error: "oracle-unavailable"}` report (see
+  [ERROR-PATTERNS.md#describe-oracle-unavailable](ERROR-PATTERNS.md#describe-oracle-unavailable)),
+  never a stall. The loader resolves the oracle barrel: `describe`, `describeMemo`,
+  `compactDescribe`.
+- **Helpers** — the oracle package peer-depends on this one and consumes
+  `partforge/oracle`'s mesh/BVH helpers and file parsers (`bounds`, `meshArea`,
+  `meshTriangles`, `parseStl`, `parse3MF`); those exports are part of its contract.
 
-```
-$ 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,12 @@ 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-oracle-unavailable
+
+- **Symptom:** A `describe` job answers `{"error": "oracle-unavailable"}`, or `partforge describe` exits with "describe needs the mesh-oracle package".
+- **Cause:** The semantic mesh oracle is a separate, closed package (`@pixiteapps/partforge-oracle`), and this app or shell doesn't have it: the worker was started without `runWorker(part, { loadOracle })`, or the CLI could not import the package.
+- **Fix:** Install the oracle package from the private registry and inject it — `runWorker(part, { loadOracle: () => import("@pixiteapps/partforge-oracle") })` in the app's worker file, or plain `npm install` for the CLI. In the oracle package's own repo, set `PARTFORGE_ORACLE` to a local path instead. Every other job (generate, export, inspect) works without it.
+
 ## describe-not-manifold
 
 - **Symptom:** `describe` returns `{"error": "not-manifold"}`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.79.0",
+  "version": "0.81.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

@@ -12,23 +12,29 @@ import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.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.
+// JS payload in the worker's graph (measure/verify/build and silhouette/match), and
+// only the `inspect` job runs 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"),
-]);
+
+// The DESCRIBE stack is not part of this package at all: the semantic mesh oracle
+// lives in a separate, closed package, and this open framework never names it. A
+// host that has it INJECTS a loader — `runWorker(part, { loadOracle })`, threaded
+// here as `opts.loadOracle`, resolving to the oracle package's barrel (describe,
+// describeMemo, compactDescribe). Injection rather than a bare import specifier is
+// deliberate: a literal `import("@scope/pkg")` in open source would fail every
+// downstream Vite build where the package isn't installed, while an injected thunk
+// is simply absent — and an absent oracle answers the job with the structured
+// `oracle-unavailable` report below instead of stalling or throwing.
 
 // 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
@@ -417,7 +423,24 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // 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();
+      if (!opts.loadOracle) {
+        // Same closed-set, returned-not-thrown error contract describe itself keeps
+        // (its errors are findings, not crashes) — shaped as the structured triple the
+        // whole repo emits, so a caller can act on the code. ERROR-PATTERNS.md#describe-
+        // oracle-unavailable carries the fix.
+        post({ type: "describe-report", report: {
+          error: "oracle-unavailable",
+          detail: "this app was built without the mesh oracle package",
+          diagnostic: {
+            cause: "the describe job needs the closed oracle package, and no loadOracle loader was injected into runWorker",
+            location: `describe "${msg.importName}"`,
+            correctiveAction: "install the oracle package and pass runWorker(part, { loadOracle: () => import(...) }); see ERROR-PATTERNS.md#describe-oracle-unavailable",
+          },
+          source: { name: msg.importName, digest: null },
+        } });
+        return;
+      }
+      const { describe: describeMesh, describeMemo, compactDescribe } = await opts.loadOracle();
       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.

package/src/framework/worker.js

@@ -36,7 +36,10 @@ async function occtKernel() {
   return createOcctKernel(replicad);
 }
 
-export function runWorker(part) {
+// `opts.loadOracle` — the injection seam for the closed mesh-oracle package (see
+// jobs.js's describe branch): a thunk resolving to the oracle barrel. Apps without
+// the package simply omit it and describe jobs answer `oracle-unavailable`.
+export function runWorker(part, opts = {}) {
   const backend = self.name === "occt" ? "occt" : "manifold";
   let manifold = null; // { preview, print }
   let occt = null;
@@ -99,7 +102,7 @@ export function runWorker(part) {
           const kernel = await kernelFor(job.data);
           // handle() declares each message's transferables (the big binary buffers).
           const post = (m, transfer = []) => postMessage(m, transfer);
-          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes }); continue; }
+          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, loadOracle: opts.loadOracle }); continue; }
           const isStale = () => job.epoch !== epoch;
           // Post gate. The boundary check cannot catch a generate that goes stale during
           // its FINAL sub-part — there is no boundary after it — nor a single-sub-part
@@ -108,7 +111,7 @@ export function runWorker(part) {
           // contract simple: a `meshes` post is current as of the moment it is posted.
           const gated = (m, transfer = []) =>
             (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
-          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes });
+          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, loadOracle: opts.loadOracle });
         } catch (err) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
           // Carry the job's jobId when it has one (capture/export are correlated by it):

package/src/oracle.js

@@ -2,26 +2,30 @@
 //
 // This is the SEAM between the oracle and everything that consumes it. The same
 // modules serve three callers: the geometry worker lazy-loads them per job family
-// (see jobs.js — an `inspect` pulls measure/verify/build, a `describe` pulls the
-// describe stack, and the generate/export hot path pulls none), the CLI and Node
-// harnesses import them here directly, and partforge/testing re-exports this whole
-// surface so an existing downstream import keeps working. Everything below is
-// DOM-free, three-free and node:-free — test/oracle-entry.test.js walks the closure
-// and holds that, so the entry stays importable from a worker, a browser, or Node
-// alike. If the oracle ever moves to its own package, this file is the boundary
-// consumers are already importing through.
+// (see jobs.js — an `inspect` pulls measure/verify/build, and the generate/export
+// hot path pulls none), the CLI and Node harnesses import them here directly, and
+// partforge/testing re-exports this whole surface so an existing downstream import
+// keeps working. Everything below is DOM-free, three-free and node:-free —
+// test/oracle-entry.test.js walks the closure and holds that, so the entry stays
+// importable from a worker, a browser, or Node alike.
+//
+// The SEMANTIC MESH ORACLE (`describe`) is NOT here: it lives in its own closed
+// package, which peer-depends on this one and consumes exactly this entry — the
+// mesh/BVH helpers and file parsers below are exported for it. The framework
+// reaches it only through injection (`runWorker(part, { loadOracle })`, jobs.js)
+// and the CLI resolves it at call time; neither ever bundles it.
 export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
-export { meshVolume, bboxSize } from "./framework/oracle/mesh.js";
+export { meshVolume, bboxSize, bounds, meshArea } from "./framework/oracle/mesh.js";
 export { buildView } from "./framework/oracle/build.js";
 export { measure } from "./framework/oracle/measure.js";
 export { verify } from "./framework/oracle/verify.js";
-export { buildBVH } from "./framework/oracle/bvh.js";
+export { buildBVH, meshTriangles } from "./framework/oracle/bvh.js";
 export { minWall } from "./framework/oracle/min-wall.js";
+// Mesh file parsers — the import pipeline's own readers, browser-safe pure
+// functions; the oracle package's corpus tests read real files through them.
+export { parseStl } from "./framework/geometry/stl-parse.js";
+export { parse3MF } from "./framework/geometry/threemf-parse.js";
 // Silhouette match scoring — the `inspect` job scores `matchTargets` with exactly
 // these, re-exported so a downstream harness can reproduce a score outside the job loop.
 export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
 export { matchMasks, matchViews } from "./framework/oracle/match.js";
-// The semantic mesh oracle — what the `describe` job runs.
-export { describe, describeMemo, DESCRIBE_ERRORS } from "./framework/oracle/describe.js";
-export { compactDescribe, LOW_COVERAGE } from "./framework/oracle/describe/report.js";
-export { DESCRIBE_LIMITS } from "./framework/oracle/describe/limits.js";

package/types/oracle.d.ts

@@ -2,9 +2,9 @@
 //
 // The declarations themselves live in testing.d.ts, where this surface was first
 // published; this file re-exports exactly the names src/oracle.js exports, plus the
-// report/mask/gap types a caller needs to annotate results. If the oracle ever moves
-// to its own package, the declarations migrate here and testing.d.ts re-exports
-// instead — the direction flips, the names don't.
+// report/mask/gap types a caller needs to annotate results. The semantic mesh
+// oracle (`describe`) is its own closed package now — its types ship with it, and
+// the direction of this seam is what lets that package consume these helpers.
 export type { GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid } from "./testing.js";
 export {
   // measurement + verification
@@ -12,16 +12,11 @@ export {
   type MeasureReport, type SubPartFacts, type AggregateFacts, type BuiltSubPart,
   type VerifyReport, type VerifyCaseResult, type VerifyCheck, type CheckStatus,
   // mesh facts, gaps, BVH, min wall
-  meshVolume, bboxSize, assemblyGaps, meshGaps, buildBVH, minWall,
+  meshVolume, bboxSize, bounds, meshArea, assemblyGaps, meshGaps, buildBVH, meshTriangles, minWall,
   type Gap, type BVH,
+  // mesh file parsers (the import pipeline's own readers)
+  parseStl, parse3MF,
   // silhouette match scoring
   MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask, matchMasks, matchViews,
   type SilhouetteMask, type MatchScores, type MatchDelta,
-  // the semantic mesh oracle
-  describe, describeMemo, compactDescribe,
-  DESCRIBE_ERRORS, DESCRIBE_LIMITS, LOW_COVERAGE,
-  type DescribeReport, type DescribeCompactReport, type DescribeFailure,
-  type DescribeSurface, type DescribeArc, type DescribeFeature, type DescribePattern,
-  type DescribeResidualRegion, type DescribeSuggestion, type DescribeSuggestionStep,
-  type DescribeScore, type DescribeTruncated, type Snapped,
 } from "./testing.js";