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.csindex 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.csnew file mode 100644index 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.csindex 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.csindex 0ff822a6..5ee167b4 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs@@ -276,7 +276,26 @@ internal static class FirmamentPrimitiveExecutortolerance);}- 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.csnew file mode 100644index 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.mdnew file mode 100644index 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).