Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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
+```