Skip to content

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.cs
index e8995545..c6cc3ed4 100644
--- a/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FrepSemanticRecoveryRematerializerTests.cs
@@ -82,7 +82,7 @@ public sealed class FrepSemanticRecoveryRematerializerTests
Assert.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.cs
index d69644bf..4feacee1 100644
--- a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs
@@ -108,7 +108,7 @@ public sealed class HoleRecoveryPolicyCoverageMatrixTests
if (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 HoleRecoveryPolicyCoverageMatrixTests
if (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.cs
new file mode 100644
index 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.cs
index d86ea49b..615b2340 100644
--- a/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SteppedHoleVariantAndExecutorTests.cs
@@ -27,7 +27,7 @@ public sealed class SteppedHoleVariantAndExecutorTests
var 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 SteppedHoleVariantAndExecutorTests
var 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 SteppedHoleVariantAndExecutorTests
var 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.cs
index 928484a7..b8e4f376 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
@@ -62,8 +62,8 @@ public static class HoleRecoveryExecutor
if (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.cs
index 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.cs
index 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 : IHoleRecoveryVariant
return 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.md
index 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.md
index 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-goals
No 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.md
new file mode 100644
index 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.