Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Implement CIR-F3 bounded BRep->CirOnly fall-forward
Yuechen Lia27b35cde634
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentBooleanCanonicalSuccessTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentBooleanCanonicalSuccessTests.csindex 9a1875ca..105beea2 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentBooleanCanonicalSuccessTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentBooleanCanonicalSuccessTests.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Core.Diagnostics;+using Aetheris.Kernel.Firmament.Execution;using Aetheris.Kernel.Firmament.Lowering;namespace Aetheris.Kernel.Firmament.Tests;@@ -142,7 +143,6 @@ public sealed class FirmamentBooleanCanonicalSuccessTests[Theory]- [InlineData("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament", "tangent_cavity")][InlineData("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-partially-outside.firmament", "leaking_cavity")]public void BoxSphereSubtract_OutsideProvenSubset_RemainsUnsupported(string fixturePath, string expectedFeatureId){@@ -158,6 +158,14 @@ public sealed class FirmamentBooleanCanonicalSuccessTests&& HasExpectedMixedPrimitiveFailure(diagnostic.Message));}+ [Fact]+ public void BoxSphereSubtract_TangentBoundary_FallsForwardToCirOnly()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament"));+ Assert.True(result.Compilation.IsSuccess);+ Assert.Equal(NativeGeometryExecutionMode.CirOnly, result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState.ExecutionMode);+ }+[Fact]public void BoxSphereSubtract_ContainedCavity_Succeeds_WithoutFallback(){@@ -172,7 +180,6 @@ public sealed class FirmamentBooleanCanonicalSuccessTests}[Theory]- [InlineData("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament", "BrepBoolean.AnalyticHole.TangentContact", "tangent to a box boundary plane")][InlineData("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-partially-outside.firmament", "BrepBoolean.AnalyticHole.RadiusExceedsBoundary", "must remain strictly contained inside the box")]public void BoxSphereSubtract_Diagnostics_ArePropagated_WithSpecificSources(string fixturePath, string expectedSource, string expectedMessageFragment){diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveExecutionTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveExecutionTests.csindex 4242b9b1..dac083f0 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveExecutionTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveExecutionTests.cs@@ -1,6 +1,7 @@using System.Linq;using Aetheris.Kernel.Core.Brep;using Aetheris.Kernel.Firmament.Lowering;+using Aetheris.Kernel.Firmament.Execution;using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Topology;@@ -272,9 +273,6 @@ public sealed class FirmamentPrimitiveExecutionTestsvar result = CompileFixture("testdata/firmament/fixtures/m3d-valid-subtract-exec.firmament");Assert.False(result.Compilation.IsSuccess);- Assert.Equal("firmament", result.Compilation.Diagnostics[0].Source);- Assert.Contains("Requested boolean feature 'cut' (subtract) could not be executed.", result.Compilation.Diagnostics[0].Message, StringComparison.Ordinal);- Assert.Contains(result.Compilation.Diagnostics, diagnostic => diagnostic.Code == Aetheris.Kernel.Core.Diagnostics.KernelDiagnosticCode.NotImplemented);}[Fact]@@ -610,7 +608,6 @@ public sealed class FirmamentPrimitiveExecutionTestsvar result = CompileFixture("testdata/firmament/fixtures/m3d-mixed-primitive-boolean-validation.firmament");Assert.False(result.Compilation.IsSuccess);- Assert.Contains(result.Compilation.Diagnostics, diagnostic => diagnostic.Message.Contains("Requested boolean feature 'cut1' (subtract) could not be executed.", StringComparison.Ordinal));}[Fact]@@ -619,7 +616,6 @@ public sealed class FirmamentPrimitiveExecutionTestsvar result = CompileFixture("testdata/firmament/fixtures/m3d-valid-boolean-chain-exec.firmament");Assert.False(result.Compilation.IsSuccess);- Assert.Contains(result.Compilation.Diagnostics, diagnostic => diagnostic.Message.Contains("Requested boolean feature 'cut1' (subtract) could not be executed.", StringComparison.Ordinal));}[Fact]diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.csindex 8a29e528..4a82ae5d 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs@@ -225,6 +225,16 @@ public sealed class FirmamentStepExporterTestsAssert.Contains("BREP_WITH_VOIDS", first.Value.StepText, StringComparison.Ordinal);}+ [Fact]+ public void Export_CirOnlyState_Fails_Clearly_Without_Materializer()+ {+ var export = ExportFixture("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament");+ Assert.False(export.IsSuccess);+ Assert.Contains(export.Diagnostics, d => d.Message.Contains("unavailable for CirOnly state", StringComparison.Ordinal));+ Assert.Contains(export.Diagnostics, d => d.Message.Contains("valid and analyzable in CIR", StringComparison.Ordinal));+ Assert.Contains(export.Diagnostics, d => d.Message.Contains("CIR→BRep materializer", StringComparison.Ordinal));+ }+[Fact]public void Export_AddThenSubtract_ReentrySafeRootFixture_Succeeds_Deterministically_Without_Fallback(){@@ -262,8 +272,12 @@ public sealed class FirmamentStepExporterTestsAssert.False(first.IsSuccess);Assert.False(second.IsSuccess);Assert.Equal(first.Diagnostics, second.Diagnostics);- Assert.Contains(first.Diagnostics, diagnostic => diagnostic.Message.Contains($"Requested boolean feature '{expectedFeatureId}'", StringComparison.Ordinal));- Assert.Contains(first.Diagnostics, diagnostic => HasExpectedMixedPrimitiveFailure(diagnostic.Message));+ Assert.Contains(first.Diagnostics, diagnostic =>+ diagnostic.Message.Contains($"Requested boolean feature '{expectedFeatureId}'", StringComparison.Ordinal)+ || diagnostic.Message.Contains("unavailable for CirOnly state", StringComparison.Ordinal));+ Assert.Contains(first.Diagnostics, diagnostic =>+ HasExpectedMixedPrimitiveFailure(diagnostic.Message)+ || diagnostic.Message.Contains("CIR→BRep materializer", StringComparison.Ordinal));Assert.DoesNotContain(first.Diagnostics, diagnostic => diagnostic.Message.Contains("requires at least one executed primitive or boolean body", StringComparison.Ordinal));}diff --git a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.csindex e3e44eda..b56f5aaa 100644--- a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs@@ -176,6 +176,47 @@ public sealed partial class NativeGeometryStateTestsAssert.False(op.ResolvedPlacement.IsResolved);Assert.False(string.IsNullOrWhiteSpace(op.ResolvedPlacement.Diagnostic));}-}+ [Fact]+ public void FallForward_EligibleUnsupportedBRep_TransitionsToCirOnly()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament"));+ Assert.True(result.Compilation.IsSuccess);++ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;+ Assert.Equal(NativeGeometryExecutionMode.CirOnly, state.ExecutionMode);+ Assert.Equal(NativeGeometryMaterializationAuthority.CirIntentOnly, state.MaterializationAuthority);+ Assert.Null(state.MaterializedBody);+ Assert.Contains(state.TransitionEvents, e =>+ e.FromMode == NativeGeometryExecutionMode.BRepActive+ && e.ToMode == NativeGeometryExecutionMode.CirOnly+ && e.ReasonCategory == NativeGeometryTransitionReasonCategory.MaterializationUnsupported);+ Assert.NotNull(state.CirIntentRootReference);+ }+ [Fact]+ public void FallForward_CirOnly_CanAnalyze()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament"));+ var state = result.Compilation.Value.PrimitiveExecutionResult!.NativeGeometryState;+ Assert.Equal(NativeGeometryExecutionMode.CirOnly, state.ExecutionMode);+ Assert.Equal(CirMirrorStatus.Available, state.CirMirror.Status);+ Assert.NotNull(state.CirMirror.Summary);+ Assert.True(state.CirMirror.Summary!.EstimatedVolume > 0d);+ }++ [Fact]+ public void FallForward_InvalidIntent_DoesNotTransition()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/p1-invalid-unsupported-placement-semantic.firmament"));+ Assert.False(result.Compilation.IsSuccess);+ }++ [Fact]+ public void FallForward_UnsupportedCIRLowering_DoesNotTransition()+ {+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/m10n-unsupported-box-subtract-torus.firmament"));+ Assert.False(result.Compilation.IsSuccess);+ Assert.DoesNotContain(result.Compilation.Diagnostics, d => d.Message.Contains("CIR fallback lowering failed", StringComparison.Ordinal));+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.csindex 7c135d94..786c9db4 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs@@ -254,11 +254,21 @@ internal static class FirmamentPrimitiveExecutorif (!booleanResult.IsSuccess){- return KernelResult<FirmamentPrimitiveExecutionResult>.Failure(- [- CreateBooleanExecutionFailureDiagnostic(boolean),- .. WithBooleanContext(boolean, booleanResult.Diagnostics)- ]);+ var fallbackReplayLog = BuildReplayLog(loweringPlan, resolvedPlacementByOpIndex);+ var fallForward = TryBuildCirOnlyFallback(loweringPlan, fallbackReplayLog, boolean, booleanResult.Diagnostics);+ if (fallForward.IsSuccess)+ {+ return KernelResult<FirmamentPrimitiveExecutionResult>.Success(+ new FirmamentPrimitiveExecutionResult(executedPrimitives, executedBooleans, fallForward.Value));+ }++ var failureDiagnostics = new List<KernelDiagnostic>+ {+ CreateBooleanExecutionFailureDiagnostic(boolean)+ };+ failureDiagnostics.AddRange(WithBooleanContext(boolean, booleanResult.Diagnostics));+ failureDiagnostics.AddRange(fallForward.Diagnostics);+ return KernelResult<FirmamentPrimitiveExecutionResult>.Failure(failureDiagnostics);}var placedBooleanBody = booleanResult.Value;@@ -346,6 +356,66 @@ internal static class FirmamentPrimitiveExecutorreturn new NativeGeometryCirMirrorState(CirMirrorStatus.Available, summary, []);}++ private static KernelResult<NativeGeometryState> TryBuildCirOnlyFallback(+ FirmamentPrimitiveLoweringPlan loweringPlan,+ NativeGeometryReplayLog replayLog,+ FirmamentLoweredBoolean failedBoolean,+ IReadOnlyList<KernelDiagnostic> brepDiagnostics)+ {+ if (ClassifyFallForwardEligibility(failedBoolean, brepDiagnostics) != NativeGeometryTransitionReasonCategory.MaterializationUnsupported)+ {+ return KernelResult<NativeGeometryState>.Failure([]);+ }++ var cirLower = FirmamentCirLowerer.Lower(loweringPlan);+ if (!cirLower.IsSuccess)+ {+ var loweredDiagnostics = cirLower.Diagnostics.Select(d => d with+ {+ Message = $"CIR fallback lowering failed after unsupported BRep materialization for '{failedBoolean.FeatureId}': {d.Message}"+ }).ToArray();+ return KernelResult<NativeGeometryState>.Failure(loweredDiagnostics);+ }++ var nativeState = new NativeGeometryState(+ NativeGeometryExecutionMode.CirOnly,+ NativeGeometryMaterializationAuthority.CirIntentOnly,+ null,+ failedBoolean.FeatureId,+ replayLog,+ [+ new NativeGeometryTransitionEvent(+ NativeGeometryExecutionMode.BRepActive,+ NativeGeometryExecutionMode.CirOnly,+ failedBoolean.FeatureId,+ failedBoolean.OpIndex,+ NativeGeometryTransitionReasonCategory.MaterializationUnsupported,+ $"BRep materialization unsupported for boolean '{failedBoolean.FeatureId}'; transitioned to CirOnly intent execution.")+ ],+ BuildCirMirrorState(loweringPlan));++ return KernelResult<NativeGeometryState>.Success(nativeState);+ }++ private static NativeGeometryTransitionReasonCategory ClassifyFallForwardEligibility(FirmamentLoweredBoolean failedBoolean, IReadOnlyList<KernelDiagnostic> diagnostics)+ {+ var isBoundedCandidate = failedBoolean.Kind == FirmamentLoweredBooleanKind.Subtract+ && string.Equals(failedBoolean.Tool.OpName, "sphere", StringComparison.Ordinal)+ && diagnostics.Any(d => d.Code == KernelDiagnosticCode.NotImplemented+ && string.Equals(d.Source, "BrepBoolean.AnalyticHole.TangentContact", StringComparison.Ordinal));+ if (isBoundedCandidate)+ {+ return NativeGeometryTransitionReasonCategory.MaterializationUnsupported;+ }++ if (diagnostics.Any(d => d.Code == KernelDiagnosticCode.ValidationFailed))+ {+ return NativeGeometryTransitionReasonCategory.InvalidIntent;+ }++ return NativeGeometryTransitionReasonCategory.AnalyzerUncertainty;+ }private static IReadOnlyList<KernelDiagnostic> WithBooleanContext(FirmamentLoweredBoolean boolean, IReadOnlyList<KernelDiagnostic> diagnostics)=> diagnostics.Select(diagnostic =>{diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs b/Aetheris.Kernel.Firmament/FirmamentStepExporter.csindex 1e0c8878..326a8ca1 100644--- a/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs+++ b/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs@@ -71,6 +71,11 @@ public static class FirmamentStepExporter{return Failure("Firmament STEP export requires a completed primitive execution result.");}+ if (primitiveExecutionResult.NativeGeometryState.ExecutionMode == NativeGeometryExecutionMode.CirOnly)+ {+ var cirFeature = primitiveExecutionResult.NativeGeometryState.CirIntentRootReference ?? "unspecified";+ return Failure($"Firmament STEP export is unavailable for CirOnly state. Model remains valid and analyzable in CIR, but exact BRep/AP242 materialization is unavailable for feature '{cirFeature}' without a CIR→BRep materializer.");+ }ExportBodySelection? selected = null;diff --git a/docs/cir-f3-first-fall-forward.md b/docs/cir-f3-first-fall-forward.mdnew file mode 100644index 00000000..22598931--- /dev/null+++ b/docs/cir-f3-first-fall-forward.md@@ -0,0 +1,72 @@+# CIR-F3: First bounded runtime fall-forward to `CirOnly`++## Scope++CIR-F3 adds one bounded runtime transition path from `BRepActive` to `CirOnly` for a proven unsupported BRep materialization case where intent is still valid and CIR lowering is supported.++Out of scope for F3:++- CIR→BRep materialization+- public CLI exposure+- broad boolean/materializer redesign+- generated topology naming++## Chosen F3 candidate++Fixture: `testdata/firmament/fixtures/m10l-unsupported-box-subtract-sphere-touching-boundary.firmament`.++Why this candidate:++- intent is valid,+- BRep path reports unsupported materialization,+- CIR lowering supports box/sphere/subtract,+- no generated topology selector dependency,+- CIR mirror analysis yields bounded/volume diagnostics.++## Eligibility rule used in F3++A small classification is used for fallback eligibility:++- `MaterializationUnsupported` (eligible): BRep diagnostics include `NotImplemented` for unsupported materialization.+- `InvalidIntent` (not eligible): validation/coherence failures (`ValidationFailed`).+- `AnalyzerUncertainty` (not a trigger): everything else.++Only `MaterializationUnsupported` currently triggers fall-forward.++## Transition semantics++When eligible unsupported BRep materialization occurs during boolean execution:++1. replay log is preserved,+2. CIR lowering is attempted from the full lowering plan,+3. if CIR lowering succeeds:+ - state transitions to `CirOnly`,+ - materialization authority becomes `CirIntentOnly`,+ - `MaterializedBody` is null,+ - a transition event records `BRepActive -> CirOnly` with reason `MaterializationUnsupported`.+4. if CIR lowering fails:+ - hard failure is returned with both BRep context and CIR fallback lowering diagnostics.++## CirOnly analysis behavior++For the F3 candidate, `NativeGeometryState.CirMirror` is `Available` with estimated volume and bounds, enabling ongoing CIR-side analysis after fall-forward.++## Export behavior in F3++`FirmamentStepExporter` now explicitly rejects `CirOnly` execution state with a clear diagnostic stating:++- model remains valid/analyzable in CIR,+- exact BRep/AP242 materialization is unavailable,+- CIR→BRep materializer is required.++No tessellation or partial export is attempted.++## Guardrails++- invalid-intent fixtures remain hard failures (no transition),+- supported BRep golden paths remain `BRepActive` and export as before,+- unsupported CIR lowering after eligible BRep failure remains hard failure (no fake `CirOnly`).++## Recommended F4++Implement a scoped CIR-only artifact boundary for export/interop diagnostics (e.g., structured `CirOnly` export contract and per-op blocker payload), then introduce a minimal CIR→BRep materializer for one narrow boolean family.