feat(algo): split u-periodic faces into bands at internal section circles

[andymai]

When a tool pierces through a solid (cylinder bore through a slab), the periodic lateral face's internal section circles were interpreted as planar disc+hole loops. None of the emitted sub-faces was the real lateral band: classification kept a phantom membrane disc, the top circle became a free edge (Euler 3), and the operations wrapper fell back to the mesh path — non-manifold, volume-lossy, and run-to-run jittery. This implements the band design from the in-code post-mortem in face_splitter/special_cases.rs, including the seam-anchoring that the reverted prior attempt (#535) lacked.

Changes

• Seam-anchor pre-pass in fill_images_faces: closed circle FF curves on cylinder/cone laterals are re-parameterized to start at surface.evaluate(seam_u, v_i); anchor vertices pre-registered so lateral band wires and plane-face hole wires resolve to the same VertexId.
• split_periodic_face_into_bands: emits N+1 band sub-faces sorted by v with on-surface interior points at (seam_u + π, v_mid); boundary-coincident (flush-cap) circles skipped; fully-flush tools bail to legacy paths.
• Disc path now preserves pre-existing inner wires, so sequential cuts no longer drop earlier holes.
• classifier/ray_cast: geometrically chained wire polygons, plane-face hole exclusion, analytic ray-cylinder crossing counts for full-period cylindrical faces (the flat-polygon approximation flipped parity for rays through bores).
• New validate_shell_closed (flags free edges) used by the algo pinning tests; operations wrapper rejects Intersect results with free edges.
• Un-ignores 11 tests, including both algo pinning tests (single bore: Euler 2 manifold; 4×4 sequential grid: F=22, strict closed manifold), the golden box-minus-cylinder regression (golden regenerated — volume/bbox unchanged, tessellation differs because the lateral is now real cylinder bands), and gridfinity sequential_booleans_volume_accuracy (Solid validation and volume regression on lip/fillet geometry #260).

Six tests stay ignored: their failures are box-box flush-fuse non-manifold cases with no periodic faces involved (separate gap).

Verification

Full workspace green (45 suites, 0 failures); the regression gates that reverted the prior attempt all pass — compound-cut 2×2/3×3/4×4 grids, honeycomb (timed, no hang), shelled-target; fmt, clippy -D warnings, boundary check.

[github-actions]

WASM Binary Size

File	main	PR	Delta
brepkit_wasm.wasm	4.72 MB	4.75 MB	+35.1 KB (+.7%)

⚠️ Size increased slightly.

[Copilot]

Pull request overview

Implements the “cylinder/cone lateral band” design for u-periodic faces so closed section circles no longer get misinterpreted as planar disc loops, which previously produced phantom membrane faces, free edges, and unstable mesh-fallback results in boolean operations involving bores through solids.

Changes:

• Adds a seam-anchoring pre-pass for full-circle intersection curves on periodic laterals and a new split_periodic_face_into_bands path that emits stacked lateral band sub-faces between consecutive section circles.
• Improves point-in-solid classification via ray casting by (a) chaining wire edges geometrically, (b) excluding planar holes from crossings, and (c) using analytic ray–cylinder crossing counts for full-period cylindrical faces.
• Tightens validation/gating for boolean results by introducing validate_shell_closed (rejects free edges) and using it in pinning tests plus an Intersect-specific “no free edges” gate; un-ignores multiple regression tests and updates the relevant golden output.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/golden/data/boolean_box_minus_cylinder.golden	Updates golden output reflecting new lateral band topology/tessellation while keeping volume/bbox stable.
crates/wasm/src/bindings/gridfinity_tests.rs	Un-ignores volume accuracy regression test tied to boolean robustness.
crates/topology/src/validation.rs	Adds validate_shell_closed and tests for rejecting free edges / accepting closed two-sided shells.
crates/operations/tests/golden_regression.rs	Un-ignores golden regression for box-minus-cylinder boolean case.
crates/operations/tests/boolean_stress.rs	Un-ignores stress tests for cylinder cut scenarios.
crates/operations/src/measure/mod.rs	Un-ignores volume regression test covering cylinder band classification.
crates/operations/src/boolean/tests.rs	Un-ignores multiple boolean regression tests previously blocked by periodic-face issues.
crates/operations/src/boolean/mod.rs	Adds Intersect-specific rejection of free-edge results via has_free_edges.
crates/algo/src/pave_filler/tests.rs	Switches pinning tests to strict closed-shell validation and un-ignores them.
crates/algo/src/classifier/ray_cast.rs	Refactors ray-cast geometry collection and adds analytic full-period cylinder crossing handling + hole exclusion.
crates/algo/src/builder/fill_images_faces.rs	Adds seam-anchor pre-pass and re-parameterizes closed section circles to start on the periodic seam.
crates/algo/src/builder/face_splitter/special_cases.rs	Introduces split_periodic_face_into_bands and preserves pre-existing inner wires in the disc-loop fallback.
crates/algo/src/builder/face_splitter/mod.rs	Routes periodic faces through the band splitter and improves inner-wire handling for closed curved holes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR implements the band-split fix for u-periodic faces (cylinder/cone laterals) cut by closed section circles — the root cause of the phantom-membrane disc topology, Euler-3 non-manifold results, and GFA mesh-boolean fallback tracked since PR #534.

• Seam-anchor pre-pass (fill_images_faces): full-circle FF curves on cylinder/cone faces are re-parameterized to start at the surface seam, with seam-point vertices pre-registered so cross-face wire sharing works without position-fallback duplication.
• split_periodic_face_into_bands (special_cases.rs): emits N+1 stacked band sub-faces with (seam_u + π) rem 2π interior points; boundary-flush circles skipped, fully-flush tools fall through to legacy paths.
• Analytic ray-cylinder classifier (ray_cast.rs): replaces the flat-polygon crossing count (parity-flip for full-period bores) with a quadratic solve; cylinder_hole_bands is intended to handle flush-cap inner-wire holes but is currently unreachable due to a sampling-threshold mismatch.
• Free-edge guard (boolean/mod.rs): Intersect results with free edges are rejected; 11 previously-ignored tests now pass.

Confidence Score: 5/5

Safe to merge — all 45 test suites pass and the regression gates from the reverted PR #535 are green.

The core algorithm is well-tested end-to-end by the pinning tests and golden regression. The three findings are non-blocking style or latent correctness concerns that do not affect correctness on the enabled test matrix.

crates/algo/src/classifier/ray_cast.rs — the cylinder_hole_bands threshold deserves a follow-up before any flush-cap inner-wire scenario is enabled.

Important Files Changed

Filename	Overview
crates/algo/src/builder/face_splitter/special_cases.rs	Replaces the long-standing known-gap comment with the real split_periodic_face_into_bands implementation; one new _ => wildcard on an EdgeCurve tuple match violates the wildcard-match-arms rule.
crates/algo/src/builder/fill_images_faces.rs	Adds seam-anchor pre-pass and cap-disc IN-edge filtering; hardcoded tolerances already flagged in prior thread.
crates/algo/src/classifier/ray_cast.rs	Adds analytic ray-cylinder crossing and cylinder_hole_bands helper; the wraps_full u-span threshold is unreachable with 16-sample circle polygons, making hole-band detection dead code.
crates/algo/src/builder/face_splitter/mod.rs	Routes u-periodic non-plane faces with no pre-existing inner wires into the band path; correctly preserves pre-existing inner wires for the disc/loop path.
crates/algo/src/builder/same_domain.rs	Replaces vertex-only polygon sampling with 8-samples-per-edge curve sampling, fixing silent hole-cancellation for single-circle inner wires.
crates/topology/src/validation.rs	Adds validate_shell_closed with two well-targeted unit tests.
crates/operations/src/boolean/mod.rs	Adds has_free_edges check gated on BooleanOp::Intersect; Cut/Fuse intentionally keep the lenient gate.
crates/algo/src/pave_filler/tests.rs	Un-ignores two pinning tests; new test comment mis-states genus-2 for an Euler=2 BRep result.

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
crates/algo/src/builder/face_splitter/special_cases.rs:200-204
New `_ =>` wildcard on an `EdgeCurve`-containing tuple match — per the `wildcard-match-arms` rule, catch-all arms on `EdgeCurve` patterns should be avoided so the compiler surfaces any new variants. If a new `EdgeCurve` variant is ever added, this arm silently routes it to `return None` instead of generating a compile error. The intended semantics can be expressed exhaustively without a blanket wildcard.

```suggestion
        match (&e.curve_3d, is_closed) {
            (EdgeCurve::Circle(_), true) => boundary_circles.push(e),
            (EdgeCurve::Line, false) => seam_edges.push(e),
            // Any other combination (open circle, closed line, NURBS, etc.)
            // means this face's boundary isn't a standard seam+circles layout.
            (EdgeCurve::Circle(_), false)
            | (EdgeCurve::Line, true)
            | (EdgeCurve::Nurbs(_), _)
            | (EdgeCurve::Ellipse(_), _) => return None,
        }
```

### Issue 2 of 3
crates/algo/src/classifier/ray_cast.rs:301-306
**`wraps_full` threshold unreachable with 16-sample circles**

`wire_polygon` generates `n_samples = 16` interior samples at fractions `k/(n+1)` for `k = 1..=16`. The highest-u sample lands at `u ≈ TAU × 16/17 ≈ 5.91`, so `u_max − u_min ≈ 5.91 < TAU − 1e-3 ≈ 6.282` — the gap is ~0.37 rad, about 370× larger than the tolerance. `wraps_full` is always `false` for any seam-anchored full-circle inner wire, making `cylinder_hole_bands` always return an empty `Vec` and the `FaceGeom::Cylinder { hole_bands }` non-empty path dead code. A viable fix is to threshold at `TAU * (n_samples as f64 / (n_samples + 1) as f64) - epsilon`, or to check directly whether the inner wire contains a single closed circle edge rather than measuring the u-span of a polygon approximation.

### Issue 3 of 3
crates/algo/src/pave_filler/tests.rs:1532-1535
The error message says "closed genus-2 manifold" but the codebase convention is that `V − E + F = 2` is the closed-manifold BRep invariant for all through-bore results regardless of topological genus — the grid-of-16 test explicitly calls this "genus 0". A box with 2 through bores has topological genus 2 (χ = −2), but the BRep Euler count hits 2 because inner-wire loops cancel the genus terms.

```suggestion
    assert_eq!(
        euler, 2,
        "Euler V-E+F should be 2 for a closed manifold (BRep convention: inner loops \
         cancel genus terms), got V={v} E={e} F={f}"
    );
```

_{Reviews (3): Last reviewed commit: "fix(algo): coordinate seam adoption with..." | Re-trigger Greptile}