Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
docs: add V2-A1 resolved profile2d contract audit
Yuechen Lib7d79383de5a
diff --git a/docs/aetheris-v2-a1-resolved-profile2d-contract.md b/docs/aetheris-v2-a1-resolved-profile2d-contract.mdnew file mode 100644index 00000000..56149dc5--- /dev/null+++ b/docs/aetheris-v2-a1-resolved-profile2d-contract.md@@ -0,0 +1,388 @@+# Aetheris V2-A1 — Resolved Profile2D contract++## 1. Executive summary++`ResolvedProfile2D` is the foundational constructive data primitive for Aetheris V2. It is not a sketch and not a constraint-solving system; it is a validated, explicit 2D region-topology contract that AIR atoms consume deterministically.++This contract formalizes that subtractive/additive constructive intent should be represented in profile space first (loops/regions/containment/interval layering), then lowered to 3D boundary topology emission. In V2 terms: declared profile topology is preferred over runtime-discovered 3D topology whenever admissibility permits.++## 2. Why Profile2D exists++Aetheris V2 needs one common profile contract that multiple AIR constructors can consume:++- `AirExtrude`+- `AirProfileStackExtrude`+- `AirRevolve`+- `AirPathSweep` / `AirPipeSweep` / `AirHelicalSweep`+- `AirRuledTransition`+- future 2D Boolean normalization lanes+- future surface-feature planning/materialization lanes++Current production/lab evidence already contains profile-like structures, but as fragmented per-feature contracts:++- rectangular outer loops (`AirRectangleProfile`)+- centered circular inner loops (`AirCenteredCircleLoop`)+- hole family radial stacks (`HoleProfileSegment`)+- z-ordered interval layers (`AirProfileStackLayer`)+- ruled-transition circle-profile assumptions+- surface-feature descriptors that imply bounded profile regions++V2-A1 extracts this into one architecture-grade contract without changing production behavior.++## 3. Non-goal: sketch constraint solving++Resolved profile work in V2-A1 explicitly excludes sketch-system responsibilities:++- no underconstrained line sets+- no geometric constraint solving (coincident/tangent/dimension)+- no solver history replay+- no interactive editing state+- no implicit intent archaeology from partially defined sketches++Sketch systems may exist above kernel level in the future. The kernel AIR boundary consumes resolved profiles only: validated 2D topology with explicit admissibility and diagnostics.++## 4. Definitions++### `AirCurve2D`++An abstract bounded deterministic 2D curve primitive admissible in kernel profile topology.++### `AirLineSegment2D`++A bounded line segment with finite start/end points in profile-local coordinates.++### `AirCircularArc2D`++A bounded circular arc with explicit center/radius/start/end parameterization and deterministic orientation.++### Optional future bounded deterministic families++Deferred unless existing bounded support is proven with deterministic topology behavior (e.g., specific non-rational polynomial segments). Not part of first production profile contract by default.++### `AirLoop2D`++An ordered closed sequence of bounded curves whose adjacent endpoints match within tolerance. Loop carries deterministic orientation and validation metadata.++### `AirRegion2D`++A containment-classified set of loops describing material and void boundaries in one profile frame.++### `ResolvedProfile2D`++The validated normalized profile payload consumed by AIR atoms. Contains curve/loop/region topology, frame, tolerance provenance, and diagnostics.++### Outer loop++A material boundary loop for an island (first production scope: one outer loop).++### Inner loop / hole loop++A void boundary fully contained by its parent outer loop.++### Island++A material-containing outer loop subtree in region topology.++### Winding/orientation++Deterministic loop orientation convention bound to profile-frame handedness and normal direction.++### Containment tree++Explicit parent/child hierarchy of islands and holes derived from normalized non-overlapping loop containment.++### Profile frame++Local 2D coordinate basis plus associated 3D embedding contract used by AIR atoms during placement/emission.++### Tolerance policy++Numerical tolerances used for endpoint closure, orientation tests, containment classification, and degeneracy rejection.++### Provenance/diagnostics++Structured source lineage plus machine-checkable validation/admissibility diagnostics for determinism and debuggability.++## 5. Minimal V2-A1 admissible curve set++Recommended first admissible set:++- line segments+- circular arcs+- full circles represented explicitly (or as unambiguous closed arc primitive form)++Deferred by default (unless concrete bounded support evidence emerges):++- other bounded deterministic non-rational segment families++Out of scope:++- rational NURBS+- arbitrary freeform curves+- implicit infinite curves (line/ray primitives without bounds)+- self-intersecting segment definitions++Why lines + arcs are sufficient for near-term AIR basis:++- box/plate/rectangular extrusion families+- cylinder and circular-hole families+- counterbore and stepped circular cut intervals+- frustum/cone families via revolve/ruled transition+- ruled circle↔circle transitions now, square/round via bounded correspondence later+- slot/capsule pathways via line+arc loops in later milestones++## 6. Loop contract++Loop invariants for admissibility:++- closed under endpoint matching tolerance+- ordered curve sequence+- no dangling edges+- no zero-length/degenerate edges+- no uncontrolled self-intersections+- deterministic orientation+- explicit semantic role:+ - outer boundary+ - hole boundary+ - island boundary (if multi-island support is enabled)++Expected failure diagnostics:++- `profile-loop-open`+- `profile-loop-endpoint-mismatch`+- `profile-loop-zero-length-segment`+- `profile-loop-self-intersection`+- `profile-loop-ambiguous-orientation`+- `profile-loop-unsupported-curve-type`++## 7. Region contract++Region invariants:++- a region is one or more loops plus deterministic containment classification+- holes must be contained by parent material loop+- holes cannot overlap each other or escape parent boundaries+- containment tree rules must be explicit when nesting is admitted+- winding+containment interpretation must be deterministic++V2-A1 recommendation for first production `ResolvedProfile2D` scope:++- support exactly one outer loop+- support zero or more hole loops++Deferred by default:++- multiple disjoint material islands+- deep alternating island/hole nesting+- arbitrary overlapping-loop normalization++## 8. Boolean normalization boundary++V2 direction includes eventual 2D Boolean normalization, but V2-A1 defines boundary/contract first:++1. already-resolved profiles (`ResolvedProfile2D`)+2. unresolved profile expressions requiring normalization++Future shape (conceptual, not implemented here):++- `AirProfileExpr2D`+ - `Union`+ - `Intersect`+ - `Difference`+ - `Offset`+ - `Normalize() -> ResolvedProfile2D`++Boundary rule:++- AIR atoms should consume `ResolvedProfile2D`, not raw unresolved Boolean expression trees, unless a specific atom explicitly owns normalization.++Compile-time analogy:++- profile-space Boolean normalization = constructive compile-time lowering+- 3D BRep Boolean subtraction = runtime topology discovery fallback++## 9. Profile frames and coordinate contracts++Profile coordinate rule:++- profiles are authored/stored in local 2D frame space+- AIR atoms place them in 3D using axis/path/frame metadata+- world coordinates are not baked into reusable profile payloads except by explicit placement wrappers++Frame contract should include:++- origin+- orthonormal basis vectors+- handedness+- associated normal direction+- orientation conventions (e.g., outer CCW in +normal frame)++This is required to keep consumption deterministic across:++- extrude+- revolve+- ruled transition+- path/pipe sweeps+- helical sweeps++## 10. Atom consumption contracts++### AirExtrude++- consumes one `ResolvedProfile2D`+- outer/hole loops emit cap boundaries and side surfaces+- line edges map to planar ruled side faces+- arc/full-circle edges map to cylindrical side families (bounded by emission support)++### AirProfileStackExtrude++- consumes ordered z-interval layers containing resolved profile semantics+- each layer represents solid interval or cut interval semantics+- inter-layer transitions emit shoulders/caps/annular boundaries under deterministic interval ordering++### AirRevolve++- consumes axis-relative profile curve/region in a known profile frame+- line segments produce planar/cylindrical/conical families as admissible+- circular arcs may map to spherical/toroidal families when explicitly supported+- requires explicit seam/pole policy and diagnostics++### AirPathSweep / AirPipeSweep / AirHelicalSweep++- consumes resolved profile plus analytic path and frame transport policy+- early scope should remain bounded (circular/annular/simple profile classes)+- excludes arbitrary NURBS/freeform sweep behavior++### AirRuledTransition++- consumes two compatible resolved profile boundary parameterizations+- current proven early scope: circle→circle frustum class+- future square↔circle/square↔round lanes require explicit segment correspondence contract++### AirSurfaceOffset++- conceptual relation only in V2-A1+- may consume profile-like regions on host surfaces / offsets later+- high-risk family remains deferred pending bounded admissibility policy++### AirMaskIntersection / future mask algebra++Optional architecture note:++- resolved profiles can serve as explicit masks+- multi-axis allowed-material masks may compose at AIR level via intersection+- no implementation in V2-A1++## 11. Diagnostics contract++Profile diagnostics should be:++- deterministic+- machine-checkable (stable code strings + payload)+- location-bearing where possible (curve index, loop index, region node)+- explicit about failure class++Suggested categories:++- validation failure+- unsupported curve family+- unsupported topology class+- normalization required before atom consumption+- tolerance ambiguity / unstable classification+- admissible profile but current emitter unsupported++## 12. Serialization/test artifact shape++Recommended future deterministic artifact representation (JSON-like or project convention equivalent):++- profile metadata/version+- curve table+- loop table (ordered curve refs + orientation)+- region containment tree+- normalized orientation state+- diagnostics list+- bounds (AABB)+- signed area / per-loop area+- optional stable hash / identity key++V2-A1 does not require implementation of this artifact; it establishes target shape for future labs/tests.++## 13. Relationship to existing code++Existing structures and their mapping pressure toward `ResolvedProfile2D`:++- `AirRectangleProfile`: specialized rectangular outer loop primitive+- `AirCenteredCircleLoop`: specialized centered circular hole loop primitive+- `AirProfileRegion2D`: minimal region contract (rectangle outer + optional inner circle + role)+- `AirProfileStackLayer`: layered z-interval wrapper around region semantics+- `HoleProfileSegment`: axis-relative radial/depth segment stack encoding profile behavior in 1D radial form+- profile-stack specs/adapters/executors: interval/material semantics that anticipate generalized resolved profile regions+- ruled-transition frustum evidence: compatible boundary transition contract already present for circle classes+- surface-feature descriptors/planning bridges: encode region-like bounded feature intent that should align with shared profile contract++Duplication and likely consolidation targets:++- multiple ad hoc profile shapes (`PolylineProfile2D`, AIR rectangle+circle records, hole radial segments) should converge behind one resolved profile contract with adapters+- validation/diagnostic logic should be centralized rather than repeated per lane+- interval/layer semantics should consume shared region topology payloads instead of per-feature special tuples++## 14. Recommended implementation ladder++Post V2-A1 staged plan:++- **V2-X1**: minimal `ResolvedProfile2D` lab (rectangle + circle loops, validation, diagnostics)+- **V2-X2**: circular-profile `AirExtrude` lab (foundation for eventual cylinder-as-extrude pathways)+- **V2-X3**: profile-with-hole extrude lab (square-with-circle-through case)+- **V2-X4**: bounded line/arc 2D Boolean normalization lab+- **V2-X5**: slot/capsule (line+arc) profile extrusion lab+- **V2-X6**: square-to-round ruled transition lab with explicit correspondence rules+- **V2-V1**: production `ResolvedProfile2D` foundation adopted by selected AIR atoms++(Sequence may be renumbered to align with roadmap management, but ordering intent should remain.)++## 15. Risks and guardrails++Primary risks:++- accidental expansion into sketch solver responsibilities+- prematurely supporting complex deep nesting without deterministic containment+- tolerance policy causing nondeterministic region classification+- spline/freeform creep beyond bounded analytic scope+- unresolved profile Boolean expression leakage into emitters+- invalid profiles reaching BRep emission and producing topology garbage++Guardrails:++- resolved profiles only at AIR atom boundaries+- bounded line/arc-first admissibility+- explicit deterministic diagnostics+- lab-first, production-second progression+- no NURBS/freeform in foundational scope+- topology normalization before emission+- negative tests for invalid loops/hole containment/tolerance ambiguity++## 16. Open questions++- Should first production profile contract allow multiple disjoint material islands?+- What containment nesting depth is truly required by near-term AIR features?+- Should full circles be a dedicated primitive or arc + closure metadata form?+- How should tolerance policy be represented (global, per-profile, per-atom, or mixed)?+- At what stage should 2D Boolean normalization be performed in AIR pipelines?+- Should profiles carry provenance labels that inform topology naming downstream?+- How should mask algebra and profile contracts meet at AIR planning/materialization boundaries?+- Where should surface-on-host profile contracts live for emboss/deboss/thicken lanes?++## 17. Glossary++- **resolved profile**: validated explicit 2D region topology contract consumed by AIR atoms.+- **sketch**: authoring/constraint-space construct, not kernel constructive foundation.+- **loop**: ordered closed bounded-curve chain in profile frame.+- **region**: containment-classified set of loops defining material/void.+- **island**: material outer-loop subtree within region containment.+- **hole**: void loop contained by an island.+- **winding**: loop orientation convention under frame handedness/normal.+- **containment tree**: explicit parent/child hierarchy for loops/islands/holes.+- **normalization**: conversion from potentially ambiguous/overlapping expressions to deterministic resolved topology.+- **profile frame**: local coordinate basis and orientation contract for profile placement.+- **admissibility**: bounded capability check that decides if an atom/emitter can consume a profile deterministically.+- **emitter support**: currently implemented geometry/topology lowering capability for admissible profiles.