Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add through holes on oriented extrusion faces
Yuechen Li007bbb4644ca
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentSketchTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentSketchTests.csindex 2f7ab35c..2542d5ce 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentSketchTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentSketchTests.cs@@ -187,7 +187,7 @@ public class FirmamentSketchTests[Theory][InlineData("Remove Cut { profile: Other from: 0mm to: 6mm }", "compose-profile-frame-mismatch")][InlineData("Placement Override { anchor: [0mm,0mm,0mm] profilePlane: XY axis: +Z referenceDirection: +X }", "compose-profile-frame-mismatch")]- [InlineData("Hole<Shaft> Drill { on: +Z center: [0mm,0mm] diameter: 2mm end: ThroughAll }", "compose-oriented-feature-not-admitted")]+ [InlineData("Hole<Shaft> Drill { on: -Z center: [0mm,0mm] diameter: 2mm end: ThroughAll }", "compose-oriented-feature-not-admitted")]public void ComposeRejectsConflictingOrUnqualifiedFrameConsumers(string operation, string code){var source = $$"""diff --git a/Aetheris.Kernel.Firmament.Tests/MultiplePlanarFaceHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/MultiplePlanarFaceHoleTests.csnew file mode 100644index 00000000..32007725--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/MultiplePlanarFaceHoleTests.cs@@ -0,0 +1,113 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Verification;+using Aetheris.Kernel.Core.Step242;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class MultiplePlanarFaceHoleTests+{+ private static string Source => FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament");+ [Fact]+ public void CrossingShaftAxes_RejectBeforeAnySurfaceIntersection()+ {+ var source = FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/crossing-face-holes-rejected.firmament");+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.False(built.IsSuccess);+ Assert.Contains(built.Diagnostics, d => d.Message.Contains("existing-hole-envelope-clearance", StringComparison.Ordinal));+ }+ [Fact]+ public void MixedRecessesOnUpright_AreAnalyticClosedAndHaveTheSameRemovedVolume()+ {+ var source = Source.Replace("Vertex2_Vertex3", "Vertex3_Vertex4", StringComparison.Ordinal).Replace("Point2(21mm, 15mm)", "Point2(13mm, 25mm)", StringComparison.Ordinal);+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.True(built.IsSuccess, string.Join(";", built.Diagnostics.Select(d => d.Message)));+ CheckVolume(built.Value.RuntimeBody!, 4020 - 49.875 * Math.PI);+ var imported = Step242Importer.ImportBody(built.Value.StepText);+ Assert.True(imported.IsSuccess); CheckVolume(imported.Value, 4020 - 49.875 * Math.PI);+ }+ [Fact]+ public void MultipleHolesOnBothBracketLegs_KeepIndependentSupportExclusions()+ {+ var source = Source[..Source.LastIndexOf(" }", StringComparison.Ordinal)] + "Hole<Shaft> UprightA { On: face(bracket.Side(\"profile:section.Outer.Vertex3_Vertex4\")); Center: Point2(10mm,10mm); Diameter: 6mm; End: ThroughAll } Hole<Shaft> UprightB { On: face(bracket.Side(\"profile:section.Outer.Vertex3_Vertex4\")); Center: Point2(10mm,25mm); Diameter: 6mm; End: ThroughAll } } }";+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.True(built.IsSuccess, string.Join(";", built.Diagnostics.Select(d => d.Message)));+ CheckVolume(built.Value.RuntimeBody!, 4020 - (49.875 + 54) * Math.PI);+ var upright = built.Value.RuntimeCorrespondence!.Descendants.Single(d => d.Face is not null && d.FirmamentSelector?.Contains("Vertex3_Vertex4", StringComparison.Ordinal) == true);+ Assert.Equal(2, PlanarFaceThroughHole.Support(built.Value.RuntimeBody!, upright.Face!.Value)!.ExcludedDisks.Count);+ }+ [Fact]+ public void ThreeSeparatedVariants_RetainTheSupportFrameAndInnerLoops_AndRoundTrip()+ {+ var built = FirmamentBuildAndExport.CompileSource(Source);+ Assert.True(built.IsSuccess, string.Join(";", built.Diagnostics.Select(d => d.Message)));+ var body = built.Value.RuntimeBody!;+ var map = new GeometrySourceMap(built.Value.RuntimeCorrespondence!);+ var frame = built.Value.RuntimeCorrespondence!.Descendants.Where(d => d.Face is not null && d.FirmamentSelector?.Contains("Vertex2_Vertex3", StringComparison.Ordinal) == true)+ .Select(d => PlanarFaceThroughHole.Support(body, d.Face!.Value)).Single();+ Assert.NotNull(frame); Assert.Equal(new double[] { 3, -20, 3 }, frame.Origin);+ Assert.Equal(new double[] { 1, 0, 0 }, frame.X); Assert.Equal(new double[] { 0, 1, 0 }, frame.Y);+ Assert.Equal(new double[] { 2, 3.5, 3.5 }, frame.ExcludedDisks.Select(d => d.Radius).ToArray());+ Assert.Equal(3, built.Value.RuntimeCorrespondence.Descendants.Count(d => d.Role == SemanticTopologyRole.HoleEntryLoop));+ var imported = Step242Importer.ImportBody(built.Value.StepText);+ Assert.True(imported.IsSuccess, string.Join(";", imported.Diagnostics.Select(d => d.Message)));+ foreach (var result in new[] { body, imported.Value }) CheckVolume(result, 4020 - 49.875 * Math.PI);+ }++ [Theory]+ [InlineData(0d, false)]+ [InlineData(4.9d, false)]+ [InlineData(5d, false)]+ [InlineData(5.005d, false)]+ [InlineData(5.02d, true)]+ public void RepeatedShafts_RejectOverlapTangencyAndSlivers(double distance, bool admitted)+ {+ var start = Source[..Source.IndexOf(" Modify", StringComparison.Ordinal)];+ var source = start + FormattableString.Invariant($"Modify bracket {{ Hole<Shaft> A {{ On: face(bracket.Side(\"profile:section.Outer.Vertex2_Vertex3\")); Center: Point2(8mm,8mm); Diameter: 5mm; End: ThroughAll }} Hole<Shaft> B {{ On: face(bracket.Side(\"profile:section.Outer.Vertex2_Vertex3\")); Center: Point2({8 + distance}mm,8mm); Diameter: 5mm; End: ThroughAll }} }} }}");+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.Equal(admitted, built.IsSuccess);+ if (admitted) CheckVolume(built.Value.RuntimeBody!, 4020 - 37.5 * Math.PI);+ else Assert.Contains(built.Diagnostics, d => d.Message.Contains("clearance", StringComparison.Ordinal));+ }++ [Fact]+ public void DiagonalDisks_AreAdmittedEvenWhenTheirAxisAlignedBoundsOverlap()+ {+ var start = Source[..Source.IndexOf(" Modify", StringComparison.Ordinal)];+ var source = start + "Modify bracket { Hole<Shaft> A { On: face(bracket.Side(\"profile:section.Outer.Vertex2_Vertex3\")); Center: Point2(8mm,8mm); Diameter: 5mm; End: ThroughAll } Hole<Shaft> B { On: face(bracket.Side(\"profile:section.Outer.Vertex2_Vertex3\")); Center: Point2(12mm,12mm); Diameter: 5mm; End: ThroughAll } } }";+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.True(built.IsSuccess, string.Join(";", built.Diagnostics.Select(d => d.Message)));+ CheckVolume(built.Value.RuntimeBody!, 4020 - 37.5 * Math.PI);+ }++ [Theory]+ [InlineData("Point2(13mm, 10mm)", "Point2(10mm, 5mm)")]+ [InlineData("Point2(21mm, 15mm)", "Point2(18mm, 10mm)")]+ public void RecessFootprints_RejectEvenWhenTheShaftsWouldFit(string before, string after)+ {+ var built = FirmamentBuildAndExport.CompileSource(Source.Replace(before, after, StringComparison.Ordinal));+ Assert.False(built.IsSuccess);+ Assert.Contains(built.Diagnostics, d => d.Message.Contains("clearance", StringComparison.Ordinal));+ }++ [Theory]+ [InlineData("CounterboreDepth: 1mm", "CounterboreDepth: 0mm")]+ [InlineData("CounterboreDepth: 1mm", "CounterboreDepth: 3mm")]+ [InlineData("CounterboreDepth: 1mm", "CounterboreDepth: 2.995mm")]+ [InlineData("CounterboreDiameter: 7mm", "CounterboreDiameter: 4mm")]+ [InlineData("CountersinkAngle: 90deg", "CountersinkAngle: 0deg")]+ [InlineData("CountersinkDiameter: 7mm", "CountersinkDiameter: 12mm")]+ public void DegenerateRecesses_RejectBeforeTopologyConstruction(string before, string after)+ {+ var built = FirmamentBuildAndExport.CompileSource(Source.Replace(before, after, StringComparison.Ordinal));+ Assert.False(built.IsSuccess);+ Assert.Contains(built.Diagnostics, d => d.Message.Contains("compose-face-hole:", StringComparison.Ordinal));+ }++ private static void CheckVolume(BrepBody body, double expected)+ {+ var mass = BrepMassProperties.Evaluate(body);+ Assert.True(mass.IsEnclosed); Assert.True(mass.IsOrientationConsistent);+ Assert.InRange(Math.Abs(mass.AbsoluteVolume - expected), 0, Math.Max(mass.ErrorBound ?? 0, 1e-6));+ }+}diff --git a/Aetheris.Kernel.Firmament.Tests/OrientedComposeShaftHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/OrientedComposeShaftHoleTests.csnew file mode 100644index 00000000..4d3c1517--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/OrientedComposeShaftHoleTests.cs@@ -0,0 +1,64 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Verification;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Step242;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class OrientedComposeShaftHoleTests+{+ private static string Source => FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament");++ [Theory]+ [InlineData("XY", 0d, 0d, 1d)]+ [InlineData("XZ", 0d, -1d, 0d)]+ [InlineData("YZ", 1d, 0d, 0d)]+ public void LocalTopThroughShaft_PreservesBodyFrameVolumeAndHoleCorrespondence(string plane, double x, double y, double z)+ {+ var result = FirmamentBuildAndExport.CompileSource(Source.Replace("on XZ", $"on {plane}", StringComparison.Ordinal));+ Assert.True(result.IsSuccess, string.Join(" | ", result.Diagnostics.Select(d => d.Message)));+ var body = Assert.IsType<BrepBody>(result.Value.RuntimeBody);+ Check(body, new Vector3D(x, y, z));+ Assert.Contains(result.Value.RuntimeCorrespondence!.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);+ Assert.Contains(result.Value.RuntimeCorrespondence.Descendants, d => d.Role == SemanticTopologyRole.HoleEntryLoop);+ Assert.Contains(result.Value.RuntimeCorrespondence.Descendants, d => d.Role == SemanticTopologyRole.HoleExitLoop);+ var imported = Step242Importer.ImportBody(result.Value.StepText);+ Assert.True(imported.IsSuccess, string.Join(" | ", imported.Diagnostics.Select(d => d.Message)));+ Check(imported.Value, new Vector3D(x, y, z));+ }++ [Fact]+ public void ALocalHoleThatSplitsTheThinLeg_IsRejected()+ {+ var result = FirmamentBuildAndExport.CompileSource(Source.Replace("diameter: 2mm", "diameter: 6mm", StringComparison.Ordinal));+ Assert.False(result.IsSuccess);+ Assert.Contains(result.Diagnostics, d => d.Message.Contains("compose-rejected:disconnected-3d-solid", StringComparison.Ordinal));+ }++ [Theory]+ [InlineData("on: +Z", "on: -Z")]+ [InlineData("end: ThroughAll", "end: Blind 5mm")]+ [InlineData("Hole<Shaft>", "Hole<Counterbore>")]+ public void OtherSupportAdapters_RemainExplicitlyUnqualified(string before, string after)+ {+ var result = FirmamentBuildAndExport.CompileSource(Source.Replace(before, after, StringComparison.Ordinal));+ Assert.False(result.IsSuccess);+ Assert.Contains(result.Diagnostics, d => d.Message.Contains("compose-oriented-feature-not-admitted", StringComparison.Ordinal));+ }++ private static void Check(BrepBody body, Vector3D expectedAxis)+ {+ var cylinders = body.Geometry.Surfaces.Select(s => s.Value).Where(s => s.Cylinder is not null).Select(s => s.Cylinder!.Value).ToArray();+ Assert.NotEmpty(cylinders);+ Assert.All(cylinders, cylinder => {+ Assert.Equal(1d, cylinder.Radius, 9);+ Assert.InRange((cylinder.Axis.ToVector() - expectedAxis).Length, 0d, 1e-9d);+ });+ var mass = BrepMassProperties.Evaluate(body);+ Assert.True(mass.IsEnclosed);+ Assert.True(mass.IsOrientationConsistent);+ var expectedVolume = 4020d - Math.PI * 20d;+ Assert.InRange(Math.Abs(mass.AbsoluteVolume - expectedVolume), 0d, Math.Max(mass.ErrorBound ?? 0d, 1e-6d));+ }+}diff --git a/Aetheris.Kernel.Firmament.Tests/PlanarFaceThroughHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/PlanarFaceThroughHoleTests.csnew file mode 100644index 00000000..e0499f88--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/PlanarFaceThroughHoleTests.cs@@ -0,0 +1,42 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Verification;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Step242;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class PlanarFaceThroughHoleTests+{+ [Theory]+ [InlineData(16d, -10d, 6d, true)]+ [InlineData(6d, -10d, 6d, false)] // Tangent to the upright: no zero-width wall.+ [InlineData(16d, -2d, 6d, false)]+ public void BracketFoot_PreservesSourceFrameAndBuildsExactThroughCavity(double x, double y, double diameter, bool admitted)+ {+ var fixture = FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament");+ var original = fixture[..fixture.IndexOf(" Modify", StringComparison.Ordinal)] + "}";+ var baseline = FirmamentBuildAndExport.CompileSource(original);+ Assert.True(baseline.IsSuccess, string.Join(";", baseline.Diagnostics.Select(d => d.Message)));+ var host = baseline.Value.RuntimeBody!;+ _ = new GeometrySourceMap(baseline.Value.RuntimeCorrespondence!);+ var target = baseline.Value.RuntimeCorrespondence!.Descendants.Where(d => d.Face is not null && d.FirmamentSelector is not null)+ .Select(d => (Descendant: d, Frame: PlanarFaceThroughHole.Support(host, d.Face!.Value)))+ .Single(d => d.Frame is not null && d.Frame.Normal[2] > .99 && Math.Abs(d.Frame.Origin[2] - 3d) < 1e-8);+ var frame = target.Frame!; var p = new Point3D(x, y, 3d); var relative = p - new Point3D(frame.Origin[0], frame.Origin[1], frame.Origin[2]);+ var u = relative.Dot(new(frame.X[0], frame.X[1], frame.X[2])); var v = relative.Dot(new(frame.Y[0], frame.Y[1], frame.Y[2]));+ var source = original[..original.LastIndexOf('}')] + FormattableString.Invariant($"Modify bracket {{ Hole<Shaft> Mount {{ On: {target.Descendant.FirmamentSelector}; Center: Point2({u}mm, {v}mm); Diameter: {diameter}mm; End: ThroughAll }} }} }}");+ var built = FirmamentBuildAndExport.CompileSource(source);+ Assert.Equal(admitted, built.IsSuccess);+ if (!admitted) { Assert.Contains(built.Diagnostics, d => d.Message.Contains("clearance", StringComparison.Ordinal)); return; }+ var cylinder = built.Value.RuntimeBody!.Geometry.Surfaces.Single(s => s.Value.Cylinder is not null).Value.Cylinder!.Value;+ Assert.InRange((cylinder.Origin - p).Length, 0d, 1e-8d);+ foreach (var body in new[] { built.Value.RuntimeBody!, Step242Importer.ImportBody(built.Value.StepText).Value })+ {+ var mass = BrepMassProperties.Evaluate(body);+ Assert.True(mass.IsEnclosed); Assert.True(mass.IsOrientationConsistent);+ Assert.InRange(Math.Abs(mass.AbsoluteVolume - (4020d - Math.PI * 9d * 3d)), 0, Math.Max(mass.ErrorBound ?? 0, 1e-6));+ }+ Assert.Contains(built.Value.RuntimeCorrespondence!.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);+ }+}diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.csindex 3ba3d92b..116c4464 100644--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs@@ -537,6 +537,12 @@ public static partial class FirmamentBuildAndExportreturn KernelResult<FirmamentStepExportResult>.Failure(emitted.Diagnostics.Select(x => new Kernel.Core.Diagnostics.KernelDiagnostic(Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error, x, "FirmamentV2.ProfileComposition")).ToArray());if (ApplyConstructionPlaneBlindDrills(stack, emitted, out var drilled) is { } drillFailure) return drillFailure;emitted = drilled;+ foreach (var faceHole in stack.Feature.FaceHoles)+ {+ emitted = PlanarFaceThroughHole.Apply(emitted, faceHole);+ if (emitted.Body is null)+ return KernelResult<FirmamentStepExportResult>.Failure(emitted.Diagnostics.Select(x => new Kernel.Core.Diagnostics.KernelDiagnostic(Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error, x, "FirmamentV2.FaceHole")).ToArray());+ }if (materializerSource.Contains("EdgeFinish", StringComparison.Ordinal))return ExportComposedSemanticTopBoundaryChamfer(materializerSource, parsed, stack, emitted, v2Parse.Document);// The composition route either retained the checked body above or@@ -575,7 +581,17 @@ public static partial class FirmamentBuildAndExportif (materializerSource.Contains("EdgeFinish", StringComparison.Ordinal))return ExportProfileSemanticTopBoundaryChamfer(materializerSource, parsed.Profile, parsed.Height, emitted, v2Parse.DiagnosticSource);var step = Step242Exporter.ExportBody(emitted.Body); if (!step.IsSuccess) return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);- return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, parsed.Profile.Name, 0, "profile-extrude", "line-arc-profile"));+ var extrusionName = FirmamentV2Parser.MechanicalDeclarations(FirmamentSyntaxParser.Parse(materializerSource).Document.Statements)+ .FirstOrDefault(d => d.Type.Name.Text == "Extrude")?.Name?.Text ?? parsed.Profile.Name;+ var profileCorrespondence = emitted.Correspondence is not { } correspondence ? null : correspondence with {+ // The extrusion plan also carries overlapping edge roles for finish planners.+ // Publish its unique side-face owners here; edge picking remains unqualified.+ Descendants = correspondence.Descendants.Where(d => d.Role == SemanticTopologyRole.ExtrusionSideFace).Select(d => d.Face is { } id+ && PlanarFaceThroughHole.Support(emitted.Body, id) is not null+ ? d with { FirmamentSelector = $"face({extrusionName}.Side({System.Text.Json.JsonSerializer.Serialize(d.SourceStableId)}))", Addressability = SemanticTopologyAddressability.DerivedStable } : d).ToArray()+ };+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, parsed.Profile.Name, 0, "profile-extrude", "line-arc-profile") {+ RuntimeBody = emitted.Body, RuntimeCorrespondence = profileCorrespondence, RuntimeBodySourceName = extrusionName });}if (v2Parse.IsSuccess && v2Parse.Document is not null){@@ -3345,6 +3361,11 @@ public static partial class FirmamentBuildAndExportnull, "ProfileCompose.Center", null, null, "+Z", item.SourceSpan,"PrismaticSectionStack/VariableCircularCavity", "SemanticCountersinkProfile", "Countersink",SupportSpan: item.SupportSpan, ParentSupport: item.ParentSupport, SupportBoundaryMargin: item.SupportBoundaryMargin)))+ .Concat(feature.FaceHoles.Select(item => new FirmamentHoleFeatureReport(+ item.Name, $"Hole<{item.Variant}>", item.StableId, item.Diameter, item.X, item.Y,+ null, "PlanarFace.Center", null, null, $"face({feature.Name}.Side({System.Text.Json.JsonSerializer.Serialize(item.SupportSource)}))", null,+ "PlanarFaceThroughHole", "ConstructionSideSelector", item.Variant,+ SupportBoundaryMargin: PlanarFaceThroughHole.MinimumClearance))).Select(report =>{var surfaces = (correspondence?.Descendants ?? []).Where(d => d.SourceStableId == report.FeatureId && d.Face.HasValue)diff --git a/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.cs b/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.csindex 8606bd3d..7d06372e 100644--- a/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.cs+++ b/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.cs@@ -29,6 +29,7 @@ internal static class FirmamentFeatureAccountingvar receipts = feature.Operations.Where(o => active.Contains(o.Name) && o.SemanticFeatureId is null).Select(o => new FirmamentFeatureReceipt(feature.Name, o.SemanticFeatureKind ?? o.Intent.ToString(), o.Name));receipts = receipts.Concat((feature.Bosses ?? []).Where(h => active.Contains(h.Name)).Select(h => new FirmamentFeatureReceipt(feature.Name, "Boss", h.Name)))+ .Concat(feature.FaceHoles.Where(h => realized.Contains(h.StableId)).Select(h => new FirmamentFeatureReceipt(feature.Name, "Hole", h.Name))).Concat((feature.Pockets ?? []).Where(h => active.Contains(h.Name)).Select(h => new FirmamentFeatureReceipt(feature.Name, "Pocket", h.Name))).Concat((feature.MaterialOffsets ?? []).Where(h => active.Contains(h.Name)).Select(h => new FirmamentFeatureReceipt(feature.Name, h.OperationKind + "Offset", h.Name))).Concat(feature.AllSlotProfiles.Where(h => realized.Contains(h.StableId)).Select(h => new FirmamentFeatureReceipt(feature.Name, "Slot", h.Name)))diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.csindex 013979c4..539774a1 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs@@ -73,7 +73,7 @@ public static class EllipsoidSemanticDeclaration { }public static class PolyhedronSemanticDeclaration { }[FirmamentConstruct("Hole", "Hole", Context = "Modify body", Entry = "Modify Body { Hole<Shaft> H { On: +Z; Center: Point2(0mm, 0mm); Diameter: 6mm; End: ThroughAll } }", Description = "Semantic drilled hole.")]-[FirmamentField("On", "On", FirmamentSchemaValueKind.FaceSelector, Required = true, Choices = ["+Z", "-Z"], Description = "Entry face. Top/+Z and bottom/-Z are admitted on Box, Extrude and Compose stock. Other selectors require their specific supported body lane. Center X/Y are coordinates in this face's local frame, not screen coordinates.")]+[FirmamentField("On", "On", FirmamentSchemaValueKind.FaceSelector, Required = true, Choices = ["+Z", "-Z"], Description = "Entry face. On an oriented Extrude or Compose, +Z is the Profile's local extrusion axis; only a Shaft with ThroughAll is admitted there. Source Side faces also support separated through shafts, counterbores and countersinks, with circular openings retained as clearance exclusions. Center X/Y are local support coordinates, not screen coordinates.")][FirmamentField("Center", "Center", FirmamentSchemaValueKind.Point, Required = true, Description = "Center in the support face.")][FirmamentField("Diameter", "Diameter", FirmamentSchemaValueKind.Length, Required = true, Description = "Shaft diameter.", SourceEditable = true, ProjectionMember = nameof(ProjectDiameter))][FirmamentField("End", "End", FirmamentSchemaValueKind.String, Required = true, Choices = ["ThroughAll", "Blind(5mm)"], Description = "ThroughAll cuts through the body. Blind(5mm) cuts to a finite depth; edit the expression for another depth.")]diff --git a/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs b/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.csnew file mode 100644index 00000000..19218bfb--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs@@ -0,0 +1,242 @@+using Aetheris.Kernel.Core.Brep;+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.Topology;++namespace Aetheris.Kernel.Firmament.Materializer;++/// <summary>Exact, construction-owned planar support; shared by browser placement and feature admission.</summary>+public sealed record PlanarSupportDisk(double[] Center, double Radius);+public sealed record PlanarFaceSupport(double[] Origin, double[] X, double[] Y, double[] Normal, double[][] Boundary,+ IReadOnlyList<PlanarSupportDisk> ExcludedDisks);+/// <summary>Construction-owned finite cavity envelope; radius bounds its entire recess and shaft.</summary>+public sealed record PlanarHoleCavity(string StableId, Point3D Mouth, Vector3D Axis, double Depth, double Radius, IReadOnlyList<FaceId> WallFaces);++public static class PlanarFaceThroughHole+{+ public const double MinimumClearance = .01;+ private const double Tol = 1e-7;+ public static PlanarFaceSupport? Support(BrepBody body, FaceId id)+ {+ var face = body.Topology.Faces.SingleOrDefault(f => f.Id == id);+ if (face is null || face.LoopIds.Count == 0 || !body.TryGetFaceSurface(id, out var surface) || surface?.Plane is not { } plane+ || !body.Bindings.TryGetFaceBinding(id, out var binding)) return null;+ var normal = plane.Normal.ToVector() * (binding.Orientation.IsAlignedWithSurface ? 1d : -1d);+ // A support frame must survive the plain-Extrude -> Compose lowering.+ // Surface UV axes are emitter details and can swap at that boundary.+ var reference = Math.Abs(normal.X) < .9d ? new Vector3D(1, 0, 0) : new Vector3D(0, 1, 0);+ var x = Direction3D.Create(reference - normal * reference.Dot(normal)).ToVector(); var y = normal.Cross(x);+ var loop = body.Topology.Loops.Single(l => l.Id == face.LoopIds[0]);+ var points = new List<Point3D>();+ foreach (var cid in loop.CoedgeIds)+ {+ var coedge = body.Topology.Coedges.Single(c => c.Id == cid);+ var edge = body.Topology.Edges.Single(e => e.Id == coedge.EdgeId);+ if (!body.Bindings.TryGetEdgeBinding(edge.Id, out var eb) || !body.Geometry.TryGetCurve(eb.CurveGeometryId, out var curve) || curve?.Kind != CurveGeometryKind.Line3) return null;+ if (!body.TryGetVertexPoint(coedge.IsReversed ? edge.EndVertexId : edge.StartVertexId, out var p)) return null;+ points.Add(p);+ }+ var boundary = points.Select(p => new[] { (p - plane.Origin).Dot(x), (p - plane.Origin).Dot(y) }).ToArray();+ if (boundary.Length < 3) return null;+ var minU = boundary.Min(p => p[0]); var minV = boundary.Min(p => p[1]);+ var origin = plane.Origin + x * minU + y * minV;+ boundary = boundary.Select(p => new[] { p[0] - minU, p[1] - minV }).ToArray();+ var area = boundary.Select((p, i) => p[0] * boundary[(i + 1) % boundary.Length][1] - p[1] * boundary[(i + 1) % boundary.Length][0]).Sum();+ if (area < 0d) Array.Reverse(boundary);+ // Convex supports give exact half-plane clearance; other trims fail closed.+ for (var i = 0; i < boundary.Length; i++)+ {+ var a = boundary[i]; var b = boundary[(i + 1) % boundary.Length];+ if (boundary.Any(p => (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]) < -Tol)) return null;+ }+ var excluded = new List<PlanarSupportDisk>();+ foreach (var inner in face.LoopIds.Skip(1))+ {+ Circle3Curve? circle = null; var sweep = 0d;+ foreach (var cid in body.Topology.Loops.Single(l => l.Id == inner).CoedgeIds)+ {+ var edge = body.Topology.Coedges.Single(c => c.Id == cid).EdgeId;+ if (!body.Bindings.TryGetEdgeBinding(edge, out var eb) || !body.Geometry.TryGetCurve(eb.CurveGeometryId, out var curve)+ || curve?.Circle3 is not { } arc || eb.TrimInterval is not { } trim) return null;+ if (Math.Abs(Math.Abs(arc.Normal.ToVector().Dot(normal)) - 1d) > Tol || Math.Abs((arc.Center - origin).Dot(normal)) > Tol) return null;+ if (circle is { } previous && ((arc.Center - previous.Center).Length > Tol || Math.Abs(arc.Radius - previous.Radius) > Tol)) return null;+ circle = arc; sweep += Math.Abs(trim.End - trim.Start);+ }+ if (circle is not { } hole || Math.Abs(sweep - 2 * Math.PI) > Tol) return null;+ var offset = hole.Center - origin;+ excluded.Add(new([offset.Dot(x), offset.Dot(y)], hole.Radius));+ }+ double[] V(Vector3D v) => [v.X, v.Y, v.Z];+ return new([origin.X, origin.Y, origin.Z], V(x), V(y), V(normal), boundary, excluded);+ }++ private static bool Contains(PlanarFaceSupport frame, Point3D center, double radius)+ {+ var relative = center - P(frame.Origin); var u = relative.Dot(V(frame.X)); var v = relative.Dot(V(frame.Y));+ for (var i = 0; i < frame.Boundary.Length; i++)+ {+ var a = frame.Boundary[i]; var b = frame.Boundary[(i + 1) % frame.Boundary.Length]; var dx = b[0] - a[0]; var dy = b[1] - a[1];+ if ((dx * (v - a[1]) - dy * (u - a[0])) / Math.Sqrt(dx * dx + dy * dy) < radius + MinimumClearance - Tol) return false;+ }+ return frame.ExcludedDisks.All(d => Math.Sqrt(Math.Pow(u - d.Center[0], 2) + Math.Pow(v - d.Center[1], 2)) >= radius + d.Radius + MinimumClearance - Tol);+ }+ private static Vector3D V(double[] v) => new(v[0], v[1], v[2]);+ private static Point3D P(double[] v) => new(v[0], v[1], v[2]);+ private static bool EnvelopesSeparated(Point3D a, Vector3D az, double ad, double ar, Point3D b, Vector3D bz, double bd, double br)+ {+ static double C(Point3D p, int i) => i == 0 ? p.X : i == 1 ? p.Y : p.Z;+ static double V(Vector3D p, int i) => i == 0 ? p.X : i == 1 ? p.Y : p.Z;+ return Enumerable.Range(0, 3).Any(i => {+ var ae = ar * Math.Sqrt(Math.Max(0d, 1d - Math.Pow(V(az, i), 2))); var be = br * Math.Sqrt(Math.Max(0d, 1d - Math.Pow(V(bz, i), 2)));+ return Math.Max(C(a, i), C(a + az * ad, i)) + ae + MinimumClearance < Math.Min(C(b, i), C(b + bz * bd, i)) - be+ || Math.Max(C(b, i), C(b + bz * bd, i)) + be + MinimumClearance < Math.Min(C(a, i), C(a + az * ad, i)) - ae;+ });+ }++ /// <summary>Insert a cylindrical cavity between two proven planar supports. No guessed face IDs or Boolean tools.</summary>+ public static PrismaticSectionStackEmissionResult Apply(PrismaticSectionStackEmissionResult emitted, PrismaticFaceHoleFeature hole)+ {+ PrismaticSectionStackEmissionResult Fail(string reason) => new(null, emitted.Plan, emitted.Diagnostics.Append($"compose-face-hole:{hole.Name}:{reason}").ToArray());+ var source = emitted.Plan?.TopologyPlan; var body = emitted.Body;+ if (source is null || body is null) return Fail("missing-host-plan");+ var matches = source.FaceMappings.Where(m => m.SourceStableId == hole.SupportSource && m.Kind is "PrismaticSide" or "HostFaceReplacement").ToArray();+ if (matches.Length != 1) return Fail("support-must-resolve-to-one-construction-face");+ var entryId = matches[0].FaceId; var entry = Support(body, entryId);+ if (entry is null) return Fail("support-requires-a-convex-planar-face-with-straight-boundaries");+ var normal = V(entry.Normal); var axis = -normal; var radius = hole.Diameter / 2d;+ var outerRadius = hole.Variant == "Shaft" ? radius : (hole.RecessDiameter ?? double.NaN) / 2d;+ if (!double.IsFinite(radius) || radius < MinimumClearance || !double.IsFinite(outerRadius)+ || hole.Variant != "Shaft" && outerRadius - radius < MinimumClearance) return Fail("invalid-shaft-or-recess-diameter");+ var mouth = P(entry.Origin) + V(entry.X) * hole.X + V(entry.Y) * hole.Y;+ if (!double.IsFinite(hole.X) || !double.IsFinite(hole.Y) || !Contains(entry, mouth, outerRadius)) return Fail("entry-or-existing-hole-clearance-must-be-at-least-0.01mm");+ var exits = body.Topology.Faces.Where(f => f.Id != entryId).Select(f => (f.Id, Frame: Support(body, f.Id)))+ .Where(f => f.Frame is not null && V(f.Frame.Normal).Dot(normal) < -1d + 1e-7)+ .Select(f => (f.Id, Frame: f.Frame!, Depth: (P(f.Frame!.Origin) - mouth).Dot(axis)))+ .Where(f => f.Depth > MinimumClearance && Contains(f.Frame, mouth + axis * f.Depth, radius)).OrderBy(f => f.Depth).ToArray();+ if (exits.Length == 0) return Fail("no-contained-parallel-exit-support");+ var exit = exits[0]; var end = mouth + axis * exit.Depth;+ var recessDepth = 0d;+ if (hole.Variant == "Counterbore") recessDepth = hole.RecessDepth ?? double.NaN;+ if (hole.Variant == "Countersink")+ {+ var angle = hole.AngleDegrees ?? double.NaN;+ if (!double.IsFinite(angle) || angle <= 0 || angle >= 180) return Fail("countersink-angle-must-be-between-0-and-180deg");+ recessDepth = (outerRadius - radius) / Math.Tan(angle * Math.PI / 360d);+ }+ if (!double.IsFinite(recessDepth) || hole.Variant != "Shaft" && (recessDepth < MinimumClearance || exit.Depth - recessDepth < MinimumClearance))+ return Fail("recess-depth-must-leave-at-least-0.01mm-of-shaft");+ var clearedWalls = new HashSet<FaceId>();+ foreach (var cavity in source.FaceHoleCavities)+ {+ var parallel = Math.Abs(axis.Dot(cavity.Axis)) > 1d - Tol;+ var offset = cavity.Mouth - mouth; var along = offset.Dot(axis);+ var radialDistance = (offset - axis * along).Length;+ var oldEnd = along + cavity.Depth * cavity.Axis.Dot(axis);+ var separated = parallel && (Math.Max(along, oldEnd) < -MinimumClearance || Math.Min(along, oldEnd) > exit.Depth + MinimumClearance+ || radialDistance >= outerRadius + cavity.Radius + MinimumClearance - Tol);+ if (!separated && !EnvelopesSeparated(mouth, axis, exit.Depth, outerRadius, cavity.Mouth, cavity.Axis, cavity.Depth, cavity.Radius))+ return Fail("existing-hole-envelope-clearance-must-be-at-least-0.01mm");+ clearedWalls.UnionWith(cavity.WallFaces);+ }+ // Conservative corridor proof. Reject any intervening face whose bounds overlap the finite tool bounds.+ // This also refuses existing cavities or nonplanar interactions instead of silently cutting through them.+ foreach (var face in body.Topology.Faces.Where(f => f.Id != entryId && f.Id != exit.Id && !clearedWalls.Contains(f.Id)))+ {+ var edgeIds = face.LoopIds.SelectMany(l => body.Topology.Loops.Single(t => t.Id == l).CoedgeIds)+ .Select(c => body.Topology.Coedges.Single(t => t.Id == c).EdgeId).Distinct()+ .ToArray();+ var bounds = new List<Point3D>();+ foreach (var id in edgeIds)+ {+ var edge = body.Topology.Edges.Single(t => t.Id == id);+ if (!body.Bindings.TryGetEdgeBinding(id, out var binding) || !body.Geometry.TryGetCurve(binding.CurveGeometryId, out var curve)) return Fail("missing-corridor-edge-geometry");+ bounds.Add(source.VertexPoints[edge.StartVertexId]); bounds.Add(source.VertexPoints[edge.EndVertexId]);+ if (curve?.Circle3 is { } circle)+ {+ var n = circle.Normal.ToVector();+ var extent = new Vector3D(circle.Radius * Math.Sqrt(Math.Max(0d, 1d - n.X * n.X)), circle.Radius * Math.Sqrt(Math.Max(0d, 1d - n.Y * n.Y)), circle.Radius * Math.Sqrt(Math.Max(0d, 1d - n.Z * n.Z)));+ bounds.Add(circle.Center + extent); bounds.Add(circle.Center - extent);+ }+ else if (curve?.Kind != CurveGeometryKind.Line3) return Fail("unsupported-corridor-edge-geometry");+ }+ var separated = Enumerable.Range(0, 3).Any(i => {+ double C(Point3D p) => i == 0 ? p.X : i == 1 ? p.Y : p.Z;+ var n = i == 0 ? normal.X : i == 1 ? normal.Y : normal.Z;+ var extent = outerRadius * Math.Sqrt(Math.Max(0d, 1d - n * n));+ return bounds.Max(C) < Math.Min(C(mouth), C(end)) - extent - MinimumClearance || bounds.Min(C) > Math.Max(C(mouth), C(end)) + extent + MinimumClearance;+ });+ if (!separated) return Fail("tool-corridor-interaction-not-admitted");+ }+ var excluded = new[] { entryId, exit.Id }; var topology = new TopologyModel(); var geometry = new BrepGeometryStore(); var bindings = new BrepBindingModel();+ foreach (var v in source.Topology.Vertices) topology.AddVertex(v);+ foreach (var e in source.Topology.Edges) topology.AddEdge(e);+ foreach (var c in source.Topology.Coedges) topology.AddCoedge(c);+ foreach (var l in source.Topology.Loops) topology.AddLoop(l);+ foreach (var f in source.Topology.Faces.Where(f => !excluded.Contains(f.Id))) topology.AddFace(f);+ foreach (var c in source.Geometry.Curves) geometry.AddCurve(c.Key, c.Value);+ foreach (var s in source.Geometry.Surfaces) geometry.AddSurface(s.Key, s.Value);+ foreach (var e in source.Bindings.EdgeBindings) bindings.AddEdgeBinding(e);+ foreach (var f in source.Bindings.FaceBindings.Where(f => !excluded.Contains(f.FaceId))) bindings.AddFaceBinding(f);+ var points = source.VertexPoints.ToDictionary(p => p.Key, p => p.Value);+ var vi = topology.Vertices.Max(v => v.Id.Value) + 1; var ei = topology.Edges.Max(e => e.Id.Value) + 1;+ var ci = topology.Coedges.Max(c => c.Id.Value) + 1; var li = topology.Loops.Max(l => l.Id.Value) + 1;+ var fi = source.Topology.Faces.Max(f => f.Id.Value) + 1; var gi = geometry.Curves.Max(c => c.Key.Value) + 1; var si = geometry.Surfaces.Max(s => s.Key.Value) + 1;+ VertexId Vertex(Point3D p) { var id = new VertexId(vi++); topology.AddVertex(new Vertex(id)); points[id] = p; return id; }+ EdgeId Edge(VertexId a, VertexId b, CurveGeometry curve, ParameterInterval trim) { var id = new EdgeId(ei++); var gid = new CurveGeometryId(gi++); topology.AddEdge(new Edge(id, a, b)); geometry.AddCurve(gid, curve); bindings.AddEdgeBinding(new(id, gid, trim, true)); return id; }+ LoopId Loop(params (EdgeId Edge, bool Reverse)[] uses) { var id = new LoopId(li++); var ids = uses.Select(_ => new CoedgeId(ci++)).ToArray(); for (var i = 0; i < ids.Length; i++) topology.AddCoedge(new(ids[i], uses[i].Edge, id, ids[(i + 1) % ids.Length], ids[(i + ids.Length - 1) % ids.Length], uses[i].Reverse)); topology.AddLoop(new(id, ids)); return id; }+ FaceId Face(IReadOnlyList<LoopId> loops, SurfaceGeometry surface, bool sense) { var id = new FaceId(fi++); var sid = new SurfaceGeometryId(si++); topology.AddFace(new(id, loops)); geometry.AddSurface(sid, surface); bindings.AddFaceBinding(new(id, sid, sense)); return id; }+ var radial = V(entry.X); var z = Direction3D.Create(normal); var x = Direction3D.Create(radial);+ (VertexId Start, EdgeId A, EdgeId B) Ring(double station, double r)+ {+ var center = mouth + axis * station; var a = Vertex(center + radial * r); var b = Vertex(center - radial * r);+ var circle = CurveGeometry.FromCircle(new Circle3Curve(center, z, r, x));+ return (a, Edge(a, b, circle, new(0, Math.PI)), Edge(b, a, circle, new(Math.PI, 2 * Math.PI)));+ }+ var mouthRing = Ring(0d, outerRadius); var endRing = Ring(exit.Depth, radius);+ var entryLoop = Loop((mouthRing.B, true), (mouthRing.A, true)); var exitLoop = Loop((endRing.A, false), (endRing.B, false));+ FaceId Replace(FaceId id, LoopId loop) { var f = source.Topology.Faces.Single(f => f.Id == id); var binding = source.Bindings.FaceBindings.Single(b => b.FaceId == id); return Face(f.LoopIds.Concat([loop]).ToArray(), source.Geometry.Surfaces.Single(s => s.Key == binding.SurfaceGeometryId).Value, binding.Orientation.IsAlignedWithSurface); }+ var entryFace = Replace(entryId, entryLoop); var exitFace = Replace(exit.Id, exitLoop);+ var cavityFaces = new List<FaceId>(); var cavityDescendants = new List<SemanticTopologyDescendant>();+ void Wall((VertexId Start, EdgeId A, EdgeId B) top, (VertexId Start, EdgeId A, EdgeId B) bottom, SurfaceGeometry surface, SemanticTopologyRole role)+ {+ var delta = points[bottom.Start] - points[top.Start];+ var seam = Edge(top.Start, bottom.Start, CurveGeometry.FromLine(new Line3Curve(points[top.Start], Direction3D.Create(delta))), new(0, delta.Length));+ var loop = Loop((top.A, false), (top.B, false), (seam, false), (bottom.B, true), (bottom.A, true), (seam, true));+ var face = Face([loop], surface, false); cavityFaces.Add(face);+ cavityDescendants.Add(new($"{hole.StableId}:wall:{role}", "Face", role, hole.StableId, Face: face, ParentStableId: hole.StableId));+ }+ var shaftStart = mouthRing; var shaftStation = 0d;+ if (hole.Variant == "Counterbore")+ {+ var recessRing = Ring(recessDepth, outerRadius); shaftStart = Ring(recessDepth, radius); shaftStation = recessDepth;+ Wall(mouthRing, recessRing, SurfaceGeometry.FromCylinder(new CylinderSurface(mouth, z, outerRadius, x)), SemanticTopologyRole.HoleCounterboreWallFace);+ var outerLoop = Loop((recessRing.A, false), (recessRing.B, false)); var innerLoop = Loop((shaftStart.B, true), (shaftStart.A, true));+ var shoulder = Face([outerLoop, innerLoop], SurfaceGeometry.FromPlane(new PlaneSurface(mouth + axis * recessDepth, z, x)), true);+ cavityFaces.Add(shoulder);+ cavityDescendants.Add(new($"{hole.StableId}:shoulder", "Face", SemanticTopologyRole.HoleCounterboreShoulderFace, hole.StableId, Face: shoulder, ParentStableId: hole.StableId));+ }+ if (hole.Variant == "Countersink")+ {+ shaftStart = Ring(recessDepth, radius); shaftStation = recessDepth;+ var halfAngle = hole.AngleDegrees!.Value * Math.PI / 360d;+ var apex = mouth + axis * (outerRadius / Math.Tan(halfAngle));+ Wall(mouthRing, shaftStart, SurfaceGeometry.FromCone(new ConeSurface(apex, z, halfAngle, x)), SemanticTopologyRole.HoleCountersinkWallFace);+ }+ Wall(shaftStart, endRing, SurfaceGeometry.FromCylinder(new CylinderSurface(mouth + axis * shaftStation, z, radius, x)), SemanticTopologyRole.HoleWallFace);+ var shell = source.Topology.Shells.Single(); topology.AddShell(new(shell.Id, shell.FaceIds.Where(f => !excluded.Contains(f)).Concat([entryFace, exitFace]).Concat(cavityFaces).ToArray()));+ var oldBody = source.Topology.Bodies.Single(); topology.AddBody(new(oldBody.Id, oldBody.ShellIds));+ var correspondence = new SemanticTopologyCorrespondence(source.Correspondence.BodyStableId,+ source.Correspondence.Descendants.Select(item => item.Face == entryId ? item with { Face = entryFace } : item.Face == exit.Id ? item with { Face = exitFace } : item).Concat(new SemanticTopologyDescendant[] {+ new($"{hole.StableId}:entry", "Loop", SemanticTopologyRole.HoleEntryLoop, hole.StableId, Loop: entryLoop, ParentStableId: hole.StableId),+ new($"{hole.StableId}:exit", "Loop", SemanticTopologyRole.HoleExitLoop, hole.StableId, Loop: exitLoop, ParentStableId: hole.StableId)+ }).Concat(cavityDescendants).ToArray(), source.Provenance.Concat(["PlanarFaceThroughHole", "PositiveEntryExitClearance", "SeparatedCavityEnvelopes", "ConservativeFiniteCorridor"]).ToArray());+ var mappings = source.FaceMappings.Select(m => m.FaceId == entryId ? m with { FaceId = entryFace, Kind = "HostFaceReplacement" } : m.FaceId == exit.Id ? m with { FaceId = exitFace, Kind = "HostFaceReplacement" } : m).ToArray();+ var plan = new PrismaticSectionStackTopologyPlan(source.StableId, topology, geometry, bindings, points, mappings, correspondence, correspondence.ProvenanceChain)+ { FaceHoleCavities = source.FaceHoleCavities.Append(new(hole.StableId, mouth, axis, exit.Depth, outerRadius, cavityFaces)).ToArray() };+ var materialized = PrismaticSectionStackBrepMaterializer.TryMaterialize(plan);+ if (materialized.Body is null) return Fail(string.Join(";", materialized.Diagnostics));+ return new(materialized.Body, emitted.Plan! with { TopologyPlan = plan, Correspondence = correspondence, Vertices = points.Count, Edges = topology.Edges.Count(), Faces = topology.Faces.Count() }, emitted.Diagnostics, correspondence);+ }+}diff --git a/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs b/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.csindex 16e4751c..94018b1e 100644--- a/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs+++ b/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs@@ -167,11 +167,14 @@ public sealed record PrismaticProfileCompositionFeature({/// <summary>Set when the body is declared hollow; normalization derives the cavity from the exterior.</summary>public PrismaticHollowIntent? Hollow { get; init; }+ public IReadOnlyList<PrismaticFaceHoleFeature> FaceHoles { get; init; } = [];public IEnumerable<(string Name, string StableId, string ProfileReference)> AllSlotProfiles =>(CapsuleSlots ?? []).Select(x => (x.Name, x.StableId, x.ProfileReference)).Concat((RoundedRectangleSlots ?? []).Select(x => (x.Name, x.StableId, x.ProfileReference)));}+public sealed record PrismaticFaceHoleFeature(string Name, string StableId, string SupportSource, double X, double Y, double Diameter,+ string Variant = "Shaft", double? RecessDiameter = null, double? RecessDepth = null, double? AngleDegrees = null);public sealed record PrismaticSectionRegion(ResolvedProfile2D Outer, IReadOnlyList<ResolvedProfile2D> Holes, IReadOnlyList<string> Provenance);public sealed record PrismaticSectionSlab(@@ -419,11 +422,13 @@ public static class PrismaticProfileCompositionParser&& !SameFrame(stockProfile.EffectiveConstructionPlane, ConstructionPlane.WorldXY)){placement = placement with { ProfileConstructionPlane = stockProfile.EffectiveConstructionPlane };- // These adapters bind supports in world coordinates. Do not let them- // reinterpret a local +Z selector as world +Z on an oriented body.+ // Axial shaft cuts are local 2D profile removals: the section-stack+ // emitter transports the hole and host together into this frame.+ // Other adapters still bind world supports and must fail closed.foreach (var dependent in operationsSyntax.Document.Statements.OfType<DeclarationSyntax>()- .Where(d => d.Type.Name.Text is "Boss" or "Pocket" or "Hole" or "Slot" or "EdgeFinish"))- diagnostics.Add($"compose-oriented-feature-not-admitted:{dependent.Type.Name.Text}:{dependent.Name?.Text}: Oriented Compose currently admits Base/Add/Remove in one common Profile frame; this feature's support adapter requires world XY.");+ .Where(d => d.Type.Name.Text is "Boss" or "Pocket" or "Hole" or "Slot" or "EdgeFinish")+ .Where(d => !IsAdmittedOrientedHole(d, compose.Name.Text)))+ diagnostics.Add($"compose-oriented-feature-not-admitted:{dependent.Type.Name.Text}:{dependent.Name?.Text}: Oriented Compose admits Base/Add/Remove, local +Z through shafts, and separated through shafts/counterbores/countersinks on qualified source Side faces; this feature needs another support adapter.");}if (stock is not null){@@ -640,6 +645,7 @@ public static class PrismaticProfileCompositionParser}}var shaftHoles = new List<PrismaticShaftHoleFeature>();+ var faceHoles = new List<PrismaticFaceHoleFeature>();var counterboreHoles = new List<PrismaticCounterboreHoleFeature>();var countersinkHoles = new List<PrismaticCountersinkHoleFeature>();var constructionPlaneBlindDrills = new List<PrismaticConstructionPlaneBlindDrillFeature>();@@ -694,13 +700,26 @@ public static class PrismaticProfileCompositionParservar diameter = ReadFeatureField(fields, composeBody, HoleDiameter, "Diameter"); var end = ReadFeatureField(fields, composeBody, HoleEnd, "End"); var role = ReadFeatureField(fields, composeBody, HoleRole, "Role");var counterboreDiameter = ReadFeatureField(fields, composeBody, HoleCounterboreDiameter, "CounterboreDiameter"); var counterboreDepth = ReadFeatureField(fields, composeBody, HoleCounterboreDepth, "CounterboreDepth"); var onExpression = fields.Take("On");var onName = FirmamentV2Parser.MechanicalFaceAxis(onExpression, compose.Name.Text) ?? FirmamentSyntaxValues.Reference(onExpression);+ var sideSource = SideSource(onExpression, compose.Name.Text);var on = HoleOn.Match("On: " + onName);- if (onExpression is not null && (!on.Success || on.Groups["face"].Value != onName))+ if (sideSource is null && onExpression is not null && (!on.Success || on.Groups["face"].Value != onName))diagnostics.Add($"compose-hole-support-invalid:{name}: Use a host face or an admitted Span<Plane>.");var from = ReadFeatureField(fields, composeBody, HoleFrom, "From"); var depthEnd = ReadFeatureField(fields, composeBody, HoleDepthEnd, "End"); var termination = ReadFeatureField(fields, composeBody, HoleTermination, "Termination");var countersinkDiameter = fields.Number("CountersinkDiameter", "mm");var countersinkAngle = fields.Number("CountersinkAngle", "deg");fields.Complete();+ if (sideSource is not null)+ {+ if (schemaVariant is not ("Shaft" or "Counterbore" or "Countersink") || from.Success || !center.Success || !diameter.Success+ || !end.Success || !string.Equals(end.Groups["end"].Value, "ThroughAll", StringComparison.OrdinalIgnoreCase)+ || !double.IsFinite(N(diameter, "d")) || N(diameter, "d") <= 0d)+ diagnostics.Add($"compose-face-hole-contract:{name}: A planar side supports Shaft, Counterbore or Countersink with a positive diameter and End: ThroughAll.");+ else if (!names.Add(name)) diagnostics.Add($"compose-duplicate-operation:{name}");+ else faceHoles.Add(new(name, $"hole:{compose.Name.Text}.{name}", sideSource, N(center, "x"), N(center, "y"), N(diameter, "d"), schemaVariant,+ schemaVariant == "Counterbore" ? counterboreDiameter.Success ? N(counterboreDiameter, "d") : null : countersinkDiameter,+ counterboreDepth.Success ? N(counterboreDepth, "d") : null, countersinkAngle));+ continue;+ }if (from.Success){if (Regex.IsMatch(body, @"\bTermination\s*:\s*Flat", RegexOptions.CultureInvariant | RegexOptions.IgnoreCase))@@ -907,10 +926,29 @@ public static class PrismaticProfileCompositionParserdiagnostics.Add($"compose-profile-frame-mismatch:{operation.Name}:{operation.ProfileReference}: All operands must use the same construction frame; an explicit Placement cannot override an oriented Profile.");}var levels = operations.SelectMany(o => new[] { o.From, o.To }).Concat(countersinkHoles.Select(h => h.ConeFrom)).Distinct().Order().ToArray();- var feature = diagnostics.Count == 0 ? new PrismaticProfileCompositionFeature(compose.Name.Text, placement.ProfilePlane, placement.Axis, placement, operations, levels, "parser-backed-scaffold-profile-composition", shaftHoles, capsuleSlots, roundedRectangleSlots, constructionPlaneBlindDrills, counterboreHoles, bosses, pockets, materialOffsets, countersinkHoles) { Hollow = hollow } : null;+ var feature = diagnostics.Count == 0 ? new PrismaticProfileCompositionFeature(compose.Name.Text, placement.ProfilePlane, placement.Axis, placement, operations, levels, "parser-backed-scaffold-profile-composition", shaftHoles, capsuleSlots, roundedRectangleSlots, constructionPlaneBlindDrills, counterboreHoles, bosses, pockets, materialOffsets, countersinkHoles) { Hollow = hollow, FaceHoles = faceHoles } : null;return new(feature, profiles, diagnostics.Distinct().ToArray(), expansion.Evidence);}+ private static bool IsAdmittedOrientedHole(DeclarationSyntax declaration, string bodyName)+ {+ if (declaration.Type.Name.Text != "Hole" || declaration.Body is null) return false;+ var variant = FirmamentSyntaxValues.Reference(declaration.Type.Arguments.FirstOrDefault()?.Value);+ var fields = declaration.Body.Statements.OfType<FieldSyntax>().ToArray();+ return !fields.Any(f => FirmamentSyntaxFields.SameField(f.Name.Text, "From"))+ && fields.Any(f => FirmamentSyntaxFields.SameField(f.Name.Text, "On") && (string.Equals(variant, "Shaft", StringComparison.OrdinalIgnoreCase) && FirmamentV2Parser.MechanicalFaceAxis(f.Value, bodyName) == "+Z"+ || SideSource(f.Value, bodyName) is not null && new[] { "Shaft", "Counterbore", "Countersink" }.Contains(variant, StringComparer.OrdinalIgnoreCase)))+ && fields.Any(f => FirmamentSyntaxFields.SameField(f.Name.Text, "End") && FirmamentSyntaxValues.Reference(f.Value) == "ThroughAll");+ }+ private static string? SideSource(ExpressionSyntax? expression, string bodyName)+ {+ if (expression is not CallSyntax face || FirmamentSyntaxValues.Reference(face.Target) != "face" || face.Arguments.Count != 1+ || face.Arguments[0].Value is not CallSyntax side || side.Target is not MemberSyntax member+ || FirmamentSyntaxValues.Reference(member.Target) != bodyName || member.Member.Text != "Side" || side.Arguments.Count != 1+ || side.Arguments[0].Value is not LiteralSyntax literal || !literal.Raw.StartsWith('"')) return null;+ return System.Text.Json.JsonSerializer.Deserialize<string>(literal.Raw);+ }+private static bool SameFrame(ConstructionPlane left, ConstructionPlane right)=> (left.Origin - right.Origin).LengthSquared < 1e-20&& (left.AxisX.ToVector() - right.AxisX.ToVector()).LengthSquared < 1e-20diff --git a/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs b/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.csindex bff58cf6..493fc57d 100644--- a/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs+++ b/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs@@ -20,7 +20,10 @@ public sealed record PrismaticSectionStackFacePlanMapping(public sealed record PrismaticSectionStackTopologyPlan(string StableId, TopologyModel Topology, BrepGeometryStore Geometry, BrepBindingModel Bindings,IReadOnlyDictionary<VertexId, Point3D> VertexPoints, IReadOnlyList<PrismaticSectionStackFacePlanMapping> FaceMappings,- SemanticTopologyCorrespondence Correspondence, IReadOnlyList<string> Provenance);+ SemanticTopologyCorrespondence Correspondence, IReadOnlyList<string> Provenance)+{+ public IReadOnlyList<PlanarHoleCavity> FaceHoleCavities { get; init; } = [];+}public sealed record PrismaticSectionStackBrepPlan(string Signature, int Vertices, int Edges, int Faces, string Policy, bool Authoritative,SemanticTopologyCorrespondence? Correspondence = null, PrismaticSectionStackTopologyPlan? TopologyPlan = null);@@ -367,7 +370,10 @@ public static class PrismaticSectionStackEmitterif (Math.Abs(z - side.To) <= Tol && topLevels.TryGetValue(profile, out var topLevel) && Math.Abs(z - topLevel) <= Tol) descendants.Add(new($"plan:{stack.Feature.Name}:{side.Construction}:edge:{edge.Id.Value}:top", "Edge", SemanticTopologyRole.TopBoundary, side.Source, Edge: edge.Id, ParentStableId: side.Construction));if (Math.Abs(z - side.From) <= Tol && bottomLevels.TryGetValue(profile, out var bottomLevel) && Math.Abs(z - bottomLevel) <= Tol) descendants.Add(new($"plan:{stack.Feature.Name}:{side.Construction}:edge:{edge.Id.Value}:bottom", "Edge", SemanticTopologyRole.BottomBoundary, side.Source, Edge: edge.Id, ParentStableId: side.Construction));}- descendants.Add(new($"plan:{stack.Feature.Name}:{side.Construction}:face:{face.Value}", "Face", SemanticTopologyRole.ExtrusionSideFace, side.Source, Face: face, ParentStableId: side.Construction));+ var selector = sideFaces.Count(s => s.Source == side.Source) == 1 && geometry.Surfaces.Any(s => s.Key == bindings.FaceBindings.Single(b => b.FaceId == face).SurfaceGeometryId && s.Value.Plane is not null)+ ? $"face({stack.Feature.Name}.Side({System.Text.Json.JsonSerializer.Serialize(side.Source)}))" : null;+ descendants.Add(new($"plan:{stack.Feature.Name}:{side.Construction}:face:{face.Value}", "Face", SemanticTopologyRole.ExtrusionSideFace, side.Source, Face: face, ParentStableId: side.Construction,+ FirmamentSelector: selector, Addressability: selector is null ? SemanticTopologyAddressability.RuntimeOnly : SemanticTopologyAddressability.DerivedStable));}foreach (var fragment in stack.Slabs.Where(s => s.Arrangement is not null).SelectMany(s => s.Arrangement!.AtomicFragments)){diff --git a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.csindex 6cd5f76d..dcc5115f 100644--- a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs+++ b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs@@ -7,7 +7,7 @@ using Aetheris.Semantics;namespace Aetheris.Kernel.Firmament.Materializer;/// <summary>Stable roles assigned while an authoritative plan is materialized. These are not geometric queries.</summary>-public enum SemanticTopologyRole { Unknown, ProfileVertex, VerticalExtrusionEdge, LocalStartBoundary, LocalEndBoundary, LocalStartCapLoop, LocalEndCapLoop, TopBoundary, BottomBoundary, ExtrusionSideFace, TopFaceBoundaryLoop, BottomFaceBoundaryLoop, HoleEntryLoop, HoleExitLoop, HoleWallFace, HoleShaftToDrillPointLoop, HoleShaftToDrillPointEdge, HoleDrillPointFace, HoleTipVertex, HoleCounterboreMouthLoop, HoleCounterboreWallFace, HoleCounterboreShoulderLoop, HoleCounterboreShaftWallFace, SlotEntryLoop, SlotExitLoop, SlotWallFace, SlotStraightWallFace, SlotEndWallFace, ComposeTransition, EdgeFinishReplacementFace, FilletSurface, ConvexJunctionPatch, ReflexJunctionPatch, CapContactEdge, SideContactEdge, JunctionToRollA, JunctionToRollB, JunctionCapContact, JunctionSideAContact, JunctionSideBContact, StartTerminationFace, EndTerminationFace, StartEndpointArc, EndEndpointArc, RetainedStartSharpEdge, RetainedEndSharpEdge, BoxFace, BoxEdge, ThreadRootFace, ThreadLeadingFlank, ThreadTrailingFlank, ThreadCrest, ThreadStartCap, ThreadEndCap, ThreadBoundaryEdge, HoleCountersinkWallFace, PathFeatureFace }+public enum SemanticTopologyRole { Unknown, ProfileVertex, VerticalExtrusionEdge, LocalStartBoundary, LocalEndBoundary, LocalStartCapLoop, LocalEndCapLoop, TopBoundary, BottomBoundary, ExtrusionSideFace, TopFaceBoundaryLoop, BottomFaceBoundaryLoop, HoleEntryLoop, HoleExitLoop, HoleWallFace, HoleShaftToDrillPointLoop, HoleShaftToDrillPointEdge, HoleDrillPointFace, HoleTipVertex, HoleCounterboreMouthLoop, HoleCounterboreWallFace, HoleCounterboreShoulderLoop, HoleCounterboreShaftWallFace, SlotEntryLoop, SlotExitLoop, SlotWallFace, SlotStraightWallFace, SlotEndWallFace, ComposeTransition, EdgeFinishReplacementFace, FilletSurface, ConvexJunctionPatch, ReflexJunctionPatch, CapContactEdge, SideContactEdge, JunctionToRollA, JunctionToRollB, JunctionCapContact, JunctionSideAContact, JunctionSideBContact, StartTerminationFace, EndTerminationFace, StartEndpointArc, EndEndpointArc, RetainedStartSharpEdge, RetainedEndSharpEdge, BoxFace, BoxEdge, ThreadRootFace, ThreadLeadingFlank, ThreadTrailingFlank, ThreadCrest, ThreadStartCap, ThreadEndCap, ThreadBoundaryEdge, HoleCountersinkWallFace, PathFeatureFace, HoleCounterboreShoulderFace }public enum SemanticTopologyAddressability { AuthoredStable, DerivedStable, ImportedStable, RuntimeOnly, Ambiguous, Unstable }public enum SemanticSelectionRequirement { ExactlyOne, OneOrMore, ConnectedChain, ClosedLoop, NonEmptyFaceSet }public enum SemanticSelectionFailure { None, SemanticSourceNotFound, NoMaterializedDescendants, AmbiguousBodyContext, SelectionCardinalityMismatch, DescendantsNotConnected, DescendantsBranch, DescendantsDoNotClose, MixedBoundaryRoles, UnsupportedTopologyChange, SelectionConsumerMismatch }diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.csindex 6ae21739..0a0f158f 100644--- a/Aetheris.Web.Runtime/Program.cs+++ b/Aetheris.Web.Runtime/Program.cs@@ -885,6 +885,8 @@ internal static class WebMeshBuildersourceAddressability = imported is not null ? "ImportedStable" : semanticFace?.Addressability.ToString() ?? "RuntimeOnly",selector = imported is not null ? $"{importedBodyName}.face(\"#{imported}\")" : semanticFace?.FirmamentSelector,surfaceKind = surface?.Kind.ToString(), diameterMm = surface?.Cylinder is { } cylinder ? (double?)(2 * cylinder.Radius) : null,+ support = semanticFace?.FirmamentSelector?.Contains(".Side(", StringComparison.Ordinal) == true+ ? Aetheris.Kernel.Firmament.Materializer.PlanarFaceThroughHole.Support(body, face.FaceId) : null,selectorReason = imported is not null ? null : semanticFace is null ? "No compiler-owned source topology mapping is available for this display face.": semanticFace.FirmamentSelector is null ? "Construction identity is known, but Firmament has no qualified source selector for this topology." : null,source = semanticFace is null ? null : faceSource, buildRevision });diff --git a/Aetheris.Web.Runtime/sdk/src/index.d.ts b/Aetheris.Web.Runtime/sdk/src/index.d.tsindex 41ea1500..a1f18915 100644--- a/Aetheris.Web.Runtime/sdk/src/index.d.ts+++ b/Aetheris.Web.Runtime/sdk/src/index.d.ts@@ -32,6 +32,9 @@ export interface PmiDisplayAnnotation {}export interface MeshRange { readonly surfaceKind?: string | null; readonly diameterMm?: number | null }export interface SelectionDescription { readonly surfaceKind?: string | null; readonly diameterMm?: number | null }+export interface PlanarFaceSupport { readonly origin: readonly number[]; readonly x: readonly number[]; readonly y: readonly number[]; readonly normal: readonly number[]; readonly boundary: readonly (readonly number[])[]; readonly excludedDisks?: readonly { readonly center: readonly number[]; readonly radius: number }[] }+export interface SelectionDescription { readonly support?: PlanarFaceSupport | null }+export interface MeshRange { readonly support?: PlanarFaceSupport | null }export interface DisplayMesh { readonly importedAsset?: { readonly path: string; readonly sha256: string; readonly evidence: string; readonly qualification: { readonly status: string; readonly geometryStatus: string } | null } | null }export interface ChangeSet { readonly changedEntityIds: readonly string[]; readonly addedEntityIds: readonly string[]; readonly removedEntityIds: readonly string[]; readonly meshChanged: boolean; readonly diagnosticsChanged: boolean }export interface RebuildResult { readonly success: boolean; readonly revision: number; readonly diagnostics: readonly Diagnostic[]; readonly retainedPreviousGeometry: boolean; readonly changes?: ChangeSet }diff --git a/Aetheris.Web.Runtime/sdk/src/index.js b/Aetheris.Web.Runtime/sdk/src/index.jsindex 9cf40cd5..02d81d45 100644--- a/Aetheris.Web.Runtime/sdk/src/index.js+++ b/Aetheris.Web.Runtime/sdk/src/index.js@@ -212,6 +212,7 @@ export class ModelSession {semanticTopologyId: range.semanticTopologyId ?? null, topologyKind: range.topologyKind ?? 'Face', outputRole: range.outputRole ?? null, originFeature: range.originFeature ?? null,selector: range.selector ?? null, sourceAddressability: range.sourceAddressability ?? 'RuntimeOnly',surfaceKind: range.surfaceKind ?? null, diameterMm: range.diameterMm ?? null,+ support: occurrence.transform.every((v, i) => Math.abs(v - (i % 5 === 0 ? 1 : 0)) < 1e-9) ? range.support ?? null : null,selectorReason: range.selectorReason ?? null, source: range.source ?? null, buildRevision: range.buildRevision ?? this.revision } : null;}describeSelection(definitionId, triangleIndex, occurrenceId) {diff --git a/docs/development/reports/2026-11/helios-face-hole-placement.md b/docs/development/reports/2026-11/helios-face-hole-placement.mdnew file mode 100644index 00000000..be6df988--- /dev/null+++ b/docs/development/reports/2026-11/helios-face-hole-placement.md@@ -0,0 +1,58 @@+# Helios face-based mounting-hole placement++The Simple Bracket foot now accepts a 6 mm Shaft through its 3 mm thickness,+normal to the selected broad face. The original XZ Profile and extrusion remain+authored source. The fixture is+`fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmament`.++Extrusion construction correspondence publishes a source-owned Side selector.+The plain extrusion and its later composition use the same outward-normal,+projected world-axis frame and lower local bounds origin. This is independent+of each emitter's surface UV axes. The browser receives that exact frame and+convex boundary, rather than guessing a support from tessellation or face IDs.++The feature planner proves positive circular clearance at the selected entry+and a parallel exit. A conservative finite cylinder bound rejects other face+interactions. It replaces the two host faces with trimmed faces and directly+wires one cylindrical wall into their existing shell. No internal caps or+Boolean body replacement are introduced. Construction provenance remains in+the plan and correspondence.++Helios supports face-first Add hole and tool-first click-to-place, gold ring+dragging, exact Center fields, automatic preview, cancellation and one source+transaction on Apply. Dragging projects the full disk inside the convex support+with a 0.01 mm margin. Typed out-of-bounds centers and nonpositive diameters+disable Apply. New input invalidates an admitted candidate immediately; stale+asynchronous results are disposed. Camera gestures remain available. Shift or+right drag controls the camera while the tool is active.++Three native cases qualify exact world placement, closed/oriented volume+`4020 - 27*pi` mm³, STEP reimport, and tangent/out-of-bounds refusals. The+complete Firmament suite passes 3,484 tests with DOTNET_PROCESSOR_COUNT=2.+All 247 Helios unit tests pass. The UI regression passes through real WebGPU+and WebGL: face selection, placement, constrained drag, exact edits, Cancel,+source download, STEP export, native CLI validation and Undo.+All 14 graph authoring workflows also pass against the production AOT frontend;+the runtime request assertion verifies use of the native AOT WASM resource.+The frontend and final solution build succeed. The production native WASM is+60,309,213 bytes, SHA-256+`463606e40ee623c798c5bf7dc07384f1bba9f6e7e688716a4def814e38d72cf2`.++The first full parallel solution attempt reports 14 failures: ten Core, two+Firmament, one CLI and one EditableV8. They include execution-budget failures+and the previously observed two NIST audit hash mismatches. The complete+affected suite passes in the bounded run above. Full-suite logs and any later+qualification results are under `artifacts/local/face-placement-*`.+A final bounded parallel attempt passes all 760 CLI tests but still reports+two Core NIST audit mismatches, an EditableV8 timing failure and three+measurement-test failures in Geometry/Server. All three measurement cases pass+in a subsequent focused run without code changes. This is not a claim that+the full solution gate passes.++Scope is a simple Shaft with ThroughAll on a uniquely resolved convex planar+extrusion side with straight outer boundaries and a clear finite corridor.+Other trims, an existing inner loop, ambiguous split supports, rotated assembly+occurrences, blind holes, counterbores and countersinks are not qualified for+this placement path. Other feature tools retain their existing interactions.+The conservative corridor may refuse geometry that a future exact intersection+adapter could prove safe. Refusal preserves source and the accepted model.diff --git a/docs/development/reports/2026-11/helios-multiple-face-holes.md b/docs/development/reports/2026-11/helios-multiple-face-holes.mdnew file mode 100644index 00000000..abef90e9--- /dev/null+++ b/docs/development/reports/2026-11/helios-multiple-face-holes.md@@ -0,0 +1,74 @@+# Multiple face holes and recess placement in Helios++The original Simple Bracket supports multiple separated Shaft, Counterbore and+Countersink features on its planar foot and upright. The fixture is+`fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament`.+It contains three different holes on the same face; the browser regression+authors four holes through the actual graph controls and exports their source+and STEP.++The support frame is derived from the retained outer loop, so adding circular+inner loops does not shift its origin or axes. Existing openings are published+as excluded disks in that frame. The browser chooses the nearest feasible+center from exact 2D line/circle projections and boundary intersections. This+avoids local iterative projection failures in narrow feasible regions. A small+rounding allowance keeps dragged positions above the compiler clearance floor.+Numeric edits are not silently moved; invalid coordinates disable Apply.++The compiler requires 0.01 mm clearance at boundaries and existing openings.+Counterbores and countersinks reserve their outer diameters. Each completed+feature retains a construction-owned finite cylindrical envelope and its cavity+face IDs. Parallel envelopes use radial/axial separation; nonparallel envelopes+must have separated bounds. Crossing envelopes reject without a surface/surface+intersection. Diagonally separated circles pass even if their axis-aligned+bounds overlap. Unowned curved corridor boundaries use analytic circle bounds,+not just endpoint bounds; unsupported curve kinds reject.++The topology planner retains every previous inner loop and directly inserts+shaft/recess rings, cylindrical or conical walls, and an annular counterbore+shoulder in the same shell. It does not introduce internal caps or Boolean+operations. Source selectors, existing hole identities and construction+correspondence are retained. Hole reports now include this support path, so+these features also appear in the compiled model browser.++Twenty-one focused native cases pass: multiple variants on one face, both+bracket legs, recesses on the upright, exact volume and STEP reimport, fixed+support frames, safe diagonal placement, overlap/tangency/sliver refusals,+recess footprint collisions, invalid depths/angles and crossing drill axes.+The mixed three-hole fixture removes exactly `49.875*pi` mm³. The separate+crossing-axis fixture is intentionally rejected by the cavity envelope guard.++All 250 Helios unit tests pass. The real UI regression passes in both WebGPU and+WebGL: multiple holes, counterbore and countersink placement, drag collision+guards, exact-coordinate refusal, Cancel, source/STEP downloads, CLI Built+validation, Undo and Redo. Production AOT qualification is recorded under+`artifacts/local/multi-face-hole-*` alongside all raw logs.++The full solution build passed. Its parallel test attempt passed 3,500 affected+Firmament tests and all 760 CLI tests but retained five failures: two known NIST+audit snapshots in Core, plus one measurement case each in Geometry and Server,+and one EditableV8 geometry-reference mismatch. A later focused test build overlapped+the running test host and hit a Windows DLL lock; it was rerun after the test+host exited and passed. The final affected suite includes two additional native+cases beyond that initial full-solution attempt. No execution budgets or audit+baselines were changed.+The final complete affected suite passes all 3,502 tests. Geometry and Server+measurement cases also pass in a focused rerun without code changes.+The EditableV8 mismatch was independently reproduced on a clean, isolated+checkout of the original `664ebb6d3c9502f5eba6cad0122d4269f6ec29f9` baseline:+`IntakeRetainer1 positions[306]` expects approximately zero and gets+`6.549348885785214` in both trees. It predates all local changes; its reference+was not rewritten. The baseline log is `multi-face-hole-baseline-audit.log`.++All 15 production graph workflows pass against the final AOT frontend. The+native runtime is 60,350,599 bytes with SHA-256+`87882ce0d37b90f8a4c4cc949e72a7885f29061d81b619813c2bed6a9fda9997`.++Limits: convex straight outer boundaries, complete circular inner openings,+uniquely resolved source Side supports, parallel contained exit, and ThroughAll.+Recesses must have positive shoulders/cone depths and leave at least 0.01 mm of+shaft depth. Full-depth envelopes use each feature's largest radius, which is+deliberately conservative for opposite-side or crossing recesses. Noncircular+trims, coplanar planning seams, blind side holes, imported/unmapped supports and+rotated assembly occurrences remain outside this path. Rejected previews leave+source and the accepted geometry intact.diff --git a/docs/development/reports/2026-11/oriented-shaft-holes-helios.md b/docs/development/reports/2026-11/oriented-shaft-holes-helios.mdnew file mode 100644index 00000000..a15956f9--- /dev/null+++ b/docs/development/reports/2026-11/oriented-shaft-holes-helios.md@@ -0,0 +1,54 @@+# Oriented through-shaft holes in the Helios graph++Helios Simple Bracket retained its XZ Profile and 20 mm extrusion. At the current+master baseline, adding `Hole<Shaft>` through the graph reached the compiler and+was refused with `compose-oriented-feature-not-admitted`. The orientation guard+also rejected a simple axial shaft cut that the local section-stack emitter can+transport with its host.++The parser now admits only a Shaft on local +Z (including its existing Top+aliases), terminated with ThroughAll, through that guard. It still rejects the+other oriented feature adapters. The section arrangement, materialization,+manifold checks, and source correspondence remain the existing owners.++The regression fixture is+`fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament`.+At local center (1.5, 20) mm and diameter 2 mm it drills through the 20 mm+extrusion. Native tests cover XY, XZ, and YZ, exact volume+`4020 - 20*pi` mm³, closed orientation-consistent material, the cylinder's world+axis, semantic entry/exit/wall ownership, and STEP reimport. Seven focused cases+pass; a 6 mm cut at that center rejects because it separates the narrow leg.++The Helios graph regression authors the feature only through form controls,+Preview and Apply, downloads its source and STEP, checks the original bracket+bounds and closed shell, and validates the downloaded source through the CLI.+The standalone CLI `analyze volume` command currently defers this oriented+curved shell; exact-volume evidence comes from BRepMassProperties in the native+regression instead. Helios also explains why Apply is disabled before Preview.++Reproduce with the source-built browser SDK and+`playwright test --config playwright.graph.config.ts --grep "Simple Bracket accepts"`.+Native focused checks use+`dotnet test Aetheris.Kernel.Firmament.Tests -c Release --filter FullyQualifiedName~OrientedComposeShaftHoleTests`.+Raw baseline, build and full-suite logs remain under `artifacts/local/oriented-shaft-*`.++The complete affected Firmament suite passes 3,481 tests with+`DOTNET_PROCESSOR_COUNT=2`; the seven new focused cases are included. Helios's+244 unit tests pass as well. All 13 Helios graph authoring tests pass against+the production AOT frontend, including the new bracket case with+`HELIOS_GRAPH_REQUIRE_AOT=true` asserting an actual AOT native WASM request.++The full parallel solution suite was attempted with and without a competing AOT+build. It reports additional tessellation execution-budget failures and NIST+audit snapshot mismatches in unchanged code. These remain qualification limits;+this change does not adjust their budgets, baselines, or geometry. The idle+parallel attempt reports 15 failures: 11 Core, two Firmament, one CLI and one+EditableV8. The affected Firmament failures disappear in the complete bounded+process run above. This is not a claim that the unrestricted solution gate passes.+The unmodified Core NIST audit class separately reproduces two hash mismatches+among 17 cases. That test project has no dependency on the modified Firmament+project.++This capability drills along the extrusion axis. A mounting hole through a broad+bracket leg face, or another oriented support/termination/variant, requires its+own support adapter and is not established by these results.diff --git a/docs/public/reference/language/solids-and-features.md b/docs/public/reference/language/solids-and-features.mdindex 23f66b9d..73141aaf 100644--- a/docs/public/reference/language/solids-and-features.md+++ b/docs/public/reference/language/solids-and-features.md@@ -134,6 +134,33 @@ This bounded stack rejects arbitrary placements, mismatched joining radii, radia## Holes+On an Extrude or Compose in an oriented Profile frame, a simple `Hole<Shaft>`+with `on: +Z` and `end: ThroughAll` cuts along the Profile's local extrusion+axis. Center coordinates are in the Profile's own 2D frame. The host and hole+are transformed together; `+Z` does not mean world Z for an XZ or YZ sketch.+See the complete [oriented bracket example](../../../../fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament).+For a through hole normal to a planar extrusion side, use a construction-owned+`On: face(bracket.Side("profile:section.Outer.Vertex2_Vertex3"))` selector.+The selected side must resolve uniquely to a planar face with a convex straight+outer boundary and optional circular inner openings. Its frame uses the outward normal and a projected world-axis basis,+with its origin at the lower local bounds. Center coordinates and diameter must+leave at least 0.01 mm of clearance at entry, exit and existing holes. Multiple+holes retain the same support frame and selector. The finite cylinder corridor+must be clear of other faces. Ambiguous, noncircular, tangent or interacting+supports reject. See the complete [bracket mounting-hole example](../../../../fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmament).++These side supports also admit `Hole<Counterbore>` and `Hole<Countersink>` with+`End: ThroughAll`. Shaft diameter must be at least 0.02 mm. Outer diameter must+exceed shaft diameter by at least 0.02 mm.+Counterbore depth, or the countersink depth derived from diameter and angle,+must be at least 0.01 mm and leave at least 0.01 mm of shaft before the exit.+The largest radius reserves a full-depth cylindrical clearance envelope against+all earlier cavities. This deliberately rejects crossing envelopes instead of+performing surface/surface intersections. See the [multiple-hole bracket](../../../../fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament).++Blind terminations on these oriented side supports are not admitted. Hole cuts+that disconnect the remaining solid reject.+| Variant | Fields || --- | --- || `Hole<Shaft>` | `on`, `center`, `diameter`, `end` |diff --git a/fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmament b/fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmamentnew file mode 100644index 00000000..5f691e78--- /dev/null+++ b/fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmament@@ -0,0 +1,16 @@+// Starter model: a 30 x 40 mm angle bracket, 3 mm thick and 20 mm wide.+Model SimpleBracket {+ units: mm+ Concept Struct layout on XZ {+ Polygon2<Explicit> outline {+ points: [[0mm,0mm], [30mm,0mm], [30mm,3mm], [3mm,3mm], [3mm,40mm], [0mm,40mm]]+ }+ }+ Profile section using layout {+ Loop Outer { outline |> TraceLoop }+ }+ Extrude bracket { profile: section; from: 0mm; to: 20mm }+ Modify bracket {+ Hole<Shaft> Hole { On: face(bracket.Side("profile:section.Outer.Vertex2_Vertex3")) Center: Point2(13mm, 10mm) Diameter: 6mm End: ThroughAll }+ }+}diff --git a/fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament b/fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmamentnew file mode 100644index 00000000..3caafbd6--- /dev/null+++ b/fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament@@ -0,0 +1,27 @@+// Separated bores on the original bracket foot; dimensions are in its stable face frame.+Model SimpleBracket {+ units: mm+ Concept Struct layout on XZ {+ Polygon2<Explicit> outline {+ points: [[0mm,0mm], [30mm,0mm], [30mm,3mm], [3mm,3mm], [3mm,40mm], [0mm,40mm]]+ }+ }+ Profile section using layout { Loop Outer { outline |> TraceLoop } }+ Extrude bracket { profile: section; from: 0mm; to: 20mm }+ Modify bracket {+ Hole<Shaft> First {+ On: face(bracket.Side("profile:section.Outer.Vertex2_Vertex3"))+ Center: Point2(5mm, 5mm); Diameter: 4mm; End: ThroughAll+ }+ Hole<Counterbore> Second {+ On: face(bracket.Side("profile:section.Outer.Vertex2_Vertex3"))+ Center: Point2(13mm, 10mm); Diameter: 4mm+ CounterboreDiameter: 7mm; CounterboreDepth: 1mm; End: ThroughAll+ }+ Hole<Countersink> Third {+ On: face(bracket.Side("profile:section.Outer.Vertex2_Vertex3"))+ Center: Point2(21mm, 15mm); Diameter: 4mm+ CountersinkDiameter: 7mm; CountersinkAngle: 90deg; End: ThroughAll+ }+ }+}diff --git a/fixtures/Regression/OrientedComposeHoles/crossing-face-holes-rejected.firmament b/fixtures/Regression/OrientedComposeHoles/crossing-face-holes-rejected.firmamentnew file mode 100644index 00000000..32c6e6ea--- /dev/null+++ b/fixtures/Regression/OrientedComposeHoles/crossing-face-holes-rejected.firmament@@ -0,0 +1,15 @@+// Both shafts fit their entry and exit faces, but their finite cavities cross.+Model CrossingHoles {+ units: mm+ Concept Struct layout on XY {+ Polygon2<Explicit> outline {+ points: [[0mm,0mm], [20mm,0mm], [20mm,20mm], [10mm,20mm], [0mm,20mm], [0mm,10mm]]+ }+ }+ Profile section using layout { Loop Outer { outline |> TraceLoop } }+ Extrude stock { profile: section; from: 0mm; to: 20mm }+ Modify stock {+ Hole<Shaft> AcrossX { On: face(stock.Side("profile:section.Outer.Vertex1_Vertex2")); Center: Point2(5mm, 10mm); Diameter: 4mm; End: ThroughAll }+ Hole<Shaft> AcrossY { On: face(stock.Side("profile:section.Outer.Vertex3_Vertex4")); Center: Point2(5mm, 10mm); Diameter: 4mm; End: ThroughAll }+ }+}diff --git a/fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament b/fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmamentnew file mode 100644index 00000000..f106d3f7--- /dev/null+++ b/fixtures/Regression/OrientedComposeHoles/simple-bracket-through-hole.firmament@@ -0,0 +1,16 @@+// Helios Simple Bracket: unchanged 30 x 40 x 3 mm L section, 20 mm extrusion.+Model SimpleBracket {+ units: mm+ Concept Struct layout on XZ {+ Polygon2<Explicit> outline {+ points: [[0mm,0mm], [30mm,0mm], [30mm,3mm], [3mm,3mm], [3mm,40mm], [0mm,40mm]]+ }+ }+ Profile section using layout {+ Loop Outer { outline |> TraceLoop }+ }+ Extrude bracket { profile: section; from: 0mm; to: 20mm }+ Modify bracket {+ Hole<Shaft> Mount { on: +Z; center: Point2(1.5mm, 20mm); diameter: 2mm; end: ThroughAll }+ }+}