Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Migrate boolean builders to Brep surgery APIs

Yuechen Lib875f549c2a2
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryRecipeParityTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryRecipeParityTests.cs
new file mode 100644
index 00000000..f5ad1b17
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryRecipeParityTests.cs
@@ -0,0 +1,66 @@
+using System.Security.Cryptography;
+using System.Text;
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.StandardLibrary;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Surgery;
+
+public sealed class BrepSurgeryRecipeParityTests
+{
+ [Fact]
+ public void MigratedOrthogonalUnion_RetainsCanonicalTopologyAndStep()
+ {
+ var body = BrepBooleanOrthogonalUnionBuilder.BuildFromCells([
+ new AxisAlignedBoxExtents(0d, 2d, 0d, 2d, 0d, 1d),
+ new AxisAlignedBoxExtents(2d, 4d, 0d, 2d, 0d, 1d),
+ ]).Value;
+
+ AssertCanonical(body, 8, 12, 6, "09e6b8d838d08748d60fe6f08f0bfcb09282eb983d26d6fc51956cf5e8828de2");
+ }
+
+ [Fact]
+ public void MigratedCylinderRootKeyway_RetainsCanonicalTopologyAndStep()
+ {
+ var shaft = BrepPrimitives.CreateCylinder(15d, 80d).Value;
+ var tool = BrepBooleanBoxRecognition.CreateBoxFromExtents(
+ new AxisAlignedBoxExtents(5d, 15d, -3d, 3d, -45d, 45d)).Value;
+ var body = BrepBoolean.Subtract(shaft, tool).Value;
+
+ AssertCanonical(body, 8, 12, 6, "b91443673ab595a0449e91359aa697ae597a03efdb90d7394ac937107e25ae98");
+ }
+
+ [Fact]
+ public void MigratedPolygonalThroughCut_RetainsCanonicalTopologyAndStep()
+ {
+ var root = StandardLibraryPrimitives.CreateRoundedCornerBox(24d, 18d, 20d, 4d).Value;
+ var tool = StandardLibraryPrimitives.CreateSlotCut(10d, 4d, 24d, 2d).Value;
+ var body = BrepBoolean.Subtract(root, tool).Value;
+
+ AssertCanonical(body, 128, 192, 66, "8554faf173a41abeb15facbeb2bd3cceb4f2ea486d6aa1e1b11c0740b922fe7d");
+ }
+
+ private static void AssertCanonical(BrepBody body, int vertices, int edges, int faces, string expectedStepSha256)
+ {
+ Assert.Equal(vertices, body.Topology.Vertices.Count());
+ Assert.Equal(edges, body.Topology.Edges.Count());
+ Assert.Equal(faces, body.Topology.Faces.Count());
+ Assert.Equal(edges, body.Geometry.Curves.Count());
+ Assert.Equal(faces, body.Geometry.Surfaces.Count());
+ Assert.Equal(edges, body.Bindings.EdgeBindings.Count());
+ Assert.Equal(faces, body.Bindings.FaceBindings.Count());
+ Assert.True(BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true).IsSuccess);
+
+ var export = Step242Exporter.ExportBody(body);
+ Assert.True(export.IsSuccess, string.Join(Environment.NewLine, export.Diagnostics.Select(diagnostic => diagnostic.Message)));
+ Assert.Equal(expectedStepSha256, Sha256(export.Value));
+
+ var reimport = Step242Importer.ImportBody(export.Value);
+ Assert.True(reimport.IsSuccess, string.Join(Environment.NewLine, reimport.Diagnostics.Select(diagnostic => diagnostic.Message)));
+ Assert.True(BrepBindingValidator.Validate(reimport.Value, requireAllEdgeAndFaceBindings: true).IsSuccess);
+ }
+
+ private static string Sha256(string value)
+ => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(value))).ToLowerInvariant();
+}
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryTests.cs
new file mode 100644
index 00000000..82d4f862
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Surgery/BrepSurgeryTests.cs
@@ -0,0 +1,138 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Surgery;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Surgery;
+
+public sealed class BrepSurgeryTests
+{
+ [Fact]
+ public void CreateKnownLoop_ConstructsClosedRectangularCycleWithDeterministicLinks()
+ {
+ var builder = new TopologyBuilder();
+ var vertices = Enumerable.Range(0, 4).Select(_ => builder.AddVertex()).ToArray();
+ var edges = new[]
+ {
+ builder.AddEdge(vertices[0], vertices[1]),
+ builder.AddEdge(vertices[1], vertices[2]),
+ builder.AddEdge(vertices[2], vertices[3]),
+ builder.AddEdge(vertices[3], vertices[0]),
+ };
+
+ var result = BrepLoopBuilder.CreateKnownLoop(builder, edges.Select(BrepEdgeUse.Forward).ToArray());
+
+ Assert.True(result.IsSuccess);
+ var loop = builder.Model.GetLoop(result.Value);
+ Assert.Equal(4, loop.CoedgeIds.Count);
+ for (var index = 0; index < loop.CoedgeIds.Count; index++)
+ {
+ var coedge = builder.Model.GetCoedge(loop.CoedgeIds[index]);
+ Assert.Equal(loop.CoedgeIds[(index + 1) % 4], coedge.NextCoedgeId);
+ Assert.Equal(loop.CoedgeIds[(index + 3) % 4], coedge.PrevCoedgeId);
+ }
+ }
+
+ [Fact]
+ public void CreateKnownLoop_RejectsOpenAndRepeatedDirectedUsesWithoutMutation()
+ {
+ var builder = new TopologyBuilder();
+ var v1 = builder.AddVertex();
+ var v2 = builder.AddVertex();
+ var v3 = builder.AddVertex();
+ var e1 = builder.AddEdge(v1, v2);
+ var e2 = builder.AddEdge(v3, v1);
+
+ var open = BrepLoopBuilder.CreateKnownLoop(builder, [BrepEdgeUse.Forward(e1), BrepEdgeUse.Forward(e2)]);
+ var repeated = BrepLoopBuilder.CreateKnownLoop(builder, [BrepEdgeUse.Forward(e1), BrepEdgeUse.Forward(e1)]);
+
+ Assert.False(open.IsSuccess);
+ Assert.Contains(open.Diagnostics, diagnostic => diagnostic.Message.Contains("open", StringComparison.OrdinalIgnoreCase));
+ Assert.False(repeated.IsSuccess);
+ Assert.Contains(repeated.Diagnostics, diagnostic => diagnostic.Message.Contains("repeats", StringComparison.OrdinalIgnoreCase));
+ Assert.Empty(builder.Model.Loops);
+ Assert.Empty(builder.Model.Coedges);
+ }
+
+ [Fact]
+ public void CreateKnownFace_PreservesCallerSuppliedOuterThenInnerLoopRoles()
+ {
+ var builder = new TopologyBuilder();
+ var vertices = Enumerable.Range(0, 4).Select(_ => builder.AddVertex()).ToArray();
+ var outerEdges = new[]
+ {
+ builder.AddEdge(vertices[0], vertices[1]),
+ builder.AddEdge(vertices[1], vertices[2]),
+ builder.AddEdge(vertices[2], vertices[3]),
+ builder.AddEdge(vertices[3], vertices[0]),
+ };
+ var periodicVertex = builder.AddVertex();
+ var circularTrimEdge = builder.AddEdge(periodicVertex, periodicVertex);
+
+ var result = BrepFaceBuilder.CreateKnownFace(
+ builder,
+ outerEdges.Select(BrepEdgeUse.Forward).ToArray(),
+ [[BrepEdgeUse.Reversed(circularTrimEdge)]]);
+
+ Assert.True(result.IsSuccess);
+ var face = builder.Model.GetFace(result.Value);
+ Assert.Equal(2, face.LoopIds.Count);
+ var innerCoedge = builder.Model.GetCoedge(builder.Model.GetLoop(face.LoopIds[1]).CoedgeIds.Single());
+ Assert.True(innerCoedge.IsReversed);
+ }
+
+ [Fact]
+ public void CreateClosedBody_AssemblesKnownCubeAndRejectsOpenFaceSet()
+ {
+ var builder = new TopologyBuilder();
+ var vertices = Enumerable.Range(0, 8).Select(_ => builder.AddVertex()).ToArray();
+ var edges = new[]
+ {
+ builder.AddEdge(vertices[0], vertices[1]), builder.AddEdge(vertices[1], vertices[2]),
+ builder.AddEdge(vertices[2], vertices[3]), builder.AddEdge(vertices[3], vertices[0]),
+ builder.AddEdge(vertices[4], vertices[5]), builder.AddEdge(vertices[5], vertices[6]),
+ builder.AddEdge(vertices[6], vertices[7]), builder.AddEdge(vertices[7], vertices[4]),
+ builder.AddEdge(vertices[0], vertices[4]), builder.AddEdge(vertices[1], vertices[5]),
+ builder.AddEdge(vertices[2], vertices[6]), builder.AddEdge(vertices[3], vertices[7]),
+ };
+
+ var faceUseSets = new IReadOnlyList<BrepEdgeUse>[]
+ {
+ [BrepEdgeUse.Forward(edges[0]), BrepEdgeUse.Forward(edges[1]), BrepEdgeUse.Forward(edges[2]), BrepEdgeUse.Forward(edges[3])],
+ [BrepEdgeUse.Reversed(edges[7]), BrepEdgeUse.Reversed(edges[6]), BrepEdgeUse.Reversed(edges[5]), BrepEdgeUse.Reversed(edges[4])],
+ [BrepEdgeUse.Forward(edges[8]), BrepEdgeUse.Forward(edges[4]), BrepEdgeUse.Reversed(edges[9]), BrepEdgeUse.Reversed(edges[0])],
+ [BrepEdgeUse.Forward(edges[9]), BrepEdgeUse.Forward(edges[5]), BrepEdgeUse.Reversed(edges[10]), BrepEdgeUse.Reversed(edges[1])],
+ [BrepEdgeUse.Forward(edges[10]), BrepEdgeUse.Forward(edges[6]), BrepEdgeUse.Reversed(edges[11]), BrepEdgeUse.Reversed(edges[2])],
+ [BrepEdgeUse.Forward(edges[11]), BrepEdgeUse.Forward(edges[7]), BrepEdgeUse.Reversed(edges[8]), BrepEdgeUse.Reversed(edges[3])],
+ };
+ var faces = faceUseSets.Select(uses => BrepFaceBuilder.CreateKnownFace(builder, uses)).ToArray();
+ Assert.All(faces, face => Assert.True(face.IsSuccess));
+
+ var openResult = BrepShellAssembler.CreateClosedBody(builder, faces.Take(5).Select(face => face.Value).ToArray());
+ var closedResult = BrepShellAssembler.CreateClosedBody(builder, faces.Select(face => face.Value).ToArray());
+
+ Assert.False(openResult.IsSuccess);
+ Assert.Contains(openResult.Diagnostics, diagnostic => diagnostic.Message.Contains("expected exactly 2", StringComparison.Ordinal));
+ Assert.True(closedResult.IsSuccess);
+ Assert.Single(builder.Model.Shells);
+ Assert.Single(builder.Model.Bodies);
+ }
+
+ [Fact]
+ public void ValidateBody_RejectsNonFiniteVertexGeometryWithTypedDiagnostic()
+ {
+ var source = BrepPrimitives.CreateBox(2d, 3d, 4d).Value;
+ var points = source.Topology.Vertices.ToDictionary(
+ vertex => vertex.Id,
+ vertex => source.TryGetVertexPoint(vertex.Id, out var point) ? point : Point3D.Origin);
+ points[points.Keys.OrderBy(id => id.Value).First()] = new Point3D(double.NaN, 0d, 0d);
+ var invalid = new BrepBody(source.Topology, source.Geometry, source.Bindings, points);
+
+ var result = BrepSurgeryValidation.ValidateBody(invalid);
+
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, diagnostic =>
+ diagnostic.Source == "Brep.Surgery.Validation"
+ && diagnostic.Message.Contains("finite geometry point", StringComparison.Ordinal));
+ }
+}
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCylinderOpenSlotBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCylinderOpenSlotBuilder.cs
index 80a46361..5e544fd2 100644
--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCylinderOpenSlotBuilder.cs
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCylinderOpenSlotBuilder.cs
@@ -1,4 +1,5 @@
using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Brep.Surgery;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Geometry.Curves;
using Aetheris.Kernel.Core.Geometry.Surfaces;
@@ -86,50 +87,66 @@ internal static class BrepBooleanCylinderOpenSlotBuilder
var eBottomRadialMax = builder.AddEdge(vBottomFloorMax, vBottomArcMax);
var eBottomRadialMin = builder.AddEdge(vBottomArcMin, vBottomFloorMin);
- var sideCylinderFace = AddFaceWithLoop(builder, [
- EdgeUse.Forward(eCylMax),
- EdgeUse.Forward(eTopArc),
- EdgeUse.Forward(eCylMin),
- EdgeUse.Forward(eBottomArc),
+ // This bounded recipe knows the retained cylinder arc, slot floor, two
+ // radial walls, and both caps before editing begins. Surgery realizes
+ // those explicit cycles and never searches for an affected feature.
+ var sideCylinderFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Forward(eCylMax),
+ BrepEdgeUse.Forward(eTopArc),
+ BrepEdgeUse.Forward(eCylMin),
+ BrepEdgeUse.Forward(eBottomArc),
]);
-
- var topCapFace = AddFaceWithLoop(builder, [
- EdgeUse.Reversed(eTopArc),
- EdgeUse.Forward(eTopRadialMax),
- EdgeUse.Forward(eTopFloor),
- EdgeUse.Forward(eTopRadialMin),
+ var topCapFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Reversed(eTopArc),
+ BrepEdgeUse.Forward(eTopRadialMax),
+ BrepEdgeUse.Forward(eTopFloor),
+ BrepEdgeUse.Forward(eTopRadialMin),
]);
-
- var bottomCapFace = AddFaceWithLoop(builder, [
- EdgeUse.Reversed(eBottomArc),
- EdgeUse.Reversed(eBottomRadialMin),
- EdgeUse.Forward(eBottomFloor),
- EdgeUse.Forward(eBottomRadialMax),
+ var bottomCapFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Reversed(eBottomArc),
+ BrepEdgeUse.Reversed(eBottomRadialMin),
+ BrepEdgeUse.Forward(eBottomFloor),
+ BrepEdgeUse.Forward(eBottomRadialMax),
]);
-
- var floorFace = AddFaceWithLoop(builder, [
- EdgeUse.Reversed(eTopFloor),
- EdgeUse.Forward(eFloorMax),
- EdgeUse.Forward(eBottomFloor),
- EdgeUse.Reversed(eFloorMin),
+ var floorFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Reversed(eTopFloor),
+ BrepEdgeUse.Forward(eFloorMax),
+ BrepEdgeUse.Forward(eBottomFloor),
+ BrepEdgeUse.Reversed(eFloorMin),
]);
-
- var sideMaxFace = AddFaceWithLoop(builder, [
- EdgeUse.Reversed(eTopRadialMax),
- EdgeUse.Reversed(eCylMax),
- EdgeUse.Reversed(eBottomRadialMax),
- EdgeUse.Forward(eFloorMax),
+ var sideMaxFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Reversed(eTopRadialMax),
+ BrepEdgeUse.Reversed(eCylMax),
+ BrepEdgeUse.Reversed(eBottomRadialMax),
+ BrepEdgeUse.Forward(eFloorMax),
]);
-
- var sideMinFace = AddFaceWithLoop(builder, [
- EdgeUse.Reversed(eTopRadialMin),
- EdgeUse.Forward(eCylMin),
- EdgeUse.Reversed(eBottomRadialMin),
- EdgeUse.Reversed(eFloorMin),
+ var sideMinFace = AddFaceWithLegacyLoopSense(builder, [
+ BrepEdgeUse.Reversed(eTopRadialMin),
+ BrepEdgeUse.Forward(eCylMin),
+ BrepEdgeUse.Reversed(eBottomRadialMin),
+ BrepEdgeUse.Reversed(eFloorMin),
]);
- var shell = builder.AddShell([sideCylinderFace, topCapFace, bottomCapFace, floorFace, sideMaxFace, sideMinFace]);
- builder.AddBody([shell]);
+ var faceResults = new[] { sideCylinderFace, topCapFace, bottomCapFace, floorFace, sideMaxFace, sideMinFace };
+ var failedFace = faceResults.FirstOrDefault(result => !result.IsSuccess);
+ if (failedFace is not null)
+ {
+ return KernelResult<BrepBody>.Failure(failedFace.Diagnostics);
+ }
+
+ var faceIds = faceResults.Select(result => result.Value).ToArray();
+ var assembly = BrepShellAssembler.CreateClosedBody(builder, faceIds);
+ if (!assembly.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(assembly.Diagnostics);
+ }
+
+ var sideCylinderFaceId = faceIds[0];
+ var topCapFaceId = faceIds[1];
+ var bottomCapFaceId = faceIds[2];
+ var floorFaceId = faceIds[3];
+ var sideMaxFaceId = faceIds[4];
+ var sideMinFaceId = faceIds[5];
var geometry = new BrepGeometryStore();
var zAxis = Direction3D.Create(new Vector3D(0d, 0d, 1d));
@@ -178,12 +195,12 @@ internal static class BrepBooleanCylinderOpenSlotBuilder
bindings.AddEdgeBinding(new EdgeGeometryBinding(eBottomRadialMax, new CurveGeometryId(11), new ParameterInterval(0d, xOnCylinderAtMaxY - floorX)));
bindings.AddEdgeBinding(new EdgeGeometryBinding(eBottomRadialMin, new CurveGeometryId(12), new ParameterInterval(0d, xOnCylinderAtMinY - floorX)));
- bindings.AddFaceBinding(new FaceGeometryBinding(sideCylinderFace, new SurfaceGeometryId(1)));
- bindings.AddFaceBinding(new FaceGeometryBinding(topCapFace, new SurfaceGeometryId(2)));
- bindings.AddFaceBinding(new FaceGeometryBinding(bottomCapFace, new SurfaceGeometryId(3)));
- bindings.AddFaceBinding(new FaceGeometryBinding(floorFace, new SurfaceGeometryId(4)));
- bindings.AddFaceBinding(new FaceGeometryBinding(sideMaxFace, new SurfaceGeometryId(5)));
- bindings.AddFaceBinding(new FaceGeometryBinding(sideMinFace, new SurfaceGeometryId(6)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(sideCylinderFaceId, new SurfaceGeometryId(1)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(topCapFaceId, new SurfaceGeometryId(2)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(bottomCapFaceId, new SurfaceGeometryId(3)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(floorFaceId, new SurfaceGeometryId(4)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(sideMaxFaceId, new SurfaceGeometryId(5)));
+ bindings.AddFaceBinding(new FaceGeometryBinding(sideMinFaceId, new SurfaceGeometryId(6)));
var points = new Dictionary<VertexId, Point3D>
{
@@ -198,41 +215,27 @@ internal static class BrepBooleanCylinderOpenSlotBuilder
};
var body = new BrepBody(builder.Model, geometry, bindings, points, composition);
- var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);
+ var validation = BrepSurgeryValidation.ValidateBody(body, requireAllEdgeAndFaceBindings: true);
return validation.IsSuccess
? KernelResult<BrepBody>.Success(body, validation.Diagnostics)
: KernelResult<BrepBody>.Failure(validation.Diagnostics);
}
- private static FaceId AddFaceWithLoop(TopologyBuilder builder, IReadOnlyList<EdgeUse> edgeUses)
- {
- var loopId = builder.AllocateLoopId();
- var coedgeIds = new CoedgeId[edgeUses.Count];
- for (var i = 0; i < edgeUses.Count; i++)
- {
- coedgeIds[i] = builder.AllocateCoedgeId();
- }
-
- for (var i = 0; i < edgeUses.Count; i++)
- {
- var next = coedgeIds[(i + 1) % edgeUses.Count];
- var prev = coedgeIds[(i + edgeUses.Count - 1) % edgeUses.Count];
- builder.AddCoedge(new Coedge(coedgeIds[i], edgeUses[i].EdgeId, loopId, next, prev, edgeUses[i].IsReversed));
- }
-
- builder.AddLoop(new Loop(loopId, coedgeIds));
- return builder.AddFace([loopId]);
- }
-
private static double NormalizeAngle(double value)
{
var angle = value % (2d * double.Pi);
return angle < 0d ? angle + (2d * double.Pi) : angle;
}
- private readonly record struct EdgeUse(EdgeId EdgeId, bool IsReversed)
+ // M3 preserves the established keyway coedge senses byte-for-byte. The
+ // recipe still hands the completed, explicitly selected loop to Surgery;
+ // strict new callers use BrepLoopBuilder instead of this control seam.
+ private static KernelResult<FaceId> AddFaceWithLegacyLoopSense(TopologyBuilder builder, IReadOnlyList<BrepEdgeUse> edgeUses)
{
- public static EdgeUse Forward(EdgeId edgeId) => new(edgeId, false);
- public static EdgeUse Reversed(EdgeId edgeId) => new(edgeId, true);
+ var loop = BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(builder, edgeUses);
+ return loop.IsSuccess
+ ? BrepFaceBuilder.CreateKnownFaceFromLoops(builder, loop.Value)
+ : KernelResult<FaceId>.Failure(loop.Diagnostics);
}
+
}
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanOrthogonalUnionBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanOrthogonalUnionBuilder.cs
index 9ff75f9a..9b164b41 100644
--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanOrthogonalUnionBuilder.cs
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanOrthogonalUnionBuilder.cs
@@ -6,6 +6,7 @@ using Aetheris.Kernel.Core.Numerics;
using Aetheris.Kernel.Core.Results;
using Aetheris.Kernel.Core.Topology;
using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Brep.Surgery;
namespace Aetheris.Kernel.Core.Brep.Boolean;
@@ -79,7 +80,15 @@ public static class BrepBooleanOrthogonalUnionBuilder
OrientEdgeUse(edges[3], corners[3], corners[0]),
};
- var faceId = AddFaceWithLoop(builder, uses);
+ // The occupied-cell recipe already selected this boundary rectangle
+ // and its winding. Surgery only realizes that known topology cycle.
+ var faceResult = AddFaceWithLegacyLoopSense(builder, uses);
+ if (!faceResult.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(faceResult.Diagnostics);
+ }
+
+ var faceId = faceResult.Value;
var rectSurfaceId = new SurfaceGeometryId(surfaceId);
geometry.AddSurface(rectSurfaceId, SurfaceGeometry.FromPlane(rect.ToPlaneSurface()));
faceBindings.Add((faceId, rectSurfaceId));
@@ -120,6 +129,9 @@ public static class BrepBooleanOrthogonalUnionBuilder
}
var faces = builder.Model.Faces.OrderBy(f => f.Id.Value).Select(f => f.Id).ToArray();
+ // Orthogonal retessellation can retain T-junction incidence across
+ // merged coplanar rectangles. Preserve its canonical assembly path in
+ // M3; strict two-use shell assembly is exercised by the other recipes.
var shell = builder.AddShell(faces);
builder.AddBody([shell]);
@@ -135,7 +147,7 @@ public static class BrepBooleanOrthogonalUnionBuilder
}
var body = new BrepBody(builder.Model, geometry, bindings, vertexPoints, safeBooleanComposition: null);
- var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);
+ var validation = BrepSurgeryValidation.ValidateBody(body, requireAllEdgeAndFaceBindings: true);
return validation.IsSuccess
? KernelResult<BrepBody>.Success(body, validation.Diagnostics)
: KernelResult<BrepBody>.Failure(validation.Diagnostics);
@@ -154,32 +166,23 @@ public static class BrepBooleanOrthogonalUnionBuilder
}
}
- private static EdgeUse OrientEdgeUse(EdgeId edgeId, in PointKey start, in PointKey end)
+ private static BrepEdgeUse OrientEdgeUse(EdgeId edgeId, in PointKey start, in PointKey end)
{
var canonical = EdgeKey.Create(start, end);
return canonical.Start.Equals(start) && canonical.End.Equals(end)
- ? EdgeUse.Forward(edgeId)
- : EdgeUse.Reversed(edgeId);
+ ? BrepEdgeUse.Forward(edgeId)
+ : BrepEdgeUse.Reversed(edgeId);
}
- private static FaceId AddFaceWithLoop(TopologyBuilder builder, IReadOnlyList<EdgeUse> edgeUses)
+ // Control seam retained for M3 parity: this builder's historical coedge
+ // sense predates DirectedEdgeUse closure validation. The known resulting
+ // loop still crosses Surgery for explicit face ownership.
+ private static KernelResult<FaceId> AddFaceWithLegacyLoopSense(TopologyBuilder builder, IReadOnlyList<BrepEdgeUse> edgeUses)
{
- var loopId = builder.AllocateLoopId();
- var coedgeIds = new CoedgeId[edgeUses.Count];
- for (var i = 0; i < edgeUses.Count; i++)
- {
- coedgeIds[i] = builder.AllocateCoedgeId();
- }
-
- for (var i = 0; i < edgeUses.Count; i++)
- {
- var next = coedgeIds[(i + 1) % edgeUses.Count];
- var prev = coedgeIds[(i + edgeUses.Count - 1) % edgeUses.Count];
- builder.AddCoedge(new Coedge(coedgeIds[i], edgeUses[i].EdgeId, loopId, next, prev, edgeUses[i].IsReversed));
- }
-
- builder.AddLoop(new Loop(loopId, coedgeIds));
- return builder.AddFace([loopId]);
+ var loop = BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(builder, edgeUses);
+ return loop.IsSuccess
+ ? BrepFaceBuilder.CreateKnownFaceFromLoops(builder, loop.Value)
+ : KernelResult<FaceId>.Failure(loop.Diagnostics);
}
private static List<FaceRect> CollectBoundaryFaceRectangles(IReadOnlyList<AxisAlignedBoxExtents> cells)
@@ -418,9 +421,4 @@ public static class BrepBooleanOrthogonalUnionBuilder
}
}
- private readonly record struct EdgeUse(EdgeId EdgeId, bool IsReversed)
- {
- public static EdgeUse Forward(EdgeId edgeId) => new(edgeId, IsReversed: false);
- public static EdgeUse Reversed(EdgeId edgeId) => new(edgeId, IsReversed: true);
- }
}
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.cs
index 5a197bdf..cee10f05 100644
--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.cs
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.cs
@@ -1,4 +1,5 @@
using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Brep.Surgery;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Geometry.Curves;
using Aetheris.Kernel.Core.Geometry.Surfaces;
@@ -48,22 +49,42 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
var outerVerticalEdges = BuildVerticalEdges(builder, outerBottomVertices, outerTopVertices);
var innerVerticalEdges = BuildVerticalEdges(builder, innerBottomVertices, innerTopVertices);
- var bottomFace = AddFaceWithLoops(
+ // The bounded through-cut recipe supplies both footprints, their inner
+ // roles, and every side correspondence. Surgery realizes those known
+ // loops; it does not derive a cut from intersection evidence.
+ var bottomFace = AddFaceWithLegacyLoopSenses(
builder,
- [.. outerBottomEdges.Select(EdgeUse.Forward)],
- [.. innerBottomEdges.Select(EdgeUse.Reversed)]);
+ [.. outerBottomEdges.Select(BrepEdgeUse.Forward)],
+ [.. innerBottomEdges.Select(BrepEdgeUse.Reversed)]);
- var topFace = AddFaceWithLoops(
+ var topFace = AddFaceWithLegacyLoopSenses(
builder,
- [.. outerTopEdges.Reverse().Select(EdgeUse.Reversed)],
- [.. innerTopEdges.Select(EdgeUse.Forward)]);
+ [.. outerTopEdges.Reverse().Select(BrepEdgeUse.Reversed)],
+ [.. innerTopEdges.Select(BrepEdgeUse.Forward)]);
- var faces = new List<FaceId> { bottomFace, topFace };
- faces.AddRange(AddSideFaces(builder, outerBottomEdges, outerTopEdges, outerVerticalEdges, reverseInnerOrientation: false));
- faces.AddRange(AddSideFaces(builder, innerBottomEdges, innerTopEdges, innerVerticalEdges, reverseInnerOrientation: true));
+ if (!bottomFace.IsSuccess || !topFace.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(
+ !bottomFace.IsSuccess ? bottomFace.Diagnostics : topFace.Diagnostics);
+ }
+
+ var outerSideFaces = AddSideFaces(builder, outerBottomEdges, outerTopEdges, outerVerticalEdges, reverseInnerOrientation: false);
+ var innerSideFaces = AddSideFaces(builder, innerBottomEdges, innerTopEdges, innerVerticalEdges, reverseInnerOrientation: true);
+ if (!outerSideFaces.IsSuccess || !innerSideFaces.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(
+ !outerSideFaces.IsSuccess ? outerSideFaces.Diagnostics : innerSideFaces.Diagnostics);
+ }
- var shell = builder.AddShell(faces);
- builder.AddBody([shell]);
+ var faces = new List<FaceId> { bottomFace.Value, topFace.Value };
+ faces.AddRange(outerSideFaces.Value);
+ faces.AddRange(innerSideFaces.Value);
+
+ var assembly = BrepShellAssembler.CreateClosedBody(builder, faces);
+ if (!assembly.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(assembly.Diagnostics);
+ }
var geometry = new BrepGeometryStore();
var bindings = new BrepBindingModel();
@@ -92,8 +113,8 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
bindings.AddFaceBinding(new FaceGeometryBinding(face, sid));
}
- BindFaceToPlane(bottomFace, outerBottomPoints[0], new Vector3D(0d, 0d, -1d), new Vector3D(1d, 0d, 0d));
- BindFaceToPlane(topFace, outerTopPoints[0], new Vector3D(0d, 0d, 1d), new Vector3D(1d, 0d, 0d));
+ BindFaceToPlane(bottomFace.Value, outerBottomPoints[0], new Vector3D(0d, 0d, -1d), new Vector3D(1d, 0d, 0d));
+ BindFaceToPlane(topFace.Value, outerTopPoints[0], new Vector3D(0d, 0d, 1d), new Vector3D(1d, 0d, 0d));
var faceIndex = 2;
for (var i = 0; i < outerBottomPoints.Length; i++)
@@ -126,7 +147,7 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
}
var body = new BrepBody(builder.Model, geometry, bindings, vertexPoints);
- var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);
+ var validation = BrepSurgeryValidation.ValidateBody(body, requireAllEdgeAndFaceBindings: true);
return validation.IsSuccess
? KernelResult<BrepBody>.Success(body, validation.Diagnostics)
: KernelResult<BrepBody>.Failure(validation.Diagnostics);
@@ -154,7 +175,7 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
return edges;
}
- private static IReadOnlyList<FaceId> AddSideFaces(TopologyBuilder builder, EdgeId[] bottom, EdgeId[] top, EdgeId[] vertical, bool reverseInnerOrientation)
+ private static KernelResult<IReadOnlyList<FaceId>> AddSideFaces(TopologyBuilder builder, EdgeId[] bottom, EdgeId[] top, EdgeId[] vertical, bool reverseInnerOrientation)
{
var faces = new List<FaceId>(bottom.Length);
for (var i = 0; i < bottom.Length; i++)
@@ -163,22 +184,28 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
var uses = reverseInnerOrientation
? new[]
{
- EdgeUse.Reversed(bottom[i]),
- EdgeUse.Forward(vertical[i]),
- EdgeUse.Forward(top[i]),
- EdgeUse.Reversed(vertical[next]),
+ BrepEdgeUse.Reversed(bottom[i]),
+ BrepEdgeUse.Forward(vertical[i]),
+ BrepEdgeUse.Forward(top[i]),
+ BrepEdgeUse.Reversed(vertical[next]),
}
: new[]
{
- EdgeUse.Forward(bottom[i]),
- EdgeUse.Forward(vertical[next]),
- EdgeUse.Reversed(top[i]),
- EdgeUse.Reversed(vertical[i]),
+ BrepEdgeUse.Forward(bottom[i]),
+ BrepEdgeUse.Forward(vertical[next]),
+ BrepEdgeUse.Reversed(top[i]),
+ BrepEdgeUse.Reversed(vertical[i]),
};
- faces.Add(AddFaceWithLoop(builder, uses));
+ var face = AddFaceWithLegacyLoopSense(builder, uses);
+ if (!face.IsSuccess)
+ {
+ return KernelResult<IReadOnlyList<FaceId>>.Failure(face.Diagnostics);
+ }
+
+ faces.Add(face.Value);
}
- return faces;
+ return KernelResult<IReadOnlyList<FaceId>>.Success(faces);
}
private static void BindLoopEdges(EdgeId[] edges, Point3D[] points, Action<EdgeId, Point3D, Point3D> bind)
@@ -197,42 +224,34 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilder
}
}
- private static FaceId AddFaceWithLoops(TopologyBuilder builder, IReadOnlyList<EdgeUse> outerLoop, IReadOnlyList<EdgeUse> innerLoop)
+ // These control seams retain the pre-M3 prismatic coedge senses. Surgery
+ // owns the face created from the recipe-supplied loop IDs; strict new loop
+ // construction goes through BrepLoopBuilder and its closure diagnostics.
+ private static KernelResult<FaceId> AddFaceWithLegacyLoopSenses(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> outerUses,
+ IReadOnlyList<BrepEdgeUse> innerUses)
{
- var outerLoopId = AddLoop(builder, outerLoop);
- var innerLoopId = AddLoop(builder, innerLoop);
- return builder.AddFace([outerLoopId, innerLoopId]);
- }
-
- private static FaceId AddFaceWithLoop(TopologyBuilder builder, IReadOnlyList<EdgeUse> edgeUses)
- {
- var loopId = AddLoop(builder, edgeUses);
- return builder.AddFace([loopId]);
- }
-
- private static LoopId AddLoop(TopologyBuilder builder, IReadOnlyList<EdgeUse> edgeUses)
- {
- var loopId = builder.AllocateLoopId();
- var coedgeIds = new CoedgeId[edgeUses.Count];
- for (var i = 0; i < edgeUses.Count; i++)
+ var outerLoop = BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(builder, outerUses);
+ if (!outerLoop.IsSuccess)
{
- coedgeIds[i] = builder.AllocateCoedgeId();
+ return KernelResult<FaceId>.Failure(outerLoop.Diagnostics);
}
- for (var i = 0; i < edgeUses.Count; i++)
- {
- var next = coedgeIds[(i + 1) % edgeUses.Count];
- var prev = coedgeIds[(i + edgeUses.Count - 1) % edgeUses.Count];
- builder.AddCoedge(new Coedge(coedgeIds[i], edgeUses[i].EdgeId, loopId, next, prev, edgeUses[i].IsReversed));
- }
-
- builder.AddLoop(new Loop(loopId, coedgeIds));
- return loopId;
+ var innerLoop = BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(builder, innerUses);
+ return innerLoop.IsSuccess
+ ? BrepFaceBuilder.CreateKnownFaceFromLoops(builder, outerLoop.Value, [innerLoop.Value])
+ : KernelResult<FaceId>.Failure(innerLoop.Diagnostics);
}
- private readonly record struct EdgeUse(EdgeId EdgeId, bool IsReversed)
+ private static KernelResult<FaceId> AddFaceWithLegacyLoopSense(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> edgeUses)
{
- public static EdgeUse Forward(EdgeId edgeId) => new(edgeId, false);
- public static EdgeUse Reversed(EdgeId edgeId) => new(edgeId, true);
+ var loop = BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(builder, edgeUses);
+ return loop.IsSuccess
+ ? BrepFaceBuilder.CreateKnownFaceFromLoops(builder, loop.Value)
+ : KernelResult<FaceId>.Failure(loop.Diagnostics);
}
+
}
diff --git a/Aetheris.Kernel.Core/Brep/Surgery/BrepEdgeUse.cs b/Aetheris.Kernel.Core/Brep/Surgery/BrepEdgeUse.cs
new file mode 100644
index 00000000..771994ea
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Surgery/BrepEdgeUse.cs
@@ -0,0 +1,14 @@
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Surgery;
+
+/// <summary>
+/// An explicitly oriented use of a caller-selected topology edge.
+/// Surgery never discovers the edge or its orientation.
+/// </summary>
+internal readonly record struct BrepEdgeUse(EdgeId EdgeId, bool IsReversed)
+{
+ public static BrepEdgeUse Forward(EdgeId edgeId) => new(edgeId, IsReversed: false);
+
+ public static BrepEdgeUse Reversed(EdgeId edgeId) => new(edgeId, IsReversed: true);
+}
diff --git a/Aetheris.Kernel.Core/Brep/Surgery/BrepFaceBuilder.cs b/Aetheris.Kernel.Core/Brep/Surgery/BrepFaceBuilder.cs
new file mode 100644
index 00000000..ebcd8a24
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Surgery/BrepFaceBuilder.cs
@@ -0,0 +1,89 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Surgery;
+
+/// <summary>
+/// Creates a topology face from caller-authorized outer and inner loops.
+/// Loop zero is outer by contract; remaining loops are caller-oriented inner trims.
+/// Surface binding remains an explicit recipe responsibility.
+/// </summary>
+internal static class BrepFaceBuilder
+{
+ public static KernelResult<FaceId> CreateKnownFaceFromLoops(
+ TopologyBuilder builder,
+ LoopId outerLoop,
+ IReadOnlyList<LoopId>? innerLoops = null)
+ {
+ ArgumentNullException.ThrowIfNull(builder);
+ var loopIds = new List<LoopId>(1 + (innerLoops?.Count ?? 0)) { outerLoop };
+ if (innerLoops is not null)
+ {
+ loopIds.AddRange(innerLoops);
+ }
+
+ var seen = new HashSet<LoopId>();
+ foreach (var loopId in loopIds)
+ {
+ if (!seen.Add(loopId))
+ {
+ return Failure($"Known face repeats loop {loopId.Value}.");
+ }
+
+ if (!builder.Model.TryGetLoop(loopId, out _))
+ {
+ return Failure($"Known face references missing loop {loopId.Value}.");
+ }
+ }
+
+ return KernelResult<FaceId>.Success(builder.AddFace(loopIds));
+ }
+
+ public static KernelResult<FaceId> CreateKnownFace(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> outerLoop,
+ IReadOnlyList<IReadOnlyList<BrepEdgeUse>>? innerLoops = null)
+ {
+ ArgumentNullException.ThrowIfNull(builder);
+ ArgumentNullException.ThrowIfNull(outerLoop);
+
+ var loopIds = new List<LoopId>(1 + (innerLoops?.Count ?? 0));
+ var outer = BrepLoopBuilder.CreateKnownLoop(builder, outerLoop);
+ if (!outer.IsSuccess)
+ {
+ return KernelResult<FaceId>.Failure(outer.Diagnostics);
+ }
+
+ loopIds.Add(outer.Value);
+ if (innerLoops is not null)
+ {
+ foreach (var innerLoop in innerLoops)
+ {
+ if (innerLoop is null)
+ {
+ return Failure("Known face contains a null inner-loop specification.");
+ }
+
+ var inner = BrepLoopBuilder.CreateKnownLoop(builder, innerLoop);
+ if (!inner.IsSuccess)
+ {
+ return KernelResult<FaceId>.Failure(inner.Diagnostics);
+ }
+
+ loopIds.Add(inner.Value);
+ }
+ }
+
+ return KernelResult<FaceId>.Success(builder.AddFace(loopIds));
+ }
+
+ private static KernelResult<FaceId> Failure(string message)
+ => KernelResult<FaceId>.Failure([
+ new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ message,
+ "Brep.Surgery.FaceBuilder"),
+ ]);
+}
diff --git a/Aetheris.Kernel.Core/Brep/Surgery/BrepLoopBuilder.cs b/Aetheris.Kernel.Core/Brep/Surgery/BrepLoopBuilder.cs
new file mode 100644
index 00000000..b9ca446a
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Surgery/BrepLoopBuilder.cs
@@ -0,0 +1,131 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Surgery;
+
+/// <summary>
+/// Realizes a loop from an already-known ordered edge-use cycle.
+/// It validates the supplied cycle but does not infer ordering or feature intent.
+/// </summary>
+internal static class BrepLoopBuilder
+{
+ public static KernelResult<LoopId> CreateKnownLoop(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> orderedEdgeUses)
+ {
+ ArgumentNullException.ThrowIfNull(builder);
+ ArgumentNullException.ThrowIfNull(orderedEdgeUses);
+
+ var validation = ValidateUses(builder, orderedEdgeUses, requireEndpointClosure: true);
+ if (!validation.IsSuccess)
+ {
+ return KernelResult<LoopId>.Failure(validation.Diagnostics);
+ }
+
+ return CreateCycle(builder, orderedEdgeUses);
+ }
+
+ /// <summary>
+ /// Compatibility-only realization for canonical recipes whose historical
+ /// coedge sense predates DirectedEdgeUse endpoint closure. New callers must
+ /// use <see cref="CreateKnownLoop"/>.
+ /// </summary>
+ internal static KernelResult<LoopId> CreateKnownLoopPreservingLegacySense(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> orderedEdgeUses)
+ {
+ ArgumentNullException.ThrowIfNull(builder);
+ ArgumentNullException.ThrowIfNull(orderedEdgeUses);
+ var validation = ValidateUses(builder, orderedEdgeUses, requireEndpointClosure: false);
+ return validation.IsSuccess
+ ? CreateCycle(builder, orderedEdgeUses)
+ : KernelResult<LoopId>.Failure(validation.Diagnostics);
+ }
+
+ private static KernelResult<bool> ValidateUses(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> orderedEdgeUses,
+ bool requireEndpointClosure)
+ {
+ if (orderedEdgeUses.Count == 0)
+ {
+ return ValidationFailure("A known loop requires at least one oriented edge use.");
+ }
+
+ var directedUses = new DirectedEdgeUse[orderedEdgeUses.Count];
+ var seenUses = new HashSet<BrepEdgeUse>();
+ for (var index = 0; index < orderedEdgeUses.Count; index++)
+ {
+ var use = orderedEdgeUses[index];
+ if (!builder.Model.TryGetEdge(use.EdgeId, out var edge) || edge is null)
+ {
+ return ValidationFailure($"Known loop edge use {index} references missing edge {use.EdgeId.Value}.");
+ }
+
+ // Periodic faces legitimately use the same seam once in each sense.
+ // Repeating the identical directed use, however, cannot describe one
+ // simple caller-authorized boundary cycle.
+ if (!seenUses.Add(use))
+ {
+ return ValidationFailure($"Known loop repeats edge {use.EdgeId.Value} with the same orientation.");
+ }
+
+ directedUses[index] = DirectedEdgeUse.Resolve(edge, use.IsReversed);
+ }
+
+ if (requireEndpointClosure)
+ {
+ for (var index = 0; index < directedUses.Length; index++)
+ {
+ var next = (index + 1) % directedUses.Length;
+ if (directedUses[index].EndVertexId != directedUses[next].StartVertexId)
+ {
+ return ValidationFailure(
+ $"Known loop is open between edge uses {index} and {next}: " +
+ $"vertex {directedUses[index].EndVertexId.Value} does not meet vertex {directedUses[next].StartVertexId.Value}.");
+ }
+ }
+ }
+
+ return KernelResult<bool>.Success(true);
+ }
+
+ private static KernelResult<LoopId> CreateCycle(
+ TopologyBuilder builder,
+ IReadOnlyList<BrepEdgeUse> orderedEdgeUses)
+ {
+ var loopId = builder.AllocateLoopId();
+ var coedgeIds = new CoedgeId[orderedEdgeUses.Count];
+ for (var index = 0; index < coedgeIds.Length; index++)
+ {
+ coedgeIds[index] = builder.AllocateCoedgeId();
+ }
+
+ for (var index = 0; index < orderedEdgeUses.Count; index++)
+ {
+ builder.AddCoedge(new Coedge(
+ coedgeIds[index],
+ orderedEdgeUses[index].EdgeId,
+ loopId,
+ coedgeIds[(index + 1) % coedgeIds.Length],
+ coedgeIds[(index + coedgeIds.Length - 1) % coedgeIds.Length],
+ orderedEdgeUses[index].IsReversed));
+ }
+
+ builder.AddLoop(new Loop(loopId, coedgeIds));
+ return KernelResult<LoopId>.Success(loopId);
+ }
+
+ private static KernelResult<LoopId> Failure(string message)
+ => KernelResult<LoopId>.Failure([
+ new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ message,
+ "Brep.Surgery.LoopBuilder"),
+ ]);
+
+ private static KernelResult<bool> ValidationFailure(string message)
+ => KernelResult<bool>.Failure(Failure(message).Diagnostics);
+}
diff --git a/Aetheris.Kernel.Core/Brep/Surgery/BrepShellAssembler.cs b/Aetheris.Kernel.Core/Brep/Surgery/BrepShellAssembler.cs
new file mode 100644
index 00000000..f2f36228
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Surgery/BrepShellAssembler.cs
@@ -0,0 +1,80 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Surgery;
+
+internal readonly record struct BrepShellAssembly(ShellId ShellId, BodyId BodyId);
+
+/// <summary>
+/// Assembles one known face set into one shell/body pair. The caller owns face
+/// selection; Surgery checks ownership and closed two-use edge incidence.
+/// </summary>
+internal static class BrepShellAssembler
+{
+ public static KernelResult<BrepShellAssembly> CreateClosedBody(
+ TopologyBuilder builder,
+ IReadOnlyList<FaceId> faceIds)
+ {
+ ArgumentNullException.ThrowIfNull(builder);
+ ArgumentNullException.ThrowIfNull(faceIds);
+
+ if (faceIds.Count == 0)
+ {
+ return Failure("Closed shell assembly requires at least one caller-selected face.");
+ }
+
+ var seenFaces = new HashSet<FaceId>();
+ var edgeUseCounts = new Dictionary<EdgeId, int>();
+ foreach (var faceId in faceIds)
+ {
+ if (!seenFaces.Add(faceId))
+ {
+ return Failure($"Closed shell assembly repeats face {faceId.Value}.");
+ }
+
+ if (!builder.Model.TryGetFace(faceId, out var face) || face is null)
+ {
+ return Failure($"Closed shell assembly references missing face {faceId.Value}.");
+ }
+
+ foreach (var loopId in face.LoopIds)
+ {
+ if (!builder.Model.TryGetLoop(loopId, out var loop) || loop is null)
+ {
+ return Failure($"Face {faceId.Value} references missing loop {loopId.Value}.");
+ }
+
+ foreach (var coedgeId in loop.CoedgeIds)
+ {
+ if (!builder.Model.TryGetCoedge(coedgeId, out var coedge) || coedge is null)
+ {
+ return Failure($"Loop {loopId.Value} references missing coedge {coedgeId.Value}.");
+ }
+
+ edgeUseCounts[coedge.EdgeId] = edgeUseCounts.GetValueOrDefault(coedge.EdgeId) + 1;
+ }
+ }
+ }
+
+ var invalidIncidence = edgeUseCounts.FirstOrDefault(pair => pair.Value != 2);
+ if (!invalidIncidence.Equals(default(KeyValuePair<EdgeId, int>)))
+ {
+ return Failure(
+ $"Closed shell edge {invalidIncidence.Key.Value} has {invalidIncidence.Value} face-boundary uses; expected exactly 2.");
+ }
+
+ var shellId = builder.AddShell(faceIds);
+ var bodyId = builder.AddBody([shellId]);
+ return KernelResult<BrepShellAssembly>.Success(new BrepShellAssembly(shellId, bodyId));
+ }
+
+ private static KernelResult<BrepShellAssembly> Failure(string message)
+ => KernelResult<BrepShellAssembly>.Failure([
+ new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ message,
+ "Brep.Surgery.ShellAssembler"),
+ ]);
+}
diff --git a/Aetheris.Kernel.Core/Brep/Surgery/BrepSurgeryValidation.cs b/Aetheris.Kernel.Core/Brep/Surgery/BrepSurgeryValidation.cs
new file mode 100644
index 00000000..7395185b
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Surgery/BrepSurgeryValidation.cs
@@ -0,0 +1,38 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Core.Brep.Surgery;
+
+/// <summary>
+/// Reuses the canonical binding/topology validators and adds the finite vertex
+/// geometry invariant required at the Surgery boundary.
+/// </summary>
+internal static class BrepSurgeryValidation
+{
+ public static KernelResult<bool> ValidateBody(BrepBody body, bool requireAllEdgeAndFaceBindings = true)
+ {
+ ArgumentNullException.ThrowIfNull(body);
+ var diagnostics = new List<KernelDiagnostic>();
+ var bindingValidation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings);
+ diagnostics.AddRange(bindingValidation.Diagnostics);
+
+ foreach (var vertex in body.Topology.Vertices)
+ {
+ if (!body.TryGetVertexPoint(vertex.Id, out var point)
+ || !double.IsFinite(point.X)
+ || !double.IsFinite(point.Y)
+ || !double.IsFinite(point.Z))
+ {
+ diagnostics.Add(new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ $"Surgery body vertex {vertex.Id.Value} requires a finite geometry point.",
+ "Brep.Surgery.Validation"));
+ }
+ }
+
+ return diagnostics.Any(diagnostic => diagnostic.Severity == KernelDiagnosticSeverity.Error)
+ ? KernelResult<bool>.Failure(diagnostics)
+ : KernelResult<bool>.Success(true, diagnostics);
+ }
+}
diff --git a/docs/architecture/artifacts/archaeology-m3/README.md b/docs/architecture/artifacts/archaeology-m3/README.md
new file mode 100644
index 00000000..5eb6b1f9
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/README.md
@@ -0,0 +1,12 @@
+# AETHERIS-ARCHAEOLOGY-M3 evidence
+
+M3 introduces an internal `Aetheris.Kernel.Core.Brep.Surgery` boundary without changing `BrepBoolean` signatures, routing, supported families, or intended canonical geometry. The M1 classification remained current after M2; references did not move.
+
+Evidence:
+
+- [surgery-extraction-map.md](surgery-extraction-map.md)
+- [migrated-recipes.md](migrated-recipes.md)
+- [topology-parity.md](topology-parity.md)
+- [orientation-validation.md](orientation-validation.md)
+- [boolean-lessons-progress.md](boolean-lessons-progress.md)
+- [validation-report.md](validation-report.md)
diff --git a/docs/architecture/artifacts/archaeology-m3/boolean-lessons-progress.md b/docs/architecture/artifacts/archaeology-m3/boolean-lessons-progress.md
new file mode 100644
index 00000000..394dbe9f
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/boolean-lessons-progress.md
@@ -0,0 +1,8 @@
+# Boolean lessons progress
+
+The initial textbook documents are now:
+
+- `docs/kernel/brep-surgery.md`: authority, topology vocabulary, result contracts, validation, operation flow, and M3 seams;
+- `docs/kernel/brep-boolean-lessons.md`: intersection versus topology, through/blind holes, counterbore/stepped history, composition, and the generic CIR experiment.
+
+The existing stepped-stack root-cause tests and generic-CIR archaeology were retained. No historical regression was deleted or converted into a claimed generic capability.
diff --git a/docs/architecture/artifacts/archaeology-m3/migrated-recipes.md b/docs/architecture/artifacts/archaeology-m3/migrated-recipes.md
new file mode 100644
index 00000000..282c2684
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/migrated-recipes.md
@@ -0,0 +1,9 @@
+# Migrated recipes
+
+| Family | Old topology path | M3 path | Known assumptions | Result |
+|---|---|---|---|---|
+| orthogonal union | private coedge/loop/face; direct shell; binding validator | Surgery legacy-sense loop + known-loop face; canonical T-junction shell; Surgery validation | occupied cells already determine oriented exterior rectangles | behavior tests and STEP/reimport pass |
+| polygonal/prismatic through cut | private outer/inner loop and face helpers; direct shell | Surgery legacy-sense loop + face; strict Surgery shell; Surgery validation | corresponding outer/inner rings, reversed cavity walls, through span | behavior tests and STEP/reimport pass |
+| cylinder-root rectangular open slot/keyway | private six face loops; direct shell | Surgery legacy-sense loop + face; strict Surgery shell; Surgery validation | retained cylinder arc, floor, radial walls, caps are known | behavior test and STEP export/reimport pass |
+
+`BrepBooleanBoxCylinderHoleBuilder` remains the similar control family on its private topology path. Recognition, Judgment routing, `SafeBooleanComposition`, and family policy did not move.
diff --git a/docs/architecture/artifacts/archaeology-m3/orientation-validation.md b/docs/architecture/artifacts/archaeology-m3/orientation-validation.md
new file mode 100644
index 00000000..ddd6a5ac
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/orientation-validation.md
@@ -0,0 +1,14 @@
+# Orientation and validation
+
+Strict extracted rules:
+
+- `BrepEdgeUse` resolves traversal exactly once from topology endpoints and explicit reversal.
+- a new known loop must close use-to-use and final-to-first;
+- an identical directed edge use cannot repeat; a periodic seam may appear once in each sense;
+- face loop zero is outer and subsequent loops are caller-oriented inner trims;
+- a strict closed shell requires exactly two boundary uses per edge;
+- every realized vertex requires a finite point before a body passes Surgery validation.
+
+Tests cover rectangular loop links, open/repeated rejection without mutation, a reversed circular inner loop, a closed cube shell, open-shell rejection, and non-finite point rejection. Existing through-hole, blind-hole, keyway, polygonal cavity, STEP, and Boolean regressions retain cavity/wall/bottom orientation coverage.
+
+Compatibility findings: historical keyway/prismatic/orthogonal coedge senses are retained behind named recipe-local control seams; orthogonal merged rectangles retain a T-junction assembly seam. These are not generalized into Surgery. Box-cylinder analytic orientation remains family-specific and is the M3 control implementation.
diff --git a/docs/architecture/artifacts/archaeology-m3/surgery-extraction-map.md b/docs/architecture/artifacts/archaeology-m3/surgery-extraction-map.md
new file mode 100644
index 00000000..013ea13b
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/surgery-extraction-map.md
@@ -0,0 +1,10 @@
+# Surgery extraction map
+
+| Old mechanic | New internal primitive | Current recipe callers | Reuse reason |
+|---|---|---|---|
+| repeated edge-use allocation and cyclic coedge links | `BrepLoopBuilder.CreateKnownLoop` + `BrepEdgeUse`; narrowly named legacy-sense adapter | orthogonal union, polygonal through cut, cylinder-root open slot; strict primitive fixtures | identical graph mechanic appeared in four Boolean builders and several feature emitters; caller supplies order/sense |
+| private face-from-one/two-loop helpers | `BrepFaceBuilder.CreateKnownFace` / `CreateKnownFaceFromLoops` | orthogonal union, polygonal through cut, cylinder-root open slot | face ownership and outer/inner ordering are independent of feature recognition |
+| repeated face set -> shell -> body | `BrepShellAssembler.CreateClosedBody` | polygonal through cut, cylinder-root open slot | caller supplies faces; assembler checks existence, duplicates, and two-use incidence |
+| direct binding validation after rebuild | `BrepSurgeryValidation.ValidateBody` | all three migrated builders | reuses canonical validators and adds finite vertex geometry |
+
+No remapper was extracted. The current mixed-through-void builder reuses an already rebuilt body and changes only composition metadata; inventing a general identity/provenance remapper from that single case would exceed evidence. Ring geometry also remains recipe-local because current analytic builders have materially different periodic seam and surface-sense conventions.
diff --git a/docs/architecture/artifacts/archaeology-m3/topology-parity.md b/docs/architecture/artifacts/archaeology-m3/topology-parity.md
new file mode 100644
index 00000000..4a281e40
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/topology-parity.md
@@ -0,0 +1,11 @@
+# Topology parity
+
+The extraction preserves allocation order, edge/coedge flags, geometry creation, binding order, and public dispatch. Canonical fingerprints below are from the post-extraction real facade/builder path; existing pre-M3 behavior/count assertions remain green.
+
+| Case | V | E | F | Curves | Surfaces | Edge/face bindings | Structural/manifold evidence | STEP/reimport | STEP SHA-256 |
+|---|---:|---:|---:|---:|---:|---:|---|---|---|
+| two-cell orthogonal union | 8 | 12 | 6 | 12 | 6 | 12 / 6 | canonical binding/graph validation; strict incidence deferred for merged-rectangle T-junction seam | yes / yes | `09e6b8d838d08748d60fe6f08f0bfcb09282eb983d26d6fc51956cf5e8828de2` |
+| cylinder-root keyway | 8 | 12 | 6 | 12 | 6 | 12 / 6 | binding/graph valid; strict two-use shell incidence passes | yes / yes | `b91443673ab595a0449e91359aa697ae597a03efdb90d7394ac937107e25ae98` |
+| polygonal through cut | 128 | 192 | 66 | 192 | 66 | 192 / 66 | binding/graph valid; strict two-use shell incidence passes | yes / yes | `8554faf173a41abeb15facbeb2bd3cceb4f2ea486d6aa1e1b11c0740b922fe7d` |
+
+No semantic bindings or provenance are fabricated by Surgery. These recipes retain their existing `SafeBooleanComposition` handling above the layer.
diff --git a/docs/architecture/artifacts/archaeology-m3/validation-report.md b/docs/architecture/artifacts/archaeology-m3/validation-report.md
new file mode 100644
index 00000000..57cda27c
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m3/validation-report.md
@@ -0,0 +1,18 @@
+# M3 validation report
+
+| Check | Result |
+|---|---|
+| `dotnet restore Aetheris.slnx` | pass; all projects current |
+| `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1` | pass; 0 warnings, 0 errors |
+| Kernel Core full | 948 passed |
+| BRep Boolean focused | 132 passed |
+| STEP AP242 focused | 273 passed |
+| SurfaceMeshIR + StandardLibrary focused | 15 passed |
+| Firmament full (includes materializers and M2 compatibility) | 1115 passed |
+| Firmament materializer/compatibility focused | 97 passed |
+| FrictionLab Boolean/generic-CIR/stepped focused with `AETHERIS_RUN_LEGACY_TESTS=1` | 61 passed |
+| Surgery primitives + canonical recipe parity | 8 passed |
+| CLI ground-truth path | `dotnet run --project Aetheris.CLI -- --help` passed |
+| `git diff --check` | pass |
+
+An intentionally broad first FrictionLab filter also selected the pre-existing unrelated `TriangleHexPrismProfileParityLabTests.TriangleAndHex_ValidRows_ProduceBodiesAndNo3DBoolean`; it failed at `ParameterInterval` with non-finite `end`, matching the milestone's known failure. The corrected focused Boolean/history selection passed 61/61. M3 did not touch that path.
diff --git a/docs/kernel/brep-boolean-lessons.md b/docs/kernel/brep-boolean-lessons.md
new file mode 100644
index 00000000..35bb4457
--- /dev/null
+++ b/docs/kernel/brep-boolean-lessons.md
@@ -0,0 +1,37 @@
+# BRep Boolean lessons
+
+## Intersection is not topology
+
+`Union`, `Subtract`, and `Intersect` express set intent. An exact result additionally needs bounded trims, outer and inner loops, face supports and senses, a closed shell, stable identity, bindings, and validation. Intersection geometry supplies local evidence; it does not choose those graph elements or explain product intent.
+
+## Through hole and blind hole
+
+The bounded box-cylinder through-hole case works because the recipe already knows one cylindrical wall, entry and exit rings, and the affected planar faces. A blind hole adds state: one exterior opening, a termination circle, a bottom face, and cavity-facing orientation. That is a different known topology recipe, not merely a shorter intersection interval.
+
+## Composition and the stepped-hole cliff
+
+Safe composition records recognized construction history, not generic BRep mutation history. The historical stepped sequence was:
+
+```text
+small through subtract -> medium blind continuation -> large shallow continuation
+```
+
+The first and second operations succeeded, while the third originally crossed a `Holes.Count == 1` family/history gate before topology building. Generalizing the builder alone was insufficient; admission required constraints over the whole coaxial history. Topology reconstruction complexity therefore depends on accumulated operation history, not only the current two bodies. The stepped-stack root-cause regressions remain in place.
+
+## Counterbore and the stepped transition
+
+A counterbore predicts two cylindrical walls, an annular shoulder, ordered radii/depths, and possibly a blind bottom. The shoulder loop roles and orientations are known recipe facts. Treating it as two unrelated generic subtractions loses precisely the state required to author and validate that topology.
+
+## Generic CIR execution
+
+The generic CIR experiment recursively mapped a Boolean expression tree to `BrepBoolean`. It succeeded only for families already supported below and did not remove stepped/conic limitations. A generic syntax tree is a generic traversal mechanism; it does not create a generic topology reconstruction algorithm.
+
+## M3 extraction lesson
+
+Strict loop closure immediately exposed that several canonical legacy builders use historical coedge-sense conventions, while orthogonal merged rectangles can retain T-junction incidence. M3 kept those outputs stable and isolated the seams. This is the practical distinction: a recipe may carry historical representation policy, while Surgery should state and enforce the topology invariant expected of new callers.
+
+The scalable direction remains:
+
+```text
+high-level intent -> recognized bounded recipe -> explicit BRep Surgery -> validation
+```
diff --git a/docs/kernel/brep-surgery.md b/docs/kernel/brep-surgery.md
new file mode 100644
index 00000000..c39c4f17
--- /dev/null
+++ b/docs/kernel/brep-surgery.md
@@ -0,0 +1,34 @@
+# Internal BRep Surgery
+
+`Aetheris.Kernel.Core.Brep.Surgery` is the internal, low-level boundary for realizing topology that a caller already knows. It creates ordered coedge cycles, faces from caller-designated outer/inner loops, closed shell/body ownership, and runs structural/binding/finite-geometry validation. It does not recognize features, select Boolean families, interpret intersection curves, or decide which topology survives.
+
+## Authority boundary
+
+```text
+recognition + Judgment policy + composition/history
+ -> bounded recipe supplies exact topology and orientation
+ -> BRep Surgery realizes and validates it
+ -> canonical BRep/STEP validation
+```
+
+`IntersectionQuery`, `ClosestPointQuery`, `SignedSideQuery`, and `ContactQuery` remain evidence-only. Numerical contact can tell a recipe where supports meet; it cannot decide loop roles, surviving trims, cavity intent, or accumulated-history admissibility.
+
+## Vocabulary and contracts
+
+- An **edge** owns endpoint vertex IDs. A `BrepEdgeUse` supplies the caller's explicit traversal sense.
+- A **loop** is a closed ordered cycle of coedges with deterministic next/previous links. `BrepLoopBuilder` rejects missing edges, repeated identical directed uses, and open endpoint chains.
+- A **face** owns one caller-designated outer loop followed by zero or more caller-designated inner loops. `BrepFaceBuilder` does not discover loop membership or winding. Surface creation and binding remain explicit recipe work because current topology and geometry stores are separate.
+- A **shell/body** is assembled from the exact face set supplied by the caller. `BrepShellAssembler` rejects missing/duplicate faces and any edge incidence other than two face-boundary uses.
+- `BrepSurgeryValidation` reuses `BrepBindingValidator`/`TopologyGraphValidator` and additionally requires a finite point for every vertex.
+
+All operations return `KernelResult<T>` with `KernelDiagnostic` errors. Surgery does not retry with inferred ordering or fallback feature interpretations. No local epsilon is used by these topology-only operations.
+
+## Example flow
+
+For a known rectangular through cut, the recipe creates corresponding lower/upper vertices and edges, specifies outer and reversed inner uses, asks Surgery to create faces and a closed shell, binds the already-known line/plane supports, and validates the body. Whether the requested subtraction belongs to that family was decided before Surgery was called.
+
+## M3 compatibility seams
+
+Some established Boolean builders predate `DirectedEdgeUse` closure semantics, and orthogonal retessellation can retain T-junction incidence across merged coplanar rectangles. M3 preserves their canonical coedge senses and assembly rather than silently changing STEP. The narrowly named `CreateKnownLoopPreservingLegacySense` shares deterministic coedge-cycle mechanics but deliberately omits the newer endpoint-closure check; it is internal and used only at documented compatibility seams. Strict new loop/shell construction uses `CreateKnownLoop` and `BrepShellAssembler`. The remaining seams are evidence for recipe-local orientation work in M4, not reasons to weaken the strict primitives.
+
+Surgery is internal in M3. Public safe/unsafe API decisions are deferred until the contracts have more recipe evidence.