Skip to content

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.cs
index 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.cs
index 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 FirmamentPrimitiveExecutionTests
var 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 FirmamentPrimitiveExecutionTests
var 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 FirmamentPrimitiveExecutionTests
var 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.cs
index 8a29e528..4a82ae5d 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs
@@ -225,6 +225,16 @@ public sealed class FirmamentStepExporterTests
Assert.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 FirmamentStepExporterTests
Assert.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.cs
index 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 NativeGeometryStateTests
Assert.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.cs
index 7c135d94..786c9db4 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -254,11 +254,21 @@ internal static class FirmamentPrimitiveExecutor
if (!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 FirmamentPrimitiveExecutor
return 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.cs
index 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.md
new file mode 100644
index 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.