Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add Firmament V2 semantic hole source hook
Yuechen Li113ae1feb630
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.csnew file mode 100644index 00000000..b63194f1--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs@@ -0,0 +1,66 @@+using Aetheris.Kernel.Core.Air;+using Aetheris.Kernel.Firmament.FirmamentV2;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class FirmamentV2SemanticHoleTests+{+ [Fact]+ public void FirmamentV2SemanticHole_ParsesShaftCounterboreCountersink()+ {+ AssertHole("Hole/valid/hole-x4-shaft-through.valid.firmfixture", FirmamentV2SemanticHoleVariant.Shaft);+ AssertHole("Hole/valid/hole-x4-counterbore-through.valid.firmfixture", FirmamentV2SemanticHoleVariant.Counterbore);+ AssertHole("Hole/valid/hole-x4-countersink-depth.valid.firmfixture", FirmamentV2SemanticHoleVariant.Countersink);+ }++ [Fact]+ public void FirmamentV2SemanticHole_InvalidFixturesProduceDeterministicDiagnostics()+ {+ Assert.Contains(FirmamentV2Parser.HoleVariantUnknown, Parse("Hole/invalid/hole-x4-unknown.invalid.firmfixture").Diagnostics);+ Assert.Contains(FirmamentV2Parser.HoleCounterboreInvalid, Parse("Hole/invalid/hole-x4-bad-counterbore.invalid.firmfixture").Diagnostics);+ Assert.Contains(FirmamentV2Parser.HoleDepthInvalid, Parse("Hole/invalid/hole-x4-negative-depth.invalid.firmfixture").Diagnostics);+ }++ [Fact]+ public void FirmamentV2SemanticHole_LowersThroughAirHoleFeatureAndPreservesProvenance()+ {+ var features = FirmamentV2SemanticHoleLowering.LowerSemanticHoles(Parse("Hole/valid/hole-x4-counterbore-through.valid.firmfixture").Document!);+ var feature = Assert.Single(features);+ Assert.Equal(nameof(AirHoleFeature), feature.Provenance.RouteName);+ Assert.Equal("mount", feature.Name);+ Assert.Equal("base.mount", feature.FeatureId);+ Assert.Equal(AirHoleStackKind.Counterbore, feature.Stack.Kind);+ Assert.Equal([AirHoleStackComponentKind.Counterbore, AirHoleStackComponentKind.Shaft], feature.Stack.Components.Select(c => c.Kind).ToArray());+ Assert.DoesNotContain("ProfileStackExtrudeSpec", feature.Provenance.ConstructionHistoryKind);+ }++ [Theory]+ [InlineData("Hole/valid/hole-x4-shaft-through.valid.firmfixture", "SimpleShaft")]+ [InlineData("Hole/valid/hole-x4-counterbore-through.valid.firmfixture", "Counterbore")]+ [InlineData("Hole/valid/hole-x4-countersink-depth.valid.firmfixture", "Countersink")]+ public void FirmamentV2SemanticHole_MaterializesViaExistingAirHolePath(string fixture, string kind)+ {+ var feature = Assert.Single(FirmamentV2SemanticHoleLowering.LowerSemanticHoles(Parse(fixture).Document!));+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, new AirHoleSimpleShaftHost(100, 60, -6, 6));+ Assert.True(result.Succeeded, string.Join(" | ", result.Diagnostics));+ Assert.Equal(kind, result.Plan!.StackKind.ToString());+ Assert.Equal(nameof(AirHoleFeature), result.Plan.SemanticSourceKind);+ Assert.Contains(result.Diagnostics, d => d.Contains("semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor", StringComparison.Ordinal));+ }++ private static void AssertHole(string fixture, FirmamentV2SemanticHoleVariant variant)+ {+ var result = Parse(fixture);+ Assert.True(result.IsSuccess, string.Join(", ", result.Diagnostics));+ var hole = Assert.Single(Assert.Single(result.Document!.ModifyBlocks!).SemanticHoles);+ Assert.Equal(variant, hole.Variant);+ Assert.Equal("face(+Z)", hole.EntryFace.Source);+ }++ private static FirmamentV2ParseResult Parse(string relative)+ {+ var path = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2", relative));+ return FirmamentV2Parser.Parse(File.ReadAllText(path));+ }+}diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.csindex 8711417f..4bce847b 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs@@ -28,7 +28,10 @@ public sealed record FirmamentV2FaceSelector(string Axis){public string Source => $"face({Axis})";}-public sealed record FirmamentV2ModifyBlock(string TargetSolid, IReadOnlyList<FirmamentV2RegionDecl> Regions);+public sealed record FirmamentV2ModifyBlock(string TargetSolid, IReadOnlyList<FirmamentV2RegionDecl> Regions, IReadOnlyList<FirmamentV2SemanticHoleDecl> SemanticHoles)+{+ public FirmamentV2ModifyBlock(string TargetSolid, IReadOnlyList<FirmamentV2RegionDecl> Regions) : this(TargetSolid, Regions, []) { }+}public sealed record FirmamentV2RegionDecl(string Name, string Kind, FirmamentV2FaceTarget Attachment, FirmamentV2CutOperation Cut);public sealed record FirmamentV2CutOperation(string OperationKind, FirmamentV2CylinderTool Tool);public sealed record FirmamentV2CylinderTool(string ToolType, double Radius, FirmamentV2FaceLocalPoint2D? Center, FirmamentV2FaceTarget Through);@@ -55,6 +58,20 @@ public sealed record FirmamentV2SideHoleIntent(string TargetSolid, string Regionpublic string Route => PolicyRoute.Direction;public FirmamentV2SideHoleRoutePolicyEvidence RouteEvidence => PolicyRoute;}+public enum FirmamentV2SemanticHoleVariant { Shaft, Counterbore, Countersink }+public enum FirmamentV2SemanticHoleEndKind { ThroughAll, Depth }+public sealed record FirmamentV2SemanticHoleEnd(FirmamentV2SemanticHoleEndKind Kind, double? Depth = null);+public sealed record FirmamentV2SemanticHoleDecl(+ string Name,+ FirmamentV2SemanticHoleVariant Variant,+ FirmamentV2FaceTarget EntryFace,+ FirmamentV2FaceLocalPoint2D Center,+ double ShaftDiameter,+ FirmamentV2SemanticHoleEnd EndCondition,+ double? CounterboreDiameter = null,+ double? CounterboreDepth = null,+ double? CountersinkDiameter = null,+ double? CountersinkAngleDegrees = null);public sealed record FirmamentV2ParseResult(bool IsSuccess, FirmamentV2Document? Document, IReadOnlyList<string> Diagnostics){public static FirmamentV2ParseResult Success(FirmamentV2Document document, IReadOnlyList<string> diagnostics) => new(true, document, diagnostics);diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.csindex 4b9a1c11..e1bd2b2b 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs@@ -1,5 +1,6 @@using System.Globalization;using System.Text.RegularExpressions;+using Aetheris.Kernel.Core.Air;namespace Aetheris.Kernel.Firmament.FirmamentV2;@@ -54,6 +55,15 @@ public static class FirmamentV2Parserpublic const string CylinderCenterArityInvalid = "firmament-v2-cylinder-center-arity-invalid";public const string CylinderCenterNotFinite = "firmament-v2-cylinder-center-not-finite";public const string SideHoleCenterExceedsClearance = "firmament-v2-side-hole-center-exceeds-clearance";+ public const string HoleVariantUnknown = "firmament-v2-hole-variant-unknown";+ public const string HoleEntryFaceMissing = "firmament-v2-hole-entry-face-missing";+ public const string HoleCenterMissing = "firmament-v2-hole-center-missing";+ public const string HoleShaftMissing = "firmament-v2-hole-shaft-diameter-missing";+ public const string HoleEndMissing = "firmament-v2-hole-end-missing";+ public const string HoleDiameterInvalid = "firmament-v2-hole-diameter-invalid";+ public const string HoleDepthInvalid = "firmament-v2-hole-depth-invalid";+ public const string HoleCounterboreInvalid = "firmament-v2-hole-counterbore-invalid";+ public const string HoleCountersinkInvalid = "firmament-v2-hole-countersink-invalid";private static readonly Regex ModelRegex = new(@"\bmodel\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);private static readonly Regex UnitsRegex = new(@"\bunits\s+(?<units>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);@@ -70,6 +80,7 @@ public static class FirmamentV2Parserprivate static readonly Regex RadiusRegex = new(@"\bradius\s*:\s*(?<value>[^\s}]+)", RegexOptions.CultureInvariant);private static readonly Regex ThroughRegex = new(@"\bthrough\s*:\s*(?<target>face\([^)]*\)|[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);private static readonly Regex CenterRegex = new(@"\bcenter\s*:\s*\[(?<values>[^\]]*)\]", RegexOptions.CultureInvariant | RegexOptions.Singleline);+ private static readonly Regex SemanticHoleHeaderRegex = new(@"\bhole\s*<\s*(?<variant>[A-Za-z_][A-Za-z0-9_]*)\s*>\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);public static FirmamentV2ParseResult Parse(string sourceText){@@ -147,7 +158,7 @@ public static class FirmamentV2Parserreturn new(name, "Box", new(values, []), baseName, new Dictionary<string, IReadOnlyList<double>>(StringComparer.Ordinal) { ["size"] = values });}- private static bool IsFatalDiagnostic(string code) => code is MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance;+ private static bool IsFatalDiagnostic(string code) => code is MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid;private static IReadOnlyList<FirmamentV2Exposure> ParseExposures(string body, List<string> diagnostics){@@ -219,8 +230,11 @@ public static class FirmamentV2Parservar close = FindMatchingBrace(source, open);if (close < 0) { diagnostics.Add(RegionUnsupported); continue; }var body = source[(open + 1)..close];+ var regions = new List<FirmamentV2RegionDecl>();var region = ParseRegion(body, solid, diagnostics);- if (region is not null) blocks.Add(new(target, [region]));+ if (region is not null) regions.Add(region);+ var holes = ParseSemanticHoles(body, solid, diagnostics);+ if (regions.Count > 0 || holes.Count > 0) blocks.Add(new(target, regions, holes));}return blocks;}@@ -228,6 +242,7 @@ public static class FirmamentV2Parserprivate static FirmamentV2RegionDecl? ParseRegion(string body, FirmamentV2SolidBinding solid, List<string> diagnostics){var regions = RegionHeaderRegex.Matches(body);+ if (regions.Count == 0) return null;if (regions.Count != 1) { diagnostics.Add(RegionUnsupported); return null; }var rm = regions[0];if (!string.Equals(rm.Groups["name"].Value, "sideHole", StringComparison.Ordinal)) { diagnostics.Add(RegionUnsupported); return null; }@@ -249,6 +264,69 @@ public static class FirmamentV2Parserreturn diagnostics.Any(IsFatalDiagnostic) ? null : new(rm.Groups["name"].Value, "FaceAttachedRegion", attach, cut);}+ private static IReadOnlyList<FirmamentV2SemanticHoleDecl> ParseSemanticHoles(string body, FirmamentV2SolidBinding solid, List<string> diagnostics)+ {+ var holes = new List<FirmamentV2SemanticHoleDecl>();+ foreach (Match hm in SemanticHoleHeaderRegex.Matches(body))+ {+ if (!Enum.TryParse<FirmamentV2SemanticHoleVariant>(hm.Groups["variant"].Value, true, out var variant)) { diagnostics.Add(HoleVariantUnknown); continue; }+ var open = body.IndexOf('{', hm.Index);+ var close = FindMatchingBrace(body, open);+ if (close < 0) { diagnostics.Add(RegionUnsupported); continue; }+ var hb = body[(open + 1)..close];+ var on = Regex.Match(hb, @"\bon\s*:\s*(?<target>face\([^)]*\)|[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);+ var face = on.Success ? ResolveFaceTarget(on.Groups["target"].Value, solid, HoleEntryFaceMissing, diagnostics) : null;+ if (face is null) diagnostics.Add(HoleEntryFaceMissing);+ var center = CenterRegex.IsMatch(hb) ? ParseCenter(hb, diagnostics) : null;+ if (center is null) diagnostics.Add(HoleCenterMissing);+ var hasShaftDiameter = ReadPositive(hb, ["shaftDiameter", "diameter"], out var shaftDiameter);+ double shaftRadius = 0d;+ var hasShaftRadius = !hasShaftDiameter && ReadPositive(hb, ["shaftRadius", "radius"], out shaftRadius);+ var shaft = hasShaftDiameter || hasShaftRadius;+ var shaftDia = hasShaftDiameter ? shaftDiameter : (hasShaftRadius ? shaftRadius * 2d : 0d);+ if (!shaft) diagnostics.Add(HoleShaftMissing);+ var end = ParseEnd(hb, diagnostics);+ double? cbDia = null, cbDepth = null, csDia = null, csAngle = null;+ if (variant == FirmamentV2SemanticHoleVariant.Counterbore)+ {+ if (!(ReadPositive(hb, ["counterboreDiameter"], out var d) || (ReadPositive(hb, ["counterboreRadius"], out var r) && (d = r * 2d) > 0)) || d <= shaftDia) diagnostics.Add(HoleCounterboreInvalid); else cbDia = d;+ if (!ReadPositive(hb, ["counterboreDepth"], out var depth)) diagnostics.Add(HoleCounterboreInvalid); else cbDepth = depth;+ }+ if (variant == FirmamentV2SemanticHoleVariant.Countersink)+ {+ if (!(ReadPositive(hb, ["countersinkDiameter"], out var d) || (ReadPositive(hb, ["countersinkRadius"], out var r) && (d = r * 2d) > 0)) || d <= shaftDia) diagnostics.Add(HoleCountersinkInvalid); else csDia = d;+ if (!ReadPositive(hb, ["countersinkAngle"], out var angle) || angle <= 0 || angle >= 180) diagnostics.Add(HoleCountersinkInvalid); else csAngle = angle;+ }+ if (face is not null && center is not null && shaft && end is not null && !diagnostics.Any(IsFatalDiagnostic))+ holes.Add(new(hm.Groups["name"].Value, variant, face, center with { Convention = FirmamentV2FaceLocalPoint2D.ConventionFor(face.Axis) }, shaftDia, end, cbDia, cbDepth, csDia, csAngle));+ }+ return holes;+ }++ private static FirmamentV2SemanticHoleEnd? ParseEnd(string body, List<string> diagnostics)+ {+ var m = Regex.Match(body, @"\bend\s*:\s*(?<kind>throughAll|depth)(?:\s+(?<value>[^\s}]+))?", RegexOptions.CultureInvariant);+ if (!m.Success) { diagnostics.Add(HoleEndMissing); return null; }+ if (m.Groups["kind"].Value == "throughAll") return new FirmamentV2SemanticHoleEnd(FirmamentV2SemanticHoleEndKind.ThroughAll);+ if (!double.TryParse(m.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var depth) || !double.IsFinite(depth) || depth <= 0) { diagnostics.Add(HoleDepthInvalid); return null; }+ return new FirmamentV2SemanticHoleEnd(FirmamentV2SemanticHoleEndKind.Depth, depth);+ }++ private static bool ReadPositive(string body, string[] names, out double value)+ {+ foreach (var name in names)+ {+ var m = Regex.Match(body, $@"\b{name}\s*:\s*(?<value>[^\s}}]+)", RegexOptions.CultureInvariant);+ if (m.Success)+ {+ if (!double.TryParse(m.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out value) || !double.IsFinite(value) || value <= 0) return false;+ return true;+ }+ }+ value = 0;+ return false;+ }+private static FirmamentV2CutOperation? ParseCut(string body, FirmamentV2SolidBinding solid, List<string> diagnostics){var cuts = CutHeaderRegex.Matches(body);diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.csnew file mode 100644index 00000000..0b8153c6--- /dev/null+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs@@ -0,0 +1,25 @@+using Aetheris.Kernel.Core.Air;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Firmament.FirmamentV2;++internal static class FirmamentV2SemanticHoleLowering+{+ public static AirHoleFeature Lower(FirmamentV2Document document, FirmamentV2ModifyBlock modify, FirmamentV2SemanticHoleDecl hole)+ {+ var placement = new AirFaceLocalHolePlacement(hole.EntryFace.Axis switch { "+Z" => "top", "-Z" => "bottom", _ => hole.EntryFace.Source }, hole.Center.U, hole.Center.V, FirmamentV2FaceLocalPoint2D.ConventionFor(hole.EntryFace.Axis), hole.EntryFace.ResolvedSelector);+ var axis = new AirHoleAxis(Direction3D.Create(hole.EntryFace.Axis switch { "-Z" => new Vector3D(0,0,-1), "+Z" => new Vector3D(0,0,1), "+X" => new Vector3D(1,0,0), "-X" => new Vector3D(-1,0,0), "+Y" => new Vector3D(0,1,0), _ => new Vector3D(0,-1,0) }), true);+ var shaft = new AirHoleShaft(hole.ShaftDiameter);+ AirHoleEndCondition endCondition = hole.EndCondition.Kind == FirmamentV2SemanticHoleEndKind.ThroughAll ? new AirHoleEndCondition.ThroughAll() : new AirHoleEndCondition.Depth(hole.EndCondition.Depth!.Value);+ var provenance = new AirProvenance("HOLE-X4", "Firmament V2 semantic hole source hook", hole.Name, $"{modify.TargetSolid}.{hole.Name}", nameof(AirHoleFeature), AirSelectionClass.None, AirRuleKind.None, $"FirmamentV2 hole<{hole.Variant}>", true, [$"source-variant:{hole.Variant}", $"target-solid:{modify.TargetSolid}", $"entry-face:{hole.EntryFace.Source}"]);+ return hole.Variant switch+ {+ FirmamentV2SemanticHoleVariant.Counterbore => AirHoleFeature.CreateCounterbore(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCounterboreComponent(hole.CounterboreDiameter!.Value, hole.CounterboreDepth!.Value), provenance),+ FirmamentV2SemanticHoleVariant.Countersink => AirHoleFeature.CreateCountersink(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCountersinkComponent(hole.CountersinkDiameter!.Value, hole.CountersinkAngleDegrees!.Value), provenance),+ _ => AirHoleFeature.CreateSimpleShaft(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, provenance)+ };+ }++ public static IReadOnlyList<AirHoleFeature> LowerSemanticHoles(FirmamentV2Document document) =>+ document.ModifyBlocks?.SelectMany(m => m.SemanticHoles.Select(h => Lower(document, m, h))).ToArray() ?? [];+}diff --git a/docs/implementation/hole-x3-stacked-hole-components.md b/docs/implementation/hole-x3-stacked-hole-components.mdindex c09c65bf..0d266183 100644--- a/docs/implementation/hole-x3-stacked-hole-components.md+++ b/docs/implementation/hole-x3-stacked-hole-components.md@@ -50,3 +50,5 @@ dotnet test Aetheris.slnx -f net10.0 --no-build --filter "Hole|FirmamentV2|Air"git diff --checkgit status --short```++Forward link: HOLE-X4 adds the Firmament V2 source hook for `hole<shaft>`, `hole<counterbore>`, and `hole<countersink>` declarations in `docs/implementation/hole-x4-firmament-v2-semantic-hole-source.md`.diff --git a/docs/implementation/hole-x4-firmament-v2-semantic-hole-source.md b/docs/implementation/hole-x4-firmament-v2-semantic-hole-source.mdnew file mode 100644index 00000000..5d99d913--- /dev/null+++ b/docs/implementation/hole-x4-firmament-v2-semantic-hole-source.md@@ -0,0 +1,47 @@+# HOLE-X4 — Firmament V2 semantic hole source hook++HOLE-X4 adds the smallest Firmament V2 authoring hook for production semantic holes. Source now declares semantic hole intent instead of raw cylinder/cone Boolean tools:++```firmament+modify base {+ hole<shaft> mount {+ on: face(+Z)+ center: [0, 0]+ diameter: 8+ end: throughAll+ }+}+```++Supported variants are exactly:++- `hole<shaft>`+- `hole<counterbore>`+- `hole<countersink>`++Supported placement is face-local on a stable planar face selector or face alias. The X4 materialization tests exercise `face(+Z)` / top-entry placement because the existing AirHole materializer is a rectangular top/bottom profile-stack lane.++Supported end conditions are `end: throughAll` and `end: depth <value>`.++Supported dimensions are explicit scalar fields:++- shaft: `diameter` / `shaftDiameter`, or radius aliases `radius` / `shaftRadius`;+- counterbore: `counterboreDiameter` or `counterboreRadius`, plus `counterboreDepth`;+- countersink: `countersinkDiameter` or `countersinkRadius`, plus `countersinkAngle` in degrees.++The parser stores these declarations as semantic hole AST nodes. Lowering converts those nodes to `AirHoleFeature`:++- `hole<shaft>` -> `AirHoleFeature.CreateSimpleShaft`;+- `hole<counterbore>` -> `AirHoleFeature.CreateCounterbore` with counterbore and shaft stack roles;+- `hole<countersink>` -> `AirHoleFeature.CreateCountersink` with countersink and shaft stack roles.++The parser does not expose raw cylinder/cone Boolean authoring for this path. Profile-stack/BRep objects remain downstream lowering furniture owned by the existing `AirHoleSimpleShaftMaterializer`; Firmament source and AIR preserve semantic hole intent.++Deferred by design: standards and fit libraries, M-size screw tables, threads/taps, drill tips, groups/patterns, up-to-face/up-to-next, arbitrary datum placement, non-planar entry faces, multi-body propagation, raw 3D Boolean source syntax, and STEP/DisplayIR/frontend behavior changes.++Validation commands used for this implementation:++```bash+dotnet build Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj -f net10.0 /m:1+dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj -f net10.0 --no-build --filter "FirmamentV2SemanticHole"+```diff --git a/fixtures/FirmamentV2/Hole/invalid/hole-x4-bad-counterbore.invalid.firmfixture b/fixtures/FirmamentV2/Hole/invalid/hole-x4-bad-counterbore.invalid.firmfixturenew file mode 100644index 00000000..6cb8ed45--- /dev/null+++ b/fixtures/FirmamentV2/Hole/invalid/hole-x4-bad-counterbore.invalid.firmfixture@@ -0,0 +1,10 @@+// fixture-id: hole-x4-bad-counterbore.invalid+// case: hole-x4-bad-counterbore.invalid+// category: Hole+// syntax-version: FirmamentV2+// validity: invalid+// implementation: rejected+// expected: invalid+// expected-diagnostic: firmament-fixture-rejected+// expected-stage: rejected+model HoleX4BadCounterbore { units mm solid base: Box { size: [10, 8, 6] } modify base { hole<counterbore> h { on: face(+Z) center: [0,0] shaftDiameter: 4 counterboreDiameter: 3 counterboreDepth: 1 end: throughAll } } }diff --git a/fixtures/FirmamentV2/Hole/invalid/hole-x4-negative-depth.invalid.firmfixture b/fixtures/FirmamentV2/Hole/invalid/hole-x4-negative-depth.invalid.firmfixturenew file mode 100644index 00000000..5ba69fc0--- /dev/null+++ b/fixtures/FirmamentV2/Hole/invalid/hole-x4-negative-depth.invalid.firmfixture@@ -0,0 +1,10 @@+// fixture-id: hole-x4-negative-depth.invalid+// case: hole-x4-negative-depth.invalid+// category: Hole+// syntax-version: FirmamentV2+// validity: invalid+// implementation: rejected+// expected: invalid+// expected-diagnostic: firmament-fixture-rejected+// expected-stage: rejected+model HoleX4NegativeDepth { units mm solid base: Box { size: [10, 8, 6] } modify base { hole<shaft> h { on: face(+Z) center: [0,0] diameter: 2 end: depth -1 } } }diff --git a/fixtures/FirmamentV2/Hole/invalid/hole-x4-unknown.invalid.firmfixture b/fixtures/FirmamentV2/Hole/invalid/hole-x4-unknown.invalid.firmfixturenew file mode 100644index 00000000..a674169d--- /dev/null+++ b/fixtures/FirmamentV2/Hole/invalid/hole-x4-unknown.invalid.firmfixture@@ -0,0 +1,10 @@+// fixture-id: hole-x4-unknown.invalid+// case: hole-x4-unknown.invalid+// category: Hole+// syntax-version: FirmamentV2+// validity: invalid+// implementation: rejected+// expected: invalid+// expected-diagnostic: firmament-fixture-rejected+// expected-stage: rejected+model HoleX4Unknown { units mm solid base: Box { size: [10, 8, 6] } modify base { hole<tapped> h { on: face(+Z) center: [0,0] diameter: 2 end: throughAll } } }diff --git a/fixtures/FirmamentV2/Hole/valid/hole-x4-counterbore-through.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/hole-x4-counterbore-through.valid.firmfixturenew file mode 100644index 00000000..2875b8e2--- /dev/null+++ b/fixtures/FirmamentV2/Hole/valid/hole-x4-counterbore-through.valid.firmfixture@@ -0,0 +1,22 @@+// fixture-id: hole-x4-counterbore-through.valid+// case: hole-x4-counterbore-through.valid+// category: Hole+// syntax-version: FirmamentV2+// validity: valid+// implementation: parser-backed+// expected: valid+// expected-stage: feature-air+model HoleX4CounterboreThrough {+ units mm+ solid base: Box { size: [100, 60, 12] }+ modify base {+ hole<counterbore> mount {+ on: face(+Z)+ center: [0, 0]+ shaftDiameter: 8+ counterboreDiameter: 14+ counterboreDepth: 5+ end: throughAll+ }+ }+}diff --git a/fixtures/FirmamentV2/Hole/valid/hole-x4-countersink-depth.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/hole-x4-countersink-depth.valid.firmfixturenew file mode 100644index 00000000..654e097b--- /dev/null+++ b/fixtures/FirmamentV2/Hole/valid/hole-x4-countersink-depth.valid.firmfixture@@ -0,0 +1,22 @@+// fixture-id: hole-x4-countersink-depth.valid+// case: hole-x4-countersink-depth.valid+// category: Hole+// syntax-version: FirmamentV2+// validity: valid+// implementation: parser-backed+// expected: valid+// expected-stage: feature-air+model HoleX4CountersinkDepth {+ units mm+ solid base: Box { size: [100, 60, 12] }+ modify base {+ hole<countersink> flatHead {+ on: face(+Z)+ center: [0, 0]+ shaftDiameter: 6+ countersinkDiameter: 12+ countersinkAngle: 82+ end: depth 10+ }+ }+}diff --git a/fixtures/FirmamentV2/Hole/valid/hole-x4-shaft-through.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/hole-x4-shaft-through.valid.firmfixturenew file mode 100644index 00000000..a2d32893--- /dev/null+++ b/fixtures/FirmamentV2/Hole/valid/hole-x4-shaft-through.valid.firmfixture@@ -0,0 +1,20 @@+// fixture-id: hole-x4-shaft-through.valid+// case: hole-x4-shaft-through.valid+// category: Hole+// syntax-version: FirmamentV2+// validity: valid+// implementation: parser-backed+// expected: valid+// expected-stage: feature-air+model HoleX4ShaftThrough {+ units mm+ solid base: Box { size: [100, 60, 12] }+ modify base {+ hole<shaft> mount {+ on: face(+Z)+ center: [0, 0]+ diameter: 8+ end: throughAll+ }+ }+}