Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
CIR-RECOVERY-V6 scaffold HoleRecoveryPolicy with ThroughHoleVariant
Yuechen Lia7f9f81b76a3
diff --git a/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.csindex 968c69c9..9c292ca5 100644--- a/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPolicyCatalogTests.cs@@ -9,7 +9,7 @@ public sealed class FrepMaterializerPolicyCatalogTestspublic void Catalog_Default_IncludesThroughHolePolicy(){var policies = FrepMaterializerPolicyCatalog.Default();- Assert.Contains(policies, p => p.Name == nameof(ThroughHoleRecoveryPolicy));+ Assert.Contains(policies, p => p.Name == nameof(HoleRecoveryPolicy));}[Fact]@@ -27,7 +27,7 @@ public sealed class FrepMaterializerPolicyCatalogTestsvar decision = FrepMaterializerPlanner.Decide(context, FrepMaterializerPolicyCatalog.Default());Assert.Equal(FrepMaterializerDecisionStatus.Selected, decision.Status);- Assert.Equal(nameof(ThroughHoleRecoveryPolicy), decision.SelectedPolicyName);+ Assert.Equal(nameof(HoleRecoveryPolicy), decision.SelectedPolicyName);}[Fact]@@ -46,7 +46,7 @@ public sealed class FrepMaterializerPolicyCatalogTests{var snapshot = FrepMaterializerPolicyCatalog.SnapshotDefault();- Assert.Equal(new[] { nameof(ThroughHoleRecoveryPolicy), nameof(CirOnlyFallbackPolicy) }, snapshot.PolicyNames);+ Assert.Equal(new[] { nameof(HoleRecoveryPolicy), 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 8b9ff0f1..e016d5fb 100644--- a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs@@ -16,7 +16,7 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.True(result.Succeeded);Assert.NotNull(result.Body);- Assert.Equal(nameof(ThroughHoleRecoveryPolicy), result.SelectedPolicy);+ Assert.Equal(nameof(HoleRecoveryPolicy), result.SelectedPolicy);Assert.Contains(result.Diagnostics, d => d.Contains("planner ran", StringComparison.Ordinal));Assert.Contains(result.Diagnostics, d => d.Contains("executor succeeded", StringComparison.Ordinal));}@@ -32,7 +32,7 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.True(result.Succeeded);Assert.NotNull(result.Body);- Assert.Equal(nameof(ThroughHoleRecoveryPolicy), result.SelectedPolicy);+ Assert.Equal(nameof(HoleRecoveryPolicy), result.SelectedPolicy);}[Fact]@@ -45,7 +45,7 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.Null(result.Body);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));+ Assert.Contains(result.Diagnostics, d => d.Contains("selected policy was not HoleRecoveryPolicy", StringComparison.Ordinal));}@@ -58,7 +58,7 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.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));+ Assert.Contains(result.Diagnostics, d => d.Contains("selected policy was not HoleRecoveryPolicy", StringComparison.Ordinal));}[Fact]diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyTests.csnew file mode 100644index 00000000..6e2fd77d--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyTests.cs@@ -0,0 +1,39 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class HoleRecoveryPolicyTests+{+ private readonly HoleRecoveryPolicy _policy = new();++ [Fact]+ public void HolePolicy_DirectBoxCylinder_SelectsThroughHoleVariant()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))));+ Assert.True(eval.Admissible);+ Assert.Contains("selected-variant:ThroughHoleVariant", eval.Evidence);+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);+ Assert.Equal(HoleKind.Through, plan.HoleKind);+ Assert.Single(plan.ProfileStack);+ Assert.Equal(HoleProfileSegmentKind.Cylindrical, plan.ProfileStack[0].SegmentKind);+ }++ [Fact]+ public void HolePolicy_TranslatedBoxCylinder_SelectsThroughHoleVariant()+ {+ var root = new CirSubtractNode(new CirTransformNode(new CirBoxNode(20, 20, 10), Transform3D.CreateTranslation(new Vector3D(5, 2, 4))), new CirTransformNode(new CirCylinderNode(3, 16), Transform3D.CreateTranslation(new Vector3D(4, 1, 4))));+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));+ Assert.True(eval.Admissible);+ Assert.Contains("translation-wrapper-supported", eval.Evidence);+ }++ [Fact]+ public void HolePolicy_BlindCylinder_RejectedByVariant()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8))));+ Assert.False(eval.Admissible);+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedNotThroughHole", StringComparison.Ordinal));+ }+}diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.csindex 51c54b0a..c84d273c 100644--- a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs+++ b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs@@ -19,7 +19,7 @@ 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 HoleRecoveryPolicy(), FrepMaterializerPolicyCategory.SemanticExact, "Composable semantic hole-family policy with through-hole variant exact BRep recovery."),new(new CirOnlyFallbackPolicy(), FrepMaterializerPolicyCategory.CirOnlyFallback, "Intent-preserving fallback when no exact semantic BRep policy is admissible.")];diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.csindex 5098c301..efebb1a3 100644--- a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs+++ b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs@@ -8,7 +8,7 @@ internal sealed record FrepSemanticRecoveryResult(bool Attempted,bool Succeeded,string? SelectedPolicy,- ThroughHoleRecoveryPlan? Plan,+ HoleRecoveryPlan? Plan,ThroughHoleRecoveryExecutionStatus ExecutionStatus,BrepBody? Body,IReadOnlyList<string> Diagnostics,@@ -38,22 +38,30 @@ internal static class FrepSemanticRecoveryRematerializer}diagnostics.Add($"selected policy: {decision.SelectedPolicyName}");- if (!string.Equals(decision.SelectedPolicyName, nameof(ThroughHoleRecoveryPolicy), StringComparison.Ordinal))+ if (!string.Equals(decision.SelectedPolicyName, nameof(HoleRecoveryPolicy), StringComparison.Ordinal)){- diagnostics.Add("selected policy was not ThroughHoleRecoveryPolicy");+ diagnostics.Add("selected policy was not HoleRecoveryPolicy");return new(true, false, decision.SelectedPolicyName, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);}var selectedEval = decision.Evaluations.Single(e => string.Equals(e.PolicyName, decision.SelectedPolicyName, StringComparison.Ordinal));- if (selectedEval.Plan is not ThroughHoleRecoveryPlan plan)+ if (selectedEval.Plan is not HoleRecoveryPlan plan){- diagnostics.Add("selected policy did not provide through-hole plan");+ diagnostics.Add("selected policy did not provide hole-recovery plan");diagnostics.Add("selected policy is non-executable for exact BRep recovery");return new(true, false, decision.SelectedPolicyName, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);}- diagnostics.Add("through-hole plan extracted");- var execution = ThroughHoleRecoveryExecutor.Execute(plan);+ diagnostics.Add("hole-recovery plan extracted");+ if (!ThroughHoleRecoveryPlanAdapter.TryConvert(plan, out var throughPlan) || throughPlan is null)+ {+ diagnostics.Add("hole plan conversion to through-hole executor contract failed");+ diagnostics.Add("selected hole variant is currently non-executable");+ return new(true, false, decision.SelectedPolicyName, plan, ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics, decision);+ }++ diagnostics.Add("hole plan converted to through-hole executor contract");+ var execution = ThroughHoleRecoveryExecutor.Execute(throughPlan);diagnostics.AddRange(execution.Diagnostics);if (execution.Status != ThroughHoleRecoveryExecutionStatus.Succeeded || execution.Body is null){diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.csnew file mode 100644index 00000000..46f77b6a--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs@@ -0,0 +1,36 @@+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Firmament.Materializer;++public enum HoleHostKind { RectangularBox, Unsupported }+public enum HoleAxisKind { Z, Unsupported }+public enum HoleKind { Through, Unsupported }+public enum HoleDepthKind { Through, Blind, Unsupported }+public enum HoleProfileSegmentKind { Cylindrical, Conical, Chamfer, ThreadDeferred, Unsupported }+public enum HoleEntryFeatureKind { Plain, Unsupported }+public enum HoleExitFeatureKind { Plain, Unsupported }+public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall }+public enum HoleTrimCurveRole { CircularRimTrim, Deferred }++public sealed record HoleProfileSegment(HoleProfileSegmentKind SegmentKind, double RadiusStart, double RadiusEnd, double DepthStart, double DepthEnd);+public sealed record HoleSurfacePatchExpectation(HoleSurfacePatchRole Role, string Description);+public sealed record HoleTrimCurveExpectation(HoleTrimCurveRole Role, string Description);++public sealed record HoleRecoveryPlan(+ HoleHostKind HostKind,+ HoleAxisKind Axis,+ HoleKind HoleKind,+ HoleDepthKind DepthKind,+ HoleEntryFeatureKind EntryFeature,+ HoleExitFeatureKind ExitFeature,+ double ThroughLength,+ double HostSizeX,+ double HostSizeY,+ double HostSizeZ,+ Vector3D HostTranslation,+ Vector3D ToolTranslation,+ IReadOnlyList<HoleProfileSegment> ProfileStack,+ IReadOnlyList<HoleSurfacePatchExpectation> ExpectedSurfacePatches,+ IReadOnlyList<HoleTrimCurveExpectation> ExpectedTrimCurves,+ FrepMaterializerCapability Capability,+ IReadOnlyList<string> Diagnostics);diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.csnew file mode 100644index 00000000..749d1d52--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs@@ -0,0 +1,95 @@+using Aetheris.Kernel.Core.Judgment;++namespace Aetheris.Kernel.Firmament.Materializer;++public interface IHoleRecoveryVariant+{+ string Name { get; }+ HoleRecoveryVariantEvaluation Evaluate(FrepMaterializerContext context);+}++public sealed record HoleRecoveryVariantEvaluation(+ string VariantName,+ bool Admissible,+ double Score,+ HoleRecoveryPlan? Plan,+ IReadOnlyList<string> Evidence,+ IReadOnlyList<string> RejectionReasons,+ IReadOnlyList<string> Diagnostics);++public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy+{+ private static readonly JudgmentEngine<FrepMaterializerContext> VariantEngine = new();+ private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant()];+ public string Name => nameof(HoleRecoveryPolicy);++ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)+ {+ var traces = _variants.Select(v => v.Evaluate(context)).ToArray();+ var diagnostics = new List<string> {$"{Name} evaluated.", $"Variants evaluated: {traces.Length}."};+ diagnostics.AddRange(traces.SelectMany(t => t.Diagnostics.Select(d => $"variant:{t.VariantName}:{d}")));++ var candidates = traces.Select((t, i) => new JudgmentCandidate<FrepMaterializerContext>(t.VariantName, _ => t.Admissible, _ => t.Score, _ => t.RejectionReasons.Count == 0 ? "variant rejected" : string.Join(" | ", t.RejectionReasons), i)).ToArray();+ var judgment = VariantEngine.Evaluate(context, candidates);+ if (!judgment.IsSuccess)+ {+ var reasons = traces.SelectMany(t => t.RejectionReasons.Select(r => $"{t.VariantName}:{r}")).ToArray();+ diagnostics.Add("No admissible hole variant.");+ return FrepMaterializerPolicyEvaluation.Rejected(Name, traces.SelectMany(t => t.Evidence).Append("semantic-hole-family").ToArray(), diagnostics, reasons);+ }++ var selectedName = judgment.Selection!.Value.Candidate.Name;+ var selected = traces.Single(t => t.VariantName == selectedName);+ var evidence = new List<string> { "semantic-hole-family", $"selected-variant:{selected.VariantName}" };+ evidence.AddRange(selected.Evidence);+ diagnostics.Add($"Selected hole variant: {selected.VariantName}.");+ diagnostics.Add("Hole recovery plan produced.");+ return FrepMaterializerPolicyEvaluation.Admitted(Name, selected.Score, FrepMaterializerCapability.ExactBRep, evidence, diagnostics, selected.Plan);+ }+}++internal sealed class ThroughHoleVariant : IHoleRecoveryVariant+{+ private const double Score = 1000d;+ public string Name => nameof(ThroughHoleVariant);++ public HoleRecoveryVariantEvaluation Evaluate(FrepMaterializerContext context)+ {+ var recognition = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(context.Root, context.ReplayLog, context.SourceLabel));+ if (!recognition.Success || recognition.Value is null)+ {+ return new(Name, false, 0d, null, ["through-hole", "rectangular-box-host"], [recognition.Diagnostic, $"recognizer-reason:{recognition.Reason}"], recognition.Diagnostics);+ }++ var r = recognition.Value;+ var supportsTranslation = r.BoxTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero || r.CylinderTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero;+ var evidence = new List<string> { "through-hole", "rectangular-box-host", "cylindrical-profile-segment", "strict-clearance", "z-axis", supportsTranslation ? "translation-wrapper-supported" : "translation-wrapper-not-required" };+ var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Through, HoleDepthKind.Through, HoleEntryFeatureKind.Plain, HoleExitFeatureKind.Plain, r.ThroughLength, r.BoxWidth, r.BoxHeight, r.BoxDepth, r.BoxTranslation, r.CylinderTranslation,+ [new(HoleProfileSegmentKind.Cylindrical, r.CylinderRadius, r.CylinderRadius, 0d, r.ThroughLength)],+ [new(HoleSurfacePatchRole.EntryFace, "Cylinder intersects host entry face with circular profile."), new(HoleSurfacePatchRole.ExitFace, "Cylinder intersects host exit face with circular profile."), new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after through-hole subtraction."), new(HoleSurfacePatchRole.CylindricalWall, "One cylindrical inner wall patch is expected.")],+ [new(HoleTrimCurveRole.CircularRimTrim, "Circular trims on entry and exit rims are expected.")],+ FrepMaterializerCapability.ExactBRep,+ recognition.Diagnostics);+ evidence.Add(recognition.Reason == CirBoxCylinderRecognitionReason.ReplayMismatch ? "replay-diagnostic" : "replay-consistent");+ return new(Name, true, Score, plan, evidence, Array.Empty<string>(), recognition.Diagnostics);+ }+}++internal static class ThroughHoleRecoveryPlanAdapter+{+ internal static bool TryConvert(HoleRecoveryPlan plan, out ThroughHoleRecoveryPlan? through)+ {+ through = null;+ if (plan.HostKind != HoleHostKind.RectangularBox || plan.Axis != HoleAxisKind.Z || plan.HoleKind != HoleKind.Through || plan.DepthKind != HoleDepthKind.Through || plan.ProfileStack.Count != 1 || plan.ProfileStack[0].SegmentKind != HoleProfileSegmentKind.Cylindrical)+ {+ return false;+ }++ var seg = plan.ProfileStack[0];+ through = new ThroughHoleRecoveryPlan(ThroughHoleHostKind.RectangularBox, ThroughHoleToolKind.Cylindrical, ThroughHoleProfileKind.Circular, ThroughHoleAxisKind.Z, plan.ThroughLength, seg.RadiusStart, plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ, plan.HostTranslation, plan.ToolTranslation,+ [new(ThroughHoleSurfaceRole.EntryFace, "Adapted from HoleRecoveryPlan."), new(ThroughHoleSurfaceRole.ExitFace, "Adapted from HoleRecoveryPlan.")],+ [new(ThroughHoleSurfaceRole.HostRetainedPlanarFaces, "Adapted from HoleRecoveryPlan."), new(ThroughHoleSurfaceRole.CylindricalWall, "Adapted from HoleRecoveryPlan.")],+ [new(ThroughHoleTrimRole.CircularRimTrim, "Adapted from HoleRecoveryPlan.")], plan.Capability, plan.Diagnostics);+ return true;+ }+}diff --git a/docs/cir-recovery-v5-policy-catalog.md b/docs/cir-recovery-v5-policy-catalog.mdindex 46ab992c..0d1c61e9 100644--- a/docs/cir-recovery-v5-policy-catalog.md+++ b/docs/cir-recovery-v5-policy-catalog.md@@ -17,7 +17,7 @@ Catalog-side metadata uses `FrepMaterializerPolicyCategory`:- `CirOnlyFallback`## Default policy list (deterministic order)-1. `ThroughHoleRecoveryPolicy` (`SemanticExact`)+1. `HoleRecoveryPolicy` (`SemanticExact`)2. `CirOnlyFallbackPolicy` (`CirOnlyFallback`)## Fallback behaviordiff --git a/docs/cir-recovery-v6-hole-recovery-policy.md b/docs/cir-recovery-v6-hole-recovery-policy.mdnew file mode 100644index 00000000..25d8298d--- /dev/null+++ b/docs/cir-recovery-v6-hole-recovery-policy.md@@ -0,0 +1,49 @@+# CIR-RECOVERY-V6: HoleRecoveryPolicy scaffold with ThroughHoleVariant++## Summary+V6 replaces the default top-level exact semantic recovery policy from `ThroughHoleRecoveryPolicy` to `HoleRecoveryPolicy`, with a compositional variant architecture and one production variant: `ThroughHoleVariant`.++## Why this migration+This follows CIR-RECOVERY-X7's recommendation to avoid top-level policy explosion and keep hole-family growth local and diagnosable.++## Architecture+- `HoleRecoveryPolicy` (top-level policy)+- `IHoleRecoveryVariant` + `HoleRecoveryVariantEvaluation`+- `ThroughHoleVariant` (only implemented variant in V6)+- `HoleRecoveryPlan` + `HoleProfileSegment` as family plan contract++## Current plan shape (implemented)+- `HostKind = RectangularBox`+- `Axis = Z`+- `HoleKind = Through`+- `DepthKind = Through`+- `ProfileStack = [ Cylindrical ]`+- `EntryFeature = Plain`+- `ExitFeature = Plain`++## Executor compatibility strategy+V6 uses **Option A (adapter)**:+- `ThroughHoleRecoveryPlanAdapter.TryConvert(HoleRecoveryPlan)`+- Existing `ThroughHoleRecoveryExecutor` remains unchanged and continues executing the through-hole route.++## Default policy catalog (V6)+1. `HoleRecoveryPolicy` (`SemanticExact`)+2. `CirOnlyFallbackPolicy` (`CirOnlyFallback`)++`ThroughHoleRecoveryPolicy` remains in code for compatibility/direct use and tests, but is no longer in the default catalog.++## Fallback behavior+If no variant is admissible, `HoleRecoveryPolicy` rejects with aggregated variant reasons and catalog selection falls through to `CirOnlyFallbackPolicy`.++## Future extension pattern+To add counterbore/countersink/blind-hole:+1. add new `IHoleRecoveryVariant` implementation,+2. emit `HoleRecoveryPlan` segments/features,+3. register variant in `HoleRecoveryPolicy` deterministic list,+4. add focused variant + fallback diagnostics tests.++## Non-goals in V6+- No new counterbore/countersink/blind variants+- No new BRep executor algorithms+- No STEP exporter behavior changes+- No public CLI/API surface changes