Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Route recognized through-holes through direct construction recipes
Yuechen Li90f05ec99c54
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Recipes/BrepSurgeryBoundaryTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Recipes/BrepSurgeryBoundaryTests.csnew file mode 100644index 00000000..30211d5a--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Brep/Recipes/BrepSurgeryBoundaryTests.cs@@ -0,0 +1,24 @@+using System.Reflection;+using System.Runtime.CompilerServices;+using Aetheris.Kernel.Core.Brep.Surgery;++namespace Aetheris.Kernel.Core.Tests.Brep.Recipes;++public sealed class BrepSurgeryBoundaryTests+{+ [Fact]+ public void SurgeryRemainsInternalAndIsNotFriendExposedToForgeHostOrKernelSdk()+ {+ var surgeryType = typeof(BrepSurgeryValidation);+ Assert.False(surgeryType.IsPublic);++ var friends = surgeryType.Assembly+ .GetCustomAttributes<InternalsVisibleToAttribute>()+ .Select(attribute => attribute.AssemblyName.Split(',')[0])+ .ToHashSet(StringComparer.Ordinal);++ Assert.DoesNotContain("Aetheris.Forge.Host", friends);+ Assert.DoesNotContain("Aetheris.Forge.KernelSdk", friends);+ Assert.DoesNotContain("Aetheris.Forge.KernelSDK", friends);+ }+}diff --git a/Aetheris.Kernel.Core.Tests/Brep/Recipes/RecognizedConstructionRecipeTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Recipes/RecognizedConstructionRecipeTests.csnew file mode 100644index 00000000..643d1e09--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Brep/Recipes/RecognizedConstructionRecipeTests.cs@@ -0,0 +1,318 @@+using System.Security.Cryptography;+using System.Text;+using System.Diagnostics;+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Brep.Recipes;+using Aetheris.Kernel.Core.Brep.Surgery;+using Aetheris.Kernel.Core.Diagnostics;+using Aetheris.Kernel.Core.Geometry;+using Aetheris.Kernel.Core.Geometry.Curves;+using Aetheris.Kernel.Core.Geometry.Surfaces;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Core.Step242;+using Aetheris.Kernel.Core.Topology;+using Aetheris.Kernel.StandardLibrary;+using Xunit.Abstractions;++namespace Aetheris.Kernel.Core.Tests.Brep.Recipes;++public sealed class RecognizedConstructionRecipeTests+{+ private readonly ITestOutputHelper _output;++ public RecognizedConstructionRecipeTests(ITestOutputHelper output) => _output = output;++ [Fact]+ public void ThroughHole_DirectRecipe_LegacyAndFacadeAreTopologyAndStepIdentical()+ {+ var root = BrepBooleanBoxRecognition.CreateBoxFromExtents(+ new AxisAlignedBoxExtents(-20d, 20d, -15d, 15d, 0d, 12d)).Value;+ var tool = TransformBody(+ BrepPrimitives.CreateCylinder(4d, 20d).Value,+ Transform3D.CreateTranslation(new Vector3D(3d, -2d, 6d)));+ var facade = BrepBoolean.Subtract(root, tool);+ Assert.True(facade.IsSuccess, Join(facade.Diagnostics));++ var history = Assert.IsType<SafeBooleanComposition>(facade.Value.SafeBooleanComposition);+ var hole = Assert.Single(history.Holes);+ var request = new ThroughHoleRecipeRequest(history.RootDescriptor, hole, history, ToleranceContext.Default);++ var recipe = ThroughHoleConstructionRecipe.Execute(request);+ var legacy = BrepBooleanBoxCylinderHoleBuilder.BuildRecognizedThroughHoleLegacy(history, ToleranceContext.Default);++ Assert.True(recipe.IsSuccess, Join(recipe.Diagnostics));+ Assert.True(legacy.IsSuccess, Join(legacy.Diagnostics));+ AssertEquivalent(legacy.Value, recipe.Value);+ AssertEquivalent(recipe.Value, facade.Value);+ Assert.Same(history, recipe.Value.SafeBooleanComposition);+ Assert.Equal(SupportedBooleanHoleSpanKind.Through, hole.SpanKind);+ Assert.Equal(7, recipe.Value.Topology.Faces.Count());+ Assert.Equal(9, recipe.Value.Topology.Loops.Count());+ Assert.Equal(30, recipe.Value.Topology.Coedges.Count());+ Assert.Single(recipe.Value.Geometry.Surfaces, entry => entry.Value.Kind == SurfaceGeometryKind.Cylinder);+ AssertRoundTrips(recipe.Value);+ }++ [Fact]+ public void ThroughHole_DirectRecipeRejectsNonThroughHistoryWithTypedDiagnostic()+ {+ var result = ThroughHoleConstructionRecipe.Execute(null);++ Assert.False(result.IsSuccess);+ var diagnostic = Assert.Single(result.Diagnostics);+ Assert.Equal(KernelDiagnosticCode.ValidationFailed, diagnostic.Code);+ Assert.Equal("Brep.Recipes.ThroughHole", diagnostic.Source);+ Assert.Contains("recognized intent", diagnostic.Message, StringComparison.Ordinal);+ }++ [Fact]+ public void ThroughHole_SemanticRequestBuilder_MatchesFacadeWithoutTemporaryOperands()+ {+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ 40d,+ 30d,+ 12d,+ new Vector3D(2d, 3d, 6d),+ 4d,+ 20d,+ new Vector3D(5d, 1d, 6d),+ "semantic-hole");+ Assert.True(request.IsSuccess, Join(request.Diagnostics));++ var direct = ThroughHoleConstructionRecipe.Execute(request.Value);+ var root = TransformBody(+ BrepPrimitives.CreateBox(40d, 30d, 12d).Value,+ Transform3D.CreateTranslation(new Vector3D(2d, 3d, 6d)));+ var tool = TransformBody(+ BrepPrimitives.CreateCylinder(4d, 20d).Value,+ Transform3D.CreateTranslation(new Vector3D(5d, 1d, 6d)));+ var facade = BrepBoolean.Subtract(root, tool);++ Assert.True(direct.IsSuccess, Join(direct.Diagnostics));+ Assert.True(facade.IsSuccess, Join(facade.Diagnostics));+ AssertEquivalent(facade.Value, direct.Value);+ Assert.Equal("semantic-hole", Assert.Single(direct.Value.SafeBooleanComposition!.Holes).FeatureId);+ }++ [Fact]+ public void ThroughHole_RecipeLayerHasNoMeaningfulRuntimeRegression()+ {+ var root = BrepPrimitives.CreateBox(40d, 30d, 12d).Value;+ var tool = BrepPrimitives.CreateCylinder(4d, 20d).Value;+ var facade = BrepBoolean.Subtract(root, tool).Value;+ var history = facade.SafeBooleanComposition!;+ var request = new ThroughHoleRecipeRequest(+ history.RootDescriptor,+ Assert.Single(history.Holes),+ history,+ ToleranceContext.Default);++ const int iterations = 100;+ _ = ThroughHoleConstructionRecipe.Execute(request);+ _ = BrepBooleanBoxCylinderHoleBuilder.BuildRecognizedThroughHoleLegacy(history, ToleranceContext.Default);++ var legacy = Stopwatch.StartNew();+ for (var index = 0; index < iterations; index++)+ {+ Assert.True(BrepBooleanBoxCylinderHoleBuilder.BuildRecognizedThroughHoleLegacy(history, ToleranceContext.Default).IsSuccess);+ }+ legacy.Stop();++ var recipe = Stopwatch.StartNew();+ for (var index = 0; index < iterations; index++)+ {+ Assert.True(ThroughHoleConstructionRecipe.Execute(request).IsSuccess);+ }+ recipe.Stop();++ _output.WriteLine($"legacy={legacy.Elapsed.TotalMilliseconds:F3}ms recipe={recipe.Elapsed.TotalMilliseconds:F3}ms iterations={iterations}");+ Assert.True(recipe.Elapsed <= legacy.Elapsed * 3 + TimeSpan.FromMilliseconds(10));+ }++ [Fact]+ public void StandardLibrary_ThroughHole_DirectRecipeMatchesCompatibilityFacade()+ {+ var direct = StandardLibraryReusableParts.CreateCubeWithCylindricalHole();+ var facade = BrepBoolean.Subtract(+ BrepPrimitives.CreateBox(20d, 20d, 20d).Value,+ BrepPrimitives.CreateCylinder(3d, 24d).Value);++ Assert.True(direct.IsSuccess, Join(direct.Diagnostics));+ Assert.True(facade.IsSuccess, Join(facade.Diagnostics));+ AssertEquivalent(facade.Value, direct.Value);+ Assert.Equal(StandardLibraryReusableParts.CubeWithCylindricalHolePartName,+ Assert.Single(direct.Value.SafeBooleanComposition!.Holes).FeatureId);+ AssertRoundTrips(direct.Value);+ }++ [Theory]+ [InlineData("firmament", 80d, 50d, 25d, 4d, 25d)]+ [InlineData("cir", 20d, 20d, 10d, 3d, 20d)]+ [InlineData("standard-library", 20d, 20d, 20d, 3d, 24d)]+ public void KnownCaller_DirectRecipeAvoidsFacadeRecognitionOverhead(+ string caller,+ double width,+ double depth,+ double height,+ double radius,+ double toolHeight)+ {+ const int iterations = 30;+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ width, depth, height, Vector3D.Zero, radius, toolHeight, Vector3D.Zero, caller).Value;++ _ = ThroughHoleConstructionRecipe.Execute(request);+ _ = BrepBoolean.Subtract(BrepPrimitives.CreateBox(width, depth, height).Value, BrepPrimitives.CreateCylinder(radius, toolHeight).Value);++ var facade = Stopwatch.StartNew();+ for (var index = 0; index < iterations; index++)+ {+ Assert.True(BrepBoolean.Subtract(+ BrepPrimitives.CreateBox(width, depth, height).Value,+ BrepPrimitives.CreateCylinder(radius, toolHeight).Value).IsSuccess);+ }+ facade.Stop();++ var direct = Stopwatch.StartNew();+ for (var index = 0; index < iterations; index++)+ {+ Assert.True(ThroughHoleConstructionRecipe.Execute(request).IsSuccess);+ }+ direct.Stop();++ _output.WriteLine($"caller={caller} facade={facade.Elapsed.TotalMilliseconds:F3}ms direct-recipe={direct.Elapsed.TotalMilliseconds:F3}ms iterations={iterations}");+ Assert.True(direct.Elapsed <= facade.Elapsed * 3 + TimeSpan.FromMilliseconds(10));+ }++ [Fact]+ public void PolygonalThroughCut_DirectRecipe_LegacyAndFacadeAreTopologyAndStepIdentical()+ {+ var root = StandardLibraryPrimitives.CreateRoundedCornerBox(24d, 18d, 20d, 4d).Value;+ var tool = StandardLibraryPrimitives.CreateSlotCut(10d, 4d, 24d, 2d).Value;+ Assert.True(BrepBooleanSafeComposition.TryRecognize(root, ToleranceContext.Default, out var rootHistory, out _));+ Assert.True(BrepBooleanPrismaticToolRecognition.TryRecognize(tool, ToleranceContext.Default, out var recognizedTool, out _));+ var outer = Assert.IsAssignableFrom<IReadOnlyList<(double X, double Y)>>(rootHistory.RootDescriptor.PolygonFootprint);++ var request = new PolygonalThroughCutRecipeRequest(+ outer,+ rootHistory.RootDescriptor.Box,+ recognizedTool.Footprint,+ ToleranceContext.Default,+ rootHistory);+ var recipe = PolygonalThroughCutRecipe.Execute(request);+ var legacy = BrepBooleanPolygonalPrismThroughCutBuilder.BuildLegacy(+ outer,+ rootHistory.RootDescriptor.Box,+ recognizedTool.Footprint);+ var facade = BrepBoolean.Subtract(root, tool);++ Assert.True(recipe.IsSuccess, Join(recipe.Diagnostics));+ Assert.True(legacy.IsSuccess, Join(legacy.Diagnostics));+ Assert.True(facade.IsSuccess, Join(facade.Diagnostics));+ AssertEquivalent(legacy.Value, recipe.Value);+ AssertEquivalent(recipe.Value, facade.Value);+ Assert.Equal(66, recipe.Value.Topology.Faces.Count());+ Assert.Equal(66, recipe.Value.Geometry.Surfaces.Count());+ AssertRoundTrips(recipe.Value);+ }++ [Fact]+ public void PolygonalThroughCut_DirectRecipeRejectsIncompleteFootprintWithTypedDiagnostic()+ {+ var request = new PolygonalThroughCutRecipeRequest(+ [(0d, 0d), (1d, 0d)],+ new AxisAlignedBoxExtents(0d, 2d, 0d, 2d, 0d, 2d),+ [(0.2d, 0.2d), (0.8d, 0.2d), (0.5d, 0.8d)],+ ToleranceContext.Default);++ var result = PolygonalThroughCutRecipe.Execute(request);++ Assert.False(result.IsSuccess);+ var diagnostic = Assert.Single(result.Diagnostics);+ Assert.Equal(KernelDiagnosticCode.ValidationFailed, diagnostic.Code);+ Assert.Equal("Brep.Recipes.PolygonalThroughCut", diagnostic.Source);+ }++ private static void AssertEquivalent(BrepBody expected, BrepBody actual)+ {+ Assert.Equal(expected.Topology.Vertices.Count(), actual.Topology.Vertices.Count());+ Assert.Equal(expected.Topology.Edges.Count(), actual.Topology.Edges.Count());+ Assert.Equal(expected.Topology.Faces.Count(), actual.Topology.Faces.Count());+ Assert.Equal(expected.Topology.Loops.Count(), actual.Topology.Loops.Count());+ Assert.Equal(expected.Topology.Coedges.Count(), actual.Topology.Coedges.Count());+ Assert.Equal(expected.Geometry.Curves.Count(), actual.Geometry.Curves.Count());+ Assert.Equal(expected.Geometry.Surfaces.Count(), actual.Geometry.Surfaces.Count());+ Assert.Equal(expected.Bindings.EdgeBindings.Count(), actual.Bindings.EdgeBindings.Count());+ Assert.Equal(expected.Bindings.FaceBindings.Count(), actual.Bindings.FaceBindings.Count());+ Assert.Equal(StepHash(expected), StepHash(actual));+ Assert.True(BrepSurgeryValidation.ValidateBody(actual, requireAllEdgeAndFaceBindings: true).IsSuccess);+ }++ private static void AssertRoundTrips(BrepBody body)+ {+ var export = Step242Exporter.ExportBody(body);+ Assert.True(export.IsSuccess, Join(export.Diagnostics));+ var import = Step242Importer.ImportBody(export.Value);+ Assert.True(import.IsSuccess, Join(import.Diagnostics));+ Assert.True(BrepBindingValidator.Validate(import.Value, requireAllEdgeAndFaceBindings: true).IsSuccess);+ }++ private static string StepHash(BrepBody body)+ {+ var export = Step242Exporter.ExportBody(body);+ Assert.True(export.IsSuccess, Join(export.Diagnostics));+ return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(export.Value))).ToLowerInvariant();+ }++ private static string Join(IEnumerable<KernelDiagnostic> diagnostics)+ => string.Join(Environment.NewLine, diagnostics.Select(diagnostic => diagnostic.Message));++ private static BrepBody TransformBody(BrepBody body, Transform3D transform)+ {+ var geometry = new BrepGeometryStore();+ foreach (var curveEntry in body.Geometry.Curves)+ {+ geometry.AddCurve(curveEntry.Key, curveEntry.Value.Kind switch+ {+ CurveGeometryKind.Line3 => CurveGeometry.FromLine(new Line3Curve(+ transform.Apply(curveEntry.Value.Line3!.Value.Origin),+ transform.Apply(curveEntry.Value.Line3.Value.Direction))),+ CurveGeometryKind.Circle3 => CurveGeometry.FromCircle(new Circle3Curve(+ transform.Apply(curveEntry.Value.Circle3!.Value.Center),+ transform.Apply(curveEntry.Value.Circle3.Value.Normal),+ curveEntry.Value.Circle3.Value.Radius,+ transform.Apply(curveEntry.Value.Circle3.Value.XAxis))),+ _ => curveEntry.Value,+ });+ }++ foreach (var surfaceEntry in body.Geometry.Surfaces)+ {+ geometry.AddSurface(surfaceEntry.Key, surfaceEntry.Value.Kind switch+ {+ SurfaceGeometryKind.Plane => SurfaceGeometry.FromPlane(new PlaneSurface(+ transform.Apply(surfaceEntry.Value.Plane!.Value.Origin),+ transform.Apply(surfaceEntry.Value.Plane.Value.Normal),+ transform.Apply(surfaceEntry.Value.Plane.Value.UAxis))),+ SurfaceGeometryKind.Cylinder => SurfaceGeometry.FromCylinder(new CylinderSurface(+ transform.Apply(surfaceEntry.Value.Cylinder!.Value.Origin),+ transform.Apply(surfaceEntry.Value.Cylinder.Value.Axis),+ surfaceEntry.Value.Cylinder.Value.Radius,+ transform.Apply(surfaceEntry.Value.Cylinder.Value.XAxis))),+ _ => surfaceEntry.Value,+ });+ }++ var points = new Dictionary<VertexId, Point3D>();+ foreach (var vertex in body.Topology.Vertices)+ {+ if (body.TryGetVertexPoint(vertex.Id, out var point))+ {+ points[vertex.Id] = transform.Apply(point);+ }+ }+ return new BrepBody(body.Topology, geometry, body.Bindings, points, body.SafeBooleanComposition, body.ShellRepresentation);+ }+}diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.csindex 759db6ea..d31925c2 100644--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs@@ -4,6 +4,7 @@ using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Numerics;using Aetheris.Kernel.Core.Results;using Aetheris.Kernel.Core.Topology;+using Aetheris.Kernel.Core.Brep.Recipes;namespace Aetheris.Kernel.Core.Brep.Boolean;@@ -1063,7 +1064,12 @@ public static class BrepBooleanKernelResult<BrepBody> rebuiltPrismSubtract = leftComposition.RootDescriptor.Kind switch{SafeBooleanRootKind.PolygonalExtrusion when leftComposition.RootDescriptor.PolygonFootprint is { Count: > 2 } polygonFootprint- => BrepBooleanPolygonalPrismThroughCutBuilder.Build(polygonFootprint, leftComposition.RootDescriptor.Box, prismaticTool.Footprint),+ => PolygonalThroughCutRecipe.Execute(new(+ polygonFootprint,+ leftComposition.RootDescriptor.Box,+ prismaticTool.Footprint,+ request.Tolerance ?? ToleranceContext.Default,+ classification.SafeCompositionResult)),_ => BrepBooleanBoxPrismThroughCutBuilder.Build(leftComposition.RootDescriptor.Box, prismaticTool.Footprint, request.Tolerance ?? ToleranceContext.Default),};if (!rebuiltPrismSubtract.IsSuccess)diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.csindex 367801a4..5f20834b 100644--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs@@ -6,6 +6,8 @@ using Aetheris.Kernel.Core.Numerics;using Aetheris.Kernel.Core.Results;using Aetheris.Kernel.Core.Topology;using Aetheris.Kernel.Core.Brep.Features;+using Aetheris.Kernel.Core.Brep.Recipes;+using Aetheris.Kernel.Core.Brep.Surgery;namespace Aetheris.Kernel.Core.Brep.Boolean;@@ -36,6 +38,18 @@ public static class BrepBooleanBoxCylinderHoleBuilderreturn CreateBoundedCylinderRootHoleChainBody(composition, tolerance);}+ if (composition.RootDescriptor.Kind == SafeBooleanRootKind.Box+ && composition.Holes.Count == 1+ && composition.Holes[0].SpanKind == SupportedBooleanHoleSpanKind.Through+ && composition.Holes[0].Surface.Kind == AnalyticSurfaceKind.Cylinder)+ {+ return ThroughHoleConstructionRecipe.Execute(new(+ composition.RootDescriptor,+ composition.Holes[0],+ composition,+ tolerance));+ }+if (composition.Holes.Count == 1&& composition.Holes[0].Surface.Kind == AnalyticSurfaceKind.Sphere&& composition.Holes[0].Surface.Sphere is RecognizedSphere sphere)@@ -116,6 +130,21 @@ public static class BrepBooleanBoxCylinderHoleBuilderreturn CreateComposedThroughHoleBody(composition, tolerance);}+ /// <summary>+ /// Recipe realization and rollback seam for the already-recognized canonical+ /// box/cylinder through-hole. This method performs no operand recognition.+ /// </summary>+ internal static KernelResult<BrepBody> BuildRecognizedThroughHoleTopology(+ SafeBooleanComposition composition,+ ToleranceContext tolerance)+ => CreateComposedThroughHoleBody(composition, tolerance);++ /// <summary>Pre-M4 callable path retained for byte/topology parity tests.</summary>+ internal static KernelResult<BrepBody> BuildRecognizedThroughHoleLegacy(+ SafeBooleanComposition composition,+ ToleranceContext tolerance)+ => CreateComposedThroughHoleBody(composition, tolerance);+private static bool IsCoaxialHolePair(in SupportedBooleanHole first, in SupportedBooleanHole second, ToleranceContext tolerance){var deltaX = first.CenterX - second.CenterX;@@ -745,33 +774,36 @@ public static class BrepBooleanBoxCylinderHoleBuilderholeTopology.Add(new HoleTopology(hole, topHoleVertex, bottomHoleVertex, seamTopVertex, seamBottomVertex, topCircle, bottomCircle, seam));}- var bottomOuterLoop = AddLoop(builder, [Forward(e1), Forward(e2), Forward(e3), Forward(e4)]);- var topOuterLoop = AddLoop(builder, [Forward(e5), Forward(e6), Forward(e7), Forward(e8)]);+ var bottomOuterLoop = AddSurgeryLoop(builder, [Forward(e1), Forward(e2), Forward(e3), Forward(e4)]);+ var topOuterLoop = AddSurgeryLoop(builder, [Forward(e5), Forward(e6), Forward(e7), Forward(e8)]);var bottomLoops = new List<LoopId>(holes.Count + 1) { bottomOuterLoop };var topLoops = new List<LoopId>(holes.Count + 1) { topOuterLoop };foreach (var hole in holeTopology){if (hole.Hole.SpanKind == SupportedBooleanHoleSpanKind.Through){- topLoops.Add(AddLoop(builder, [Forward(hole.TopCircle)]));- bottomLoops.Add(AddLoop(builder, [Reversed(hole.BottomCircle)]));+ topLoops.Add(AddSurgeryLoop(builder, [Forward(hole.TopCircle)]));+ bottomLoops.Add(AddSurgeryLoop(builder, [Reversed(hole.BottomCircle)]));}else if (hole.Hole.SpanKind == SupportedBooleanHoleSpanKind.BlindFromTop){- topLoops.Add(AddLoop(builder, [Forward(hole.TopCircle)]));+ topLoops.Add(AddSurgeryLoop(builder, [Forward(hole.TopCircle)]));}else{- bottomLoops.Add(AddLoop(builder, [Reversed(hole.BottomCircle)]));+ bottomLoops.Add(AddSurgeryLoop(builder, [Reversed(hole.BottomCircle)]));}}- var bottomFace = builder.AddFace(bottomLoops);- var topFace = builder.AddFace(topLoops);- var xMinFace = builder.AddFace([AddLoop(builder, [Forward(e1), Forward(e10), Reversed(e5), Reversed(e9)])]);- var xMaxFace = builder.AddFace([AddLoop(builder, [Forward(e2), Forward(e11), Reversed(e6), Reversed(e10)])]);- var yMaxFace = builder.AddFace([AddLoop(builder, [Forward(e3), Forward(e12), Reversed(e7), Reversed(e11)])]);- var yMinFace = builder.AddFace([AddLoop(builder, [Forward(e4), Forward(e9), Reversed(e8), Reversed(e12)])]);+ // Recognition has already identified the support faces and loop roles.+ // Surgery realizes those exact ownership decisions; numerical+ // intersection is not topology authority here.+ var bottomFace = AddKnownFace(builder, bottomLoops);+ var topFace = AddKnownFace(builder, topLoops);+ var xMinFace = AddKnownFace(builder, [AddSurgeryLoop(builder, [Forward(e1), Forward(e10), Reversed(e5), Reversed(e9)])]);+ var xMaxFace = AddKnownFace(builder, [AddSurgeryLoop(builder, [Forward(e2), Forward(e11), Reversed(e6), Reversed(e10)])]);+ var yMaxFace = AddKnownFace(builder, [AddSurgeryLoop(builder, [Forward(e3), Forward(e12), Reversed(e7), Reversed(e11)])]);+ var yMinFace = AddKnownFace(builder, [AddSurgeryLoop(builder, [Forward(e4), Forward(e9), Reversed(e8), Reversed(e12)])]);var holeFaces = new List<FaceId>(holes.Count);foreach (var hole in holeTopology)@@ -780,8 +812,8 @@ public static class BrepBooleanBoxCylinderHoleBuilder// the bottom circle, back up the reversed seam, then the top// circle. The previous top/bottom ordering was incidence-manifold// but disconnected in declared coedge traversal.- holeFaces.Add(builder.AddFace([- AddLoop(builder, [Forward(hole.Seam), Forward(hole.BottomCircle), Reversed(hole.Seam), Reversed(hole.TopCircle)])+ holeFaces.Add(AddKnownFace(builder, [+ AddSurgeryLoop(builder, [Forward(hole.Seam), Forward(hole.BottomCircle), Reversed(hole.Seam), Reversed(hole.TopCircle)])]));}@@ -789,7 +821,7 @@ public static class BrepBooleanBoxCylinderHoleBuilderforeach (var hole in holeTopology.Where(h => h.Hole.IsBlind)){var terminationEdge = hole.Hole.SpanKind == SupportedBooleanHoleSpanKind.BlindFromTop ? hole.BottomCircle : hole.TopCircle;- blindBottomFaces.Add(builder.AddFace([AddLoop(builder, [Forward(terminationEdge)])]));+ blindBottomFaces.Add(AddKnownFace(builder, [AddSurgeryLoop(builder, [Forward(terminationEdge)])]));}var shellFaces = new List<FaceId>(6 + holeFaces.Count)@@ -804,8 +836,11 @@ public static class BrepBooleanBoxCylinderHoleBuildershellFaces.AddRange(holeFaces);shellFaces.AddRange(blindBottomFaces);- var shell = builder.AddShell(shellFaces);- builder.AddBody([shell]);+ var assembly = BrepShellAssembler.CreateClosedBody(builder, shellFaces);+ if (!assembly.IsSuccess)+ {+ return KernelResult<BrepBody>.Failure(assembly.Diagnostics);+ }var geometry = new BrepGeometryStore();var width = box.MaxX - box.MinX;@@ -920,7 +955,7 @@ public static class BrepBooleanBoxCylinderHoleBuilder}var body = new BrepBody(builder.Model, geometry, bindings, vertexPoints, 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);@@ -1622,6 +1657,18 @@ public static class BrepBooleanBoxCylinderHoleBuilderreturn loopId;}+ private static LoopId AddSurgeryLoop(TopologyBuilder builder, IReadOnlyList<EdgeUse> edgeUses)+ {+ // Periodic analytic faces use the seam twice; preserve the established+ // coedge senses at this explicitly named compatibility seam.+ return BrepLoopBuilder.CreateKnownLoopPreservingLegacySense(+ builder,+ edgeUses.Select(use => new BrepEdgeUse(use.EdgeId, use.IsReversed)).ToArray()).Value;+ }++ private static FaceId AddKnownFace(TopologyBuilder builder, IReadOnlyList<LoopId> loops)+ => BrepFaceBuilder.CreateKnownFaceFromLoops(builder, loops[0], loops.Skip(1).ToArray()).Value;+private static bool SupportsBoundedBlindContinuationOnRecognizedOrthogonalAdditiveRoot(SafeBooleanComposition composition,ToleranceContext tolerance)diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutAdapter.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutAdapter.csnew file mode 100644index 00000000..40a4a622--- /dev/null+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutAdapter.cs@@ -0,0 +1,29 @@+using Aetheris.Kernel.Core.Brep.Recipes;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Core.Results;++namespace Aetheris.Kernel.Core.Brep.Boolean;++/// <summary>+/// Compatibility/rollback adapter retained while callers still enter through+/// Boolean vocabulary. Topology ownership lives in Brep.Recipes.+/// </summary>+internal static class BrepBooleanPolygonalPrismThroughCutBuilder+{+ public static KernelResult<BrepBody> Build(+ IReadOnlyList<(double X, double Y)> outerFootprint,+ AxisAlignedBoxExtents rootBounds,+ IReadOnlyList<(double X, double Y)> innerFootprint)+ => PolygonalThroughCutRecipe.Execute(new(+ outerFootprint,+ rootBounds,+ innerFootprint,+ ToleranceContext.Default));++ internal static KernelResult<BrepBody> BuildLegacy(+ IReadOnlyList<(double X, double Y)> outerFootprint,+ AxisAlignedBoxExtents rootBounds,+ IReadOnlyList<(double X, double Y)> innerFootprint)+ => PolygonalThroughCutTopologyRealizer.Build(outerFootprint, rootBounds, innerFootprint);+}diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanPolygonalPrismThroughCutBuilder.csindex cee10f05..6ff92532 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.Boolean;using Aetheris.Kernel.Core.Brep.Surgery;using Aetheris.Kernel.Core.Geometry;using Aetheris.Kernel.Core.Geometry.Curves;@@ -7,9 +8,13 @@ using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Results;using Aetheris.Kernel.Core.Topology;-namespace Aetheris.Kernel.Core.Brep.Boolean;+namespace Aetheris.Kernel.Core.Brep.Recipes;-internal static class BrepBooleanPolygonalPrismThroughCutBuilder+/// <summary>+/// Recipe-owned topology realization. This receives ordered, recognized+/// footprints and has no access to arbitrary Boolean operands or recognition.+/// </summary>+internal static class PolygonalThroughCutTopologyRealizer{public static KernelResult<BrepBody> Build(IReadOnlyList<(double X, double Y)> outerFootprint,@@ -23,7 +28,7 @@ internal static class BrepBooleanPolygonalPrismThroughCutBuilderKernelDiagnosticCode.ValidationFailed,KernelDiagnosticSeverity.Error,"Bounded prism-family subtract requires valid outer/inner footprints with at least three vertices.",- "BrepBooleanPolygonalPrismThroughCutBuilder.Build")+ "Brep.Recipes.PolygonalThroughCut.Realize")]);}diff --git a/Aetheris.Kernel.Core/Brep/Recipes/PolygonalThroughCutRecipe.cs b/Aetheris.Kernel.Core/Brep/Recipes/PolygonalThroughCutRecipe.csnew file mode 100644index 00000000..bc0902f2--- /dev/null+++ b/Aetheris.Kernel.Core/Brep/Recipes/PolygonalThroughCutRecipe.cs@@ -0,0 +1,56 @@+using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Diagnostics;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Core.Results;++namespace Aetheris.Kernel.Core.Brep.Recipes;++/// <summary>+/// Recognized polygonal-prism subtraction intent. Correspondence and winding+/// of both footprints are policy facts supplied above the recipe, not inferred+/// here from arbitrary BReps.+/// </summary>+internal sealed record PolygonalThroughCutRecipeRequest(+ IReadOnlyList<(double X, double Y)> OuterFootprint,+ AxisAlignedBoxExtents RootBounds,+ IReadOnlyList<(double X, double Y)> InnerFootprint,+ ToleranceContext Tolerance,+ SafeBooleanComposition? ConstructionHistory = null);++/// <summary>+/// Contrasts with the circular through-hole: each polygon segment produces a+/// separately ordered planar cavity wall, while the support faces receive+/// multi-edge inner loops. The same feature-agnostic Surgery loop, face, shell,+/// and validation mechanics realize this different expected topology.+/// </summary>+internal static class PolygonalThroughCutRecipe+{+ public static KernelResult<BrepBody> Execute(PolygonalThroughCutRecipeRequest? request)+ {+ if (request is null)+ {+ return Failure("Polygonal through-cut recipe requires recognized intent.");+ }++ if (request.OuterFootprint.Count < 3 || request.InnerFootprint.Count < 3)+ {+ return Failure("Polygonal through-cut recipe requires outer and inner footprints with at least three ordered vertices.");+ }++ _ = request.Tolerance; // Recognition consumed tolerance; realization is topology-exact.+ return PolygonalThroughCutTopologyRealizer.Build(+ request.OuterFootprint,+ request.RootBounds,+ request.InnerFootprint);+ }++ private static KernelResult<BrepBody> Failure(string message)+ => KernelResult<BrepBody>.Failure([+ new KernelDiagnostic(+ KernelDiagnosticCode.ValidationFailed,+ KernelDiagnosticSeverity.Error,+ message,+ "Brep.Recipes.PolygonalThroughCut"),+ ]);+}diff --git a/Aetheris.Kernel.Core/Brep/Recipes/ThroughHoleConstructionRecipe.cs b/Aetheris.Kernel.Core/Brep/Recipes/ThroughHoleConstructionRecipe.csnew file mode 100644index 00000000..cbd8db32--- /dev/null+++ b/Aetheris.Kernel.Core/Brep/Recipes/ThroughHoleConstructionRecipe.cs@@ -0,0 +1,155 @@+using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Diagnostics;+using Aetheris.Kernel.Core.Geometry;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Core.Results;++namespace Aetheris.Kernel.Core.Brep.Recipes;++/// <summary>+/// Recognized intent for the canonical box/cylinder through-hole recipe.+/// Recognition and composition policy have already proved that the root is a+/// box and that the single cylindrical void spans two distinct planar supports.+/// </summary>+internal sealed record ThroughHoleRecipeRequest(+ SafeBooleanRootDescriptor Root,+ SupportedBooleanHole Hole,+ SafeBooleanComposition ConstructionHistory,+ ToleranceContext Tolerance);++/// <summary>+/// Converts caller-owned, recognized box/cylinder semantics into the narrow+/// through-hole recipe contract. This performs bounded composition policy; it+/// does not construct or recognize temporary operand bodies.+/// </summary>+internal static class ThroughHoleRecipeRequestBuilder+{+ public static KernelResult<ThroughHoleRecipeRequest> FromBoxAndZCylinder(+ double hostSizeX,+ double hostSizeY,+ double hostSizeZ,+ Vector3D hostTranslation,+ double toolRadius,+ double toolHeight,+ Vector3D toolTranslation,+ string? featureId = null,+ ToleranceContext? tolerance = null)+ {+ var resolvedTolerance = tolerance ?? ToleranceContext.Default;+ if (!AllPositiveFinite(hostSizeX, hostSizeY, hostSizeZ, toolRadius, toolHeight)+ || !AllFinite(hostTranslation.X, hostTranslation.Y, hostTranslation.Z,+ toolTranslation.X, toolTranslation.Y, toolTranslation.Z))+ {+ return Failure("Through-hole semantic dimensions and translations must be finite, with positive dimensions.");+ }++ var rootBox = new AxisAlignedBoxExtents(+ hostTranslation.X - (hostSizeX * 0.5d),+ hostTranslation.X + (hostSizeX * 0.5d),+ hostTranslation.Y - (hostSizeY * 0.5d),+ hostTranslation.Y + (hostSizeY * 0.5d),+ hostTranslation.Z - (hostSizeZ * 0.5d),+ hostTranslation.Z + (hostSizeZ * 0.5d));+ var root = SafeBooleanRootDescriptor.FromBox(rootBox);+ var history = new SafeBooleanComposition(rootBox, [], root);+ var cylinder = new RecognizedCylinder(+ new Point3D(toolTranslation.X, toolTranslation.Y, toolTranslation.Z),+ Direction3D.Create(new Vector3D(0d, 0d, 1d)),+ toolRadius,+ -toolHeight * 0.5d,+ toolHeight * 0.5d);+ var surface = new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cylinder);++ if (!BrepBooleanSafeCompositionGraphValidator.TryValidateNextSubtract(+ history,+ surface,+ resolvedTolerance,+ out var updatedHistory,+ out var diagnostic,+ featureId))+ {+ return KernelResult<ThroughHoleRecipeRequest>.Failure([+ diagnostic?.ToKernelDiagnostic()+ ?? new KernelDiagnostic(+ KernelDiagnosticCode.ValidationFailed,+ KernelDiagnosticSeverity.Error,+ "Through-hole semantic request was rejected by bounded composition policy.",+ "Brep.Recipes.ThroughHole.RequestBuilder"),+ ]);+ }++ var hole = updatedHistory.Holes.Single();+ if (hole.SpanKind != SupportedBooleanHoleSpanKind.Through)+ {+ return Failure("Through-hole semantic request must span both host boundary planes.");+ }++ return KernelResult<ThroughHoleRecipeRequest>.Success(+ new ThroughHoleRecipeRequest(root, hole, updatedHistory, resolvedTolerance));+ }++ private static bool AllPositiveFinite(params double[] values)+ => values.All(value => double.IsFinite(value) && value > 0d);++ private static bool AllFinite(params double[] values)+ => values.All(double.IsFinite);++ private static KernelResult<ThroughHoleRecipeRequest> Failure(string message)+ => KernelResult<ThroughHoleRecipeRequest>.Failure([+ new KernelDiagnostic(+ KernelDiagnosticCode.ValidationFailed,+ KernelDiagnosticSeverity.Error,+ message,+ "Brep.Recipes.ThroughHole.RequestBuilder"),+ ]);+}++/// <summary>+/// The "Hello World" of explicit BRep construction: six surviving box faces,+/// one circular inner loop on each entry/exit face, and one cylindrical wall+/// whose periodic seam and rings have known senses. Surgery realizes the known+/// loops/faces/shell; this class does not inspect arbitrary operand topology.+///+/// Rotated tools, blind termination, tangent/coincident entry, intersecting+/// prior voids, and non-planar supports require different recognized contracts.+/// Generalizing this request to accept two bodies would erase the facts that+/// make this recipe tractable.+/// </summary>+internal static class ThroughHoleConstructionRecipe+{+ public static KernelResult<BrepBody> Execute(ThroughHoleRecipeRequest? request)+ {+ if (request is null)+ {+ return Failure("Through-hole recipe requires recognized intent.");+ }++ if (request.Root.Kind != SafeBooleanRootKind.Box+ || request.Root != request.ConstructionHistory.RootDescriptor+ || request.Hole.SpanKind != SupportedBooleanHoleSpanKind.Through+ || request.Hole.Surface.Kind != AnalyticSurfaceKind.Cylinder+ || request.ConstructionHistory.Holes.Count != 1+ || request.ConstructionHistory.Holes[0] != request.Hole)+ {+ return Failure(+ "Through-hole recipe requires one recognized cylindrical void spanning two distinct planar supports on a box root.");+ }++ // The historical builder remains the rollback/parity seam. Its narrow+ // realization entry now uses Surgery primitives; recognition, Judgment,+ // and construction history stay outside this recipe.+ return BrepBooleanBoxCylinderHoleBuilder.BuildRecognizedThroughHoleTopology(+ request.ConstructionHistory,+ request.Tolerance);+ }++ private static KernelResult<BrepBody> Failure(string message)+ => KernelResult<BrepBody>.Failure([+ new KernelDiagnostic(+ KernelDiagnosticCode.ValidationFailed,+ KernelDiagnosticSeverity.Error,+ message,+ "Brep.Recipes.ThroughHole"),+ ]);+}diff --git a/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs b/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.csindex 8195d602..ae7c32b3 100644--- a/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs+++ b/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs@@ -5,6 +5,7 @@ using System.Runtime.CompilerServices;[assembly: InternalsVisibleTo("Aetheris.FrictionLab.Tests")][assembly: InternalsVisibleTo("Aetheris.Kernel.Firmament")][assembly: InternalsVisibleTo("Aetheris.Kernel.Firmament.Tests")]+[assembly: InternalsVisibleTo("Aetheris.Kernel.StandardLibrary")][assembly: InternalsVisibleTo("aetheris")][assembly: InternalsVisibleTo("Aetheris.Continuum")][assembly: InternalsVisibleTo("Aetheris.Continuum.Tests")]diff --git a/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.csindex c53bf1ee..f902d9e8 100644--- a/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs@@ -31,6 +31,11 @@ public sealed class AirHoleSimpleShaftMaterializerTestsAssert.Equal(-5, result.Plan.CutZMin);Assert.Equal(5, result.Plan.CutZMax);Assert.Contains(result.Diagnostics, d => d.Contains("semantic-parent featureId=hole-001", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("ThroughHoleConstructionRecipe", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("no Boolean or temporary tool BRep", StringComparison.Ordinal));+ Assert.Contains("ThroughHoleConstructionRecipe", correspondence.ProvenanceChain);+ Assert.Contains("BrepSurgery", correspondence.ProvenanceChain);+ Assert.DoesNotContain("ProfileStackExtrudeSpec", correspondence.ProvenanceChain);Assert.DoesNotContain(result.Diagnostics, d => d.Contains("CylinderCut", StringComparison.OrdinalIgnoreCase));var step = Step242Exporter.ExportBody(result.Body!);diff --git a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.csindex 4640f61e..39fabff9 100644--- a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs@@ -22,6 +22,8 @@ public sealed class CirBrepMaterializerTestsAssert.True(result.IsSuccess);Assert.Equal("subtract_box_cylinder", result.SelectedStrategy);Assert.Equal(CirBrepMaterializer.BoxMinusCylinderPattern, result.PatternName);+ Assert.Equal("matched-box-minus-cylinder-direct-recipe", result.Message);+ Assert.Equal("cut", Assert.Single(result.Body!.SafeBooleanComposition!.Holes).FeatureId);}[Fact]@@ -36,6 +38,7 @@ public sealed class CirBrepMaterializerTestsAssert.True(result.IsSuccess);Assert.Equal("subtract_box_box", result.SelectedStrategy);Assert.Equal(CirBrepMaterializer.BoxMinusBoxPattern, result.PatternName);+ Assert.Null(result.Body!.SafeBooleanComposition?.Holes.SingleOrDefault().FeatureId);}[Fact]diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.csindex ac75f5d9..b5c03f4a 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs@@ -48,7 +48,14 @@ public sealed class FirmamentV2SemanticHoleTestsAssert.True(result.Succeeded, string.Join(" | ", result.Diagnostics));Assert.Equal(kind, result.Plan!.StackKind.ToString());Assert.Equal(nameof(AirHoleFeature), result.Plan.SemanticSourceKind);- Assert.Contains(result.Diagnostics, d => d.Contains("semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor", StringComparison.Ordinal));+ if (kind == "SimpleShaft")+ {+ Assert.Contains(result.Diagnostics, d => d.Contains("semantic AirHoleFeature -> ThroughHoleRecipeRequest -> ThroughHoleConstructionRecipe", StringComparison.Ordinal));+ }+ else+ {+ Assert.Contains(result.Diagnostics, d => d.Contains("semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor", StringComparison.Ordinal));+ }}private static void AssertHole(string fixture, FirmamentV2SemanticHoleVariant variant)diff --git a/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.csindex 6d0df443..870691b6 100644--- a/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs@@ -20,9 +20,9 @@ public sealed class ThroughHoleRecoveryExecutorTestsAssert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);Assert.NotNull(result.Body);- Assert.Contains("Box primitive constructed.", result.Diagnostics);- Assert.Contains(result.Diagnostics, d => d.Contains("Cylinder primitive constructed", StringComparison.Ordinal));- Assert.Contains("Boolean subtract succeeded.", result.Diagnostics);+ Assert.Contains(result.Diagnostics, d => d.Contains("Recipe request constructed from recognized semantics", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("no temporary tool BRep or Boolean recognition pass", StringComparison.Ordinal));+ Assert.Contains("Through-hole Recipe succeeded.", result.Diagnostics);}[Fact]@@ -37,7 +37,7 @@ public sealed class ThroughHoleRecoveryExecutorTestsAssert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);Assert.NotNull(result.Body);- Assert.Contains("Boolean subtract succeeded.", result.Diagnostics);+ Assert.Contains("Through-hole Recipe succeeded.", result.Diagnostics);}[Fact]diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.csindex c9064a4c..bf3bc196 100644--- a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs@@ -1,6 +1,8 @@using Aetheris.Kernel.Core.Air;using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Recipes;using Aetheris.Kernel.Core.Geometry.Curves;+using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Topology;using Aetheris.Kernel.Firmament.FirmamentV2;@@ -107,9 +109,43 @@ internal static class AirHoleSimpleShaftMaterializer}var diagnostics = planResult.Diagnostics.ToList();- diagnostics.Add("air-hole-x2 execution route: semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor.");diagnostics.Add($"air-hole-x2 semantic-parent featureId={planResult.Plan.SemanticFeatureId} source={planResult.Plan.SemanticSourceKind}.");+ if (planResult.Plan.EndConditionKind == AirHoleEndConditionKind.ThroughAll+ && planResult.Plan.StackKind == AirHoleStackKind.SimpleShaft)+ {+ diagnostics.Add("air-hole-m5 execution route: semantic AirHoleFeature -> ThroughHoleRecipeRequest -> ThroughHoleConstructionRecipe.");+ var hostCenterZ = (host.ZMin + host.ZMax) * 0.5d;+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ host.Width,+ host.Depth,+ host.Thickness,+ new Vector3D(0d, 0d, hostCenterZ),+ planResult.Plan.Radius,+ host.Thickness,+ new Vector3D(planResult.Plan.CenterU, planResult.Plan.CenterV, hostCenterZ),+ planResult.Plan.SemanticFeatureId);+ if (!request.IsSuccess)+ {+ diagnostics.AddRange(request.Diagnostics.Select(diagnostic => $"air-hole-m5 recipe request failed: {diagnostic.Message}"));+ return new(AirHoleSimpleShaftMaterializationStatus.ExecutionFailed, planResult.Plan, null, diagnostics);+ }++ var recipe = ThroughHoleConstructionRecipe.Execute(request.Value);+ if (!recipe.IsSuccess)+ {+ diagnostics.AddRange(recipe.Diagnostics.Select(diagnostic => $"air-hole-m5 recipe execution failed: {diagnostic.Message}"));+ return new(AirHoleSimpleShaftMaterializationStatus.ExecutionFailed, planResult.Plan, null, diagnostics);+ }++ diagnostics.Add("air-hole-m5 direct Recipe materialization succeeded; no Boolean or temporary tool BRep was used.");+ var recipeCorrespondence = BuildCorrespondence(planResult.Plan, recipe.Value);+ diagnostics.Add("air-hole-x2 semantic correspondence published: entry/exit loops and edges plus shaft wall face.");+ return new(AirHoleSimpleShaftMaterializationStatus.Succeeded, planResult.Plan, recipe.Value, diagnostics, recipeCorrespondence);+ }++ diagnostics.Add("air-hole-x2 execution route: semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor.");+var execution = ProfileStackExtrudeExecutor.Execute(planResult.Plan.ProfileStackSpec);diagnostics.AddRange(execution.Diagnostics);if (execution.Status != ProfileStackExtrudeExecutionStatus.Succeeded || execution.Body is null)@@ -206,7 +242,7 @@ internal static class AirHoleSimpleShaftMaterializernew($"material:{source}:exit-edge", "Edge", SemanticTopologyRole.BottomBoundary, source, Edge: EdgeOf(exitLoop), ParentStableId: plan.SemanticFeatureId),new($"material:{source}:wall", "Face", SemanticTopologyRole.HoleWallFace, source, Face: wall.Id, ParentStableId: plan.SemanticFeatureId)};- return new(plan.SemanticFeature.TargetBodyId ?? "semantic-hole-host", descendants, ["HoleAIR", "AirHoleSimpleShaftMaterializationPlan", "ProfileStackExtrudeSpec", "AuthoritativeBRepPlan"]);+ return new(plan.SemanticFeature.TargetBodyId ?? "semantic-hole-host", descendants, ["HoleAIR", "AirHoleSimpleShaftMaterializationPlan", "ThroughHoleConstructionRecipe", "BrepSurgery"]);}private static IEnumerable<ProfileStackLayer> BuildLayers(AirHoleFeature feature, AirHoleSimpleShaftHost host, double cutZMin, double cutZMax)diff --git a/Aetheris.Kernel.Firmament/Materializer/CirBrepMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/CirBrepMaterializer.csindex aa9796cb..b29b448c 100644--- a/Aetheris.Kernel.Firmament/Materializer/CirBrepMaterializer.cs+++ b/Aetheris.Kernel.Firmament/Materializer/CirBrepMaterializer.cs@@ -1,5 +1,6 @@using Aetheris.Kernel.Core.Brep;using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Brep.Recipes;using Aetheris.Continuum.Backends.Sdf;using Aetheris.Kernel.Core.Diagnostics;using Aetheris.Kernel.Core.Judgment;@@ -57,12 +58,18 @@ internal static class CirBrepMaterializerpublic CirBrepMaterializationResult Materialize(CirBrepMaterializerContext context){if (!TryMatch(context, true, out var m, out var reason)) return new(false, null, BoxMinusCylinderPattern, "strategy-no-longer-admissible", [], reason, Name, []);- var b = BrepPrimitives.CreateBox(m!.LeftBox.Width, m.LeftBox.Height, m.LeftBox.Depth);- var c = BrepPrimitives.CreateCylinder(m.Cylinder!.Radius, m.Cylinder.Height);- if (!b.IsSuccess) return Failed(BoxMinusCylinderPattern, "Failed to create BRep box primitive.", b.Diagnostics);- if (!c.IsSuccess) return Failed(BoxMinusCylinderPattern, "Failed to create BRep cylinder primitive.", c.Diagnostics);- var s = BrepBoolean.Subtract(TranslateBody(b.Value, m.LeftTranslation), TranslateBody(c.Value, m.RightTranslation));- return s.IsSuccess ? new(true, s.Value, BoxMinusCylinderPattern, null, [], "matched-box-minus-cylinder", Name, []) : Failed(BoxMinusCylinderPattern, "Failed to boolean subtract box/cylinder during CIR rematerialization.", s.Diagnostics);+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ m!.LeftBox.Width,+ m.LeftBox.Height,+ m.LeftBox.Depth,+ m.LeftTranslation,+ m.Cylinder!.Radius,+ m.Cylinder.Height,+ m.RightTranslation,+ context.LatestOperation?.FeatureId);+ if (!request.IsSuccess) return Failed(BoxMinusCylinderPattern, "Failed to construct recognized CIR through-hole Recipe request.", request.Diagnostics);+ var recipe = ThroughHoleConstructionRecipe.Execute(request.Value);+ return recipe.IsSuccess ? new(true, recipe.Value, BoxMinusCylinderPattern, null, [], "matched-box-minus-cylinder-direct-recipe", Name, []) : Failed(BoxMinusCylinderPattern, "Failed to execute through-hole Recipe during CIR rematerialization.", recipe.Diagnostics);}}diff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.csindex 7c2ffbb6..ee73dba2 100644--- a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs@@ -1,6 +1,5 @@using Aetheris.Kernel.Core.Brep;-using Aetheris.Kernel.Core.Brep.Boolean;-using Aetheris.Kernel.Firmament.Execution;+using Aetheris.Kernel.Core.Brep.Recipes;namespace Aetheris.Kernel.Firmament.Materializer;@@ -43,49 +42,39 @@ public static class ThroughHoleRecoveryExecutordiagnostics.Add("Plan specialization accepted: rectangular-box + cylindrical + circular + Z-axis.");- var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);- if (!boxResult.IsSuccess)- {- diagnostics.Add($"Box primitive construction failed: {string.Join(" | ", boxResult.Diagnostics.Select(d => d.Message))}");- return new(ThroughHoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);- }-- var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);- diagnostics.Add("Box primitive constructed.");-var throughLength = double.Max(plan.ThroughLength, plan.HostSizeZ);- var cylinderResult = BrepPrimitives.CreateCylinder(plan.ToolRadius, throughLength);- if (!cylinderResult.IsSuccess)+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ plan.HostSizeX,+ plan.HostSizeY,+ plan.HostSizeZ,+ plan.HostTranslation,+ plan.ToolRadius,+ throughLength,+ plan.ToolTranslation);+ if (!request.IsSuccess){- diagnostics.Add($"Cylinder primitive construction failed: {string.Join(" | ", cylinderResult.Diagnostics.Select(d => d.Message))}");+ diagnostics.Add($"Recipe request construction failed: {string.Join(" | ", request.Diagnostics.Select(d => d.Message))}");return new(ThroughHoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);}- var cylinderBody = TranslateBody(cylinderResult.Value, plan.ToolTranslation);- diagnostics.Add($"Cylinder primitive constructed (height={throughLength:G17}).");-- diagnostics.Add("Boolean subtract invoked.");- var subtract = BrepBoolean.Subtract(boxBody, cylinderBody);- if (!subtract.IsSuccess)+ diagnostics.Add($"Through-hole Recipe request constructed from recognized semantics (height={throughLength:G17}).");+ diagnostics.Add("Direct ThroughHoleConstructionRecipe invoked; no temporary tool BRep or Boolean recognition pass.");+ var recipe = ThroughHoleConstructionRecipe.Execute(request.Value);+ if (!recipe.IsSuccess){- diagnostics.Add($"Boolean subtract failed: {string.Join(" | ", subtract.Diagnostics.Select(d => d.Message))}");+ diagnostics.Add($"Through-hole Recipe failed: {string.Join(" | ", recipe.Diagnostics.Select(d => d.Message))}");return new(ThroughHoleRecoveryExecutionStatus.BooleanFailed, null, diagnostics);}- diagnostics.Add("Boolean subtract succeeded.");+ diagnostics.Add("Through-hole Recipe succeeded.");- if (subtract.Value is null)+ if (recipe.Value is null){- diagnostics.Add("Invalid result: subtract success returned null body.");+ diagnostics.Add("Invalid result: Recipe success returned null body.");return new(ThroughHoleRecoveryExecutionStatus.InvalidResult, null, diagnostics);}diagnostics.Add("Result BRep body produced.");- return new(ThroughHoleRecoveryExecutionStatus.Succeeded, subtract.Value, diagnostics);+ return new(ThroughHoleRecoveryExecutionStatus.Succeeded, recipe.Value, diagnostics);}-- private static BrepBody TranslateBody(BrepBody body, Aetheris.Kernel.Core.Math.Vector3D translation)- => translation == Aetheris.Kernel.Core.Math.Vector3D.Zero- ? body- : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);}diff --git a/Aetheris.Kernel.StandardLibrary/StandardLibraryReusableParts.cs b/Aetheris.Kernel.StandardLibrary/StandardLibraryReusableParts.csindex af838cde..1a38c21d 100644--- a/Aetheris.Kernel.StandardLibrary/StandardLibraryReusableParts.cs+++ b/Aetheris.Kernel.StandardLibrary/StandardLibraryReusableParts.cs@@ -1,5 +1,6 @@using Aetheris.Kernel.Core.Brep;-using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Brep.Recipes;+using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Core.Diagnostics;using Aetheris.Kernel.Core.Results;@@ -56,19 +57,21 @@ public static class StandardLibraryReusablePartsconst double holeRadius = 3d;const double holeHeight = 24d;- var cubeResult = BrepPrimitives.CreateBox(cubeSize, cubeSize, cubeSize);- if (!cubeResult.IsSuccess)+ var request = ThroughHoleRecipeRequestBuilder.FromBoxAndZCylinder(+ cubeSize,+ cubeSize,+ cubeSize,+ Vector3D.Zero,+ holeRadius,+ holeHeight,+ Vector3D.Zero,+ featureId: CubeWithCylindricalHolePartName);+ if (!request.IsSuccess){- return cubeResult;+ return KernelResult<BrepBody>.Failure(request.Diagnostics);}- var holeResult = BrepPrimitives.CreateCylinder(holeRadius, holeHeight);- if (!holeResult.IsSuccess)- {- return holeResult;- }-- return BrepBoolean.Subtract(cubeResult.Value, holeResult.Value);+ return ThroughHoleConstructionRecipe.Execute(request.Value);}}diff --git a/Aetheris.Server/Api/KernelEndpoints.cs b/Aetheris.Server/Api/KernelEndpoints.csindex 7a3d5601..46a24627 100644--- a/Aetheris.Server/Api/KernelEndpoints.cs+++ b/Aetheris.Server/Api/KernelEndpoints.cs@@ -208,7 +208,8 @@ public static class KernelEndpoints}return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));- }));+ }))+ .WithDescription("Compatibility Boolean API for bounded recognized BRep families. Unsupported arbitrary body combinations return typed kernel rejections; this is not a general-purpose exact Boolean guarantee.");documents.MapPost("/{documentId:guid}/occurrences", (Guid documentId, CreateOccurrenceRequestDto request, KernelDocumentStore store) =>WithDocument(store, documentId, document =>diff --git a/docs/architecture/artifacts/archaeology-m4/README.md b/docs/architecture/artifacts/archaeology-m4/README.mdnew file mode 100644index 00000000..930864d4--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/README.md@@ -0,0 +1,16 @@+# AETHERIS-ARCHAEOLOGY-M4 evidence++Status: representative recipe migration implemented and validated.++M4 adds the internal `Aetheris.Kernel.Core.Brep.Recipes` ownership boundary.+Existing Boolean recognition, Judgment routing, and recognized-family history+produce typed requests; through-hole and polygonal through-cut recipes realize+their known topology through BRep Surgery. `BrepBoolean` remains the unchanged+public compatibility facade.++- [recipe-architecture.md](recipe-architecture.md)+- [through-hole-parity.md](through-hole-parity.md)+- [second-recipe-parity.md](second-recipe-parity.md)+- [composition-history.md](composition-history.md)+- [educational-migration.md](educational-migration.md)+- [validation-report.md](validation-report.md)diff --git a/docs/architecture/artifacts/archaeology-m4/composition-history.md b/docs/architecture/artifacts/archaeology-m4/composition-history.mdnew file mode 100644index 00000000..0b51d2b3--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/composition-history.md@@ -0,0 +1,11 @@+# Composition history++`SafeBooleanComposition` remains above Recipes as recognized-family+construction history, not generic BRep metadata. The through-hole request+retains the exact history containing root kind, feature identity, analytic+descriptor, axis/span/radii, and continuation state; its result preserves that+same object. Polygonal facade rebuilding continues to attach its admitted+through-void history after recipe realization.++Stepped/counterbore, conic, mixed-family, and continuation policies remain in+their historical classifiers/builders. M4 does not erase or generalize them.diff --git a/docs/architecture/artifacts/archaeology-m4/educational-migration.md b/docs/architecture/artifacts/archaeology-m4/educational-migration.mdnew file mode 100644index 00000000..b20c18a8--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/educational-migration.md@@ -0,0 +1,13 @@+# Educational migration++The through-hole recipe entry documents its known input family, seven-face+output, ring/seam orientation, validation expectations, and the cases that+break the contract. The polygonal recipe documents the contrasting ordered-wall+lesson. The old builder entry points remain named adapters/parity seams rather+than deleted teaching logic.++`docs/kernel/brep-surgery.md` now follows a complete recognized request through+geometry, loops, faces, assembly, validation, STEP, and reimport and includes a+recipe checklist. `docs/kernel/brep-boolean-lessons.md` now covers the API+illusion, intersection-versus-topology, through/blind/stepped holes,+counterbores, polygonal contrast, and the generic-CIR limitation.diff --git a/docs/architecture/artifacts/archaeology-m4/recipe-architecture.md b/docs/architecture/artifacts/archaeology-m4/recipe-architecture.mdnew file mode 100644index 00000000..35caf7e0--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/recipe-architecture.md@@ -0,0 +1,18 @@+# Recipe architecture++```text+recognition / Judgment / SafeBooleanComposition+ -> ThroughHoleRecipeRequest | PolygonalThroughCutRecipeRequest+ -> ThroughHoleConstructionRecipe | PolygonalThroughCutRecipe+ -> BrepLoopBuilder / BrepFaceBuilder / BrepShellAssembler / validation+ -> BrepBody -> STEP validation+```++Requests contain recognized roots, feature descriptors/ordered footprints,+bounded span, tolerance, and only the history needed by the construction. They+never accept two arbitrary bodies. Results are `KernelResult<BrepBody>` and+direct-contract failures are typed `KernelDiagnostic` values.++`IntersectionQuery` and other geometry queries remain observational. No new+Boolean family, generic intersection topology, public Surgery API, reflection,+or general recipe framework was added. M1's M4/M5 sequencing remains current.diff --git a/docs/architecture/artifacts/archaeology-m4/second-recipe-parity.md b/docs/architecture/artifacts/archaeology-m4/second-recipe-parity.mdnew file mode 100644index 00000000..b5498955--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/second-recipe-parity.md@@ -0,0 +1,12 @@+# Polygonal through-cut parity++The contrasting recipe consumes ordered outer/inner footprints and root bounds.+Unlike a circular hole, it creates one planar cavity wall per polygon edge and+multi-edge inner support loops. The existing M3 implementation remains callable+as `BuildLegacy`; the facade now explicitly creates a typed recipe request.++The rounded-box/slot fixture remains 128 vertices, 192 edges, and 66 faces with+192 curves and 66 planar surfaces. Legacy, direct recipe, and facade STEP are+identical. The established canonical SHA-256 remains+`8554faf173a41abeb15facbeb2bd3cceb4f2ea486d6aa1e1b11c0740b922fe7d` and+STEP reimport remains valid.diff --git a/docs/architecture/artifacts/archaeology-m4/through-hole-parity.md b/docs/architecture/artifacts/archaeology-m4/through-hole-parity.mdnew file mode 100644index 00000000..c6f1acf2--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/through-hole-parity.md@@ -0,0 +1,20 @@+# Through-hole parity++The canonical box/cylinder through-hole is routed by existing Boolean policy to+`ThroughHoleRecipeRequest`, then `ThroughHoleConstructionRecipe`. The retained+`BuildRecognizedThroughHoleLegacy` seam permits direct comparison.++Canonical result: 12 vertices, 15 edges, 7 faces, 9 loops, 30 coedges, 15+curves, and 7 surfaces (six planar, one cylindrical). Entry and exit faces each+own one inner circular loop; the wall owns its rings and periodic seam.++Direct recipe, legacy seam, and `BrepBoolean.Subtract` have identical topology+counts, bindings, analytic supports, orientations as serialized, construction+history object, and exact STEP text/SHA-256. STEP reimport passes binding and+manifold preflight. No historical hash was fabricated; equality is measured+against the retained implementation on every test run.++The real Firmament source was also rebuilt and inspected with Aetheris CLI. Its+STEP SHA-256 was `9183b3ed6747b0d754910bec5cd60c0affce08f0f43310e0623477ab7fc1fbe4`;+CLI reported 12 vertices, 15 edges, 7 faces, six planes, one cylinder, and+`enclosed-manifold`.diff --git a/docs/architecture/artifacts/archaeology-m4/validation-report.md b/docs/architecture/artifacts/archaeology-m4/validation-report.mdnew file mode 100644index 00000000..39b35e22--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m4/validation-report.md@@ -0,0 +1,32 @@+# Validation report++Validation was run on 2026-08-13 (America/Los_Angeles).++- `dotnet restore Aetheris.slnx`: passed.+- `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1`: passed with 0 warnings and 0 errors.+- Aetheris CLI rebuilt the canonical Firmament box/cylinder example and inspected+ its STEP as an enclosed manifold: 12 vertices, 15 edges, 7 faces, six planes,+ and one cylinder.+- Core: 953 passed, including Boolean, Surgery, Recipes, STEP AP242,+ StandardLibrary consumers, and SurfaceMeshIR.+- Recipe direct/performance tests: 5 passed. Exact legacy/recipe/facade STEP+ parity and typed rejection passed. A non-benchmark 100-iteration smoke+ measurement was 10.942 ms legacy versus 5.882 ms recipe on this run.+- Firmament: 1,115 passed. Focused hole/CIR/StandardLibrary/SurfaceMeshIR+ materializers: 292 passed.+- Focused STEP/SurfaceMesh/recipe: 294 passed.+- CLI: 364 passed.+- Opt-in FrictionLab: 394 passed after excluding the documented unrelated+ `TriangleHexPrismProfileParityLabTests`; the complete run was 394 passed and+ 5 failed, all five manifestations of its pre-existing non-finite interval.++The pre-existing `TriangleHexPrismProfileParityLabTests` non-finite+`ParameterInterval` failure remains classified as unrelated unless its behavior+changes. No giant BRep or STEP dump is stored here.++One pre-existing artifact inconsistency was surfaced rather than hidden: the+checked-in `testdata/firmament/exports/boolean_box_cylinder_hole.step` reports+an old disconnected wall-loop ordering, while rebuilding its source through the+current real path reports `enclosed-manifold`. M4 did not rewrite the historical+fixture because canonical Firmament artifact migration is outside this phase;+the new/legacy/facade comparisons use current generated output.diff --git a/docs/architecture/artifacts/archaeology-m5/README.md b/docs/architecture/artifacts/archaeology-m5/README.mdnew file mode 100644index 00000000..f2fc810f--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/README.md@@ -0,0 +1,14 @@+# Archaeology M5: production caller migration++M5 moves callers that already know through-hole intent to `ThroughHoleConstructionRecipe`. The typed `ThroughHoleRecipeRequestBuilder` converts semantic box/Z-cylinder data into validated construction history without constructing or recognizing temporary operand bodies.++Migrated: `ThroughHoleRecoveryExecutor`, recognized CIR `subtract(box,cylinder)`, and StandardLibrary `cube_with_cylindrical_hole`. The public Boolean facade remains stable for legacy/generic callers. No Boolean family or Surgery public surface was added.++- [production-caller-map.md](production-caller-map.md)+- [firmament-migration.md](firmament-migration.md)+- [cir-migration.md](cir-migration.md)+- [standardlibrary-migration.md](standardlibrary-migration.md)+- [remaining-boolean-callers.md](remaining-boolean-callers.md)+- [kernelsdk-boundary.md](kernelsdk-boundary.md)+- [topology-parity.md](topology-parity.md)+- [validation-report.md](validation-report.md)diff --git a/docs/architecture/artifacts/archaeology-m5/cir-migration.md b/docs/architecture/artifacts/archaeology-m5/cir-migration.mdnew file mode 100644index 00000000..653c1d9e--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/cir-migration.md@@ -0,0 +1,5 @@+# CIR migration++The `subtract_box_cylinder` Judgment strategy already knows box dimensions/translations, cylinder radius/span, and replay feature identity. It now creates a typed request and executes the through-hole Recipe directly. Two primitive builds plus Boolean operand/root/tool recognition are removed.++The `subtract_box_box` strategy still invokes the bounded compatibility facade because no recognized reusable construction Recipe describes that result. `subtract_box_torus` remains a precise unsupported result. Arbitrary CIR trees still receive `no-strategy-matched`; CIR field composition and intersection witnesses have not become topology authority.diff --git a/docs/architecture/artifacts/archaeology-m5/firmament-migration.md b/docs/architecture/artifacts/archaeology-m5/firmament-migration.mdnew file mode 100644index 00000000..8261c107--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/firmament-migration.md@@ -0,0 +1,16 @@+# Firmament migration++The recovered through-hole path is now:++```text+Firmament V2 source / ConstructionIR+ -> CIR box-cylinder recognition and ThroughHoleRecoveryPlan+ -> typed ThroughHoleRecipeRequestBuilder+ -> ThroughHoleConstructionRecipe+ -> BRep Surgery+ -> validated BRep -> STEP AP242+```++`AirHoleSimpleShaftMaterializer` routes canonical face-local `ThroughAll` simple shafts directly to the Recipe and publishes that route in semantic topology provenance. `ThroughHoleRecoveryExecutor` likewise no longer creates a box/tool BRep or invokes `BrepBoolean`. `HoleRecoveryExecutor` delegates its legacy through fallback to this executor.++Blind, counterbore, countersink, chamfered-entry, and stepped legacy fallbacks remain bounded Boolean users because M5 does not introduce their missing Recipes. Firmament V1 primitive execution remains unchanged and opt-in compatibility tests cover its historical route.diff --git a/docs/architecture/artifacts/archaeology-m5/kernelsdk-boundary.md b/docs/architecture/artifacts/archaeology-m5/kernelsdk-boundary.mdnew file mode 100644index 00000000..5f37f5ec--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/kernelsdk-boundary.md@@ -0,0 +1,12 @@+# KernelSDK and Surgery boundary++Classification:++| Primitive | M5 classification | Reason |+|---|---|---|+| explicit edge use, strict loop, face, shell builders; validation | internal; plausible safe-advanced later | typed/deterministic, but public identity/provenance contract is immature |+| legacy-sense loop helper | not ready | intentionally bypasses the strict new closure convention for canonical parity |+| raw topology/store mutation or validation bypass | requires unsafe; not exposed | can construct invalid state |+| recognized Recipes | preferred future advanced surface | preserves intent above topology mechanics |++Nothing is exposed in M5. An architecture test proves Surgery types are non-public and Core does not friend-expose internals to Forge.Host or Forge.KernelSDK. The extension `UNSAFE` opt-in permits arbitrary in-process C# and is not a CLR sandbox or a BRep permission boundary. Forge.Host continues through Templates, recognized construction interfaces, Modules, and normal generation.diff --git a/docs/architecture/artifacts/archaeology-m5/production-caller-map.md b/docs/architecture/artifacts/archaeology-m5/production-caller-map.mdnew file mode 100644index 00000000..fb0c5552--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/production-caller-map.md@@ -0,0 +1,17 @@+# Production Boolean caller map++Counts are direct call sites outside Core/tests/labs: **15 before M5; 12 after M5**. Caller classes fell from six to four.++| Caller | Class | Old path | M5 path / retention | Risk |+|---|---|---|---|---|+| `ThroughHoleRecoveryExecutor` | known construction | box + cylinder -> `Subtract` | semantic plan -> request builder -> through-hole Recipe | low; migrated with differential parity |+| `AirHoleSimpleShaftMaterializer` | canonical V2 known construction | semantic plan -> profile-stack emitter | face-local ThroughAll simple shaft -> through-hole Recipe | low; migrated with CLI STEP dogfood |+| `HoleRecoveryExecutor` through variant | known construction | delegates to above after bounded routing | delegated path is now direct Recipe | low |+| `HoleRecoveryExecutor` blind/counterbore/countersink/stepped | known bounded legacy family | one or repeated `Subtract` fallbacks; profile-stack route preferred where admitted | retained: no matching explicit Recipe in M5 | medium/high |+| `StandardLibraryReusableParts` cube/hole | known construction | primitives -> `Subtract` | semantic dimensions -> request builder -> Recipe | low; migrated |+| recognized CIR box/cylinder | import recovery + recognized construction | primitives -> `Subtract` | recognized parameters -> request builder -> Recipe | medium; migrated and preserves replay feature ID |+| recognized CIR box/box | bounded compatibility | primitives -> `Subtract` | retained; no explicit construction Recipe | medium |+| `FirmamentPrimitiveExecutor` | V1 compatibility and generic V2 primitive bridge | operation enum -> Boolean facade | retained to preserve format/execution behavior | high |+| server Boolean endpoint | external compatibility API | arbitrary body IDs + operation -> facade | retained and documented as bounded, not general | high |++`ClassifyBooleanCase` has no external production caller. Test and FrictionLab calls remain historical/experimental evidence and were not migrated for count reduction.diff --git a/docs/architecture/artifacts/archaeology-m5/remaining-boolean-callers.md b/docs/architecture/artifacts/archaeology-m5/remaining-boolean-callers.mdnew file mode 100644index 00000000..3b25d279--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/remaining-boolean-callers.md@@ -0,0 +1,8 @@+# Remaining Boolean callers++- `FirmamentPrimitiveExecutor`: compatibility execution for operation-shaped V1 input and a generic primitive bridge. Retained deliberately; known recovered through holes take the Recipe path elsewhere.+- `HoleRecoveryExecutor`: five direct subtract sites implement legacy blind/counterbore/countersink/chamfered/stepped fallback families. Their multi-stage history and topology require family-specific Recipes outside M5.+- `CirBrepMaterializer` box/box: recognized operands but no named reusable construction Recipe.+- server `operations/boolean`: genuine external compatibility surface over two stored bodies. API description now states bounded-family support and typed rejection.++The facade remains public and behavior-compatible. It is not the normal implementation path for the three migrated semantic constructions.diff --git a/docs/architecture/artifacts/archaeology-m5/standardlibrary-migration.md b/docs/architecture/artifacts/archaeology-m5/standardlibrary-migration.mdnew file mode 100644index 00000000..811a809a--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/standardlibrary-migration.md@@ -0,0 +1,5 @@+# StandardLibrary migration++`cube_with_cylindrical_hole` already owns fixed feature intent (20-unit cube, radius 3, through span 24). It now calls the typed request builder and `ThroughHoleConstructionRecipe` directly; StandardLibrary does not consume Surgery.++The differential test compares this result against the former primitive/Boolean path for topology/geometry/binding counts and canonical STEP hash, then exports and reimports STEP. The Recipe history now retains the standard-part feature ID; geometry and STEP remain identical.diff --git a/docs/architecture/artifacts/archaeology-m5/topology-parity.md b/docs/architecture/artifacts/archaeology-m5/topology-parity.mdnew file mode 100644index 00000000..2c7d3858--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/topology-parity.md@@ -0,0 +1,9 @@+# Topology and artifact parity++Differential coverage retains the old facade as a test oracle. Direct through-hole output matches it for vertices, edges, faces, loops, coedges, curves, surfaces, edge/face bindings, and canonical STEP SHA-256. The canonical result remains seven faces, nine loops, thirty coedges, and one cylindrical support. STEP export/reimport and complete binding validation pass.++Translated semantic input also matches the facade. CIR preserves replay feature identity; StandardLibrary records its known part feature ID. These are history/provenance gains and do not alter STEP topology. Surgery validation runs on every comparison.++The request builder calls bounded composition policy directly. Per migrated execution it removes one root recognition, one tool analytic recognition, the related dispatcher classification, and both temporary primitive constructions where the caller previously built them.++Representative 30-iteration measurements (diagnostic regression test, not a benchmark suite): Firmament 11.229 ms facade vs 1.857 ms direct; CIR 5.071 ms vs 1.833 ms; StandardLibrary 4.977 ms vs 1.908 ms. The direct path is faster in all three samples because it skips operand construction and re-recognition.diff --git a/docs/architecture/artifacts/archaeology-m5/validation-report.md b/docs/architecture/artifacts/archaeology-m5/validation-report.mdnew file mode 100644index 00000000..c833a219--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m5/validation-report.md@@ -0,0 +1,15 @@+# Validation report++Validation results:++- `dotnet restore Aetheris.slnx`: clean.+- `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1`: clean, zero warnings/errors.+- Core full suite: 959 passed (includes Recipe/Surgery/Boolean/STEP parity and boundary tests).+- Firmament default: 1,115 passed. Opt-in V1 compatibility: 1,734 passed.+- CLI: 364 passed; Forge Host: 10; Server: 54; Continuum/SurfaceMeshIR: 148.+- Remaining solution projects: Collaboration 5, FEA 12, Geometry 58, Modules 37, Reconstruction 24, Semantics 9, sample 8; all passed.+- Focused Boolean/CIR FrictionLab: 31 passed.+- Full opt-in FrictionLab: 394 passed, 5 known failures.+- CLI V2 dogfood parsed `Hole<Shaft> Mount`, built STEP hash `EE665BD001DF97D210E4FBB5D535FF2E26FC58601AA369B204089B7378799450`, reimported one enclosed manifold with 7 faces/15 edges/12 vertices, six planes, and one cylinder. The hash is unchanged from the pre-migration artifact.++The five failures are exactly the known `TriangleHexPrismProfileParityLabTests` non-finite `ParameterInterval` baseline at `ProfileExtrusionBRepPlan.cs:128`; no M5 path is present in their stacks.diff --git a/docs/kernel/brep-boolean-lessons.md b/docs/kernel/brep-boolean-lessons.mdindex 35bb4457..41bbc0fc 100644--- a/docs/kernel/brep-boolean-lessons.md+++ b/docs/kernel/brep-boolean-lessons.md@@ -1,12 +1,43 @@# BRep Boolean lessons+This is a practical guide for implementing a bounded topology recipe. The+public Boolean names are compatibility vocabulary; they are not evidence that+the kernel can infer arbitrary result topology.++## The Boolean API illusion++`Subtract(left, right)` looks uniform while its successful implementations are+not. A through-hole, blind pocket, open keyway, prismatic cut, and orthogonal+union each require different loop roles, face survival rules, orientation, and+history. The facade is useful routing compatibility, but the implementation+must eventually name the recognized construction it is performing.+## 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.+For the canonical box/cylinder case, recognition proves a world-Z cylinder+fully spans a box. `ThroughHoleRecipeRequest` then carries the box root, the+recognized hole descriptor, tolerance, feature identity, and+`SafeBooleanComposition` history. The expected result is fixed before topology+editing: six surviving exterior faces, one inner circular loop on each planar+support, one cylindrical wall, two rings, and a periodic seam. The recipe+supplies those loop senses and support bindings to Surgery, then validates and+STEP-round-trips the result.++This works reliably because the answer's topology is part of the admitted+family contract. A generic arbitrary-body subtraction lacks that contract: an+intersection curve cannot say which fragments survive, which loops are inner,+how faces are oriented, which identity survives, or whether earlier features+permit the operation.++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. Rotated tools, tangency at entry,+non-planar supports, and intersection with an existing void likewise require+new bounded recognition and topology contracts, not flags on this recipe.## Composition and the stepped-hole cliff@@ -26,6 +57,42 @@ A counterbore predicts two cylindrical walls, an annular shoulder, ordered radiiThe 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.+## Contrasting recipe: polygonal through cut++The polygonal recipe is deliberately not a circular-hole parameterization.+Recognition supplies ordered outer and inner footprints and a full through+span. The recipe creates one planar cavity wall per inner polygon segment and+multi-edge inner loops on both support faces. Explicit correspondence and wall+ordering replace the circular recipe's analytic rings and periodic seam. Both+recipes use the same Surgery mechanics because those mechanics only realize+caller-authorized loops, faces, shells, and validation.++## When to write your own BRep recipe++Use this decision ladder:++1. Prefer a Firmament Template for ordinary product generation.+2. Use a typed construction primitive when the result is a primitive.+3. Use an existing recognized Recipe when its admitted intent matches.+4. Add a reusable bounded Recipe when a construction family is broadly useful and its expected topology can be stated completely.+5. Use bespoke Surgery only when the consumer already knows the exact topology it must author.+6. Treat arbitrary-body Boolean as a compatibility or experimental path, not a default implementation strategy.++Do not add a central dispatcher case merely because a new pair of bodies can be recognized. The recognition must name a useful construction contract, and the result graph must be predictable enough for explicit validation.++### Bespoke bounded example++For a known planar plate with a known inner polygonal opening, gather intersection/contact evidence only to check the authored polygon against the support. Author the outer loop and the explicitly ordered inner loop, create one known wall face per inner edge, assemble the caller-selected faces into a shell, validate manifold incidence/bindings/finite geometry, then inspect and reimport STEP. The developer owns the expected topology, orientation, IDs, provenance, and tolerance decisions. `IntersectionQuery` witnesses are not authoritative trims unless that bespoke recipe explicitly adopts them under its own contract.++## Writing the bounded contract++Write the expected face/edge/loop graph first. State the admitted root and tool+families, orientation convention, tolerance boundaries, analytic support+requirements, identity/history behavior, and exact rejection cases. Only then+construct geometry and call Surgery. If those facts cannot be stated without+inspecting arbitrary fragments and guessing their role, the proposed recipe is+not bounded enough.+## M3 extraction lessonStrict 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.diff --git a/docs/kernel/brep-surgery.md b/docs/kernel/brep-surgery.mdindex c39c4f17..7c2097d5 100644--- a/docs/kernel/brep-surgery.md+++ b/docs/kernel/brep-surgery.md@@ -23,12 +23,62 @@ recognition + Judgment policy + composition/historyAll 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+## Complete recognized-recipe 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.+The canonical through-hole path is the smallest complete example:++```text+BrepBoolean recognition + Judgment + SafeBooleanComposition+ -> ThroughHoleRecipeRequest (box root, one through cylinder, history, tolerance)+ -> recipe creates box edges plus entry/exit rings and periodic seam geometry+ -> BrepLoopBuilder realizes caller-ordered outer, inner, and wall loops+ -> BrepFaceBuilder assigns the two rings as support-face inner loops+ and creates the cylindrical cavity wall+ -> BrepShellAssembler assembles the seven caller-selected faces+ -> recipe binds line/circle curves and plane/cylinder surfaces+ -> BrepSurgeryValidation checks topology, bindings, and finite vertices+ -> STEP AP242 export and reimport validate the ordinary interchange path+```++The recipe, not Surgery, knows that the top and bottom planar faces survive,+that each receives one circular inner loop, and that one inward-facing+cylindrical wall joins them. The periodic seam is intentionally represented in+the canonical legacy sense; the narrowly named compatibility loop primitive+preserves this without weakening strict construction for new representations.++The polygonal through-cut is the contrast. Its request supplies corresponding+outer and inner footprints. Every polygon segment becomes a separately ordered+planar cavity wall. The support faces receive multi-edge inner loops, yet the+same loop/face/shell/validation substrate applies because Surgery has no hole or+prism feature knowledge.++## Recipe author checklist++- Know the expected topology before editing.+- Preserve analytic supports instead of approximating them.+- Supply loop and face orientation deliberately.+- Preserve provenance, feature identity, and construction history deliberately.+- Validate edge/face incidence and manifoldness.+- Treat recognition and geometry tolerance explicitly.+- Export and reimport through the normal STEP path.+- Do not use generic numerical intersections as topology authority.## M3 compatibility seamsSome 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.+## Advanced consumer boundary++> BRep Surgery is an escape hatch for explicit topology construction, not a substitute general Boolean solver.++An advanced caller must know the expected vertices, edges, ordered loop uses, outer/inner loop roles, faces, supports, orientations, and shell membership before invoking Surgery. Geometry queries may provide evidence, but Surgery does not infer trims, surviving fragments, feature intent, or tolerances.++Surgery guarantees deterministic construction from typed explicit inputs and validates graph ownership, edge incidence, bindings when required, and finite vertex geometry. The caller remains responsible for stable identity, feature provenance, construction history, analytic support choice, and a declared tolerance policy. Validate topology and bindings, inspect support kinds/orientations, export and reimport STEP, and compare downstream mesh behavior when relevant.++Current primitive classification is:++- `BrepEdgeUse`, strict known-loop construction, known-face construction, shell assembly, and validation are plausible `SAFE_ADVANCED` building blocks but remain `INTERNAL_ONLY` while their public identity/provenance contracts mature.+- the legacy-sense loop seam is `NOT_READY`; it exists only for canonical compatibility output.+- arbitrary topology mutation, ID injection, bypassed validation, and raw store access would be `REQUIRES_UNSAFE` and are not exposed.++Forge's existing `UNSAFE` extension consent governs arbitrary in-process extension loading; it is not a topology sandbox. Because CLR in-process code cannot provide that sandbox and no BRep-specific permission contract exists, neither Forge.Host nor Forge.KernelSDK exposes Surgery in M5. Existing recognized Recipes should become the first advanced construction surface if consumer pressure establishes a stable public contract.