grid-apps-cmms/docs/void/plan-chamfer-offset-v2.md

# Void Chamfer V2 Plan (Geometric Offset, Not Boolean Cutters)

## Goal

Replace the current chamfer implementation based on cutter solids + boolean difference with a deterministic geometric chamfer pipeline that operates directly on mesh topology and face offsets.

## Why Change

1. Current path is boolean-driven (`solid/chamfer.js`) and depends on synthetic cutter prisms.
2. Boolean chamfer is fragile near:
   - short edges
   - dense/curved topology
   - multi-edge corner interactions
   - near-coplanar/low-angle neighborhoods
3. Provenance and boundary tracking are harder when chamfer is represented as a subtract operation, rather than explicit edge-face reconstruction.
4. Debugging and deterministic replay are harder with cutter generation and manifold fallback behavior.

## Current-State Findings

1. Chamfer currently:
   - resolves selected edges
   - builds cutter meshes from adjacent triangle normals
   - performs boolean difference
   - writes resulting body as manifold output

2. Signals in current code indicate boolean-centric lifecycle:
   - `manifold_chamfer_passthrough`
   - `manifold_chamfer_ready`
   - cutter debug/failure logs

3. Edge references are already fairly good:
   - chamfer refs use canonical boundary/segment identities
   - this is strong input for a topology-based rebuild

## Target Architecture

Chamfer becomes a topology/geometry transform, not a subtractive solid operation.

1. Input:
   - selected sharp edges (from stable boundary segment refs)
   - chamfer distance (and later optional asymmetric distances)

2. Core operation:
   - for each selected edge, offset its two incident face planes by chamfer distance
   - intersect offset planes with local wedge to compute chamfer strip geometry
   - trim neighboring faces and insert chamfer face(s)

3. Corner resolution:
   - solve multi-edge vertex neighborhoods explicitly
   - produce watertight corner patches without global booleans

4. Output:
   - rebuilt manifold mesh + updated provenance/boundary mappings
   - explicit chamfer faces with stable IDs (not anonymous boolean remnants)

## Data Model / Provenance Updates

1. Extend chamfer result metadata:
   - `source_edge_segment_ids[]`
   - `generated_face_ids[]`
   - `status: geometric_chamfer_ready`

2. GeometryStore integration:
   - chamfer faces emit boundaries/segments directly
   - chamfer faces carry source edge lineage

3. Preserve compatibility:
   - existing docs still readable
   - optional fallback to legacy boolean chamfer behind feature flag

## Algorithm Plan

## Stage A: Topology Extraction

1. Build edge->incident-face adjacency from input mesh.
2. Identify valid chamfer candidates:
   - manifold edges with exactly two incident faces
   - non-smooth crease threshold gating

3. Group selected edges into connected chamfer regions.

## Stage B: Per-Edge Offset Construction

1. For each selected edge:
   - compute incident face normals
   - construct two offset face planes
   - compute chamfer line as plane-plane intersection in local neighborhood

2. Create edge strip endpoints using neighboring trim constraints.

## Stage C: Face Trimming + Insertion

1. Trim original incident faces against chamfer boundary lines.
2. Insert chamfer quad/tri strip faces.
3. Maintain winding and local normal consistency.

## Stage D: Vertex Corner Solver

1. At each selected vertex:
   - collect incoming chamfer strips
   - solve intersection polygon in tangent frame
   - triangulate corner patch deterministically

2. Handle edge cases:
   - 2-edge corner
   - n-edge star corner
   - near-parallel incident faces

## Stage E: Rebuild + Mapping

1. Rebuild indexed mesh with new vertices/faces.
2. Recompute boundary segments and canonical edge refs.
3. Emit provenance mappings:
   - old edge ref -> new chamfer face/segments
   - unchanged faces preserve IDs where possible

## Execution Phases

## Phase 1: Infrastructure + Feature Flag

1. Add `chamfer_mode` toggle:
   - `legacy_boolean` (default initially)
   - `geometric_offset` (new path)
2. Build shared adjacency/topology helpers.

Exit criteria:

1. New path can run no-op safely and fall back cleanly.

## Phase 2: Single-Edge Geometric Chamfer

1. Implement robust one-edge chamfer on simple prism/cube cases.
2. Add deterministic unit fixtures.

Exit criteria:

1. Single selected edge produces expected geometry with no booleans.

## Phase 3: Multi-Edge Same-Face + Parallel Chains

1. Handle multiple selected edges on same body.
2. Ensure trim interactions are stable and watertight.

Exit criteria:

1. Common user workflows work without mesh cracks.

## Phase 4: Corner Solver

1. Implement n-edge corner patches.
2. Add tolerance policy and degeneracy handling.

Exit criteria:

1. Complex corners no longer require boolean fallback.

## Phase 5: Provenance + GeometryStore Wiring

1. Emit chamfer-derived boundaries/patch IDs with lineage.
2. Update hover/select mapping for chamfer outputs.

Exit criteria:

1. Chamfer boundaries are first-class and traceable.

## Phase 6: Default Cutover

1. Make geometric mode default.
2. Keep legacy boolean fallback for one release window.
3. Remove legacy path after stability window.

## Testing Plan

## Unit

1. Edge adjacency correctness.
2. Plane offset/intersection math.
3. Corner patch triangulation determinism.
4. Degenerate geometry tolerance behavior.

## Integration

1. Cube single-edge chamfer.
2. Multiple connected edges.
3. Concave/convex mixed selections.
4. Timeline edits upstream/downstream with stable refs.
5. Interaction with boolean-added bodies.

## Regression

1. No face holes/non-manifold edges after chamfer.
2. No ID churn for unaffected faces.
3. Boundary segment refs remain selectable post-chamfer.

## Risks and Mitigations

1. Risk: corner solver complexity.
   - Mitigation: staged rollout with strict fixtures before cutover.

2. Risk: precision instability on small geometry.
   - Mitigation: unified epsilon policy + local frame math.

3. Risk: behavior divergence from existing chamfer expectations.
   - Mitigation: side-by-side mode comparison tooling and temp dual-run validator.

## Implementation Touchpoints

1. `src/void/solid/chamfer.js`
   - split into legacy boolean and new geometric engine.

2. `src/void/solid/rebuild.js`
   - route chamfer feature to mode-specific executor.

3. `src/void/api/solids.js`
   - preserve/refit canonical edge mappings after geometric chamfer.
   - expose chamfer lineage for debug overlays.

4. `src/void/api/geometry_store.js`
   - ensure chamfer outputs emit boundary/segment/provenance records consistently.

## Immediate Next Step

Implement Phase 1 + Phase 2 in parallel:

1. Add mode flag and new engine scaffolding.
2. Land deterministic single-edge geometric chamfer on planar solids.