partforge 0.85.4 → 0.86.0

package/bin/cli.js

@@ -26,25 +26,7 @@ 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> …";
+const USAGE = "usage: partforge <lint|measure|render|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
@@ -205,52 +187,6 @@ 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 { describe: describeMesh, compactDescribe } = await loadOracle();
-      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 }, 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
-      // 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>]";
@@ -488,83 +424,6 @@ 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 }, compactDescribe) {
-  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

@@ -1559,30 +1559,26 @@ 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
-
-`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.
+## Host jobs: extending the worker
+
+The worker's job loop handles a closed set of message types (`generate`, the exports,
+`inspect`, …). A host app can add its own: `runWorker(part, { jobs: { <type>:
+handler } })`. A message whose `type` matches no built-in is handed to the matching
+handler as `handler(kernel, part, msg, post, { isStale })` — the live kernel (so the
+handler can `kernel.import(name)` a declared import, or read `kernel._importDigest`),
+the part current when the message arrived, the message, and the poster for results
+(`post(msg, transferables?)`). A throw is posted as the ordinary `{type: "error",
+message, jobId}`; built-in types cannot be overridden; a type with no handler is
+ignored.
+
+This is the seam through which a host adds a capability this open framework does not
+ship. The semantic mesh oracle — imported mesh → feature report, for rebuilding an
+STL parametrically — is one: it is a separate, closed package with its own CLI, and
+the app that installs it registers its job here. This repo carries nothing
+oracle-shaped: no verb, no message types, no error codes. The one direction that
+does exist is the oracle peer-depending on this package for `partforge/oracle`'s
+mesh/BVH helpers and file parsers (`bounds`, `meshArea`, `meshTriangles`, `parseStl`,
+`parse3MF`); those exports are part of its contract.
 
 
 ## Probes: measuring geometry into the report
@@ -1947,8 +1943,8 @@ 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`. The oracle half of this surface — `measure`, `verify`,
-`describe`, gaps, match scoring — is also published on its own as
+`npx vitest run`. The oracle half of this surface — `measure`, `verify`, 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:

package/docs/ERROR-PATTERNS.md

@@ -652,42 +652,6 @@ 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"}`.
-- **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.85.4",
+  "version": "0.86.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

@@ -26,22 +26,16 @@ const loadInspect = () => Promise.all([
   import("./oracle/verify.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
-// 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;
+// HOST JOBS — the extension seam. A host registers its own job types with
+// `runWorker(part, { jobs: { <type>: handler } })`, threaded here as `opts.jobs`, and
+// a message whose type matches no built-in below is handed to that handler with the
+// live kernel, the current part, the message and the poster. This is how a host adds
+// a capability the open framework does not ship — partforge-cloud's semantic
+// mesh-oracle describe job lives entirely in its own closed package and arrives here
+// as one of these — without this repo naming it, importing it, or knowing its message
+// shapes. Built-ins win a name clash (a host cannot redefine `generate`); a type with
+// no handler at all is ignored, as unknown types always were. A handler's throw is
+// posted as the ordinary `{type: "error"}` any failed job posts.
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -414,47 +408,8 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       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.
-      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.
-      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 });
+    } else if (opts.jobs && Object.hasOwn(opts.jobs, msg.type)) {
+      await opts.jobs[msg.type](kernel, part, msg, post, { isStale: opts.isStale });
     }
   } catch (err) {
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the

package/src/framework/worker.js

@@ -36,9 +36,9 @@ async function occtKernel() {
   return createOcctKernel(replicad);
 }
 
-// `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`.
+// `opts.jobs` — host-registered job handlers, `{ <type>: (kernel, part, msg, post,
+// ctx) => … }` (see jobs.js's HOST JOBS comment). A message type no built-in claims
+// goes to the matching handler; apps with nothing to add simply omit it.
 export function runWorker(part, opts = {}) {
   const backend = self.name === "occt" ? "occt" : "manifold";
   let manifold = null; // { preview, print }
@@ -102,7 +102,7 @@ export function runWorker(part, opts = {}) {
           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, loadOracle: opts.loadOracle }); continue; }
+          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, jobs: opts.jobs }); 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
@@ -111,7 +111,7 @@ export function runWorker(part, opts = {}) {
           // 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, loadOracle: opts.loadOracle });
+          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, jobs: opts.jobs });
         } 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

@@ -9,11 +9,11 @@
 // 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.
+// The SEMANTIC MESH ORACLE (imported mesh -> feature report) is NOT here, and this
+// framework has no verb, job or import for it: it is 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. A host that installs it registers its
+// job through the generic `runWorker(part, { jobs })` seam (jobs.js).
 export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
 export { meshVolume, bboxSize, bounds, meshArea } from "./framework/oracle/mesh.js";
 export { buildView } from "./framework/oracle/build.js";

package/types/worker.d.ts

@@ -17,13 +17,29 @@ export interface WorkerHandle {
   setPart(newPart: PartDefinition): void;
 }
 
+/**
+ * A host-registered job handler (`runWorker`'s `opts.jobs`): receives the live
+ * kernel, the part current when the message arrived, the message itself, the
+ * poster for results (`post(msg, transferables?)`), and a context with `isStale`
+ * (set for jobs that can be superseded by a rebind). A throw is posted as the
+ * ordinary `{type: "error", message, jobId}`.
+ */
+export type HostJob = (
+  kernel: unknown,
+  part: PartDefinition,
+  msg: { type: string; jobId?: number; [key: string]: unknown },
+  post: (msg: object, transfer?: Transferable[]) => void,
+  ctx: { isStale?: () => boolean },
+) => void | Promise<void>;
+
 /**
  * Run the worker job loop for `part`. Call once, at worker module top level.
- * `opts.loadOracle` injects the closed semantic-mesh-oracle package (a thunk
- * resolving its barrel: `describe`, `describeMemo`, `compactDescribe`); omitted,
- * describe jobs answer with a structured `oracle-unavailable` report.
+ * `opts.jobs` registers host job types by message `type`: a message no built-in
+ * job claims is handed to the matching handler; built-ins are not overridable and
+ * a type with no handler is ignored. This is how a host adds capabilities the open
+ * framework does not ship.
  */
 export function runWorker(
   part: PartDefinition,
-  opts?: { loadOracle?: () => Promise<{ describe: Function; describeMemo: () => Map<string, unknown>; compactDescribe: Function }> },
+  opts?: { jobs?: Record<string, HostJob> },
 ): WorkerHandle;