Skip to content

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.cs
new file mode 100644
index 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.cs
index 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.cs
index 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.md
index 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.md
new file mode 100644
index 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.