Skip to content

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.cs
index 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 HoleRecoveryPolicyCoverageMatrixTests
var 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 HoleRecoveryPolicyCoverageMatrixTests
Assert.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 HoleRecoveryPolicyCoverageMatrixTests
Assert.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 HoleRecoveryPolicyCoverageMatrixTests
private 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.cs
new file mode 100644
index 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.cs
index 410e4f5e..20755002 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
@@ -60,6 +60,18 @@ public static class HoleRecoveryExecutor
return 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 HoleRecoveryExecutor
return 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.cs
index 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.cs
index 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.md
index 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.md
new file mode 100644
index 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.