Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR mirror state sidecar and state-backed diagnostics
Yuechen Li3482494726fc
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.csindex e3db501e..c8d13a28 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs@@ -335,7 +335,8 @@ ops[2]:BuildNonManifoldBody(),null,new NativeGeometryReplayLog([]),- []));+ [],+ new NativeGeometryCirMirrorState(CirMirrorStatus.NotAttempted, null, [])));var validationExecution = FirmamentValidationExecutor.Execute(parsedDocument, executionResult);diff --git a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateDifferentialHelper.cs b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateDifferentialHelper.csnew file mode 100644index 00000000..bec185d8--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateDifferentialHelper.cs@@ -0,0 +1,40 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++internal sealed record StateBackedDifferentialResult(bool Success, Point3D BrepMin, Point3D BrepMax, Point3D CirMin, Point3D CirMax, double BoundsMaxAbsDelta, double? CirEstimatedVolume);++internal static class NativeGeometryStateDifferentialHelper+{+ public static StateBackedDifferentialResult CompareBoundsAndVolumeFromState(NativeGeometryState state)+ {+ Assert.NotNull(state.MaterializedBody);+ Assert.Equal(CirMirrorStatus.Available, state.CirMirror.Status);+ Assert.NotNull(state.CirMirror.Summary);++ var (min, max) = GetBounds(state.MaterializedBody!);+ var cir = state.CirMirror.Summary!;+ var deltas = new[]+ {+ Math.Abs(min.X - cir.Min.X), Math.Abs(min.Y - cir.Min.Y), Math.Abs(min.Z - cir.Min.Z),+ Math.Abs(max.X - cir.Max.X), Math.Abs(max.Y - cir.Max.Y), Math.Abs(max.Z - cir.Max.Z)+ };++ return new StateBackedDifferentialResult(deltas.Max() < 1.0d, min, max, cir.Min, cir.Max, deltas.Max(), cir.EstimatedVolume);+ }++ private static (Point3D Min, Point3D Max) GetBounds(BrepBody body)+ {+ var points = body.Topology.Vertices+ .Select(v => body.TryGetVertexPoint(v.Id, out var p) ? p : (Point3D?)null)+ .Where(p => p is not null)+ .Select(p => p!.Value)+ .ToArray();++ return (+ new Point3D(points.Min(p => p.X), points.Min(p => p.Y), points.Min(p => p.Z)),+ new Point3D(points.Max(p => p.X), points.Max(p => p.Y), points.Max(p => p.Z)));+ }+}diff --git a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.csindex 1e33e2f0..d467d957 100644--- a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs@@ -69,7 +69,8 @@ public sealed class NativeGeometryStateTests"cut1",7,NativeGeometryTransitionReasonCategory.MaterializationUnsupported,- "future fallback path")]);+ "future fallback path")],+ new NativeGeometryCirMirrorState(CirMirrorStatus.NotAttempted, null, []));var failed = cirOnly with { ExecutionMode = NativeGeometryExecutionMode.Failed, MaterializationAuthority = NativeGeometryMaterializationAuthority.PendingRematerialization };@@ -77,4 +78,54 @@ public sealed class NativeGeometryStateTestsAssert.Equal(NativeGeometryExecutionMode.Failed, failed.ExecutionMode);Assert.Null(cirOnly.MaterializedBody);}-}+++ [Fact]+ public void NativeGeometryState_CirMirror_BoxBasic_Available()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/box_basic.firmament"));+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;++ Assert.Equal(NativeGeometryExecutionMode.BRepActive, state.ExecutionMode);+ Assert.Equal(NativeGeometryMaterializationAuthority.BRepAuthoritative, state.MaterializationAuthority);+ Assert.Equal(CirMirrorStatus.Available, state.CirMirror.Status);+ Assert.NotNull(state.CirMirror.Summary);+ Assert.True(state.CirMirror.Summary!.EstimatedVolume > 0d);+ }++ [Fact]+ public void NativeGeometryState_CirMirror_BoxMinusCylinder_Available()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/boolean_box_cylinder_hole.firmament"));+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;++ Assert.True(result.Compilation.IsSuccess);+ Assert.Equal(CirMirrorStatus.Available, state.CirMirror.Status);+ Assert.NotNull(state.CirMirror.Summary);+ }++ [Fact]+ public void NativeGeometryState_CirMirror_Unsupported_DoesNotFailProduction()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/rounded_corner_box_basic.firmament"));+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;++ Assert.True(result.Compilation.IsSuccess);+ Assert.Equal(CirMirrorStatus.Unsupported, state.CirMirror.Status);+ Assert.NotEmpty(state.CirMirror.Diagnostics);+ }+++ [Fact]+ public void StateBackedDifferential_UsesNativeGeometryState()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/box_basic.firmament"));+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;++ var differential = NativeGeometryStateDifferentialHelper.CompareBoundsAndVolumeFromState(state);++ Assert.True(differential.Success);+ Assert.True(differential.CirEstimatedVolume > 0d);+ }++}\ No newline at end of filediff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.csindex 5ee167b4..c14a4dd2 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs@@ -11,6 +11,7 @@ using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Numerics;using Aetheris.Kernel.Core.Results;using Aetheris.Kernel.Core.Topology;+using Aetheris.Kernel.Firmament.Analysis;using Aetheris.Kernel.Firmament.Connectors;using Aetheris.Kernel.Firmament.Lowering;using Aetheris.Kernel.Firmament.Validation;@@ -293,12 +294,49 @@ internal static class FirmamentPrimitiveExecutormaterializedBody,null,replayLog,- []);+ [],+ BuildCirMirrorState(loweringPlan));return KernelResult<FirmamentPrimitiveExecutionResult>.Success(new FirmamentPrimitiveExecutionResult(executedPrimitives, executedBooleans, nativeState));}+++ private static NativeGeometryCirMirrorState BuildCirMirrorState(FirmamentPrimitiveLoweringPlan loweringPlan)+ {+ var lower = FirmamentCirLowerer.Lower(loweringPlan);+ if (!lower.IsSuccess)+ {+ return new NativeGeometryCirMirrorState(+ CirMirrorStatus.Unsupported,+ null,+ lower.Diagnostics.Select(d => new NativeGeometryCirMirrorDiagnostics(d.Message, null, d.Source)).ToArray());+ }++ var analysis = CirNativeAnalysisService.AnalyzeNode(lower.Value.Root, denseResolution: 28);+ if (!analysis.Success || analysis.Bounds is null || analysis.Volume is null)+ {+ var diagnostics = analysis.Diagnostics+ .Select(d => new NativeGeometryCirMirrorDiagnostics(d.Message, d.OpIndex, d.FeatureId))+ .ToList();+ if (!analysis.Success && diagnostics.Count == 0)+ {+ diagnostics.Add(new NativeGeometryCirMirrorDiagnostics("CIR mirror analysis failed.", null, null));+ }++ return new NativeGeometryCirMirrorState(CirMirrorStatus.Failed, null, diagnostics);+ }++ var summary = new NativeGeometryCirMirrorSummary(+ analysis.Bounds.Min,+ analysis.Bounds.Max,+ analysis.Volume.EstimatedVolume,+ analysis.Volume.Approximate,+ analysis.Volume.Resolution);++ return new NativeGeometryCirMirrorState(CirMirrorStatus.Available, summary, []);+ }private static IReadOnlyList<KernelDiagnostic> WithBooleanContext(FirmamentLoweredBoolean boolean, IReadOnlyList<KernelDiagnostic> diagnostics)=> diagnostics.Select(diagnostic =>{diff --git a/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs b/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.csindex fae9e93a..9ff9f1b5 100644--- a/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs+++ b/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Math;namespace Aetheris.Kernel.Firmament.Execution;@@ -45,10 +46,36 @@ public sealed record NativeGeometryReplayOperation(string? PlacementSummary,string? MetadataReference);+public enum CirMirrorStatus+{+ NotAttempted,+ Available,+ Unsupported,+ Failed+}++public sealed record NativeGeometryCirMirrorDiagnostics(+ string Message,+ int? OpIndex,+ string? FeatureId);++public sealed record NativeGeometryCirMirrorSummary(+ Point3D Min,+ Point3D Max,+ double EstimatedVolume,+ bool VolumeApproximate,+ int? DenseResolution);++public sealed record NativeGeometryCirMirrorState(+ CirMirrorStatus Status,+ NativeGeometryCirMirrorSummary? Summary,+ IReadOnlyList<NativeGeometryCirMirrorDiagnostics> Diagnostics);+public sealed record NativeGeometryState(NativeGeometryExecutionMode ExecutionMode,NativeGeometryMaterializationAuthority MaterializationAuthority,BrepBody? MaterializedBody,string? CirIntentRootReference,NativeGeometryReplayLog ReplayLog,- IReadOnlyList<NativeGeometryTransitionEvent> TransitionEvents);+ IReadOnlyList<NativeGeometryTransitionEvent> TransitionEvents,+ NativeGeometryCirMirrorState CirMirror);diff --git a/docs/cir-f2-cir-mirror.md b/docs/cir-f2-cir-mirror.mdnew file mode 100644index 00000000..5e198bfd--- /dev/null+++ b/docs/cir-f2-cir-mirror.md@@ -0,0 +1,56 @@+# CIR-F2: bounded CIR mirror + state-backed differential harness++## Summary++CIR-F2 adds a bounded, non-authoritative CIR mirror to `NativeGeometryState` for models that already succeed in the production BRep-first path.++Production remains unchanged:++- Firmament lowering and eager BRep execution are authoritative.+- STEP export still reads the materialized BRep path.+- CIR mirror failures never fail production success in this milestone.++## Mirror model++`NativeGeometryState` now carries `CirMirror` with:++- `Status`: `NotAttempted`, `Available`, `Unsupported`, `Failed`+- optional summary (bounds + estimated volume)+- diagnostics list++## Construction path++For successful primitive execution, executor attempts mirror construction by:++1. lowering the existing `FirmamentPrimitiveLoweringPlan` through `FirmamentCirLowerer`,+2. running `CirNativeAnalysisService.AnalyzeNode` when lowering succeeds,+3. persisting bounded mirror diagnostics in state.++Replay-log reconstruction is intentionally deferred; this milestone uses existing lowering plan directly to avoid duplicating lowerer behavior.++## Supported vs unsupported behavior++- Supported subset: mirror is `Available` and includes bounded summary diagnostics.+- Unsupported CIR subset (for example rounded-corner box): mirror is `Unsupported` with lowerer diagnostics.+- Analysis-only failure after successful lowering: mirror is `Failed` with analysis diagnostics.++In all three cases, successful BRep execution remains successful and authoritative.++## Differential harness++A state-backed helper compares BRep materialized bounds against mirrored CIR bounds + mirror volume summary by consuming `NativeGeometryState` directly.++This is diagnostic-focused and keeps CIR-side comparison attached to execution state, not a separate ad hoc reconstruction path.++## Relation to fall-forward++This milestone is preparation for future fall-forward work only:++- no `CirOnly` transition enablement,+- no CIR→BRep rematerializer,+- no export contract changes,+- no public CLI behavior change.++## Recommended CIR-F3++Implement the first tightly-bounded runtime fall-forward transition for one proven unsupported-materialization family, gated by explicit state transitions and preserved SEM-A0 provenance guardrails.