partforge 0.81.0 → 0.82.0

package/bin/cli.js

@@ -438,6 +438,34 @@ function printMeasure(r) {
   console.log(`  near-misses: ${r.nearMisses.length
     ? r.nearMisses.map((g) => `${g.a}×${g.b} (${g.distance.toFixed(2)}mm at [${g.at.map((n) => n.toFixed(1)).join(", ")}])`).join(", ")
     : "none"}`);
+  if (r.probes) {
+    // Solid-fact probes get the sub-part line treatment (in mm³ — probes are
+    // localization instruments, a slab's volume in cm³ rounds to noise), one
+    // level deep too so the common paired shape ({ mine, ref }) reads as lines
+    // rather than a JSON wall; anything else prints as JSON; a failed probe
+    // prints its error where the reader is.
+    const isFacts = (v) => v && typeof v === "object" && "empty" in v && "volume" in v;
+    const factsLine = (v) => (v.empty
+      ? `empty (no material in the probed region)`
+      : `bbox ${v.bbox.map((n) => n.toFixed(2)).join("×")}  ` +
+        `bounds [${v.bounds.min.map((n) => n.toFixed(2)).join(", ")}]…[${v.bounds.max.map((n) => n.toFixed(2)).join(", ")}]  ` +
+        `vol ${v.volume.toFixed(2)}mm³`);
+    console.log(`  probes:`);
+    for (const [name, v] of Object.entries(r.probes)) {
+      if (v && typeof v === "object" && typeof v.error === "string") {
+        console.log(`    ${name}  ERROR: ${v.error}`);
+      } else if (isFacts(v)) {
+        console.log(`    ${name}  ${factsLine(v)}`);
+      } else if (v && typeof v === "object" && !Array.isArray(v) && Object.values(v).some(isFacts)) {
+        console.log(`    ${name}:`);
+        for (const [key, sub] of Object.entries(v)) {
+          console.log(`      ${key}  ${isFacts(sub) ? factsLine(sub) : JSON.stringify(sub)}`);
+        }
+      } else {
+        console.log(`    ${name}  ${JSON.stringify(v)}`);
+      }
+    }
+  }
 }
 
 function printVerify(v) {

package/docs/AUTHORING-PARTS.md

@@ -88,6 +88,8 @@ export default {
     },
   },
   views: { <name>: { label, default?, animations? } },  // view tabs; a view may own animations (below)
+  probes?,                                 // { name: (k, p, d) => Solid | plain JSON } — measurements reported by
+                                           // measure/inspect, never rendered or exported (see "Probes" below)
 };
 ```
 
@@ -1520,6 +1522,76 @@ keeps only the seams:
   `meshTriangles`, `parseStl`, `parse3MF`); those exports are part of its contract.
 
 
+## Probes: measuring geometry into the report
+
+A `probes` block turns the measure report into an instrument panel. Each probe is
+a pure `(k, p, d)` function with **build's exact contract** — same kernel handle,
+same resolved params and derived values — but its result lands in the **report**
+instead of the scene:
+
+```js
+probes: {
+  // A Solid anywhere in the return value is measured into a fact object:
+  // { empty, bbox, bounds, centerOfMass, volume, surfaceArea, triangleCount,
+  //   watertight, holes }
+  slabX12: (k, p, d) => buildBody(k, p, d)
+    .intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+
+  // The paired form — the localizing workhorse when a rebuild drifts from its
+  // imported reference: the same thin slab through both solids, side by side.
+  slabPair: (k, p, d) => ({
+    mine: buildBody(k, p, d).intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+    ref:  k.import("scan").intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+  }),
+
+  // Plain JSON passes through verbatim — compute any number the solid queries
+  // can reach (volume/boundingBox booleans, arc fits, whatever).
+  xor: (k, p, d) => {
+    const mine = buildBody(k, p, d), ref = k.import("scan");
+    return mine.volume() + ref.volume() - 2 * mine.intersect(ref).volume();
+  },
+}
+```
+
+**Where they show up.** `npx partforge measure` prints a `probes:` section and
+includes `probes: { name: value }` in `--json`; the worker's `inspect` job carries
+the same key, so any host reporting measure output (e.g. an agent's check loop)
+sees probe values on every edit with no extra wiring. Probes are **part-level,
+not per-view**: every measured view reports them, so they never disappear because
+the "wrong" tab was measured.
+
+**What they replace.** Before probes, 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 — polluting views, the control panel's
+mental model, and the overlap check. Probes are invisible to the viewer, the
+exporter, the assembly checks, and `verify` gates; they exist only in the report.
+
+**Failure is contained.** A probe that throws reports `{ error: "…" }` in its
+own slot — it never crashes the measurement and never flips the report's `ok`.
+An empty boolean result (a slab that misses the part) reports
+`{ empty: true, volume: 0 }` rather than degenerate infinite bounds — "no
+material here" is a first-class answer for a localizing probe. Lint covers
+probes with the same pass as builds: a throwing probe is `probe-throws`, a
+malformed block is `invalid-probes`, and unknown ops / bad options / impurity
+are caught exactly as in `build`.
+
+**Driving geometry from a live measurement.** Probes get numbers *out*. To feed
+a measurement *into* geometry, remember that `build` already holds a real
+kernel: `k.import("scan").boundingBox()` (and `.volume()`, and booleans between
+solids) work live inside any build, so a sub-part can size itself off another
+solid directly — no probe needed. Keep it pure: the measurement is deterministic
+for a given import + params, which is exactly what the geometry cache assumes.
+To set parameter **defaults** from a reference (the "rebuild this STL" flow),
+declare a probe that reads the value, run `measure`, and bake the reported
+number into `defaults` — the probe then keeps watching it on every regen, so a
+swapped import shows up as a probe delta instead of silently stale defaults.
+
+**Cost.** Probes run on every `measure`/`inspect` (including quick checks — the
+agent loop is exactly who reads them), so keep them proportionate: a handful of
+thin-slab booleans is cheap; a dense sweep of whole-part XORs is not. `verify`'s
+per-case re-measures skip probes entirely (no gate reads them). The reference
+part for probes is [`src/parts/import-demo.js`](../src/parts/import-demo.js).
+
 ## Wiring a part into a runnable app
 
 Three tiny glue files per part (copy from the demo). The worker statically imports
@@ -1953,8 +2025,9 @@ previously didn't; that's the fix working as intended, not a regression.
 ### Rule catalog
 
 **Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`,
-`missing-views`, `part-view-unknown` (all errors); `view-unused`,
-`default-view-ambiguous` (warnings).
+`missing-views`, `part-view-unknown`, `invalid-probes` (all errors); `view-unused`,
+`default-view-ambiguous` (warnings). `invalid-probes` fires when a declared
+`probes` block isn't an object of functions (see "Probes" above).
 
 **Parameter schema** — `features-requires-sliders`, `features-requires-on`,
 `control-key-not-in-defaults`, `control-default-not-primitive`,
@@ -2033,10 +2106,12 @@ internals (`hidden: true`). Grouping controls organizes them but does not
 reduce the count — the check recurses into groups — so a group alone doesn't
 bring a section back under budget.
 
-**Kernel API**, found by executing `build()` against a geometry-free probe —
+**Kernel API**, found by executing `build()` — and every declared probe, which
+shares build's `(k, p, d)` contract — against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
-`derive-throws`, `manifold-backend-uses-occt-op`, `build-runaway` (errors);
-`nondeterministic-build` (warning, from diffing two probe runs).
+`probe-throws`, `derive-throws`, `manifold-backend-uses-occt-op`,
+`build-runaway` (errors); `nondeterministic-build` (warning, from diffing two
+probe runs).
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.81.0",
+  "version": "0.82.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/geometry/probe.js

@@ -155,21 +155,34 @@ export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
 }
 
 /**
- * Execute every sub-part's build() against a validating probe.
- * Never throws: a build error becomes an entry in `throws`, a runaway sets `runaway`.
+ * Execute every sub-part's build() — and every declared probe (`part.probes`,
+ * same (k, p, d) contract, see oracle/measure.js) — against a validating probe.
+ * Never throws: a build error becomes an entry in `throws` (probe entries land
+ * in `probeThrows`), a runaway sets `runaway`.
  */
 export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {}) {
   const probe = createValidatingProbe({ maxOps });
   const throws = [];
+  const probeThrows = [];
   let runaway = false;
-  for (const [name, sp] of Object.entries(part?.parts ?? {})) {
-    if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
+  const run = (fn, onThrow) => {
     try {
-      sp.build(probe.kernel, p, d);
+      fn(probe.kernel, p, d);
     } catch (e) {
-      if (e instanceof ProbeRunawayError) { runaway = true; break; }
-      throws.push({ subpart: name, message: e?.message || String(e) });
+      if (e instanceof ProbeRunawayError) { runaway = true; return false; }
+      onThrow(e?.message || String(e));
+    }
+    return true;
+  };
+  for (const [name, sp] of Object.entries(part?.parts ?? {})) {
+    if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
+    if (!run(sp.build, (m) => throws.push({ subpart: name, message: m }))) break;
+  }
+  if (!runaway) {
+    for (const [name, fn] of Object.entries(part?.probes ?? {})) {
+      if (typeof fn !== "function") continue; // invalid-probes already reports this
+      if (!run(fn, (m) => probeThrows.push({ probe: name, message: m }))) break;
     }
   }
-  return { calls: probe.calls, issues: probe.issues, used: probe.used, solidUsed: probe.solidUsed, throws, runaway };
+  return { calls: probe.calls, issues: probe.issues, used: probe.used, solidUsed: probe.solidUsed, throws, probeThrows, runaway };
 }

package/src/framework/lint/rules-build.js

@@ -50,6 +50,16 @@ export const BUILD_RULES = [
         "Fix the error in build(). This was raised with no kernel attached, so it is a fault in the build's own logic (bad arithmetic, a missing param, a null dereference) rather than a geometry failure.",
         `parts.${subpart}.build`)),
   },
+  {
+    // Same class of fault as build-throws, located at the probe. A throwing
+    // probe degrades at runtime to `{ error }` in the measure report rather
+    // than crashing anything — this rule is what makes it loud anyway.
+    id: "probe-throws",
+    run: ({ probe }) => probe().probeThrows.map(({ probe: name, message }) =>
+      err("probe-throws", `probe "${name}" threw during a geometry-free run: ${message}`,
+        "Fix the error in the probe function. This was raised with no kernel attached, so it is a fault in the probe's own logic (bad arithmetic, a missing param, a null dereference) rather than a geometry failure — at runtime it would report `{ error }` instead of a measurement.",
+        `probes.${name}`)),
+  },
   {
     id: "manifold-backend-uses-occt-op",
     run: ({ part, probe }) => {
@@ -75,9 +85,9 @@ export const BUILD_RULES = [
     id: "nondeterministic-build",
     run: ({ probe, probeAgain }) => {
       const a = probe();
-      if (a.runaway || a.throws.length > 0) return []; // an aborted build can't be compared
+      if (a.runaway || a.throws.length > 0 || a.probeThrows.length > 0) return []; // an aborted run can't be compared
       const b = probeAgain();
-      if (b.runaway || b.throws.length > 0) return [];
+      if (b.runaway || b.throws.length > 0 || b.probeThrows.length > 0) return [];
       if (JSON.stringify(a.calls) === JSON.stringify(b.calls)) return [];
       return [warn("nondeterministic-build",
         "two builds with identical parameters produced different kernel calls",

package/src/framework/lint/rules-shape.js

@@ -40,6 +40,25 @@ export const SHAPE_RULES = [
           `parts.${name}.build`));
     },
   },
+  {
+    // `probes` is optional; when present it must be an object of (k, p, d)
+    // functions — same contract as build, but the result lands in the measure
+    // report instead of the scene (see AUTHORING-PARTS.md "Probes").
+    id: "invalid-probes",
+    run: ({ part }) => {
+      if (part?.probes === undefined) return [];
+      if (!isPlainObject(part.probes)) {
+        return [err("invalid-probes", "`probes` must be an object mapping names to functions",
+          "Declare probes as `probes: { name: (k, p, d) => Solid | plain JSON }` — each is measured into the report by `partforge measure` and the inspect job.",
+          "probes")];
+      }
+      return Object.entries(part.probes)
+        .filter(([, fn]) => typeof fn !== "function")
+        .map(([name]) => err("invalid-probes", `probe "${name}" is not a function`,
+          "Every entry in `probes` must be a `(k, p, d)` function returning a Solid (measured into facts) or plain JSON (reported verbatim).",
+          `probes.${name}`));
+    },
+  },
   {
     id: "missing-views",
     run: ({ part }) => (isPlainObject(part?.views) && Object.keys(part.views).length > 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/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: {