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.csnew file mode 100644index 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.csindex 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.csindex 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 : IHoleRecoveryVariantvar 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 : IHoleRecoveryVariantdiagnostics.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 : IHoleRecoveryVariantvar 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 : IHoleRecoveryVariantplan = 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 : IHoleRecoveryVarianthost.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 : IHoleRecoveryVariantvar 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.mdindex 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.mdindex 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.mdindex 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 statusNo 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.mdnew file mode 100644index 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.