Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add ThroughHoleRecoveryPolicy semantic scaffold and plan
Yuechen Li27acdd6cd9f4
diff --git a/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.cs b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.csnew file mode 100644index 00000000..56cb2177--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.cs@@ -0,0 +1,96 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class ThroughHoleRecoveryPolicyTests+{+ private readonly ThroughHoleRecoveryPolicy _policy = new();++ [Fact]+ public void ThroughHolePolicy_DirectBoxCylinder_AdmitsAndCreatesPlan()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))));+ Assert.True(eval.Admissible);+ Assert.Equal(FrepMaterializerCapability.ExactBRep, eval.Capability);+ var plan = Assert.IsType<ThroughHoleRecoveryPlan>(eval.Plan);+ Assert.Equal(ThroughHoleHostKind.RectangularBox, plan.HostKind);+ Assert.Equal(ThroughHoleToolKind.Cylindrical, plan.ToolKind);+ Assert.Equal(ThroughHoleProfileKind.Circular, plan.ProfileKind);+ Assert.Equal(ThroughHoleAxisKind.Z, plan.Axis);+ Assert.Equal(20d, plan.ThroughLength, 6);+ }++ [Fact]+ public void ThroughHolePolicy_TranslatedBoxCylinder_Admits()+ {+ 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 Planner_SelectsThroughHolePolicy_OverFallback()+ {+ var context = new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20)));+ var decision = FrepMaterializerPlanner.Decide(context, [+ _policy,+ new FakePolicy("fallback", FrepMaterializerPolicyEvaluation.Admitted("fallback", 1d, FrepMaterializerCapability.CirOnly))+ ]);+ Assert.Equal(nameof(ThroughHoleRecoveryPolicy), decision.SelectedPolicyName);+ }++ [Fact]+ public void ThroughHolePolicy_RejectsBoxSphere()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2))));+ Assert.False(eval.Admissible);+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedRightNotCylinder", StringComparison.Ordinal));+ }++ [Fact]+ public void ThroughHolePolicy_RejectsBlindCylinder()+ {+ 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));+ }++ [Fact]+ public void ThroughHolePolicy_RejectsTangentOrGrazing()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateTranslation(new Vector3D(3, 0, 0))))));+ Assert.False(eval.Admissible);+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedTangentOrGrazing", StringComparison.Ordinal));+ }++ [Fact]+ public void ThroughHolePolicy_RejectsUnsupportedTransform()+ {+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateRotationX(0.2)))));+ Assert.False(eval.Admissible);+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedTransform", StringComparison.Ordinal));+ }++ [Fact]+ public void ThroughHolePolicy_DecisionTraceContainsPlanEvidence()+ {+ var decision = FrepMaterializerPlanner.Decide(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))), [_policy]);+ var eval = Assert.Single(decision.Evaluations);+ Assert.Contains("semantic-through-hole", eval.Evidence);+ Assert.Contains(eval.Evidence, e => e.Contains("expected-patches", StringComparison.Ordinal));+ Assert.Contains(eval.Evidence, e => e.Contains("expected-trims", StringComparison.Ordinal));+ }++ private sealed class FakePolicy(string name, FrepMaterializerPolicyEvaluation evaluation) : IFrepMaterializerPolicy+ {+ public string Name => name;++ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context) => evaluation;+ }+}diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.csindex 1890d36f..08b0d9b3 100644--- a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs+++ b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs@@ -31,20 +31,29 @@ public sealed record FrepMaterializerPolicyEvaluation(FrepMaterializerCapability Capability,IReadOnlyList<string> Evidence,IReadOnlyList<string> RejectionReasons,- IReadOnlyList<string> Diagnostics)+ IReadOnlyList<string> Diagnostics,+ object? Plan = null){public static FrepMaterializerPolicyEvaluation Admitted(string policyName,double score,FrepMaterializerCapability capability,IReadOnlyList<string>? evidence = null,- IReadOnlyList<string>? diagnostics = null)- => new(policyName, true, score, capability, evidence ?? Array.Empty<string>(), Array.Empty<string>(), diagnostics ?? Array.Empty<string>());+ IReadOnlyList<string>? diagnostics = null,+ object? plan = null)+ => new(policyName, true, score, capability, evidence ?? Array.Empty<string>(), Array.Empty<string>(), diagnostics ?? Array.Empty<string>(), plan);public static FrepMaterializerPolicyEvaluation Rejected(string policyName,params string[] rejectionReasons)=> new(policyName, false, 0d, FrepMaterializerCapability.Unsupported, Array.Empty<string>(), rejectionReasons, Array.Empty<string>());++ public static FrepMaterializerPolicyEvaluation Rejected(+ string policyName,+ IReadOnlyList<string>? evidence = null,+ IReadOnlyList<string>? diagnostics = null,+ params string[] rejectionReasons)+ => new(policyName, false, 0d, FrepMaterializerCapability.Unsupported, evidence ?? Array.Empty<string>(), rejectionReasons, diagnostics ?? Array.Empty<string>());}public enum FrepMaterializerDecisionStatusdiff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.csnew file mode 100644index 00000000..d63551f9--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.cs@@ -0,0 +1,65 @@+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Firmament.Materializer;++public enum ThroughHoleHostKind+{+ RectangularBox,+ Unsupported+}++public enum ThroughHoleToolKind+{+ Cylindrical,+ Unsupported+}++public enum ThroughHoleProfileKind+{+ Circular,+ Unsupported+}++public enum ThroughHoleAxisKind+{+ Z,+ Unsupported+}++public enum ThroughHoleSurfaceRole+{+ EntryFace,+ ExitFace,+ HostRetainedPlanarFaces,+ CylindricalWall+}++public enum ThroughHoleTrimRole+{+ CircularRimTrim,+ Deferred+}++public sealed record ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole Role, string Description);++public sealed record ThroughHoleExpectedPatch(ThroughHoleSurfaceRole Role, string Description);++public sealed record ThroughHoleExpectedTrim(ThroughHoleTrimRole Role, string Description);++public sealed record ThroughHoleRecoveryPlan(+ ThroughHoleHostKind HostKind,+ ThroughHoleToolKind ToolKind,+ ThroughHoleProfileKind ProfileKind,+ ThroughHoleAxisKind Axis,+ double ThroughLength,+ double ToolRadius,+ double HostSizeX,+ double HostSizeY,+ double HostSizeZ,+ Vector3D HostTranslation,+ Vector3D ToolTranslation,+ IReadOnlyList<ThroughHoleSurfaceParticipation> EntryExitSurfaces,+ IReadOnlyList<ThroughHoleExpectedPatch> ExpectedPatches,+ IReadOnlyList<ThroughHoleExpectedTrim> ExpectedTrims,+ FrepMaterializerCapability Capability,+ IReadOnlyList<string> Diagnostics);diff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.csnew file mode 100644index 00000000..a8d1f496--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs@@ -0,0 +1,72 @@+namespace Aetheris.Kernel.Firmament.Materializer;++public sealed class ThroughHoleRecoveryPolicy : IFrepMaterializerPolicy+{+ private const double SemanticThroughHoleScore = 1000d;++ public string Name => nameof(ThroughHoleRecoveryPolicy);++ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)+ {+ ArgumentNullException.ThrowIfNull(context);++ var recognition = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(context.Root, context.ReplayLog, context.SourceLabel));+ if (!recognition.Success || recognition.Value is null)+ {+ return FrepMaterializerPolicyEvaluation.Rejected(+ Name,+ evidence: ["semantic-through-hole", $"recognizer-reason:{recognition.Reason}"],+ diagnostics: recognition.Diagnostics,+ rejectionReasons: [recognition.Diagnostic, $"recognizer-reason:{recognition.Reason}"]);+ }++ var recognized = recognition.Value;+ var evidence = new List<string>+ {+ "semantic-through-hole",+ "rectangular-box-host",+ "cylindrical-tool",+ "through-hole",+ "strict-clearance"+ };++ var supportsTranslation = recognized.BoxTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero+ || recognized.CylinderTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero;+ evidence.Add(supportsTranslation ? "translation-wrapper-supported" : "translation-wrapper-not-required");+ evidence.Add(recognition.Reason == CirBoxCylinderRecognitionReason.ReplayMismatch ? "replay-diagnostic" : "replay-consistent");+ evidence.Add("expected-patches:entry-exit-planar,cylindrical-wall");+ evidence.Add("expected-trims:circular-rim");++ var plan = new ThroughHoleRecoveryPlan(+ ThroughHoleHostKind.RectangularBox,+ ThroughHoleToolKind.Cylindrical,+ ThroughHoleProfileKind.Circular,+ ThroughHoleAxisKind.Z,+ recognized.ThroughLength,+ recognized.CylinderRadius,+ recognized.BoxWidth,+ recognized.BoxHeight,+ recognized.BoxDepth,+ recognized.BoxTranslation,+ recognized.CylinderTranslation,+ [+ new ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole.EntryFace, "Cylinder intersects host entry face with circular profile."),+ new ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole.ExitFace, "Cylinder intersects host exit face with circular profile.")+ ],+ [+ new ThroughHoleExpectedPatch(ThroughHoleSurfaceRole.HostRetainedPlanarFaces, "Host planar faces are retained after through-hole subtraction."),+ new ThroughHoleExpectedPatch(ThroughHoleSurfaceRole.CylindricalWall, "One cylindrical inner wall patch is expected.")+ ],+ [new ThroughHoleExpectedTrim(ThroughHoleTrimRole.CircularRimTrim, "Circular trims on entry and exit rims are expected.")],+ FrepMaterializerCapability.ExactBRep,+ recognition.Diagnostics);++ return FrepMaterializerPolicyEvaluation.Admitted(+ Name,+ SemanticThroughHoleScore,+ FrepMaterializerCapability.ExactBRep,+ evidence,+ recognition.Diagnostics,+ plan);+ }+}diff --git a/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.mdindex 80e31b03..7e2eaa6d 100644--- a/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md+++ b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md@@ -41,4 +41,4 @@ No lowering plan or execution-state dependency is required in V1A.## Next milestone-CIR-RECOVERY-V1B should add a first production semantic policy (`BoxCylinderThroughHolePolicy`) that emits diagnostic-rich evaluation only (or bounded exact path if explicitly scoped), while preserving existing behavior gates.+CIR-RECOVERY-V1B should add a first production semantic policy (`ThroughHoleRecoveryPolicy`) with an internal box+cylinder specialization that emits a diagnostic-rich semantic plan, while preserving existing behavior gates.diff --git a/docs/cir-recovery-v1b-through-hole-policy.md b/docs/cir-recovery-v1b-through-hole-policy.mdnew file mode 100644index 00000000..1d6a1e8c--- /dev/null+++ b/docs/cir-recovery-v1b-through-hole-policy.md@@ -0,0 +1,61 @@+# CIR-RECOVERY-V1B: ThroughHoleRecoveryPolicy scaffold++## Why semantic-through-hole (not pair-specific top-level)++CIR-BREP-X6 recommended a semantic policy lane (`ThroughHoleRecoveryPolicy`) with bounded internal host/tool specializations instead of promoting a pair-specific `BoxCylinderThroughHolePolicy` to top level. This keeps policy growth manageable as feature families expand.++## First specialization in V1B++V1B adds one internal specialization through existing production recognizer behavior:+- host: rectangular box+- tool: cylindrical subtractor+- feature: strict-clearance through-hole along Z++Recognizer source remains `CirBoxCylinderRecognizer`.++## Recovery plan shape++`ThroughHoleRecoveryPlan` carries semantic execution intent for V2:+- host/tool/profile/axis kinds+- through length, host/tool dimensions, translations+- entry/exit surface participation+- expected patch roles and trim roles+- capability + diagnostics++This is intentionally semantic and bounded (not a topology graph).++## Scoring and evidence++`ThroughHoleRecoveryPolicy` uses deterministic fixed score `1000` for recognized canonical semantic through-hole with `ExactBRep` capability, intentionally above fallback bands.++Evidence includes:+- `semantic-through-hole`+- `rectangular-box-host`+- `cylindrical-tool`+- `through-hole`+- `strict-clearance`+- translation support note+- replay consistency/diagnostic note+- expected patch/trim role hints++## Rejected cases++Policy rejects and forwards recognizer reasons/diagnostics for:+- non subtract roots+- non box/cylinder operands+- blind cylinders+- tangent/grazing cuts+- unsupported transforms+- other unsupported recognizer cases++## Not included in V1B++- no BRep body construction+- no STEP export wiring+- no rematerializer/fall-forward changes+- no boolean-generic recovery+- no shell stitching / topology mutation / naming++## Next milestone (V2)++Consume `ThroughHoleRecoveryPlan` in an executor that builds exact BRep surfaces/trims for this semantic lane, then integrate into materialization pipeline with capability-gated fallback.