Module budget 

Deterministic per-boolean exact-predicate budget (issue #1109).

Every predicate over an implicit (intersection) point runs a cascade: interval filter → fixed-width exact → BigRational (predicates.rs). The interval filter resolves generic geometry for free, but on genuinely near-coplanar / grazing operands its sign straddles zero, so the predicate falls through to the exact tiers — the fixed-width rungs climb to ~1340 bits and a few spill into BigRational (~5000× the interval tier). Boolean-heavy CAD models (Tekla half-space end-clips, Revit flush openings) are full of such faces, so a single hard element runs the exact path on a huge fraction of the O(intersection-pairs) predicate set. The pure-Rust exact kernel has no operand cap (the old BSP polygon cap was deleted in #1024), so those elements grind to completion regardless of cost and stall the geometry stream at 95% (issue #1109).

This is a deterministic guardrail: it counts interval-filter failures (every predicate that needed the expensive exact tier) per boolean and trips when the count crosses a cap. The count is a pure function of the (snap-grid, integer) operands, so the trip point is IDENTICAL on native x86_64 / aarch64 and on wasm32 — the server and the browser client degrade the SAME hard element to the SAME fallback. That preserves the cross-target parity the pure-Rust kernel exists to guarantee.

A wall-clock budget would NOT preserve parity: the fast native server would finish the exact cut while the slower wasm client tripped the timer, yielding different geometry for the same model. The exact-evaluation COUNT is the right metric precisely because it is platform-independent.

On trip the boolean bails; crate::csg records OperandTooLarge and returns the host un-cut, which routes void subtraction to the deterministic #635 AABB box-cut fallback (“a square hole is dramatically less wrong than a missing void”).

Structs

ElementScope

An open per-element budget scope. Returned by enter_element; dropping it restores every accumulator to the value it had when the scope opened.

Constants

DEFAULT_CAP

Default per-boolean exact-evaluation cap for the interactive profile.

DEFAULT_ELEMENT_CAP

Default per-ELEMENT exact-evaluation cap (#1109 follow-up).

Functions

begin

Begin a boolean operation: reset the per-op escalation counter and snapshot the cap. Call once at every public boolean entry in crate::csg.

begin_element

Begin an ELEMENT scope (#1109 follow-up): reset the per-element accumulator and snapshot the per-element cap, BEFORE the element’s booleans run, so every boolean the element issues accumulates into one budget and a hard element degrades as a whole. Mesh production opens it through enter_element, which also restores the enclosing element’s scope; call this directly only where no element can be nested on the same thread.

cap

The active per-boolean cap, as configured (None ⇒ unbounded).

count

Escalations counted so far in the current boolean (diagnostics / cap calibration).

element_cap

The active per-element cap, as configured (None ⇒ unbounded).

element_count

Escalations accumulated so far in the current element across all its booleans (diagnostics / per-element cap calibration).

element_peak

Highest single-ELEMENT escalation total observed since the last reset_peak. For per-element cap calibration / diagnostics.

enter_element

Open a per-element budget scope (begin_element) that restores the enclosing scope’s counters and caps when dropped. Use this, not a bare begin_element, wherever element meshing can be re-entered on one thread.

note_escalation

Record one exact-tier predicate evaluation (an interval-filter failure). Called from the .or_else(|| fixed::…) arms of crate::kernel::predicates — the point where a predicate leaves the cheap interval filter for the expensive fixed-width / BigRational path.

peak

Highest single-boolean escalation count observed since process start (or the last reset_peak). For cap calibration / diagnostics.

reset_peak

Reset the global peak escalation counters (per-boolean and per-element).

set_cap

Set the global per-boolean escalation cap. None = unbounded (exact to completion — the server/CLI/offline-export profile); Some(n) = trip after n BigRational escalations (the interactive viewer/wasm profile). The default is DEFAULT_CAP, so the viewer is bounded out of the box.

set_element_cap

Set the global per-element escalation cap (#1109 follow-up). None = unbounded. The default is DEFAULT_ELEMENT_CAP.

tripped

Whether the current boolean OR the current element has exceeded its escalation budget. Checked at loop boundaries in the arrangement AND inside the per-point retriangulation loop so the bail is timely and graceful. Once the per-element budget is blown, every subsequent boolean the element issues trips immediately (its COUNT resets per begin, but ELEM_COUNT does not), so the element’s remaining cuts bail to the #635 AABB fallback.