Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F1 native geometry state and replay log skeleton

Yuechen Lia6e9b7b2386d
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs
index 2cda9f88..e3db501e 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentValidationExecutionTests.cs
@@ -328,7 +328,14 @@ ops[2]:
[
new FirmamentExecutedPrimitive(0, "base", FirmamentLoweredPrimitiveKind.Box, BuildNonManifoldBody())
],
- ExecutedBooleans: []);
+ ExecutedBooleans: [],
+ NativeGeometryState: new NativeGeometryState(
+ NativeGeometryExecutionMode.BRepActive,
+ NativeGeometryMaterializationAuthority.BRepAuthoritative,
+ BuildNonManifoldBody(),
+ null,
+ new NativeGeometryReplayLog([]),
+ []));
var validationExecution = FirmamentValidationExecutor.Execute(parsedDocument, executionResult);
diff --git a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs
new file mode 100644
index 00000000..1e33e2f0
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs
@@ -0,0 +1,80 @@
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class NativeGeometryStateTests
+{
+ [Fact]
+ public void NativeGeometryState_BoxBasic_IsBRepActive()
+ {
+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/box_basic.firmament"));
+
+ Assert.True(result.Compilation.IsSuccess);
+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;
+ Assert.Equal(NativeGeometryExecutionMode.BRepActive, state.ExecutionMode);
+ Assert.Equal(NativeGeometryMaterializationAuthority.BRepAuthoritative, state.MaterializationAuthority);
+ Assert.NotNull(state.MaterializedBody);
+ Assert.Empty(state.TransitionEvents);
+ }
+
+ [Fact]
+ public void ReplayLog_BoxMinusCylinder_RecordsOps()
+ {
+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/boolean_box_cylinder_hole.firmament"));
+
+ Assert.True(result.Compilation.IsSuccess);
+ var log = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState.ReplayLog;
+
+ Assert.True(log.Operations.Count >= 2);
+ Assert.Contains(log.Operations, op => op.OperationKind.StartsWith("primitive:", StringComparison.Ordinal));
+ Assert.Contains(log.Operations, op => op.OperationKind.StartsWith("boolean:", StringComparison.Ordinal));
+ Assert.Equal(log.Operations.OrderBy(op => op.OpIndex).Select(op => op.OpIndex), log.Operations.Select(op => op.OpIndex));
+ Assert.All(log.Operations, op => Assert.False(string.IsNullOrWhiteSpace(op.FeatureId)));
+ }
+
+ [Fact]
+ public void TransitionDiagnostic_Categories_AreDistinct()
+ {
+ var unsupported = new NativeGeometryTransitionEvent(NativeGeometryExecutionMode.BRepActive, NativeGeometryExecutionMode.CirOnly, "f1", 3, NativeGeometryTransitionReasonCategory.MaterializationUnsupported, "unsupported materializer");
+ var invalid = new NativeGeometryTransitionEvent(NativeGeometryExecutionMode.BRepActive, NativeGeometryExecutionMode.Failed, "f2", 4, NativeGeometryTransitionReasonCategory.InvalidIntent, "invalid selector");
+ var uncertain = new NativeGeometryTransitionEvent(NativeGeometryExecutionMode.BRepActive, NativeGeometryExecutionMode.BRepActive, "f3", 5, NativeGeometryTransitionReasonCategory.AnalyzerUncertainty, "approximate result");
+
+ Assert.NotEqual(unsupported.ReasonCategory, invalid.ReasonCategory);
+ Assert.NotEqual(invalid.ReasonCategory, uncertain.ReasonCategory);
+ Assert.NotEqual(unsupported.ReasonCategory, uncertain.ReasonCategory);
+ }
+
+ [Fact]
+ public void ProductionPath_Unchanged()
+ {
+ var export = FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/box_basic.firmament"))));
+
+ Assert.True(export.IsSuccess);
+ Assert.Equal("base", export.Value.ExportedFeatureId);
+ Assert.NotEmpty(export.Value.StepText);
+ }
+
+ [Fact]
+ public void UnsupportedFutureState_CanBeRepresented()
+ {
+ var cirOnly = new NativeGeometryState(
+ NativeGeometryExecutionMode.CirOnly,
+ NativeGeometryMaterializationAuthority.CirIntentOnly,
+ null,
+ "cir-root:test",
+ new NativeGeometryReplayLog([]),
+ [new NativeGeometryTransitionEvent(
+ NativeGeometryExecutionMode.BRepActive,
+ NativeGeometryExecutionMode.CirOnly,
+ "cut1",
+ 7,
+ NativeGeometryTransitionReasonCategory.MaterializationUnsupported,
+ "future fallback path")]);
+
+ var failed = cirOnly with { ExecutionMode = NativeGeometryExecutionMode.Failed, MaterializationAuthority = NativeGeometryMaterializationAuthority.PendingRematerialization };
+
+ Assert.Equal(NativeGeometryExecutionMode.CirOnly, cirOnly.ExecutionMode);
+ Assert.Equal(NativeGeometryExecutionMode.Failed, failed.ExecutionMode);
+ Assert.Null(cirOnly.MaterializedBody);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
index e18dc361..5780d2c0 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
@@ -6,7 +6,8 @@ namespace Aetheris.Kernel.Firmament.Execution;
public sealed record FirmamentPrimitiveExecutionResult(
IReadOnlyList<FirmamentExecutedPrimitive> ExecutedPrimitives,
- IReadOnlyList<FirmamentExecutedBoolean> ExecutedBooleans);
+ IReadOnlyList<FirmamentExecutedBoolean> ExecutedBooleans,
+ NativeGeometryState NativeGeometryState);
public sealed record FirmamentExecutedPrimitive(
int OpIndex,
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index 0ff822a6..5ee167b4 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -276,7 +276,26 @@ internal static class FirmamentPrimitiveExecutor
tolerance);
}
- return KernelResult<FirmamentPrimitiveExecutionResult>.Success(new FirmamentPrimitiveExecutionResult(executedPrimitives, executedBooleans));
+ var replayLog = BuildReplayLog(loweringPlan);
+ BrepBody? materializedBody = null;
+ if (executedBooleans.Count > 0)
+ {
+ materializedBody = executedBooleans.OrderBy(b => b.OpIndex).Last().Body;
+ }
+ else if (executedPrimitives.Count > 0)
+ {
+ materializedBody = executedPrimitives.OrderBy(p => p.OpIndex).Last().Body;
+ }
+
+ var nativeState = new NativeGeometryState(
+ NativeGeometryExecutionMode.BRepActive,
+ NativeGeometryMaterializationAuthority.BRepAuthoritative,
+ materializedBody,
+ null,
+ replayLog,
+ []);
+
+ return KernelResult<FirmamentPrimitiveExecutionResult>.Success(new FirmamentPrimitiveExecutionResult(executedPrimitives, executedBooleans, nativeState));
}
@@ -301,6 +320,58 @@ internal static class FirmamentPrimitiveExecutor
$"Requested boolean feature '{boolean.FeatureId}' ({boolean.Kind.ToString().ToLowerInvariant()}) could not be executed.",
Source: "firmament");
+
+ private static NativeGeometryReplayLog BuildReplayLog(FirmamentPrimitiveLoweringPlan loweringPlan)
+ {
+ var replayOps = new List<NativeGeometryReplayOperation>(loweringPlan.Primitives.Count + loweringPlan.Booleans.Count);
+
+ replayOps.AddRange(loweringPlan.Primitives
+ .OrderBy(p => p.OpIndex)
+ .Select(p => new NativeGeometryReplayOperation(
+ p.OpIndex,
+ p.FeatureId,
+ $"primitive:{p.Kind.ToString().ToLowerInvariant()}",
+ null,
+ null,
+ null,
+ SummarizePlacement(p.Placement),
+ null)));
+
+ replayOps.AddRange(loweringPlan.Booleans
+ .OrderBy(b => b.OpIndex)
+ .Select(b => new NativeGeometryReplayOperation(
+ b.OpIndex,
+ b.FeatureId,
+ $"boolean:{b.Kind.ToString().ToLowerInvariant()}",
+ b.PrimaryReferenceFeatureId,
+ b.Tool.OpName,
+ b.Tool.RawFields.TryGetValue("id", out var toolId) ? toolId : null,
+ SummarizePlacement(b.Placement),
+ b.Tool.RawValue)));
+
+ return new NativeGeometryReplayLog(replayOps.OrderBy(o => o.OpIndex).ToArray());
+ }
+
+ private static string? SummarizePlacement(FirmamentLoweredPlacement? placement)
+ {
+ if (placement is null)
+ {
+ return null;
+ }
+
+ var anchor = placement.On switch
+ {
+ FirmamentLoweredPlacementOriginAnchor => "origin",
+ FirmamentLoweredPlacementSelectorAnchor selector => selector.Selector,
+ _ => "unknown"
+ };
+
+ var offset = placement.Offset.Count == 3
+ ? $"[{placement.Offset[0]},{placement.Offset[1]},{placement.Offset[2]}]"
+ : "[]";
+
+ return $"on={anchor};offset={offset};semantic={placement.UsesSemanticAnchor}";
+ }
private static bool IsPatternGeneratedFeature(string featureId)
=> featureId.Contains("__lin", StringComparison.Ordinal)
|| featureId.Contains("__cir", StringComparison.Ordinal)
diff --git a/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs b/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs
new file mode 100644
index 00000000..fae9e93a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs
@@ -0,0 +1,54 @@
+using Aetheris.Kernel.Core.Brep;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+public enum NativeGeometryExecutionMode
+{
+ BRepActive,
+ CirOnly,
+ Failed
+}
+
+public enum NativeGeometryMaterializationAuthority
+{
+ BRepAuthoritative,
+ CirIntentOnly,
+ PendingRematerialization
+}
+
+public enum NativeGeometryTransitionReasonCategory
+{
+ MaterializationUnsupported,
+ InvalidIntent,
+ AnalyzerUncertainty,
+ ExplicitFailure
+}
+
+public sealed record NativeGeometryTransitionEvent(
+ NativeGeometryExecutionMode FromMode,
+ NativeGeometryExecutionMode ToMode,
+ string? FeatureId,
+ int? OpIndex,
+ NativeGeometryTransitionReasonCategory ReasonCategory,
+ string Message);
+
+public sealed record NativeGeometryReplayLog(
+ IReadOnlyList<NativeGeometryReplayOperation> Operations);
+
+public sealed record NativeGeometryReplayOperation(
+ int OpIndex,
+ string FeatureId,
+ string OperationKind,
+ string? SourceFeatureId,
+ string? ToolKind,
+ string? ToolId,
+ string? PlacementSummary,
+ string? MetadataReference);
+
+public sealed record NativeGeometryState(
+ NativeGeometryExecutionMode ExecutionMode,
+ NativeGeometryMaterializationAuthority MaterializationAuthority,
+ BrepBody? MaterializedBody,
+ string? CirIntentRootReference,
+ NativeGeometryReplayLog ReplayLog,
+ IReadOnlyList<NativeGeometryTransitionEvent> TransitionEvents);
diff --git a/docs/cir-f1-native-geometry-state.md b/docs/cir-f1-native-geometry-state.md
new file mode 100644
index 00000000..6bdedbd8
--- /dev/null
+++ b/docs/cir-f1-native-geometry-state.md
@@ -0,0 +1,45 @@
+# CIR-F1: native geometry state + replay log skeleton
+
+## What this milestone adds
+
+CIR-F1 introduces internal execution-state scaffolding for the future BRep-first / CIR fall-forward architecture described in CIR-F0, while preserving current runtime behavior.
+
+Added model elements:
+
+- Execution mode: `BRepActive`, `CirOnly`, `Failed`
+- Materialization authority: `BRepAuthoritative`, `CirIntentOnly`, `PendingRematerialization`
+- `NativeGeometryState` envelope attached to primitive execution results
+- `NativeGeometryReplayLog` with normalized per-operation entries
+- `NativeGeometryTransitionEvent` with explicit reason categories
+
+## What is intentionally inactive in CIR-F1
+
+- No production transition to `CirOnly` is performed.
+- No CIR replay execution is performed.
+- No CIR-to-BRep materialization is performed.
+- No change to Firmament public CLI behavior or STEP export semantics.
+
+## Relationship to CIR-F0
+
+CIR-F0 proposed state-machine and replay-first architecture as the first safe step before any runtime fall-forward.
+CIR-F1 implements that recommendation by:
+
+1. defining state/authority/transition diagnostics,
+2. producing deterministic replay log records from existing lowering plans,
+3. proving current successful execution is representable as `BRepActive`.
+
+## Replay log usage (future)
+
+The replay log is intended to become the deterministic source for lazy CIR reconstruction when future milestones enable fall-forward. In this milestone the log is write-only and diagnostic-focused.
+
+## Behavior change statement
+
+This milestone is behavior-preserving:
+
+- existing eager BRep primitive/boolean execution remains authoritative,
+- existing STEP export path remains authoritative,
+- existing success/failure semantics remain unchanged.
+
+## Recommended CIR-F2
+
+CIR-F2 should consume this scaffold to add a bounded CIR mirror + differential harness for a minimal supported subset (without enabling production fall-forward yet).