Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

docs: add EDGE-A0 AirEdgeSweep fillet/chamfer architecture audit

Yuechen Li9d5c02eba7e0
diff --git a/docs/aetheris-v2-sweep-first-architecture.md b/docs/aetheris-v2-sweep-first-architecture.md
index d00d9c1f..f2dedd7d 100644
--- a/docs/aetheris-v2-sweep-first-architecture.md
+++ b/docs/aetheris-v2-sweep-first-architecture.md
@@ -152,6 +152,9 @@ Aetheris’s bounded no-NURBS answer to common loft-like manufacturing intent:
- ruled side walls with deterministic representation,
- no generic freeform loft interpolation.
+
+Note: bounded edge surfacing for future constructive chamfer/fillet is tracked under `AirEdgeSweep` architecture audit (`docs/edge-a0-air-edge-sweep-fillet-chamfer-audit.md`).
+
### 6.7 AirSurfaceOffset
Necessary but high-risk family:
diff --git a/docs/edge-a0-air-edge-sweep-fillet-chamfer-audit.md b/docs/edge-a0-air-edge-sweep-fillet-chamfer-audit.md
new file mode 100644
index 00000000..a140bebf
--- /dev/null
+++ b/docs/edge-a0-air-edge-sweep-fillet-chamfer-audit.md
@@ -0,0 +1,253 @@
+# EDGE-A0 / V2-A4 — AirEdgeSweep fillet/chamfer architecture audit
+
+## 1. Executive summary
+Fillets/chamfers in current Aetheris production behavior are implemented as legacy bounded BRep feature operations (`BrepBoundedChamfer`, `BrepBoundedFillet`) routed through Firmament bounded execution seams.
+
+V2 evidence from V2-V5, V2-X8.1, and V2-X8.2 confirms that bounded chamfer recognition is load-bearing for some legacy topology routes (notably triangle prism), and that summary/STEP parity is insufficient when adjacency/corner contracts diverge.
+
+The forward architecture direction should treat chamfers/fillets as constructive edge sweeps (`AirEdgeSweep`) rather than discovered topology repair.
+
+This milestone is a decision-grade state audit and bounded roadmap proposal only. It does not change production behavior.
+
+## 2. Why this audit exists
+Triangle production migration to `LineArcProfileExtrudeEmitter` was attempted and reverted because bounded chamfer/corner recognition depended on legacy adjacency/corner topology conventions that were not preserved.
+
+V2-A3 doctrine formalized the rule that load-bearing topology remains legacy-authoritative until a replacement contract is explicitly proven (including feature-recognition parity).
+
+`AirEdgeSweep` is the likely replacement contract for future constructive chamfer/fillet behavior, so this audit exists to define admissible scope, risk boundaries, and first-lab sequencing.
+
+## 3. Current code/docs inspected
+### Core/docs
+- `docs/aetheris-v2-sweep-first-architecture.md`
+- `docs/aetheris-v2-a1-resolved-profile2d-contract.md`
+- `docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md`
+- `docs/v2-v5-triangle-prism-profile-extrude-production.md`
+- `docs/frictionlab/v2-x8-1-triangle-chamfer-adjacency-parity-lab.md`
+- `docs/frictionlab/v2-x8-2-triangle-adjacency-delta-audit.md`
+- `docs/surface-feature-a0-architecture-audit.md`
+- `docs/surface-feature-a1-descriptors.md`
+- `docs/surface-feature-a2-planning-bridge.md`
+- `docs/surface-feature-a3-planar-groove-dry-run.md`
+- `docs/surface-feature-a4-planar-groove-evidence.md`
+
+### Code/test surfaces examined
+- `Aetheris.Kernel.Core/Brep/EdgeFinishing/BrepBoundedChamfer.cs`
+- `Aetheris.Kernel.Core/Brep/EdgeFinishing/BrepBoundedFillet.cs`
+- `Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs`
+- chamfer/fillet/corner/triangle-related tests under:
+ - `Aetheris.Kernel.Firmament.Tests`
+ - `Aetheris.Kernel.Core.Tests`
+ - `Aetheris.FrictionLab.Tests`
+
+### Diagnostics searched
+- `No bounded corner-resolution candidate was admissible`
+- `Bounded fillet edge resolution rejected`
+
+## 4. Current chamfer architecture
+### Entry points
+- Firmament execution routes chamfer booleans through bounded chamfer execution (`ExecuteBoundedChamferOnRecognizedOrthogonalRoot`) and then into `BrepBoundedChamfer` candidate families.
+
+### Bounded corner resolution / candidate selection
+- Bounded chamfer uses explicit bounded candidates (single edge, incident edge-pair corner, and single-corner modes depending on recognized context and selectors).
+- Admissibility and rejection reasons are explicit and diagnostic-first.
+
+### Diagnostics
+- Failure reports include bounded context/source diagnostics and corner-resolution rejection details, including the known message `No bounded corner-resolution candidate was admissible` in failed parity routes.
+
+### Assumptions about adjacency/corner ordering
+- Chamfer admissibility is sensitive to emitted local topology conventions (loop/coedge ordering/orientation and corner incidence semantics).
+- Triangle migration labs show this sensitivity is currently load-bearing.
+
+### Supported/unsupported envelopes (current)
+- Supported: bounded, explicit selector-driven chamfer cases within recognized root contexts (including specific orthogonal and trusted-polyhedral bounded lanes).
+- Unsupported/deferred: generic open-ended chamfer surfacing, unconstrained multi-corner chain resolution, and broad freeform edge modification.
+
+### Relationship to triangle primitive
+- For chamfer-sensitive triangle production, legacy `BrepPrimitives.CreateTriangularPrism` remains authoritative until adjacency contract parity is proven.
+
+### Separation
+- **Construction intent**: explicit bounded chamfer operation with constrained selectors.
+- **Topology discovery**: still dependent on existing emitted topology contracts rather than a fully declared constructive edge-sweep contract.
+- **Legacy adjacency assumptions**: load-bearing in triangle/corner parity evidence.
+- **Corner patch policy**: bounded candidate-based resolution with explicit rejection when no admissible corner candidate exists.
+
+## 5. Current fillet architecture
+### Entry points
+- Firmament bounded fillet route (`ExecuteBoundedManufacturingFilletOnRecognizedOrthogonalRoot`) dispatches to `BrepBoundedFillet.FilletTrustedPolyhedralSingleInternalConcaveEdge` and candidate families.
+
+### Supported analytic cases / construction style
+- Current bounded fillet is centered on constant-radius cylindrical internal concave bounded cases with explicit admissibility.
+- Candidate families include single-edge and chained same-radius cylindrical lanes, plus bounded cylindrical-termination contexts.
+
+### Diagnostics
+- Explicit rejection diagnostics for context/radius/edge validity and candidate admissibility.
+- Representative rejection: `Bounded fillet edge resolution rejected: ...`.
+
+### Supported/unsupported envelope
+- Supported: bounded internal concave edge selections with deterministic local loop/corner construction constraints.
+- Unsupported/deferred: broad convex edge replacement families, variable-radius generalization, unconstrained corner-networks, and generic rolling-ball reconstruction.
+
+### Relationship to analytic surface families
+- Current bounded fillet route materially emits/depends on cylindrical fillet faces for admitted scopes.
+- Broader analytic families (plane/cylinder/cone/sphere/torus) remain relevant for future classification but are not all currently generalized under one constructive fillet contract.
+
+### Separation
+- **Construction intent**: bounded constant-radius fillet intent over selected edges.
+- **Topology discovery**: partially local constructive rebuild with bounded assumptions, still constrained by legacy metadata/topology contracts.
+- **Legacy assumptions**: occupied-cell safe-composition metadata and local incidence conventions are required.
+- **Corner patch policy**: bounded one/two-corner chain behavior with deterministic rejection outside scope.
+
+## 6. AirEdgeSweep concept
+Proposed `AirEdgeSweep` should be a declared constructive edge-surface operation contract.
+
+Required conceptual inputs:
+- host body / host feature context,
+- target edge or edge chain,
+- adjacent faces,
+- sweep profile:
+ - straight line for chamfer,
+ - circular arc for fillet,
+ - variable profile explicitly deferred for first production scopes,
+- offset rule:
+ - distance,
+ - radius,
+ - face-relative offsets,
+ - tangent constraints,
+- convex/concave classification,
+- corner policy,
+- admissibility diagnostics,
+- fallback/legacy behavior policy.
+
+Contract aliases:
+- `AirChamfer` = constrained `AirEdgeSweep` with straight-line profile.
+- `AirFillet` = constrained `AirEdgeSweep` with circular-arc profile.
+
+## 7. Chamfer as ruled edge transition
+Conceptually:
+- Construct offset edge curves on the two adjacent host faces.
+- Connect the two offset curves with straight generators.
+- In planar-planar straight-edge cases, resulting chamfer face is planar/ruled.
+- Adjacent host faces are trimmed/replaced according to a declared topology plan.
+
+First-scope boundary:
+- planar-planar straight edge,
+- constant chamfer distance,
+- no corner chain,
+- no variable distance.
+
+## 8. Fillet as circular-profile edge sweep
+Conceptually:
+- Construct tangent/offset guide curves from adjacent faces.
+- Sweep a circular arc profile along the target edge path.
+- Planar-planar constant-radius fillet reduces to cylindrical face emission.
+- Plane-cylinder contexts may classify to bounded toroidal/other analytic families when explicitly admitted.
+- Corner patches must be explicit constructions, not discovered late-stage rolling-ball repairs.
+
+First-scope boundary:
+- planar-planar straight edge,
+- constant radius,
+- convex/concave separated,
+- no variable radius.
+
+## 9. Convex vs concave policy
+Architectural distinction:
+- Concave fillets/chamfers can often be additive transition patches in bounded contexts and are typically lower risk.
+- Convex fillets/chamfers replace/remove sharp external edge topology and require deterministic trim/replacement semantics.
+- Convex cases are the primary anti-subtract target and must be treated as explicit replacement construction.
+- Both lanes should be constructive; first lab ordering can differ for risk control.
+
+Recommended lab tracks:
+- concave additive patch lab first (safest proof lane),
+- convex planar chamfer replacement lab next,
+- convex planar fillet replacement after.
+
+## 10. Corner patch policy
+Corners are where legacy/discovery-heavy approaches tend to fail due to ambiguity in chain interaction and termination.
+
+Provisional policy:
+- Equal-radius convex triple-edge fillet corners may be admissible via explicit sphere patch construction.
+- Unequal-radius/mixed-family corner cases are deferred.
+- Chamfer triple-corner cases may require explicit planar/triangular corner patch construction.
+- Initial labs should isolate or avoid corner chains until single-edge semantics are proven.
+
+First-scope limitations (explicit):
+- no broad multi-edge corner-network solver,
+- no unequal-radius convex corner blending,
+- no implicit rolling-ball corner discovery.
+
+## 11. Proposed AirEdgeSweep admissibility ladder
+1. host/edge/faces are analytic and in supported families,
+2. edge chain is simple and bounded,
+3. adjacent faces are known and oriented,
+4. convex/concave classification is deterministic,
+5. offset/tangent curves are constructible,
+6. sweep profile is admissible,
+7. corner policy is known for this request,
+8. topology replacement/addition plan is deterministic,
+9. STEP/export analytic-family output is supported for the admitted scope or explicitly deferred with diagnostics.
+
+## 12. Relationship to V2-A3 parallel lanes
+- `BrepBoundedChamfer` remains legacy-authoritative for currently chamfer-sensitive production routes.
+- `AirEdgeSweep` should be developed in parallel lab lanes.
+- Legacy chamfer/fillet routes must not be retired before feature-recognition parity is proven for affected scopes.
+- Triangle production migration may be revisited only after AirEdgeSweep or explicit adjacency-contract hardening closes known deltas.
+
+## 13. Relationship to ruled surfaces and surface offsets
+- Chamfer is closely aligned with an `AirRuledTransition`-like edge transition family.
+- Fillet is a circular-profile edge sweep and is not strictly ruled.
+- Surface offset is related but higher risk (self-intersection/trim stability) and should remain separately bounded.
+- Do not collapse this work into generic UV/NURBS surfacing; preserve no-NURBS guardrail.
+
+## 14. Recommended first labs
+Proposed sequence:
+- **EDGE-X1**: Chamfer/fillet capability and diagnostic matrix inventory (code + fixtures + explicit unsupported map).
+- **EDGE-X2**: Concave planar chamfer additive patch lab (simplest constructive edge-sweep proof).
+- **EDGE-X3**: Convex planar single-edge chamfer replacement lab (offset + chamfer face + deterministic local topology rebuild).
+- **EDGE-X4**: Planar-planar constant-radius fillet cylindrical edge-sweep lab.
+- **EDGE-X5**: Three-edge equal-radius convex corner patch audit/lab.
+- **EDGE-V1**: Production-adjacent `AirChamfer` for first bounded admitted case.
+
+Rationale for sequence: starts with currently lower-risk constructive/additive geometry, then moves to replacement-heavy convex semantics.
+
+## 15. Migration checklist for future AirEdgeSweep PRs
+Each future `AirEdgeSweep` PR should include:
+- supported edge and adjacent-face families,
+- convex/concave scope,
+- offset/tangent construction contract,
+- profile construction contract,
+- corner policy,
+- topology replacement/addition plan,
+- resulting analytic surface-family declaration,
+- STEP smoke markers for admitted cases,
+- recognizer parity evidence (candidate/admissible counts and first-delta diagnostics),
+- assertion that no unintended Boolean/subtract fallback was introduced,
+- explicit legacy fallback/authority policy.
+
+## 16. Risks and guardrails
+### Risks
+- Rebuilding rolling-ball complexity under a new name.
+- Scope drift into generic surfacing/NURBS.
+- Regressing existing chamfer behavior while pursuing migration.
+- Corner patch logic becoming unbounded/underdetermined.
+- Continued hidden dependency on face/edge ordering without explicit contract.
+- Underestimating convex replacement complexity vs concave additive cases.
+
+### Guardrails
+- Bounded analytic first scopes only.
+- Lab-first, production-second sequencing.
+- Explicit admissibility and rejection diagnostics.
+- Separate convex vs concave tracks.
+- No generic UV/NURBS expansion.
+- Legacy remains authoritative until parity is proven.
+- No test weakening.
+
+## 17. Non-goals
+- no `AirEdgeSweep` implementation,
+- no production route changes,
+- no change to existing chamfer/fillet behavior,
+- no triangle migration retry,
+- no STEP/exporter changes,
+- no Boolean core changes,
+- no generic surfacing expansion,
+- no NURBS/freeform expansion,
+- no sketch-solver/clipping-engine expansion.
diff --git a/docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md b/docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md
index 0a5b3599..fb8567a2 100644
--- a/docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md
+++ b/docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md
@@ -127,6 +127,8 @@ Until `AirEdgeSweep` exists as a proven contract:
Non-action for this milestone: do **not** implement `AirEdgeSweep` here.
+Follow-up architecture audit reference: `docs/edge-a0-air-edge-sweep-fillet-chamfer-audit.md` (EDGE-A0 / V2-A4).
+
## 9. Implications for prismatic migration roadmap
Roadmap adjustments:
- triangle production migration: blocked by feature-recognition parity.
diff --git a/docs/v2-v5-triangle-prism-profile-extrude-production.md b/docs/v2-v5-triangle-prism-profile-extrude-production.md
index 92b23443..db8e2fec 100644
--- a/docs/v2-v5-triangle-prism-profile-extrude-production.md
+++ b/docs/v2-v5-triangle-prism-profile-extrude-production.md
@@ -65,3 +65,7 @@ The V2-X8.2 forensic ledger audit identifies deterministic legacy-vs-candidate a
V2-A3 formalizes this result as doctrine: triangle remains on legacy production routing because topology contract parity for bounded feature recognition is not yet proven. The line-arc triangle route remains valid as a parallel V2 lane for scoped profile-first contexts, not as a silent replacement.
Reference: `docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md`.
+
+
+Update note (EDGE-A0): triangle migration remains blocked pending adjacency-contract hardening and future constructive edge-surfacing (`AirEdgeSweep`) contract proof.
+