Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

docs: add V2-A3 topology contract and parallel lane doctrine

Yuechen Lia77c131d4201
diff --git a/docs/aetheris-v2-sweep-first-architecture.md b/docs/aetheris-v2-sweep-first-architecture.md
index 8e800692..d00d9c1f 100644
--- a/docs/aetheris-v2-sweep-first-architecture.md
+++ b/docs/aetheris-v2-sweep-first-architecture.md
@@ -364,3 +364,8 @@ Roadmap principle: each stage must shrink fallback ambiguity and increase declar
- **Boolean fallback**: explicit, policy-bounded 3D Boolean route used when topology cannot be sufficiently declared in AIR construction space.
- **Declared topology**: topology implied directly by validated constructive intent.
- **Discovered topology**: topology inferred at runtime through intersection/classification/trimming/stitching operations.
+
+## Update note (V2-A3)
+V2 emitters and legacy emitters may intentionally coexist as parallel lanes when legacy adjacency/corner topology is load-bearing for downstream feature recognition. Declared-topology preference remains intact, but production replacement requires full migration parity gates, including recognizer parity, before legacy authority is retired.
+
+Reference: `docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md`.
diff --git a/docs/frictionlab/v2-x8-2-triangle-adjacency-delta-audit.md b/docs/frictionlab/v2-x8-2-triangle-adjacency-delta-audit.md
index 77d1d0c3..6e1d3d62 100644
--- a/docs/frictionlab/v2-x8-2-triangle-adjacency-delta-audit.md
+++ b/docs/frictionlab/v2-x8-2-triangle-adjacency-delta-audit.md
@@ -22,3 +22,8 @@ Keep legacy route; harden emitter ordering/orientation parity before any product
## Non-goals
No production migration, chamfer behavior change, STEP change, Boolean-core change, or hex/slot migration.
+
+## Update note (V2-A3)
+V2-A3 codifies this audit outcome into migration doctrine: geometry/STEP parity is necessary but insufficient when downstream recognizers depend on adjacency/corner contracts. Triangle production remains legacy-authoritative until replacement topology contract parity is demonstrated.
+
+Reference: `docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md`.
diff --git a/docs/v2-a2-prismatic-operation-migration-audit.md b/docs/v2-a2-prismatic-operation-migration-audit.md
index 1518fd35..ac6f366e 100644
--- a/docs/v2-a2-prismatic-operation-migration-audit.md
+++ b/docs/v2-a2-prismatic-operation-migration-audit.md
@@ -215,3 +215,13 @@ V2-X8 lab-only parity probe added for triangle/hex prism baseline-vs-emitter com
## Update note (V2-V5)
V2-V5 attempted to consume V2-X8 triangle evidence for production migration, but reverted after Firmament bounded-chamfer regression exposed a seam-level topology/adjacency parity blocker. Triangle production routing remains unchanged pending blocker resolution.
+
+## Update note (V2-A3)
+Triangle is no longer treated as the first production migration candidate. V2-X8.1/V2-X8.2 evidence classifies triangle production migration as blocked by feature-recognition parity (adjacency/corner contract divergence under bounded chamfer recognition).
+
+Migration order is now interpreted through parallel-lane doctrine:
+- V2 emitters remain preferred for new declared-topology work,
+- legacy routes remain authoritative where topology is load-bearing for downstream recognizers,
+- production replacement requires full parity ladder (including downstream feature-recognition parity), not summary/STEP parity alone.
+
+See: `docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md`.
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
new file mode 100644
index 00000000..0a5b3599
--- /dev/null
+++ b/docs/v2-a3-legacy-topology-contracts-and-parallel-emitter-lanes.md
@@ -0,0 +1,167 @@
+# V2-A3 — Legacy topology contracts and parallel V2 emitter lanes
+
+## 1. Executive summary
+Aetheris V2 emitters are the preferred direction for new declared-topology construction because they make profile admissibility, curve-family constraints, and emission diagnostics explicit at the AIR-to-BRep seam.
+
+However, existing legacy emitters can carry downstream topology contracts that are not captured by simple geometry validity or STEP-valid interchange checks alone. In particular, recognizers that depend on adjacency, corner incidence, or seam ordering may implicitly rely on legacy topology conventions.
+
+Migration must therefore be gated by all observable and semantic consumers, not only by surface-family parity. Parallel emitter lanes are acceptable and in some cases required when a V2 lane is constructive-correct for new work but legacy topology remains load-bearing for existing bounded-feature behavior.
+
+Doctrine:
+- **Geometry parity is not feature parity.**
+- **STEP parity is not recognizer parity.**
+- **Load-bearing topology stays legacy until the replacement contract is proven.**
+
+## 2. Why this doctrine exists
+V2-V5 attempted production migration of triangle prism emission to `LineArcProfileExtrudeEmitter` based on prior representability and summary parity evidence.
+
+That migration was correctly reverted after V2-X8.1 demonstrated bounded chamfer recognition divergence in triangle cases, and V2-X8.2 isolated the first deterministic mismatch as adjacency-structural at loop/coedge seam ordering/orientation.
+
+In short:
+- triangle migration was attempted,
+- topology/STEP summary evidence was insufficient,
+- downstream bounded chamfer recognition depended on legacy adjacency/corner ordering,
+- migration was reverted to preserve production behavior,
+- adjacency-structural delta was captured as the first concrete divergence.
+
+This doctrine formalizes that result as a general migration guardrail rather than a one-off exception.
+
+## 3. Definitions
+- **legacy topology contract**: the de facto and/or explicit topology semantics (ordering, orientation, adjacency, corner incidence, seam convention) emitted by a legacy route and depended upon by downstream behavior.
+- **V2 emitter lane**: an AIR/V2 constructive path that emits topology from resolved profile/sweep intent under bounded admissibility.
+- **parallel emitter lane**: coexistence of legacy and V2 lanes where each has an explicit authority boundary and neither silently replaces the other.
+- **topology summary parity**: parity of high-level body/face/edge/vertex/loop/coedge counts and broad semantic families.
+- **STEP parity**: parity of expected STEP/AP242 markers and surface-family evidence under current exporter behavior.
+- **feature-recognition parity**: parity of downstream recognizer outputs (candidate sets, admissibility, and first divergence diagnostics) for features that consume emitted topology.
+- **adjacency/corner contract**: the local incidence semantics around corners/edges/seams used by bounded recognizers.
+- **load-bearing topology**: topology conventions that materially affect downstream behavior correctness.
+- **migration gate**: required parity layer that must pass before replacing a production route.
+- **fallback/legacy authority**: policy that keeps legacy route authoritative when required parity is not proven.
+
+## 4. Migration parity ladder
+Production migration requires the following ladder, in order:
+
+1. **Construction validity**
+ - body produced for valid bounded inputs,
+ - invalids rejected deterministically,
+ - no forbidden operations introduced for the scoped route.
+
+2. **Topology summary parity**
+ - vertex/edge/face counts,
+ - face family counts,
+ - loop/coedge counts,
+ - extents/bounds parity.
+
+3. **STEP/interchange parity**
+ - expected STEP markers preserved,
+ - no `BREP_WITH_VOIDS` regressions where not expected,
+ - no exporter/importer changes unless explicitly scoped.
+
+4. **Diagnostic/fallback parity**
+ - route diagnostics remain stable where externally observed,
+ - fallback behavior remains preserved where relevant.
+
+5. **Feature-recognition parity**
+ - downstream recognizers yield equivalent admissible candidates,
+ - adjacency/corner/edge incidence semantics match required contracts,
+ - chamfer/fillet/hole/surface-feature recognizers remain green for affected scopes.
+
+A migration is **not production-ready** if it fails any required downstream parity layer for existing consumers.
+
+## 5. Triangle prism case study
+- **Legacy route**: `BrepPrimitives.CreateTriangularPrism(...)`.
+- **Candidate route**: `LineArcProfileExtrudeEmitter` with one outer line loop.
+- **V2-X8 evidence**: triangle is representable by line-profile extrusion; body/summary/STEP signals were promising.
+- **V2-V5 attempt**: production migration attempted then reverted.
+- **V2-X8.1 finding**: feature-recognition mismatch in bounded triangle chamfer/corner scenarios.
+- **V2-X8.2 finding**: first deterministic delta is adjacency-structural at loop/coedge seam, with chamfer admissibility divergence (`legacy=1/1`, `candidate=0/1`).
+
+Final decision:
+- triangle remains legacy for production routing,
+- line-arc triangle remains valid for new and/or parallel profile-first uses,
+- do not retry triangle production migration until adjacency/chamfer contract is resolved or parity is explicitly proven.
+
+## 6. Parallel lane policy
+Parallel lanes are allowed when:
+- V2 emitter behavior is constructive-correct for new declared-topology use,
+- legacy topology remains load-bearing for downstream behavior in existing production paths.
+
+Examples:
+- legacy triangle prism remains authoritative for chamfer-sensitive production route,
+- line-arc profile triangle can be used in lab/new profile-first contexts without legacy chamfer contract obligations,
+- future slot/capsule profile emission may proceed in parallel before replacing legacy faceted slot routes.
+
+Policy requirements:
+- keep lane names and diagnostics explicit,
+- do not silently substitute V2 emitter for legacy route,
+- document authority boundary,
+- preserve fallback behavior,
+- add migration-gate tests before replacement.
+
+## 7. Feature-recognition parity requirements
+For any shape that feeds bounded downstream features, require parity checks for:
+- chamfer/corner recognition,
+- fillet/edge-sweep recognition,
+- surface-feature descriptor recognition,
+- hole/profile-stack recovery,
+- importer/exporter semantic reconstruction where applicable.
+
+For each recognizer family, require:
+- candidate counts,
+- admissible counts,
+- first-divergence diagnostics,
+- edge/face/vertex incidence summaries where needed to isolate local contract deltas.
+
+## 8. Relationship to future AirEdgeSweep
+Triangle/chamfer divergence indicates current chamfer/fillet logic still depends on legacy topology contracts.
+
+Future `AirEdgeSweep` (or equivalent edge-surfacing contract) is the likely architecture for reframing these features as constructive edge-surface operations:
+- chamfer as straight-profile edge sweep / ruled transition,
+- fillet as circular-profile edge sweep,
+- concave cases may be additive/easier in bounded contexts,
+- convex cases require replacement/trim semantics.
+
+Until `AirEdgeSweep` exists as a proven contract:
+- keep load-bearing chamfer-sensitive topology on legacy authority,
+- use V2 emitters in parallel where safe.
+
+Non-action for this milestone: do **not** implement `AirEdgeSweep` here.
+
+## 9. Implications for prismatic migration roadmap
+Roadmap adjustments:
+- triangle production migration: blocked by feature-recognition parity.
+- hex migration: must not proceed on summary parity alone; run feature-recognition parity when hex feeds bounded features.
+- slot/capsule migration: requires explicit topology-contract decision (legacy faceted vs analytic cylindrical-side expectations).
+- rectangle/circle through-hole: already integrated because scoped gates passed.
+- new profile-first operations may use V2 emitters without replacing legacy routes.
+
+## 10. Updated migration gate checklist
+Every migration PR must include:
+- supported shape boundary,
+- old route identified,
+- new route identified,
+- invalid behavior parity,
+- topology summary parity,
+- STEP/interchange parity,
+- diagnostics parity,
+- downstream feature-recognition parity,
+- CLI/example fixture parity (if applicable),
+- fallback/legacy authority policy,
+- docs updated with decision and boundary.
+
+## 11. Non-goals
+This milestone does **not** include:
+- production route changes,
+- chamfer/fillet redesign,
+- `AirEdgeSweep` implementation,
+- STEP exporter/importer changes,
+- Boolean core changes,
+- hex/slot migration,
+- sketch solver/clipping engine/NURBS/freeform expansion.
+
+## 12. Recommended next milestones
+- **V2-A4 / EDGE-A0**: `AirEdgeSweep` fillet/chamfer architecture audit.
+- **V2-X9**: slot/capsule production evaluation as parallel V2 lane (not automatic replacement of legacy faceted slot route).
+- **V2-X8.3**: triangle emitter ordering/adjacency hardening only if triangle migration remains a priority.
+- **V2-V6**: hex migration only after downstream feature-recognition parity scope is defined and passed.
+- **V2-A3.1**: apply migration checklist rigor across existing V2 migration docs/tests where needed.
diff --git a/docs/v2-v5-triangle-prism-profile-extrude-production.md b/docs/v2-v5-triangle-prism-profile-extrude-production.md
index 1dbd3601..92b23443 100644
--- a/docs/v2-v5-triangle-prism-profile-extrude-production.md
+++ b/docs/v2-v5-triangle-prism-profile-extrude-production.md
@@ -60,3 +60,8 @@ A dedicated follow-up lab now probes triangle chamfer adjacency/corner feature-r
## Update note (V2-X8.2)
The V2-X8.2 forensic ledger audit identifies deterministic legacy-vs-candidate adjacency deltas and reinforces the V2-V5 honest stop: keep triangle production on legacy routing until seam parity is restored.
+
+## Update note (V2-A3)
+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`.