partforge 0.71.0 → 0.72.0

package/docs/AUTHORING-PARTS.md

@@ -1964,9 +1964,14 @@ carries:
 Subpart facts include `minWall` (number or `null` — null exactly when no reading
 exists, e.g. the OCCT backend or min-wall measurement turned off, matching
 `minWallAt`'s null) and `minWallAt` (`[x,y,z]` or `null`). Min wall casts one ray
-per triangle, which is unbounded work on a dense mesh, so past 50,000 triangles
+per triangle, which is unbounded work on a dense mesh, so past a sample budget
 it casts from a spread, deterministic subset instead — `minWallSampled` (boolean)
 and `minWallSamples` (`{ sampled, total }` or `null`) say whether that happened.
+**The budget depends on whether the reading is checked against anything**: a part
+that declares a min-wall gate — a `verify.process` profile, or an `expect`
+mentioning `minWall` — gets 50,000, because a gate's verdict rides on it; a part
+that declares neither gets 5,000, because there the number is a diagnostic for a
+reader rather than an assertion. Declaring the gate is what buys the resolution.
 `sampled` is how many triangles the walk *selected*, not how many rays were
 cast: a degenerate (zero-area) triangle has no normal to cast along and is
 skipped. A sampled reading is an **upper bound**: it can miss a thin spot, never
@@ -1980,6 +1985,24 @@ Overlap entries are
 `{ a, b, volume, location }`. Pair-distance facts are `gaps` (every sub-part
 pair: `{ a, b, distance, at }`, distance 0 = touching or overlapping) and
 `nearMisses` (the pairs with an unintended-looking gap under 0.5 mm).
+`measuredGaps` is the companion to `measuredMinWall` for that pass, and `gaps` is
+**absent** rather than empty when it did not run — an empty table means "measured,
+and these pairs have no distance", which a declared `clearance` gate fails on.
+
+### Quick checks
+
+An editor may ask for a **quick** check, which skips both ray-casting passes — min
+wall and pair distances — and keeps everything derived from the build itself:
+triangles, bbox, volume, genus, watertight, the assembly overlap check, and lint.
+On a 460k-triangle assembly that is roughly 6.8 s down to 0.9 s.
+
+Gates still run on a quick check wherever the facts allow it, so a violated `bbox`
+or `holes` expectation still fails. What a quick check will **never** do is return a
+pass: any gate it could not evaluate is listed in `verify.unevaluated`, and one such
+gate makes `verify.ok` **`null`** rather than `true`. So `ok` is tri-state — `false`
+(something failed), `null` (nothing failed, but something went unchecked), `true`
+(everything declared was checked and passed) — and code that treats a truthy `ok` as
+"passed" stays correct without changing. Run a full check before trusting a part.
 
 A **thrown** error (bad part module, kernel failure) with `--json` prints pure
 JSON to stdout and exits 1:

package/package.json

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

@@ -241,10 +241,11 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // an unparameterized inspect that case IS this measurement. Seeding it in
       // (see verify.js's seeding block for the min-wall superset rule that makes
       // the reuse sound) stops the oracle from rebuilding the same geometry and
-      // re-casting the same min-wall rays a second time. Measuring `{ minWall:
-      // true }` here is what makes the seed usable by any verify run, min-wall
-      // gated or not — the result says so itself (`measuredMinWall`), so this
-      // call and the seed cannot drift apart.
+      // re-casting the same min-wall rays a second time. On a full lap the seed is
+      // usable by any verify run, min-wall gated or not, because the pass ran — and
+      // the result says so ITSELF (`measuredMinWall`/`measuredGaps`), never a claim
+      // by this caller, so the two cannot drift apart. On a quick lap the passes did
+      // not run, the stamps say false, and verify reports what it could not check.
       //
       // The view is built HERE rather than inside measure, and handed down through
       // `opts.built`, because optional match scoring needs the same meshes: one build
@@ -259,15 +260,31 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // measure built internally and its own signature default hid this. Found by a
       // live browser check, not by tests: this suite passes explicit views, and the
       // cloud's unit tests fake the worker.
+      //
+      // `checks: "quick"` is the agent's fast lap. Min wall and pair distances are
+      // the oracle's two ray-casting passes and, profiled on a 460k-triangle
+      // assembly, 79% of its cost — and they SHARE the BVH those rays need, so
+      // skipping one leaves the index build standing and saves about half of what
+      // skipping both does. Everything else is derived from the build this job
+      // already paid for and stays: triangles, bbox, volume, genus, watertight,
+      // and the assembly overlap check. verify still runs — the gates that read
+      // those facts are free — and reports what it could not evaluate rather than
+      // passing it, which is why `quick` can be honoured on a gated part instead
+      // of refused. Anything other than the literal "quick" is the full lap: an
+      // unrecognized value must never quietly buy less checking than the caller
+      // asked for.
+      const quick = msg.checks === "quick";
       const view = msg.view ?? Object.keys(part.views)[0];
       const built = buildView(kernel, part, view, msg.params ?? {});
-      const measured = measure(kernel, part, view, msg.params ?? {}, { minWall: true, built });
+      const measured = measure(kernel, part, view, msg.params ?? {},
+        { minWall: !quick, gaps: !quick, built });
       const report = {
         measure: measured,
         verify: verify(kernel, part, {
           // The defaulted view, not msg.view: the seed below was measured on it, and
           // verify's seed reuse is only sound when both name the same view.
           view,
+          quick,
           seed: { params: msg.params ?? {}, result: measured },
         }),
       };

package/src/framework/oracle/gates.js

@@ -0,0 +1,50 @@
+// Which declared gates a part actually has — the questions the oracle asks before
+// deciding how hard to work. Kept out of verify.js so measure() can ask the same
+// question without importing verify (which imports measure), and so there is ONE
+// definition of "does this part gate on min wall": measure sizes its sample budget
+// by it and verify decides whether to measure it at all. Two derivations that drift
+// would put a coarse reading behind a real gate, which is exactly the trap verify's
+// seeding block guards against.
+//
+// Every function here is TOTAL. A part whose profile name is unknown, or whose
+// `expect` function throws, is reported as GATED — the conservative direction, since
+// that is the full-resolution behaviour every part had before budgets existed. The
+// real error surfaces from verify, which is where a reader can act on it.
+import { resolveProfile } from "./dfm-profiles.js";
+import { expandCases } from "./cases.js";
+import { resolveParams } from "../part-model.js";
+
+// `expect` may be a function of a case's resolved params, so the answer is a property
+// of the EXPANDED cases, not of the raw spec — which means answering it costs a call
+// to the PART'S OWN code, once per case. Both callers here are on hot paths (verify
+// expands for its case loop; measure asks the gate question on every call, and verify
+// calls measure once per case), so an unmemoized expansion would invoke a part's
+// `expect` O(cases²) times per report. Memoized by part identity, and re-derived if
+// the spec object behind that identity was swapped — the realistic mutation, and the
+// one a bare WeakMap would serve staleness for.
+const expansions = new WeakMap();
+
+export function expandExpectations(part) {
+  const spec = part?.verify?.expect ?? {};
+  const hit = expansions.get(part);
+  if (hit && hit.spec === spec) return hit.expanded;
+  const expanded = typeof spec !== "function"
+    ? expandCases(part).map((c) => ({ ...c, expect: spec }))
+    : expandCases(part).map((c) => {
+      const { p, d } = resolveParams(part, c.params);
+      return { ...c, expect: spec(p, d) ?? {} };
+    });
+  if (part && typeof part === "object") expansions.set(part, { spec, expanded });
+  return expanded;
+}
+
+export function partGatesMinWall(part, { process, expanded } = {}) {
+  try {
+    const spec = process ?? part?.verify?.process;
+    if (spec && resolveProfile(spec)?.minWall != null) return true;
+    return (expanded ?? expandExpectations(part)).some(({ expect }) =>
+      Object.values(expect ?? {}).some((o) => o && typeof o === "object" && "minWall" in o));
+  } catch {
+    return true; // unresolvable → measure it properly and let verify report the error
+  }
+}

package/src/framework/oracle/measure.js

@@ -3,7 +3,8 @@ import { cachedBVH } from "./bvh.js";
 import { assemblyOverlaps } from "../assembly.js";
 import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
 import { bounds, meshArea, meshCentroid } from "./mesh.js";
-import { minWall } from "./min-wall.js";
+import { minWall, DIAGNOSTIC_SAMPLES } from "./min-wall.js";
+import { partGatesMinWall } from "./gates.js";
 
 const size = ({ min, max }) => [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
 const unionBounds = (list) => list.reduce(
@@ -40,13 +41,20 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // the cache just fills it earlier. min-wall indexes exactly one mesh, so it is
   // handed the resolved BVH rather than the Map.
   const bvhCache = new Map();
+  // Sample budget for the min-wall pass. A part that declares a min-wall gate (a
+  // process profile or an `expect` mentioning it) gets the full resolution, because
+  // a gate's verdict rides on the reading. Everything else gets the diagnostic
+  // budget: min wall is the single most expensive thing the oracle does — one
+  // inward ray per sampled triangle plus the BVH those rays need — and on an
+  // ungated part it buys a fact nobody checks, at full price, on every agent edit.
+  const minWallSamples = partGatesMinWall(part) ? undefined : DIAGNOSTIC_SAMPLES;
   const subBounds = [];
   const subparts = built.map(({ name, solid, mesh }) => {
     const b = bounds(mesh.positions);
     subBounds.push(b);
     // Resolved lazily and only when asked for: without min-wall, a single-sub-part
     // view (no meshGaps) must still build no index at all.
-    const mw = opts.minWall ? minWall(mesh, { bvh: cachedBVH(mesh, bvhCache) }) : null;
+    const mw = opts.minWall ? minWall(mesh, { bvh: cachedBVH(mesh, bvhCache), maxSamples: minWallSamples }) : null;
     const vol = solid.volume();
     // Deviation-from-reference: only for a sub-part that declares `reference:
     // "<import name>"` (Task 12 — the gate that holds a parametric rebuild to
@@ -96,7 +104,13 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // so this reads on OCCT too. nearMisses = the issue-#29 signal: pairs that
   // *almost* touch; overlapping pairs are excluded by name (a fully-contained
   // sub-part has surface distance > 0 but is the overlap gate's business).
-  const gaps = built.length > 1 ? meshGaps(built, { bvhCache }) : [];
+  // `opts.gaps: false` is the quick lap's second half (see jobs.js): pair distances
+  // are the other ray-casting pass, and they and min-wall share the BVH, so skipping
+  // only one leaves the index build standing. The result is `undefined`, NEVER `[]`:
+  // pairGapChecks reads an empty table as "measured, and this pair has no distance"
+  // and fails a declared gate on it, while an absent table reads as no reading.
+  const measuredGaps = opts.gaps !== false;
+  const gaps = measuredGaps ? (built.length > 1 ? meshGaps(built, { bvhCache }) : []) : undefined;
 
   // Rebuilds with the same kernel and cleans up at its end — every solid fact
   // above is already read, so this is safe.
@@ -106,7 +120,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
 
   const overlapping = new Set(overlaps.map((o) => pairKey(o.a, o.b)));
   const gapThreshold = opts.gapThreshold ?? GAP_THRESHOLD;
-  const nearMisses = gaps.filter(
+  const nearMisses = (gaps ?? []).filter(
     (g) => g.distance > CONTACT_EPS && g.distance < gapThreshold && !overlapping.has(pairKey(g.a, g.b)),
   );
 
@@ -133,6 +147,9 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     // nothing measured it, which reads identically to "no reading available";
     // verify's seeding rule turns on exactly this distinction (see verify.js).
     measuredMinWall: !!opts.minWall,
+    // Companion stamp to measuredMinWall, and read the same way: whether the pass
+    // ran, said by the pass itself rather than claimed by whoever holds the result.
+    measuredGaps,
     subparts,
     aggregate,
     overlaps,

package/src/framework/oracle/min-wall.js

@@ -33,6 +33,23 @@ import { buildBVH, readTriangleInto } from "./bvh.js";
 // are the only ones that engage it. Override per call with `{ maxSamples }`.
 const MAX_SAMPLES = 50_000;
 
+// The budget for a min-wall reading NOTHING GATES ON — a fact the report carries so
+// the model can notice a thin feature, rather than a number a declared minimum is
+// checked against. A tenth the rays, and the reading is stamped `sampled` either way,
+// so no consumer can mistake it for exact. measure() picks between the two by asking
+// gates.js whether the part declares a min-wall gate; a part that does gets
+// MAX_SAMPLES, unchanged.
+//
+// The win is real but bounded, and the bound is worth knowing before tuning this
+// number: the RAYS get ten times cheaper, the BVH they cast into does not, and it is
+// roughly half the pass. Measured on src/parts/screw.js (210k triangles, same code
+// path, gated vs not): measure() 837 ms → 458 ms, reporting the identical 0.008 mm.
+// Dropping the index too means not measuring min wall at all, which is the quick
+// lap's business (see jobs.js), not this constant's.
+const DIAGNOSTIC_SAMPLES = 5_000;
+
+export { MAX_SAMPLES, DIAGNOSTIC_SAMPLES };
+
 const gcd = (a, b) => { while (b) { const t = a % b; a = b; b = t; } return a; };
 
 // Stride for the sampling walk: near n/φ and coprime to n, so stepping by it visits

package/src/framework/oracle/verify.js

@@ -2,9 +2,8 @@ import { parseAssertion, evaluateAssertion } from "./assert-dsl.js";
 import { measure as defaultMeasure } from "./measure.js";
 import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile } from "./dfm-profiles.js";
-import { expandCases } from "./cases.js";
+import { expandExpectations, partGatesMinWall } from "./gates.js";
 import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../param-deps.js";
-import { resolveParams } from "../part-model.js";
 import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
 
 // Re-exported for backwards compatibility: the registries moved to framework/ so
@@ -52,11 +51,19 @@ function pairGapChecks(facts, { contacts, clearance }, subPartNames) {
   // No gap table at all = legacy facts → skip. A table that MERELY LACKS the pair
   // = the sub-part built empty (meshGaps skips empty meshes) → a declared gate
   // must fail loudly, not skip, or verify.ok would vouch for an unverified pair.
+  // `measuredGaps === false` says the pass was deliberately skipped (a quick lap);
+  // an absent stamp is a legacy result, whose skip stays exactly as untagged as it
+  // has always been rather than retroactively withholding verdicts.
+  const gapsSkipped = facts.measuredGaps === false;
   const noReading = (base) => (facts.gaps
     ? { ...base, actual: null, status: "fail", pass: false,
         message: "no measured distance for the pair",
         hint: "one sub-part produced no mesh (an empty solid?) — fix the build before trusting this gate" }
-    : { ...base, actual: null, status: "skip", pass: null, message: "unavailable" });
+    : { ...base, actual: null, status: "skip", pass: null,
+        ...(gapsSkipped
+          ? { unevaluated: true, message: "not measured (quick check)",
+              hint: "re-run this check without `quick` to measure pair distances" }
+          : { message: "unavailable" }) });
 
   if (contacts != null && !Array.isArray(contacts)) {
     throw new Error(`contacts: must be an array of ["a", "b"] pairs, got ${JSON.stringify(contacts)}`);
@@ -157,12 +164,25 @@ export function evaluateCase(facts, { profile, expect, subPartNames }) {
   for (const [metric, expr] of Object.entries(viewExp)) checks.push(check("view", null, metric, expr, VIEW_METRICS, facts));
   checks.push(...pairGapChecks(facts, { contacts, clearance }, subPartNames));
 
+  // Same rule as gapsSkipped above, one metric over: a min-wall gate with no reading
+  // is a warn ("min wall unavailable"), which does not move `ok` — right when the
+  // rays were cast and all missed, wrong when they were never cast. The stamp is
+  // what tells those apart, and it is measure()'s own, never a caller's claim.
+  const minWallSkipped = facts.measuredMinWall === false;
   for (const s of facts.subparts) {
     const merged = {
       ...(profile?.minWall != null ? { minWall: `>=${profile.minWall}` } : {}),
       ...(expect?.[s.name] ?? {}),
     };
-    for (const [metric, expr] of Object.entries(merged)) checks.push(check("subpart", s.name, metric, expr, SUBPART_METRICS, s));
+    for (const [metric, expr] of Object.entries(merged)) {
+      const c = check("subpart", s.name, metric, expr, SUBPART_METRICS, s);
+      if (minWallSkipped && metric === "minWall" && c.actual == null) {
+        checks.push({ ...c, unevaluated: true, message: "not measured (quick check)",
+          hint: "re-run this check without `quick` to measure min wall" });
+        continue;
+      }
+      checks.push(c);
+    }
   }
   return checks;
 }
@@ -170,26 +190,23 @@ export function evaluateCase(facts, { profile, expect, subPartNames }) {
 // `seed` lets a caller that has ALREADY measured this part hand the result in so
 // verify does not recompute it — see the seeding block below for the shape and
 // the one correctness rule that governs it.
-export function verify(kernel, part, { process, view, measureFn = defaultMeasure, seed } = {}) {
+// `quick` is the fast lap (see jobs.js): evaluate everything the seed already
+// supports and MEASURE NOTHING. What that leaves unchecked is reported as
+// `unevaluated` rather than quietly downgraded, and one unevaluated gate withholds
+// `ok` — a fast lap yields facts, never a verdict.
+export function verify(kernel, part, { process, view, measureFn = defaultMeasure, seed, quick = false } = {}) {
   view = view ?? Object.keys(part.views)[0];
   const profileSpec = process ?? part.verify?.process;
   const profile = profileSpec ? resolveProfile(profileSpec) : null;
-  const expectSpec = part.verify?.expect ?? {};
 
-  const cases = expandCases(part);
   // `expect` can be a pure function of the case's resolved params — (p, d) →
   // expect object — so topology that legitimately changes with a preset (an
   // optional drain or bore flipping the genus) can be pinned per case instead
-  // of one static number that some presets must violate.
-  const resolveExpect = (params) => {
-    if (typeof expectSpec !== "function") return expectSpec;
-    const { p, d } = resolveParams(part, params);
-    return expectSpec(p, d) ?? {};
-  };
-  const expanded = cases.map((c) => ({ ...c, expect: resolveExpect(c.params) }));
-  const expectMentionsMinWall = expanded.some(({ expect }) =>
-    Object.values(expect).some((o) => o && typeof o === "object" && "minWall" in o));
-  const needMinWall = profile?.minWall != null || expectMentionsMinWall;
+  // of one static number that some presets must violate. The expansion lives in
+  // gates.js because measure() needs the same answer (it sizes the min-wall sample
+  // budget by it) and must not derive it separately — see there.
+  const expanded = expandExpectations(part);
+  const needMinWall = partGatesMinWall(part, { process, expanded });
   const readKeys = subPartReadKeys(part, view, part.defaults);
   const signature = (params) =>
     readKeys === RELEVANT_ALL
@@ -237,24 +254,48 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   //
   // Non-default measure options (a custom `gapThreshold`) are the caller's
   // responsibility: seed only a measurement taken the way verify would take it.
-  if (seed?.result && (seed.result.measuredMinWall || !needMinWall) && seed.result.view === view) {
+  // Under `quick` the superset rule is not waived so much as satisfied differently:
+  // a min-wall-less seed is reused, and the min-wall gate it cannot answer becomes
+  // `unevaluated` instead of being re-measured. The rule exists to stop a coarse
+  // reading standing in for a gate's verdict, and a withheld verdict does that too.
+  if (seed?.result && (quick || seed.result.measuredMinWall || !needMinWall) && seed.result.view === view) {
     memo.set(signature({ ...part.defaults, ...(seed.params ?? {}) }), seed.result);
   }
 
   const measureCase = (params) => {
     const key = signature(params);
-    if (!memo.has(key)) memo.set(key, measureFn(kernel, part, view, params, { minWall: needMinWall }));
+    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 }));
     return memo.get(key);
   };
 
   const subPartNames = Object.keys(part.parts);
-  const caseResults = expanded.map(({ name, params, expect }) => ({ name, params, checks: evaluateCase(measureCase(params), { profile, expect, subPartNames }) }));
+  // An unmeasured case gets ONE check standing for the whole case rather than a
+  // silent absence: "this preset was not checked" has to be visible in the same
+  // list every other verdict lives in, or a reader counting passes sees a shorter
+  // list and no reason.
+  const notMeasured = (name) => [{
+    scope: "case", subpart: null, metric: "measured", kind: "gate", expr: "measured",
+    actual: null, status: "skip", pass: null, unevaluated: true,
+    message: "not measured (quick check)",
+    hint: "re-run this check without `quick` to evaluate this case",
+  }];
+  const caseResults = expanded.map(({ name, params, expect }) => {
+    const facts = measureCase(params);
+    return { name, params, checks: facts ? evaluateCase(facts, { profile, expect, subPartNames }) : notMeasured(name) };
+  });
   const all = caseResults.flatMap((c) => c.checks.map((ch) => ({ case: c.name, ...ch })));
+  const failures = all.filter((c) => c.status === "fail");
+  const unevaluated = all.filter((c) => c.unevaluated);
   return {
-    ok: !all.some((c) => c.status === "fail"),
+    // Tri-state, and the order matters: a real failure is still a failure even on a
+    // lap that skipped other gates, so `false` outranks the withheld `null`.
+    ok: failures.length ? false : unevaluated.length ? null : true,
     view,
     cases: caseResults,
-    failures: all.filter((c) => c.status === "fail"),
+    failures,
     warnings: all.filter((c) => c.status === "warn"),
+    unevaluated,
   };
 }