Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Frep semantic recovery policy catalog scaffold

Yuechen Li1600db104a21
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs
index a3e6a18d..ba82cdc5 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs
@@ -338,7 +338,7 @@ public sealed class FirmamentStepExporterTests
var remat = NativeGeometryRematerializer.TryRematerialize(artifact.PrimitiveLoweringPlan!, cirOnlyState);
Assert.False(remat.IsSuccess);
- Assert.Contains(remat.Diagnostics, d => d.Message.Contains("selectedPolicy='none'", StringComparison.Ordinal));
+ Assert.Contains(remat.Diagnostics, d => d.Message.Contains("selectedPolicy='CirOnlyFallbackPolicy'", StringComparison.Ordinal));
Assert.DoesNotContain(remat.Diagnostics, d => d.Message.Contains("semantic recovery policy", StringComparison.Ordinal));
}
diff --git a/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs
new file mode 100644
index 00000000..968c69c9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs
@@ -0,0 +1,52 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FrepMaterializerPolicyCatalogTests
+{
+ [Fact]
+ public void Catalog_Default_IncludesThroughHolePolicy()
+ {
+ var policies = FrepMaterializerPolicyCatalog.Default();
+ Assert.Contains(policies, p => p.Name == nameof(ThroughHoleRecoveryPolicy));
+ }
+
+ [Fact]
+ public void Catalog_Default_OrderIsDeterministic()
+ {
+ var first = FrepMaterializerPolicyCatalog.Default().Select(p => p.Name).ToArray();
+ var second = FrepMaterializerPolicyCatalog.Default().Select(p => p.Name).ToArray();
+ Assert.Equal(first, second);
+ }
+
+ [Fact]
+ public void Planner_WithDefaultCatalog_SelectsThroughHoleForBoxCylinder()
+ {
+ var context = new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20)));
+ var decision = FrepMaterializerPlanner.Decide(context, FrepMaterializerPolicyCatalog.Default());
+
+ Assert.Equal(FrepMaterializerDecisionStatus.Selected, decision.Status);
+ Assert.Equal(nameof(ThroughHoleRecoveryPolicy), decision.SelectedPolicyName);
+ }
+
+ [Fact]
+ public void Planner_WithDefaultCatalog_UsesFallbackForUnsupported()
+ {
+ var context = new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2)));
+ var decision = FrepMaterializerPlanner.Decide(context, FrepMaterializerPolicyCatalog.Default());
+
+ Assert.Equal(FrepMaterializerDecisionStatus.Selected, decision.Status);
+ Assert.Equal(nameof(CirOnlyFallbackPolicy), decision.SelectedPolicyName);
+ Assert.Equal(FrepMaterializerCapability.CirOnly, decision.Capability);
+ }
+
+ [Fact]
+ public void Catalog_Snapshot_ReportsPolicyNamesAndOrder()
+ {
+ var snapshot = FrepMaterializerPolicyCatalog.SnapshotDefault();
+
+ Assert.Equal(new[] { nameof(ThroughHoleRecoveryPolicy), nameof(CirOnlyFallbackPolicy) }, snapshot.PolicyNames);
+ Assert.Contains(snapshot.Diagnostics, d => d.Contains("default catalog built", StringComparison.Ordinal));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs
index 450a4554..8b9ff0f1 100644
--- a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs
@@ -43,8 +43,22 @@ public sealed class FrepSemanticRecoveryRematerializerTests
Assert.False(result.Succeeded);
Assert.Null(result.Body);
- Assert.Equal(FrepMaterializerDecisionStatus.NoAdmissiblePolicy, result.Decision.Status);
- Assert.Contains(result.Diagnostics, d => d.Contains("no admissible policy", StringComparison.Ordinal));
+ Assert.Equal(FrepMaterializerDecisionStatus.Selected, result.Decision.Status);
+ Assert.Equal(nameof(CirOnlyFallbackPolicy), result.SelectedPolicy);
+ Assert.Contains(result.Diagnostics, d => d.Contains("selected policy was not ThroughHoleRecoveryPolicy", StringComparison.Ordinal));
+ }
+
+
+ [Fact]
+ public void CirOnlyFallback_DoesNotProduceBrepSuccess()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(20d, 10d, 8d), new CirSphereNode(2d));
+ var result = FrepSemanticRecoveryRematerializer.TryRecover(root);
+
+ Assert.False(result.Succeeded);
+ Assert.Null(result.Body);
+ Assert.Equal(nameof(CirOnlyFallbackPolicy), result.SelectedPolicy);
+ Assert.Contains(result.Diagnostics, d => d.Contains("selected policy was not ThroughHoleRecoveryPolicy", StringComparison.Ordinal));
}
[Fact]
diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs
new file mode 100644
index 00000000..51c54b0a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs
@@ -0,0 +1,66 @@
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+public enum FrepMaterializerPolicyCategory
+{
+ SemanticExact,
+ CirOnlyFallback
+}
+
+public sealed record FrepMaterializerPolicyRegistration(
+ IFrepMaterializerPolicy Policy,
+ FrepMaterializerPolicyCategory Category,
+ string Description);
+
+public sealed record FrepMaterializerPolicyCatalogSnapshot(
+ IReadOnlyList<string> PolicyNames,
+ IReadOnlyList<string> Diagnostics);
+
+public static class FrepMaterializerPolicyCatalog
+{
+ private static readonly IReadOnlyList<FrepMaterializerPolicyRegistration> DefaultRegistrationsValue =
+ [
+ new(new ThroughHoleRecoveryPolicy(), FrepMaterializerPolicyCategory.SemanticExact, "Canonical rectangular-box minus cylindrical through-hole exact BRep recovery."),
+ new(new CirOnlyFallbackPolicy(), FrepMaterializerPolicyCategory.CirOnlyFallback, "Intent-preserving fallback when no exact semantic BRep policy is admissible.")
+ ];
+
+ public static IReadOnlyList<FrepMaterializerPolicyRegistration> DefaultRegistrations() => DefaultRegistrationsValue;
+
+ public static IReadOnlyList<IFrepMaterializerPolicy> Default() => DefaultRegistrationsValue.Select(r => r.Policy).ToArray();
+
+ public static FrepMaterializerPolicyCatalogSnapshot SnapshotDefault()
+ {
+ var diagnostics = new List<string>
+ {
+ "FrepMaterializerPolicyCatalog default catalog built.",
+ $"Policy registration count: {DefaultRegistrationsValue.Count}."
+ };
+
+ diagnostics.AddRange(DefaultRegistrationsValue.Select((registration, index) =>
+ $"[{index}] {registration.Policy.Name} ({registration.Category}) - {registration.Description}"));
+
+ return new(DefaultRegistrationsValue.Select(r => r.Policy.Name).ToArray(), diagnostics);
+ }
+}
+
+public sealed class CirOnlyFallbackPolicy : IFrepMaterializerPolicy
+{
+ private const double CirOnlyFallbackScore = 1d;
+
+ public string Name => nameof(CirOnlyFallbackPolicy);
+
+ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)
+ {
+ ArgumentNullException.ThrowIfNull(context);
+
+ return FrepMaterializerPolicyEvaluation.Admitted(
+ Name,
+ CirOnlyFallbackScore,
+ FrepMaterializerCapability.CirOnly,
+ ["cir-only-fallback", "intent-preserving"],
+ [
+ "Exact semantic BRep recovery unavailable for current input.",
+ "Fallback selected to preserve CIR intent without BRep emission."
+ ],
+ plan: null);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs
index 02c58d5a..5098c301 100644
--- a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs
@@ -16,7 +16,6 @@ internal sealed record FrepSemanticRecoveryResult(
internal static class FrepSemanticRecoveryRematerializer
{
- private static readonly ThroughHoleRecoveryPolicy ThroughHolePolicy = new();
internal static FrepSemanticRecoveryResult TryRecover(
CirNode root,
@@ -26,7 +25,10 @@ internal static class FrepSemanticRecoveryRematerializer
ArgumentNullException.ThrowIfNull(root);
var diagnostics = new List<string> { "semantic recovery attempted", "planner ran" };
- var decision = FrepMaterializerPlanner.Decide(new FrepMaterializerContext(root, replayLog, sourceLabel), [ThroughHolePolicy]);
+ var catalogSnapshot = FrepMaterializerPolicyCatalog.SnapshotDefault();
+ diagnostics.AddRange(catalogSnapshot.Diagnostics);
+
+ var decision = FrepMaterializerPlanner.Decide(new FrepMaterializerContext(root, replayLog, sourceLabel), FrepMaterializerPolicyCatalog.Default());
diagnostics.AddRange(decision.Diagnostics);
if (decision.Status != FrepMaterializerDecisionStatus.Selected)
@@ -46,6 +48,7 @@ internal static class FrepSemanticRecoveryRematerializer
if (selectedEval.Plan is not ThroughHoleRecoveryPlan plan)
{
diagnostics.Add("selected policy did not provide through-hole plan");
+ diagnostics.Add("selected policy is non-executable for exact BRep recovery");
return new(true, false, decision.SelectedPolicyName, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);
}
diff --git a/docs/cir-recovery-v5-policy-catalog.md b/docs/cir-recovery-v5-policy-catalog.md
new file mode 100644
index 00000000..46ab992c
--- /dev/null
+++ b/docs/cir-recovery-v5-policy-catalog.md
@@ -0,0 +1,51 @@
+# CIR-RECOVERY-V5: expandable semantic recovery policy catalog scaffold
+
+## Purpose
+CIR-RECOVERY-V5 introduces a production policy catalog layer for semantic FRep→BRep recovery planning so new bounded recovery policies can be added with local changes.
+
+## Catalog structure
+`FrepMaterializerPolicyCatalog` is the single default registration location in `Aetheris.Kernel.Firmament.Materializer`.
+
+It exposes:
+- `DefaultRegistrations()` for ordered policy registrations.
+- `Default()` for planner-consumable `IFrepMaterializerPolicy` list.
+- `SnapshotDefault()` for deterministic policy-order diagnostics.
+
+## Policy categories
+Catalog-side metadata uses `FrepMaterializerPolicyCategory`:
+- `SemanticExact`
+- `CirOnlyFallback`
+
+## Default policy list (deterministic order)
+1. `ThroughHoleRecoveryPolicy` (`SemanticExact`)
+2. `CirOnlyFallbackPolicy` (`CirOnlyFallback`)
+
+## Fallback behavior
+`CirOnlyFallbackPolicy` is always admissible with low score and `FrepMaterializerCapability.CirOnly`.
+It preserves intent/diagnostics and intentionally emits no executable BRep plan.
+
+## Planner behavior
+`FrepMaterializerPlanner` remains the existing generic JudgmentEngine selector.
+No policy-specific dispatch logic was added to planner internals.
+
+## Rematerializer wiring
+`FrepSemanticRecoveryRematerializer` now consumes `FrepMaterializerPolicyCatalog.Default()` instead of manually constructing a single policy list.
+If fallback is selected, rematerializer records non-executable diagnostics and does not report BRep recovery success.
+
+## Locality-of-change rule
+Adding a new semantic recovery capability should require only:
+1. Implementing a new `IFrepMaterializerPolicy`.
+2. Registering it in `FrepMaterializerPolicyCatalog` in the intended order/category.
+3. Adding focused tests for recognition, admissibility, and rematerializer behavior.
+
+No `FrepMaterializerPlanner` logic edits are required.
+
+## Non-goals in V5
+- New exact semantic recovery implementations beyond through-hole.
+- STEP export behavior changes.
+- Generic boolean dispatcher.
+- Public CLI/API expansion.
+- Generated topology naming.
+
+## Recommended next milestone
+Add next semantic exact family policies (for example counterbore/countersink) as bounded `IFrepMaterializerPolicy` implementations and register them above fallback with explicit diagnostics and evidence contracts.