Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
docs: add AIR-A0 kickoff and architecture probe report
Yuechen Li91f72c52b98a
diff --git a/docs/air-a0-architecture-probe-report.md b/docs/air-a0-architecture-probe-report.mdnew file mode 100644index 00000000..0f96e52f--- /dev/null+++ b/docs/air-a0-architecture-probe-report.md@@ -0,0 +1,230 @@+# AIR-A0 architecture probe report++## 1) Executive summary++Outcome: **Success (design/audit milestone)**.++Evidence indicates Aetheris already contains multiple AIR-like lanes (especially hole-family semantic plans + profile-stack execution + surface-feature descriptor planning), while bounded Boolean infrastructure remains necessary but should be treated as fallback for irreducible interactions.++Best immediate next lab: **AIR-X1 minimal Profile IR + AirProfileStackExtrude spec extraction from existing hole-family plans**, because it has highest leverage, strongest existing evidence, and lowest architecture risk.++## 2) Source code/docs inspected++### Core code inspected+- Semantic recovery/materializer:+ - `FrepMaterializerPolicyCatalog`+ - `HoleRecoveryPolicy`+ - `HoleRecoveryPlan` / `HoleProfileSegment`+ - `HoleRecoveryExecutor`+ - `ProfileStackExtrudeSpec` / `ProfileStackLayer`+ - `ProfileStackExtrudeExecutor`+ - `ProfileStackExtrudePlanAdapter`+ - `FrepSemanticRecoveryRematerializer`+- CIR/FRep:+ - `CirNode` / `CirNodes`+ - primitive nodes: box, cylinder, cone, sphere, torus+ - boolean nodes: union/subtract/intersect+ - `CirTape` and inline `CirTapeLowerer`+ - `FirmamentCirLowerer`+- BRep:+ - `BrepPrimitives` (`CreateBox/CreateCylinder/CreateCone/CreateSphere/CreateTorus` and extrusion helper usage)+ - `BrepBoolean`+ - `BrepBooleanBoxCylinderHoleBuilder`+ - `SafeBooleanComposition` / `BrepBooleanSafeComposition`+- STEP:+ - `Step242Exporter`+- Surface-feature lane:+ - `SurfaceFeatureDescriptors`+ - `SurfaceFeaturePlanningBridge`+ - `SurfaceFeatureDryRunGenerator`+ - `SurfaceFeatureEvidenceGenerator`++### Docs inspected+- `docs/frictionlab/cir-sweep-x0-profile-stack-extrude-lab.md`+- `docs/cir-sweep-v1-profile-stack-extrude-executor.md`+- `docs/cir-sweep-v2-cylindrical-hole-profile-stack-migration.md`+- `docs/cir-recovery-v19-hole-family-capability-manifest.md`+- `docs/brep-boolean-stack-a0-stepped-root-cause.md`+- `docs/brep-boolean-stack-a1-nlevel-coaxial-validator.md`+- `docs/brep-boolean-stack-a2-stepped-downstream-blocker.md`+- `docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.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`+- `docs/step-void-a0-brep-with-voids-audit.md`+- `docs/step-void-a1-brep-with-voids-import.md`+- `docs/step-void-a2-solid-root-export-planner.md`+- `docs/firmament-semantic-topology-naming.md` (SEM-A0)+- `docs/groove-a0-bounded-revolved-groove-audit.md`++## 3) AIR concept definition++**AIR — Atomic Intermediate Representation** is the bounded constructive intent layer between CIR/FRep semantics and BRep topology emission.++ABC model:+- **AIR** = atomic constructive intent.+- **BRep** = boundary topology.+- **CIR** = evaluable constructive/field representation.++Phrase contract:+- AIR describes construction.+- BRep describes boundary.+- CIR describes volume/evaluation.++AIR is additive architecture; it does not replace CIR or BRep.++## 4) Current code inventory++### 4.1 Already AIR-like+- `HoleRecoveryPlan` + `HoleProfileSegment` explicit intent schema (host/axis/depth/entry/exit/profile stack/placement).+- `HoleRecoveryPolicy` variant admissibility + scoring via `JudgmentEngine`.+- `ProfileStackExtrudeSpec/ProfileStackLayer/ProfileStackExtrudeExecutor` explicit stack construction lane.+- `ProfileStackExtrudePlanAdapter` intent-preserving conversion from semantic plan.+- `FrepSemanticRecoveryRematerializer` planner->policy->plan->executor orchestration.+- Surface-feature descriptor/planning/dry-run/evidence pipeline (non-emitting but intent-atomic).++### 4.2 Partially AIR-like+- `BrepPrimitives`: some direct primitive topology constructors (not intent-atomic), but also uses extrude-style helpers for prism-like families.+- `BrepBooleanBoxCylinderHoleBuilder.BuildComposition`: composition from recognized analytic intent; still under Boolean namespace.+- `Step242Exporter` root planner: strong policy architecture, but post-BRep/export layer.++### 4.3 Boolean-first but could become AIR-fronted+- Box-cylinder/cone/safe subtract families where intent is known as holes/stacks before 3D boolean operations.+- Some primitive factories (cylinder/cone/sphere/torus) can be represented as revolve/extrude atoms with bounded emitters.+- Groove/surface-feature families currently deferred/planning-only could become explicit `AirSurfaceFeature` materialization lanes.++### 4.4 Not AIR / fallback territory+- General unsupported boolean cases and non-sweepable interactions in `BrepBoolean` execution classes.+- Arbitrary mixed interactions that violate bounded coaxial/profile constraints.+- Freeform/high-order surfacing not expressed by bounded descriptors.++## 5) Primitive-as-sweep/revolve analysis++| Primitive | Extrude/Revolve/Ruled form? | Current impl trend | What needed for AIR emitter |+|---|---|---|---|+| Box | Yes (rect profile extrude) | direct topology constructor | `AirExtrude` with rectangle profile canonicalization + exact planar/cyl side policies |+| Cylinder | Yes (circle extrude or line revolve) | direct constructor; also reused in hole tools | choose canonical `AirRevolve` or `AirExtrude` form + seam/cap emission policy |+| Cone/Frustum | Yes (revolve of line segment) + ruled form | constructor + conical tool paths | `AirRevolve` + `AirRuledTransition` bounded contracts and radius-order guards |+| Sphere | Yes (semicircle revolve) | direct constructor | `AirRevolve` bounded to full/partial sphere with seam/pole policy |+| Torus | Yes (circle revolve around axis) | direct constructor, generic torus boolean often unsupported in feature lanes | constrained `AirRevolve` torus contract + explicit fallback for unsupported interactions |++Observation: all canonical primitives are representable via sweep/revolve/ruled atomics; the key work is deterministic emitter policy, not representability.++## 6) Candidate AIR node set++Recommended A0 names:++- `AirExtrude`+- `AirProfileStackExtrude`+- `AirRevolve`+- `AirRuledTransition`+- `AirEdgeSweep`+- `AirSurfaceFeature`+- `AirBooleanFallback`++Justification:+- Prefix groups by layer and distinguishes from CIR/BRep nodes.+- Matches existing evidence lanes (profile stack, surface-feature planning).+- Preserves explicit fallback semantics rather than implicit boolean defaulting.++## 7) Feature-to-AIR mapping table++| Feature family | Primary AIR atom | Notes |+|---|---|---|+| through-hole | `AirProfileStackExtrude` | already close to V2 cylindrical stack route |+| blind-hole | `AirProfileStackExtrude` | needs bounded blind stack/entry handling |+| counterbore | `AirProfileStackExtrude` | explicit layered cylindrical spans |+| countersink | `AirProfileStackExtrude` or `AirRevolve` | conical entry + cylindrical continuation |+| chamfered-entry | `AirProfileStackExtrude` or `AirRuledTransition` | bounded chamfer cone semantics |+| stepped-hole | `AirProfileStackExtrude` | strongest existing AIR-like evidence |+| fillet | `AirSurfaceFeature` (deferred) | bounded host/path/profile contracts required |+| chamfer | `AirSurfaceFeature` / `AirRuledTransition` | deterministic edge/face constraints needed |+| groove/ridge | `AirSurfaceFeature` | aligns with A0-A4 lane |+| shell | `AirBooleanFallback` (initially) | topology mutation-heavy; keep fallback first |+| emboss/deboss | `AirSurfaceFeature` | descriptor-first path |+| thread/deferred | `AirSurfaceFeature` or deferred | maintain deferred/forge policy initially |+| slot/keyway | `AirExtrude` / `AirEdgeSweep` | depends on host/path boundedness |+| lattices | fallback/deferred | outside first bounded AIR scope |+| torus-like features | `AirRevolve` / `AirSurfaceFeature` | bounded torus contracts only |++## 8) Boolean fallback boundary++Boolean remains necessary for:+- cross-axis holes and oblique intersections,+- unrelated solid composition/assembly-like boolean composition,+- non-sweepable interactions,+- multi-feature interference not representable as one bounded profile stack,+- cases where admissibility checks fail for AIR atoms.++Policy: boolean is explicit fallback atom (`AirBooleanFallback`) rather than hidden default foundation.++## 9) No-NURBS / ruled-transition policy++- AIR initial scope is bounded analytic.+- No arbitrary NURBS loft primitive in AIR-A0/AIR-X1.+- Ruled transitions allowed only with deterministic bounded contracts.+- Generic loft/freeform remains out-of-scope until explicit constrained design exists.++## 10) Risks and guardrails++### Risks+1. Over-broad AIR scope could recreate a sketch kernel prematurely.+2. Conflating AIR with BRep may erase intent diagnostics.+3. Boolean fallback might regress if AIR admissibility is too aggressive.+4. Surface-feature lane may overclaim exactness before emitters exist.++### Guardrails+1. Keep AIR atoms bounded + policy-scored via JudgmentEngine.+2. Require explicit admissibility/rejection diagnostics per atom.+3. Preserve existing Boolean and STEP behavior unchanged while probing.+4. Preserve SEM-A0 identity boundaries (no generated topology naming expansion).++## 11) Recommended AIR project ladder++1. **AIR-X1**: minimal Profile IR + `AirProfileStackExtrude` extraction from current hole-family plans.+2. **AIR-X2**: primitive-as-AIR emitters audit/prototype for box/cylinder/cone/sphere/torus.+3. **AIR-X3**: ruled-transition bounded feasibility (frustum/adapter family).+4. **AIR-X4**: surface-feature AIR lane mapping from existing A0-A4 descriptor/evidence pipeline.+5. **AIR-V1**: orchestrated AIR planner with explicit BooleanFallback and no public API changes.++## 12) Recommended immediate next milestone++**Recommended next milestone: AIR-X1**.++Why AIR-X1 first:+- strongest present evidence (`HoleRecoveryPlan` + profile-stack executor already active),+- lowest risk (bounded cylindrical families, existing tests/docs),+- direct value (formalizes first AIR atom without touching public behavior),+- prepares AIR-X2/X3 by defining profile primitives and admissibility contracts.++## 13) Confidence ratings++| Topic | Confidence | Evidence quality |+|---|---|---|+| AIR-like status of hole-family/profile-stack lane | High | direct code + test/documentation continuity |+| Primitive representability as extrude/revolve/ruled | High | geometric equivalence + current helper patterns |+| SurfaceFeature as future AIR lane | Medium-High | strong planning/evidence docs, emission still deferred |+| Boolean fallback boundary recommendations | High | BREP-BOOLEAN-STACK + bounded boolean diagnostics |+| Minimal Profile IR proposal | Medium | architectural inference from current bounded schemas |++## Required diagrams++### Pipeline diagram++```text+Firmament/CIR/FRep+ -> Semantic Recovery+ -> AIR+ -> BRep+ -> STEP+```++### ABC list++```text+AIR = atomic constructive intent+BRep = boundary topology+CIR = evaluable constructive/field representation+```diff --git a/docs/air-a0-atomic-intermediate-representation-kickoff.md b/docs/air-a0-atomic-intermediate-representation-kickoff.mdnew file mode 100644index 00000000..8b506192--- /dev/null+++ b/docs/air-a0-atomic-intermediate-representation-kickoff.md@@ -0,0 +1,137 @@+# AIR-A0 — Atomic Intermediate Representation kickoff++## 1) Purpose++**AIR = Atomic Intermediate Representation.**++AIR is the proposed constructive intent layer between CIR/FRep semantic recovery and BRep emission:++```text+Firmament / CIR / FRep+ -> semantic recovery+ -> AIR+ -> BRep+ -> STEP+```++AIR exists because many exact CAD feature families in current Aetheris are already naturally expressed as sweeps/profile stacks/surface features, while 3D boolean subtraction is often being used as a late-stage reconstruction mechanism. For admissible families, AIR should preserve intent explicitly before topology emission.++## 2) ABC model++### AIR (Atomic Intermediate Representation)+AIR captures **atomic constructive intent**: bounded operations such as extrude/revolve/profile-stack/surface-feature-style construction, including explicit admissibility and fallback markers.++### BRep (Boundary representation)+BRep captures **boundary topology and geometry bindings** (faces/edges/loops/coedges/curves/surfaces), i.e., what the solid boundary is after construction decisions have been made.++### CIR (Constructive/field IR)+CIR captures **evaluable constructive/field semantics** (node/tape evaluation, CSG-style combinations, transforms), i.e., a volume/evaluation representation useful for semantic reasoning and replay.++> AIR describes construction.+> BRep describes boundary.+> CIR describes volume/evaluation.++AIR does not replace CIR or BRep; it fills the missing intent-preserving constructive lane between them.++## 3) Why Boolean is fallback, not foundation++A0 hypothesis:++1. **3D boolean subtraction discovers topology after the fact.** It is often robust only within bounded families and can become brittle with stack depth/interference interactions.+2. **For sweep/profile-stack features, topology is known pre-emission.** Layered intent can be declared explicitly (z-spans, radii, entry side, continuity) before topology construction.+3. **2D/profile-driven construction is generally cheaper/more deterministic** than full 3D intersection-heavy routes for admissible families.+4. **Boolean remains necessary** for irreducible interactions (cross-axis intersections, unrelated solids, multi-feature interference outside one atomic lane).++Therefore AIR should be sweep-first/surface-feature-first, with Boolean retained as an explicit fallback/escape hatch.++## 4) AIR candidate atoms (A0)++### Extrude+- Represents: 2D closed profile extruded along an axis/frame.+- Examples: box-like prisms, polygonal prisms, straight-slot prisms.+- Expected analytic surfaces: planar caps + ruled/planar side faces (and circular/arc-derived cylindrical faces when profile contains arcs).+- Should not handle: arbitrary self-intersecting profiles, unconstrained profile-boolean kernels, freeform loft substitutions.++### ProfileStackExtrude+- Represents: ordered z-layers/intervals with profile/radius transitions across depth.+- Examples: through-hole, stepped-hole, bounded counterbore-like stacks.+- Expected analytic surfaces: cylindrical walls, planar annular transitions, bounded conical/chamfer transitions if explicitly admitted.+- Should not handle: arbitrary non-contiguous stacks, unconstrained cross-axis interference, implicit placement inference.++### Revolve+- Represents: profile revolved around an axis over bounded angle/range.+- Examples: cylinders, spheres (half-profile revolve), torus-like sections (bounded policy), rotational grooves.+- Expected analytic surfaces: cylindrical, conical, spherical, toroidal families; circular trims.+- Should not handle: arbitrary swept freeform blends or unconstrained generalized loft behavior.++### RuledTransition+- Represents: deterministic ruled transition between bounded profile sections.+- Examples: frustum/cone-like adapters, bounded taper transitions.+- Expected analytic surfaces: planes/cones/cylinders and explicitly bounded ruled surfaces.+- Should not handle: generic NURBS loft fallback, high-order continuity claims beyond bounded contract.++### EdgeSweep+- Represents: bounded profile sweep along a declared path/edge contract.+- Examples: keyway-like/slot-like feature sweeps on admissible host/path contracts.+- Expected analytic surfaces: path/profile-induced ruled/cylindrical/toroidal subsets under strict path/profile constraints.+- Should not handle: arbitrary 3D guide-curve networks or unconstrained Frenet-frame sweep complexity in A0.++### SurfaceFeature+- Represents: descriptor-driven surface-local features with explicit planning/evidence and deferred/materialized states.+- Examples: planar groove/ridge families, emboss/deboss-like bounded features.+- Expected analytic surfaces: host retained patches + bounded groove/profile patches with explicit trim expectations.+- Should not handle: generic torus boolean, broad freeform surfacing, topology naming generation.++### BooleanFallback+- Represents: explicit AIR escape hatch where atomic constructive intent is insufficient.+- Examples: cross-axis interacting voids, unrelated solid composition, multi-feature interference.+- Expected analytic surfaces: whatever bounded Boolean families can support.+- Should not handle: being treated as default primary primitive for sweepable/structured families.++## 5) Relationship to current code++- Current `HoleRecoveryPolicy` already decompiles CIR boolean shapes into explicit intent (`HoleRecoveryPlan`, `HoleProfileSegment`, placement metadata).+- `ProfileStackExtrudeSpec/ProfileStackLayer/ProfileStackExtrudeExecutor` are already AIR-like nucleus behavior for stacked cylindrical intent.+- `FrepSemanticRecoveryRematerializer` already routes semantic selection -> executable plan -> BRep output and fallback decisions.+- `BrepPrimitives` includes both direct topology constructors and sweep-like helpers (`BrepExtrude`, revolve helpers in bounded feature lanes), suggesting future primitive wrappers can thinly map to AIR emitters.+- `BrepBoolean` + safe composition family remain critical fallback and bounded composition mechanisms.+- Surface-feature A0-A4 already define a non-emitting descriptor/planning/evidence lane strongly aligned with a future `SurfaceFeature` AIR atom.++## 6) No-NURBS boundary policy++A0 boundary:++- AIR remains **bounded analytic** first.+- No generic NURBS/loft fallback as core AIR primitive.+- Ruled transitions are admissible when deterministic/manufacturable and explicitly bounded.+- Arbitrary loft is out of AIR scope unless a later constrained design explicitly defines admissibility, exactness contracts, and deterministic fallback behavior.++## 7) Open architecture questions++1. What minimal profile/sketch model is sufficient for AIR-X1 without importing a full sketch kernel?+2. Which current primitives should be re-expressed as AIR emitters first (box/cylinder/cone/sphere/torus ordering)?+3. Where should AIR admissibility/scoring live (reuse JudgmentEngine policies vs per-atom validators)?+4. How should AIR represent deferred/exactness states for SurfaceFeature lane without conflating with BRep availability?+5. How should BooleanFallback provenance be preserved for diagnostics and future replay?+6. How much transform/path generality is admissible in first EdgeSweep and Revolve labs?+7. What is the smallest viable AIR->BRep emitter interface that preserves diagnostics and STEP-root expectations?++## 8) Pipeline and ABC diagrams++### Pipeline++```text+Firmament/CIR/FRep+ -> Semantic Recovery+ -> AIR (Atomic Intermediate Representation)+ -> BRep+ -> STEP+```++### ABC conceptual triangle/list++```text+[AIR] atomic constructive intent+[BRep] boundary topology + geometry bindings+[CIR] evaluable constructive/field representation+```