partforge 0.80.0 → 0.82.0

package/src/framework/oracle/measure.js

@@ -1,6 +1,7 @@
 import { buildView } from "./build.js";
 import { cachedBVH } from "./bvh.js";
 import { assemblyOverlaps } from "../assembly.js";
+import { resolveParams } from "../part-model.js";
 import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
 import { bounds, meshArea, meshCentroid } from "./mesh.js";
 import { minWall, DIAGNOSTIC_SAMPLES } from "./min-wall.js";
@@ -12,6 +13,80 @@ const unionBounds = (list) => list.reduce(
   { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] },
 );
 
+// ── probes ──────────────────────────────────────────────────────────────────
+// Part-declared measurements: `probes: { name: (k, p, d) => Solid | JSON }`,
+// pure functions with build's exact contract but whose result lands in the
+// REPORT instead of the scene. The instrument a rebuild-against-reference
+// workflow needs — before this, getting a cross-section's numbers out of the
+// pipeline meant authoring throwaway `exportable: false` sub-parts and fishing
+// their facts out of the sub-part list (the "Probes" feedback report).
+// A Solid anywhere in the return value (duck-typed on volume+toMesh, the two
+// queries the facts need) is replaced by a fact object; scalars/arrays/objects
+// pass through; a throw becomes `{ error }` — probes are instrumentation, so
+// they never crash the measurement and never gate `ok`.
+
+const isSolid = (v) => v !== null && typeof v === "object"
+  && typeof v.volume === "function" && typeof v.toMesh === "function";
+
+function solidProbeFacts(solid) {
+  const mesh = solid.toMesh();
+  // Empty = the probe's boolean found nothing (a slab that misses the part).
+  // A first-class answer, not degenerate infinite bounds: "the reference has no
+  // material here" is exactly what a localizing probe is asked.
+  const empty = typeof solid.isEmpty === "function" ? solid.isEmpty() : mesh.triangles === 0;
+  if (empty) {
+    return { empty: true, bbox: null, bounds: null, centerOfMass: null,
+      volume: 0, surfaceArea: 0, triangleCount: 0, watertight: null, holes: null };
+  }
+  const b = bounds(mesh.positions);
+  return {
+    empty: false,
+    bbox: size(b),
+    bounds: { min: b.min, max: b.max },
+    centerOfMass: meshCentroid(mesh.positions, mesh.indices),
+    volume: solid.volume(),
+    surfaceArea: meshArea(mesh.positions, mesh.indices),
+    triangleCount: mesh.triangles,
+    // Mirrors the sub-part fact: answered by isEmpty where the backend has it
+    // (and this branch already means it said false), null where it can't say.
+    watertight: typeof solid.isEmpty === "function" ? true : null,
+    holes: typeof solid.genus === "function" ? solid.genus() : null,
+  };
+}
+
+// Bounded so a self-referential or absurdly deep return value can't hang the
+// report; past the cap the value is summarized rather than walked.
+const MAX_PROBE_VALUE_DEPTH = 4;
+function resolveProbeValue(v, depth = 0) {
+  if (isSolid(v)) return solidProbeFacts(v);
+  if (v === null || typeof v !== "object") {
+    return typeof v === "function" ? { error: "probe returned a function — return a Solid or plain JSON" } : v;
+  }
+  if (depth >= MAX_PROBE_VALUE_DEPTH) return { error: `probe value deeper than ${MAX_PROBE_VALUE_DEPTH} levels` };
+  if (Array.isArray(v)) return v.map((x) => resolveProbeValue(x, depth + 1));
+  return Object.fromEntries(Object.entries(v).map(([key, x]) => [key, resolveProbeValue(x, depth + 1)]));
+}
+
+// Evaluate every declared probe with resolved (p, d). Reads all solid facts
+// eagerly, so the caller may free the kernel's objects afterwards. Never
+// throws: each probe's failure is its own `{ error }` entry.
+function evaluateProbes(kernel, part, params) {
+  const { p, d } = resolveParams(part, params);
+  // Oracle-owned cache round, same reasoning as buildView's: probe geometry must
+  // not evict what the viewer is showing, and the next round evicts this one.
+  kernel.beginSubPart?.("oracle:probes");
+  try {
+    return Object.fromEntries(Object.entries(part.probes).map(([name, fn]) => {
+      try {
+        if (typeof fn !== "function") throw new Error("probe must be a function (k, p, d)");
+        return [name, resolveProbeValue(fn(kernel, p, d))];
+      } catch (e) {
+        return [name, { error: e?.message || String(e) }];
+      }
+    }));
+  } finally { kernel.endSubPart?.(); }
+}
+
 // Headless geometric report for one view of a part (Manifold-only). Reads exact
 // solid facts (volume/genus/emptiness) and mesh facts (bbox/area/triangles), plus
 // the assembly overlap check plus pair gap distances (near misses are reported,
@@ -100,6 +175,15 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     };
   });
 
+  // Declared probes, evaluated regardless of view (they are part-level facts —
+  // per-view probes were exactly the annoyance this replaces) and before
+  // assemblyOverlaps/cleanup below frees the kernel's objects. `opts.probes:
+  // false` skips them: verify's per-case re-measures pass it because no gate
+  // reads probe values, so re-running their booleans per case buys nothing.
+  const probes = opts.probes !== false && part.probes && Object.keys(part.probes).length
+    ? evaluateProbes(kernel, part, params)
+    : undefined;
+
   // Pair surface distances from the meshes already built — no kernel dependency,
   // so this reads on OCCT too. nearMisses = the issue-#29 signal: pairs that
   // *almost* touch; overlapping pairs are excluded by name (a fully-contained
@@ -155,6 +239,9 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     overlaps,
     gaps,
     nearMisses,
+    // Present only when the part declares probes AND this run evaluated them —
+    // a probe error stays inside its own entry and never reaches `ok` below.
+    ...(probes ? { probes } : {}),
     ok: subparts.every((s) => s.watertight !== false) && overlaps.length === 0,
   };
 }

package/src/framework/oracle/verify.js

@@ -266,7 +266,10 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
     const key = signature(params);
     if (memo.has(key)) return memo.get(key);
     if (quick) return null;   // a case the seed does not cover — reported, never built
-    memo.set(key, measureFn(kernel, part, view, params, { minWall: needMinWall }));
+    // `probes: false` — no gate reads probe values, so re-running their booleans
+    // for every case buys nothing. (A seed measured WITH probes is a superset in
+    // the same way a min-wall seed is: the extra key is simply never read here.)
+    memo.set(key, measureFn(kernel, part, view, params, { minWall: needMinWall, probes: false }));
     return memo.get(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/src/parts/import-demo.js

@@ -1,5 +1,7 @@
 // Reference part for docs/AUTHORING-PARTS.md's "Importing geometry" section —
-// the worked example for BOTH import uses in one part:
+// and for its "Probes" section (the `probes` block below measures the import
+// live into the measure report) — the worked example for BOTH import uses in
+// one part:
 //   • reference — `ref` is a translucent ghost of the imported scan (never
 //     exported); `body` is a parametric rebuild of the same block, bound to
 //     the scan via `reference: "scan"` and held to it by the three ref*
@@ -108,6 +110,25 @@ export default {
   // socket never touches `body` (see `mountOffsetX`). "reference" is the
   // ghost-overlay view, browsed by hand or with an explicit view argument.
   views: { assembly: { label: "Assembly" }, reference: { label: "Reference overlay" } },
+  // Probes — measurements that land in the `measure` report instead of the
+  // scene (docs/AUTHORING-PARTS.md "Probes"). Pure (k, p, d) functions like
+  // build; never rendered, never exported, reported for every view.
+  probes: {
+    // Paired 1 mm cross-sections of the rebuild and the scan at the same X
+    // station — the localizing instrument for the deviation gate above: when
+    // refXorVolume creeps up, slide the slab along X to find WHERE the two
+    // solids disagree instead of guessing from one whole-part number.
+    midSlab: (k, p) => {
+      const slab = () => k.box({ min: [9.5, -50, -50], max: [10.5, 50, 50] });
+      return {
+        body: k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }).intersect(slab()),
+        scan: k.import("scan").intersect(slab()),
+      };
+    },
+    // A live reading straight off the import — the numbers `defaults` were
+    // measured from. Plain JSON passes through the report verbatim.
+    scanBounds: (k) => k.import("scan").boundingBox(),
+  },
   verify: {
     process: "fdm-pla",
     expect: {

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";

package/types/testing.d.ts

@@ -186,6 +186,21 @@ export function meshVolume(positions: ArrayLike<number>, indices?: ArrayLike<num
 /** `[dx, dy, dz]` extent of a flat position array. */
 export function bboxSize(positions: ArrayLike<number>): [number, number, number];
 
+/** World-frame axis-aligned bounds of a flat position array. */
+export function bounds(positions: ArrayLike<number>): { min: [number, number, number]; max: [number, number, number] };
+
+/** Total surface area of an indexed (or soup, when `indices` is omitted) triangle mesh, mm². */
+export function meshArea(positions: ArrayLike<number>, indices?: ArrayLike<number>): number;
+
+/** Triangles as `[v0, v1, v2]` coordinate triples, from an indexed mesh or a soup. */
+export function meshTriangles(mesh: Mesh): [number, number, number][][];
+
+/** Parse a binary or ASCII STL into a welded, indexed mesh. */
+export function parseStl(bytes: Uint8Array | ArrayBuffer): { positions: Float32Array; indices: Uint32Array };
+
+/** Parse a 3MF archive's first mesh object into a welded, indexed mesh. */
+export function parse3MF(bytes: Uint8Array | ArrayBuffer): { positions: Float32Array; indices: Uint32Array };
+
 // --- the BVH ----------------------------------------------------------------
 
 /** A triangle BVH over one mesh — nearest ray hit, nearest point, exact mesh distance. */
@@ -454,183 +469,6 @@ export function matchViews(
   opts?: { scaleAware?: boolean },
 ): { best: ({ view: string } & MatchScores) | null; views: Record<string, number> };
 
-// --- describe (the semantic mesh oracle) ------------------------------------
-
-/** A raw measurement snapped to intent — never destroys the measurement. */
-export interface Snapped {
-  raw: number;
-  to: number;
-  note: string | null;
-}
-
-/** One fitted surface patch. `fit` is the raw per-type fit record (fit.js). */
-export interface DescribeSurface {
-  id: string;
-  type: string;
-  area: number;
-  triangles: number;
-  rms: number;
-  maxDev: number;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- shape varies by surface type (plane/cylinder/cone/torus/sphere)
-  fit: Record<string, any>;
-}
-
-/** One fitted edge between two surfaces. */
-export interface DescribeArc {
-  between: [string, string];
-  convexity: "convex" | "concave" | "flat";
-  kind: string;
-  radius: number | null;
-  axis: unknown;
-  length: number;
-}
-
-/**
- * One recognised feature. Shape varies by `type` (a hole carries `diameter`/
- * `axis`, a fillet carries `radius`/`between`, …) — the fields every family
- * shares are pulled out here; the rest is read by `type`. Every field here
- * must be something a rebuilding agent would want (round 4 review) —
- * `surfaces`/`evidence` are; nothing per-triangle belongs here. describe.js
- * strips any such internal-plumbing field (`faceScope`, a prismatic
- * candidate builder's own per-triangle index map) before a feature reaches
- * this shape, so this catch-all is not a substitute for that discipline.
- */
-export interface DescribeFeature {
-  id: string;
-  key: string;
-  type: string;
-  /** The marginal xor-volume reduction that admitted this feature, normalised
-   * to the source volume — the fraction of the PART'S VOLUME this feature
-   * accounts for, not a certainty rating (see `DescribeScore`'s own note): a
-   * small-but-certain feature legitimately reports a small share. `null` for
-   * a type acceptCandidates never proposes (fillet, chamfer, revolve, shell). */
-  volumeShare: number | null;
-  /** Snapped values for whichever of diameter/depth/radius/width/thickness this feature carries. */
-  snapped: Record<string, Snapped>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-type facts (axis, profile, evidence, …)
-  [key: string]: any;
-}
-
-/** A repetition (grid/linear/circular) or a detected mirror plane over the feature list. */
-export interface DescribePattern {
-  id: string;
-  type: "grid" | "linear" | "circular";
-  members: string[];
-  axis: number[] | null;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-type spacing/count facts
-  [key: string]: any;
-}
-
-/** One connected island of mesh area no surface fit claimed. */
-export interface DescribeResidualRegion {
-  triangles: number;
-  centroid: number[];
-  bounds: { min: number[]; max: number[] };
-}
-
-/** One proposed rebuild step, in the order acceptCandidates actually admitted it. */
-export interface DescribeSuggestionStep {
-  op: string;
-  explains: string[];
-  pattern: string | null;
-  score: number;
-  args: Record<string, unknown>;
-}
-
-/** A proposed reconstruction — an interpretation, not a measurement (see `disclaimer`). */
-export interface DescribeSuggestion {
-  disclaimer: string;
-  params: Array<{ name: string; value: number; from: string }>;
-  steps: DescribeSuggestionStep[];
-}
-
-/** Which of the report's capped arrays actually hit their ceiling (`DESCRIBE_LIMITS`). */
-export interface DescribeTruncated {
-  surfaces: boolean;
-  edges: boolean;
-  features: boolean;
-  patterns: boolean;
-  residualRegions: boolean;
-  suggestionSteps: boolean;
-}
-
-export interface DescribeScore {
-  /** Surface coverage from segmentation: fraction of the mesh's area fitted to some surface type. */
-  explainedArea: number;
-  /** Shape coverage from reconstruction: fraction of the part's volume the accepted features rebuild. */
-  explainedVolumeFraction: number;
-  xorFraction: number;
-  xorVolume: number;
-  note: string;
-}
-
-/** A full `describe()` report — everything measured, meant for archival/`--json`. */
-export interface DescribeReport {
-  source: { name: string | null; digest: string | null; triangles: number; watertight: boolean | null; units: "mm" };
-  frame: { up: "+Z"; note: string };
-  bounds: { min: number[]; max: number[]; size: number[] };
-  counts: { surfaces: number; edges: number };
-  surfaces: DescribeSurface[];
-  edges: DescribeArc[];
-  features: DescribeFeature[];
-  patterns: DescribePattern[];
-  symmetry: unknown[];
-  residual: { areaFraction: number; regions: DescribeResidualRegion[] };
-  score: DescribeScore;
-  suggestion: DescribeSuggestion | null;
-  truncated: DescribeTruncated;
-  /** Present only when the acceptance loop hit its boolean budget before converging. */
-  warning?: "budget-exceeded";
-}
-
-/** The model-facing view: capped arrays elided to counts, a coverage banner first when low. */
-export type DescribeCompactReport = Omit<DescribeReport, "surfaces" | "edges"> & {
-  /** Present, and serialized FIRST, only when coverage is below `LOW_COVERAGE`. */
-  warning?: string;
-};
-
-/** A closed-set failure, returned rather than thrown (spec §5's diagnostic triple). */
-export interface DescribeFailure {
-  error: "not-manifold" | "too-large" | "empty" | "budget-exceeded" | "unreadable";
-  detail: string;
-  diagnostic: { cause: string; location: string; correctiveAction: string };
-  source: { name: string | null; digest: string | null; [key: string]: unknown };
-}
-
-/** The closed set of error codes `describe()` can return. */
-export const DESCRIBE_ERRORS: readonly string[];
-
-/** Report array ceilings (`MAX_SURFACES`, `MAX_FEATURES`, …) — a plain-data module, no imports. */
-export const DESCRIBE_LIMITS: {
-  MAX_SURFACES: number;
-  MAX_EDGES: number;
-  MAX_FEATURES: number;
-  MAX_PATTERNS: number;
-  MAX_RESIDUAL_REGIONS: number;
-  MAX_SUGGESTION_STEPS: number;
-};
-
-/** Below this fraction (the worse of `explainedArea`/`explainedVolumeFraction`) `compactDescribe` prepends a warning. */
-export const LOW_COVERAGE: number;
-
-/** A fresh, caller-owned digest memo — scope one per worker, or per test. */
-export function describeMemo(): Map<string, DescribeReport>;
-
-/**
- * Mesh in, semantic feature report out. `solid` is a LIVE kernel `Solid` — the
- * kernel has no public mesh->solid constructor, so a caller reads one back via
- * `kernel.import(name)`. Keyed by `opts.digest` in `opts.memo` (when both are
- * given): the report depends on nothing but the mesh bytes, so an edit to the
- * part that produced the mesh can never invalidate it.
- */
-export function describe(
-  kernel: GeometryKernel,
-  solid: Solid,
-  opts?: { name?: string; digest?: string; budget?: number; memo?: Map<string, DescribeReport> },
-): DescribeReport | DescribeFailure;
-
-/** The full report, reduced to what a model should read: capped arrays elided to counts, low-coverage banner first. */
-export function compactDescribe(full: DescribeReport): DescribeCompactReport;
 
 // --- rendering --------------------------------------------------------------
 

package/types/worker.d.ts

@@ -17,5 +17,13 @@ export interface WorkerHandle {
   setPart(newPart: PartDefinition): void;
 }
 
-/** Run the worker job loop for `part`. Call once, at worker module top level. */
-export function runWorker(part: PartDefinition): WorkerHandle;
+/**
+ * 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.
+ */
+export function runWorker(
+  part: PartDefinition,
+  opts?: { loadOracle?: () => Promise<{ describe: Function; describeMemo: () => Map<string, unknown>; compactDescribe: Function }> },
+): WorkerHandle;