Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Document prismatic coplanar split merge policy

Yuechen Liede09e604a9f
diff --git a/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md b/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
index fe8fa77e..64553070 100644
--- a/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
+++ b/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
@@ -278,7 +278,7 @@ This milestone does not include:
## EDGE-PRISMATIC-V1 status note
-The prismatic section-transition row is now **internal production-adjacent / not routed** for Z-axis two/three-section, line-only, one-outer-loop, no-hole, equal-count identity-correspondence transitions. Rectangle, pentagon, hexagon, asymmetric pentagon, and stable+transition rectangle cases validate the topology formula and STEP smoke through the existing exporter. No production chamfer/fillet behavior, ProfileStack behavior, STEP exporter/importer behavior, Boolean core behavior, AirEdgeSweep behavior, public API, triangle migration, sketch solver, clipping engine, or NURBS/freeform support changed.
+The prismatic section-transition row is now **internal production-adjacent / not routed** for Z-axis two/three-section, line-only, one-outer-loop, no-hole, equal-count identity-correspondence transitions. Rectangle, pentagon, hexagon, asymmetric pentagon, and stable+transition rectangle cases validate the split-preserving topology formula and STEP smoke through the existing exporter. EDGE-PRISMATIC-X4 records split preservation as the current prismatic contract: coplanar section-boundary faces are semantic output by default, not merge candidates inside the emitter. No production chamfer/fillet behavior, ProfileStack behavior, STEP exporter/importer behavior, Boolean core behavior, AirEdgeSweep behavior, public API, triangle migration, sketch solver, clipping engine, or NURBS/freeform support changed.
## EDGE-PRISMATIC-V2 status note
diff --git a/docs/edge-prismatic-v1-section-transition-emitter.md b/docs/edge-prismatic-v1-section-transition-emitter.md
index 1cfb21b5..4fd7aa2f 100644
--- a/docs/edge-prismatic-v1-section-transition-emitter.md
+++ b/docs/edge-prismatic-v1-section-transition-emitter.md
@@ -72,6 +72,7 @@ For admitted requests the emitter:
7. Binds each cap and transition face to a plane surface.
8. Preserves split faces at section boundaries.
9. Does not merge coplanar faces in V1.
+10. Follows EDGE-PRISMATIC-X4 policy: section-boundary faces are semantic interval evidence, and any future coplanar merge must be a separate explicit post-emission mode rather than a silent emitter behavior change.
## 7. Success cases and topology formula
diff --git a/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.md b/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.md
index 762c1fc6..bda69d3a 100644
--- a/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.md
+++ b/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.md
@@ -92,7 +92,7 @@ For the canonical controlled case, the expected and tested topology is:
| coedges | 40 |
| bounds | `[-5,-4,0]..[5,4,6]` |
-The route preserves the `z = 5` split between stable lower side faces and upper transition faces. It does not merge coplanar faces in this milestone.
+The route preserves the `z = 5` split between stable lower side faces and upper transition faces. It does not merge coplanar faces in this milestone. EDGE-PRISMATIC-X4 records this as policy for controlled prismatic chamfer output: split faces are semantic section-stack/transition-interval evidence, and any future merged output must be an explicitly selected compatibility mode with recognizer and diagnostics parity.
## 7. STEP smoke findings
diff --git a/docs/edge-prismatic-x4-coplanar-split-merge-policy-audit.md b/docs/edge-prismatic-x4-coplanar-split-merge-policy-audit.md
new file mode 100644
index 00000000..651373d8
--- /dev/null
+++ b/docs/edge-prismatic-x4-coplanar-split-merge-policy-audit.md
@@ -0,0 +1,193 @@
+# EDGE-PRISMATIC-X4 — Coplanar split/merge policy audit
+
+## 1. Executive summary
+
+The current `PrismaticSectionTransitionEmitter` preserves section-boundary split faces. In a stacked-section body, every adjacent section pair owns its interval and emits its own transition faces, even when an interval is geometrically unchanged from the interval below or above.
+
+Some adjacent faces in those outputs are coplanar and could theoretically be merged into fewer larger faces. That is especially visible in the top-edge chamfer route, where unchanged rectangular sides remain planar across the lower stable prism interval and the upper transition interval.
+
+This audit decides the current policy: **preserve splits by default** because they encode construction intent, section-stack evidence, and transition intervals. Coplanar merging is an optimization and must not be treated as the default emission behavior.
+
+Merging may become a future optional simplification pass, but only when downstream recognizers, diagnostics, route contracts, corpus artifacts, and STEP smoke agree that the simplified topology preserves required semantics.
+
+## 2. Why this audit exists
+
+EDGE-PRISMATIC-X2/V2 expresses the controlled top `+X` horizontal edge chamfer as three Z-stacked sections:
+
+1. a full rectangle at `z0 = 0`;
+2. the same full rectangle at `z1 = height - chamferDistance`;
+3. an inset rectangle at `z2 = height`.
+
+The interval `z0..z1` is a stable lower prism. The interval `z1..z2` is the transition interval that contains the chamfer face on the changed `+X` side. The other sides are unchanged or partly unchanged in XY, so their lower stable side faces and upper interval side faces may lie on the same geometric plane.
+
+Those coplanar faces remain split at `z1` today. That split affects:
+
+- topology counts used by labs and tests;
+- topology summary parity when comparing emitters and routes;
+- feature-recognition and analyzer assumptions about face counts, face ordering, adjacency, and surface families;
+- STEP entity shape and downstream consumer observations;
+- future production claims about what the prismatic lane guarantees.
+
+The decision is therefore semantic, not merely geometric. A valid closed planar BRep with fewer faces is not automatically equivalent to the split-preserving prismatic result.
+
+## 3. Definitions
+
+- **Section-boundary split**: an emitted topology boundary at a source section Z plane, such as `z = height - chamferDistance`, that separates faces belonging to adjacent section intervals.
+- **Stable interval face**: a face emitted for an interval whose corresponding source edge is unchanged between two adjacent sections. In the top-edge chamfer case, the lower prism side faces in `z0..z1` are stable interval faces.
+- **Transition interval face**: a face emitted for the interval where corresponding profile edges are connected between adjacent sections. It may represent a changed side, such as the chamfer face, or an unchanged/coplanar side within the transition interval.
+- **Coplanar adjacent faces**: two faces that share an edge and lie on the same geometric plane within tolerance, but remain separate topological faces.
+- **Semantic face identity**: the meaning attached to a face by construction source, interval, role, diagnostics, lineage, or future PMI/feature recovery, beyond its geometric plane alone.
+- **Topology simplification**: a post-emission operation that reduces topology complexity, such as merging adjacent coplanar faces, while preserving the same geometric bounds.
+- **Recognizer parity**: evidence that downstream recognizers produce equivalent candidate sets, admissibility, and diagnostics after a topology change.
+- **Merge policy**: the route-level decision about whether coplanar adjacent faces are preserved as semantic section output or simplified into merged faces.
+
+## 4. Current emitted topology
+
+### 4.1 Two-section transition
+
+A two-section transition has no internal section boundary. It has only the lower cap, upper cap, and one interval of side transition faces.
+
+For `n` vertices under the current convention, the expected topology is:
+
+- vertices = `2n`;
+- edges = `3n`;
+- faces = `n + 2`;
+- coedges = `6n`.
+
+The count expands as `n` bottom profile edges, `n` top profile edges, `n` transition edges, `2` cap faces, and `n` transition faces. Since there is only one transition interval, there is no internal section-boundary split to merge away.
+
+### 4.2 Three-section stable+transition
+
+A three-section stable+transition stack has an internal section boundary at `z1`. The emitter preserves split faces across intervals:
+
+- the lower stable prism interval emits its own side faces;
+- the upper transition interval emits its own side faces;
+- the shared `z1` boundary remains visible in topology through profile edges and adjacent face separation.
+
+For the EDGE-PRISMATIC-X2/V2 top-edge chamfer row, the split-preserving counts are:
+
+- vertices = `12`;
+- edges = `20`;
+- faces = `10`;
+- lower prism side faces = `4`;
+- transition faces = `4`;
+- chamfer transition faces = `1`;
+- loops = `10`;
+- coedges = `40`.
+
+The four lower prism side faces represent the stable `z0..z1` interval. The four upper interval faces represent the `z1..z2` transition interval. Only the changed `+X` upper interval face is the chamfer face, but unchanged upper interval faces are still distinct from their lower neighbors because they carry transition-interval context and preserve evidence that the route was a three-section construction.
+
+## 5. Arguments for preserving split faces
+
+- **Construction-history intent**: the source model is a section stack, not a minimal plane set. Section boundaries are construction facts.
+- **Transition interval diagnostics**: failures, warnings, or future role classifications can point to the exact stable or transition interval.
+- **Simple section-stack formula**: topology counts scale directly with section count and vertex count: `faces = 2 + ((S - 1) * n)` under the current first-scope convention.
+- **Recognizer stability**: existing tests and analyzers can rely on known split-preserving counts until a separate merge mode is proven.
+- **Future feature/PMI lineage**: split faces provide natural anchors for interval provenance, chamfer role labels, and source-section lineage.
+- **Inspectable invalid/transition boundaries**: a boundary like `z1` remains visible for artifact review, CLI summaries, and differential debugging.
+- **Avoids premature optimization**: no current production requirement demands a minimal-face BRep, and simplifying before parity evidence would risk destroying load-bearing semantics.
+
+## 6. Arguments for future coplanar merge
+
+A future optional merge mode may still be valuable because it could provide:
+
+- simpler topology with fewer faces;
+- a result closer to a hand-authored minimal BRep in simple unchanged-side cases;
+- smaller STEP output when adjacent planar faces collapse into fewer `ADVANCED_FACE` entities;
+- compatibility with downstream consumers that prefer minimal planar patches;
+- reduced face-count surprise for users who expect a rectangular side to be one face when no visible geometric break exists.
+
+These benefits are real, but they are optimization benefits. They do not override the current semantic contract.
+
+## 7. Risks of merging too early
+
+Merging coplanar prismatic faces before the ecosystem agrees on policy risks:
+
+- loss of section-boundary evidence;
+- feature-recognition divergence when candidate counts, adjacency, or seam ordering changes;
+- face ID/order churn in tests, CLI artifacts, analyzers, and downstream references;
+- mismatch with the prismatic corpus and topology summaries built around split-preserving counts;
+- accidental conflation of stable and transition intervals;
+- harder diagnostics when a transition interval fails or when a changed edge must be isolated;
+- replay and differential instability if equivalent geometry alternates between split and merged topology depending on tolerance or route detail.
+
+This ties directly to the V2-A3 doctrine: **geometry parity is not feature parity**, and **STEP parity is not recognizer parity**. A merged body may have the same bounds, planes, and STEP smoke markers while still being a different feature-recognition object.
+
+## 8. Recommended policy
+
+The recommended policy is:
+
+1. First-scope `PrismaticSectionTransitionEmitter` preserves split faces by default.
+2. Split faces are semantic output, not incidental artifacts.
+3. No coplanar merge occurs inside the emitter.
+4. Any future merge must be:
+ - explicit;
+ - optional;
+ - post-emission;
+ - diagnostics-preserving;
+ - feature-recognition parity tested.
+5. Merged output must be a separate route/result mode, for example `PreserveSectionSplits` versus `MergeCoplanarFaces`.
+6. Production routes should default to preserving splits until enough parity evidence exists to justify a merged mode for a bounded route.
+
+In short: **coplanar merging is optimization; section-boundary preservation is intent**. Do not optimize away intent until downstream recognizers, diagnostics, and route contracts agree.
+
+## 9. Future merge-admissibility gates
+
+A future merge mode must pass all of these gates before it can be trusted for a bounded route:
+
+- same geometric bounds and surface-family expectations as split-preserving output;
+- STEP smoke for both split and merged output without exporter/importer changes unless separately scoped;
+- stable merged topology summary with documented formulas and fixtures;
+- feature-recognition parity for affected chamfer, fillet, corner, primitive, profile-stack, semantic recovery, and analyzer consumers;
+- diagnostics and lineage preservation, including a way to recover original section/interval provenance after merging;
+- CLI/artifact corpus comparison that records split and merged outputs as distinct modes;
+- explicit user or route policy selecting merge behavior;
+- no change to default split-preserving behavior.
+
+## 10. Test implications
+
+Current tests should continue asserting split counts for prismatic rows. In particular, the three-section top-edge chamfer and stable+transition rows should remain at the documented split-preserving counts unless an explicitly named merged-mode fixture is added later.
+
+Future tests for a merge mode should:
+
+- assert both split and merged counts;
+- verify STEP smoke for both modes;
+- verify recognition parity, not only topology summary parity;
+- verify diagnostics preserve original section lineage and transition interval roles;
+- prove that default routes still emit split-preserving topology unless merge mode is explicitly requested.
+
+## 11. Documentation/compatibility implications
+
+- EDGE-A1 should treat split preservation as the current prismatic contract for prismatic rows.
+- EDGE-PRISMATIC-X1/X2/X3/V1/V2 docs should state that split faces are intentional.
+- Any downstream route consuming prismatic section transitions must not silently merge coplanar faces.
+- Any future merged output should be named as a separate compatibility surface, not a quiet replacement for existing prismatic output.
+
+## 12. Recommended next milestones
+
+Recommended next milestones are:
+
+1. **EDGE-PRISMATIC-X5**: prismatic artifact/corpus route using split-preserving output.
+2. **EDGE-PRISMATIC-X6**: optional coplanar merge proof lab, only after the split-preserving corpus exists.
+3. **EDGE-PRISMATIC-V3**: controlled Firmament/CLI route if the split-preserving corpus is stable.
+4. Or return to chamfer/fillet work after X4 if the prismatic audit trail is sufficient for current planning.
+
+## 13. Non-goals
+
+This milestone does not include:
+
+- implementation;
+- a merge pass;
+- emitter behavior changes;
+- production routing;
+- STEP exporter/importer changes;
+- Boolean core changes;
+- AirEdgeSweep changes;
+- `ProfileStackExtrudeExecutor` behavior changes;
+- production chamfer/fillet behavior changes;
+- public API changes;
+- test weakening;
+- face-count changes;
+- geometry implementation;
+- triangle migration retry;
+- sketch solver, clipping engine, NURBS, or freeform support.
diff --git a/docs/frictionlab/edge-prismatic-x1-section-transition-emitter-lab.md b/docs/frictionlab/edge-prismatic-x1-section-transition-emitter-lab.md
index 6dd0ff92..ca9fbbc2 100644
--- a/docs/frictionlab/edge-prismatic-x1-section-transition-emitter-lab.md
+++ b/docs/frictionlab/edge-prismatic-x1-section-transition-emitter-lab.md
@@ -149,7 +149,7 @@ The three-section stable + transition rectangle case has:
- loops `10`;
- coedges `40`.
-These counts are asserted in `PrismaticSectionTransitionEmitterLabTests` and document the intended split-face contract.
+These counts are asserted in `PrismaticSectionTransitionEmitterLabTests` and document the intended split-face contract. EDGE-PRISMATIC-X4 now defines that contract as the current policy: section-boundary split faces are semantic prismatic output and must be preserved by default; coplanar merging is only a future explicit post-emission simplification mode.
## 7. STEP smoke findings
diff --git a/docs/frictionlab/edge-prismatic-x2-top-edge-chamfer-through-prismatic-emitter-lab.md b/docs/frictionlab/edge-prismatic-x2-top-edge-chamfer-through-prismatic-emitter-lab.md
index de8cc8ac..9821ece6 100644
--- a/docs/frictionlab/edge-prismatic-x2-top-edge-chamfer-through-prismatic-emitter-lab.md
+++ b/docs/frictionlab/edge-prismatic-x2-top-edge-chamfer-through-prismatic-emitter-lab.md
@@ -77,7 +77,7 @@ The canonical X2 row succeeds through the prismatic emitter and preserves the ED
- coedges: `40`
- bounds: `[-5,-4,0]..[5,4,6]`
-The lower vertical side faces and upper transition faces remain split at `z=5`, including where adjacent portions are coplanar. This is intentional because it preserves the section-stack witness and transition-interval evidence. X2 does not merge coplanar faces.
+The lower vertical side faces and upper transition faces remain split at `z=5`, including where adjacent portions are coplanar. This is intentional because it preserves the section-stack witness and transition-interval evidence. X2 does not merge coplanar faces. EDGE-PRISMATIC-X4 records this as semantic output policy: these split faces are not incidental artifacts and any future coplanar merge must be an explicit optional post-emission mode with diagnostics and recognizer parity evidence.
## 7. STEP smoke findings
diff --git a/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.md b/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.md
index bdff5bb1..496de579 100644
--- a/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.md
+++ b/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.md
@@ -82,6 +82,8 @@ For every successful two-section line-only transition with `n` vertices:
The test suite asserts this formula for rectangle, pentagon, hexagon, and asymmetric polygon rows and records `edge-prismatic-x3-topology-formula-validated` for successful rows.
+For `S` sections, the current emitter's documented convention remains split-preserving. EDGE-PRISMATIC-X4 clarifies that generic transition counts intentionally preserve section-boundary faces; adjacent coplanar faces are not merged by default.
+
For `S` sections, the current emitter's documented convention remains:
- vertices: `S * n`;