Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
CIR-RECOVERY-V13.2: add explicit stepped tier placement semantics
Yuechen Lida7a832e56e1
diff --git a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.csindex e8995545..c6cc3ed4 100644--- a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs@@ -82,7 +82,7 @@ public sealed class FrepSemanticRecoveryRematerializerTestsAssert.False(result.Succeeded);Assert.Null(result.Body);Assert.Contains(result.Diagnostics, d => d.Contains("executor failed", StringComparison.Ordinal));- Assert.Contains(result.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));}private static NativeGeometryReplayLog BuildReplay(string toolKind)=> new([diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.csindex d69644bf..4feacee1 100644--- a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs@@ -108,7 +108,7 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsif (plan.HoleKind == HoleKind.Stepped){Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);- Assert.Contains(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));return;}@@ -131,7 +131,7 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTestsif (plan.HoleKind == HoleKind.Stepped){Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);- Assert.Contains(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));return;}diff --git a/Aetheris.Kernel.Firmament.Tests/SteppedHolePlacementSemanticsTests.cs b/Aetheris.Kernel.Firmament.Tests/SteppedHolePlacementSemanticsTests.csnew file mode 100644index 00000000..aab47761--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SteppedHolePlacementSemanticsTests.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 SteppedHolePlacementSemanticsTests+{+ [Fact]+ public void SteppedPlan_ProfileSegmentsCarryExplicitPlacement()+ {+ var plan = BuildPlan();++ Assert.Equal(3, plan.ProfileStack.Count);+ Assert.All(plan.ProfileStack, segment =>+ {+ Assert.NotEqual(HoleTierAnchorSide.Unknown, segment.AnchorSide);+ Assert.False(double.IsNaN(segment.ZMin));+ Assert.False(double.IsNaN(segment.ZMax));+ Assert.True(segment.ZMax >= segment.ZMin);+ Assert.NotNull(segment.PlacementDiagnostics);+ Assert.NotEmpty(segment.PlacementDiagnostics!);+ });+ }++ [Fact]+ public void SteppedPlan_TopEntryZSpansMatchFrictionLabRoute()+ {+ var plan = BuildPlan();+ var hostMinZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);+ var hostMaxZ = plan.HostTranslation.Z + (plan.HostSizeZ * 0.5d);+ var large = plan.ProfileStack[0];+ var medium = plan.ProfileStack[1];+ var small = plan.ProfileStack[2];++ Assert.Equal(HoleTierAnchorSide.Through, small.AnchorSide);+ Assert.True(small.IsThrough);+ Assert.True(small.ZMin <= hostMinZ + 1e-9);+ Assert.True(small.ZMax >= hostMaxZ - 1e-9);++ Assert.Equal(HoleTierAnchorSide.Top, medium.AnchorSide);+ Assert.False(medium.IsThrough);+ Assert.Equal(6d, medium.DepthFromAnchor, 10);+ Assert.Equal(hostMaxZ - medium.DepthFromAnchor, medium.ZMin, 10);+ Assert.Equal(hostMaxZ, medium.ZMax, 10);++ Assert.Equal(HoleTierAnchorSide.Top, large.AnchorSide);+ Assert.False(large.IsThrough);+ Assert.Equal(4d, large.DepthFromAnchor, 10);+ Assert.Equal(hostMaxZ - large.DepthFromAnchor, large.ZMin, 10);+ Assert.Equal(hostMaxZ, large.ZMax, 10);++ Assert.True(small.RadiusStart < medium.RadiusStart && medium.RadiusStart < large.RadiusStart);+ }++ [Fact]+ public void SteppedPlan_PlacementNoLongerMissingPolarity()+ {+ var exec = HoleRecoveryExecutor.Execute(BuildPlan());+ Assert.DoesNotContain(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));+ }++ [Fact]+ public void SteppedExecution_RemainsDeferredInV13_2()+ {+ var exec = HoleRecoveryExecutor.Execute(BuildPlan());+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);+ Assert.Null(exec.Body);+ Assert.DoesNotContain(exec.Diagnostics, d => d.Contains("subtract", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(exec.Diagnostics, d => d.Contains("No STEP export attempted", StringComparison.Ordinal));+ }++ private static HoleRecoveryPlan BuildPlan()+ => (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped())).Plan!;++ private static CirNode BuildStepped()+ {+ var host = new CirBoxNode(20, 20, 10);+ var small = new CirCylinderNode(2, 20);+ var medium = new CirTransformNode(new CirCylinderNode(3, 6), Transform3D.CreateTranslation(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.Tests/SteppedHoleVariantAndExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.csindex d86ea49b..615b2340 100644--- a/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs@@ -27,7 +27,7 @@ public sealed class SteppedHoleVariantAndExecutorTestsvar exec = HoleRecoveryExecutor.Execute(plan);Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);Assert.Null(exec.Body);- Assert.Contains(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));}[Fact]@@ -37,7 +37,7 @@ public sealed class SteppedHoleVariantAndExecutorTestsvar exec = HoleRecoveryExecutor.Execute(plan);Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);Assert.Null(exec.Body);- Assert.Contains(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));Assert.Contains(exec.Diagnostics, d => d.Contains("No STEP export attempted", StringComparison.Ordinal));}@@ -72,7 +72,7 @@ public sealed class SteppedHoleVariantAndExecutorTestsvar exec = HoleRecoveryExecutor.Execute(invalid);Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, exec.Status);Assert.Null(exec.Body);- Assert.Contains(exec.Diagnostics, d => d.Contains("missing-stepped-entry-side-polarity", StringComparison.Ordinal));+ Assert.Contains(exec.Diagnostics, d => d.Contains("stepped-execution-route-disabled-until-v13.3", StringComparison.Ordinal));Assert.DoesNotContain(exec.Diagnostics, d => d.Contains("Stepped subtract", StringComparison.Ordinal));}diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.csindex 928484a7..b8e4f376 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs@@ -62,8 +62,8 @@ public static class HoleRecoveryExecutorif (plan.HoleKind == HoleKind.Stepped && plan.DepthKind == HoleDepthKind.ThroughWithEntryRelief){- diagnostics.Add("Stepped-hole plan recognized but execution deferred: plan does not encode entry-side polarity for medium/large tiers, and production route cannot be proven equivalent to FrictionLab route.");- diagnostics.Add("Deferred reason: missing-stepped-entry-side-polarity.");+ diagnostics.Add("Stepped-hole plan recognized with explicit tier placement metadata; execution intentionally deferred in V13.2 pending production route re-enable.");+ diagnostics.Add("Deferred reason: stepped-execution-route-disabled-until-v13.3.");return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);}diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.csindex 6e6f8773..1d295201 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs@@ -7,12 +7,24 @@ public enum HoleAxisKind { Z, 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 HoleTierAnchorSide { Top, Bottom, Through, Unknown }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, SteppedTransitionFloorAnnulus }public enum HoleTrimCurveRole { CircularRimTrim, Deferred }-public sealed record HoleProfileSegment(HoleProfileSegmentKind SegmentKind, double RadiusStart, double RadiusEnd, double DepthStart, double DepthEnd);+public sealed record HoleProfileSegment(+ HoleProfileSegmentKind SegmentKind,+ double RadiusStart,+ double RadiusEnd,+ double DepthStart,+ double DepthEnd,+ HoleTierAnchorSide AnchorSide = HoleTierAnchorSide.Unknown,+ double DepthFromAnchor = 0d,+ double ZMin = double.NaN,+ double ZMax = double.NaN,+ bool IsThrough = false,+ IReadOnlyList<string>? PlacementDiagnostics = null);public sealed record HoleSurfacePatchExpectation(HoleSurfacePatchRole Role, string Description);public sealed record HoleTrimCurveExpectation(HoleTrimCurveRole Role, string Description);diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.csindex 0a02a72d..c1bfded3 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs@@ -550,11 +550,37 @@ internal sealed class SteppedHoleVariant : IHoleRecoveryVariantreturn new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedLargestRadiusClearance"], diagnostics);}- diagnostics.Add("entry side detected.");+ var mediumMinZ = mediumT.Z - (medium.Height * 0.5d);+ var mediumMaxZ = mediumT.Z + (medium.Height * 0.5d);+ var largeMinZ = largeT.Z - (large.Height * 0.5d);+ var largeMaxZ = largeT.Z + (large.Height * 0.5d);+ var mediumTouchesTop = Math.Abs(mediumMaxZ - boxMaxZ) <= tol;+ var mediumTouchesBottom = Math.Abs(mediumMinZ - boxMinZ) <= tol;+ var largeTouchesTop = Math.Abs(largeMaxZ - boxMaxZ) <= tol;+ var largeTouchesBottom = Math.Abs(largeMinZ - boxMinZ) <= tol;+ var mediumAnchor = mediumTouchesTop ? HoleTierAnchorSide.Top : (mediumTouchesBottom ? HoleTierAnchorSide.Bottom : HoleTierAnchorSide.Unknown);+ var largeAnchor = largeTouchesTop ? HoleTierAnchorSide.Top : (largeTouchesBottom ? HoleTierAnchorSide.Bottom : HoleTierAnchorSide.Unknown);+ if (mediumAnchor == HoleTierAnchorSide.Unknown || largeAnchor == HoleTierAnchorSide.Unknown)+ {+ diagnostics.Add("entry side anchor unresolved for medium/large.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedSteppedAnchorUnknown"], diagnostics);+ }++ if (mediumAnchor != largeAnchor)+ {+ diagnostics.Add("entry side anchor mismatch between medium and large tiers.");+ return new(Name, false, 0d, null, ["stepped-hole", "rectangular-box-host"], ["UnsupportedSteppedAnchorMismatch"], diagnostics);+ }++ diagnostics.Add($"entry side detected: {(mediumAnchor == HoleTierAnchorSide.Top ? "top(+Z)" : "bottom(-Z)")}. ");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(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(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/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md b/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.mdindex e825ebc5..31d974c9 100644--- a/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md+++ b/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md@@ -50,3 +50,7 @@ Support remains intentionally bounded to the canonical three-level coaxial Z-axi- **Decision (Outcome B):** stepped execution is restored to **deferred** in production with explicit diagnostic:- `missing-stepped-entry-side-polarity`- Through/blind/counterbore/countersink execution paths remain unchanged.++## V13.2 follow-up+- V13.2 closes the prior plan-contract gap by adding explicit stepped tier placement semantics to `HoleProfileSegment` and populating anchor/depth/z-span metadata for each tier.+- The old polarity-missing blocker is retired; stepped execution remains deferred under a new intentional gate (`stepped-execution-route-disabled-until-v13.3`) until production route re-enable.diff --git a/docs/cir-recovery-v13-stepped-hole-variant-executor-step.md b/docs/cir-recovery-v13-stepped-hole-variant-executor-step.mdindex 40b832ed..2ffb756b 100644--- a/docs/cir-recovery-v13-stepped-hole-variant-executor-step.md+++ b/docs/cir-recovery-v13-stepped-hole-variant-executor-step.md@@ -31,6 +31,11 @@ Stepped execution is reverted to deferred in production pending plan/executor co- Executor now returns `UnsupportedPlan` with `missing-stepped-entry-side-polarity` instead of attempting non-equivalent stepped Boolean execution.- STEP smoke for stepped is therefore intentionally deferred in production until that contract gap is closed.+## V13.2 placement-contract hardening update+- `HoleProfileSegment` now carries explicit tier placement semantics (`AnchorSide`, `DepthFromAnchor`, `ZMin`, `ZMax`, `IsThrough`) for stepped tiers.+- Stepped plans now populate those fields directly from host/tool geometry, so medium/large entry-side polarity is no longer implicit.+- Production execution remains intentionally deferred with `stepped-execution-route-disabled-until-v13.3` while route re-enable is held for the next milestone.+## Non-goalsNo generic N-level stack executor, no threaded-hole support, no STEP exporter changes, no public API changes.diff --git a/docs/cir-recovery-v132-stepped-tier-placement-semantics.md b/docs/cir-recovery-v132-stepped-tier-placement-semantics.mdnew file mode 100644index 00000000..c0821943--- /dev/null+++ b/docs/cir-recovery-v132-stepped-tier-placement-semantics.md@@ -0,0 +1,43 @@+# CIR-RECOVERY-V13.2: explicit stepped-hole tier placement semantics++## Why this milestone exists+A4.1 proved the production stepped executor could not reconstruct medium/large tier placement from the prior `HoleRecoveryPlan` contract. The blocker was `missing-stepped-entry-side-polarity`. V13.2 hardens plan semantics so stepped tiers carry explicit anchor/depth/z-span metadata.++## Placement contract+`HoleProfileSegment` now carries explicit tier placement fields:+- `AnchorSide` (`Top`, `Bottom`, `Through`, `Unknown`)+- `DepthFromAnchor`+- `ZMin`+- `ZMax`+- `IsThrough`+- `PlacementDiagnostics`++### Coordinate convention+Host/world Z follows existing Aetheris BRep conventions:+- host min Z = `HostTranslation.Z - HostSizeZ/2`+- host max Z = `HostTranslation.Z + HostSizeZ/2`+- top entry means contact at host max Z+- bottom entry means contact at host min Z++`ZMin/ZMax` are stored in host/world coordinates and are the intended subtraction span for that segment.++## Canonical top-entry stepped example+For host z-range `[-10,+10]`:+- small through tier: `AnchorSide=Through`, `IsThrough=true`, span includes `[-10,+10]`+- medium tier depth 8 from top: `AnchorSide=Top`, `ZMin=+2`, `ZMax=+10`+- large tier depth 4 from top: `AnchorSide=Top`, `ZMin=+6`, `ZMax=+10`++## Bottom-entry mirroring policy+If stepped relief tiers touch host min Z, both blind tiers use `AnchorSide=Bottom` and their Z spans mirror top-entry behavior about the host midpoint. Mixed medium/large anchor sides are rejected as unsupported.++## Relation to FrictionLab route+FrictionLab succeeded because medium/large z spans were explicit. V13.2 aligns production plan metadata with that convention and adds tests that compare radii/order/z spans against that successful route model.++## Why execution remains deferred+V13.2 is contract hardening only. Production stepped execution remains intentionally deferred with:+- `stepped-execution-route-disabled-until-v13.3`++No stepped Boolean execution is attempted in this milestone.++## V13.3 next step+Re-enable stepped production execution using plan-provided placement semantics (`AnchorSide`, `DepthFromAnchor`, `ZMin/ZMax`, `IsThrough`) and keep route-equivalence tests as an execution gate.