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.csnew file mode 100644index 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.csindex 1b125924..06ebd148 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentBuildAdmissionValidation.cs@@ -55,6 +55,12 @@ public static class FirmamentBuildAdmissionValidationpublic 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.csindex 5124c952..fa21ce8c 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguagePalette.cs@@ -31,9 +31,9 @@ public static class FirmamentLanguagePaletteServicenew("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.csindex 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 PlanarFaceThroughHolerecessDepth = (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.mdnew file mode 100644index 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.