Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add counterbore hole-recovery variant with plan-only semantics
Yuechen Li6030f6cfd311
diff --git a/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.cs b/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.csnew file mode 100644index 00000000..873897c7--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.cs@@ -0,0 +1,89 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class CounterboreVariantTests+{+ [Fact]+ public void CounterboreVariant_AdmitsSimpleBoxCounterborePlan()+ {+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalCounterbore()));+ Assert.True(eval.Admissible);+ Assert.Contains("selected-variant:CounterboreVariant", eval.Evidence);+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);+ Assert.Equal(HoleKind.Counterbore, plan.HoleKind);+ Assert.Equal(HoleDepthKind.ThroughWithEntryRelief, plan.DepthKind);+ Assert.Equal(2, plan.ProfileStack.Count);+ Assert.True(plan.ProfileStack[0].RadiusStart > plan.ProfileStack[1].RadiusStart);+ Assert.Contains(plan.ExpectedSurfacePatches, p => p.Role == HoleSurfacePatchRole.CounterboreFloorAnnulus);+ Assert.Contains(plan.ExpectedSurfacePatches, p => p.Role == HoleSurfacePatchRole.CounterboreWall);+ }++ [Fact]+ public void CounterboreVariant_RejectsSimpleThroughHole()+ {+ var eval = new HoleRecoveryPolicy().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);+ }++ [Fact]+ public void CounterboreVariant_RejectsNonCoaxialCylinders()+ {+ var root = new CirSubtractNode(+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),+ new CirTransformNode(new CirCylinderNode(4, 4), Transform3D.CreateTranslation(new Vector3D(1, 0, -3))));+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root));+ Assert.False(eval.Evidence.Contains("selected-variant:CounterboreVariant"));+ Assert.Contains("coaxial", string.Join("|", eval.EvaluationsFor(nameof(CounterboreVariant))).ToLowerInvariant());+ }++ [Fact]+ public void Rematerializer_CounterborePlan_DoesNotFalseSucceedWithoutExecutor()+ {+ var result = FrepSemanticRecoveryRematerializer.TryRecover(BuildCanonicalCounterbore());+ Assert.False(result.Succeeded);+ Assert.Null(result.Body);+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, result.ExecutionStatus);+ Assert.Contains(result.Diagnostics, d => d.Contains("selected policy: HoleRecoveryPolicy", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("non-executable", StringComparison.Ordinal));+ }+++ [Fact]+ public void CounterboreVariant_RejectsLargeRadiusNotGreaterThanSmall()+ {+ var root = new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(3, 20)), new CirTransformNode(new CirCylinderNode(3, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root));+ Assert.Contains("radius", string.Join("|", eval.EvaluationsFor(nameof(CounterboreVariant))).ToLowerInvariant());+ }++ [Fact]+ public void CounterboreVariant_RejectsLargeCylinderThroughFullDepth()+ {+ var root = new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)), new CirCylinderNode(4, 20));+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root));+ Assert.Contains("not a counterbore relief", string.Join("|", eval.EvaluationsFor(nameof(CounterboreVariant))).ToLowerInvariant());+ }++ [Fact]+ public void CounterboreVariant_RejectsSmallCylinderNotThrough()+ {+ var root = new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 6)), new CirTransformNode(new CirCylinderNode(4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root));+ Assert.DoesNotContain("selected-variant:CounterboreVariant", eval.Evidence);+ }++ private static CirNode BuildCanonicalCounterbore()+ => new CirSubtractNode(+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),+ new CirTransformNode(new CirCylinderNode(4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));+}++internal static class HoleRecoveryPolicyEvalExtensions+{+ public static IReadOnlyList<string> EvaluationsFor(this FrepMaterializerPolicyEvaluation eval, string variantName)+ => eval.Diagnostics.Where(d => d.StartsWith($"variant:{variantName}:", StringComparison.Ordinal)).ToArray();+}diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.csindex 46f77b6a..d693cce2 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs@@ -4,12 +4,12 @@ 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 HoleKind { Through, Counterbore, Unsupported }+public enum HoleDepthKind { Through, Blind, ThroughWithEntryRelief, Unsupported }public enum HoleProfileSegmentKind { Cylindrical, Conical, Chamfer, ThreadDeferred, Unsupported }-public enum HoleEntryFeatureKind { Plain, Unsupported }+public enum HoleEntryFeatureKind { Plain, Counterbore, Unsupported }public enum HoleExitFeatureKind { Plain, Unsupported }-public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall }+public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall, CounterboreFloorAnnulus, CounterboreWall }public enum HoleTrimCurveRole { CircularRimTrim, Deferred }public sealed record HoleProfileSegment(HoleProfileSegmentKind SegmentKind, double RadiusStart, double RadiusEnd, double DepthStart, double DepthEnd);diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.csindex 749d1d52..3ccfc05f 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs@@ -1,3 +1,4 @@+using Aetheris.Kernel.Core.Cir;using Aetheris.Kernel.Core.Judgment;namespace Aetheris.Kernel.Firmament.Materializer;@@ -20,7 +21,7 @@ public sealed record HoleRecoveryVariantEvaluation(public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy{private static readonly JudgmentEngine<FrepMaterializerContext> VariantEngine = new();- private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant()];+ private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant(), new CounterboreVariant()];public string Name => nameof(HoleRecoveryPolicy);public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)@@ -75,6 +76,131 @@ internal sealed class ThroughHoleVariant : IHoleRecoveryVariant}}++internal sealed class CounterboreVariant : IHoleRecoveryVariant+{+ private const double Score = 1100d;+ public string Name => nameof(CounterboreVariant);++ public HoleRecoveryVariantEvaluation Evaluate(FrepMaterializerContext context)+ {+ if (context.Root is not CirSubtractNode outerSubtract)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedRootNotNestedSubtract"], ["Root must be nested subtract for counterbore."]);+ }++ if (outerSubtract.Left is not CirSubtractNode innerSubtract)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedCounterboreShape"], ["Counterbore requires Subtract(Subtract(host,small),large) structure."]);+ }++ var hostRec = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(innerSubtract.Left, innerSubtract.Right), context.ReplayLog, context.SourceLabel));+ if (!hostRec.Success || hostRec.Value is null)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], [hostRec.Diagnostic, $"small-recognizer-reason:{hostRec.Reason}"], hostRec.Diagnostics);+ }++ var shallowRec = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(innerSubtract.Left, outerSubtract.Right), context.ReplayLog, context.SourceLabel));+ if (shallowRec.Success)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedLargeCylinderThroughFullDepth"], ["Large cylinder spans full host depth and is not a counterbore relief."]);+ }++ if (shallowRec.Reason is not CirBoxCylinderRecognitionReason.UnsupportedNotThroughHole)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], [shallowRec.Diagnostic, $"large-recognizer-reason:{shallowRec.Reason}"], shallowRec.Diagnostics);+ }++ if (!TryUnwrapTranslation(outerSubtract.Right, out var largeNode, out var largeTranslation) || largeNode is not CirCylinderNode largeCylinder)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedLargeTool"], ["Counterbore relief tool must be cylindrical with translation-only transform."]);+ }++ var host = hostRec.Value;+ var tol = Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;+ if (Math.Abs(largeTranslation.X - host.CylinderTranslation.X) > tol || Math.Abs(largeTranslation.Y - host.CylinderTranslation.Y) > tol)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedNonCoaxialCylinders"], ["Counterbore relief cylinder must be coaxial with through cylinder in XY."]);+ }++ if (largeCylinder.Radius <= host.CylinderRadius + tol)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedLargeRadiusNotGreaterThanSmall"], ["Counterbore relief radius must be greater than through radius."]);+ }++ var boxMinZ = host.BoxTranslation.Z - (host.BoxDepth * 0.5d);+ var boxMaxZ = host.BoxTranslation.Z + (host.BoxDepth * 0.5d);+ var largeMinZ = largeTranslation.Z - (largeCylinder.Height * 0.5d);+ var largeMaxZ = largeTranslation.Z + (largeCylinder.Height * 0.5d);+ var touchesEntry = Math.Abs(largeMinZ - boxMinZ) <= tol || Math.Abs(largeMaxZ - boxMaxZ) <= tol;+ if (!touchesEntry)+ {+ return new(Name, false, 0d, null, ["counterbore", "rectangular-box-host"], ["UnsupportedMissingEntryFace"], ["Counterbore relief must enter from a host entry face."]);+ }++ var floorDepth = Math.Min(largeCylinder.Height, host.BoxDepth);+ var evidence = new List<string> { "counterbore", "rectangular-box-host", "coaxial-cylinders", "entry-relief", "through-core", "planned-exact-no-executor" };+ var plan = new HoleRecoveryPlan(+ HoleHostKind.RectangularBox,+ HoleAxisKind.Z,+ HoleKind.Counterbore,+ HoleDepthKind.ThroughWithEntryRelief,+ HoleEntryFeatureKind.Counterbore,+ HoleExitFeatureKind.Plain,+ host.ThroughLength,+ host.BoxWidth,+ host.BoxHeight,+ host.BoxDepth,+ host.BoxTranslation,+ host.CylinderTranslation,+ [+ new(HoleProfileSegmentKind.Cylindrical, largeCylinder.Radius, largeCylinder.Radius, 0d, floorDepth),+ new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength)+ ],+ [+ new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after counterbore subtraction."),+ new(HoleSurfacePatchRole.CounterboreFloorAnnulus, "Counterbore relief floor annulus is expected."),+ new(HoleSurfacePatchRole.CounterboreWall, "Larger-radius shallow cylindrical wall patch is expected."),+ new(HoleSurfacePatchRole.CylindricalWall, "Smaller-radius through cylindrical wall patch is expected.")+ ],+ [new(HoleTrimCurveRole.CircularRimTrim, "Circular trims at counterbore rim and through core transitions are expected.")],+ FrepMaterializerCapability.ExactBRep,+ ["Counterbore variant plan produced; executor support pending."]);++ return new(Name, true, Score, plan, evidence, Array.Empty<string>(), ["CounterboreVariant admitted canonical nested subtract pattern."]);+ }++ private static bool TryUnwrapTranslation(Aetheris.Kernel.Core.Cir.CirNode node, out Aetheris.Kernel.Core.Cir.CirNode unwrapped, out Aetheris.Kernel.Core.Math.Vector3D translation)+ {+ unwrapped = node;+ translation = Aetheris.Kernel.Core.Math.Vector3D.Zero;+ while (unwrapped is Aetheris.Kernel.Core.Cir.CirTransformNode transformNode)+ {+ var origin = transformNode.Transform.Apply(Aetheris.Kernel.Core.Math.Point3D.Origin);+ var x = transformNode.Transform.Apply(new Aetheris.Kernel.Core.Math.Point3D(1d, 0d, 0d));+ var y = transformNode.Transform.Apply(new Aetheris.Kernel.Core.Math.Point3D(0d, 1d, 0d));+ var z = transformNode.Transform.Apply(new Aetheris.Kernel.Core.Math.Point3D(0d, 0d, 1d));+ const double eps = 1e-9d;+ if (!NearlyEqual(x - origin, new Aetheris.Kernel.Core.Math.Vector3D(1d, 0d, 0d), eps)+ || !NearlyEqual(y - origin, new Aetheris.Kernel.Core.Math.Vector3D(0d, 1d, 0d), eps)+ || !NearlyEqual(z - origin, new Aetheris.Kernel.Core.Math.Vector3D(0d, 0d, 1d), eps))+ {+ unwrapped = node;+ translation = Aetheris.Kernel.Core.Math.Vector3D.Zero;+ return false;+ }++ translation += origin - Aetheris.Kernel.Core.Math.Point3D.Origin;+ unwrapped = transformNode.Child;+ }++ return true;+ }++ private static bool NearlyEqual(Aetheris.Kernel.Core.Math.Vector3D a, Aetheris.Kernel.Core.Math.Vector3D b, double eps)+ => Math.Abs(a.X - b.X) <= eps && Math.Abs(a.Y - b.Y) <= eps && Math.Abs(a.Z - b.Z) <= eps;+}+internal static class ThroughHoleRecoveryPlanAdapter{internal static bool TryConvert(HoleRecoveryPlan plan, out ThroughHoleRecoveryPlan? through)diff --git a/docs/cir-recovery-v6-hole-recovery-policy.md b/docs/cir-recovery-v6-hole-recovery-policy.mdindex 25d8298d..2fc88ac3 100644--- a/docs/cir-recovery-v6-hole-recovery-policy.md+++ b/docs/cir-recovery-v6-hole-recovery-policy.md@@ -47,3 +47,8 @@ To add counterbore/countersink/blind-hole:- No new BRep executor algorithms- No STEP exporter behavior changes- No public CLI/API surface changes+++## Update note (V7A)++`HoleRecoveryPolicy` now composes multiple hole-family variants (`ThroughHoleVariant`, `CounterboreVariant`) via JudgmentEngine, preserving the same policy-level integration boundary.diff --git a/docs/cir-recovery-v7a-counterbore-variant-plan.md b/docs/cir-recovery-v7a-counterbore-variant-plan.mdnew file mode 100644index 00000000..dcad903a--- /dev/null+++ b/docs/cir-recovery-v7a-counterbore-variant-plan.md@@ -0,0 +1,74 @@+# CIR-RECOVERY-V7A: CounterboreVariant recognition + HoleRecoveryPlan only++## Scope++V7A adds a bounded `CounterboreVariant` under `HoleRecoveryPolicy`.++- Included: CIR recognition for canonical counterbore-like nested subtracts and semantic `HoleRecoveryPlan` emission.+- Excluded: counterbore BRep executor, STEP export updates, public API changes.++## Supported CIR shape++Primary admitted shape:++`Subtract(Subtract(Box, SmallThroughCylinder), LargeShallowCylinder)`++With constraints:++- host is `CirBoxNode` (translation wrappers allowed),+- both tools are `CirCylinderNode` (translation wrappers allowed),+- cylinders are coaxial in XY,+- `Large.Radius > Small.Radius`,+- small cylinder is through-hole relative to host depth,+- large cylinder is blind/shallow and touches one entry side of host.++## Semantic plan shape++Admitted variant produces `HoleRecoveryPlan` with:++- `HoleKind = Counterbore`+- `DepthKind = ThroughWithEntryRelief`+- `EntryFeature = Counterbore`+- profile stack of two cylindrical segments:+ 1. larger-radius shallow segment,+ 2. smaller-radius through segment.++Expected topology semantics include:++- retained host planar faces,+- counterbore floor annulus,+- counterbore wall,+- through cylindrical wall,+- circular rim trims.++## Rejection behavior++`CounterboreVariant` rejects:++- non-nested subtract shapes,+- non-box host or non-cylinder tools,+- unsupported transforms,+- non-coaxial cylinders,+- `Large.Radius <= Small.Radius`,+- large cylinder through full depth,+- large cylinder that does not touch an entry face,+- any inner small-cylinder case that is not a valid through-hole.++## Rematerializer behavior in V7A++The rematerializer may select `CounterboreVariant` and extract a `HoleRecoveryPlan`, but conversion to `ThroughHoleRecoveryExecutor` contract intentionally fails with unsupported-plan diagnostics. No false BRep success is claimed.++## Locality of change++V7A remains local to hole policy variant composition:++- add `CounterboreVariant`,+- register in `HoleRecoveryPolicy` variant list,+- extend semantic hole enums minimally for counterbore plan vocabulary,+- add focused tests.++No planner, catalog architecture, or executor implementation changes are required.++## V7B recommendation++Implement a dedicated counterbore executor adapter/contract that consumes `HoleRecoveryPlan(HoleKind.Counterbore)` and emits bounded exact BRep for the admitted canonical shape.