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.mdindex 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 notediff --git a/docs/edge-prismatic-v1-section-transition-emitter.md b/docs/edge-prismatic-v1-section-transition-emitter.mdindex 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 formuladiff --git a/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.md b/docs/edge-prismatic-v2-controlled-top-edge-chamfer-route.mdindex 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 findingsdiff --git a/docs/edge-prismatic-x4-coplanar-split-merge-policy-audit.md b/docs/edge-prismatic-x4-coplanar-split-merge-policy-audit.mdnew file mode 100644index 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.mdindex 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 findingsdiff --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.mdindex 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 findingsdiff --git a/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.md b/docs/frictionlab/edge-prismatic-x3-generic-line-profile-transition-lab.mdindex 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`;