Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add A0 stepped stack root-cause verification tests and doc

Yuechen Liaf1456e28b0e
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanSteppedStackRootCauseTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanSteppedStackRootCauseTests.cs
new file mode 100644
index 00000000..a0e9fb59
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanSteppedStackRootCauseTests.cs
@@ -0,0 +1,116 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Boolean;
+
+public sealed class BrepBooleanSteppedStackRootCauseTests
+{
+ [Fact]
+ public void SteppedThirdSubtract_FailsWithObservedValidatorDiagnostic()
+ {
+ var baseBox = BrepBooleanBoxRecognition.CreateBoxFromExtents(new AxisAlignedBoxExtents(-15d, 15d, -15d, 15d, -10d, 10d)).Value;
+ var through = BrepPrimitives.CreateCylinder(2d, 30d).Value;
+ var mediumBlind = Translate(BrepPrimitives.CreateCylinder(3d, 6d).Value, Transform3D.CreateTranslation(new Vector3D(0d, 0d, 7d)));
+ var shallowBlind = Translate(BrepPrimitives.CreateCylinder(4d, 3d).Value, Transform3D.CreateTranslation(new Vector3D(0d, 0d, 8.5d)));
+
+ var first = BrepBoolean.Subtract(baseBox, through);
+ Assert.True(first.IsSuccess);
+
+ var second = BrepBoolean.Subtract(first.Value, mediumBlind);
+ Assert.True(second.IsSuccess);
+ Assert.Equal(2, second.Value.SafeBooleanComposition?.Holes.Count);
+
+ var third = BrepBoolean.Subtract(second.Value, shallowBlind);
+ Assert.False(third.IsSuccess);
+
+ var diagnostic = Assert.Single(third.Diagnostics);
+ Assert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);
+ Assert.Equal("BrepBoolean.AnalyticHole.HoleInterference", diagnostic.Source);
+ Assert.Contains("overlaps previously accepted hole", diagnostic.Message, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void NLevelCoaxialBuilderProbe_ObservedBehavior_IsSuccessfulBuild()
+ {
+ var baseBox = BrepBooleanBoxRecognition.CreateBoxFromExtents(new AxisAlignedBoxExtents(-15d, 15d, -15d, 15d, -10d, 10d)).Value;
+ var through = BrepPrimitives.CreateCylinder(2d, 30d).Value;
+ var mediumBlind = Translate(BrepPrimitives.CreateCylinder(3d, 6d).Value, Transform3D.CreateTranslation(new Vector3D(0d, 0d, 7d)));
+
+ var first = BrepBoolean.Subtract(baseBox, through);
+ Assert.True(first.IsSuccess);
+ var second = BrepBoolean.Subtract(first.Value, mediumBlind);
+ Assert.True(second.IsSuccess);
+
+ var composition = second.Value.SafeBooleanComposition!;
+ var seedHole = composition.Holes[1];
+ var thirdHole = seedHole with
+ {
+ BottomRadius = 4d,
+ TopRadius = 4d,
+ EndCenter = new Point3D(seedHole.EndCenter.X, seedHole.EndCenter.Y, 7d),
+ EndZ = 7d,
+ };
+ composition = composition with { Holes = [composition.Holes[0], composition.Holes[1], thirdHole] };
+
+ var build = BrepBooleanBoxCylinderHoleBuilder.BuildComposition(composition, ToleranceContext.Default);
+ Assert.True(build.IsSuccess, string.Join(Environment.NewLine, build.Diagnostics.Select(d => d.Message)));
+ Assert.True(BrepBindingValidator.Validate(build.Value, requireAllEdgeAndFaceBindings: true).IsSuccess);
+ }
+
+ [Fact]
+ public void CounterboreTwoLevel_StillSucceeds()
+ {
+ var baseBox = BrepBooleanBoxRecognition.CreateBoxFromExtents(new AxisAlignedBoxExtents(-35d, 35d, -20d, 20d, -8d, 8d)).Value;
+ var pocket = Translate(BrepPrimitives.CreateCylinder(5d, 6d).Value, Transform3D.CreateTranslation(new Vector3D(0d, 0d, 5d)));
+ var through = BrepPrimitives.CreateCylinder(3d, 24d).Value;
+
+ var first = BrepBoolean.Subtract(baseBox, pocket);
+ Assert.True(first.IsSuccess);
+
+ var second = BrepBoolean.Subtract(first.Value, through);
+ Assert.True(second.IsSuccess, string.Join(Environment.NewLine, second.Diagnostics.Select(d => d.Message)));
+ Assert.Equal(2, second.Value.SafeBooleanComposition?.Holes.Count);
+ }
+
+ private static BrepBody Translate(BrepBody body, Transform3D transform)
+ {
+ var geometry = new BrepGeometryStore();
+ foreach (var curveEntry in body.Geometry.Curves)
+ {
+ geometry.AddCurve(curveEntry.Key, curveEntry.Value.Kind switch
+ {
+ CurveGeometryKind.Line3 => CurveGeometry.FromLine(new Line3Curve(transform.Apply(curveEntry.Value.Line3!.Value.Origin), transform.Apply(curveEntry.Value.Line3.Value.Direction))),
+ CurveGeometryKind.Circle3 => CurveGeometry.FromCircle(new Circle3Curve(transform.Apply(curveEntry.Value.Circle3!.Value.Center), transform.Apply(curveEntry.Value.Circle3.Value.Normal), curveEntry.Value.Circle3.Value.Radius, transform.Apply(curveEntry.Value.Circle3.Value.XAxis))),
+ _ => curveEntry.Value
+ });
+ }
+
+ foreach (var surfaceEntry in body.Geometry.Surfaces)
+ {
+ geometry.AddSurface(surfaceEntry.Key, surfaceEntry.Value.Kind switch
+ {
+ SurfaceGeometryKind.Plane => SurfaceGeometry.FromPlane(new PlaneSurface(transform.Apply(surfaceEntry.Value.Plane!.Value.Origin), transform.Apply(surfaceEntry.Value.Plane.Value.Normal), transform.Apply(surfaceEntry.Value.Plane.Value.UAxis))),
+ SurfaceGeometryKind.Cylinder => SurfaceGeometry.FromCylinder(new CylinderSurface(transform.Apply(surfaceEntry.Value.Cylinder!.Value.Origin), transform.Apply(surfaceEntry.Value.Cylinder.Value.Axis), surfaceEntry.Value.Cylinder.Value.Radius, transform.Apply(surfaceEntry.Value.Cylinder.Value.XAxis))),
+ _ => surfaceEntry.Value
+ });
+ }
+
+ var vertexPoints = new Dictionary<VertexId, Point3D>();
+ foreach (var vertex in body.Topology.Vertices)
+ {
+ if (body.TryGetVertexPoint(vertex.Id, out var point))
+ {
+ vertexPoints[vertex.Id] = transform.Apply(point);
+ }
+ }
+
+ return new BrepBody(body.Topology, geometry, body.Bindings, vertexPoints, body.SafeBooleanComposition);
+ }
+}
diff --git a/docs/brep-boolean-stack-a0-stepped-root-cause.md b/docs/brep-boolean-stack-a0-stepped-root-cause.md
new file mode 100644
index 00000000..f3f336be
--- /dev/null
+++ b/docs/brep-boolean-stack-a0-stepped-root-cause.md
@@ -0,0 +1,85 @@
+# BREP-BOOLEAN-STACK-A0 stepped coaxial stack root-cause verification
+
+## 1) Purpose and scope
+
+This milestone verifies (without fixing behavior) whether stepped-hole boolean failure is caused by hard N=2 cliffs in:
+
+- validator (`BrepBooleanSafeCompositionGraphValidator`),
+- builder (`BrepBooleanBoxCylinderHoleBuilder`).
+
+Out of scope for A0: validator refactor, N-level classifier implementation, N-level topology/builder rewrite, policy/exporter/public-API changes.
+
+## 2) Code/docs inspected
+
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanSafeCompositionGraphValidator.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCoaxialSubtractStackFamily.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanSafeComposition.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BooleanDiagnostic.cs`
+- Existing boolean tests under `Aetheris.Kernel.Core.Tests/Brep/Boolean/`
+- `docs/cir-recovery-v13-stepped-hole-variant-executor-step.md`
+- `docs/frictionlab/cir-brep-x8-generic-cir-brep-executor-lab.md`
+
+`Claude on Stepped Boolean Root Cause.txt` was not present in repository at verification time.
+
+## 3) Validator cliff result
+
+Confirmed.
+
+Observed behavior for stepped-like 3-stage coaxial stack on box root:
+
+1. subtract through hole (`r=2`, `h=30`) succeeds,
+2. subtract blind continuation (`r=3`, top-entry depth 6) succeeds,
+3. subtract larger shallower blind (`r=4`, top-entry depth 3) fails.
+
+Observed diagnostic on step 3:
+
+- `Code`: `NotImplemented` (kernel-level mapping),
+- `Source`: `BrepBoolean.AnalyticHole.HoleInterference`,
+- message contains overlapping-hole rejection.
+
+Mechanically this aligns with validator loop behavior:
+
+- coaxial family classification is gated inside `if (composition.Holes.Count == 1 && (existingHole.IsBlind || nextHole.IsBlind))`,
+- by step 3, `composition.Holes.Count == 2`, so no coaxial-stack classification path is executed,
+- default pair overlap checks execute and reject as interference.
+
+## 4) Builder cliff result
+
+Hypothesis **not** confirmed as stated.
+
+Builder probe using an injected N=3 coaxial composition (through + blind + blind) succeeded in current `BuildComposition` path and passed binding validation in this test harness.
+
+So in this A0 probe, the builder did **not** emit `UnsupportedBlindHoleComposition` for N=3 shape data. That means validator cliff is clearly observed, while builder-side rejection did not reproduce with this controlled composition input.
+
+## 5) `skipPairChecks` inspection
+
+Current production flow:
+
+- produced in `TryValidateBlindContinuationCandidate(..., out bool skipPairChecks, ...)`,
+- consumed in `TryValidateNextSubtract` loop with `if (skipPairChecks) continue;`.
+
+Behavior in current implementation is effectively pair-local, per existing hole iteration:
+
+- only evaluated in the `composition.Holes.Count == 1` blind-continuation gate,
+- for step-2 two-hole compositions it can skip remaining checks for that one pair,
+- there is no current mixed-family partial iteration state for N>=3 because the blind continuation classifier gate does not run once hole count exceeds 1.
+
+This means the feared partial-loop mixed-family dependency is not exercised in the current stepped third-subtract path; the cliff is earlier (gate condition itself).
+
+## 6) Hypothesis status
+
+**Outcome B — partially confirmed.**
+
+- Validator cliff: confirmed.
+- Builder cliff as explicit N>=3 rejection: not reproduced in this A0 probe; observed behavior differed (successful build for injected N=3 composition).
+
+## 7) Recommended next milestone
+
+Proceed to:
+
+1. `BREP-BOOLEAN-STACK-A1`: validator continuation gate/generalization with explicit candidate scoring/diagnostics for N-level coaxial families.
+2. `BREP-BOOLEAN-STACK-A2`: dedicated N-level coaxial stepped builder/topology path, bounded and test-driven.
+
+Keep both milestones behavior-bounded and diagnostic-forward.