Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add semantic stacked air hole materialization

Yuechen Lic9c09eadc979
diff --git a/Aetheris.Kernel.Core/Air/AirHoleFeature.cs b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
index 18a8e5dd..60a6fdaa 100644
--- a/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
+++ b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
@@ -3,7 +3,9 @@ using Aetheris.Kernel.Core.Math;
namespace Aetheris.Kernel.Core.Air;
internal enum AirHoleEndConditionKind { ThroughAll, Depth }
-internal enum AirHoleLoweringRouteKind { NotLowered, SimpleShaftProfileStackCandidate }
+internal enum AirHoleLoweringRouteKind { NotLowered, SimpleShaftProfileStackCandidate, StackedProfileStackCandidate }
+internal enum AirHoleStackKind { SimpleShaft, Counterbore, Countersink }
+internal enum AirHoleStackComponentKind { Shaft, Counterbore, Countersink }
internal sealed record AirHoleFeature(
string Name,
@@ -13,6 +15,7 @@ internal sealed record AirHoleFeature(
AirHoleAxis Axis,
AirHoleShaft Shaft,
AirHoleEndCondition EndCondition,
+ AirHoleStack Stack,
AirProvenance Provenance,
IReadOnlyList<AirDiagnostic> Diagnostics)
{
@@ -42,10 +45,44 @@ internal sealed record AirHoleFeature(
axis,
shaft,
endCondition,
+ AirHoleStack.SimpleShaft(shaft, endCondition),
provenance ?? DefaultProvenance(name, featureId),
diagnostics);
}
+
+ public static AirHoleFeature CreateCounterbore(
+ string name,
+ string featureId,
+ string? targetBodyId,
+ AirFaceLocalHolePlacement placement,
+ AirHoleAxis axis,
+ AirHoleShaft shaft,
+ AirHoleEndCondition endCondition,
+ AirHoleCounterboreComponent counterbore,
+ AirProvenance? provenance = null)
+ {
+ var stack = AirHoleStack.Counterbore(counterbore, new AirHoleShaftComponent(shaft.Diameter, endCondition));
+ var diagnostics = Validate(name, featureId, placement, axis, shaft, endCondition).Concat(ValidateStack(stack, shaft, endCondition)).ToArray();
+ return new AirHoleFeature(name, featureId, targetBodyId, placement, axis, shaft, endCondition, stack, provenance ?? DefaultProvenance(name, featureId), diagnostics);
+ }
+
+ public static AirHoleFeature CreateCountersink(
+ string name,
+ string featureId,
+ string? targetBodyId,
+ AirFaceLocalHolePlacement placement,
+ AirHoleAxis axis,
+ AirHoleShaft shaft,
+ AirHoleEndCondition endCondition,
+ AirHoleCountersinkComponent countersink,
+ AirProvenance? provenance = null)
+ {
+ var stack = AirHoleStack.Countersink(countersink, new AirHoleShaftComponent(shaft.Diameter, endCondition));
+ var diagnostics = Validate(name, featureId, placement, axis, shaft, endCondition).Concat(ValidateStack(stack, shaft, endCondition)).ToArray();
+ return new AirHoleFeature(name, featureId, targetBodyId, placement, axis, shaft, endCondition, stack, provenance ?? DefaultProvenance(name, featureId), diagnostics);
+ }
+
public AirHoleLoweringPlan CreateSimpleShaftLoweringPlan()
{
if (!IsValid)
@@ -71,7 +108,7 @@ internal sealed record AirHoleFeature(
AirRuleKind.None,
"authored/semantic-hole-intent",
true,
- ["Simple shaft hole only; throughAll and fixed depth end conditions are represented before lower geometry."]);
+ ["Semantic shaft/counterbore/countersink hole intent; throughAll and fixed depth end conditions are represented before lower geometry."]);
private static IEnumerable<AirDiagnostic> Validate(string name, string featureId, AirFaceLocalHolePlacement placement, AirHoleAxis axis, AirHoleShaft shaft, AirHoleEndCondition endCondition)
{
@@ -85,6 +122,26 @@ internal sealed record AirHoleFeature(
if (endCondition is AirHoleEndCondition.Depth depth && (!IsFinite(depth.Value) || depth.Value <= 0d)) yield return Error("hole-x1-depth-invalid", "Depth end condition must be greater than zero.");
}
+ private static IEnumerable<AirDiagnostic> ValidateStack(AirHoleStack stack, AirHoleShaft shaft, AirHoleEndCondition endCondition)
+ {
+ if (stack.Kind == AirHoleStackKind.Counterbore)
+ {
+ var cb = stack.Components.OfType<AirHoleCounterboreComponent>().Single();
+ if (!IsFinite(cb.Diameter) || cb.Diameter <= shaft.Diameter) yield return Error("hole-x3-counterbore-diameter-invalid", "Counterbore diameter must be finite and greater than shaft diameter.");
+ if (!IsFinite(cb.Depth) || cb.Depth <= 0d) yield return Error("hole-x3-counterbore-depth-invalid", "Counterbore depth must be finite and greater than zero.");
+ if (endCondition is AirHoleEndCondition.Depth d && IsFinite(cb.Depth) && cb.Depth > d.Value) yield return Error("hole-x3-counterbore-depth-exceeds-shaft-span", "Counterbore depth must not exceed bounded shaft depth.");
+ }
+ if (stack.Kind == AirHoleStackKind.Countersink)
+ {
+ var cs = stack.Components.OfType<AirHoleCountersinkComponent>().Single();
+ if (!IsFinite(cs.EntryDiameter) || cs.EntryDiameter <= shaft.Diameter) yield return Error("hole-x3-countersink-diameter-invalid", "Countersink entry diameter must be finite and greater than shaft diameter.");
+ if (!IsFinite(cs.AngleDegrees) || cs.AngleDegrees <= 0d || cs.AngleDegrees >= 180d) yield return Error("hole-x3-countersink-angle-invalid", "Countersink angle must be finite and between 0 and 180 degrees.");
+ var sinkDepth = cs.DerivedDepthForShaft(shaft);
+ if (!IsFinite(sinkDepth) || sinkDepth <= 0d) yield return Error("hole-x3-countersink-depth-invalid", "Countersink derived depth must be finite and greater than zero.");
+ if (IsFinite(sinkDepth) && endCondition is AirHoleEndCondition.Depth d && sinkDepth > d.Value) yield return Error("hole-x3-countersink-depth-exceeds-shaft-span", "Countersink derived depth must not exceed bounded shaft depth.");
+ }
+ }
+
private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
private static AirDiagnostic Error(string code, string message) => new(code, AirDiagnosticSeverity.Error, message);
}
@@ -96,6 +153,27 @@ internal sealed record AirHoleShaft(double Diameter)
public double Radius => Diameter / 2d;
}
+internal abstract record AirHoleStackComponent(AirHoleStackComponentKind Kind);
+internal sealed record AirHoleShaftComponent(double Diameter, AirHoleEndCondition EndCondition) : AirHoleStackComponent(AirHoleStackComponentKind.Shaft)
+{
+ public double Radius => Diameter / 2d;
+}
+internal sealed record AirHoleCounterboreComponent(double Diameter, double Depth) : AirHoleStackComponent(AirHoleStackComponentKind.Counterbore)
+{
+ public double Radius => Diameter / 2d;
+}
+internal sealed record AirHoleCountersinkComponent(double EntryDiameter, double AngleDegrees) : AirHoleStackComponent(AirHoleStackComponentKind.Countersink)
+{
+ public double EntryRadius => EntryDiameter / 2d;
+ public double DerivedDepthForShaft(AirHoleShaft shaft) => (EntryRadius - shaft.Radius) / System.Math.Tan((AngleDegrees / 2d) * System.Math.PI / 180d);
+}
+internal sealed record AirHoleStack(AirHoleStackKind Kind, IReadOnlyList<AirHoleStackComponent> Components)
+{
+ public static AirHoleStack SimpleShaft(AirHoleShaft shaft, AirHoleEndCondition endCondition) => new(AirHoleStackKind.SimpleShaft, [new AirHoleShaftComponent(shaft.Diameter, endCondition)]);
+ public static AirHoleStack Counterbore(AirHoleCounterboreComponent counterbore, AirHoleShaftComponent shaft) => new(AirHoleStackKind.Counterbore, [counterbore, shaft]);
+ public static AirHoleStack Countersink(AirHoleCountersinkComponent countersink, AirHoleShaftComponent shaft) => new(AirHoleStackKind.Countersink, [countersink, shaft]);
+}
+
internal abstract record AirHoleEndCondition(AirHoleEndConditionKind Kind)
{
public sealed record ThroughAll() : AirHoleEndCondition(AirHoleEndConditionKind.ThroughAll);
diff --git a/Aetheris.Kernel.Firmament.Tests/AirHoleStackedMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/AirHoleStackedMaterializerTests.cs
new file mode 100644
index 00000000..1ad74732
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/AirHoleStackedMaterializerTests.cs
@@ -0,0 +1,82 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class AirHoleStackedMaterializerTests
+{
+ [Fact]
+ public void CounterboreThroughAll_MaterializesAsOwnedSemanticStack()
+ {
+ var feature = Counterbore(new AirHoleEndCondition.ThroughAll(), counterboreDepth: 2);
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, Host());
+
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.Same(feature, result.Plan!.SemanticFeature);
+ Assert.Equal(AirHoleStackKind.Counterbore, result.Plan.StackKind);
+ Assert.Equal([AirHoleStackComponentKind.Counterbore, AirHoleStackComponentKind.Shaft], result.Plan.StackComponentRoles);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.Role.Contains("counterbore-entry") && l.InnerCircleRadius == 4);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.Role.Contains("shaft") && l.InnerCircleRadius == 2);
+ Assert.Contains(result.Diagnostics, d => d.Contains("semantic AirHoleFeature", StringComparison.Ordinal));
+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("CylinderCut", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void CounterboreDepth_MaterializesDeterministicStackSpans()
+ {
+ var result = AirHoleSimpleShaftMaterializer.Execute(Counterbore(new AirHoleEndCondition.Depth(4), 1.5), Host());
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.Contains(result.Plan!.ProfileStackSpec.Layers, l => l.Role.Contains("shaft") && l.ZMin == 1 && l.ZMax == 5);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.Role.Contains("counterbore-entry") && l.ZMin == 3.5 && l.ZMax == 5);
+ }
+
+ [Fact]
+ public void CounterboreValidation_RejectsInvalidStackDeterministically()
+ {
+ Assert.Contains(Counterbore(new AirHoleEndCondition.Depth(4), 1, diameter: 4).Diagnostics, d => d.Code == "hole-x3-counterbore-diameter-invalid");
+ Assert.Contains(Counterbore(new AirHoleEndCondition.Depth(4), 0).Diagnostics, d => d.Code == "hole-x3-counterbore-depth-invalid");
+ Assert.Contains(Counterbore(new AirHoleEndCondition.Depth(1), 2).Diagnostics, d => d.Code == "hole-x3-counterbore-depth-exceeds-shaft-span");
+ }
+
+ [Fact]
+ public void CountersinkThroughAll_MaterializesConicalEntryAndOwnedShaftStack()
+ {
+ var result = AirHoleSimpleShaftMaterializer.Execute(Countersink(new AirHoleEndCondition.ThroughAll(), 90), Host());
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.Equal(AirHoleStackKind.Countersink, result.Plan!.StackKind);
+ Assert.Equal([AirHoleStackComponentKind.Countersink, AirHoleStackComponentKind.Shaft], result.Plan.StackComponentRoles);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.Role.Contains("countersink-entry") && l.InnerCircleRadius == 4 && l.TopInnerCircleRadius == 2);
+ var step = Step242Exporter.ExportBody(result.Body!);
+ Assert.True(step.IsSuccess);
+ Assert.Contains("CONICAL_SURFACE", step.Value, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void CountersinkDepth_MaterializesDeterministicStackSpans()
+ {
+ var result = AirHoleSimpleShaftMaterializer.Execute(Countersink(new AirHoleEndCondition.Depth(4), 90), Host());
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.Contains(result.Plan!.ProfileStackSpec.Layers, l => l.Role.Contains("shaft") && l.ZMin == 1 && l.ZMax == 5);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.Role.Contains("countersink-entry") && Math.Abs(l.ZMin - 3) < 1e-9 && l.ZMax == 5);
+ }
+
+ [Fact]
+ public void CountersinkValidation_RejectsInvalidStackDeterministically()
+ {
+ Assert.Contains(Countersink(new AirHoleEndCondition.Depth(4), 90, entryDiameter: 4).Diagnostics, d => d.Code == "hole-x3-countersink-diameter-invalid");
+ Assert.Contains(Countersink(new AirHoleEndCondition.Depth(4), 0).Diagnostics, d => d.Code == "hole-x3-countersink-angle-invalid");
+ Assert.Contains(Countersink(new AirHoleEndCondition.Depth(1), 90).Diagnostics, d => d.Code == "hole-x3-countersink-depth-exceeds-shaft-span");
+ }
+
+ private static AirHoleSimpleShaftHost Host() => new(20, 20, -5, 5);
+
+ private static AirHoleFeature Counterbore(AirHoleEndCondition endCondition, double counterboreDepth, double diameter = 8) => AirHoleFeature.CreateCounterbore(
+ "cb", "hole-cb", "body-main", new AirFaceLocalHolePlacement("top", 0, 0, "face(top):u=+X,v=+Y"),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(0, 0, 1)), true), new AirHoleShaft(4), endCondition, new AirHoleCounterboreComponent(diameter, counterboreDepth));
+
+ private static AirHoleFeature Countersink(AirHoleEndCondition endCondition, double angle, double entryDiameter = 8) => AirHoleFeature.CreateCountersink(
+ "cs", "hole-cs", "body-main", new AirFaceLocalHolePlacement("top", 0, 0, "face(top):u=+X,v=+Y"),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(0, 0, 1)), true), new AirHoleShaft(4), endCondition, new AirHoleCountersinkComponent(entryDiameter, angle));
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
index 94bc6228..6297e0c8 100644
--- a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
@@ -35,6 +35,8 @@ internal sealed record AirHoleSimpleShaftMaterializationPlan(
double CutZMin,
double CutZMax,
AirHoleEndConditionKind EndConditionKind,
+ AirHoleStackKind StackKind,
+ IReadOnlyList<AirHoleStackComponentKind> StackComponentRoles,
ProfileStackExtrudeSpec ProfileStackSpec,
IReadOnlyList<string> Diagnostics);
@@ -77,7 +79,7 @@ internal static class AirHoleSimpleShaftMaterializer
public static AirHoleSimpleShaftMaterializationResult TryCreatePlan(AirHoleFeature feature, AirHoleSimpleShaftHost host)
{
- var diagnostics = new List<string> { "air-hole-x2 simple shaft planner started." };
+ var diagnostics = new List<string> { "air-hole-x2 semantic hole planner started." };
if (!feature.IsValid)
{
diagnostics.AddRange(feature.Diagnostics.Select(d => $"semantic diagnostic {d.Code}: {d.Message}"));
@@ -120,8 +122,8 @@ internal static class AirHoleSimpleShaftMaterializer
feature.Placement.U,
feature.Placement.V);
var plan = new AirHoleSimpleShaftMaterializationPlan(feature, host, feature.FeatureId, nameof(AirHoleFeature), feature.Placement.EntryFaceName,
- feature.Placement.U, feature.Placement.V, axisZ, feature.Shaft.Radius, cutZMin, cutZMax, feature.EndCondition.Kind, spec, diagnostics.ToArray());
- diagnostics.Add("air-hole-x2 plan created; semantic AirHoleFeature remains parent intent.");
+ feature.Placement.U, feature.Placement.V, axisZ, feature.Shaft.Radius, cutZMin, cutZMax, feature.EndCondition.Kind, feature.Stack.Kind, feature.Stack.Components.Select(c => c.Kind).ToArray(), spec, diagnostics.ToArray());
+ diagnostics.Add("air-hole-x2/x3 plan created; semantic AirHoleFeature remains parent intent and owns stack components.");
return new(AirHoleSimpleShaftMaterializationStatus.Succeeded, plan, null, diagnostics);
}
@@ -135,7 +137,25 @@ internal static class AirHoleSimpleShaftMaterializer
private static IEnumerable<ProfileStackLayer> BuildLayers(AirHoleFeature feature, AirHoleSimpleShaftHost host, double cutZMin, double cutZMax)
{
if (cutZMin > host.ZMin + Tolerance) yield return new(host.ZMin, cutZMin, null, "air-hole-x2-solid-before-blind-depth", []);
- yield return new(cutZMin, cutZMax, feature.Shaft.Radius, $"air-hole-x2-simple-shaft:{feature.FeatureId}", []);
+ if (feature.Stack.Kind == AirHoleStackKind.Counterbore)
+ {
+ var cb = feature.Stack.Components.OfType<AirHoleCounterboreComponent>().Single();
+ var entryMin = Math.Max(cutZMin, cutZMax - cb.Depth);
+ yield return new(cutZMin, cutZMax, feature.Shaft.Radius, $"air-hole-x3-shaft:{feature.FeatureId}", []);
+ yield return new(entryMin, cutZMax, cb.Radius, $"air-hole-x3-counterbore-entry:{feature.FeatureId}", []);
+ }
+ else if (feature.Stack.Kind == AirHoleStackKind.Countersink)
+ {
+ var cs = feature.Stack.Components.OfType<AirHoleCountersinkComponent>().Single();
+ var sinkDepth = cs.DerivedDepthForShaft(feature.Shaft);
+ var entryMin = Math.Max(cutZMin, cutZMax - sinkDepth);
+ yield return new(cutZMin, cutZMax, feature.Shaft.Radius, $"air-hole-x3-shaft:{feature.FeatureId}", []);
+ yield return new(entryMin, cutZMax, cs.EntryRadius, $"air-hole-x3-countersink-entry:{feature.FeatureId}", [], feature.Shaft.Radius);
+ }
+ else
+ {
+ yield return new(cutZMin, cutZMax, feature.Shaft.Radius, $"air-hole-x2-simple-shaft:{feature.FeatureId}", []);
+ }
if (cutZMax < host.ZMax - Tolerance) yield return new(cutZMax, host.ZMax, null, "air-hole-x2-solid-after-blind-depth", []);
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
index 95e0d053..bc0621af 100644
--- a/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
@@ -20,7 +20,8 @@ public sealed record ProfileStackLayer(
double ZMax,
double? InnerCircleRadius,
string Role,
- IReadOnlyList<string> Diagnostics);
+ IReadOnlyList<string> Diagnostics,
+ double? TopInnerCircleRadius = null);
public sealed record ProfileStackExtrudeSpec(
double Width,
@@ -52,7 +53,7 @@ public static class ProfileStackExtrudeExecutor
for (var i = 0; i < orderedLayers.Count; i++)
{
var l = orderedLayers[i];
- diagnostics.Add($"profile-stack layer[{i}] role={l.Role} zMin={l.ZMin:0.###} zMax={l.ZMax:0.###} radius={(l.InnerCircleRadius?.ToString("0.###") ?? "none") }.");
+ diagnostics.Add($"profile-stack layer[{i}] role={l.Role} zMin={l.ZMin:0.###} zMax={l.ZMax:0.###} radius={(l.InnerCircleRadius?.ToString("0.###") ?? "none") } topRadius={(l.TopInnerCircleRadius?.ToString("0.###") ?? "same")}.");
}
if (orderedLayers.All(l => !l.InnerCircleRadius.HasValue))
@@ -71,8 +72,24 @@ public static class ProfileStackExtrudeExecutor
: (Math.Abs(l.ZMax - spec.ZMax) < 1e-9
? SupportedBooleanHoleSpanKind.BlindFromTop
: SupportedBooleanHoleSpanKind.Contained);
+ if (l.TopInnerCircleRadius.HasValue && Math.Abs(l.TopInnerCircleRadius.Value - l.InnerCircleRadius.Value) > 1e-9)
+ {
+ var bottomRadius = l.InnerCircleRadius.Value;
+ var topRadius = l.TopInnerCircleRadius.Value;
+ var semiAngle = Math.Atan(Math.Abs(topRadius - bottomRadius) / (l.ZMax - l.ZMin));
+ var radiusScale = Math.Tan(semiAngle);
+ var axis = topRadius >= bottomRadius ? zAxis : Direction3D.Create(new Vector3D(0, 0, -1));
+ var axisOriginZ = topRadius >= bottomRadius ? l.ZMin - bottomRadius / radiusScale : l.ZMax + topRadius / radiusScale;
+ var minParam = topRadius >= bottomRadius ? bottomRadius / radiusScale : topRadius / radiusScale;
+ var maxParam = topRadius >= bottomRadius ? topRadius / radiusScale : bottomRadius / radiusScale;
+ var cone = new RecognizedCone(new Point3D(spec.CenterX, spec.CenterY, axisOriginZ), axis, minParam, maxParam, semiAngle, Math.Min(bottomRadius, topRadius), Math.Max(bottomRadius, topRadius));
+ holes.Add(new SupportedBooleanHole(l.Role, new AnalyticSurface(AnalyticSurfaceKind.Cone, Cone: cone), spec.CenterX, spec.CenterY,
+ new Point3D(spec.CenterX, spec.CenterY, l.ZMin), new Point3D(spec.CenterX, spec.CenterY, l.ZMax), zAxis, xAxis,
+ bottomRadius, topRadius, span, l.ZMin, l.ZMax));
+ continue;
+ }
var cyl = new RecognizedCylinder(new Point3D(spec.CenterX, spec.CenterY, 0), zAxis, l.InnerCircleRadius!.Value, l.ZMin, l.ZMax);
- holes.Add(new SupportedBooleanHole(l.Role, new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cyl), 0, 0,
+ holes.Add(new SupportedBooleanHole(l.Role, new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cyl), spec.CenterX, spec.CenterY,
new Point3D(spec.CenterX, spec.CenterY, l.ZMin), new Point3D(spec.CenterX, spec.CenterY, l.ZMax), zAxis, xAxis,
l.InnerCircleRadius.Value, l.InnerCircleRadius.Value, span, l.ZMin, l.ZMax));
}
@@ -121,7 +138,11 @@ public static class ProfileStackExtrudeExecutor
if (i > 0)
{
var prev = orderedLayers[i - 1];
- if (Math.Abs(prev.ZMax - l.ZMin) > 1e-9)
+ if (l.ZMin < prev.ZMax - 1e-9)
+ {
+ diagnostics.Add($"profile-stack validation accepted overlapping semantic entry-prep layer between [{i - 1}] and [{i}].");
+ }
+ else if (Math.Abs(prev.ZMax - l.ZMin) > 1e-9)
{
diagnostics.Add($"profile-stack validation failed: non-contiguous layer ordering between [{i - 1}] and [{i}].");
return false;
@@ -129,7 +150,7 @@ public static class ProfileStackExtrudeExecutor
}
}
- if (Math.Abs(orderedLayers[0].ZMin - spec.ZMin) > 1e-9 || Math.Abs(orderedLayers[^1].ZMax - spec.ZMax) > 1e-9)
+ if (orderedLayers[0].ZMin > spec.ZMin + 1e-9 || orderedLayers.Max(l => l.ZMax) < spec.ZMax - 1e-9)
{
diagnostics.Add("profile-stack validation failed: layers do not fully cover global z-span.");
return false;
diff --git a/docs/implementation/hole-x2-simple-shaft-hole-materialization.md b/docs/implementation/hole-x2-simple-shaft-hole-materialization.md
index 50f7eac4..25ce8598 100644
--- a/docs/implementation/hole-x2-simple-shaft-hole-materialization.md
+++ b/docs/implementation/hole-x2-simple-shaft-hole-materialization.md
@@ -61,3 +61,5 @@ dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.cspr
```
Full milestone validation should also run the solution restore/build and focused `Air`/`Hole`/`FirmamentV2` filters documented in the milestone prompt.
+
+Forward link: HOLE-X3 extends this lane with semantic counterbore/countersink stack components in `docs/implementation/hole-x3-stacked-hole-components.md`.
diff --git a/docs/implementation/hole-x3-stacked-hole-components.md b/docs/implementation/hole-x3-stacked-hole-components.md
new file mode 100644
index 00000000..c09c65bf
--- /dev/null
+++ b/docs/implementation/hole-x3-stacked-hole-components.md
@@ -0,0 +1,52 @@
+# HOLE-X3 stacked semantic hole components
+
+HOLE-X3 extends the production semantic `AirHoleFeature` lane from simple shaft holes to owned axial stacks for counterbore and countersink holes. The authored source of truth remains one semantic hole feature; stack components are semantic children, not independent cylinder/cone cuts.
+
+## Supported stack shapes
+
+- Simple shaft: one `AirHoleShaftComponent`.
+- Counterbore: one entry `AirHoleCounterboreComponent` followed by the shaft component.
+- Countersink: one entry `AirHoleCountersinkComponent` followed by the shaft component. The production declaration uses entry diameter plus included angle and derives sink depth from the shaft radius.
+
+Supported placement and end conditions remain the HOLE-X2 subset: face-local top/bottom planar entry placement, Z-aligned entry normal/axis, throughAll, and fixed depth.
+
+## Materialization path and provenance
+
+The lowering/materialization path is:
+
+```text
+AirHoleFeature
+ -> AirHoleStack owned by that feature
+ -> AirHoleSimpleShaftMaterializationPlan with StackKind/StackComponentRoles
+ -> ProfileStackExtrudeSpec/ProfileStackLayer implementation furniture
+ -> ProfileStackExtrudeExecutor
+ -> BRep output
+```
+
+`ProfileStackExtrudeSpec` is still only a downstream execution contract. The materialization plan keeps the source `AirHoleFeature`, semantic feature id, source kind, stack kind, and component roles so tests and diagnostics can trace BRep output back to the parent semantic feature.
+
+## Validation behavior
+
+Counterbore validation rejects non-finite or too-small entry diameters, non-positive/non-finite counterbore depths, and counterbore depths that exceed a bounded depth end condition.
+
+Countersink validation rejects non-finite or too-small entry diameters, invalid included angles, non-positive derived sink depths, and derived depths that exceed a bounded depth end condition.
+
+## Deferred features
+
+HOLE-X3 does not add parser syntax, standards or fit libraries, thread/tap geometry, drill-tip geometry, hole groups, patterns, upToFace/upToNext, arbitrary datum placement, STEP/DisplayIR/frontend/product behavior changes, or generic raw 3D boolean authoring.
+
+## Relationship to semantic-hole strategy
+
+This implements the principle from `docs/llm-cad-strategy/07-holes-are-semantic-features.md`: counterbores and countersinks are variants of a semantic hole feature. The entry preparation and shaft remain an owned axial feature stack because later standards, PMI, manufacturing intent, and edits need a single parent hole identity.
+
+## Validation commands
+
+```bash
+dotnet restore Aetheris.slnx
+dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1
+dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj -f net10.0 --no-build --filter "AirHole|Stack|Counterbore|Countersink"
+dotnet test Aetheris.Kernel.Core.Tests/Aetheris.Kernel.Core.Tests.csproj -f net10.0 --no-build --filter AirHoleFeature
+dotnet test Aetheris.slnx -f net10.0 --no-build --filter "Hole|FirmamentV2|Air"
+git diff --check
+git status --short
+```