Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Explain face-hole recess depth failures

Yuechen Li575e7ec22ff7
diff --git a/Aetheris.Kernel.Firmament.Tests/FaceRecessDirectionTests.cs b/Aetheris.Kernel.Firmament.Tests/FaceRecessDirectionTests.cs
new file mode 100644
index 00000000..82660e09
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FaceRecessDirectionTests.cs
@@ -0,0 +1,89 @@
+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.FirmamentV2;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FaceRecessDirectionTests
+{
+ private static string Original {
+ get {
+ var source = FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/bracket-foot-hole.firmament");
+ return source[..source.IndexOf(" Modify", StringComparison.Ordinal)] + "}";
+ }
+ }
+ [Theory]
+ [InlineData("Vertex2_Vertex3")]
+ [InlineData("Vertex3_Vertex4")]
+ [InlineData("Vertex5_Vertex0")]
+ public void RecessOpensOnPickedFace_AndExtendsInward_OnBothNormalSigns(string side)
+ {
+ var baseline = FirmamentBuildAndExport.CompileSource(Original).Value;
+ var target = baseline.RuntimeCorrespondence!.Descendants.Single(d => d.Face is not null && d.FirmamentSelector?.Contains(side, StringComparison.Ordinal) == true);
+ var frame = PlanarFaceThroughHole.Support(baseline.RuntimeBody!, target.Face!.Value)!;
+ var u = frame.Boundary.Average(p => p[0]); var v = frame.Boundary.Average(p => p[1]);
+ var normal = new Vector3D(frame.Normal[0], frame.Normal[1], frame.Normal[2]);
+ var mouth = new Point3D(frame.Origin[0], frame.Origin[1], frame.Origin[2])
+ + new Vector3D(frame.X[0], frame.X[1], frame.X[2]) * u + new Vector3D(frame.Y[0], frame.Y[1], frame.Y[2]) * v;
+ foreach (var variant in new[] { "Counterbore", "Countersink" })
+ {
+ var fields = variant == "Counterbore" ? "CounterboreDiameter: 7mm; CounterboreDepth: 1mm" : "CountersinkDiameter: 7mm; CountersinkAngle: 90deg";
+ var source = Original[..Original.LastIndexOf('}')] + FormattableString.Invariant($"Modify bracket {{ Hole<{variant}> Recess {{ On: {target.FirmamentSelector}; Center: Point2({u}mm, {v}mm); Diameter: 4mm; {fields}; End: ThroughAll }} }} }}");
+ var result = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(result.IsSuccess, string.Join(";", result.Diagnostics.Select(d => d.Message)));
+ var body = result.Value.RuntimeBody!; var correspondence = result.Value.RuntimeCorrespondence!;
+ var entryFace = correspondence.Descendants.Single(d => d.Face is not null && d.FirmamentSelector == target.FirmamentSelector);
+ var entry = PlanarFaceThroughHole.Support(body, entryFace.Face!.Value)!;
+ Assert.Equal(3.5, Assert.Single(entry.ExcludedDisks).Radius);
+ var exits = correspondence.Descendants.Where(d => d.Face is not null && d.FirmamentSelector is not null)
+ .Select(d => PlanarFaceThroughHole.Support(body, d.Face!.Value)).Where(f => f is not null && f.ExcludedDisks.Count == 1
+ && new Vector3D(f.Normal[0], f.Normal[1], f.Normal[2]).Dot(normal) < -.99).ToArray();
+ Assert.Equal(2d, Assert.Single(exits)!.ExcludedDisks[0].Radius);
+ var shaftFace = correspondence.Descendants.Single(d => d.Role == SemanticTopologyRole.HoleWallFace);
+ var shaft = body.GetFaceSurface(shaftFace.Face!.Value).Cylinder!.Value;
+ Assert.Equal(variant == "Counterbore" ? -1d : -1.5d, (shaft.Origin - mouth).Dot(normal), 8);
+ if (variant == "Counterbore") {
+ var shoulder = correspondence.Descendants.Single(d => d.Role == SemanticTopologyRole.HoleCounterboreShoulderFace);
+ Assert.Equal(-1d, (body.GetFaceSurface(shoulder.Face!.Value).Plane!.Value.Origin - mouth).Dot(normal), 8);
+ } else {
+ var cone = correspondence.Descendants.Single(d => d.Role == SemanticTopologyRole.HoleCountersinkWallFace);
+ Assert.True((body.GetFaceSurface(cone.Face!.Value).Cone!.Value.Apex - mouth).Dot(normal) < 0);
+ }
+ var imported = Step242Importer.ImportBody(result.Value.StepText); Assert.True(imported.IsSuccess);
+ foreach (var checkedBody in new[] { body, imported.Value }) {
+ var mass = BrepMassProperties.Evaluate(checkedBody);
+ Assert.True(mass.IsEnclosed); Assert.True(mass.IsOrientationConsistent);
+ Assert.InRange(Math.Abs(mass.AbsoluteVolume - (4020 - (variant == "Counterbore" ? 20.25 : 17.625) * Math.PI)), 0, Math.Max(mass.ErrorBound ?? 0, 1e-6));
+ }
+ }
+ }
+
+ [Fact]
+ public void FullThicknessCounterbore_ReportsOneActionableError()
+ {
+ var source = FirmamentCorpusHarness.ReadFixtureText("fixtures/Regression/OrientedComposeHoles/bracket-multiple-face-holes.firmament")
+ .Replace("CounterboreDepth: 1mm", "CounterboreDepth: 3mm", StringComparison.Ordinal);
+ var result = FirmamentBuildAndExport.CompileSource(source); Assert.False(result.IsSuccess);
+ var presented = FirmamentBuildAdmissionValidation.Present(Assert.Single(result.Diagnostics), "bracket.firmament", source);
+ Assert.Equal("compose-face-hole", presented.Code);
+ Assert.Contains("depth is 3 mm", presented.Message); Assert.Contains("face has 3 mm", presented.Message);
+ Assert.Contains("2.99 mm", presented.Message); Assert.Contains("Reduce CounterboreDepth", presented.Message);
+ Assert.DoesNotContain("authoritative-section-stack", presented.Message);
+ }
+
+ [Theory]
+ [InlineData("counterbore")]
+ [InlineData("countersink")]
+ public void PaletteDefaults_FitTheThreeMillimeterUpright(string id)
+ {
+ var item = FirmamentLanguagePaletteService.Palette().Items.Single(i => i.Id == id);
+ var feature = item.Source.Replace("On: +Z", "On: face(bracket.Side(\"profile:section.Outer.Vertex3_Vertex4\"))", StringComparison.Ordinal)
+ .Replace("Center: Point2(0mm, 0mm)", "Center: Point2(10mm, 21mm)", StringComparison.Ordinal);
+ var source = Original[..Original.LastIndexOf('}')] + $"Modify bracket {{ {feature} }} }}";
+ var result = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(result.IsSuccess, string.Join(";", result.Diagnostics.Select(d => d.Message)));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs
index 1b125924..06ebd148 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs
@@ -55,6 +55,12 @@ public static class FirmamentBuildAdmissionValidation
public static FirmamentV2ValidationDiagnostic Present(KernelDiagnostic diagnostic, string sourceFile, string? source = null)
{
+ if (diagnostic.Message.StartsWith("compose-face-hole:", StringComparison.Ordinal)
+ && diagnostic.Message.IndexOf(": ", StringComparison.Ordinal) is var explanation && explanation > 0)
+ {
+ var located = Present(diagnostic with { Message = diagnostic.Message[..explanation] }, sourceFile, source);
+ return located with { Message = diagnostic.Message[(explanation + 2)..] };
+ }
var separator = diagnostic.Message.IndexOf(':');
var code = separator > 0 && !diagnostic.Message[..separator].Any(char.IsWhiteSpace)
? diagnostic.Message[..separator]
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs
index 5124c952..fa21ce8c 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs
@@ -31,9 +31,9 @@ public static class FirmamentLanguagePaletteService
new("hole-blind", "Blind hole", "Holes", "A drilled hole to a depth.", "feature", "BlindHole",
"Hole<Shaft> BlindHole { On: +Z Center: Point2(0mm, 0mm) Diameter: 6mm End: Blind 5mm }"),
new("counterbore", "Counterbored hole", "Holes", "A through hole with a flat-bottomed recess for a cap screw head.", "feature", "Counterbore",
- "Hole<Counterbore> Counterbore { On: +Z Center: Point2(0mm, 0mm) Diameter: 4mm CounterboreDiameter: 7mm CounterboreDepth: 3mm End: ThroughAll }"),
+ "Hole<Counterbore> Counterbore { On: +Z Center: Point2(0mm, 0mm) Diameter: 4mm CounterboreDiameter: 7mm CounterboreDepth: 1mm End: ThroughAll }"),
new("countersink", "Countersunk hole", "Holes", "A through hole with a conical recess for a flat-head screw.", "feature", "Countersink",
- "Hole<Countersink> Countersink { On: +Z Center: Point2(0mm, 0mm) Diameter: 6mm CountersinkDiameter: 12mm CountersinkAngle: 90deg End: ThroughAll }"),
+ "Hole<Countersink> Countersink { On: +Z Center: Point2(0mm, 0mm) Diameter: 6mm CountersinkDiameter: 8mm CountersinkAngle: 90deg End: ThroughAll }"),
new("perforation", "Perforation", "Holes", "A field of round vents across the top face.", "feature", "Vents",
"Perforation Vents { On: +Z Diameter: 6mm Layout: Hex Pitch: 9mm Margin: 8mm }"),
diff --git a/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs b/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs
index 19218bfb..47af2abe 100644
--- a/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/PlanarFaceThroughHole.cs
@@ -98,7 +98,8 @@ public static class PlanarFaceThroughHole
/// <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());
+ // Successful planning receipts are not errors when a later feature is refused.
+ PrismaticSectionStackEmissionResult Fail(string reason) => new(null, emitted.Plan, [$"compose-face-hole:{hole.Name}:{reason}"]);
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();
@@ -126,7 +127,11 @@ public static class PlanarFaceThroughHole
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 action = hole.Variant == "Counterbore" ? "Reduce CounterboreDepth" : "Reduce CountersinkDiameter or increase CountersinkAngle";
+ var message = FormattableString.Invariant($"{hole.Variant} depth is {recessDepth:0.###} mm, but this face has {exit.Depth:0.###} mm of material along the inward cutting direction. Recess depth must be from {MinimumClearance:0.###} to {exit.Depth - MinimumClearance:0.###} mm to retain a through shaft. {action}, or use a plain through hole.");
+ return Fail($"recess-depth-must-leave-at-least-0.01mm-of-shaft: {message}");
+ }
var clearedWalls = new HashSet<FaceId>();
foreach (var cavity in source.FaceHoleCavities)
{
diff --git a/docs/development/reports/2026-11/helios-recess-direction.md b/docs/development/reports/2026-11/helios-recess-direction.md
new file mode 100644
index 00000000..f69ea6f5
--- /dev/null
+++ b/docs/development/reports/2026-11/helios-recess-direction.md
@@ -0,0 +1,55 @@
+# Recess direction, defaults and refusal messages
+
+The reported counterbore used a 3 mm depth on the bracket's 3 mm wall. It was
+correctly refused because no smaller through shaft would remain. The placement
+guide nevertheless pointed along the outward support normal, making the result
+look reversed. Planning receipts were also incorrectly presented as errors
+alongside the actual depth refusal.
+
+The native cavity construction is unchanged. New regression checks verify that
+the larger opening lies on the selected entry face and the smaller shaft opens
+on the opposite exit, with the shoulder/shaft transition inside the material.
+Both recess types are checked on the foot, upright and opposite upright face.
+The bodies remain closed, correctly oriented and have the expected volume after
+STEP reimport.
+
+The gold direction arrow now points inward and has an arrowhead. The form says
+that the recess opens on the selected face. Palette defaults are a 4/7 mm
+counterbore at 1 mm depth, and a 6/8 mm 90° countersink (1 mm derived depth), so
+both fit the 3 mm bracket without correcting the defaults manually.
+
+A face-hole refusal returns only its actual failure, rather than promoting
+successful planner receipts to errors. Depth errors preserve their stable code
+and source location but present the requested depth, available wall thickness,
+allowed range and parameter to change. The 3 mm case reports a 2.99 mm maximum.
+The 0.01 mm remaining-shaft and clearance guards are preserved.
+
+Forty focused native/palette cases pass, including six direction builds across
+both signs of the face normal, stock-depth refusals and unchanged multi-hole
+guards. All 251 Helios unit tests pass. The screenshot workflow passes in both
+WebGPU and WebGL: use untouched defaults on the upright, refuse a 3 mm depth
+with one actionable message, recover to 1 mm, place a default countersink and
+export source/STEP for native CLI Built validation.
+
+Full solution and production qualification logs are retained as
+`artifacts/local/recess-direction-*`. Owning repository changes remain local;
+the deployed Site includes the complete corresponding patches.
+
+The Release solution build passes with zero warnings and errors. All 3,508
+Firmament tests pass in the full solution run. Five previously recorded failures
+remain outside this change: two Core NIST audit snapshots, the Geometry rotated
+occurrence measurement and Server revision measurement timing checks, and the
+EditableV8 dimensional-fit geometry snapshot. The last snapshot was reproduced
+on the unchanged upstream baseline during the preceding qualification; no
+snapshot or tolerance was changed. The full solution gate is therefore not green.
+
+The production AOT SDK and Helios frontend builds pass. The deployment uses
+published Helios revision `c705951db04cfb9fe726c04452d92e2181c6ce79` and Aetheris
+revision `007bbb4644ca8fba59bc66d5ab5a2a45a66ffb9e`, plus this change's complete
+working-tree patches. The decoded native WASM is 60,351,643 bytes with SHA-256
+`a70822bff349c28119cceb88bfc63f40774fb7b393fba496839dc5436324b705`.
+
+All 16 production graph workflows pass against the optimized bundle, with the
+production AOT runtime required. This includes the motivating default-depth,
+inward-direction, refusal/recovery and same-face recess workflow, as well as
+existing hole clearance, drag, undo, export and assembly graph checks.