Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Consolidate Firmament V2 side-hole route policy
Yuechen Li1a20b497c6dc
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.csindex 93b5abf1..8147888f 100644--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs@@ -1385,6 +1385,50 @@ public sealed class AirTraceCommandTestsAssert.Contains("firmament-v2-side-hole-route-unsupported", Run("trace", "--fixture", FirmamentV2Fixture("Region/invalid/side-hole-alias-z-wrong-through-v2.invalid.firmfixture"), "--json").Stdout);}++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_ManifestContainsPolicyFacts()+ {+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-z-axis-v2.valid.firmfixture"), "--out-dir", dir).ExitCode);+ using var doc = JsonDocument.Parse(File.ReadAllText(Path.Combine(dir, "manifest.json")));+ var route = doc.RootElement.GetProperty("route");+ Assert.Equal("Z", route.GetProperty("axis").GetString());+ Assert.Equal("+Z->-Z", route.GetProperty("direction").GetString());+ Assert.Equal("+Z", route.GetProperty("attachFace").GetString());+ Assert.Equal("-Z", route.GetProperty("throughFace").GetString());+ Assert.Equal("face(+Z):u=+X,v=+Y", route.GetProperty("centerFrame").GetString());+ Assert.Equal("+X", route.GetProperty("uAxis").GetString());+ Assert.Equal("+Y", route.GetProperty("vAxis").GetString());+ Assert.Equal(5, route.GetProperty("uHalfExtent").GetDouble());+ Assert.Equal(4, route.GetProperty("vHalfExtent").GetDouble());+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_TraceJsonContainsPolicyFacts()+ {+ var (exitCode, output, _) = Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-z-axis-v2.valid.firmfixture"), "--json");+ Assert.Equal(0, exitCode);+ using var doc = JsonDocument.Parse(output);+ var route = doc.RootElement.GetProperty("firmamentV2").GetProperty("semanticIntent").GetProperty("routeEvidence");+ Assert.Equal("Z", route.GetProperty("axis").GetString());+ Assert.Equal("+Z->-Z", route.GetProperty("direction").GetString());+ Assert.Equal("+Z", route.GetProperty("attachFace").GetString());+ Assert.Equal("-Z", route.GetProperty("throughFace").GetString());+ Assert.Equal("face(+Z):u=+X,v=+Y", route.GetProperty("centerFrame").GetString());+ Assert.Equal("+X", route.GetProperty("uAxis").GetString());+ Assert.Equal("+Y", route.GetProperty("vAxis").GetString());+ Assert.Equal(5, route.GetProperty("uHalfExtent").GetDouble());+ Assert.Equal(4, route.GetProperty("vHalfExtent").GetDouble());+ }++ [Fact]+ public void DefaultActiveTests_DoNotRequireCorpusOrLegacy()+ {+ Assert.True(string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("AETHERIS_RUN_LEGACY_TESTS")) || Environment.GetEnvironmentVariable("AETHERIS_RUN_LEGACY_TESTS") == "0");+ Assert.True(string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("AETHERIS_RUN_CORPUS_TESTS")) || Environment.GetEnvironmentVariable("AETHERIS_RUN_CORPUS_TESTS") == "0");+ }+private static (int ExitCode, string Stdout, string Stderr) Run(params string[] args){var stdout = new StringWriter(); var stderr = new StringWriter();diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.csindex bac95423..da5ec812 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs@@ -608,6 +608,117 @@ public sealed class FirmamentV2ParserTestsAssert.Contains(FirmamentV2Parser.SideHoleRouteUnsupported, FirmamentV2Parser.Parse(Source("Region/invalid/side-hole-alias-z-wrong-through-v2.invalid.firmfixture")).Diagnostics);}++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_AllSixRoutesAreSupported()+ {+ var size = new double[] { 10, 8, 6 };+ foreach (var (attach, through) in new[] { ("+X", "-X"), ("-X", "+X"), ("+Y", "-Y"), ("-Y", "+Y"), ("+Z", "-Z"), ("-Z", "+Z") })+ {+ var result = FirmamentV2SideHoleRoutePolicy.Resolve(attach, through, size, radius: 1);+ Assert.True(result.IsSupported, $"{attach}->{through}: {result.Diagnostic}");+ Assert.Equal($"{attach}->{through}", result.Route!.Direction);+ }+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_RouteFramesAreCorrect()+ {+ var size = new double[] { 10, 8, 6 };+ Assert.Equal(("+Y", "+Z", "face(+X):u=+Y,v=+Z"), Frame("+X", "-X"));+ Assert.Equal(("+Y", "+Z", "face(-X):u=+Y,v=+Z"), Frame("-X", "+X"));+ Assert.Equal(("+X", "+Z", "face(+Y):u=+X,v=+Z"), Frame("+Y", "-Y"));+ Assert.Equal(("+X", "+Z", "face(-Y):u=+X,v=+Z"), Frame("-Y", "+Y"));+ Assert.Equal(("+X", "+Y", "face(+Z):u=+X,v=+Y"), Frame("+Z", "-Z"));+ Assert.Equal(("+X", "+Y", "face(-Z):u=+X,v=+Y"), Frame("-Z", "+Z"));++ (string U, string V, string CenterFrame) Frame(string attach, string through)+ {+ var route = FirmamentV2SideHoleRoutePolicy.Resolve(attach, through, size, radius: 1).Route!;+ return (route.UAxis, route.VAxis, route.CenterFrame);+ }+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_ClearanceUsesCorrectHalfExtents()+ {+ var size = new double[] { 10, 8, 6 };+ Assert.Equal((4, 3), Extents("+X", "-X"));+ Assert.Equal((4, 3), Extents("-X", "+X"));+ Assert.Equal((5, 3), Extents("+Y", "-Y"));+ Assert.Equal((5, 3), Extents("-Y", "+Y"));+ Assert.Equal((5, 4), Extents("+Z", "-Z"));+ Assert.Equal((5, 4), Extents("-Z", "+Z"));++ (double U, double V) Extents(string attach, string through)+ {+ var route = FirmamentV2SideHoleRoutePolicy.Resolve(attach, through, size, radius: 1).Route!;+ return (route.UHalfExtent, route.VHalfExtent);+ }+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_RejectsSameFace()+ {+ var result = FirmamentV2SideHoleRoutePolicy.Resolve("+X", "+X", new double[] { 10, 8, 6 }, radius: 1);+ Assert.False(result.IsSupported);+ Assert.Equal(FirmamentV2Parser.SideHoleSameFaceUnsupported, result.Diagnostic);+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_RejectsMixedAxis()+ {+ var result = FirmamentV2SideHoleRoutePolicy.Resolve("+Z", "+X", new double[] { 10, 8, 6 }, radius: 1);+ Assert.False(result.IsSupported);+ Assert.Equal(FirmamentV2Parser.SideHoleRouteUnsupported, result.Diagnostic);+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_RejectsCenterBoundary()+ {+ var result = FirmamentV2SideHoleRoutePolicy.Resolve("+Z", "-Z", new double[] { 10, 8, 6 }, radius: 1, centerU: 4, centerV: 0);+ Assert.False(result.IsSupported);+ Assert.Equal(FirmamentV2Parser.SideHoleCenterExceedsClearance, result.Diagnostic);+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_DirectFixturesStillGreen()+ {+ foreach (var fixture in new[] { "Region/valid/side-hole-v2.valid.firmfixture", "Region/valid/side-hole-y-axis-v2.valid.firmfixture", "Region/valid/side-hole-z-axis-v2.valid.firmfixture" })+ {+ var result = FirmamentFrontendTraceProbe.ParseV2Only(Source(fixture));+ Assert.True(result.ParseSucceeded, fixture + ": " + string.Join(", ", result.Diagnostics));+ Assert.Equal("Integrated", result.FirmamentV2!.ParentIntegration);+ Assert.Equal("Closed", result.FirmamentV2.ShellClosure);+ Assert.Equal("Succeeded", result.FirmamentV2.StepSmoke);+ }+ }++ [Fact]+ public void FirmamentV2SideHoleRoutePolicy_AliasFixturesStillGreen()+ {+ foreach (var fixture in new[] { "Region/valid/side-hole-aliases-v2.valid.firmfixture", "Region/valid/side-hole-aliases-y-axis-v2.valid.firmfixture", "Region/valid/side-hole-aliases-z-axis-v2.valid.firmfixture" })+ {+ var result = FirmamentFrontendTraceProbe.ParseV2Only(Source(fixture));+ Assert.True(result.ParseSucceeded, fixture + ": " + string.Join(", ", result.Diagnostics));+ Assert.Equal("Integrated", result.FirmamentV2!.ParentIntegration);+ Assert.Equal("Closed", result.FirmamentV2.ShellClosure);+ Assert.Equal("Succeeded", result.FirmamentV2.StepSmoke);+ }+ }++ [Fact]+ public void FirmamentV2_AllPriorSideHoleMilestonesRemainGreen()+ {+ foreach (var fixture in Directory.EnumerateFiles(Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Region/valid")), "side-hole*.valid.firmfixture"))+ {+ var lines = File.ReadAllLines(fixture);+ var bodyStart = Array.FindIndex(lines, line => !string.IsNullOrWhiteSpace(line) && !line.TrimStart().StartsWith("//", StringComparison.Ordinal));+ var result = FirmamentFrontendTraceProbe.ParseV2Only(string.Join(Environment.NewLine, lines.Skip(Math.Max(0, bodyStart))));+ Assert.True(result.ParseSucceeded, Path.GetFileName(fixture) + ": " + string.Join(", ", result.Diagnostics));+ }+ }+private static string Source(string relative){var path = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2", relative));diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.csindex bda06861..8711417f 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs@@ -3,7 +3,12 @@ namespace Aetheris.Kernel.Firmament.FirmamentV2;public sealed record FirmamentV2Document(string ModelName, string Units, IReadOnlyList<FirmamentV2SolidBinding> Solids, IReadOnlyList<FirmamentV2ModifyBlock>? ModifyBlocks = null){public FirmamentV2SolidBinding Solid => Solids[^1];- public FirmamentV2SideHoleIntent? SideHoleIntent => ModifyBlocks?.SelectMany(m => m.Regions.Select(r => new FirmamentV2SideHoleIntent(m.TargetSolid, r.Name, r.Attachment.Source, r.Attachment.Kind, r.Attachment.Axis, r.Cut.Tool.Through.Source, r.Cut.Tool.Through.Kind, r.Cut.Tool.Through.Axis, r.Cut.Tool.ToolType, r.Cut.Tool.Radius, r.Cut.Tool.Center?.U ?? 0, r.Cut.Tool.Center?.V ?? 0, r.Cut.Tool.Center is not null, FirmamentV2FaceLocalPoint2D.ConventionFor(r.Attachment.Axis), Units))).SingleOrDefault();+ public FirmamentV2SideHoleIntent? SideHoleIntent => ModifyBlocks?.SelectMany(m => m.Regions.Select(r =>+ {+ var targetSolid = Solids.Single(s => string.Equals(s.Name, m.TargetSolid, StringComparison.Ordinal));+ var route = FirmamentV2SideHoleRoutePolicy.Resolve(r.Attachment.Axis, r.Cut.Tool.Through.Axis, targetSolid.Box.Size, r.Cut.Tool.Radius, r.Cut.Tool.Center?.U ?? 0, r.Cut.Tool.Center?.V ?? 0).Route!;+ return new FirmamentV2SideHoleIntent(m.TargetSolid, r.Name, r.Attachment.Source, r.Attachment.Kind, r.Attachment.Axis, r.Cut.Tool.Through.Source, r.Cut.Tool.Through.Kind, r.Cut.Tool.Through.Axis, r.Cut.Tool.ToolType, r.Cut.Tool.Radius, r.Cut.Tool.Center?.U ?? 0, r.Cut.Tool.Center?.V ?? 0, r.Cut.Tool.Center is not null, route.CenterFrame, Units, route);+ })).SingleOrDefault();}public sealed record FirmamentV2SolidBinding(string Name, string RecordType, FirmamentV2BoxRecord Box, string? DerivedFrom = null, IReadOnlyDictionary<string, IReadOnlyList<double>>? Overrides = null)@@ -45,12 +50,11 @@ public sealed record FirmamentV2FaceLocalPoint2D(double U, double V, string Conv_ => PlusXConvention};}-public sealed record FirmamentV2SideHoleIntent(string TargetSolid, string RegionName, string AttachTargetSource, string AttachTargetKind, string AttachFace, string ThroughTargetSource, string ThroughTargetKind, string ThroughFace, string Tool, double Radius, double CenterU, double CenterV, bool CenterExplicit, string CenterSelectorFrame, string Units)+public sealed record FirmamentV2SideHoleIntent(string TargetSolid, string RegionName, string AttachTargetSource, string AttachTargetKind, string AttachFace, string ThroughTargetSource, string ThroughTargetKind, string ThroughFace, string Tool, double Radius, double CenterU, double CenterV, bool CenterExplicit, string CenterSelectorFrame, string Units, FirmamentV2SideHoleRoutePolicyEvidence PolicyRoute){- public string Route => $"{AttachFace}->{ThroughFace}";- public FirmamentV2SideHoleRouteEvidence RouteEvidence => new(AttachFace.Length == 2 ? AttachFace[1].ToString() : string.Empty, Route, AttachFace, ThroughFace);+ public string Route => PolicyRoute.Direction;+ public FirmamentV2SideHoleRoutePolicyEvidence RouteEvidence => PolicyRoute;}-public sealed record FirmamentV2SideHoleRouteEvidence(string Axis, string Direction, string AttachFace, string ThroughFace);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 112815c3..4b9a1c11 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs@@ -237,30 +237,15 @@ public static class FirmamentV2Parserif (close < 0) { diagnostics.Add(RegionUnsupported); return null; }var cut = ParseCut(body[(open + 1)..close], solid, diagnostics);if (attach is null || cut is null) return null;- var supportedCanonical = attach.Axis == "+X" && cut.Tool.Through.Axis == "-X";- var supportedReverseX = attach.Axis == "-X" && cut.Tool.Through.Axis == "+X";- var supportedY = (attach.Axis == "+Y" && cut.Tool.Through.Axis == "-Y") || (attach.Axis == "-Y" && cut.Tool.Through.Axis == "+Y");- var supportedZ = (attach.Axis == "+Z" && cut.Tool.Through.Axis == "-Z") || (attach.Axis == "-Z" && cut.Tool.Through.Axis == "+Z");- if (!supportedCanonical && !supportedReverseX && !supportedY && !supportedZ)+ var centerU = cut.Tool.Center?.U ?? 0;+ var centerV = cut.Tool.Center?.V ?? 0;+ var route = FirmamentV2SideHoleRoutePolicy.Resolve(attach.Axis, cut.Tool.Through.Axis, solid.Box.Size, cut.Tool.Radius, centerU, centerV);+ if (!route.IsSupported){- if (attach.Axis == cut.Tool.Through.Axis) diagnostics.Add(SideHoleSameFaceUnsupported);- else if (AxisName(attach.Axis) != AxisName(cut.Tool.Through.Axis)) diagnostics.Add(SideHoleRouteUnsupported);- else diagnostics.Add(SideHoleRouteUnsupported);- if (attach.Kind == "Alias" || cut.Tool.Through.Kind == "Alias") diagnostics.Add(SideHoleAliasResolvesToUnsupportedFace);+ diagnostics.Add(route.Diagnostic!);+ if (route.Diagnostic is SideHoleRouteUnsupported && (attach.Kind == "Alias" || cut.Tool.Through.Kind == "Alias")) diagnostics.Add(SideHoleAliasResolvesToUnsupportedFace);diagnostics.Add(SideHoleOnlyPlusXMinusXSupported);}- var axis = AxisName(attach.Axis);- var uHalfExtent = axis switch- {- "Y" => solid.Box.Size[0] / 2.0,- "Z" => solid.Box.Size[0] / 2.0,- _ => solid.Box.Size[1] / 2.0- };- var vHalfExtent = axis == "Z" ? solid.Box.Size[1] / 2.0 : solid.Box.Size[2] / 2.0;- if (cut.Tool.Radius >= Math.Min(uHalfExtent, vHalfExtent)) diagnostics.Add(SideHoleRadiusExceedsClearance);- var centerU = cut.Tool.Center?.U ?? 0;- var centerV = cut.Tool.Center?.V ?? 0;- if (Math.Abs(centerU) + cut.Tool.Radius >= uHalfExtent || Math.Abs(centerV) + cut.Tool.Radius >= vHalfExtent) diagnostics.Add(SideHoleCenterExceedsClearance);return diagnostics.Any(IsFatalDiagnostic) ? null : new(rm.Groups["name"].Value, "FaceAttachedRegion", attach, cut);}@@ -297,7 +282,6 @@ public static class FirmamentV2Parserreturn new FirmamentV2FaceLocalPoint2D(u, v, string.Empty);}- private static string AxisName(string faceAxis) => faceAxis.Length == 2 ? faceAxis[1].ToString() : string.Empty;private static FirmamentV2FaceSelector? ParseFaceSelector(string selector, string diagnostic, List<string> diagnostics){diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SideHoleRoutePolicy.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SideHoleRoutePolicy.csnew file mode 100644index 00000000..44a1b1a9--- /dev/null+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SideHoleRoutePolicy.cs@@ -0,0 +1,84 @@+namespace Aetheris.Kernel.Firmament.FirmamentV2;++public static class FirmamentV2SideHoleRoutePolicy+{+ public const string RouteUnsupportedDiagnostic = "firmament-v2-side-hole-route-unsupported";+ public const string SameFaceUnsupportedDiagnostic = "firmament-v2-side-hole-same-face-unsupported";+ public const string CenterExceedsClearanceDiagnostic = "firmament-v2-side-hole-center-exceeds-clearance";+ public const string RadiusExceedsClearanceDiagnostic = "firmament-v2-side-hole-radius-exceeds-clearance";++ private static readonly IReadOnlyDictionary<string, RouteDefinition> Routes = new Dictionary<string, RouteDefinition>(StringComparer.Ordinal)+ {+ ["+X->-X"] = new("X", "+X", "-X", "face(+X):u=+Y,v=+Z", "+Y", "+Z", BoxDimension.Y, BoxDimension.Z),+ ["-X->+X"] = new("X", "-X", "+X", "face(-X):u=+Y,v=+Z", "+Y", "+Z", BoxDimension.Y, BoxDimension.Z),+ ["+Y->-Y"] = new("Y", "+Y", "-Y", "face(+Y):u=+X,v=+Z", "+X", "+Z", BoxDimension.X, BoxDimension.Z),+ ["-Y->+Y"] = new("Y", "-Y", "+Y", "face(-Y):u=+X,v=+Z", "+X", "+Z", BoxDimension.X, BoxDimension.Z),+ ["+Z->-Z"] = new("Z", "+Z", "-Z", "face(+Z):u=+X,v=+Y", "+X", "+Y", BoxDimension.X, BoxDimension.Y),+ ["-Z->+Z"] = new("Z", "-Z", "+Z", "face(-Z):u=+X,v=+Y", "+X", "+Y", BoxDimension.X, BoxDimension.Y),+ };++ public static IReadOnlyList<string> SupportedDirections => Routes.Keys.Order(StringComparer.Ordinal).ToArray();++ public static FirmamentV2SideHoleRoutePolicyResult Resolve(string attachFace, string throughFace, IReadOnlyList<double> boxSize, double radius, double centerU = 0, double centerV = 0)+ {+ ArgumentNullException.ThrowIfNull(attachFace);+ ArgumentNullException.ThrowIfNull(throughFace);+ ArgumentNullException.ThrowIfNull(boxSize);+ if (boxSize.Count != 3) throw new ArgumentException("Box size must contain X, Y, and Z dimensions.", nameof(boxSize));++ var direction = Direction(attachFace, throughFace);+ if (!Routes.TryGetValue(direction, out var route))+ {+ var diagnostic = string.Equals(attachFace, throughFace, StringComparison.Ordinal)+ ? SameFaceUnsupportedDiagnostic+ : RouteUnsupportedDiagnostic;+ return FirmamentV2SideHoleRoutePolicyResult.Rejected(diagnostic, direction);+ }++ var uHalfExtent = HalfExtent(boxSize, route.UHalfExtentDimension);+ var vHalfExtent = HalfExtent(boxSize, route.VHalfExtentDimension);+ var evidence = new FirmamentV2SideHoleRoutePolicyEvidence(+ route.Axis,+ direction,+ route.AttachFace,+ route.ThroughFace,+ route.CenterFrame,+ route.UAxis,+ route.VAxis,+ uHalfExtent,+ vHalfExtent);++ if (radius >= Math.Min(uHalfExtent, vHalfExtent))+ return FirmamentV2SideHoleRoutePolicyResult.Rejected(RadiusExceedsClearanceDiagnostic, direction, evidence);++ if (!HasStrictClearance(centerU, centerV, radius, uHalfExtent, vHalfExtent))+ return FirmamentV2SideHoleRoutePolicyResult.Rejected(CenterExceedsClearanceDiagnostic, direction, evidence);++ return FirmamentV2SideHoleRoutePolicyResult.Supported(evidence);+ }++ public static bool HasStrictClearance(double centerU, double centerV, double radius, double uHalfExtent, double vHalfExtent) =>+ Math.Abs(centerU) + radius < uHalfExtent && Math.Abs(centerV) + radius < vHalfExtent;++ public static FirmamentV2SideHoleRoutePolicyEvidence? EvidenceFor(string attachFace, string throughFace, IReadOnlyList<double> boxSize)+ {+ var result = Resolve(attachFace, throughFace, boxSize, 0);+ return result.Route;+ }++ private static string Direction(string attachFace, string throughFace) => $"{attachFace}->{throughFace}";++ private static double HalfExtent(IReadOnlyList<double> boxSize, BoxDimension dimension) => boxSize[(int)dimension] / 2.0;++ private enum BoxDimension { X = 0, Y = 1, Z = 2 }++ private sealed record RouteDefinition(string Axis, string AttachFace, string ThroughFace, string CenterFrame, string UAxis, string VAxis, BoxDimension UHalfExtentDimension, BoxDimension VHalfExtentDimension);+}++public sealed record FirmamentV2SideHoleRoutePolicyEvidence(string Axis, string Direction, string AttachFace, string ThroughFace, string CenterFrame, string UAxis, string VAxis, double UHalfExtent, double VHalfExtent);++public sealed record FirmamentV2SideHoleRoutePolicyResult(bool IsSupported, string? Diagnostic, string Direction, FirmamentV2SideHoleRoutePolicyEvidence? Route)+{+ public static FirmamentV2SideHoleRoutePolicyResult Supported(FirmamentV2SideHoleRoutePolicyEvidence route) => new(true, null, route.Direction, route);+ public static FirmamentV2SideHoleRoutePolicyResult Rejected(string diagnostic, string direction, FirmamentV2SideHoleRoutePolicyEvidence? route = null) => new(false, diagnostic, direction, route);+}diff --git a/docs/air-firmament-x10-v2-side-hole-y-axis.md b/docs/air-firmament-x10-v2-side-hole-y-axis.mdindex e666d300..3d762341 100644--- a/docs/air-firmament-x10-v2-side-hole-y-axis.md+++ b/docs/air-firmament-x10-v2-side-hole-y-axis.md@@ -94,3 +94,7 @@ AIR-FIRMAMENT-X11 — controlled V2 side-hole Z-axis face-pair variation. X11 mu## X11 follow-upAIR-FIRMAMENT-X11 extends the same controlled opposite-face policy to Z-axis routes (`+Z -> -Z` and `-Z -> +Z`) and preserves the X10 Y-axis route evidence and clearance behavior.++## X12 follow-up++AIR-FIRMAMENT-X12 keeps the Y-axis routes unchanged and moves their route/frame/clearance facts into `FirmamentV2SideHoleRoutePolicy`; see `docs/air-firmament-x12-side-hole-route-policy.md`.diff --git a/docs/air-firmament-x11-v2-side-hole-z-axis.md b/docs/air-firmament-x11-v2-side-hole-z-axis.mdindex a5f16e6a..3e9c5fb9 100644--- a/docs/air-firmament-x11-v2-side-hole-z-axis.md+++ b/docs/air-firmament-x11-v2-side-hole-z-axis.md@@ -116,3 +116,7 @@ This does not prove mixed-axis support, same-face support, blind holes, oblique## Next milestone recommendationAIR-FIRMAMENT-X12 should consolidate controlled opposite-face side-hole route policy into a central route/frame/admissibility table rather than adding more feature surface area.++## X12 follow-up++AIR-FIRMAMENT-X12 consolidates the six X4-X11 controlled opposite-face side-hole routes into `FirmamentV2SideHoleRoutePolicy`; see `docs/air-firmament-x12-side-hole-route-policy.md` for the central route/frame/clearance table.diff --git a/docs/air-firmament-x12-side-hole-route-policy.md b/docs/air-firmament-x12-side-hole-route-policy.mdnew file mode 100644index 00000000..6302890d--- /dev/null+++ b/docs/air-firmament-x12-side-hole-route-policy.md@@ -0,0 +1,92 @@+# AIR-FIRMAMENT-X12 — V2 side-hole route policy++## Purpose and scope++AIR-FIRMAMENT-X12 centralizes the controlled Firmament V2 side-hole route, frame, and clearance rules into `FirmamentV2SideHoleRoutePolicy`. Scope is deliberately limited to parser-backed V2 side-hole cuts through `Box` target solids.++## Relationship to X4-X11++X4 introduced the canonical `+X -> -X` route. X5 locked artifact reporting. X6 added radius variation. X7 added center offsets. X8 allowed FaceRef aliases as feature targets. X9, X10, and X11 added reverse-X, Y-axis, and Z-axis opposite-face routes. X12 does not add a seventh route; it consolidates the six routes already proven by X4-X11.++## Why consolidation is needed++Before X12, route support checks, face-local center frame strings, transverse extents, clearance checks, trace facts, and manifest facts were spread across parser and intent/reporting code. X12 makes the route table the source of truth so future route changes do not require duplicating axis-specific conditionals.++## Supported route table++| Route | Axis | Attach face | Through face | u axis | v axis | u half extent | v half extent |+| --- | --- | --- | --- | --- | --- | --- | --- |+| `+X -> -X` | X | `+X` | `-X` | `+Y` | `+Z` | Y/2 | Z/2 |+| `-X -> +X` | X | `-X` | `+X` | `+Y` | `+Z` | Y/2 | Z/2 |+| `+Y -> -Y` | Y | `+Y` | `-Y` | `+X` | `+Z` | X/2 | Z/2 |+| `-Y -> +Y` | Y | `-Y` | `+Y` | `+X` | `+Z` | X/2 | Z/2 |+| `+Z -> -Z` | Z | `+Z` | `-Z` | `+X` | `+Y` | X/2 | Y/2 |+| `-Z -> +Z` | Z | `-Z` | `+Z` | `+X` | `+Y` | X/2 | Y/2 |++For the canonical `Box [10, 8, 6]`, X/2 is 5, Y/2 is 4, and Z/2 is 3.++## Face-local frame table++| Attach face | Center frame |+| --- | --- |+| `+X` | `face(+X):u=+Y,v=+Z` |+| `-X` | `face(-X):u=+Y,v=+Z` |+| `+Y` | `face(+Y):u=+X,v=+Z` |+| `-Y` | `face(-Y):u=+X,v=+Z` |+| `+Z` | `face(+Z):u=+X,v=+Y` |+| `-Z` | `face(-Z):u=+X,v=+Y` |++## Clearance rule++All supported routes use the same strict clearance predicate:++```text+abs(centerU) + radius < uHalfExtent+abs(centerV) + radius < vHalfExtent+```++Equality is rejected. Radius-only clearance is also checked against the smaller transverse half extent.++## Route rejection policy++The policy returns stable diagnostics:++- same attach/through face: `firmament-v2-side-hole-same-face-unsupported`+- mixed-axis or otherwise unsupported route: `firmament-v2-side-hole-route-unsupported`+- radius too large for the route frame: `firmament-v2-side-hole-radius-exceeds-clearance`+- center at or beyond route clearance: `firmament-v2-side-hole-center-exceeds-clearance`++Alias resolution diagnostics remain in parser alias handling because the route policy only receives resolved face facts.++## JudgmentEngine decision++JudgmentEngine is **not used** in X12. The route decision is deterministic lookup in a six-row table plus deterministic clearance predicates. A JudgmentEngine layer would add scoring ceremony without competing interpretations, and AGENTS.md guidance says not to use JudgmentEngine for simple deterministic transformations or ordinary dispatch.++## Trace/manifest route policy evidence++`FirmamentV2SideHoleIntent.RouteEvidence` now exposes normalized policy facts: axis, direction, attach/through faces, center frame, u/v axes, and u/v half extents. Trace JSON serializes this under `firmamentV2.semanticIntent.routeEvidence`; artifact manifests serialize the same evidence under `route`. Existing route, attach face, through face, and center frame fields remain available for compatibility.++## Fixtures/tests covered++The X12 tests cover policy resolution for all six routes, frame and half-extent correctness, same-face rejection, mixed-axis rejection, strict center-boundary rejection, direct X/Y/Z golden paths, alias X/Y/Z golden paths, manifest policy facts, trace JSON policy facts, and prior X4-X11 side-hole fixture success.++## What this proves++X12 proves route/frame/admissibility policy is centralized for controlled Firmament V2 Box side-hole routes and that parser semantic validation, semantic intent, trace JSON, and artifact manifest facts consume the same resolved route policy evidence.++## What this does not prove++X12 does not prove mixed-axis routes, same-face routes, blind holes, oblique holes, non-box target solids, arbitrary center frames, general Boolean admission, multiple cuts, multiple regions, or reusable non-side-hole prismatic through-cut admission.++## Tests run++- `dotnet restore Aetheris.slnx`+- `dotnet build Aetheris.slnx -f net10.0 --no-restore`+- `./scripts/test-active.sh`+- targeted kernel and CLI Firmament V2 side-hole filters+- CLI trace spot checks for X, reverse-X, Y, Z, and mixed-axis invalid fixtures+- artifact spot check for Z-axis side-hole manifest evidence++## Next milestone recommendation++AIR-FIRMAMENT-X13 — transition side-hole route policy into reusable prismatic through-cut policy.diff --git a/docs/air-firmament-x7-v2-side-hole-center-offset.md b/docs/air-firmament-x7-v2-side-hole-center-offset.mdindex 09adef7f..6c62293c 100644--- a/docs/air-firmament-x7-v2-side-hole-center-offset.md+++ b/docs/air-firmament-x7-v2-side-hole-center-offset.md@@ -78,3 +78,7 @@ X10 note: controlled Y-face frames are now `face(+Y): u=+X, v=+Z` and `face(-Y):## X11 center-frame extensionAIR-FIRMAMENT-X11 adds Z-face local frames: `face(+Z): u=+X, v=+Y` and `face(-Z): u=+X, v=+Y`. Existing X/Y center-frame conventions remain unchanged.++## X12 follow-up++AIR-FIRMAMENT-X12 keeps the strict center-clearance rule and centralizes the face-local center frames and transverse half extents in `FirmamentV2SideHoleRoutePolicy`; see `docs/air-firmament-x12-side-hole-route-policy.md`.