Skip to content

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.cs
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
index 3ba3d92b..116c4464 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -537,6 +537,12 @@ public static partial class FirmamentBuildAndExport
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.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 FirmamentBuildAndExport
if (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 FirmamentBuildAndExport
null, "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.cs
index 8606bd3d..7d06372e 100644
--- a/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentFeatureAccounting.cs
@@ -29,6 +29,7 @@ internal static class FirmamentFeatureAccounting
var 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.cs
index 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.cs
new file mode 100644
index 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.cs
index 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 PrismaticProfileCompositionParser
var 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 PrismaticProfileCompositionParser
diagnostics.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-20
diff --git a/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs b/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs
index 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 PrismaticSectionStackEmitter
if (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.cs
index 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.cs
index 6ae21739..0a0f158f 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -885,6 +885,8 @@ internal static class WebMeshBuilder
sourceAddressability = 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.ts
index 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.js
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.firmament
new file mode 100644
index 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.firmament
new file mode 100644
index 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.firmament
new file mode 100644
index 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.firmament
new file mode 100644
index 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 }
+ }
+}