brepkit

Use at the start of an autonomous or unsupervised session to pick what to work on, when deciding whether a geometry case is worth chasing, when a task looks like something a past session already tried, or before claiming a case is closed. The sanctioned work-selection doctrine: what is open and ready, what is terminal, the chase filters, and the acceptance bar.

Use when adding or changing methods on BrepKernel in crates/wasm, wiring ops into executeBatch, writing tests for bindings, building the wasm package (wasm-pack or cargo xtask wasm-build), testing a local kernel build inside brepjs or another JS consumer, or debugging wasm-only failures such as tests that will not compile with JsError, panics that abort the wasm instance, "recursive use of an object" errors, or a JS app silently loading a stale wasm build. Also use when the CI "WASM Binary Size" PR comment shows growth or a change adds a dependency to the wasm graph.

Use when adding a new modeling operation to crates/operations (a new pub fn taking &mut Topology and returning a SolidId or similar), when extending an existing operation with a new code path, or when an operation's tests need to prove correctness before shipping. Covers implementation traps, error handling, test placement, wasm exposure, and the verification bar.

Use when a boolean, revolve, offset, or other operation degrades exact analytic geometry (planes, cylinders, cones, spheres, tori, circles) to NURBS or a mesh fallback, when face counts explode from a handful to hundreds, when running or interpreting the approx_census, when adding an exact analytic-analytic intersection arm, or when deciding whether an analytic-recovery task is worth chasing at all.

Diagnose and fix failures of the GFA boolean engine (fuse, cut, intersect). Use when a boolean result mesh-falls-back to hundreds of all-planar faces, comes out non-manifold or open-shelled, is missing faces, has wrong volume, fails the Euler or validation gates, errors in shell assembly, or gives different results across runs.

The meta-method for debugging hard geometry bugs in brepkit, used when a boolean, fillet, offset, or tessellation produces wrong volume, wrong face count, open or non-manifold shells, mesh fallback, misclassified points, or any failure where the first diagnosis did not immediately hold. Also applies before starting any multi-pass investigation, when a repro behaves differently from the real case, or when successive root-cause theories keep overturning each other.

Diagnose fillet and chamfer bugs by locating which engine owns them, debug the v2 walking blend, and avoid the silent no-op success in the public fillet binding. Use when a fillet or chamfer leaves free edges, produces an open or non-manifold shell, silently changes nothing, degrades a cylindrical wall to NURBS, or when deciding whether to touch the deprecated v1 fillet code.

Use when a STEP or other file imports wrong (missing solids, all-NURBS where analytic was expected, hard UnsupportedEntity errors), when verifying writer output round-trips, when capturing a faithful fixture from a real file, or when adding or extending a format in crates/io. Covers the format matrix, STEP reader anatomy, the analytic round-trip check, and heal-after-import.

Use when adding a workspace dependency between brepkit crates, deciding which crate new code belongs in, adding a variant to EdgeCurve or FaceSurface (or a new analytic surface type), fixing a CI "boundaries" job failure or a VIOLATION from scripts/check-boundaries.sh, or hitting "two different versions of crate brepkit-topology" errors.

Use when debugging floating-point failures in brepkit: a boolean or heal result flips pass/fail across runs or under tiny (1e-13) input nudges, closed/periodic geometry (circles, tori, seams) produces collapsed AABBs or wrong arcs, intersection points miss chord-discretized seams, near-duplicate vertices fail to merge, or when writing any code that compares floats, hashes coordinates, or iterates edges of closed curves.

Use when proving brepkit matches or beats the reference kernel, running the brepjs wasm head-to-head benchmark, overlaying a local kernel build into the gridfinity tool, re-probing scenario face counts after a GFA or boolean change, capturing faithful fixtures (STEP or arena .bin) from a failing tool scenario, or running local criterion micro-benchmarks. Also use whenever a speedup or parity claim is about to be quoted anywhere.

Use when committing, pushing, opening, reviewing, or merging a pull request in brepkit, or when a git hook fails, a push hangs, commitlint flags a message, a PR sits waiting on AI review, or parallel work needs a worktree. Covers hooks, conventional commits, the AI-review merge gate, the sandbox HTTPS push, and release-please.

Use when investigating or fixing performance in brepkit: a benchmark got slower, an operation (boolean, fuse, tessellation) is unexpectedly slow or hangs, a criterion bench times out or shows wild variance, or a PR needs before/after perf numbers. Covers flamegraphs, the criterion bench suite, cross-kernel comparison, and the perf bug classes this codebase has actually had.

Shipping a brepkit change all the way into brepjs. Use when a feature PR has merged and the change must reach npm and the brepjs adapter, when bumping the brepkit-wasm pin in brepjs, when running or debugging the type sync (sync:brepkit-types, tsc failures on Brepkit* types), when a dep-bump branch conflicts with a release-please commit, or when a push fails or hangs in this sandbox.

Use when working with brepkit-render (offscreen GPU render, face-id buffer, interactive viewer, compute mesher, screen-space LOD) or when visually verifying a solid in this sandbox, including capturing a live viewer window headlessly, writing image-based render tests, or deciding between render checks and mesh watertightness checks.

Ground-truth verification of any B-Rep result in brepkit. Use when checking whether a solid is watertight, manifold, correctly classified, or has the right volume; when signing off a boolean, offset, fillet, or other geometry change; when a volume looks wrong or disagrees across deflections; or when deciding whether a "passing" check actually proves the geometry is correct.

Use when meshing B-Rep faces or debugging tessellation output in crates/operations/src/tessellate/. Triggers: mesh cracks at shared face boundaries, boundary_edge_count > 0, non-manifold edges, a hole on a sphere/torus skinned over (mesh area too large), flipped triangle normals, adding or changing a face mesher, or choosing between CDT and a structured band mesher on a periodic surface (cylinder, cone, sphere, torus).

Use when writing, placing, running, or updating tests in brepkit; when a bug fix needs a regression fixture; when deciding whether a repro is faithful to the real failing geometry; when a golden file mismatches; or when ending a session with unverified work (verify-or-revert). Covers unit, proptest, golden, integration, wasm contract, bench, and ignored ready-repro tests.