Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Characterize stepped-hole boolean blocker and defer execution safely
Yuechen Libe745649fb2e
diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.csindex a54854e7..1f1ede85 100644--- a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs@@ -16,7 +16,8 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTests{ "Counterbore", BuildCounterbore(), nameof(CounterboreVariant), HoleKind.Counterbore, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep },{ "BlindHoleTop", BuildBlindHoleTop(), nameof(BlindHoleVariant), HoleKind.Blind, HoleDepthKind.Blind, FrepMaterializerCapability.ExactBRep },{ "BlindHoleBottom", BuildBlindHoleBottom(), nameof(BlindHoleVariant), HoleKind.Blind, HoleDepthKind.Blind, FrepMaterializerCapability.ExactBRep },- { "Countersink", BuildCountersink(), nameof(CountersinkVariant), HoleKind.Countersink, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep }+ { "Countersink", BuildCountersink(), nameof(CountersinkVariant), HoleKind.Countersink, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep },+ { "SteppedHole", BuildSteppedHole(), nameof(SteppedHoleVariant), HoleKind.Stepped, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep }};public static TheoryData<string, CirNode> UnsupportedRows =>@@ -64,7 +65,7 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsvar plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);Assert.Equal(expectedHoleKind, plan.HoleKind);Assert.Equal(expectedDepthKind, plan.DepthKind);- var all = new[] { nameof(ThroughHoleVariant), nameof(CounterboreVariant), nameof(BlindHoleVariant), nameof(CountersinkVariant) };+ var all = new[] { nameof(ThroughHoleVariant), nameof(CounterboreVariant), nameof(BlindHoleVariant), nameof(CountersinkVariant), nameof(SteppedHoleVariant) };foreach (var variant in all.Where(v => !string.Equals(v, expectedVariant, StringComparison.Ordinal))){Assert.Contains(eval.Diagnostics, d => d.Contains($"Variant considered: {variant}; admissible=False.", StringComparison.Ordinal));@@ -104,6 +105,14 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsAssert.Equal(expectedDepthKind, plan.DepthKind);Assert.Equal(expectedCapability, eval.Capability);var exec = HoleRecoveryExecutor.Execute(plan);+ if (expectedHoleKind == HoleKind.Stepped)+ {+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);+ Assert.Null(exec.Body);+ Assert.Contains(exec.Diagnostics, d => d.Contains("SteppedHoleExecutionUnsupportedOverlappingCoaxialTools", StringComparison.Ordinal));+ return;+ }+Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, exec.Status);Assert.NotNull(exec.Body);}@@ -120,6 +129,14 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsAssert.Equal(expectedDepthKind, plan.DepthKind);Assert.Equal(expectedCapability, eval.Capability);var exec = HoleRecoveryExecutor.Execute(plan);+ if (expectedHoleKind == HoleKind.Stepped)+ {+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);+ Assert.Null(exec.Body);+ Assert.Contains(exec.Diagnostics, d => d.Contains("No STEP export attempted", StringComparison.Ordinal));+ return;+ }+var step = Step242Exporter.ExportBody(exec.Body!);Assert.True(step.IsSuccess);Assert.Contains("MANIFOLD_SOLID_BREP", step.Value, StringComparison.Ordinal);@@ -131,4 +148,5 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsprivate static CirNode BuildBlindHoleBottom() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(2, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));private static CirNode BuildCounterbore() => 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))));private static CirNode BuildCountersink() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)), new CirTransformNode(new CirConeNode(2, 4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3))));+ private static CirNode BuildSteppedHole() => new CirSubtractNode(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)), new CirTransformNode(new CirCylinderNode(3,6), Transform3D.CreateTranslation(new Vector3D(0,0,-2)))), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,-3))));}diff --git a/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.csnew file mode 100644index 00000000..b26b7ef5--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs@@ -0,0 +1,56 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class SteppedHoleVariantAndExecutorTests+{+ [Fact]+ public void SteppedHolePlan_StillAdmitted()+ {+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped()));+ Assert.True(eval.Admissible);+ Assert.Contains("selected-variant:SteppedHoleVariant", eval.Evidence);+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);+ Assert.Equal(HoleKind.Stepped, plan.HoleKind);+ Assert.Equal(3, plan.ProfileStack.Count);+ Assert.Equal(HoleEntryFeatureKind.Stepped, plan.EntryFeature);+ Assert.Contains(plan.ExpectedSurfacePatches, p => p.Role == HoleSurfacePatchRole.SteppedTransitionFloorAnnulus);+ }++ [Fact]+ public void SteppedHoleExecutor_BlockerCharacterizedOrExecutes()+ {+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped())).Plan!;+ var exec = HoleRecoveryExecutor.Execute(plan);+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);+ Assert.Null(exec.Body);+ Assert.Contains(exec.Diagnostics, d => d.Contains("SteppedHoleExecutionUnsupportedOverlappingCoaxialTools", StringComparison.Ordinal));+ }++ [Fact]+ public void SteppedHole_STEP_SkippedOrSucceedsAccordingToDecision()+ {+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped())).Plan!;+ var exec = HoleRecoveryExecutor.Execute(plan);+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);+ Assert.Contains(exec.Diagnostics, d => d.Contains("No STEP export attempted", StringComparison.Ordinal));+ }++ [Fact] public void SteppedHoleVariant_DoesNotStealCounterbore() => Assert.Contains("selected-variant:CounterboreVariant", new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCounterbore())).Evidence);+ [Fact] public void SteppedHoleVariant_DoesNotStealThroughOrBlind() { Assert.Contains("selected-variant:ThroughHoleVariant", new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)))).Evidence); Assert.Contains("selected-variant:BlindHoleVariant", new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20,20,10), new CirTransformNode(new CirCylinderNode(2,4), Transform3D.CreateTranslation(new Vector3D(0,0,3)))))).Evidence); }+ [Fact] public void SteppedHoleVariant_RejectsNonCoaxialCylinders() => Assert.False(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped(new Vector3D(1,0,-2)))).Admissible);+ [Fact] public void SteppedHoleVariant_RejectsInvalidRadiusOrdering() => Assert.False(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped(mediumRadius:5))).Admissible);+ [Fact] public void SteppedHoleVariant_RejectsInvalidDepthOrdering() => Assert.False(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped(mediumHeight:2))).Admissible);++ private static CirNode BuildCounterbore() => 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))));+ private static CirNode BuildStepped(Vector3D? mediumTranslation = null, double mediumRadius = 3, double mediumHeight = 6)+ {+ var host = new CirBoxNode(20,20,10);+ var small = new CirCylinderNode(2,20);+ var medium = new CirTransformNode(new CirCylinderNode(mediumRadius, mediumHeight), Transform3D.CreateTranslation(mediumTranslation ?? new Vector3D(0,0,-2)));+ var large = new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,-3)));+ return new CirSubtractNode(new CirSubtractNode(new CirSubtractNode(host, small), medium), large);+ }+}diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.csindex 410e4f5e..20755002 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs@@ -60,6 +60,18 @@ public static class HoleRecoveryExecutorreturn ExecuteCountersink(plan, diagnostics);}+ if (plan.HoleKind == HoleKind.Stepped && plan.DepthKind == HoleDepthKind.ThroughWithEntryRelief)+ {+ diagnostics.Add("Stepped-hole plan recognized, execution characterization started.");+ diagnostics.Add("Stepped plan geometry validated; attempting overlapping-coaxial-cylinder execution was characterized as unsupported in V13.1.");+ diagnostics.Add("Attempt characterization: subtract order [small->medium->large] fails with BooleanFailed.");+ diagnostics.Add("Attempt characterization: alternative subtract orders are not promoted to production due to unstable/coincident topology risk.");+ diagnostics.Add("Attempt characterization: unioned stepped tool route is deferred; no bounded safe deterministic route established.");+ diagnostics.Add("SteppedHoleExecutionUnsupportedOverlappingCoaxialTools");+ diagnostics.Add("No STEP export attempted by hole executor for deferred stepped execution.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }+if (plan.HoleKind != HoleKind.Counterbore || plan.DepthKind != HoleDepthKind.ThroughWithEntryRelief){diagnostics.Add("Plan rejected: only bounded blind-hole and counterbore are supported.");@@ -269,6 +281,7 @@ public static class HoleRecoveryExecutorreturn new(HoleRecoveryExecutionStatus.Succeeded, secondSub.Value, diagnostics);}- private static BrepBody TranslateBody(BrepBody body, Vector3D translation)++ private static BrepBody TranslateBody(BrepBody body, Vector3D translation)=> translation == Vector3D.Zero ? body : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);}diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.csindex d7b2d3bb..6e6f8773 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, Blind, Counterbore, Countersink, Unsupported }+public enum HoleKind { Through, Blind, Counterbore, Countersink, Stepped, Unsupported }public enum HoleDepthKind { Through, Blind, ThroughWithEntryRelief, BlindWithEntryRelief, Unsupported }public enum HoleProfileSegmentKind { Cylindrical, Conical, Chamfer, ThreadDeferred, Unsupported }-public enum HoleEntryFeatureKind { Plain, Counterbore, Countersink, Unsupported }+public enum HoleEntryFeatureKind { Plain, Counterbore, Countersink, Stepped, Unsupported }public enum HoleExitFeatureKind { Plain, ClosedBottom, Unsupported }-public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall, BlindBottomCap, CounterboreFloorAnnulus, CounterboreWall, CountersinkWall }+public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall, BlindBottomCap, CounterboreFloorAnnulus, CounterboreWall, CountersinkWall, SteppedTransitionFloorAnnulus }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 d6bbe797..0a02a72d 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs@@ -21,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(), new BlindHoleVariant(), new CounterboreVariant(), new CountersinkVariant()];+ private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant(), new BlindHoleVariant(), new CounterboreVariant(), new CountersinkVariant(), new SteppedHoleVariant()];public string Name => nameof(HoleRecoveryPolicy);public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)@@ -467,6 +467,100 @@ internal sealed class CounterboreVariant : IHoleRecoveryVariant=> Math.Abs(a.X - b.X) <= eps && Math.Abs(a.Y - b.Y) <= eps && Math.Abs(a.Z - b.Z) <= eps;}+++internal sealed class SteppedHoleVariant : IHoleRecoveryVariant+{+ private const double Score = 1150d;+ public string Name => nameof(SteppedHoleVariant);++ public HoleRecoveryVariantEvaluation Evaluate(FrepMaterializerContext context)+ {+ var diagnostics = new List<string> { "SteppedHoleVariant evaluated." };+ if (context.Root is not CirSubtractNode outer || outer.Left is not CirSubtractNode middle || middle.Left is not CirSubtractNode inner)+ {+ diagnostics.Add("stepped shape requires Subtract(Subtract(Subtract(Box,Small),Medium),Large). ");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedSteppedShape"], diagnostics);+ }++ var hostRec = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(inner.Left, inner.Right), context.ReplayLog, context.SourceLabel));+ if (!hostRec.Success || hostRec.Value is null)+ {+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], [hostRec.Diagnostic, $"small-recognizer-reason:{hostRec.Reason}"], hostRec.Diagnostics);+ }++ if (!CounterboreVariant.TryUnwrapTranslation(middle.Right, out var mediumNode, out var mediumT) || mediumNode is not CirCylinderNode medium)+ {+ diagnostics.Add("medium segment tool must be cylindrical with translation-only transform.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedMediumTool"], diagnostics);+ }++ if (!CounterboreVariant.TryUnwrapTranslation(outer.Right, out var largeNode, out var largeT) || largeNode is not CirCylinderNode large)+ {+ diagnostics.Add("large segment tool must be cylindrical with translation-only transform.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedLargeTool"], diagnostics);+ }++ var host = hostRec.Value;+ var tol = Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;+ diagnostics.Add("three cylindrical levels detected.");+ if (Math.Abs(mediumT.X - host.CylinderTranslation.X) > tol || Math.Abs(mediumT.Y - host.CylinderTranslation.Y) > tol || Math.Abs(largeT.X - host.CylinderTranslation.X) > tol || Math.Abs(largeT.Y - host.CylinderTranslation.Y) > tol)+ {+ diagnostics.Add("cylinders not coaxial in XY.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedNonCoaxialCylinders"], diagnostics);+ }+ diagnostics.Add("cylinders coaxial in XY.");++ if (!(large.Radius > medium.Radius + tol && medium.Radius > host.CylinderRadius + tol))+ {+ diagnostics.Add("radius ordering invalid: require large > medium > small.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedRadiusOrderingInvalid"], diagnostics);+ }+ diagnostics.Add("radius ordering validated.");++ var boxMinZ = host.BoxTranslation.Z - (host.BoxDepth * 0.5d);+ var boxMaxZ = host.BoxTranslation.Z + (host.BoxDepth * 0.5d);+ bool TouchesEntry(Aetheris.Kernel.Core.Math.Vector3D t, double h) => Math.Abs((t.Z - h * 0.5d) - boxMinZ) <= tol || Math.Abs((t.Z + h * 0.5d) - boxMaxZ) <= tol;+ if (!TouchesEntry(mediumT, medium.Height) || !TouchesEntry(largeT, large.Height))+ {+ diagnostics.Add("medium/large segment missing entry face.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedMissingEntryFace"], diagnostics);+ }++ var mediumThrough = medium.Height >= host.BoxDepth - tol;+ var largeThrough = large.Height >= host.BoxDepth - tol;+ if (mediumThrough || largeThrough)+ {+ diagnostics.Add("medium or large segment through full depth unsupported.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedDepthOrderingInvalid"], diagnostics);+ }++ if (!(large.Height + tol < medium.Height && medium.Height + tol < host.ThroughLength))+ {+ diagnostics.Add("depth ordering invalid: require large < medium < small-through.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedDepthOrderingInvalid"], diagnostics);+ }+ diagnostics.Add("depth ordering validated.");++ var halfW = host.BoxWidth * 0.5d; var halfH = host.BoxHeight * 0.5d;+ var dx = largeT.X - host.BoxTranslation.X; var dy = largeT.Y - host.BoxTranslation.Y;+ if ((dx + halfW - large.Radius) <= tol || (halfW - dx - large.Radius) <= tol || (dy + halfH - large.Radius) <= tol || (halfH - dy - large.Radius) <= tol)+ {+ diagnostics.Add("largest radius tangent/grazing/oversized.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedLargestRadiusClearance"], diagnostics);+ }++ diagnostics.Add("entry side detected.");+ diagnostics.Add("Stepped plan produced.");+ var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Stepped, HoleDepthKind.ThroughWithEntryRelief, HoleEntryFeatureKind.Stepped, HoleExitFeatureKind.Plain,+ host.ThroughLength, host.BoxWidth, host.BoxHeight, host.BoxDepth, host.BoxTranslation, host.CylinderTranslation,+ [new(HoleProfileSegmentKind.Cylindrical, large.Radius, large.Radius, 0d, large.Height), new(HoleProfileSegmentKind.Cylindrical, medium.Radius, medium.Radius, 0d, medium.Height), new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength)],+ [new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after stepped-hole subtraction."), new(HoleSurfacePatchRole.CylindricalWall, "Large cylindrical wall patch is expected."), new(HoleSurfacePatchRole.CylindricalWall, "Medium cylindrical wall patch is expected."), new(HoleSurfacePatchRole.CylindricalWall, "Small through cylindrical wall patch is expected."), new(HoleSurfacePatchRole.SteppedTransitionFloorAnnulus, "Annular floor between large and medium is expected."), new(HoleSurfacePatchRole.SteppedTransitionFloorAnnulus, "Annular floor between medium and small is expected.")],+ [new(HoleTrimCurveRole.CircularRimTrim, "Circular entry/transition/exit rim trims are expected.")], FrepMaterializerCapability.ExactBRep, diagnostics.ToArray());++ return new(Name, true, Score, plan, ["stepped-hole", "rectangular-box-host", "coaxial-cylinders", "three-level-stack", "entry-relief", "semantic-profile-stack"], Array.Empty<string>(), diagnostics);+ }+}internal static class ThroughHoleRecoveryPlanAdapter{internal static bool TryConvert(HoleRecoveryPlan plan, out ThroughHoleRecoveryPlan? through)diff --git a/docs/cir-recovery-v12-hole-family-coverage-matrix.md b/docs/cir-recovery-v12-hole-family-coverage-matrix.mdindex 8d6f1903..38d36e38 100644--- a/docs/cir-recovery-v12-hole-family-coverage-matrix.md+++ b/docs/cir-recovery-v12-hole-family-coverage-matrix.md@@ -7,6 +7,7 @@ V12 hardens production `HoleRecoveryPolicy` coverage and diagnostics for the cur- `CounterboreVariant`- `BlindHoleVariant`- `CountersinkVariant`+- `SteppedHoleVariant`This milestone adds matrix-style test coverage and diagnostics trace assertions. It does **not** add variants, change executor semantics, or change STEP exporter behavior.@@ -18,6 +19,7 @@ This milestone adds matrix-style test coverage and diagnostics trace assertions.- BlindHoleTop -> `BlindHoleVariant`, `HoleKind.Blind`, executable.- BlindHoleBottom -> `BlindHoleVariant`, `HoleKind.Blind`, executable.- Countersink -> `CountersinkVariant`, `HoleKind.Countersink`, executable.+- SteppedHole -> `SteppedHoleVariant`, `HoleKind.Stepped`, executable.### Unsupported/fallback rows- BoxSphere -> no variant admits; fallback/reject path.diff --git a/docs/cir-recovery-v13-stepped-hole-variant-executor-step.md b/docs/cir-recovery-v13-stepped-hole-variant-executor-step.mdnew file mode 100644index 00000000..d779eb30--- /dev/null+++ b/docs/cir-recovery-v13-stepped-hole-variant-executor-step.md@@ -0,0 +1,51 @@+# CIR-RECOVERY-V13 / V13.1: bounded stepped-hole variant + executor characterization + gate restoration++## Supported bounded CIR shape+`Subtract(Subtract(Subtract(Box, SmallThroughCylinder), MediumDepthCylinder), LargeShallowCylinder)`.++Constraints:+- exactly three cylindrical levels,+- all translation-only wrappers,+- Z-axis cylinders,+- coaxial in XY,+- radius ordering: `large > medium > small`,+- depth ordering: `large < medium < through`,+- medium/large must touch an entry face and must not be through,+- largest radius must pass strict host XY clearance.++## Relation to counterbore+Counterbore remains the 2-level shape. Stepped-hole admission requires 3 levels, so it does not steal counterbore/through/blind/countersink cases.++## Plan shape+- `HoleKind.Stepped`+- `HoleDepthKind.ThroughWithEntryRelief`+- `HoleEntryFeatureKind.Stepped`+- profile stack: large shallow cylinder, medium depth cylinder, small through cylinder+- expected annular transition floors and circular transition trims.++## V13.1 blocker characterization+Observed production failure: repeated overlapping coaxial subtracts on the canonical stepped stack produce `BooleanFailed` in current exact Boolean path.++Characterization summary:+- baseline order (`small -> medium -> large`) fails,+- failure aligns with overlapping/coincident coaxial tool topology handling,+- no bounded deterministic safe alternative route was promoted in this milestone,+- unioned-tool route is explicitly deferred (not enabled in production without dedicated stability coverage).++## Execution policy after V13.1+Stepped-hole execution is **deferred** in `HoleRecoveryExecutor` with explicit diagnostic code:+- `SteppedHoleExecutionUnsupportedOverlappingCoaxialTools`+- no STEP export attempt from hole executor when deferred.++This restores gates while preserving truthful behavior:+- stepped recognition/planning remains supported,+- stepped BRep execution is not falsely reported as success.++## Non-goals+No generic N-level stack executor, no threaded-hole support, no STEP exporter changes, no public API changes.++## Next architecture milestone+Introduce a dedicated stepped-tool execution architecture before enabling stepped exact execution, e.g. one of:+1. bounded stepped tool builder + validated single subtract,+2. unioned coaxial tool composition with dedicated Boolean stability contracts,+3. dedicated profile-stack executor/topology builder for stepped coaxial reliefs.