partforge 0.109.1 → 0.111.0

package/bin/cli.js

@@ -222,11 +222,17 @@ const commands = {
       };
       if (flags.out) writeOut();
       let vok = true;
-      if ((part.verify || flags.process) && !flags["no-verify"]) {
+      // Always, not only when the part has a `verify` block: a part with none is
+      // the most vacuous case of all, and the "nothing verified" verdict below
+      // exists to say so rather than let a clean exit read as verified.
+      if (!flags["no-verify"]) {
         const v = verify(kernel, part, { process: flags.process, view });
         if (!flags.json) printVerify(v);
         report.verify = v;
-        vok = v.ok;
+        // Tri-state: `null` is a withheld verdict (nothing declared, or a check
+        // that could not run), not a failure — the notice prints; the exit code
+        // reports only what actually failed.
+        vok = v.ok !== false;
         if (flags.out) writeOut();
       }
       if (flags.out) console.log(`\nwrote ${flags.out}`);
@@ -542,8 +548,21 @@ function printVerify(v) {
       }
     }
   }
+  // Part-level notices live only in `warnings` (they are about the part, not a
+  // case), so they print here, after the cases.
+  for (const n of v.warnings.filter((c) => c.scope === "part")) {
+    console.log(`  part`);
+    console.log(`    ⚠ ${n.metric}  (${n.message})`);
+    if (n.hint) console.log(`        hint: ${n.hint}`);
+  }
   const f = v.failures.length, w = v.warnings.length;
-  console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
+  // One switch on the tri-state verdict, so the line and `ok` cannot disagree.
+  const verdict = v.ok === false ? `${f} gate failure(s)`
+    : v.ok === true ? "all gates passed"
+    : v.unevaluated?.length ? `verdict withheld (${v.unevaluated.length} check(s) not evaluated)`
+    : v.declared ? "nothing verified (every declared check skipped)"
+    : "nothing verified (no expectations declared)";
+  console.log(`  result: ${verdict}${w ? `, ${w} warning(s)` : ""}`);
 }
 
 function printLint(r) {

package/docs/AUTHORING-PARTS.md

@@ -2860,6 +2860,7 @@ probe runs).
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
+`verify-unknown-orientation`,
 `verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise
 `contacts` / `clearance` keys, which are not scalar view metrics; they are
 validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
@@ -2993,11 +2994,13 @@ carries:
 - `hint` — one self-contained corrective sentence (always present),
 - `pattern` — a stable [ERROR-PATTERNS.md](ERROR-PATTERNS.md) entry ID when one
   applies (follow it with `ERROR-PATTERNS.md#<id>`),
-- `note` — an optional caveat about *how* the value was measured, attached
-  whatever the verdict. Today only `minWall` sets one, when the reading came
-  from a sample rather than every triangle (see below),
+- `note` — an optional caveat about *how* the value was measured, or a companion
+  reading, attached whatever the verdict. `minWall` sets one when the reading came
+  from a sample rather than every triangle (see below); `overhangArea` sets one
+  naming the steepest unsupported face's angle,
 - `location` — `[x, y, z]` in mm where the metric has one: `minWall` (thinnest
-  sample point) and `overlaps` (the center of the first offending intersection's
+  sample point), `overhangArea` (the largest unsupported face's centroid) and
+  `overlaps` (the center of the first offending intersection's
   *bounding box* — a nearby indicator, not an exact point: when a pair overlaps in
   more than one place the bbox center can fall in the empty space between regions)
   and the pair checks `contact` / `clearance` / `nearMiss` (the midpoint between
@@ -3010,6 +3013,11 @@ exists, e.g. the OCCT backend or min-wall measurement turned off, matching
 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.
+A part that opted into the overhang check (see the `verify` block) also carries
+`overhangArea` (mm² of unsupported downward-facing surface, `null` when not
+checked or on an `exportable: false` sub-part), `overhangAngle` (the steepest such
+face, degrees from vertical) and `overhangAt` (that face's centroid); the report's
+`measuredOverhang` stamps the angle the pass ran against, or `null`.
 **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
@@ -3099,7 +3107,9 @@ A part can declare how it should be checked, co-located with its schema, so
 ```js
 verify: {
   process: "fdm-pla",            // a DFM profile: fdm-pla | fdm-petg | resin, or an
-                                  // inline { bed:[x,y,z], minWall, clearance } object
+                                  // inline { bed:[x,y,z], minWall, clearance, overhang } object
+  orientation: "print",          // optional; ONLY with this is overhang checked — it says the
+                                  // part is laid out for its bed (Z up, bed at the lowest Z)
   cases: ["defaults", "M3"],     // optional; default = defaults + every preset
   expect: {                      // design intent, by sub-part name (+ "_view")
     spacer: { holes: 1, bbox: "<=[60,60,60]", volume: "0.4..0.6cm3" },
@@ -3110,10 +3120,30 @@ verify: {
 }
 ```
 
-**What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`)
-and a **min-wall** warning. **What `expect` gives you:** per-sub-part assertions on the
-facts `measure` already reports — `holes` (through-bores / genus), `volume`,
-`surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`, `boundsMin` / `boundsMax`
+**What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`),
+a **min-wall** warning, and — only for a part that also declares
+`orientation: "print"` — an **overhang** warning: `overhangArea` is the mm² of
+downward-facing surface steeper than the profile's `overhang` angle (45° from vertical
+on the FDM profiles; resin carries none, since it prints on supports), measured per
+sub-part with the bed at that sub-part's own lowest Z, and warned past 1 mm². The
+opt-in is deliberate: a profile says what a process can print, the orientation key
+says this part is laid out for it, and a part still being shaped, or one bound for a
+different process, should not be nagged about its underside. Writing your own
+`overhangArea` expectation is the other way in — it arms the measurement by itself,
+against the profile's angle or 45° when the profile names none, so a declared
+expectation is never answered "unavailable". Two bands next to the bed are never
+counted: the footprint itself, and faces whose centroid sits within 1 mm of the bed
+(the lower curl of a bottom-edge fillet or chamfer, which prints fine). A bridge (a
+flat underside spanning two supports) and the ceiling of a horizontal bore are
+reported as overhangs — the mesh alone cannot tell a bridge from a ceiling — which
+is why this is a warning and never a gate. Two more limits, stated: it is judged in
+the DISPLAY pose, so a sub-part whose `place` differs for export (a lid that prints
+flat beside its base) is measured as displayed, and `exportable: false` sub-parts
+are skipped. Switch it off under an FDM profile with an inline
+`{ base: "fdm-pla", overhang: null }`. **What `expect` gives you:** per-sub-part
+assertions on the facts `measure` already reports — `holes` (through-bores / genus),
+`volume`, `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`,
+`overhangArea`, `boundsMin` / `boundsMax`
 (the axis-aligned `{min,max}` corner positions — where the geometry sits, vs
 `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
 centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
@@ -3150,9 +3180,25 @@ verify: { expect: {
 
 **Gates vs. warnings:** exact facts are **gates** (a failure sets a non-zero exit code);
 `minWall` is computed (a ray/shot wall-thickness measurement) and reported as a
-**warning** — it flags walls below the profile's minimum but never fails the build.
-`holes`/`watertight` are Manifold-only, so those assertions **skip** on OCCT parts
-rather than fail.
+**warning** — it flags walls below the profile's minimum but never fails the build —
+and so is `overhangArea` (see above). `holes`/`watertight` are Manifold-only, so those
+assertions **skip** on OCCT parts rather than fail.
+
+**A verify block that declares nothing verifies nothing.** `verify.ok` is tri-state:
+`true` when every declared check passed, `false` on any gate failure, and `null` when
+no verdict can be given — a quick lap that could not measure a gate, or a part with
+**no declared expectations** at all (no `verify` block, an empty `expect`, no profile).
+That last case used to read as `ok: true` with zero checks, which every reader took as
+"verified". It now comes back `ok: null` with `evaluated: 0` and a `no expectations
+declared` warning whose hint says what to pin; the CLI runs verify on every part, block
+or no block, prints *nothing verified* and exits 0 (a withheld verdict is not a
+failure). The same `null` covers a part that declared checks none of which could be
+answered — every one SKIPPED (a `ref*` metric on a sub-part with no `reference`,
+`holes` on the OCCT backend, a pair on a disabled sub-part) — with a `no expectation
+could be evaluated` warning instead; `declared` and `evaluated` on the report tell
+the two apart. A single answerable expectation — or a process profile, which brings
+the bed-fit gate — is enough for a verdict. Treat `null` as "not verified", never as
+a pass.
 
 **Per-case expectations.** Checks run across defaults **and every preset**, so a
 static `expect` breaks the moment a preset legitimately changes an asserted fact —
@@ -3456,6 +3502,16 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
   For the case that causes this most often — a tapped hole — reach for
   `k.tappedBore`, which owns the bore and the thread together and cannot land them
   on the same face.
+- **A boolean that comes back geometrically impossible is a build error, not a
+  part.** Every `cut`/`cutAll`/`intersect`/`union` result is judged by volume against
+  its operands on both backends: a union smaller than an input, a cut that grew, a
+  negative volume, or the exact kernel's silent "returned one operand instead of the
+  union" all throw `boolean result invalid: …` with the fix menu above instead of
+  shipping a wrong preview or STEP file
+  ([boolean-dropped-operand](ERROR-PATTERNS.md#boolean-dropped-operand),
+  [boolean-impossible-result](ERROR-PATTERNS.md#boolean-impossible-result)). A
+  legitimately degenerate design — a hole wider than its plate — is not impossible and
+  builds as before; `verify` is what catches that.
 
 ---
 

package/docs/ERROR-PATTERNS.md

@@ -68,6 +68,18 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Detected:** The exact kernel now refuses the common cylindrical form of this contact up front — several swept faces lying exactly on one cylindrical face fail the boolean immediately with `<op> between exactly-touching surfaces: … (radius <r>)` and the fix menu below, instead of grinding. Scope, honestly: the guard needs the contact to tile the cylinder (a thread does, ~6+ hugging faces per turn; a sub-turn thread can slip under it — that is the old grinding behavior, not a new one), it covers swept-face-on-cylinder contact only (two swept faces mated exactly, or contact with non-cylindrical faces, can still hang), and a hand-sunk thread whose chord-bands happen to hug the wall can be refused even though it would have built — `k.tappedBore` resolves that refusal too, since its internal composition is exempt. The rule below applies everywhere regardless.
 - **Fix:** For a tapped hole — far and away the most common cause — use `k.tappedBore({ d, pitch, turns, depth })`, which returns the bore and its thread as one tool and cannot put them on the same face. Otherwise: give the surfaces a deliberate clearance instead of letting them land on the same number. Derive one from the other with an explicit gap — `const boreD = threadRootD - 2 * boreClearance;` with `boreClearance` around 0.05-0.1 mm — rather than reusing the same expression for both. The gap is far below a printable layer, so the fit is unchanged. The same rule covers a cut that ends exactly flush with a face (overshoot it by a few tenths, as the surrounding examples do with `+ 0.4` / `- 0.2`) and two tools that abut exactly end-to-end.
 
+## boolean-dropped-operand
+
+- **Symptom:** `dropped an operand` — the full message reads `boolean result invalid: <op> dropped an operand — the result's volume (<v>) equals operand <i>'s exactly, but operand <j> (<vj>) has <x> mm³ of material outside it that the union lost.`, thrown from a `union` (or from `cutAll`, labelled `cutAll (tools)`, whose tools are fused before the cut; or labelled `k.tappedBore's bore ∪ thread union`, in which case the author wrote no union — the framework's own composition failed, report it). Before partforge 0.110 the same construction shipped silently: a STEP export that is a plain cylinder, a preview missing the thread, a `measure` volume equal to the core's alone ([screw-thread-vanishes-on-occt](#screw-thread-vanishes-on-occt)).
+- **Cause:** The exact kernel's fuse failed without reporting it and returned one operand instead of the union — a thin or near-self-touching swept operand (a sub-pitch thread ridge riding a core, a thread tool whose root sits on the bore wall) is the case seen on real parts. The gate (`boolean-gate.js`) noticed because the result's volume is one operand's to float precision while the other operand has material outside it, which no union can lose.
+- **Fix:** Give the operands genuine overlap rather than a tangent contact (sink one 0.05 mm or more into the other — derive one radius from the other with an explicit offset, never the same expression twice). Build a thread in the **periodic** `screwSweep` form, which needs no union at all, or a tapped hole with `k.tappedBore`, which owns the bore and thread together. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Helical & threaded features". Do not "fix" it by catching the error — the geometry it refused is wrong, and the previous good preview stays on screen while you correct the construction.
+
+## boolean-impossible-result
+
+- **Symptom:** `produced an impossible result` — the full message reads `boolean result invalid: <op> produced an impossible result — …`, thrown from `union`, `cut`, `cutAll` or `intersect`, naming one of: `a negative volume`, `a union smaller than its largest operand`, `a cut larger than its body`, `a cut that emptied its body although the tools cover at most <x> mm³ of its <y> mm³`, `an intersection larger than its smallest operand`.
+- **Cause:** The kernel's boolean returned geometry that violates the one property no boolean may (a union contains its inputs, a cut only removes, an intersection lies inside each input, a solid has non-negative volume) without reporting an error. On the exact kernel this follows a tangent or self-touching contact the coincidence guard could not recognise up front ([boolean-coincident-faces-hang](#boolean-coincident-faces-hang) covers the form it does refuse); on the mesh kernel it should never happen and would be a kernel bug worth reporting. The gate carries 1% slack on the largest operand, so volume-integration noise cannot trip it.
+- **Fix:** The same menu as the coincidence guard's — genuine overlap or genuine clearance (0.05 mm or more) instead of exact contact, cut tools overcut past the faces they pierce, threads in the periodic `screwSweep` form or via `k.tappedBore`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Gotchas". A refusal is a throw, not a warning, on purpose: the alternative is the silently wrong part these rules exist to stop, and a live preview keeps its last good mesh on screen across a failed rebuild.
+
 ## chamfer-rescue-bisection
 
 - **Symptom:** `partforge: chamfer` warning saying the distance `over-ran the geometry — reduced to` a smaller one (or `has no valid distance`), with an attempt count and elapsed seconds, alongside slow builds.
@@ -574,6 +586,13 @@ Variant literal for a curve-adjacent corner: `filletProfile: corner <i> at (<x>,
 - **Cause:** the thread was built as a thin sub-pitch helical sliver and unioned
   onto a core. OCCT's boolean fails on a near-self-touching swept operand and
   silently returns the other operand — or nothing — rather than throwing.
+- **Detected:** since partforge 0.110 the boolean result gate refuses both
+  outcomes instead of shipping them — `boolean result invalid: union dropped an
+  operand` when the core comes back alone
+  ([boolean-dropped-operand](#boolean-dropped-operand)), `… produced an
+  impossible result` when nothing does
+  ([boolean-impossible-result](#boolean-impossible-result)). The fix below is
+  unchanged; the symptom is now a build error naming it.
 - **Fix:** build the thread in the **periodic** form instead — a profile spanning
   exactly one `pitch` with equal first and last radius encloses the axis, so
   `k.screwSweep` yields the whole threaded body with no boolean at all. See

package/docs/KERNEL-CONTRACT.md

@@ -487,6 +487,44 @@ exactly the old behavior. The same array also carries *job-level* notices that
 belong to no single sub-part — currently a font source refused by its control's
 `allow` list — as entries with `part: null`.
 
+**Boolean result gate** (both backends, partforge 0.110, `boolean-gate.js`): every
+author-facing boolean — `cut`, `cutAll`, `intersect`, `union` in both forms, and the
+B-rep backend's internal tool fuse inside `cutAll` — is judged AFTER it runs, by
+volume against its operands, and a result that violates the one property no boolean
+may violate **throws** (`code: "BOOLEAN_RESULT_INVALID"`, message leading
+`boolean result invalid:`): a union smaller than any operand, a cut larger than its
+body, an intersection larger than its smallest operand, a negative volume. Each
+inequality carries 1% of the operand it is compared AGAINST as slack (floored at
+1e-6 mm³) — never of the largest operand, which would switch the cut and intersect
+rules off whenever the tool is the big one — so volume-integration noise can never
+fire them. Two signatures the inequalities cannot decide are confirmed lazily, on that
+signature only: first a free bounding-box enclosure test, then ONE extra intersect. A
+union whose volume equals one operand's to float precision is refused when the other
+operand has material outside it, judged against that operand's OWN size (the
+documented silent failure — a thin thread ridge dropped, the core returned alone);
+a cut that came back empty is refused when its tools cannot have covered the body. A
+probe that fails is inconclusive, never a refusal, and so is a negative OPERAND (broken
+input, not this boolean's doing). On the B-rep class the probe intersect runs through
+the coincidence guard like every other boolean — it runs on exactly the pair that just
+misbehaved — and a guard refusal counts as "nothing inside", which on the equal-volume
+signature is the refusal the gate was about to make anyway rather than an unabortable
+grind. A refusal is remembered by cache key, so a live edit does not re-pay the failing
+boolean per rebuild. This is deliberately NOT the warnings channel: a skipped fillet is
+an honest part minus a feature, whereas a union that lost its core is wrong, and the two
+other provably-wrong cases in this contract (an empty `Shape2D` reaching `extrude`, the
+coincidence guard) throw for the same reason; a refusal raised by a boolean INSIDE a
+degrading feature (the mesh fillet's own cutters and fillers, a B-rep `safeOp`) is
+caught by that feature's policy and reported as its skip, message included. Results are
+judged once, before they enter the solid cache. A conforming mesh kernel is expected
+never to trip it — the rule is stated for both classes so that a mesh-class refusal
+reads as the kernel bug it would be; measured, the volume reads cost ~0.4% on a
+hundred-cut chain there. Classification: additive, `CONTRACT_VERSION` stays 4. The
+Versioning rule below counts "tightened validation that rejects previously valid
+input" as breaking; this rejects input the kernel previously ACCEPTED but never built
+correctly — every refused result is wrong geometry the author could not have wanted —
+so no previously valid part changes, and a part it refuses was already broken on that
+backend, with the breakage now named.
+
 ## Shape2D (2-D booleans)
 
 `k.shape2d(profile)` (`KERNEL_OPS`) lifts a point list, `{outer,
@@ -876,8 +914,8 @@ The recurring constraint: every op here is implementable on **both** a mesh-CSG
 and a B-rep kernel (see `docs/geometry-backend-strategy.md` for why that dual-backend
 property is worth protecting — OCCT booleans are ~75–1400× slower). Generation *safety*
 comes not from a restricted DSL but from the verify loop (`measure`/`verify` gates:
-`bbox`, `volume`, `holes`, `watertight`, overlaps — plus `minWall` *warnings*, which
-report but never fail) — a generator gets machine-checkable
+`bbox`, `volume`, `holes`, `watertight`, overlaps — plus `minWall` and `overhangArea`
+*warnings*, which report but never fail) — a generator gets machine-checkable
 pass/fail feedback per part, which a syntax could never provide.
 
 ## Conformance checklist for a new backend or host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.109.1",
+  "version": "0.111.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/boolean-gate.js

@@ -0,0 +1,200 @@
+// Refuses a boolean whose RESULT is geometrically impossible — after the op ran.
+//
+// The failure this exists for (measured on real parts, and independently in the
+// 2026-09 ModelRift CadQuery/OpenSCAD study): an exact B-rep kernel's boolean
+// does not throw when it fails. It returns one operand instead of the union, an
+// empty solid instead of the cut, or a negative-volume shape that its own
+// validity check still calls valid — and every one of those ships as a STEP
+// file, a preview, or a `measure` report that looks like a part. The
+// coincidence guard (occt-coincidence.js) refuses the one degenerate
+// CONSTRUCTION it can recognise before the op runs; this gate is the other
+// half, judging the result by the one property no boolean may violate: its
+// volume relative to its inputs.
+//
+//   union      ≥ every operand        (a union contains its inputs)
+//   cut        ≤ its body             (a cut only removes)
+//   intersect  ≤ its smallest operand (an intersection lies inside each input)
+//   any        ≥ 0
+//
+// The inequalities are cheap — one volume read per solid, memoized by the
+// backends — and each carries a slack of 1% of the operand it is compared
+// AGAINST (floored at 1e-6 mm³), so B-spline volume integration noise can never
+// fire them. Scaling the slack to the largest operand instead would switch the
+// cut and intersect rules off whenever the tool is the big one, which the
+// "overcut your tools" guidance makes routine. What the inequalities cannot
+// catch is the exact documented signature of a dropped operand: a thin thread
+// ridge unioned onto a core comes back as the core alone, which is LARGER than
+// the ridge and so passes `union ≥ every operand`. That signature — the
+// result's volume equals one operand's to float precision — is the one place
+// the gate asks for more: first a bounding-box enclosure test (an operand whose
+// box lies inside the other's cannot have lost material; free, and it settles
+// the legitimate "boss buried in the plate" union without a boolean), then an
+// overlap volume (`operands[i] ∩ operands[j]`, supplied lazily by the backend
+// so the extra boolean only ever runs on this signature). If the other operand
+// has material outside the equal one, the union lost it — judged against that
+// operand's OWN size, so a thin ridge is not hidden behind the core's slack.
+// The same probe decides a cut that came back EMPTY: impossible unless the
+// tools covered the whole body. A probe that throws is inconclusive, never a
+// refusal; so is a negative OPERAND, which is broken input rather than this
+// boolean's doing (the backends latch orientation where they know to).
+//
+// This module is pure and backend-neutral on purpose: both kernels call it from
+// inside their cached boolean closures (a cache hit is never re-judged), and
+// test/boolean-gate.test.js pins every rule with plain numbers — the
+// malfunctions it exists for have no deterministic fixture, since the
+// reproducible one is now refused up front by the coincidence guard. Mesh CSG
+// is exact arithmetic and is expected never to trip it; measured, the reads
+// cost nothing there (~0.4% on a hundred-cut chain), and a mesh-class refusal
+// would be a kernel bug worth seeing.
+//
+// A refusal THROWS rather than warning. The warnings channel is for honest
+// degradation (a skipped fillet leaves a correct part minus a feature); a union
+// that lost its core is wrong, not degraded, and the two existing precedents for
+// provably wrong geometry — an empty Shape2D reaching `extrude`, and the
+// coincidence guard — both throw with coaching. In the cloud app that throw lands
+// in the export dialog's "Ask the assistant to fix it" path with the message
+// forwarded verbatim, and a live preview keeps its last good mesh on screen.
+// A refusal that reaches a boolean INSIDE a degrading feature (the mesh fillet's
+// own cutters and fillers, a B-rep safeOp) is caught there and reported as that
+// feature's skip, message included — the feature is what failed, and the part
+// minus it is still honest.
+import { BooleanResultError } from "./errors.js";
+
+export const BOOLEAN_RESULT_INVALID = "BOOLEAN_RESULT_INVALID";
+
+// Slack on the inequalities, relative to the operand being compared against and
+// floored absolutely. 1% is far above any volume-integration error either kernel
+// produces (OCCT's GProp on spline faces; Manifold's exact triangle sum) and far
+// below any real failure (the measured cases were 30% and 100% off).
+const REL_TOL = 1e-2;
+const ABS_TOL = 1e-6; // mm³
+const tolOf = (v) => Math.max(ABS_TOL, REL_TOL * v);
+// "Equals one operand exactly": a returned-unchanged operand reports the identical
+// number; a genuine union that added less than this is physically nothing.
+const EQUAL_REL = 1e-9;
+
+const fmt = (v) => Number(v.toPrecision(6)).toString();
+
+const IMPOSSIBLE_COACHING =
+  "The kernel's boolean returned broken geometry without reporting an error, so the build was " +
+  "refused rather than shipping it. This happens on an exact B-rep kernel when operands touch " +
+  "tangentially or a swept operand nearly touches itself; give the surfaces genuine overlap or " +
+  "genuine clearance (0.05 or more) instead of an exact contact, overcut tools past the faces " +
+  "they pierce, and build threads in the periodic screwSweep form or with k.tappedBore. " +
+  "See ERROR-PATTERNS.md#boolean-impossible-result.";
+
+const DROPPED_COACHING =
+  "The kernel's boolean returned one input instead of the union, without reporting an error — " +
+  "usually a thin or near-self-touching swept operand (a sub-pitch thread ridge riding a core). " +
+  "Give the operands genuine overlap instead of a tangent contact; build a thread in the periodic " +
+  "screwSweep form so it needs no union, or a tapped hole with k.tappedBore. " +
+  "See ERROR-PATTERNS.md#boolean-dropped-operand.";
+
+const impossible = (label, detail) =>
+  new BooleanResultError(`boolean result invalid: ${label} produced an impossible result — ${detail} ${IMPOSSIBLE_COACHING}`);
+const dropped = (label, detail) =>
+  new BooleanResultError(`boolean result invalid: ${label} dropped an operand — ${detail} ${DROPPED_COACHING}`);
+
+// Probe `operands[i] ∩ operands[j]`'s volume through the backend's thunk; null when
+// the probe itself fails (an inconclusive answer must not become a refusal).
+function overlapOf(overlap, i, j) {
+  try {
+    const v = overlap(i, j);
+    return Number.isFinite(v) ? Math.max(0, v) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Cheap enclosure pre-test: true only when the backend can say from bounding
+// boxes alone that operand j lies inside operand i. Absent or throwing = unknown.
+function enclosedBy(encloses, i, j) {
+  try { return encloses?.(i, j) === true; } catch { return false; }
+}
+
+/**
+ * Judge a boolean's result by volume.
+ *
+ * @param {"union"|"cut"|"cutAll"|"intersect"} op
+ * @param {number[]} operands  volumes; for cut/cutAll index 0 is the body, the rest tools
+ * @param {number} result      the result's volume
+ * @param {{ overlap: (i: number, j: number) => number, encloses?: (i: number, j: number) => boolean }} probes
+ *   `overlap` lazily computes the volume of `operands[i] ∩ operands[j]`; consulted only
+ *   on the two signatures the inequalities cannot decide, and allowed to throw (treated
+ *   as inconclusive). `encloses(i, j)` answers "does operand i's bounding box contain
+ *   operand j's" — when true the overlap is never asked for.
+ * @param {string} [label=op]  how the message names the op — a backend that fuses
+ *   cutAll's tools before cutting judges that fuse as a `union` labelled `cutAll (tools)`
+ * @returns {BooleanResultError|null}
+ */
+export function checkBooleanResult(op, operands, result, probes, label = op) {
+  if (operands.length < 2) return null;
+  if (!Number.isFinite(result) || !operands.every(Number.isFinite)) return null;
+  if (operands.some((v) => v < 0)) return null; // broken input, not this boolean's result
+  const { overlap, encloses } = probes ?? {};
+  const largest = Math.max(...operands);
+
+  if (result < -tolOf(largest)) {
+    return impossible(label, `a negative volume (${fmt(result)} mm³).`);
+  }
+
+  if (op === "union") {
+    if (result < largest - tolOf(largest)) {
+      return impossible(label, `a union smaller than its largest operand (${fmt(result)} mm³ vs ${fmt(largest)} mm³).`);
+    }
+    // The dropped-operand signature: the result IS one operand. Every other operand
+    // with volume must then lie inside it, or the union lost material.
+    const i = operands.findIndex((v) => v > ABS_TOL && Math.abs(result - v) <= EQUAL_REL * v);
+    if (i < 0) return null;
+    for (let j = 0; j < operands.length; j++) {
+      const vj = operands[j];
+      if (j === i || vj <= ABS_TOL || enclosedBy(encloses, i, j)) continue;
+      const inside = overlapOf(overlap, i, j);
+      if (inside === null) continue;
+      const outside = vj - inside;
+      if (outside > tolOf(vj)) {
+        return dropped(label,
+          `the result's volume (${fmt(result)} mm³) equals operand ${i}'s exactly, but operand ${j} ` +
+          `(${fmt(vj)} mm³) has ${fmt(outside)} mm³ of material outside it that the union lost.`);
+      }
+    }
+    return null;
+  }
+
+  if (op === "cut" || op === "cutAll") {
+    const body = operands[0];
+    const tol = tolOf(body);
+    if (result > body + tol) {
+      return impossible(label, `a cut larger than its body (${fmt(result)} mm³ vs ${fmt(body)} mm³).`);
+    }
+    if (result <= tol && body > tol) {
+      // Empty result: only possible when the tools covered the whole body. A tool
+      // whose box encloses the body's settles it; otherwise each tool's overlap is
+      // summed — an OVER-estimate of coverage (tools may overlap each other), so
+      // this refuses only when even that cannot reach the body's volume.
+      let covered = 0;
+      for (let j = 1; j < operands.length; j++) {
+        if (operands[j] <= ABS_TOL) continue;
+        if (enclosedBy(encloses, j, 0)) return null;
+        const inside = overlapOf(overlap, 0, j);
+        if (inside === null) return null; // inconclusive
+        covered += inside;
+      }
+      if (covered < body - tol) {
+        return impossible(label,
+          `a cut that emptied its body although the tools cover at most ${fmt(covered)} mm³ of its ${fmt(body)} mm³.`);
+      }
+    }
+    return null;
+  }
+
+  if (op === "intersect") {
+    const smallest = Math.min(...operands);
+    if (result > smallest + tolOf(smallest)) {
+      return impossible(label, `an intersection larger than its smallest operand (${fmt(result)} mm³ vs ${fmt(smallest)} mm³).`);
+    }
+    return null;
+  }
+
+  return null;
+}

package/src/framework/geometry/errors.js

@@ -8,3 +8,14 @@ export class KernelCapabilityError extends Error {
     this.code = "NEEDS_OCCT";
   }
 }
+
+// Thrown by the boolean result gate (boolean-gate.js) when a boolean's result is
+// geometrically impossible — the kernel returned wrong geometry without reporting
+// it. Not a capability gap: nothing reroutes on it. `.code` is the stable handle.
+export class BooleanResultError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BooleanResultError";
+    this.code = "BOOLEAN_RESULT_INVALID";
+  }
+}

package/src/framework/geometry/manifold-backend.js

@@ -18,6 +18,7 @@ import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
 import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
+import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
 
@@ -55,6 +56,42 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // while Manifold's own batch operator evaluates the same union as a balanced tree.
   // A one-solid "union" returns the operand's own Manifold untouched (see union below).
   const unionRaw = (ms) => (ms.length === 1 ? ms[0] : T(Manifold.union(ms)));
+  // Boolean result gate (boolean-gate.js): every author-facing boolean's result is
+  // judged by volume against its operands before it enters the cache, and an
+  // impossible result throws instead of shipping. Mesh CSG is exact arithmetic,
+  // so this backend is expected never to trip it — it is here because the gate
+  // is one kernel-contract rule, not an OCCT special case, and a refusal on this
+  // backend would itself be a kernel bug worth seeing. Measured at ~0.4% on a
+  // hundred-cut chain: `volume()` forces the lazy CSG node, but chained booleans
+  // were never batched in this binding, so nothing is lost to the read. Volumes
+  // are memoized per Manifold object (a result judged here is an operand a step
+  // later). The probes run only on the dropped-operand / emptied-body
+  // signatures: an enclosure test off bounding boxes first, and an intersect
+  // whose result is freed as soon as its one number is read — NOT tracked, so
+  // an n-ary union of buried features does not hold n intermediates to cleanup.
+  const volumes = new WeakMap();
+  const volumeOf = (mm) => {
+    let v = volumes.get(mm);
+    if (v === undefined) { v = mm.volume(); volumes.set(mm, v); }
+    return v;
+  };
+  const BOX_SLACK = 1e-3; // mm — an enclosure test, not a measurement
+  const judged = (op, operandMs, resultM) => {
+    const box = (mm) => mm.boundingBox();
+    const err = checkBooleanResult(op, operandMs.map(volumeOf), volumeOf(resultM), {
+      overlap: (i, j) => {
+        const x = operandMs[i].intersect(operandMs[j]);
+        try { return x.volume(); } finally { x.delete?.(); }
+      },
+      encloses: (i, j) => {
+        const a = box(operandMs[i]), b = box(operandMs[j]);
+        return [0, 1, 2].every((k) => b.min[k] >= a.min[k] - BOX_SLACK && b.max[k] <= a.max[k] + BOX_SLACK);
+      },
+    });
+    if (err) throw err;
+    return resultM;
+  };
+  const judgedUnion = (ms) => judged("union", ms, unionRaw(ms));
 
   const cache = createSolidCache();
   // Feature-skip warnings (the OCCT backend's safeOp policy, adopted here): a
@@ -348,7 +385,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     _m: m,
     _hash: hash,
     _canon: canon,
-    cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
+    cut: (t) => cached(h("cut", hash, t._hash), () => judged("cut", [m, t._m], T(m.subtract(t._m)))),
     // THROWING forms. These are the composition primitives — internal callers
     // that have their own recovery (prismRoundAllFast, which answers a failed
     // fillet by falling back to the reference Minkowski roundAll) must use
@@ -411,10 +448,12 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     },
     // batch difference: first minus the union of the rest, evaluated as one boolean
     // tree — no materialized intermediate union (the unionRaw memory note applies)
-    cutAll: (tools) => cached(h("cutAll", hash, tools.map((t) => t._hash)),
-      () => T(Manifold.difference([m, ...tools.map((t) => t._m)]))),
-    intersect: (t) => cached(h("intersect", hash, t._hash), () => T(m.intersect(t._m))),
-    union: (t) => cached(h("union", [hash, t._hash]), () => unionRaw([m, t._m])),
+    cutAll: (tools) => cached(h("cutAll", hash, tools.map((t) => t._hash)), () => {
+      const ms = [m, ...tools.map((t) => t._m)];
+      return judged("cutAll", ms, T(Manifold.difference(ms)));
+    }),
+    intersect: (t) => cached(h("intersect", hash, t._hash), () => judged("intersect", [m, t._m], T(m.intersect(t._m)))),
+    union: (t) => cached(h("union", [hash, t._hash]), () => judged("union", [m, t._m], unionRaw([m, t._m]))),
     clone: () => wrap(m, hash),
     // Name this solid's surface for hover/pick feature attribution. asOriginal()
     // stamps a fresh originalID that survives transforms and booleans, so every
@@ -724,8 +763,8 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // would pin one WASM object under two entries and eviction would dispose it twice.
     union: (solids) => solids.length === 1
       ? solids[0]
-      : hoistBoolean("union", solids, (ops) => unionRaw(ops.map((s) => s._m)))
-        ?? cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
+      : hoistBoolean("union", solids, (ops) => judgedUnion(ops.map((s) => s._m)))
+        ?? cached(h("union", solids.map((s) => s._hash)), () => judgedUnion(solids.map((s) => s._m))),
     // Imported geometry, registered pre-build by the framework via `_registerImport`
     // (ensureImports, Task 8). The master Manifold is kernel-lifetime (untracked —
     // see `imports` above); wrap() is free, so every call is cheap.