Skip to content

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.cs
index 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.cs
new file mode 100644
index 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.cs
index 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 NativeGeometryStateTests
Assert.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 file
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index 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 FirmamentPrimitiveExecutor
materializedBody,
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.cs
index 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.md
new file mode 100644
index 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.