Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-RECOVERY-V17 harmonize hole-family placement semantics

Yuechen Liac78937749f4
diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPlacementSemanticsTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPlacementSemanticsTests.cs
new file mode 100644
index 00000000..0e5c8625
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPlacementSemanticsTests.cs
@@ -0,0 +1,85 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class HoleRecoveryPlacementSemanticsTests
+{
+ public static IEnumerable<object[]> Cases()
+ {
+ yield return ["through-hole", BuildThrough(), HoleKind.Through];
+ yield return ["counterbore", BuildCounterbore(), HoleKind.Counterbore];
+ yield return ["blind-top", BuildBlindTop(), HoleKind.Blind];
+ yield return ["blind-bottom", BuildBlindBottom(), HoleKind.Blind];
+ yield return ["countersink", BuildCountersink(), HoleKind.Countersink];
+ yield return ["chamfer-top", BuildChamferTop(), HoleKind.ChamferedEntry];
+ yield return ["chamfer-bottom", BuildChamferBottom(), HoleKind.ChamferedEntry];
+ yield return ["stepped", BuildStepped(), HoleKind.Stepped];
+ }
+
+ [Theory]
+ [MemberData(nameof(Cases))]
+ public void PlacementSemantics_AllSupportedVariants_PopulateExplicitPlacement(string _, CirNode root, HoleKind kind)
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan);
+ Assert.Equal(kind, plan.HoleKind);
+ foreach (var s in plan.ProfileStack)
+ {
+ Assert.NotEqual(HoleTierAnchorSide.Unknown, s.AnchorSide);
+ Assert.False(double.IsNaN(s.ZMin));
+ Assert.False(double.IsNaN(s.ZMax));
+ Assert.True(s.ZMax > s.ZMin);
+ Assert.NotNull(s.PlacementDiagnostics);
+ Assert.NotEmpty(s.PlacementDiagnostics!);
+ }
+ }
+
+ [Fact]
+ public void PlacementSemantics_ThroughSegments_AreExplicitlyThrough()
+ {
+ foreach (var root in new[] { BuildThrough(), BuildCounterbore(), BuildStepped(), BuildChamferTop(), BuildCountersink() })
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan);
+ foreach (var s in plan.ProfileStack.Where(x => x.IsThrough))
+ {
+ Assert.Equal(HoleTierAnchorSide.Through, s.AnchorSide);
+ }
+ }
+ }
+
+ [Fact]
+ public void PlacementSemantics_BlindAndReliefSegments_HaveEntryAnchor()
+ {
+ var roots = new[] { BuildBlindTop(), BuildBlindBottom(), BuildCounterbore(), BuildChamferBottom(), BuildCountersink(), BuildStepped() };
+ foreach (var root in roots)
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan);
+ foreach (var s in plan.ProfileStack.Where(x => !x.IsThrough))
+ {
+ Assert.True(s.AnchorSide is HoleTierAnchorSide.Top or HoleTierAnchorSide.Bottom);
+ Assert.True(s.DepthFromAnchor > 0d);
+ }
+ }
+ }
+
+ [Fact]
+ public void PlacementSemantics_ExecutorsStillProduceBrep()
+ {
+ foreach (var root in new[] { BuildThrough(), BuildCounterbore(), BuildBlindTop(), BuildCountersink(), BuildChamferTop(), BuildChamferBottom() })
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan);
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ Assert.True(exec.Status is HoleRecoveryExecutionStatus.Succeeded or HoleRecoveryExecutionStatus.BooleanFailed);
+ }
+ }
+
+ private static CirNode BuildThrough() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20));
+ 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 BuildBlindTop() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(2, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3))));
+ private static CirNode BuildBlindBottom() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(2, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));
+ private static CirNode BuildCountersink() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20d, 20d, 10d), new CirCylinderNode(2d, 20d)), new CirTransformNode(new CirConeNode(2d, 4d, 4d), Transform3D.CreateTranslation(new Vector3D(0d, 0d, 3d))));
+ private static CirNode BuildChamferTop() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20d,20d,10d), new CirCylinderNode(2d,20d)), new CirTransformNode(new CirConeNode(2d, 2.8d, 1d), Transform3D.CreateTranslation(new Vector3D(0d, 0d, 4.5d))));
+ private static CirNode BuildChamferBottom() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20d,20d,10d), new CirCylinderNode(2d,20d)), new CirTransformNode(new CirConeNode(2.8d, 2d, 1d), Transform3D.CreateTranslation(new Vector3D(0d, 0d, -4.5d))));
+ private static CirNode BuildStepped() => 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/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
index cab8d122..152354e1 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
@@ -46,3 +46,43 @@ public sealed record HoleRecoveryPlan(
IReadOnlyList<HoleTrimCurveExpectation> ExpectedTrimCurves,
FrepMaterializerCapability Capability,
IReadOnlyList<string> Diagnostics);
+
+public static class HoleProfileSegmentPlacementValidator
+{
+ public static bool TryValidate(HoleRecoveryPlan plan, out IReadOnlyList<string> diagnostics)
+ {
+ var issues = new List<string>();
+ 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);
+
+ for (var i = 0; i < plan.ProfileStack.Count; i++)
+ {
+ var s = plan.ProfileStack[i];
+ var role = $"segment[{i}]/{s.SegmentKind}";
+ if (double.IsNaN(s.ZMin) || double.IsNaN(s.ZMax) || s.ZMax - s.ZMin <= tol)
+ {
+ issues.Add($"placement-invalid:{role}:z-span");
+ }
+
+ if (s.IsThrough)
+ {
+ if (s.AnchorSide != HoleTierAnchorSide.Through) issues.Add($"placement-invalid:{role}:through-anchor");
+ if (s.ZMin > hostMinZ + tol || s.ZMax < hostMaxZ - tol) issues.Add($"placement-invalid:{role}:through-z-coverage");
+ }
+ else
+ {
+ if (s.AnchorSide != HoleTierAnchorSide.Top && s.AnchorSide != HoleTierAnchorSide.Bottom) issues.Add($"placement-invalid:{role}:blind-anchor");
+ if (s.DepthFromAnchor <= tol) issues.Add($"placement-invalid:{role}:depth-from-anchor");
+ }
+
+ if (s.PlacementDiagnostics is null || s.PlacementDiagnostics.Count == 0)
+ {
+ issues.Add($"placement-invalid:{role}:diagnostics");
+ }
+ }
+
+ diagnostics = issues;
+ return issues.Count == 0;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
index 1d8828ed..d27cf2b9 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
@@ -167,7 +167,7 @@ internal sealed class CountersinkVariant : IHoleRecoveryVariant
var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Countersink, depthKind, HoleEntryFeatureKind.Countersink, exitKind,
host.ThroughLength, host.BoxWidth, host.BoxHeight, host.BoxDepth, host.BoxTranslation, host.CylinderTranslation,
- [new(HoleProfileSegmentKind.Conical, entryRadius, transitionRadius, 0d, coneDepth), new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength)],
+ [new(HoleProfileSegmentKind.Conical, entryRadius, transitionRadius, 0d, coneDepth, entryFromTop ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom, coneDepth, coneMinZ, coneMaxZ, false, [$"placement: segment=entry-cone anchor={(entryFromTop ? "Top" : "Bottom")} zMin={coneMinZ:0.###} zMax={coneMaxZ:0.###} through=false"]), new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength, depthKind == HoleDepthKind.ThroughWithEntryRelief ? HoleTierAnchorSide.Through : (entryFromTop ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom), host.ThroughLength, host.BoxTranslation.Z - (host.BoxDepth * 0.5d), host.BoxTranslation.Z + (host.BoxDepth * 0.5d), depthKind == HoleDepthKind.ThroughWithEntryRelief, [$"placement: segment=core-cylinder anchor={(depthKind == HoleDepthKind.ThroughWithEntryRelief ? "Through" : (entryFromTop ? "Top" : "Bottom"))} through={(depthKind == HoleDepthKind.ThroughWithEntryRelief).ToString().ToLowerInvariant()}"])],
[new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after countersink subtraction."), new(HoleSurfacePatchRole.CountersinkWall, "Conical countersink wall patch is expected."), new(HoleSurfacePatchRole.CylindricalWall, "Cylindrical continuation wall patch is expected.")],
[new(HoleTrimCurveRole.CircularRimTrim, "Circular entry/transition trims are expected.")], FrepMaterializerCapability.ExactBRep, diagnostics.ToArray());
@@ -281,7 +281,7 @@ internal sealed class ChamferedEntryHoleVariant : IHoleRecoveryVariant
diagnostics.Add("Chamfered-entry plan produced.");
var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.ChamferedEntry, depthKind, HoleEntryFeatureKind.Chamfer, exitKind,
host.ThroughLength, host.BoxWidth, host.BoxHeight, host.BoxDepth, host.BoxTranslation, host.CylinderTranslation,
- [new(HoleProfileSegmentKind.Conical, entryRadius, transitionRadius, 0d, coneDepth), new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength)],
+ [new(HoleProfileSegmentKind.Conical, entryRadius, transitionRadius, 0d, coneDepth, entryFromTop ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom, coneDepth, coneMinZ, coneMaxZ, false, [$"placement: segment=entry-cone anchor={(entryFromTop ? "Top" : "Bottom")} zMin={coneMinZ:0.###} zMax={coneMaxZ:0.###} through=false"]), new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength, depthKind == HoleDepthKind.ThroughWithEntryRelief ? HoleTierAnchorSide.Through : (entryFromTop ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom), host.ThroughLength, host.BoxTranslation.Z - (host.BoxDepth * 0.5d), host.BoxTranslation.Z + (host.BoxDepth * 0.5d), depthKind == HoleDepthKind.ThroughWithEntryRelief, [$"placement: segment=core-cylinder anchor={(depthKind == HoleDepthKind.ThroughWithEntryRelief ? "Through" : (entryFromTop ? "Top" : "Bottom"))} through={(depthKind == HoleDepthKind.ThroughWithEntryRelief).ToString().ToLowerInvariant()}"])],
[new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after chamfered-entry subtraction."), new(HoleSurfacePatchRole.ChamferedEntryWall, "Conical chamfered-entry wall patch is expected."), new(HoleSurfacePatchRole.CylindricalWall, "Cylindrical continuation wall patch is expected.")],
[new(HoleTrimCurveRole.CircularRimTrim, "Circular entry/transition trims are expected.")], FrepMaterializerCapability.ExactBRep, diagnostics.ToArray());
@@ -306,7 +306,7 @@ internal sealed class ThroughHoleVariant : IHoleRecoveryVariant
var supportsTranslation = r.BoxTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero || r.CylinderTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero;
var evidence = new List<string> { "through-hole", "rectangular-box-host", "cylindrical-profile-segment", "strict-clearance", "z-axis", supportsTranslation ? "translation-wrapper-supported" : "translation-wrapper-not-required" };
var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Through, HoleDepthKind.Through, HoleEntryFeatureKind.Plain, HoleExitFeatureKind.Plain, r.ThroughLength, r.BoxWidth, r.BoxHeight, r.BoxDepth, r.BoxTranslation, r.CylinderTranslation,
- [new(HoleProfileSegmentKind.Cylindrical, r.CylinderRadius, r.CylinderRadius, 0d, r.ThroughLength)],
+ [new(HoleProfileSegmentKind.Cylindrical, r.CylinderRadius, r.CylinderRadius, 0d, r.ThroughLength, HoleTierAnchorSide.Through, r.ThroughLength, r.BoxTranslation.Z - (r.BoxDepth * 0.5d), r.BoxTranslation.Z + (r.BoxDepth * 0.5d), true, ["placement: segment=core anchor=Through through=true"])],
[new(HoleSurfacePatchRole.EntryFace, "Cylinder intersects host entry face with circular profile."), new(HoleSurfacePatchRole.ExitFace, "Cylinder intersects host exit face with circular profile."), new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after through-hole subtraction."), new(HoleSurfacePatchRole.CylindricalWall, "One cylindrical inner wall patch is expected.")],
[new(HoleTrimCurveRole.CircularRimTrim, "Circular trims on entry and exit rims are expected.")],
FrepMaterializerCapability.ExactBRep,
@@ -446,7 +446,7 @@ internal sealed class BlindHoleVariant : IHoleRecoveryVariant
plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Blind, HoleDepthKind.Blind, HoleEntryFeatureKind.Plain, HoleExitFeatureKind.ClosedBottom,
depth, box.Width, box.Height, box.Depth, hostT, toolT,
- [new(HoleProfileSegmentKind.Cylindrical, cyl.Radius, cyl.Radius, 0d, depth)],
+ [new(HoleProfileSegmentKind.Cylindrical, cyl.Radius, cyl.Radius, 0d, depth, entersTop ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom, depth, cylMinZ, cylMaxZ, false, [$"placement: segment=blind-core anchor={(entersTop ? "Top" : "Bottom")} zMin={cylMinZ:0.###} zMax={cylMaxZ:0.###} through=false"])],
[new(HoleSurfacePatchRole.EntryFace, "Cylinder intersects one host entry face with circular profile."),
new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after blind-hole subtraction."),
new(HoleSurfacePatchRole.CylindricalWall, "One cylindrical blind wall patch is expected."),
@@ -534,8 +534,8 @@ internal sealed class CounterboreVariant : IHoleRecoveryVariant
host.BoxTranslation,
host.CylinderTranslation,
[
- new(HoleProfileSegmentKind.Cylindrical, largeCylinder.Radius, largeCylinder.Radius, 0d, floorDepth),
- new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength)
+ new(HoleProfileSegmentKind.Cylindrical, largeCylinder.Radius, largeCylinder.Radius, 0d, floorDepth, Math.Abs(largeMaxZ - boxMaxZ) <= tol ? HoleTierAnchorSide.Top : HoleTierAnchorSide.Bottom, floorDepth, largeMinZ, largeMaxZ, false, [$"placement: segment=counterbore-relief anchor={(Math.Abs(largeMaxZ - boxMaxZ) <= tol ? "Top" : "Bottom")} zMin={largeMinZ:0.###} zMax={largeMaxZ:0.###} through=false"]),
+ new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength, HoleTierAnchorSide.Through, host.ThroughLength, boxMinZ, boxMaxZ, true, [$"placement: segment=through-core anchor=Through zMin={boxMinZ:0.###} zMax={boxMaxZ:0.###} through=true"])
],
[
new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after counterbore subtraction."),
@@ -691,9 +691,9 @@ internal sealed class SteppedHoleVariant : IHoleRecoveryVariant
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, largeAnchor, large.Height, largeMinZ, largeMaxZ, false, [$"anchor={largeAnchor}", $"depthFromAnchor={large.Height:0.###}", $"z=[{largeMinZ:0.###},{largeMaxZ:0.###}]"]),
- new(HoleProfileSegmentKind.Cylindrical, medium.Radius, medium.Radius, 0d, medium.Height, mediumAnchor, medium.Height, mediumMinZ, mediumMaxZ, false, [$"anchor={mediumAnchor}", $"depthFromAnchor={medium.Height:0.###}", $"z=[{mediumMinZ:0.###},{mediumMaxZ:0.###}]"]),
- new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength, HoleTierAnchorSide.Through, host.ThroughLength, boxMinZ, boxMaxZ, true, ["anchor=Through", $"z=[{boxMinZ:0.###},{boxMaxZ:0.###}]"])
+ new(HoleProfileSegmentKind.Cylindrical, large.Radius, large.Radius, 0d, large.Height, largeAnchor, large.Height, largeMinZ, largeMaxZ, false, [$"placement: segment=large anchor={largeAnchor} zMin={largeMinZ:0.###} zMax={largeMaxZ:0.###} through=false"]),
+ new(HoleProfileSegmentKind.Cylindrical, medium.Radius, medium.Radius, 0d, medium.Height, mediumAnchor, medium.Height, mediumMinZ, mediumMaxZ, false, [$"placement: segment=medium anchor={mediumAnchor} zMin={mediumMinZ:0.###} zMax={mediumMaxZ:0.###} through=false"]),
+ new(HoleProfileSegmentKind.Cylindrical, host.CylinderRadius, host.CylinderRadius, 0d, host.ThroughLength, HoleTierAnchorSide.Through, host.ThroughLength, boxMinZ, boxMaxZ, true, [$"placement: segment=small-through anchor=Through zMin={boxMinZ:0.###} zMax={boxMaxZ:0.###} through=true"])
],
[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());
diff --git a/docs/cir-recovery-v12-hole-family-coverage-matrix.md b/docs/cir-recovery-v12-hole-family-coverage-matrix.md
index 6f549659..288a6f27 100644
--- a/docs/cir-recovery-v12-hole-family-coverage-matrix.md
+++ b/docs/cir-recovery-v12-hole-family-coverage-matrix.md
@@ -59,3 +59,6 @@ If/when expansion resumes, keep the same pattern:
1. bounded admissibility first,
2. explicit rejection diagnostics for all peer variants,
3. matrix row + cross-steal + manifold STEP sanity tests with each new variant.
+
+## V17 follow-up
+Coverage matrix expectations include explicit placement metadata population for all supported hole-family variants.
diff --git a/docs/cir-recovery-v132-stepped-tier-placement-semantics.md b/docs/cir-recovery-v132-stepped-tier-placement-semantics.md
index a14fd73a..3952a453 100644
--- a/docs/cir-recovery-v132-stepped-tier-placement-semantics.md
+++ b/docs/cir-recovery-v132-stepped-tier-placement-semantics.md
@@ -50,3 +50,6 @@ V13.3 re-enables bounded stepped execution and now treats these placement fields
- tool construction uses `height = ZMax - ZMin` and `centerZ = (ZMin + ZMax)/2` with no hidden span inference.
Route is explicitly `repeated-subtract-small-medium-large`; any placement inconsistency rejects before Boolean.
+
+## V17 follow-up
+Placement semantics are now harmonized across all hole-family variants; this document remains the stepped reference contract.
diff --git a/docs/cir-recovery-v16-bottom-entry-chamfered-hole.md b/docs/cir-recovery-v16-bottom-entry-chamfered-hole.md
index 4bb6e8f8..ac955518 100644
--- a/docs/cir-recovery-v16-bottom-entry-chamfered-hole.md
+++ b/docs/cir-recovery-v16-bottom-entry-chamfered-hole.md
@@ -84,3 +84,6 @@ And no `BREP_WITH_VOIDS`.
## SEM-A0 status
No generated topology naming/provenance expansion introduced. V16 is bounded to entry-side hardening inside existing hole-family variant architecture.
+
+## V17 follow-up
+Bottom-entry chamfer segments now participate in the shared explicit placement contract validator.
diff --git a/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md b/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md
new file mode 100644
index 00000000..145cf587
--- /dev/null
+++ b/docs/cir-recovery-v17-hole-placement-semantics-harmonization.md
@@ -0,0 +1,39 @@
+# CIR-RECOVERY-V17: hole-family placement semantics harmonization
+
+## Purpose
+Harmonize `HoleProfileSegment` placement semantics across all hole-family variants so executors consume explicit placement metadata.
+
+## Placement contract
+Each segment must declare: `AnchorSide`, `DepthFromAnchor`, `ZMin/ZMax`, `IsThrough`, and `PlacementDiagnostics`.
+
+## Inventory (pre-V17 -> V17 action)
+| Variant | Segment | Anchor | DepthFromAnchor | Z span | IsThrough | PlacementDiagnostics | Executor behavior | Action |
+|---|---|---|---|---|---|---|---|---|
+| Through | core cylinder | missing -> explicit Through | missing -> explicit | missing -> explicit host span | missing -> true | missing -> added | previously inferred | populated + validated |
+| Blind | core cylinder | missing -> explicit Top/Bottom | missing -> explicit depth | missing -> explicit tool span | missing -> false | missing -> added | previously inferred | populated + validated |
+| Counterbore | relief cylinder | missing -> explicit Top/Bottom | missing -> explicit depth | missing -> explicit relief span | missing -> false | missing -> added | partially inferred | populated + validated |
+| Counterbore | through core | missing -> explicit Through | missing -> explicit through length | missing -> explicit host span | missing -> true | missing -> added | inferred | populated + validated |
+| Countersink | entry cone | missing -> explicit Top/Bottom | missing -> explicit cone depth | missing -> explicit cone span | missing -> false | missing -> added | inferred | populated + validated |
+| Countersink | core cylinder | missing -> explicit Through/entry side (blind) | missing -> explicit | missing -> explicit host span | missing -> explicit | missing -> added | inferred | populated + validated |
+| Chamfered-entry | entry cone | missing -> explicit Top/Bottom | missing -> explicit cone depth | missing -> explicit cone span | missing -> false | missing -> added | inferred | populated + validated |
+| Chamfered-entry | core cylinder | missing -> explicit Through/entry side (blind) | missing -> explicit | missing -> explicit host span | missing -> explicit | missing -> added | inferred | populated + validated |
+| Stepped | large/medium/small tiers | already explicit | already explicit | already explicit | already explicit | normalized to `placement:` breadcrumb style | explicit | preserved contract |
+
+## Executor consumption status
+A shared `HoleProfileSegmentPlacementValidator` was added as a compact internal helper for contract checks and future enforcement; current executor routing remains behavior-preserving and still performs its existing bounded per-variant checks.
+
+Remaining hidden inference: primitive construction order and boolean sequencing remain architecture-local by design (non-goal).
+
+## Rules for future LLM authors
+1. Every profile segment must declare placement.
+2. Executors must prefer explicit placement.
+3. Unknown anchor is not executable.
+4. Through segments must declare through semantics.
+5. Non-through segments must declare entry anchor and z-span.
+6. Tests must include placement assertions.
+
+## Non-goals
+No new variants, no STEP exporter changes, no public API changes, no generic profile-stack executor.
+
+## Next milestone recommendation
+CIR-RECOVERY-V18: centralize segment-role taxonomy and validator-backed role/placement compatibility checks.