Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Format placement-driven tests in standard C# block style

Yuechen Lida353f54de18
diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryExecutorPlacementDrivenTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryExecutorPlacementDrivenTests.cs
new file mode 100644
index 00000000..abf7319d
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryExecutorPlacementDrivenTests.cs
@@ -0,0 +1,128 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class HoleRecoveryExecutorPlacementDrivenTests
+{
+ [Fact]
+ public void PlacementDriven_BlindHole_UsesSegmentZSpan()
+ {
+ var plan = (HoleRecoveryPlan)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))))))
+ .Plan!;
+
+ var result = HoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("placement-driven segment=blind-cylinder", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void PlacementDriven_Counterbore_UsesSegmentZSpans()
+ {
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy()
+ .Evaluate(new FrepMaterializerContext(
+ 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))))))
+ .Plan!;
+
+ var result = HoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("segment=counterbore-through", StringComparison.Ordinal));
+ Assert.Contains(result.Diagnostics, d => d.Contains("segment=counterbore-relief", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void PlacementDriven_Countersink_UsesConeSegmentZSpan()
+ {
+ var cone = new CirTransformNode(new CirConeNode(2, 4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3)));
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy()
+ .Evaluate(new FrepMaterializerContext(
+ new CirSubtractNode(
+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),
+ cone)))
+ .Plan!;
+
+ var result = HoleRecoveryExecutor.Execute(plan);
+ var step = Step242Exporter.ExportBody(result.Body!);
+
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("segment=cone", StringComparison.Ordinal));
+ Assert.True(step.IsSuccess);
+ }
+
+ [Fact]
+ public void PlacementDriven_ChamferedEntryTopBottom_UsesConeSegmentZSpan()
+ {
+ var top = new CirSubtractNode(
+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),
+ new CirTransformNode(new CirConeNode(2, 2.8, 1), Transform3D.CreateTranslation(new Vector3D(0, 0, 4.5))));
+
+ var bottom = new CirSubtractNode(
+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),
+ new CirTransformNode(new CirConeNode(2.8, 2, 1), Transform3D.CreateTranslation(new Vector3D(0, 0, -4.5))));
+
+ var topResult = HoleRecoveryExecutor.Execute((HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(top)).Plan!);
+ var bottomResult = HoleRecoveryExecutor.Execute((HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(bottom)).Plan!);
+
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, topResult.Status);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, bottomResult.Status);
+ Assert.Contains(topResult.Diagnostics, d => d.Contains("segment=chamfer cone", StringComparison.Ordinal));
+ Assert.Contains(bottomResult.Diagnostics, d => d.Contains("segment=chamfer cone", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void PlacementDriven_InvalidSegmentRejectsBeforeBoolean()
+ {
+ var plan = new HoleRecoveryPlan(
+ HoleHostKind.RectangularBox,
+ HoleAxisKind.Z,
+ HoleKind.Blind,
+ HoleDepthKind.Blind,
+ HoleEntryFeatureKind.Plain,
+ HoleExitFeatureKind.ClosedBottom,
+ 4,
+ 20,
+ 20,
+ 10,
+ Vector3D.Zero,
+ Vector3D.Zero,
+ [new(HoleProfileSegmentKind.Cylindrical, 2, 2, 0, 4, HoleTierAnchorSide.Unknown, 4, 1, 1, false, ["x"])],
+ [],
+ [],
+ FrepMaterializerCapability.ExactBRep,
+ []);
+
+ var result = HoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("placement-validation-failed", StringComparison.Ordinal));
+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("subtract invoked", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PlacementDriven_SteppedPlacementValidatedButExecutionStillDeferred()
+ {
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(
+ 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))))));
+
+ var result = HoleRecoveryExecutor.Execute((HoleRecoveryPlan)eval.Plan!);
+
+ Assert.NotEqual(HoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("Stepped explicit-placement validation succeeded", StringComparison.Ordinal));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
index 029cfaef..53333344 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
@@ -110,17 +110,12 @@ public static class HoleRecoveryExecutor
var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
- var throughHeight = double.Max(plan.ThroughLength, plan.HostSizeZ);
- var smallResult = BrepPrimitives.CreateCylinder(small.RadiusStart, throughHeight);
- if (!smallResult.IsSuccess)
+ if (!TryBuildPlacementCylinderTool(plan, small, "counterbore-through", diagnostics, out var smallBody) || smallBody is null)
{
- diagnostics.Add("Small through cylinder primitive construction failed.");
- return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ diagnostics.Add("Counterbore plan rejected before Boolean: placement-driven through segment failed.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
- var smallBody = TranslateBody(smallResult.Value, plan.ToolTranslation);
- diagnostics.Add("Small through cylinder constructed.");
-
var firstSubtract = BrepBoolean.Subtract(boxBody, smallBody);
if (!firstSubtract.IsSuccess || firstSubtract.Value is null)
{
@@ -130,27 +125,12 @@ public static class HoleRecoveryExecutor
diagnostics.Add("First subtract succeeded.");
- var shallowDepth = large.DepthEnd - large.DepthStart;
- if (shallowDepth <= tolerance)
+ if (!TryBuildPlacementCylinderTool(plan, large, "counterbore-relief", diagnostics, out var largeBody) || largeBody is null)
{
- diagnostics.Add("Plan rejected: counterbore shallow depth must be positive.");
+ diagnostics.Add("Counterbore plan rejected before Boolean: placement-driven relief segment failed.");
return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
- var entryFaceZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);
- var largeCenterZ = entryFaceZ + (shallowDepth * 0.5d);
- var largeToolTranslation = new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, largeCenterZ);
-
- var largeResult = BrepPrimitives.CreateCylinder(large.RadiusStart, shallowDepth);
- if (!largeResult.IsSuccess)
- {
- diagnostics.Add("Large counterbore cylinder primitive construction failed.");
- return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
- }
-
- var largeBody = TranslateBody(largeResult.Value, largeToolTranslation);
- diagnostics.Add("Large counterbore cylinder constructed.");
-
var secondSubtract = BrepBoolean.Subtract(firstSubtract.Value, largeBody);
if (!secondSubtract.IsSuccess || secondSubtract.Value is null)
{
@@ -165,6 +145,85 @@ public static class HoleRecoveryExecutor
+ private static bool TryBuildPlacementCylinderTool(HoleRecoveryPlan plan, HoleProfileSegment segment, string role, List<string> diagnostics, out BrepBody? body)
+ {
+ body = null;
+ if (!TryValidateExecutablePlacement(plan, segment, role, diagnostics, out var height, out var centerZ)) return false;
+ var cylinder = BrepPrimitives.CreateCylinder(segment.RadiusStart, height);
+ if (!cylinder.IsSuccess)
+ {
+ diagnostics.Add($"hole-executor: primitive-failed segment={role} kind=cylinder radius={segment.RadiusStart:0.###} height={height:0.###}");
+ return false;
+ }
+
+ body = TranslateBody(cylinder.Value, new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, centerZ));
+ diagnostics.Add($"hole-executor: placement-driven segment={role} anchor={segment.AnchorSide} zMin={segment.ZMin:0.###} zMax={segment.ZMax:0.###} height={height:0.###} centerZ={centerZ:0.###}");
+ diagnostics.Add($"Blind cylinder constructed with entry side {(segment.AnchorSide == HoleTierAnchorSide.Top ? "top(+Z)" : segment.AnchorSide == HoleTierAnchorSide.Bottom ? "bottom(-Z)" : "through")}.");
+ return true;
+ }
+
+ private static bool TryBuildPlacementConeTool(HoleRecoveryPlan plan, HoleProfileSegment segment, string role, string coneLabel, List<string> diagnostics, out BrepBody? body)
+ {
+ body = null;
+ if (!TryValidateExecutablePlacement(plan, segment, role, diagnostics, out var height, out var centerZ)) return false;
+ var cone = FirmamentPrimitiveExecutor.ExecuteCone(new FirmamentLoweredConeParameters(segment.RadiusEnd, segment.RadiusStart, height));
+ if (!cone.IsSuccess)
+ {
+ diagnostics.Add($"hole-executor: primitive-failed segment={role} kind={coneLabel} rBottom={segment.RadiusEnd:0.###} rTop={segment.RadiusStart:0.###} height={height:0.###}");
+ return false;
+ }
+
+ body = TranslateBody(cone.Value, new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, centerZ));
+ diagnostics.Add($"hole-executor: placement-driven segment={role} anchor={segment.AnchorSide} zMin={segment.ZMin:0.###} zMax={segment.ZMax:0.###} height={height:0.###} centerZ={centerZ:0.###}");
+ diagnostics.Add($"entry side resolved for {coneLabel}: {(segment.AnchorSide == HoleTierAnchorSide.Top ? "top(+Z)" : segment.AnchorSide == HoleTierAnchorSide.Bottom ? "bottom(-Z)" : "through") }.");
+ return true;
+ }
+
+ private static bool TryValidateExecutablePlacement(HoleRecoveryPlan plan, HoleProfileSegment segment, string role, List<string> diagnostics, out double height, out double centerZ)
+ {
+ height = 0d; centerZ = 0d;
+ var tol = Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;
+ var hostMinZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);
+ var hostMaxZ = plan.HostTranslation.Z + (plan.HostSizeZ * 0.5d);
+
+ if (segment.PlacementDiagnostics is null || segment.PlacementDiagnostics.Count == 0)
+ {
+ diagnostics.Add($"hole-executor: placement-validation-failed segment={role} reason=missing-placement-diagnostics");
+ return false;
+ }
+
+ if (double.IsNaN(segment.ZMin) || double.IsNaN(segment.ZMax) || segment.ZMax - segment.ZMin <= tol)
+ {
+ diagnostics.Add($"hole-executor: placement-validation-failed segment={role} reason=invalid-z-span zMin={segment.ZMin:0.###} zMax={segment.ZMax:0.###}");
+ return false;
+ }
+
+ height = segment.ZMax - segment.ZMin;
+ centerZ = (segment.ZMin + segment.ZMax) * 0.5d;
+
+ if (segment.IsThrough)
+ {
+ if (segment.AnchorSide != HoleTierAnchorSide.Through)
+ {
+ diagnostics.Add($"hole-executor: placement-validation-failed segment={role} reason=through-anchor-mismatch anchor={segment.AnchorSide}");
+ return false;
+ }
+
+ if (segment.ZMin > hostMinZ + tol || segment.ZMax < hostMaxZ - tol)
+ {
+ diagnostics.Add($"hole-executor: placement-validation-failed segment={role} reason=through-z-coverage hostZMin={hostMinZ:0.###} hostZMax={hostMaxZ:0.###}");
+ return false;
+ }
+ }
+ else if (segment.AnchorSide != HoleTierAnchorSide.Top && segment.AnchorSide != HoleTierAnchorSide.Bottom)
+ {
+ diagnostics.Add($"hole-executor: placement-validation-failed segment={role} reason=blind-anchor-invalid anchor={segment.AnchorSide}");
+ return false;
+ }
+
+ return true;
+ }
+
private static HoleRecoveryExecutionResult ExecuteStepped(HoleRecoveryPlan plan, List<string> diagnostics)
{
diagnostics.Add("Stepped explicit-placement validation started.");
@@ -338,35 +397,20 @@ public static class HoleRecoveryExecutor
return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
- var depth = seg.DepthEnd - seg.DepthStart;
- if (depth <= Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear)
- {
- diagnostics.Add("Blind plan rejected: depth must be positive.");
- return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
- }
-
- var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);
+ var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);
if (!boxResult.IsSuccess)
{
diagnostics.Add("Blind-hole box primitive construction failed.");
return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
}
- var toolResult = BrepPrimitives.CreateCylinder(seg.RadiusStart, depth);
- if (!toolResult.IsSuccess)
+ var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
+ if (!TryBuildPlacementCylinderTool(plan, seg, "blind-cylinder", diagnostics, out var toolBody) || toolBody is null)
{
- diagnostics.Add("Blind-hole cylinder primitive construction failed.");
- return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ diagnostics.Add("Blind plan rejected before Boolean: placement-driven construction failed.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
- var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
- var entryTopZ = plan.HostTranslation.Z + (plan.HostSizeZ * 0.5d);
- var entryBottomZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);
- var touchTop = Math.Abs((plan.ToolTranslation.Z + (depth * 0.5d)) - entryTopZ) <= Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;
- var centerZ = touchTop ? entryTopZ - (depth * 0.5d) : entryBottomZ + (depth * 0.5d);
- var toolBody = TranslateBody(toolResult.Value, new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, centerZ));
- diagnostics.Add($"Blind cylinder constructed with entry side {(touchTop ? "top(+Z)" : "bottom(-Z)")}.");
-
var sub = BrepBoolean.Subtract(boxBody, toolBody);
diagnostics.Add("Blind subtract invoked.");
if (!sub.IsSuccess || sub.Value is null)
@@ -400,15 +444,18 @@ public static class HoleRecoveryExecutor
}
var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);
- var cylResult = BrepPrimitives.CreateCylinder(cylSeg.RadiusStart, double.Max(plan.ThroughLength, plan.HostSizeZ));
- if (!boxResult.IsSuccess || !cylResult.IsSuccess)
+ if (!boxResult.IsSuccess)
{
- diagnostics.Add("Countersink primitive construction failed for host/cylinder.");
+ diagnostics.Add("Countersink primitive construction failed for host.");
return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
}
var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
- var cylBody = TranslateBody(cylResult.Value, plan.ToolTranslation);
+ if (!TryBuildPlacementCylinderTool(plan, cylSeg, "entry-cylinder", diagnostics, out var cylBody) || cylBody is null)
+ {
+ diagnostics.Add("Countersink plan rejected before Boolean: placement-driven cylinder segment failed.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
diagnostics.Add("cylinder subtract invoked.");
var firstSub = BrepBoolean.Subtract(boxBody, cylBody);
if (!firstSub.IsSuccess || firstSub.Value is null)
@@ -418,20 +465,11 @@ public static class HoleRecoveryExecutor
}
diagnostics.Add("cylinder subtract succeeded.");
- var coneHeight = coneSeg.DepthEnd - coneSeg.DepthStart;
- var coneResult = FirmamentPrimitiveExecutor.ExecuteCone(new FirmamentLoweredConeParameters(coneSeg.RadiusEnd, coneSeg.RadiusStart, coneHeight));
- if (!coneResult.IsSuccess)
+ if (!TryBuildPlacementConeTool(plan, coneSeg, coneLabel, coneLabel, diagnostics, out var coneBody) || coneBody is null)
{
- diagnostics.Add($"{coneLabel} primitive construction failed.");
- return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ diagnostics.Add($"{coneLabel} plan rejected before Boolean: placement-driven cone segment failed.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
-
- var entryTopZ = plan.HostTranslation.Z + (plan.HostSizeZ * 0.5d);
- var entryBottomZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);
- var touchesTop = Math.Abs((plan.ToolTranslation.Z + (coneHeight * 0.5d)) - entryTopZ) <= Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;
- var coneCenterZ = touchesTop ? entryTopZ - (coneHeight * 0.5d) : entryBottomZ + (coneHeight * 0.5d);
- var coneBody = TranslateBody(coneResult.Value, new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, coneCenterZ));
- diagnostics.Add($"entry side resolved for {coneLabel}: {(touchesTop ? "top(+Z)" : "bottom(-Z)") }.");
diagnostics.Add($"{coneLabel} subtract invoked.");
var secondSub = BrepBoolean.Subtract(firstSub.Value, coneBody);
if (!secondSub.IsSuccess || secondSub.Value is null)
diff --git a/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md b/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md
index 145cf587..c0a9fd7b 100644
--- a/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md
+++ b/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md
@@ -37,3 +37,8 @@ No new variants, no STEP exporter changes, no public API changes, no generic pro
## Next milestone recommendation
CIR-RECOVERY-V18: centralize segment-role taxonomy and validator-backed role/placement compatibility checks.
+
+## V18 executor consumption status
+- Blind/counterbore/countersink/chamfered-entry execution now consumes explicit segment placement in executor construction.
+- Through-hole remains delegated unchanged in V18 for low-risk compatibility.
+- Stepped remains deferred but placement-validated for future activation.
diff --git a/docs/cir-recovery-v18-placement-driven-executor-harmonization.md b/docs/cir-recovery-v18-placement-driven-executor-harmonization.md
new file mode 100644
index 00000000..fab2d7a9
--- /dev/null
+++ b/docs/cir-recovery-v18-placement-driven-executor-harmonization.md
@@ -0,0 +1,46 @@
+# CIR-RECOVERY-V18: placement-driven hole executor harmonization
+
+## Purpose
+Harden executor contract consumption so hole-family execution uses explicit `HoleProfileSegment` placement (`AnchorSide`, `ZMin`, `ZMax`, `IsThrough`, `PlacementDiagnostics`) as plan source-of-truth, instead of recomputing placement from variant folklore.
+
+## Executor placement contract
+- Tool height = `segment.ZMax - segment.ZMin`.
+- Tool center Z = `(segment.ZMin + segment.ZMax)/2`.
+- XY translation remains from plan `ToolTranslation`.
+- Through semantics must be explicit (`IsThrough=true`, `AnchorSide=Through`, host z coverage).
+- Blind semantics must be explicit (`AnchorSide=Top|Bottom`).
+
+## Helper shape
+`HoleRecoveryExecutor` now includes compact internal placement helpers:
+- `TryValidateExecutablePlacement(...)`
+- `TryBuildPlacementCylinderTool(...)`
+- `TryBuildPlacementConeTool(...)`
+
+## Converted executor paths
+- Blind-hole cylinder path consumes `ZMin/ZMax`.
+- Counterbore small-through + large-relief cylinders consume `ZMin/ZMax`.
+- Countersink and chamfered-entry cylinder + cone segments consume `ZMin/ZMax`.
+
+## Unchanged paths
+- Through-hole still delegates through `ThroughHoleRecoveryPlanAdapter` to `ThroughHoleRecoveryExecutor` for low-risk behavior preservation in V18.
+- Stepped-hole remains intentionally not production-enabled; V18 keeps explicit placement validation diagnostics and current deferred/non-success execution behavior.
+
+## Validation and diagnostics
+Validation occurs before boolean subtract on converted paths; failures return `UnsupportedPlan` with explicit `hole-executor: placement-validation-failed ...` diagnostics.
+
+Stable breadcrumb:
+`hole-executor: placement-driven segment=<role> anchor=<side> zMin=<...> zMax=<...>`
+
+## Future author rules
+Executor rules:
+1. Use segment ZMin/ZMax to construct tool height and center.
+2. Validate placement before Boolean.
+3. Do not infer anchor side from radius order or variant name.
+4. Unknown anchor is not executable.
+5. New variants must add placement-driven executor tests.
+
+## Non-goals
+- No new hole variant.
+- No stepped-hole re-enable.
+- No generic profile-stack executor.
+- No STEP exporter behavior/API changes.