Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

docs: add CIR-E0 evaluation runtime design

Yuechen Lic8d7c663a127
diff --git a/docs/cir-e0-evaluation-runtime.md b/docs/cir-e0-evaluation-runtime.md
new file mode 100644
index 00000000..cb1baeea
--- /dev/null
+++ b/docs/cir-e0-evaluation-runtime.md
@@ -0,0 +1,250 @@
+# CIR-E0 evaluation runtime design
+
+Status: **Design milestone only** (no production code changes).
+
+## 1) Current CIR evaluation limitations
+
+Current 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:
+
+- Point evaluation is recursive and recomputes shared work for every sample; no linearized execution form exists today.
+- `CirVolumeEstimator.EstimateVolume` currently performs a dense triple loop and calls `node.Evaluate(p)` per cell center, so all tree recursion overhead appears in hot loops.
+- `CirAnalyzer` only provides point classification plus passthrough volume estimate; there is no region-level classification/early-out.
+- Current boolean composition follows implicit field algebra (`Union=min`, `Subtract=max(left,-right)`, `Intersect=max`), which is semantically useful but not guaranteed to preserve exact signed-distance behavior after composition.
+- Transform evaluation currently inverts transform per call path (`CirTransformNode.Evaluate`), so repeated region queries have no transform cache plan.
+
+Implication: CIR has a semantic kernel, but no dedicated evaluation runtime yet for map/section/volume-heavy analysis paths.
+
+## 2) Proposed tape IR (linear evaluation tape)
+
+### 2.1 Goal
+
+Introduce a **point-evaluation-first** linear tape lowered from CIR tree, with stable instruction indices and optional provenance metadata.
+
+### 2.2 Instruction shape
+
+A minimal instruction record should include:
+
+- `OpCode` (primitive eval, boolean combine, transform, constant load if needed).
+- `DestSlot` (result register index).
+- `InputA`, `InputB` (source slot indices, `-1` when unused).
+- `PayloadIndex` (index into side tables for primitive/transform parameters).
+- `NodeId` / provenance handle (optional but recommended for tracing).
+
+Conceptual form:
+
+```text
+0: EvalBox payload=box0 -> s0
+1: EvalCylinder payload=cyl0 -> s1
+2: Neg s1 -> s2
+3: Max s0,s2 -> s3 // subtract
+return s3
+```
+
+### 2.3 Side tables
+
+Keep instruction payload small by storing structured parameters in side arrays:
+
+- `BoxParams[]`, `CylinderParams[]`, `SphereParams[]`
+- `TransformParams[]` (forward + inverse cached)
+- optional `ConstDouble[]`
+
+### 2.4 Boolean + transform op mapping
+
+- `Union(left,right)` -> `Min`
+- `Subtract(left,right)` -> `Neg` + `Max`
+- `Intersect(left,right)` -> `Max`
+- `Transform(child,T)` -> `ApplyInverseTransform(point,T)` then evaluate child path
+
+For point-only tape, transforms can be represented either as:
+- explicit point-frame instructions (`PushFrame/PopFrame` style), or
+- lower-time baking into primitive-local evaluators.
+
+E0 recommendation: prefer explicit transform instructions for inspectability.
+
+### 2.5 Output and provenance
+
+- Tape has one designated `OutputSlot`.
+- Every instruction should optionally retain source-node provenance (`CirNodeKind`, stable lowering index, and optional user-facing trace label) to support diagnostics.
+
+## 3) Interval / region evaluation model
+
+## 3.1 Interval value type
+
+Define region evaluation as interval over implicit field values:
+
+- `FieldInterval { MinValue, MaxValue, CertaintyFlags }`
+
+Interpretation over region `R`:
+- `MaxValue < 0` => region fully inside.
+- `MinValue > 0` => region fully outside.
+- otherwise straddling zero => mixed/uncertain boundary crossing.
+
+Because CIR composition is implicit-field algebra (not strict SDF post-CSG), this is a **conservative classification signal**, not exact distance semantics.
+
+## 3.2 Primitive intervals over AABB
+
+For each primitive, compute conservative bounds over region AABB:
+
+- Box/sphere/cylinder: use distance-to-shape bound formulas using nearest/farthest-point envelopes from region to primitive frame.
+- Transformed primitives: evaluate interval in local space by transforming region conservatively (AABB in local frame) or using bound propagation with transform norms.
+
+E0 policy: correctness-first conservative intervals (may widen), never optimistic narrowing.
+
+## 3.3 Boolean interval combination
+
+Given `A=[aMin,aMax]`, `B=[bMin,bMax]`:
+
+- Union (`min`): `[min(aMin,bMin), min(aMax,bMax)]`
+- Intersect (`max`): `[max(aMin,bMin), max(aMax,bMax)]`
+- Subtract (`max(a,-b)`): negate B as `[-bMax,-bMin]`, then max-combine.
+
+These are monotone interval lifts of current scalar ops.
+
+## 3.4 Safe pruning rules
+
+Examples:
+
+- Union node: if left interval `leftMax < 0` (definitely inside), union result definitely inside; right child can be skipped for region classification.
+- Intersect node: if either child `childMin > 0` (definitely outside), result definitely outside; other child skip allowed.
+- Subtract node (`max(left,-right)`):
+ - if `leftMin > 0`, result definitely outside regardless of right.
+ - if `rightMax < 0` (region fully inside subtracted tool => `-rightMin > 0` tendency), classification may become outside; combine rule still governs.
+
+Pruning must be gated by conservative interval facts only.
+
+## 4) JudgmentEngine / utility-scored planning model
+
+`JudgmentEngine<TContext>` already matches CIR planning structure: candidate list, admissibility predicates, numeric score, deterministic tie-break, and rejection reasons.
+
+### 4.1 Candidate action families
+
+For region/point workloads, candidate actions can be expressed as:
+
+- `FullTapeInterpreter`
+- `UseCachedInterval`
+- `ClassifyByIntervalOnly`
+- `PruneChildSubtree`
+- `SubdivideRegion`
+- `UseCompiledDelegate`
+- `FallbackRecursiveInterpreter`
+- `UnsupportedUnknown`
+
+### 4.2 Context wrapper needed
+
+Current engine is sufficient as chooser, but CIR needs a small wrapper context (e.g., `CirEvalPlanContext`) containing:
+
+- workload kind (point/map/section/volume)
+- region size/depth budget
+- interval confidence/width metrics
+- cache hit metadata
+- compilation availability/warmth
+- trace sink options
+- determinism policy and tolerance context
+
+### 4.3 Admissibility, score, rejection
+
+Each candidate defines:
+
+- admissibility: hard safety/availability checks (e.g., compiled delegate exists; interval bound valid; depth < max).
+- score: utility estimate (expected cost, expected prune gain, cache locality, required fidelity).
+- rejection: explicit reason string, mirroring existing Boolean routing style.
+
+Deterministic behavior is inherited from `JudgmentEngine`: score, then tie-break priority, then name, then declaration order.
+
+## 5) HFSM / Dominatus analogy: where valid vs not
+
+- **CIR semantic tree**: declarative geometry semantics (not FSM).
+- **Tape**: linear program/dataflow (not FSM).
+- **Execution planner**: bounded decision scheduling (FSM-like only in control policy transitions, e.g., classify/subdivide/fallback states).
+- **Runtime state**: work queue of regions, caches, and diagnostics.
+
+So analogy is useful at planner/orchestration level (deterministic inspectable policy transitions), not as a claim that CIR geometry itself is an FSM.
+
+## 6) .NET execution tiers (recommended path)
+
+A 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.
+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).
+
+Recommendation: prove correctness and diagnostics at A/B before moving to C/D.
+
+## 7) C# iterator assessment
+
+- **Helpful**: planning pipelines, trace event streams, and offline explainability (`IEnumerable<TraceEvent>`).
+- **Risky in hot path**: iterator state machines and allocations can hurt tight voxel/map loops.
+- **Recommendation**:
+ - use iterators for non-hot planning/trace formatting layers,
+ - use arrays/spans/struct-based loops in final tape execution and interval kernels.
+
+## 8) Trace / diagnostic model
+
+Design trace schema with event records tied to provenance:
+
+- `PlanCandidateEvaluated` (name, admissible, score, rejection reason)
+- `PlanSelected`
+- `IntervalComputed` (node/instruction, region id, min/max, method)
+- `PruneApplied` (node, reason, skipped range)
+- `RegionClassified` (full/empty/mixed, supporting interval facts)
+- `SubdivisionChosen` (axis/split, budget/depth rationale)
+- `ExecutionTierChosen` (recursive/tape/compiled and why)
+
+Trace goals:
+- explain *why* pruning occurred,
+- explain region class decision basis,
+- explain planner selection and fallback,
+- align with existing Aetheris style of explicit rejection reasons.
+
+## 9) Analyzer workload integration
+
+How runtime supports workloads:
+
+- **Point containment**: tape interpreter first benefit (many probe points).
+- **Approximate volume**: biggest gain from region classification/pruning + subdivision policy.
+- **Analyze map**: grid scan can reuse per-tile interval culling.
+- **Analyze section**: 2D slice sampling benefits from tape + region short-circuit.
+- **Analyze compare**: repeated evaluations across two kernels benefit from deterministic traces.
+- **Future local/sub-box volume**: directly aligns with region interval planner.
+
+First implementation target recommendation: **approximate volume path**, because it is currently dense and repeatedly evaluates point samples over a bounded region.
+
+## 10) Risks and anti-goals
+
+Key risks:
+
+- **Dual-kernel drift**: recursive and tape evaluators diverge semantically.
+- **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.
+- **Debugging complexity**: planner + caching + tiers obscure errors unless traces are first-class.
+- **Semantic mismatch**: CIR implicit field semantics vs BRep materialized behavior differ in edge conventions.
+- **Tolerance ambiguity**: inconsistent boundary thresholds across point/region classifiers.
+
+Anti-goals for near term:
+- custom native JIT,
+- GPU evaluator,
+- replacing BRep materialization/production Firmament runtime,
+- full speculative optimizer before tape interpreter exists.
+
+## 11) Recommended implementation ladder
+
+- **CIR-E1**: Lower CIR tree to linear tape + point tape interpreter (parity with recursive oracle, trace scaffolding).
+- **CIR-E2**: Interval evaluation over AABB for primitives/booleans/transforms with conservative proofs.
+- **CIR-E3**: Utility-scored region planner using `JudgmentEngine` wrapper context + rejection diagnostics.
+- **CIR-E4**: Integrate planner/tape into CIR analyzer volume/map/section paths behind explicit experimental switch.
+- **CIR-E5**: Add compiled delegate tier from tape (reuse .NET JIT), include deterministic eligibility diagnostics.
+- **CIR-E6**: Region-specialized reduced plans (pruned tape snapshots), optional compile-on-reuse heuristics.
+
+## 12) Recommended immediate next milestone
+
+Immediate next step: **CIR-E1 (tape lowering + tape point interpreter)**.
+
+Definition of done for CIR-E1:
+
+- deterministic lowering from existing `CirNode` tree to linear tape with provenance,
+- 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.