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.csnew file mode 100644index 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.csnew file mode 100644index 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.csindex 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 BrepBooleanCylinderOpenSlotBuildervar 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 BrepBooleanCylinderOpenSlotBuilderbindings.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.csindex 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 BrepBooleanOrthogonalUnionBuilderOrientEdgeUse(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.csindex 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 BrepBooleanPolygonalPrismThroughCutBuildervar 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 BrepBooleanPolygonalPrismThroughCutBuilderbindings.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 BrepBooleanPolygonalPrismThroughCutBuilderreturn 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 BrepBooleanPolygonalPrismThroughCutBuildervar 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.csnew file mode 100644index 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.csnew file mode 100644index 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.csnew file mode 100644index 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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.