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.csindex a3e6a18d..ba82cdc5 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs@@ -338,7 +338,7 @@ public sealed class FirmamentStepExporterTestsvar 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.csnew file mode 100644index 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.csindex 450a4554..8b9ff0f1 100644--- a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs@@ -43,8 +43,22 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.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.csnew file mode 100644index 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.csindex 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 FrepSemanticRecoveryRematerializerArgumentNullException.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 FrepSemanticRecoveryRematerializerif (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.mdnew file mode 100644index 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.