Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
CIR-E1.1: document tape-first runtime framing
Yuechen Licfb2d3937dd6
diff --git a/Aetheris.Kernel.Core/Cir/CirNode.cs b/Aetheris.Kernel.Core/Cir/CirNode.csindex 4d384aee..1c87ad0f 100644--- a/Aetheris.Kernel.Core/Cir/CirNode.cs+++ b/Aetheris.Kernel.Core/Cir/CirNode.cs@@ -29,5 +29,8 @@ public abstract record CirNode(CirNodeKind Kind){public abstract CirBounds Bounds { get; }+ /// <summary>+ /// Semantic/oracle evaluator retained during the CIR-E1 transition while tape-first runtime paths mature.+ /// </summary>public abstract double Evaluate(Point3D point);}diff --git a/Aetheris.Kernel.Core/Cir/CirTape.cs b/Aetheris.Kernel.Core/Cir/CirTape.csindex d2c025c0..f30a6791 100644--- a/Aetheris.Kernel.Core/Cir/CirTape.cs+++ b/Aetheris.Kernel.Core/Cir/CirTape.cs@@ -28,6 +28,10 @@ public readonly record struct CirTapeSpherePayload(double Radius);public readonly record struct CirTapeTransformPayload(Transform3D InverseTransform);public readonly record struct CirTapeTransformEvalPayload(CirNode Child, Transform3D InverseTransform);+/// <summary>+/// Linear MIR/runtime representation for CIR point evaluation.+/// During transition, this is the intended execution form while <see cref="CirNode"/> remains the semantic builder/oracle.+/// </summary>public sealed class CirTape{public CirTape(@@ -142,6 +146,9 @@ public sealed class CirTapepublic static class CirTapeLowerer{+ /// <summary>+ /// Deterministically lowers semantic <see cref="CirNode"/> trees into runtime <see cref="CirTape"/>.+ /// </summary>public static CirTape Lower(CirNode node){ArgumentNullException.ThrowIfNull(node);@@ -204,6 +211,8 @@ public static class CirTapeLowerercase CirTransformNode transform:{var payloadIndex = state.TransformEvalPayloads.Count;+ // CIR-E1 transitional caveat: transform execution keeps a child-node reference and+ // performs recursive child evaluation. E2 is expected to flatten this into pure tape ops.state.TransformEvalPayloads.Add(new CirTapeTransformEvalPayload(transform.Child, transform.Transform.Inverse()));return state.Emit(CirTapeOpCode.EvalTransform, -1, -1, payloadIndex, node.Kind);}diff --git a/docs/cir-e0-evaluation-runtime.md b/docs/cir-e0-evaluation-runtime.mdindex cb1baeea..de337ba8 100644--- a/docs/cir-e0-evaluation-runtime.md+++ b/docs/cir-e0-evaluation-runtime.md@@ -2,6 +2,8 @@Status: **Design milestone only** (no production code changes).+> CIR-E1.1 framing note (May 5, 2026): the linear `CirTape` introduced in E1 is now the intended runtime/MIR direction for serious CIR evaluation paths. `CirNode` remains intentionally in place as a semantic prototype/builder surface, a compatibility lowering source, and an oracle for parity tests while lowering/execution paths are still converging.+## 1) Current CIR evaluation limitationsCurrent CIR is intentionally a semantic tree with `CirNode.Evaluate(point)` dispatch per node kind and recursive composition (`min/max` for boolean ops). This is correct for representation but has runtime limits for dense sampling workloads. Specifically:@@ -165,7 +167,7 @@ So analogy is useful at planner/orchestration level (deterministic inspectable pA staged model:1. **Tier A**: current recursive interpreter (`CirNode.Evaluate`) remains baseline oracle.-2. **Tier B**: tape interpreter (flat arrays/spans, no recursion) for hot point loops and better tracing.+2. **Tier B**: tape interpreter (flat arrays/spans, no recursion for core primitives/booleans) for hot point loops and better tracing.3. **Tier C**: compiled delegate (`Func<Point3D,double>` or struct evaluator) emitted from tape via expression trees or generated methods; rely on .NET JIT.4. **Tier D**: region-specialized reduced tape (after interval pruning), interpreted first, optionally compiled if repeatedly reused.5. **Tier E**: custom/native JIT explicitly deferred (anti-goal for near-term milestones).@@ -216,6 +218,7 @@ First implementation target recommendation: **approximate volume path**, becauseKey risks:- **Dual-kernel drift**: recursive and tape evaluators diverge semantically.+- **Transitional transform recursion**: E1 `EvalTransform` currently stores inverse transform payload + child node and calls recursive child evaluation; keeping this too long can hide hot-path recursion costs and delay true flat-tape execution guarantees.- **Bad interval math**: optimistic bounds cause incorrect pruning.- **Runtime monster**: over-abstraction before B-tier tape value is proven.- **Performance illusions**: synthetic wins without end-to-end analyzer improvement.@@ -248,3 +251,48 @@ Definition of done for CIR-E1:- tape point evaluation parity checked against recursive evaluator on existing CIR fixtures,- no behavioral change required yet in external CLI paths,- first-pass trace output showing instruction execution and selected evaluation tier.++## 13) CIR-E1.1 tape-first runtime framing (transition policy)++### 13.1 What changed in framing++- M0/M1 used tree-first framing to prove semantics quickly (`CirNode` primitives/booleans/transforms).+- After E1, runtime framing is tape-first: `CirTape` is the intended MIR/runtime substrate for evaluation-centric workloads.+- Tree-to-tape lowering remains a first-class adapter during transition and for backward compatibility.++### 13.2 `CirNode` role during transition++`CirNode` is retained deliberately for three roles:++1. convenience semantic builder/prototype surface,+2. compatibility source for deterministic lowering to tape,+3. recursive oracle used by parity/differential tests.++This is not a deprecation notice for `CirNode`; it is an execution-path reframing.++### 13.3 Transform caveat (E1 transitional behavior)++E1 `EvalTransform` is correct but not fully flat:++- lowering emits transform payload (inverse transform) and retains a child `CirNode` reference,+- tape execution evaluates the transformed point by recursively calling `Child.Evaluate(...)`.++Why acceptable for E1:++- preserves correctness and deterministic parity while tape infrastructure lands,+- avoids premature broad refactor of transform/subtree lowering policy.++Why transitional:++- this leaves recursion in the runtime hot path,+- it weakens the “all execution is explicit in tape instructions” goal,+- it complicates future interval/pruning/compiled-delegate tiers that assume flat instruction ownership.++E2 direction:++- flatten transform execution into tape-native instruction flow (or equivalent frame model) so transformed children no longer require recursive node calls at runtime.++### 13.4 Lowering target policy going forward++- New evaluation/runtime lowerers should target tape directly where feasible.+- Tree-lowering adapters remain valid for migration and parity, but are no longer the conceptual end-state runtime.