Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Support construction-plane hole placement and inspection

Yuechen Lidd85af032f12
diff --git a/Aetheris.CLI.Tests/FirmamentV2SideHoleRealExporterPipelineTests.cs b/Aetheris.CLI.Tests/FirmamentV2SideHoleRealExporterPipelineTests.cs
index d08f1db3..536e52f6 100644
--- a/Aetheris.CLI.Tests/FirmamentV2SideHoleRealExporterPipelineTests.cs
+++ b/Aetheris.CLI.Tests/FirmamentV2SideHoleRealExporterPipelineTests.cs
@@ -60,6 +60,23 @@ public sealed class FirmamentV2SideHoleRealExporterPipelineTests
Assert.InRange(Math.Abs(volume.Volume - expectedVolume), 0d, 1e-8);
}
+ [Fact]
+ public void ConstructionPlaneHole_AnalyticVolumeCountsOnePartitionedPhysicalCylinder()
+ {
+ var root = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../"));
+ var fixture = Path.Combine(root, "fixtures", "FirmamentV2", "Hole", "valid", "construction-plane-through-hole.firmament");
+ var stepPath = Path.Combine(Path.GetTempPath(), "aetheris-construction-plane-hole-" + Guid.NewGuid().ToString("N") + ".step");
+ var stdout = new StringWriter(); var stderr = new StringWriter();
+
+ Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["build", fixture, "--out", stepPath, "--json"], stdout, stderr));
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+
+ Assert.True(volume.Success, "construction-plane source reaches independent STEP volume analysis");
+ Assert.True(volume.Exact);
+ Assert.Equal("analytic-box-minus-x-hole", volume.Method);
+ Assert.Equal(72000d - Math.PI * 4d * 4d * 100d, volume.Volume, 8);
+ }
+
private static int CountStepEntities(string stepText, string entityName) =>
Regex.Matches(stepText, "=\\s*" + Regex.Escape(entityName) + "\\s*\\(", RegexOptions.CultureInvariant).Count;
}
diff --git a/Aetheris.CLI.Tests/InspectSelectionsTests.cs b/Aetheris.CLI.Tests/InspectSelectionsTests.cs
index 0db6bfe4..fa64a7be 100644
--- a/Aetheris.CLI.Tests/InspectSelectionsTests.cs
+++ b/Aetheris.CLI.Tests/InspectSelectionsTests.cs
@@ -20,6 +20,29 @@ public sealed class InspectSelectionsTests
Assert.Equal("EdgeFinish", selection.GetProperty("consumer").GetString());
}
+ [Fact]
+ public void InspectSelections_ReportsConstructionPlaneHoleSourceToPlanEvidence()
+ {
+ var root = FindRepoRoot();
+ var source = Path.Combine(root, "fixtures", "FirmamentV2", "Hole", "valid", "construction-plane-through-hole.firmament");
+ var stdout = new StringWriter(); var stderr = new StringWriter();
+
+ var exit = Aetheris.CLI.CliRunner.Run(["inspect-selections", source, "--json"], stdout, stderr);
+
+ Assert.Equal(0, exit); Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()), stderr.ToString());
+ using var json = JsonDocument.Parse(stdout.ToString());
+ var summary = json.RootElement.GetProperty("summary");
+ Assert.Equal("ConstructionPlane", summary.GetProperty("placementKind").GetString());
+ Assert.Equal("construction:PositiveXWorkplane", summary.GetProperty("constructionPlaneId").GetString());
+ Assert.Equal("concept:SideLayout.PositiveXDatum", summary.GetProperty("sourceConceptPlaneId").GetString());
+ Assert.Equal("ThroughAll", summary.GetProperty("extent").GetString());
+ Assert.Equal(100, summary.GetProperty("hostInterval")[1].GetDouble());
+ Assert.Equal("LocalFrameHoleBRepPlan", json.RootElement.GetProperty("plan").GetProperty("kind").GetString());
+ Assert.Contains(json.RootElement.GetProperty("descendants").EnumerateArray(), descendant => descendant.GetProperty("role").GetString() == "HoleExitLoop");
+ Assert.Equal(2, json.RootElement.GetProperty("descendants").EnumerateArray().Count(descendant => descendant.GetProperty("role").GetString() == "HoleWallFace"));
+ Assert.All(json.RootElement.GetProperty("selectionResults").EnumerateArray(), result => Assert.True(result.GetProperty("succeeded").GetBoolean()));
+ }
+
private static string FindRepoRoot()
{
var directory = new DirectoryInfo(AppContext.BaseDirectory);
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index d35053a0..0e78b300 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -501,6 +501,7 @@ public static class CliRunner
if (args.Length == 0 || IsHelpFlag(args[0])) { stdout.WriteLine(InspectSelectionsUsage); return args.Length == 0 ? 1 : 0; }
if (args.Length != 2 || args[1] != "--json") { stderr.WriteLine(InspectSelectionsUsage); return 1; }
if (!File.Exists(args[0])) { stderr.WriteLine($"Selection source was not found: {args[0]}"); return 1; }
+ var totalClock = Stopwatch.StartNew();
var source = File.ReadAllText(args[0]);
if (PrismaticProfileCompositionParser.IsCompositionSource(source))
{
@@ -519,12 +520,44 @@ public static class CliRunner
}, JsonOptions));
return composeDiagnostics.Count == 0 && composeParseDiagnostics.Count == 0 && composeResults.All(x => x.Succeeded) ? 0 : 1;
}
+ var parseClock = Stopwatch.StartNew();
var v2 = FirmamentV2Parser.Parse(source, Path.GetDirectoryName(Path.GetFullPath(args[0])));
+ parseClock.Stop();
if (v2.IsSuccess && v2.Document is not null && v2.Document.ModifyBlocks?.SelectMany(x => x.SemanticHoles).Any() == true)
{
+ var inspectClock = Stopwatch.StartNew();
var hole = SemanticHoleInspection.Inspect(v2.Document);
+ inspectClock.Stop();
if (!hole.Succeeded || hole.Correspondence is null) { stderr.WriteLine(string.Join(Environment.NewLine, hole.Diagnostics)); return 1; }
- stdout.WriteLine(JsonSerializer.Serialize(new { body = hole.Correspondence.BodyStableId, hole = hole.HoleId, descendants = hole.Correspondence.Descendants.Select(x => new { x.StableId, x.Kind, role = x.Role.ToString(), x.SourceStableId, x.ParentStableId }), provenance = hole.Correspondence.ProvenanceChain, diagnostics = hole.Diagnostics }, JsonOptions));
+ var selectionResults = new[]
+ {
+ new SemanticSelectionRequest("inspect:mouth-loop", "MouthLoop", hole.Correspondence.BodyStableId, [hole.HoleId!], SemanticTopologyRole.HoleEntryLoop, SemanticSelectionRequirement.ClosedLoop, "inspect-selections"),
+ new SemanticSelectionRequest("inspect:exit-loop", "ExitLoop", hole.Correspondence.BodyStableId, [hole.HoleId!], SemanticTopologyRole.HoleExitLoop, SemanticSelectionRequirement.ClosedLoop, "inspect-selections"),
+ new SemanticSelectionRequest("inspect:shaft-wall-faces", "ShaftWallFaces", hole.Correspondence.BodyStableId, [hole.HoleId!], SemanticTopologyRole.HoleWallFace, SemanticSelectionRequirement.NonEmptyFaceSet, "inspect-selections")
+ }.Select(request => SemanticTopologySelectionResolver.Resolve(hole.Body!, hole.Correspondence, request)).ToArray();
+ totalClock.Stop();
+ stdout.WriteLine(JsonSerializer.Serialize(new
+ {
+ body = hole.Correspondence.BodyStableId,
+ hole = hole.HoleId,
+ sourceDeclaration = new { kind = "Hole<Shaft>", featureId = hole.HoleId, sourceSpan = hole.Evidence?.SourceSpan },
+ boundPlacement = hole.Evidence is null ? null : new { kind = hole.Evidence.PlacementKind, hole.Evidence.ConstructionPlaneId, hole.Evidence.SourceConceptPlaneId, hole.Evidence.LocalCenter },
+ airPlacement = hole.Evidence is null ? null : new { kind = hole.Evidence.PlacementKind == "ConstructionPlane" ? "AirConstructionPlaneHolePlacement" : "AirFaceLocalHolePlacement", featureId = hole.Evidence.FeatureId, hole.Evidence.ConstructionPlaneId, hole.Evidence.LocalCenter },
+ plan = hole.Evidence?.PlanId is null ? null : new { kind = "LocalFrameHoleBRepPlan", stableId = hole.Evidence.PlanId, hostInterval = hole.Evidence.HostInterval },
+ summary = hole.Evidence is null ? null : new
+ {
+ hole.Evidence.FeatureId, hole.Evidence.PlacementKind, hole.Evidence.ConstructionPlaneId, hole.Evidence.SourceConceptPlaneId,
+ frameOrigin = hole.Evidence.FrameOrigin, axisX = hole.Evidence.AxisX, axisY = hole.Evidence.AxisY, axisZ = hole.Evidence.AxisZ,
+ localCenter = hole.Evidence.LocalCenter, worldMouthCenter = hole.Evidence.WorldMouthCenter,
+ hole.Evidence.Diameter, hole.Evidence.Radius, extent = hole.Evidence.Extent, hostInterval = hole.Evidence.HostInterval,
+ hole.Evidence.PlanId, hole.Evidence.SourceSpan
+ },
+ descendants = hole.Correspondence.Descendants.Select(x => new { x.StableId, x.Kind, role = x.Role.ToString(), x.SourceStableId, x.ParentStableId, edge = x.Edge?.Value, face = x.Face?.Value, loop = x.Loop?.Value }),
+ selectionResults = selectionResults.Select(result => new { name = result.Request.Label, stableId = result.Request.StableId, topologyRole = result.Request.Role?.ToString(), expectedShape = result.Request.Require.ToString(), succeeded = result.Succeeded, failure = result.Failure.ToString(), materializedDescendants = result.Descendants.Select(x => x.StableId), diagnostics = result.Diagnostics }),
+ provenance = hole.Correspondence.ProvenanceChain,
+ diagnostics = hole.Diagnostics,
+ timings = new { parseMs = parseClock.Elapsed.TotalMilliseconds, inspectMs = inspectClock.Elapsed.TotalMilliseconds, totalMs = totalClock.Elapsed.TotalMilliseconds }
+ }, JsonOptions));
return 0;
}
var parsed = ProfileAuthoringParser.Parse(source);
diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.cs
index 25a69d54..f4c000d7 100644
--- a/Aetheris.CLI/StepAnalyzer.cs
+++ b/Aetheris.CLI/StepAnalyzer.cs
@@ -219,7 +219,7 @@ public sealed record VolumeAnalysisResult(
{
volume = 0d;
basis = string.Empty;
- var cylinders = new List<(double Radius, double XMin, double XMax)>();
+ var cylinders = new List<(double CenterY, double CenterZ, double Radius, double XMin, double XMax)>();
foreach (var face in body.Topology.Faces)
{
@@ -232,7 +232,7 @@ public sealed record VolumeAnalysisResult(
{
if (!IsXAxis(cylinder.Axis.ToVector())) return false;
if (!TryResolveFaceXSpan(body, face.Id, out var xMin, out var xMax)) return false;
- cylinders.Add((cylinder.Radius, xMin, xMax));
+ cylinders.Add((cylinder.Origin.Y, cylinder.Origin.Z, cylinder.Radius, xMin, xMax));
continue;
}
@@ -248,7 +248,12 @@ public sealed record VolumeAnalysisResult(
}
var baseVolume = (bbox.Max.X - bbox.Min.X) * (bbox.Max.Y - bbox.Min.Y) * (bbox.Max.Z - bbox.Min.Z);
- var removed = cylinders.Sum(c => double.Pi * c.Radius * c.Radius * (c.XMax - c.XMin));
+ // One analytic cylinder may be represented by multiple trimmed faces
+ // (the local-frame hole planner deliberately uses two arcs to avoid a
+ // reused longitudinal seam). Deduplicate that partition before adding
+ // physical removal volumes; distinct centers remain distinct holes.
+ var physicalCylinders = cylinders.DistinctBy(c => (c.CenterY, c.CenterZ, c.Radius, c.XMin, c.XMax));
+ var removed = physicalCylinders.Sum(c => double.Pi * c.Radius * c.Radius * (c.XMax - c.XMin));
volume = baseVolume - removed;
basis = "Exact analytic volume for an axis-aligned rectangular box with supported locked Firmament V2 +X/-X cylindrical side-hole interval.";
return double.IsFinite(volume) && volume > 0d;
diff --git a/Aetheris.Kernel.Core/Air/AirHoleFeature.cs b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
index bbdf2c05..0bc54aa5 100644
--- a/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
+++ b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
@@ -11,7 +11,7 @@ internal sealed record AirHoleFeature(
string Name,
string FeatureId,
string? TargetBodyId,
- AirFaceLocalHolePlacement Placement,
+ AirHolePlacement Placement,
AirHoleAxis Axis,
AirHoleShaft Shaft,
AirHoleEndCondition EndCondition,
@@ -25,6 +25,7 @@ internal sealed record AirHoleFeature(
public const string UnsupportedThreadDiagnostic = "hole-x1-thread-deferred";
public bool IsValid => Diagnostics.All(d => d.Severity != AirDiagnosticSeverity.Error);
+ public AirConstructionPlaneHolePlacement? ConstructionPlanePlacement => Placement as AirConstructionPlaneHolePlacement;
public static AirHoleFeature CreateSimpleShaft(
string name,
@@ -50,6 +51,21 @@ internal sealed record AirHoleFeature(
diagnostics);
}
+ public static AirHoleFeature CreateConstructionPlaneSimpleShaft(
+ string name,
+ string featureId,
+ string? targetBodyId,
+ AirConstructionPlaneHolePlacement placement,
+ AirHoleShaft shaft,
+ AirHoleEndCondition endCondition,
+ AirProvenance? provenance = null)
+ {
+ var diagnostics = ValidateConstructionPlane(name, featureId, placement, shaft, endCondition).ToArray();
+ return new AirHoleFeature(name, featureId, targetBodyId, placement,
+ new AirHoleAxis(placement.AxisZ, false), shaft, endCondition, AirHoleStack.SimpleShaft(shaft, endCondition),
+ provenance ?? DefaultProvenance(name, featureId), diagnostics);
+ }
+
public static AirHoleFeature CreateCounterbore(
string name,
@@ -142,6 +158,16 @@ internal sealed record AirHoleFeature(
}
}
+ private static IEnumerable<AirDiagnostic> ValidateConstructionPlane(string name, string featureId, AirConstructionPlaneHolePlacement placement, AirHoleShaft shaft, AirHoleEndCondition endCondition)
+ {
+ if (string.IsNullOrWhiteSpace(name)) yield return Error("hole-x2-name-required", "Hole feature name is required.");
+ if (string.IsNullOrWhiteSpace(featureId)) yield return Error("hole-x2-feature-id-required", "Hole feature id is required.");
+ if (string.IsNullOrWhiteSpace(placement.ConstructionPlaneId) || string.IsNullOrWhiteSpace(placement.SourceConceptPlaneId)) yield return Error("HoleConstructionPlaneInvalid", "Construction Plane placement requires stable construction and Concept Plane identities.");
+ if (!IsFinite(placement.LocalCenterX) || !IsFinite(placement.LocalCenterY)) yield return Error("HoleLocalCenterInvalid", "Construction Plane local center coordinates must be finite.");
+ if (!IsFinite(shaft.Diameter) || shaft.Diameter <= 0d) yield return Error("hole-x2-diameter-invalid", "Hole diameter must be greater than zero.");
+ if (endCondition is AirHoleEndCondition.Depth depth && (!IsFinite(depth.Value) || depth.Value <= 0d)) yield return Error("HoleExtentInvalid", "Bounded shaft depth must be greater than zero.");
+ }
+
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);
}
@@ -157,13 +183,43 @@ internal sealed record AirResolvedPoint3PlacementSource(
double PlaneDistance,
string SourceSpan);
+internal abstract record AirHolePlacement(double U, double V)
+{
+ public virtual string? EntryFaceName => null;
+ public virtual AirResolvedPoint3PlacementSource? ResolvedPoint3 => null;
+}
+
internal sealed record AirFaceLocalHolePlacement(
- string EntryFaceName,
+ string FaceName,
double U,
double V,
string FrameConvention,
string? StableFaceSelector = null,
- AirResolvedPoint3PlacementSource? ResolvedPoint3 = null);
+ AirResolvedPoint3PlacementSource? Point3Source = null) : AirHolePlacement(U, V)
+{
+ public override string EntryFaceName => FaceName;
+ public override AirResolvedPoint3PlacementSource? ResolvedPoint3 => Point3Source;
+}
+
+/// <summary>
+/// Immutable local-frame placement for new semantic holes. Unlike the legacy
+/// <see cref="AirFaceLocalHolePlacement"/>, this is authored from construction
+/// evidence, never from a materialized face name or topology id.
+/// </summary>
+internal sealed record AirConstructionPlaneHolePlacement(
+ string ConstructionPlaneId,
+ string SourceConceptPlaneId,
+ Point3D FrameOrigin,
+ Direction3D AxisX,
+ Direction3D AxisY,
+ Direction3D AxisZ,
+ double LocalCenterX,
+ double LocalCenterY,
+ string SourceSpan,
+ string Provenance) : AirHolePlacement(LocalCenterX, LocalCenterY)
+{
+ public Point3D WorldMouthCenter => FrameOrigin + AxisX.ToVector() * LocalCenterX + AxisY.ToVector() * LocalCenterY;
+}
internal sealed record AirHoleAxis(Direction3D Direction, bool DefaultedFromEntryFaceNormal);
internal sealed record AirHoleShaft(double Diameter)
{
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2ConstructionPlaneHoleSourceTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ConstructionPlaneHoleSourceTests.cs
new file mode 100644
index 00000000..e96f6b18
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ConstructionPlaneHoleSourceTests.cs
@@ -0,0 +1,75 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Firmament.FirmamentV2;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentV2ConstructionPlaneHoleSourceTests
+{
+ [Fact]
+ public void Source_ConstructionPlaneHole_LowersDirectlyAndPublishesSelectableDescendants()
+ {
+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(Fixture));
+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));
+ var hole = Assert.Single(Assert.Single(parsed.Document!.ModifyBlocks!).SemanticHoles);
+ var placement = Assert.IsType<FirmamentV2ConstructionPlaneHolePlacement>(hole.Placement);
+ Assert.Equal("construction:PositiveXWorkplane", placement.Plane.StableId);
+ Assert.Equal((10d, 6d), (placement.Center.U, placement.Center.V));
+
+ var air = Assert.Single(FirmamentV2SemanticHoleLowering.LowerSemanticHoles(parsed.Document));
+ Assert.IsType<AirConstructionPlaneHolePlacement>(air.Placement);
+ Assert.Null(air.Placement.EntryFaceName);
+ var materialized = AirHoleSimpleShaftMaterializer.Execute(air, new AirHoleSimpleShaftHost(100, 60, 0, 12));
+ Assert.True(materialized.Succeeded, string.Join(" | ", materialized.Diagnostics));
+ Assert.IsType<LocalFrameHoleBRepPlan>(materialized.Plan!.HoleBRepPlan);
+
+ var correspondence = Assert.IsType<SemanticTopologyCorrespondence>(materialized.Correspondence);
+ var request = new SemanticSelectionRequest("selection:mouth", "mouth", "Base", ["Base.SideMount"], SemanticTopologyRole.HoleEntryLoop, SemanticSelectionRequirement.ClosedLoop, "fixture");
+ var selected = SemanticTopologySelectionResolver.Resolve(materialized.Body!, correspondence, request);
+ Assert.True(selected.Succeeded, string.Join(" | ", selected.Diagnostics.Select(d => d.Code + ":" + d.Message)));
+ Assert.Contains(correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleExitLoop);
+ Assert.Contains(correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);
+ }
+
+ [Theory]
+ [InlineData("From: MissingWorkplane", FirmamentV2Parser.HoleConstructionPlaneNotFound)]
+ [InlineData("From: PositiveXWorkplane\n On: Base.Top", FirmamentV2Parser.HolePlacementMixed)]
+ [InlineData("Center: Point2(10mm, 6mm)\n Diameter: 8mm\n End: ThroughAll", FirmamentV2Parser.HoleConstructionPlaneCenterMissing)]
+ [InlineData("End: Blind", FirmamentV2Parser.HoleConstructionPlaneExtentUnsupported)]
+ [InlineData("From: PositiveXWorkplane\n From: PositiveXWorkplane", FirmamentV2Parser.HolePlacementDuplicate)]
+ public void Source_ConstructionPlaneHole_InvalidPlacementIsTyped(string replacement, string diagnostic)
+ {
+ var source = File.ReadAllText(Fixture);
+ if (replacement.StartsWith("Center:", StringComparison.Ordinal)) source = source.Replace("Center: Point2(10mm, 6mm)\n ", string.Empty, StringComparison.Ordinal);
+ else if (replacement.StartsWith("End:", StringComparison.Ordinal)) source = source.Replace("End: ThroughAll", replacement, StringComparison.Ordinal);
+ else source = source.Replace("From: PositiveXWorkplane", replacement, StringComparison.Ordinal);
+ var result = FirmamentV2Parser.Parse(source);
+ Assert.False(result.IsSuccess);
+ Assert.Contains(diagnostic, result.Diagnostics);
+ }
+
+ [Theory]
+ [InlineData("construction-plane-orientation.invalid.firmament", "HoleConstructionPlaneOrientationUnsupported")]
+ [InlineData("construction-plane-mouth-misses-host.invalid.firmament", "HoleMouthMissesHost")]
+ public void Source_ConstructionPlaneHole_MaterializationBoundaryIsTyped(string fixture, string diagnostic)
+ {
+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(InvalidFixture(fixture)));
+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));
+
+ var inspection = SemanticHoleInspection.Inspect(parsed.Document!);
+
+ Assert.False(inspection.Succeeded);
+ Assert.Contains(inspection.Diagnostics, message => message.StartsWith(diagnostic, StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void Source_ConstructionPlaneHole_UnsupportedHostIsTyped()
+ {
+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(InvalidFixture("construction-plane-host-unsupported.invalid.firmament")));
+ Assert.False(parsed.IsSuccess);
+ Assert.Contains(FirmamentV2Parser.HoleConstructionPlaneHostUnsupported, parsed.Diagnostics);
+ }
+
+ private static string Fixture => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament"));
+ private static string InvalidFixture(string name) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Hole/invalid", name));
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/LocalFrameHoleBRepPlanTests.cs b/Aetheris.Kernel.Firmament.Tests/LocalFrameHoleBRepPlanTests.cs
new file mode 100644
index 00000000..97cc2e32
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/LocalFrameHoleBRepPlanTests.cs
@@ -0,0 +1,61 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Brep.Verification;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class LocalFrameHoleBRepPlanTests
+{
+ [Fact]
+ public void PositiveXConstructionPlane_ThroughAll_IsExactAndPlanOwned()
+ {
+ var placement = new AirConstructionPlaneHolePlacement(
+ "construction:PositiveXWorkplane", "concept:SideLayout.PositiveXDatum",
+ new Point3D(-50, 0, 0), Direction3D.Create(new Vector3D(0, 1, 0)), Direction3D.Create(new Vector3D(0, 0, 1)), Direction3D.Create(new Vector3D(1, 0, 0)),
+ 0, 0, "fixture", "test");
+ var feature = AirHoleFeature.CreateConstructionPlaneSimpleShaft("PositiveXThrough", "base.PositiveXThrough", "base", placement,
+ new AirHoleShaft(8), new AirHoleEndCondition.ThroughAll());
+
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, new AirHoleSimpleShaftHost(100, 60, -6, 6));
+
+ Assert.True(result.Succeeded, string.Join(" | ", result.Diagnostics));
+ var plan = Assert.IsType<LocalFrameHoleBRepPlan>(result.Plan!.HoleBRepPlan);
+ Assert.Equal((0d, 100d), plan.HostMaterialInterval);
+ Assert.Equal("construction:PositiveXWorkplane", plan.Placement.ConstructionPlaneId);
+ Assert.Contains(plan.Topology.Surfaces, s => s.Geometry.Cylinder is { } c && Math.Abs(c.Axis.ToVector().X - 1d) < 1e-12 && Math.Abs(c.Radius - 4d) < 1e-12);
+ Assert.Contains(plan.Correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleEntryLoop);
+ Assert.Contains(plan.Correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleExitLoop);
+ Assert.NotEmpty(plan.Correspondence.Descendants.Where(d => d.Role == SemanticTopologyRole.HoleWallFace));
+
+ var mass = BrepMassProperties.Evaluate(result.Body!);
+ Assert.True(mass.IsEnclosed);
+ Assert.True(mass.IsOrientationConsistent);
+ var analyticVolume = 100d * 60d * 12d - Math.PI * 4d * 4d * 100d;
+ Assert.True(mass.ErrorBound.HasValue);
+ Assert.InRange(Math.Abs(mass.AbsoluteVolume - analyticVolume), 0d, mass.ErrorBound!.Value);
+
+ var step = Step242Exporter.ExportBody(result.Body!);
+ Assert.True(step.IsSuccess);
+ var reimport = Step242Importer.ImportBody(step.Value!);
+ Assert.True(reimport.IsSuccess);
+ Assert.Contains(reimport.Value!.Geometry.Surfaces, s => s.Value.Cylinder is { } c && Math.Abs(c.Axis.ToVector().X - 1d) < 1e-12);
+ }
+
+ [Fact]
+ public void ConstructionPlane_MouthAwayFromBoxBoundary_IsRejectedExplicitly()
+ {
+ var placement = new AirConstructionPlaneHolePlacement(
+ "construction:Bad", "concept:Bad", new Point3D(0, 0, 0),
+ Direction3D.Create(new Vector3D(0, 1, 0)), Direction3D.Create(new Vector3D(0, 0, 1)), Direction3D.Create(new Vector3D(1, 0, 0)),
+ 0, 0, "fixture", "test");
+ var feature = AirHoleFeature.CreateConstructionPlaneSimpleShaft("Bad", "base.Bad", "base", placement,
+ new AirHoleShaft(8), new AirHoleEndCondition.ThroughAll());
+
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, new AirHoleSimpleShaftHost(100, 60, -6, 6));
+
+ Assert.False(result.Succeeded);
+ Assert.Contains(result.Diagnostics, d => d.StartsWith("HoleDirectionDoesNotEnterHost", StringComparison.Ordinal));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 093c5675..e7c67ac4 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -1205,19 +1205,23 @@ public static class FirmamentBuildAndExport
var stepHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(step.Value)));
var surfaceKinds = body.Geometry.Surfaces.Select(s => s.Value.Kind).ToArray();
- var featureReports = semanticHoles.Select(h => new FirmamentHoleFeatureReport(
+ var featureReports = semanticHoles.Select(h =>
+ {
+ var legacyPlacement = h.Placement as AirFaceLocalHolePlacement;
+ var constructionPlacement = h.ConstructionPlanePlacement;
+ return new FirmamentHoleFeatureReport(
h.Name,
"Hole",
h.FeatureId,
h.Shaft.Diameter,
h.Placement.U,
h.Placement.V,
- h.Placement.ResolvedPoint3 is { } p ? new[] { p.X, p.Y, p.Z } : null,
- h.Placement.ResolvedPoint3 is { } sourcePoint ? sourcePoint.Ordinal is { } ordinal ? $"{sourcePoint.SourceMember}[{ordinal}]" : sourcePoint.SourceMember : null,
- h.Placement.ResolvedPoint3?.StableId,
- h.Placement.ResolvedPoint3?.Ordinal,
- h.Placement.ResolvedPoint3?.PlacementFace ?? h.Placement.EntryFaceName,
- h.Placement.ResolvedPoint3?.SourceSpan,
+ legacyPlacement?.ResolvedPoint3 is { } p ? new[] { p.X, p.Y, p.Z } : constructionPlacement is { } cp ? new[] { cp.WorldMouthCenter.X, cp.WorldMouthCenter.Y, cp.WorldMouthCenter.Z } : null,
+ legacyPlacement?.ResolvedPoint3 is { } sourcePoint ? sourcePoint.Ordinal is { } ordinal ? $"{sourcePoint.SourceMember}[{ordinal}]" : sourcePoint.SourceMember : constructionPlacement?.SourceConceptPlaneId,
+ legacyPlacement?.ResolvedPoint3?.StableId ?? constructionPlacement?.SourceConceptPlaneId,
+ legacyPlacement?.ResolvedPoint3?.Ordinal,
+ legacyPlacement?.ResolvedPoint3?.PlacementFace ?? constructionPlacement?.ConstructionPlaneId ?? legacyPlacement?.EntryFaceName ?? "unplaced",
+ legacyPlacement?.ResolvedPoint3?.SourceSpan ?? constructionPlacement?.SourceSpan,
semanticHoles.Count == 1 ? nameof(AirHoleSimpleShaftMaterializer) : nameof(AirHoleCompositeMaterializer),
"HoleProfileStack",
h.Stack.Kind.ToString(),
@@ -1232,7 +1236,8 @@ public static class FirmamentBuildAndExport
surfaceKinds.Count(k => k == SurfaceGeometryKind.Cone),
surfaceKinds.Count(k => k == SurfaceGeometryKind.Plane),
stepHash,
- true)).ToArray();
+ true);
+ }).ToArray();
return KernelResult<FirmamentStepExportResult>.Success(
new FirmamentStepExportResult(
step.Value,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs b/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
index 8fbdb3ab..3bb1db24 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
@@ -1,6 +1,7 @@
using System.Globalization;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;
+using Aetheris.Kernel.Firmament.Materializer;
namespace Aetheris.Kernel.Firmament.FirmamentV2;
@@ -217,7 +218,12 @@ internal static class ConceptIrResolver
var box = Regex.Match(bodyText, @"\bBox\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
var modify = Regex.Match(bodyText, @"\bModify\s+(?<target>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
var edge = Regex.Match(bodyText, @"\bEdgeFinish\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
- if (!box.Success || !modify.Success) { diagnostics.Add(FirmamentV2Parser.Phase3EdgeFinishSyntaxInvalid); return null; }
+ if (!box.Success || !modify.Success)
+ {
+ var constructionPlaneHole = Regex.IsMatch(bodyText, @"\bHole\s*<\s*Shaft\s*>[\s\S]*?\bFrom\s*:", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+ diagnostics.Add(constructionPlaneHole ? FirmamentV2Parser.HoleConstructionPlaneHostUnsupported : FirmamentV2Parser.Phase3EdgeFinishSyntaxInvalid);
+ return null;
+ }
var boxOpen = materializedOpen + 1 + bodyText.IndexOf('{', box.Index);
var boxClose = FindMatchingBrace(source, boxOpen);
var modifyStart = materializedOpen + 1 + modify.Index;
@@ -293,10 +299,14 @@ internal static class ConceptIrResolver
var modifyBody = source[(modifyOpen + 1)..modifyClose];
var holes = ParseConceptHoles(modifyBody, modifyOpen + 1, box.Groups["name"].Value, resolvedBounds,
- allInstances, materialized.Groups["name"].Value, bindings, diagnostics);
+ allInstances, materialized.Groups["name"].Value, bindings, diagnostics, source);
var patterns = ParseConceptPatterns(modifyBody, modifyOpen + 1, box.Groups["name"].Value, resolvedBounds, allInstances, materialized.Groups["name"].Value, bindings, diagnostics, out var patternHoles);
holes = holes.Concat(patternHoles).ToArray();
- if (holes.Count == 0 && finishes.Count == 0) { diagnostics.Add(FirmamentV2Parser.Phase3EdgeFinishSyntaxInvalid); return null; }
+ if (holes.Count == 0 && finishes.Count == 0)
+ {
+ if (!diagnostics.Any(FirmamentV2Parser.IsConceptFatalDiagnostic)) diagnostics.Add(FirmamentV2Parser.Phase3EdgeFinishSyntaxInvalid);
+ return null;
+ }
var satisfiesMaterialized = materialized.Groups["concept"].Success ? new[] { materialized.Groups["concept"].Value } : [];
var exposed = ParseExposedMembers(bodyText, materializedOpen + 1, materialized.Groups["name"].Value, box.Groups["name"].Value, resolvedBounds,
@@ -341,7 +351,8 @@ internal static class ConceptIrResolver
IReadOnlyDictionary<string, ConceptIrStructInstance> instances,
string materializedName,
List<ConceptIrBinding> bindings,
- List<string> diagnostics)
+ List<string> diagnostics,
+ string? fullSource = null)
{
const double tolerance = 1e-9;
var result = new List<FirmamentV2SemanticHoleDecl>();
@@ -353,7 +364,30 @@ internal static class ConceptIrResolver
var open = body.IndexOf('{', header.Index); var close = FindMatchingBrace(body, open);
if (close < 0) { diagnostics.Add(FirmamentV2Parser.RegionUnsupported); continue; }
var holeBody = body[(open + 1)..close];
+ var from = FieldValue(holeBody, "from");
var on = FieldValue(holeBody, "on");
+ if (FieldCount(holeBody, "from") > 1 || FieldCount(holeBody, "on") > 1)
+ { diagnostics.Add(FirmamentV2Parser.HolePlacementDuplicate); continue; }
+ if (!string.IsNullOrWhiteSpace(from))
+ {
+ if (!string.IsNullOrWhiteSpace(on)) { diagnostics.Add(FirmamentV2Parser.HolePlacementMixed); continue; }
+ if (!TryResolveConstructionPlane(fullSource, from, out var constructionPlane, out var planeDiagnostic))
+ { diagnostics.Add(planeDiagnostic ?? FirmamentV2Parser.HoleConstructionPlaneNotFound); continue; }
+ var localCenter = ParsePoint2(FieldValue(holeBody, "center"));
+ if (localCenter is null) { diagnostics.Add(FirmamentV2Parser.HoleConstructionPlaneCenterMissing); continue; }
+ var localDiameter = ParseLengthOrUnitless(FieldValue(holeBody, "diameter"));
+ if (!double.IsFinite(localDiameter) || localDiameter <= 0) { diagnostics.Add(FirmamentV2Parser.HoleDiameterInvalid); continue; }
+ var localEnd = FieldValue(holeBody, "end");
+ if (!string.Equals(localEnd, "throughAll", StringComparison.OrdinalIgnoreCase) && !string.Equals(localEnd, "Through", StringComparison.OrdinalIgnoreCase))
+ { diagnostics.Add(FirmamentV2Parser.HoleConstructionPlaneExtentUnsupported); continue; }
+ var constructionSourceSpan = new FirmamentV2SourceSpan(bodyOffset + header.Index, close - header.Index + 1);
+ var center = new FirmamentV2FaceLocalPoint2D(localCenter.Value.U, localCenter.Value.V, "ConstructionPlaneLocalXY");
+ result.Add(new(header.Groups["name"].Value, FirmamentV2SemanticHoleVariant.Shaft, FirmamentV2FaceTarget.Direct("+Z"), center,
+ localDiameter, new(FirmamentV2SemanticHoleEndKind.ThroughAll), SourceSpan: constructionSourceSpan,
+ Placement: new FirmamentV2ConstructionPlaneHolePlacement(constructionPlane!, center, constructionSourceSpan)));
+ bindings.Add(new($"{materializedName}.{header.Groups["name"].Value}.ConstructionPlane", from, constructionPlane!.SourceConceptId, "ConstructionPlane"));
+ continue;
+ }
var faceAxis = on switch
{
"face(+Z)" => "+Z",
@@ -905,7 +939,28 @@ internal static class ConceptIrResolver
private static ConceptIrVector3 Vector(string axis) => axis switch { "+X" => new(1, 0, 0), "-X" => new(-1, 0, 0), "+Y" => new(0, 1, 0), "-Y" => new(0, -1, 0), "+Z" => new(0, 0, 1), "-Z" => new(0, 0, -1), _ => new(0, 0, 0) };
private static string AxisOf(ConceptIrVector3 v) => (v.X, v.Y, v.Z) switch { (1, 0, 0) => "+X", (-1, 0, 0) => "-X", (0, 1, 0) => "+Y", (0, -1, 0) => "-Y", (0, 0, 1) => "+Z", (0, 0, -1) => "-Z", _ => string.Empty };
private static bool IsInsidePattern(string body, int index) => Regex.Matches(body, @"\bPattern\s+[A-Za-z_][A-Za-z0-9_]*\s*\{", RegexOptions.CultureInvariant).Cast<Match>().Any(p => { var close = FindMatchingBrace(body, body.IndexOf('{', p.Index)); return p.Index < index && close > index; });
- private static string FieldValue(string body, string name) { var m = Regex.Match(body, $@"\b{Regex.Escape(name)}\s*:\s*(?<value>[^\r\n}}]+)", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant); return m.Success ? m.Groups["value"].Value.Trim() : string.Empty; }
+ private static string FieldValue(string body, string name) { var m = Regex.Match(body, $@"\b{Regex.Escape(name)}\s*:\s*(?<value>[^\r\n;}}]+)", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant); return m.Success ? m.Groups["value"].Value.Trim() : string.Empty; }
+ private static int FieldCount(string body, string name) => Regex.Matches(body, $@"\b{Regex.Escape(name)}\s*:", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant).Count;
+ private static (double U, double V)? ParsePoint2(string source)
+ {
+ var match = Regex.Match(source, @"^Point2\s*\(\s*(?<u>[^,]+)\s*,\s*(?<v>[^)]+)\s*\)$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+ if (!match.Success) return null;
+ var u = ParseLengthOrUnitless(match.Groups["u"].Value.Trim()); var v = ParseLengthOrUnitless(match.Groups["v"].Value.Trim());
+ return double.IsFinite(u) && double.IsFinite(v) ? (u, v) : null;
+ }
+
+ private static bool TryResolveConstructionPlane(string? source, string name, out ConstructionPlane? plane, out string? diagnostic)
+ {
+ plane = null; diagnostic = null;
+ if (string.IsNullOrWhiteSpace(source)) { diagnostic = FirmamentV2Parser.HoleConstructionPlaneNotFound; return false; }
+ var declaration = Regex.Match(source, $@"\bConstruction\s+Plane\s+{Regex.Escape(name)}\s*\{{\s*Trace\s*:\s*(?<trace>[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+ if (!declaration.Success) { diagnostic = FirmamentV2Parser.HoleConstructionPlaneNotFound; return false; }
+ if (!TryResolvePlane(source, declaration.Groups["trace"].Value, out var conceptPlane, out var conceptDiagnostic))
+ { diagnostic = conceptDiagnostic ?? FirmamentV2Parser.HoleConstructionPlaneNotFound; return false; }
+ if (!ConstructionPlane.TryTrace("construction:" + name, conceptPlane!, $"{declaration.Index}:{declaration.Length}", out plane, out var frameDiagnostic))
+ { diagnostic = frameDiagnostic ?? "HoleConstructionPlaneInvalid"; return false; }
+ return true;
+ }
private static int IntField(string body, string name) => int.TryParse(FieldValue(body, name), NumberStyles.None, CultureInfo.InvariantCulture, out var value) ? value : -1;
private static double ParseLength(string source) { source = source.Trim(); return source.EndsWith("mm", StringComparison.Ordinal) && double.TryParse(source[..^2], NumberStyles.Float, CultureInfo.InvariantCulture, out var value) ? value : double.NaN; }
private static double ParseLengthOrUnitless(string source)
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
index 3bca6e4f..5739decb 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
@@ -1,3 +1,5 @@
+using Aetheris.Kernel.Firmament.Materializer;
+
namespace Aetheris.Kernel.Firmament.FirmamentV2;
public sealed record FirmamentV2Document(string ModelName, string Units, IReadOnlyList<FirmamentV2SolidBinding> Solids, IReadOnlyList<FirmamentV2ModifyBlock>? ModifyBlocks = null, IReadOnlyList<FirmamentV2TemplateDecl>? Templates = null, IReadOnlyList<FirmamentV2PmiDecl>? Pmi = null, IReadOnlyList<FirmamentV2RecognizedRegion>? RecognizedRegions = null, IReadOnlyList<FirmamentV2ReplacementDecl>? Replacements = null, IReadOnlyList<FirmamentV2LetDeclaration>? Lets = null, IReadOnlyList<FirmamentV2BoundLet>? BoundLets = null, IReadOnlyList<FirmamentV2LetRecordDeclaration>? LetRecords = null, IReadOnlyList<FirmamentV2BoundLetRecord>? BoundLetRecords = null, IReadOnlyList<FirmamentV2ManufacturingConceptDeclaration>? ManufacturingConcepts = null, IReadOnlyList<FirmamentV2FeatureConceptDeclaration>? FeatureConcepts = null, FirmamentV2PmiBlock? PmiBlock = null, FirmamentV2BoundPmiBlock? BoundPmi = null, ConceptIrDocument? ConceptIr = null, IReadOnlyList<FirmamentV2LatticeFillDecl>? LatticeFills = null, IReadOnlyList<FirmamentV2StandaloneLatticeFillDecl>? StandaloneLatticeFills = null)
@@ -155,6 +157,10 @@ public sealed record FirmamentV2ResolvedPoint3(
string PlacementFace,
double PlaneDistance,
FirmamentV2SourceSpan SourceSpan);
+/// <summary>Bound placement mode: new sources use a traced immutable Construction Plane; legacy sources retain face-local placement.</summary>
+public abstract record FirmamentV2BoundHolePlacement;
+public sealed record FirmamentV2FaceLocalHolePlacement(FirmamentV2FaceTarget EntryFace, FirmamentV2FaceLocalPoint2D Center) : FirmamentV2BoundHolePlacement;
+public sealed record FirmamentV2ConstructionPlaneHolePlacement(ConstructionPlane Plane, FirmamentV2FaceLocalPoint2D Center, FirmamentV2SourceSpan SourceSpan) : FirmamentV2BoundHolePlacement;
public sealed record FirmamentV2SemanticHoleDecl(
string Name,
FirmamentV2SemanticHoleVariant Variant,
@@ -167,7 +173,8 @@ public sealed record FirmamentV2SemanticHoleDecl(
double? CountersinkDiameter = null,
double? CountersinkAngleDegrees = null,
FirmamentV2ResolvedPoint3? ResolvedCenter = null,
- FirmamentV2SourceSpan? SourceSpan = null);
+ FirmamentV2SourceSpan? SourceSpan = null,
+ FirmamentV2BoundHolePlacement? Placement = null);
public enum FirmamentV2PmiKind { HoleDiameter, DatumPlane, Distance, Flatness, Parallel, Perpendicular, Coplanar }
public sealed record FirmamentV2PmiDecl(string Name, FirmamentV2PmiKind Kind, string Target, double? Value = null);
public sealed record FirmamentV2PmiBlock(IReadOnlyList<FirmamentV2PmiRecord> Records, FirmamentV2SourceSpan SourceSpan);
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index be7992d6..85e6a11d 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -134,6 +134,12 @@ public static class FirmamentV2Parser
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";
+ public const string HoleConstructionPlaneNotFound = "HoleConstructionPlaneNotFound";
+ public const string HolePlacementMixed = "HolePlacementMixed";
+ public const string HolePlacementDuplicate = "HolePlacementDuplicate";
+ public const string HoleConstructionPlaneHostUnsupported = "HoleConstructionPlaneHostUnsupported";
+ public const string HoleConstructionPlaneCenterMissing = "HoleLocalCenterInvalid";
+ public const string HoleConstructionPlaneExtentUnsupported = "HoleConstructionPlaneExtentUnsupported";
public const string PmiKindUnknown = "firmament-v2-pmi-kind-unknown";
public const string PmiTargetMissing = "firmament-v2-pmi-target-missing";
public const string PmiTargetUnresolved = "firmament-v2-pmi-target-unresolved";
@@ -978,7 +984,9 @@ public static class FirmamentV2Parser
return double.TryParse(source[..^2], NumberStyles.Float, CultureInfo.InvariantCulture, out var value) ? value : double.NaN;
}
- private static bool IsConceptFatalDiagnostic(string code) =>
+ internal static bool IsConceptFatalDiagnostic(string code) =>
+ code is HoleConstructionPlaneNotFound or HolePlacementMixed or HolePlacementDuplicate or HoleConstructionPlaneCenterMissing or HoleConstructionPlaneExtentUnsupported or HoleConstructionPlaneHostUnsupported
+ ||
code.StartsWith(ConceptIrResolver.MissingMember, StringComparison.Ordinal)
|| code.StartsWith(ConceptIrResolver.UnknownMember, StringComparison.Ordinal)
|| code.StartsWith(ConceptIrResolver.TypeMismatch, StringComparison.Ordinal)
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs
index 30fd17f5..eadc2c09 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs
@@ -7,6 +7,22 @@ internal static class FirmamentV2SemanticHoleLowering
{
public static AirHoleFeature Lower(FirmamentV2Document document, FirmamentV2ModifyBlock modify, FirmamentV2SemanticHoleDecl hole)
{
+ if (hole.Placement is FirmamentV2ConstructionPlaneHolePlacement construction)
+ {
+ var plane = construction.Plane;
+ var constructionPlacement = new AirConstructionPlaneHolePlacement(plane.StableId, plane.SourceConceptId, plane.Origin, plane.AxisX, plane.AxisY, plane.AxisZ,
+ construction.Center.U, construction.Center.V, $"{construction.SourceSpan.Start}:{construction.SourceSpan.Length}", plane.Provenance);
+ AirHoleEndCondition constructionEnd = hole.EndCondition.Kind == FirmamentV2SemanticHoleEndKind.ThroughAll
+ ? new AirHoleEndCondition.ThroughAll()
+ : new AirHoleEndCondition.Depth(hole.EndCondition.Depth!.Value);
+ var constructionProvenance = new AirProvenance("CONSTRUCTION-PLANE-HOLE-SOURCE-X3", "Construction Plane semantic hole source", hole.Name,
+ $"{modify.TargetSolid}.{hole.Name}", nameof(AirConstructionPlaneHolePlacement), AirSelectionClass.None, AirRuleKind.None,
+ "FirmamentV2 Hole<Shaft> From ConstructionPlane", true,
+ [$"target-solid:{modify.TargetSolid}", $"construction-plane:{plane.StableId}", $"source-concept-plane:{plane.SourceConceptId}",
+ $"local-center:[{construction.Center.U:R},{construction.Center.V:R}]", "extent:ThroughAll"]);
+ return AirHoleFeature.CreateConstructionPlaneSimpleShaft(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, constructionPlacement,
+ new AirHoleShaft(hole.ShaftDiameter), constructionEnd, constructionProvenance);
+ }
var pointSource = hole.ResolvedCenter is null ? null : new AirResolvedPoint3PlacementSource(
hole.ResolvedCenter.X, hole.ResolvedCenter.Y, hole.ResolvedCenter.Z, hole.ResolvedCenter.StableId,
hole.ResolvedCenter.SourceMember, hole.ResolvedCenter.Ordinal, hole.ResolvedCenter.PlacementFace,
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
index 0bd4e2cb..9d235d51 100644
--- a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
@@ -1,11 +1,17 @@
using Aetheris.Kernel.Core.Air;
using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Geometry.Curves;
using Aetheris.Kernel.Core.Topology;
using Aetheris.Kernel.Firmament.FirmamentV2;
namespace Aetheris.Kernel.Firmament.Materializer;
-public sealed record SemanticHoleInspectionResult(bool Succeeded, string? HoleId, BrepBody? Body, SemanticTopologyCorrespondence? Correspondence, IReadOnlyList<string> Diagnostics);
+public sealed record SemanticHoleSourceInspectionEvidence(
+ string FeatureId, string PlacementKind, string? ConstructionPlaneId, string? SourceConceptPlaneId,
+ double[]? FrameOrigin, double[]? AxisX, double[]? AxisY, double[]? AxisZ,
+ double[] LocalCenter, double[]? WorldMouthCenter, double Diameter, double Radius,
+ string Extent, double[]? HostInterval, string? PlanId, string? SourceSpan);
+public sealed record SemanticHoleInspectionResult(bool Succeeded, string? HoleId, BrepBody? Body, SemanticTopologyCorrespondence? Correspondence, IReadOnlyList<string> Diagnostics, SemanticHoleSourceInspectionEvidence? Evidence = null);
public static class SemanticHoleInspection
{
public static SemanticHoleInspectionResult Inspect(FirmamentV2Document document)
@@ -15,7 +21,17 @@ public static class SemanticHoleInspection
if (holes.Count != 1 || binding?.Primitive is not FirmamentV2BoxRecord box || box.Size.Count != 3) return new(false, null, null, null, ["MissingCorrespondenceEvidence: bounded inspection requires one shaft hole in one Box host."]);
var host = document.ConceptIr is null ? new AirHoleSimpleShaftHost(box.Size[0], box.Size[1], -box.Size[2] / 2d, box.Size[2] / 2d) : new AirHoleSimpleShaftHost(box.Size[0], box.Size[1], 0d, box.Size[2]);
var result = AirHoleSimpleShaftMaterializer.Execute(holes[0], host);
- return new(result.Succeeded && result.Correspondence is not null, holes[0].FeatureId, result.Body, result.Correspondence, result.Diagnostics);
+ var feature = holes[0]; var placement = feature.ConstructionPlanePlacement;
+ double[] Vector(Aetheris.Kernel.Core.Math.Vector3D v) => [v.X, v.Y, v.Z];
+ var evidence = placement is null
+ ? new SemanticHoleSourceInspectionEvidence(feature.FeatureId, "FaceLocal", null, null, null, null, null, null,
+ [feature.Placement.U, feature.Placement.V], null, feature.Shaft.Diameter, feature.Shaft.Radius, feature.EndCondition.Kind.ToString(), null, null, null)
+ : new SemanticHoleSourceInspectionEvidence(feature.FeatureId, "ConstructionPlane", placement.ConstructionPlaneId, placement.SourceConceptPlaneId,
+ [placement.FrameOrigin.X, placement.FrameOrigin.Y, placement.FrameOrigin.Z], Vector(placement.AxisX.ToVector()), Vector(placement.AxisY.ToVector()), Vector(placement.AxisZ.ToVector()),
+ [placement.LocalCenterX, placement.LocalCenterY], [placement.WorldMouthCenter.X, placement.WorldMouthCenter.Y, placement.WorldMouthCenter.Z],
+ feature.Shaft.Diameter, feature.Shaft.Radius, "ThroughAll", result.Plan?.HoleBRepPlan is { } plan ? [plan.HostMaterialInterval.Start, plan.HostMaterialInterval.End] : null,
+ result.Plan?.HoleBRepPlan?.StableId, placement.SourceSpan);
+ return new(result.Succeeded && result.Correspondence is not null, feature.FeatureId, result.Body, result.Correspondence, result.Diagnostics, evidence);
}
}
@@ -54,7 +70,8 @@ internal sealed record AirHoleSimpleShaftMaterializationPlan(
AirHoleStackKind StackKind,
IReadOnlyList<AirHoleStackComponentKind> StackComponentRoles,
ProfileStackExtrudeSpec ProfileStackSpec,
- IReadOnlyList<string> Diagnostics);
+ IReadOnlyList<string> Diagnostics,
+ LocalFrameHoleBRepPlan? HoleBRepPlan = null);
internal sealed record AirHoleSimpleShaftMaterializationResult(
AirHoleSimpleShaftMaterializationStatus Status,
@@ -72,6 +89,9 @@ internal static class AirHoleSimpleShaftMaterializer
public static AirHoleSimpleShaftMaterializationResult Execute(AirHoleFeature feature, AirHoleSimpleShaftHost host)
{
+ if (feature.ConstructionPlanePlacement is { } constructionPlacement)
+ return ExecuteConstructionPlaneThroughAll(feature, host, constructionPlacement);
+
var planResult = TryCreatePlan(feature, host);
if (planResult.Status != AirHoleSimpleShaftMaterializationStatus.Succeeded || planResult.Plan is null)
{
@@ -105,6 +125,11 @@ internal static class AirHoleSimpleShaftMaterializer
diagnostics.Add("air-hole-x2 rejected: semantic hole invalid before materialization.");
return new(AirHoleSimpleShaftMaterializationStatus.InvalidSemanticHole, null, null, diagnostics);
}
+ if (feature.Placement is not AirFaceLocalHolePlacement placement)
+ {
+ diagnostics.Add("HoleConstructionPlaneHostUnsupported: the legacy profile-stack route accepts face-local placements only.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
if (!IsFinite(host.Width) || !IsFinite(host.Depth) || !IsFinite(host.ZMin) || !IsFinite(host.ZMax) || host.Width <= 0d || host.Depth <= 0d || host.Thickness <= Tolerance)
{
@@ -112,16 +137,16 @@ internal static class AirHoleSimpleShaftMaterializer
return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
}
- if (Math.Abs(feature.Placement.U) + feature.Shaft.Radius > host.Width / 2d + Tolerance ||
- Math.Abs(feature.Placement.V) + feature.Shaft.Radius > host.Depth / 2d + Tolerance)
+ if (Math.Abs(placement.U) + feature.Shaft.Radius > host.Width / 2d + Tolerance ||
+ Math.Abs(placement.V) + feature.Shaft.Radius > host.Depth / 2d + Tolerance)
{
diagnostics.Add("air-hole-x2 rejected: face-local center/radius does not fit within the supported rectangular entry face.");
return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
}
var axisZ = feature.Axis.Direction.Z;
- var top = string.Equals(feature.Placement.EntryFaceName, host.TopFaceName, StringComparison.OrdinalIgnoreCase) && axisZ > 1d - Tolerance;
- var bottom = string.Equals(feature.Placement.EntryFaceName, host.BottomFaceName, StringComparison.OrdinalIgnoreCase) && axisZ < -1d + Tolerance;
+ var top = string.Equals(placement.EntryFaceName, host.TopFaceName, StringComparison.OrdinalIgnoreCase) && axisZ > 1d - Tolerance;
+ var bottom = string.Equals(placement.EntryFaceName, host.BottomFaceName, StringComparison.OrdinalIgnoreCase) && axisZ < -1d + Tolerance;
if (!top && !bottom)
{
diagnostics.Add("air-hole-x2 rejected: only planar top/+Z and bottom/-Z face-local placements are supported by this rectangular profile-stack lowering lane.");
@@ -138,10 +163,10 @@ internal static class AirHoleSimpleShaftMaterializer
var layers = BuildLayers(feature, host, cutZMin, cutZMax).ToArray();
var spec = new ProfileStackExtrudeSpec(host.Width, host.Depth, host.ZMin, host.ZMax, layers,
[$"air-hole-x2 provenance featureId={feature.FeatureId}", $"air-hole-x2 provenance source={nameof(AirHoleFeature)}"],
- 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, feature.Stack.Kind, feature.Stack.Components.Select(c => c.Kind).ToArray(), spec, diagnostics.ToArray());
+ placement.U,
+ placement.V);
+ var plan = new AirHoleSimpleShaftMaterializationPlan(feature, host, feature.FeatureId, nameof(AirHoleFeature), placement.EntryFaceName,
+ placement.U, 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);
}
@@ -202,4 +227,107 @@ internal static class AirHoleSimpleShaftMaterializer
}
private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+
+ /// <summary>
+ /// The initial LOCAL-FRAME-HOLES-X2 host query. A rectangular Box is admitted
+ /// only when the supplied proper frame is a signed permutation of the host
+ /// world axes. In that case transforming the eight Box corners proves one
+ /// exact local-Z material interval; there is no spatial search or oversized
+ /// cutting tool. The resulting host-with-hole is planned as one ordinary
+ /// circular-inner-loop local profile extrusion.
+ /// </summary>
+ private static AirHoleSimpleShaftMaterializationResult ExecuteConstructionPlaneThroughAll(
+ AirHoleFeature feature, AirHoleSimpleShaftHost host, AirConstructionPlaneHolePlacement placement)
+ {
+ var diagnostics = new List<string> { "LocalFrameHoleConstructionPlanePlacement", "HoleBRepPlan", "HostMaterialIntervalQuery:BoxSignedPermutation" };
+ if (!feature.IsValid)
+ {
+ diagnostics.AddRange(feature.Diagnostics.Select(d => $"semantic diagnostic {d.Code}: {d.Message}"));
+ return new(AirHoleSimpleShaftMaterializationStatus.InvalidSemanticHole, null, null, diagnostics);
+ }
+ if (feature.EndCondition is not AirHoleEndCondition.ThroughAll)
+ {
+ diagnostics.Add("HoleConstructionPlaneExtentUnsupported: construction-plane execution currently admits ThroughAll only; blind termination remains unimplemented.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+ if (feature.Stack.Kind != AirHoleStackKind.SimpleShaft)
+ {
+ diagnostics.Add("HoleConstructionPlaneHostUnsupported: construction-plane execution currently admits a simple Box host and simple cylindrical shaft only.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+ if (!IsSignedAxis(placement.AxisX) || !IsSignedAxis(placement.AxisY) || !IsSignedAxis(placement.AxisZ) ||
+ Math.Abs(placement.AxisX.ToVector().Dot(placement.AxisY.ToVector())) > Tolerance ||
+ Math.Abs(placement.AxisX.ToVector().Dot(placement.AxisZ.ToVector())) > Tolerance ||
+ Math.Abs(placement.AxisY.ToVector().Dot(placement.AxisZ.ToVector())) > Tolerance)
+ {
+ diagnostics.Add("HoleConstructionPlaneOrientationUnsupported: admitted Box host requires a proper signed-permutation Construction Plane frame.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ var worldCorners = new[]
+ {
+ new Aetheris.Kernel.Core.Math.Point3D(-host.Width / 2d, -host.Depth / 2d, host.ZMin), new Aetheris.Kernel.Core.Math.Point3D(host.Width / 2d, -host.Depth / 2d, host.ZMin),
+ new Aetheris.Kernel.Core.Math.Point3D(-host.Width / 2d, host.Depth / 2d, host.ZMin), new Aetheris.Kernel.Core.Math.Point3D(host.Width / 2d, host.Depth / 2d, host.ZMin),
+ new Aetheris.Kernel.Core.Math.Point3D(-host.Width / 2d, -host.Depth / 2d, host.ZMax), new Aetheris.Kernel.Core.Math.Point3D(host.Width / 2d, -host.Depth / 2d, host.ZMax),
+ new Aetheris.Kernel.Core.Math.Point3D(-host.Width / 2d, host.Depth / 2d, host.ZMax), new Aetheris.Kernel.Core.Math.Point3D(host.Width / 2d, host.Depth / 2d, host.ZMax)
+ };
+ (double X, double Y, double Z) Local(Aetheris.Kernel.Core.Math.Point3D point)
+ {
+ var delta = point - placement.FrameOrigin;
+ return (delta.Dot(placement.AxisX.ToVector()), delta.Dot(placement.AxisY.ToVector()), delta.Dot(placement.AxisZ.ToVector()));
+ }
+ var local = worldCorners.Select(Local).ToArray();
+ var xmin = local.Min(p => p.X); var xmax = local.Max(p => p.X); var ymin = local.Min(p => p.Y); var ymax = local.Max(p => p.Y);
+ var zmin = local.Min(p => p.Z); var zmax = local.Max(p => p.Z);
+ if (Math.Abs(zmin) > Tolerance || zmax <= Tolerance)
+ {
+ diagnostics.Add($"HoleDirectionDoesNotEnterHost: mouth localZ interval is [{zmin:R},{zmax:R}], expected [0,+). constructionPlane={placement.ConstructionPlaneId}");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+ if (placement.LocalCenterX - feature.Shaft.Radius < xmin - Tolerance || placement.LocalCenterX + feature.Shaft.Radius > xmax + Tolerance ||
+ placement.LocalCenterY - feature.Shaft.Radius < ymin - Tolerance || placement.LocalCenterY + feature.Shaft.Radius > ymax + Tolerance)
+ {
+ diagnostics.Add("HoleMouthMissesHost: local circular mouth does not lie fully within the admitted Box cross-section.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ var frame = new ConstructionPlane(placement.ConstructionPlaneId, placement.SourceConceptPlaneId, placement.FrameOrigin,
+ placement.AxisX, placement.AxisY, placement.AxisZ, placement.SourceSpan, placement.Provenance);
+ var outer = new LineArcProfileLoop2D([
+ new LineArcLineSegment2D((xmin, ymin), (xmax, ymin)), new LineArcLineSegment2D((xmax, ymin), (xmax, ymax)),
+ new LineArcLineSegment2D((xmax, ymax), (xmin, ymax)), new LineArcLineSegment2D((xmin, ymax), (xmin, ymin))], false);
+ // A deterministic two-arc loop avoids a reused longitudinal seam edge.
+ // It is still one exact circle/cylinder support, but yields normal
+ // DirectedEdgeUse closure and correct signed mass integration.
+ var inner = new LineArcProfileLoop2D([
+ new LineArcCircularArc2D((placement.LocalCenterX, placement.LocalCenterY), feature.Shaft.Radius, 0d, -Math.PI),
+ new LineArcCircularArc2D((placement.LocalCenterX, placement.LocalCenterY), feature.Shaft.Radius, Math.PI, -Math.PI)], true);
+ var planned = ProfileExtrusionBRepPlanner.TryPlan(new LineArcProfileExtrudeRequest([outer, inner], zmax, frame, 0d, zmax));
+ if (!planned.Succeeded || planned.Plan is null)
+ {
+ diagnostics.AddRange(planned.Diagnostics); diagnostics.Add("HolePlanInvalid: local-frame circular extrusion plan was not created.");
+ return new(AirHoleSimpleShaftMaterializationStatus.ExecutionFailed, null, null, diagnostics);
+ }
+ var holePlan = LocalFrameHoleBRepPlan.FromProfilePlan(feature, placement, (0d, zmax), planned.Plan);
+ var materialized = ProfileExtrusionBRepMaterializer.TryMaterialize(planned.Plan);
+ diagnostics.AddRange(materialized.Diagnostics);
+ if (!materialized.Succeeded || materialized.Body is null)
+ {
+ diagnostics.Add("HoleMaterializerDiverged: authoritative HoleBRepPlan failed materialization.");
+ return new(AirHoleSimpleShaftMaterializationStatus.ExecutionFailed, null, null, diagnostics);
+ }
+ var spec = new ProfileStackExtrudeSpec(host.Width, host.Depth, host.ZMin, host.ZMax, [], [], placement.LocalCenterX, placement.LocalCenterY);
+ var plan = new AirHoleSimpleShaftMaterializationPlan(feature, host, feature.FeatureId, nameof(AirHoleFeature), placement.ConstructionPlaneId,
+ placement.LocalCenterX, placement.LocalCenterY, 1d, feature.Shaft.Radius, 0d, zmax, feature.EndCondition.Kind, feature.Stack.Kind,
+ feature.Stack.Components.Select(c => c.Kind).ToArray(), spec, diagnostics.ToArray(), holePlan);
+ diagnostics.Add($"HostMaterialIntervals:[0,{zmax:R}] local-Z; constructionPlane={placement.ConstructionPlaneId}; sourceConceptPlane={placement.SourceConceptPlaneId}.");
+ diagnostics.Add("local-frame-hole materialization succeeded: authoritative HoleBRepPlan -> ProfileExtrusionBRepMaterializer.");
+ return new(AirHoleSimpleShaftMaterializationStatus.Succeeded, plan, materialized.Body, diagnostics, holePlan.Correspondence);
+ }
+
+ private static bool IsSignedAxis(Aetheris.Kernel.Core.Math.Direction3D axis)
+ {
+ var values = new[] { Math.Abs(axis.ToVector().X), Math.Abs(axis.ToVector().Y), Math.Abs(axis.ToVector().Z) };
+ return values.Count(v => Math.Abs(v - 1d) <= Tolerance) == 1 && values.Count(v => v <= Tolerance) == 2;
+ }
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/LocalFrameHoleBRepPlan.cs b/Aetheris.Kernel.Firmament/Materializer/LocalFrameHoleBRepPlan.cs
new file mode 100644
index 00000000..5ccf5922
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/LocalFrameHoleBRepPlan.cs
@@ -0,0 +1,43 @@
+using Aetheris.Kernel.Core.Air;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+/// <summary>
+/// Authoritative semantic wrapper for the local-frame hole topology. The shared
+/// ProfileExtrusionBRepPlan remains the owner of vertices, curve supports,
+/// DirectedEdgeUse loops, surfaces, faces, shell, and materialization identity.
+/// This wrapper owns the Hole-specific frame, host interval, and descendant roles.
+/// </summary>
+internal sealed record LocalFrameHoleBRepPlan(
+ string StableId,
+ string FeatureId,
+ AirConstructionPlaneHolePlacement Placement,
+ (double Start, double End) HostMaterialInterval,
+ ProfileExtrusionBRepPlan Topology,
+ SemanticTopologyCorrespondence Correspondence,
+ IReadOnlyList<string> Provenance)
+{
+ public static LocalFrameHoleBRepPlan FromProfilePlan(AirHoleFeature feature, AirConstructionPlaneHolePlacement placement,
+ (double Start, double End) interval, ProfileExtrusionBRepPlan topology)
+ {
+ var innerStart = topology.Loops.Single(x => x.Role == ProfileExtrusionPlanRole.LocalStartCapLoop && x.SourceStableId.EndsWith("Loop1", StringComparison.Ordinal));
+ var innerEnd = topology.Loops.Single(x => x.Role == ProfileExtrusionPlanRole.LocalEndCapLoop && x.SourceStableId.EndsWith("Loop1", StringComparison.Ordinal));
+ var walls = topology.Faces.Where(x => x.Role == ProfileExtrusionPlanRole.SideFace &&
+ topology.Surfaces.Single(s => s.Id == x.SurfaceId).Geometry.Kind == Aetheris.Kernel.Core.Geometry.SurfaceGeometryKind.Cylinder).ToArray();
+ var source = feature.FeatureId;
+ var descendants = new List<SemanticTopologyDescendant>
+ {
+ new($"plan:{source}:mouth-loop", "Loop", SemanticTopologyRole.HoleEntryLoop, source, Loop: innerStart.Id, ParentStableId: source),
+ new($"plan:{source}:exit-loop", "Loop", SemanticTopologyRole.HoleExitLoop, source, Loop: innerEnd.Id, ParentStableId: source),
+
+ };
+ descendants.AddRange(walls.Select((wall, index) => new SemanticTopologyDescendant($"plan:{source}:shaft-wall:{index}", "Face", SemanticTopologyRole.HoleWallFace, source, Face: wall.Id, ParentStableId: source,
+ GeometryPreview: $"radius={feature.Shaft.Radius:R};localZ=[{interval.Start:R},{interval.End:R}]")));
+ descendants.AddRange(innerStart.Uses.Select(use => new SemanticTopologyDescendant($"plan:{source}:mouth-edge:{use.EdgeId.Value}", "Edge", SemanticTopologyRole.TopBoundary, source, Edge: use.EdgeId, ParentStableId: source)));
+ descendants.AddRange(innerEnd.Uses.Select(use => new SemanticTopologyDescendant($"plan:{source}:exit-edge:{use.EdgeId.Value}", "Edge", SemanticTopologyRole.BottomBoundary, source, Edge: use.EdgeId, ParentStableId: source)));
+ var provenance = new[] { "HoleBRepPlan", "ConstructionPlanePlacement", "HostMaterialIntervalQuery", "ProfileExtrusionBRepPlan", "AuthoritativeBRepPlan",
+ "ConstructionPlane:" + placement.ConstructionPlaneId, "ConceptPlane:" + placement.SourceConceptPlaneId };
+ return new($"brep-plan:hole:{source}:{placement.ConstructionPlaneId}", source, placement, interval, topology,
+ new SemanticTopologyCorrespondence(feature.TargetBodyId ?? "semantic-hole-host", descendants, provenance), provenance);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/ProfileExtrusionBRepPlan.cs b/Aetheris.Kernel.Firmament/Materializer/ProfileExtrusionBRepPlan.cs
index 860ad3b2..1f73539f 100644
--- a/Aetheris.Kernel.Firmament/Materializer/ProfileExtrusionBRepPlan.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/ProfileExtrusionBRepPlan.cs
@@ -174,8 +174,12 @@ public static class ProfileExtrusionBRepPlanner
faces.Add(startFace); faces.Add(endFace);
foreach (var (sideLoop, surface, segmentSource, loopSource, startEdge, endEdge, startLongitudinal, endLongitudinal, isHole) in sideSpecs)
{
- var plannedSurface = new ProfileExtrusionPlanSurface($"plan:{segmentSource}:surface:side", new SurfaceGeometryId(nextSurface++), surface, true, segmentSource, ProfileExtrusionPlanRole.SideFace); surfaces.Add(plannedSurface);
- var sideFace = new ProfileExtrusionPlanFace($"plan:{segmentSource}:face:side", new FaceId(nextFace++), [sideLoop.Id], plannedSurface.Id, true, segmentSource, ProfileExtrusionPlanRole.SideFace); faces.Add(sideFace);
+ // A cylindrical inner loop bounds void material: retain its analytic
+ // outward support normal but reverse the face sense, so shell/mass
+ // orientation subtracts rather than adds the circular shaft.
+ var sideSameSense = !isHole;
+ var plannedSurface = new ProfileExtrusionPlanSurface($"plan:{segmentSource}:surface:side", new SurfaceGeometryId(nextSurface++), surface, sideSameSense, segmentSource, ProfileExtrusionPlanRole.SideFace); surfaces.Add(plannedSurface);
+ var sideFace = new ProfileExtrusionPlanFace($"plan:{segmentSource}:face:side", new FaceId(nextFace++), [sideLoop.Id], plannedSurface.Id, sideSameSense, segmentSource, ProfileExtrusionPlanRole.SideFace); faces.Add(sideFace);
if (sourceProfile is not null)
{
var prefix = $"material:{sourceProfile.Name}:{segmentSource}";
diff --git a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
index 72f1d8f5..87b5e4fd 100644
--- a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
@@ -63,7 +63,10 @@ public static class SemanticTopologySelectionResolver
foreach (var candidate in candidates)
{
var loop = body.Topology.Loops.Single(x => x.Id == candidate.Loop!.Value);
- if (loop.CoedgeIds.Count < 3) return Fail(SemanticSelectionFailure.DescendantsDoNotClose, "DescendantsDoNotClose", "A loop descendant is degenerate.", candidates);
+ // Exact circular boundaries can be represented by two analytic
+ // arc uses; directed closure below remains the authoritative
+ // non-degeneracy test.
+ if (loop.CoedgeIds.Count < 2) return Fail(SemanticSelectionFailure.DescendantsDoNotClose, "DescendantsDoNotClose", "A loop descendant is degenerate.", candidates);
var uses = loop.CoedgeIds.Select(id => body.Topology.Coedges.Single(x => x.Id == id)).Select(c => DirectedEdgeUse.Resolve(body.Topology.Edges.Single(e => e.Id == c.EdgeId), c)).ToArray();
if (uses.Where((use, index) => use.EndVertexId != uses[(index + 1) % uses.Length].StartVertexId).Any())
return Fail(SemanticSelectionFailure.DescendantsDoNotClose, "DescendantsDoNotClose", "A loop descendant does not have directed closure.", candidates);
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
index 0f5a3e12..7c85f9a0 100644
--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
@@ -877,6 +877,7 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
[Theory]
[InlineData("semantic-shaft-hole", "hole:base.mount")]
+ [InlineData("construction-plane-through-hole", "hole:Base.SideMount")]
[InlineData("split-compose-chamfer", "profile:BaseProfile.Outer.South")]
[InlineData("ctc-01-x3", "profile:CentralHex.Outer.SouthEast")]
[InlineData("ctc-01-x4", "hole:Ctc01PrismaticBlockoutX4.LeftTopMount")]
diff --git a/Aetheris.Server/Api/CadmataFixtureService.cs b/Aetheris.Server/Api/CadmataFixtureService.cs
index 4276e528..8103a42e 100644
--- a/Aetheris.Server/Api/CadmataFixtureService.cs
+++ b/Aetheris.Server/Api/CadmataFixtureService.cs
@@ -15,6 +15,7 @@ internal static class CadmataFixtureService
["construction-plane-positive-x"] = "fixtures/FirmamentV2/Profile/valid/construction-plane-positive-x.firmament",
["split-compose-chamfer"] = "fixtures/FirmamentV2/ProfileComposition/valid/semantic-split-compose-chamfer.firmament",
["semantic-shaft-hole"] = "fixtures/FirmamentV2/Hole/valid/semantic-shaft-selection.firmament",
+ ["construction-plane-through-hole"] = "fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament",
["ctc-01-x3"] = "testdata/firmament/reconstructions/nist_ctc_01/ctc01_prismatic_blockout_x3.firmament",
["ctc-01-x4"] = "testdata/firmament/reconstructions/nist_ctc_01/ctc01_prismatic_blockout_x4.firmament",
["semantic-capsule-slot"] = "fixtures/FirmamentV2/ProfileComposition/valid/semantic-capsule-slot-through.firmament",
@@ -28,13 +29,13 @@ internal static class CadmataFixtureService
if (!File.Exists(sourcePath)) { error = $"Cadmata fixture source is unavailable: {relative}."; return false; }
var source = File.ReadAllText(sourcePath);
BrepBody? body = null; SemanticTopologyCorrespondence? correspondence = null; IReadOnlyList<ResolvedProfile2D> profiles = []; IReadOnlyList<PrismaticShaftHoleFeature> shaftHoles = []; IReadOnlyList<PrismaticCapsuleSlotFeature> capsuleSlots = []; IReadOnlyList<PrismaticRoundedRectangleSlotFeature> roundedRectangleSlots = [];
- var diagnostics = new List<string>();
- if (fixtureId == "semantic-shaft-hole")
+ var diagnostics = new List<string>(); SemanticHoleSourceInspectionEvidence? semanticHoleEvidence = null;
+ if (fixtureId is "semantic-shaft-hole" or "construction-plane-through-hole")
{
var parsed = FirmamentV2Parser.Parse(source, Path.GetDirectoryName(sourcePath));
if (!parsed.IsSuccess || parsed.Document is null) { error = string.Join("; ", parsed.Diagnostics); return false; }
var inspected = SemanticHoleInspection.Inspect(parsed.Document);
- body = inspected.Body; correspondence = inspected.Correspondence; diagnostics.AddRange(inspected.Diagnostics);
+ body = inspected.Body; correspondence = inspected.Correspondence; semanticHoleEvidence = inspected.Evidence; diagnostics.AddRange(inspected.Diagnostics);
}
else if (PrismaticProfileCompositionParser.IsCompositionSource(source))
{
@@ -59,12 +60,12 @@ internal static class CadmataFixtureService
}
if (body is null) { error = "The compiler did not materialize a body for this Cadmata fixture."; return false; }
var added = document.AddBody(body, $"Cadmata: {fixtureId}");
- var artifact = BuildArtifact(fixtureId, relative, profiles, shaftHoles, capsuleSlots, roundedRectangleSlots, correspondence, diagnostics, body);
+ var artifact = BuildArtifact(fixtureId, relative, profiles, shaftHoles, capsuleSlots, roundedRectangleSlots, correspondence, diagnostics, body, semanticHoleEvidence);
response = new(document.Id.ToString(), added.OccurrenceId.ToString(), added.DefinitionId.ToString(), fixtureId, artifact);
return true;
}
- private static CadmataVisualizationArtifactDto BuildArtifact(string fixtureId, string sourcePath, IReadOnlyList<ResolvedProfile2D> profiles, IReadOnlyList<PrismaticShaftHoleFeature> shaftHoles, IReadOnlyList<PrismaticCapsuleSlotFeature> capsuleSlots, IReadOnlyList<PrismaticRoundedRectangleSlotFeature> roundedRectangleSlots, SemanticTopologyCorrespondence? correspondence, IReadOnlyList<string> diagnostics, BrepBody body)
+ private static CadmataVisualizationArtifactDto BuildArtifact(string fixtureId, string sourcePath, IReadOnlyList<ResolvedProfile2D> profiles, IReadOnlyList<PrismaticShaftHoleFeature> shaftHoles, IReadOnlyList<PrismaticCapsuleSlotFeature> capsuleSlots, IReadOnlyList<PrismaticRoundedRectangleSlotFeature> roundedRectangleSlots, SemanticTopologyCorrespondence? correspondence, IReadOnlyList<string> diagnostics, BrepBody body, SemanticHoleSourceInspectionEvidence? semanticHoleEvidence = null)
{
var entities = new List<CadmataVisualizationEntityDto>();
foreach (var profile in profiles)
@@ -88,6 +89,19 @@ internal static class CadmataFixtureService
entities.Add(new(id, "HoleFeature", "mount", "conceptAxes", "SemanticHole", new("circle", Center: new(1.5, -1, 5), Radius: 2), "offset:0", null, null, null, correspondence?.Descendants.Select(d => d.StableId).ToArray(), null, null, "AirHoleSimpleShaftMaterializer", null, new Dictionary<string, string> { ["diameter"] = "4 mm", ["axis"] = "+Z", ["endCondition"] = "throughAll" }));
entities.Add(new("concept:base.mount.axis", "ConceptAxis", "mount axis", "conceptAxes", "HoleAxis", new("polyline", [new(1.5, -1, -5), new(1.5, -1, 5)]), "offset:0", [id], null, null, null, null, null, null, null, null));
}
+ if (semanticHoleEvidence is { PlacementKind: "ConstructionPlane", FrameOrigin: { } origin, AxisX: { } axisX, AxisY: { } axisY, AxisZ: { } axisZ, WorldMouthCenter: { } mouth, HostInterval: { } interval })
+ {
+ CadmataPointDto P(double[] v) => new(v[0], v[1], v[2]);
+ var frameOrigin = P(origin); var x = P(axisX); var y = P(axisY); var z = P(axisZ); var mouthPoint = P(mouth);
+ CadmataPointDto Add(CadmataPointDto a, CadmataPointDto direction, double scale) => new(a.X + direction.X * scale, a.Y + direction.Y * scale, a.Z + direction.Z * scale);
+ var featureId = "hole:" + semanticHoleEvidence.FeatureId;
+ var frameAxes = new[] { frameOrigin, Add(frameOrigin, x, 8), frameOrigin, Add(frameOrigin, y, 8), frameOrigin, Add(frameOrigin, z, 8) };
+ entities.Add(new(semanticHoleEvidence.ConstructionPlaneId!, "ConstructionPlane", semanticHoleEvidence.ConstructionPlaneId!, "constructionPlanes", "ConstructionFrame", new("polyline", frameAxes), semanticHoleEvidence.SourceSpan, [semanticHoleEvidence.SourceConceptPlaneId!], [featureId], null, null, null, null, null, null, new Dictionary<string, string> { ["sourceConceptId"] = semanticHoleEvidence.SourceConceptPlaneId! }));
+ entities.Add(new(semanticHoleEvidence.SourceConceptPlaneId!, "ConceptPlane", semanticHoleEvidence.SourceConceptPlaneId!, "conceptPlanes", "ConceptGuide", new("polyline", frameAxes), semanticHoleEvidence.SourceSpan, null, [semanticHoleEvidence.ConstructionPlaneId!], null, null, null, null, null, null, null));
+ var descendants = correspondence?.Descendants.Select(d => d.StableId).ToArray() ?? [];
+ entities.Add(new(featureId, "HoleFeature", semanticHoleEvidence.FeatureId, "conceptAxes", "SemanticHole", new("circle", Center: mouthPoint, Radius: semanticHoleEvidence.Radius), semanticHoleEvidence.SourceSpan, [semanticHoleEvidence.ConstructionPlaneId!], null, null, descendants, null, null, "LocalFrameHoleBRepPlan", null, new Dictionary<string, string> { ["placementKind"] = "ConstructionPlane", ["extent"] = semanticHoleEvidence.Extent, ["hostInterval"] = $"{interval[0]:R}..{interval[1]:R}" }));
+ entities.Add(new(featureId + ".axis", "ConceptAxis", "drilling axis", "conceptAxes", "HoleAxis", new("polyline", [mouthPoint, Add(mouthPoint, z, interval[1] - interval[0])]), semanticHoleEvidence.SourceSpan, [featureId], null, null, null, null, null, null, null, null));
+ }
foreach (var hole in shaftHoles)
{
double BoundaryZ(SemanticTopologyRole role, double fallback)
@@ -121,8 +135,8 @@ internal static class CadmataFixtureService
{
entities.Add(new(descendant.StableId, $"BRep{descendant.Kind}", descendant.Role.ToString(), descendant.Kind == "Face" ? "selections" : "brepEdges", descendant.Role.ToString(), null, null, [descendant.SourceStableId], null, null, null, new(descendant.Face is { } face ? [face.Value] : null, descendant.Edge is { } edge ? [edge.Value] : null, descendant.Loop is { } loop ? [loop.Value] : null, descendant.Vertex is { } vertex ? [vertex.Value] : null), null, null, null, null));
}
- var hasSemanticFeatures = fixtureId == "semantic-shaft-hole" || shaftHoles.Count > 0 || capsuleSlots.Count > 0 || roundedRectangleSlots.Count > 0;
- var selectionSourceIds = fixtureId == "semantic-shaft-hole" ? new[] { "hole:base.mount" } : capsuleSlots.Count > 0 ? capsuleSlots.Select(slot => slot.StableId).ToArray() : roundedRectangleSlots.Count > 0 ? roundedRectangleSlots.Select(slot => slot.StableId).ToArray() : shaftHoles.Count > 0 ? shaftHoles.Select(hole => hole.StableId).ToArray() : entities.Where(e => e.Kind == "ProfileSegment").Select(e => e.StableId).ToArray();
+ var hasSemanticFeatures = fixtureId is "semantic-shaft-hole" or "construction-plane-through-hole" || shaftHoles.Count > 0 || capsuleSlots.Count > 0 || roundedRectangleSlots.Count > 0;
+ var selectionSourceIds = fixtureId == "semantic-shaft-hole" ? new[] { "hole:base.mount" } : fixtureId == "construction-plane-through-hole" && semanticHoleEvidence is not null ? new[] { "hole:" + semanticHoleEvidence.FeatureId } : capsuleSlots.Count > 0 ? capsuleSlots.Select(slot => slot.StableId).ToArray() : roundedRectangleSlots.Count > 0 ? roundedRectangleSlots.Select(slot => slot.StableId).ToArray() : shaftHoles.Count > 0 ? shaftHoles.Select(hole => hole.StableId).ToArray() : entities.Where(e => e.Kind == "ProfileSegment").Select(e => e.StableId).ToArray();
var selection = new CadmataVisualizationSelectionDto($"selection:{fixtureId}", hasSemanticFeatures ? "semantic feature descendants" : "compiler-published profile boundary", hasSemanticFeatures ? "FaceSet" : "LoopSet", selectionSourceIds, selectionSourceIds, !hasSemanticFeatures, []);
return new("cadmata-concept-viz-x1", fixtureId, sourcePath, entities, [selection], diagnostics.Select(d => new CadmataVisualizationDiagnosticDto("Compiler.Trace", d, "info")).ToArray(), new Dictionary<string, double> { ["entityCount"] = entities.Count, ["faceCount"] = body.Topology.Faces.Count(), ["edgeCount"] = body.Topology.Edges.Count() });
}
diff --git a/docs/cadmata/concept-visualization-x1.md b/docs/cadmata/concept-visualization-x1.md
index 7e694ed0..6a146d03 100644
--- a/docs/cadmata/concept-visualization-x1.md
+++ b/docs/cadmata/concept-visualization-x1.md
@@ -88,3 +88,10 @@ replacement faces must not be inferred heuristically.
## Profile extrusion BRepPlan X1
For ordinary Profile extrusion, Cadmata continues to receive the Concept plane, Construction Plane, local Profile, world BRep body, and semantic descendants. The new plan inspector can supply a debug-only source segment → planned entity → material descendant chain without duplicating a frontend topology model. Cadmata must reference plan correspondence rather than reconstruct roles from viewport geometry.
+
+The `construction-plane-through-hole` fixture extends this handoff with a
+Construction Plane Hole. It publishes the source Concept Plane, Construction
+Plane, local-center marker, local-`+Z` drill axis, analytic shaft envelope,
+Mouth/Exit loops, and Shaft-wall faces. The Hole and plane reference each other
+through stable ids, so selection highlights compiler-published consumers and
+descendants rather than tessellation-derived cylinders.
diff --git a/docs/firmament/concept-plane-drilled-holes-x1.md b/docs/firmament/concept-plane-drilled-holes-x1.md
index 10da9e2e..13fca5e9 100644
--- a/docs/firmament/concept-plane-drilled-holes-x1.md
+++ b/docs/firmament/concept-plane-drilled-holes-x1.md
@@ -103,3 +103,8 @@ vulnerability warnings from the JavaScript SDK audit; it has no .NET errors.
## LOCAL-FRAME-HOLE-X2 extension point
PROFILE-EXTRUSION-BREPPLAN-X1 supplies the required single topology authority for a future local-frame hole. A Hole should lower to local Construction AIR and append/reuse `ProfileExtrusionBRepPlan` primitives for mouth loops, shaft cylinders, optional cone/tip entities, and plan-owned semantic descendants. It reuses the immutable frame, local/world mapping, cap and cylinder orientations, directed loop closure, materializer, STEP emission, and Cadmata correspondence. Host subtraction and drill-point cones remain deliberately unimplemented here.
+
+X3 implements the bounded source-to-material successor for a Box `ThroughAll`
+shaft: new sources lower directly to `AirConstructionPlaneHolePlacement`, then
+to `LocalFrameHoleBRepPlan`. Blind DrillPoint remains the next extension, not a
+claimed capability; see [Construction Plane Hole source X3](construction-plane-hole-source-x3.md).
diff --git a/docs/firmament/construction-plane-hole-source-x3.md b/docs/firmament/construction-plane-hole-source-x3.md
new file mode 100644
index 00000000..9e04977c
--- /dev/null
+++ b/docs/firmament/construction-plane-hole-source-x3.md
@@ -0,0 +1,120 @@
+# Construction Plane Hole source X3
+
+Construction Plane Hole placement is a source-level spatial contract, not a
+disguised face attachment. New semantic Hole sources resolve their location and
+drilling axis from a traced Construction Plane; they never require an entry-face
+name, a raw BRep id, a world-space center, or a world-space axis.
+
+## Admitted source form
+
+```firmament
+Concept Struct SideLayout {
+ PositiveXDatum: Plane {
+ Origin: [-50mm, 0mm, 0mm]
+ Normal: [1, 0, 0]
+ Up: [0, 0, 1]
+ }
+}
+
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base {
+ Hole<Shaft> SideMount {
+ From: PositiveXWorkplane
+ Center: Point2(10mm, 6mm)
+ Diameter: 8mm
+ End: ThroughAll
+ }
+ }
+}
+```
+
+`Center` is local `(U,V)` in the Construction Plane. Local `+Z` is the drill
+direction. In the fixture above the resolved world mouth is `[-50, 10, 6]` and
+the drilling direction is world `+X`, proving that placement is not an implicit
+world-Z or face-local operation.
+
+## Placement and lowering contract
+
+The bound declaration has an explicit placement union:
+
+- `FirmamentV2ConstructionPlaneHolePlacement` holds the resolved Construction
+ Plane, its source Concept Plane identity, and the local center.
+- `FirmamentV2FaceLocalHolePlacement` preserves the existing compatibility lane.
+
+Exactly one mode is valid. A `From` Construction Plane cannot be combined with
+legacy `On` face placement. Missing `Center`, an unknown plane, or a non-
+`ThroughAll` termination produces a typed source diagnostic. Construction Plane
+resolution is performed by the existing Concept Plane/Construction Plane trace;
+the Hole binder consumes that immutable result and does not derive a frame from
+final BRep geometry.
+
+New Hole sources lower directly to `AirConstructionPlaneHolePlacement`. Its
+stable Hole id, Construction Plane id, source Concept Plane id, frame origin and
+axes, local center, world mouth center, diameter, termination, provenance, and
+source span survive to materialization. No fake face name is synthesized. The
+legacy route lowers to `AirFaceLocalHolePlacement` and remains supported for
+existing fixtures only.
+
+## Bounded material route
+
+Production dispatch is explicit:
+
+```text
+Firmament Hole From ConstructionPlane
+ -> AirConstructionPlaneHolePlacement
+ -> LocalFrameHoleBRepPlan
+ -> ProfileExtrusionBRepPlan materialization
+ -> exact STEP / reimport / M8
+```
+
+X3 admits only a simple Box host, an orientation accepted by the local-frame
+planner (the verified signed-permutation frame with mouth at local `Z=0` and
+host material in local `+Z`), and `ThroughAll`. The plan publishes the resolved
+local host interval and owns the semantic correspondence: Mouth loop/edges,
+Exit loop/edges, and Shaft-wall faces. Selection resolution consumes those
+published descendants as `LoopSet`, `EdgeSet`, and `FaceSet`; it does not search
+final coordinates.
+
+Unsupported host/frame/termination requests fail explicitly through the
+Construction Plane host, orientation, or extent diagnostic paths. X3 does not
+claim blind/flat-bottom/DrillPoint geometry, `ShaftDepth`, `TotalDepth`,
+composed-host traversal, arbitrary proper frames, CTC side holes, countersinks,
+or counterbores. The extension point for blind DrillPoint is
+`LocalFrameHoleBRepPlan`: add the local termination surfaces/loops and their
+plan-owned correspondence before asking the shared profile-extrusion
+materializer to make topology.
+
+## Inspection and Cadmata
+
+`aetheris inspect-selections <source> --json` emits the source-to-plan evidence
+for each Construction Plane Hole: feature and plane ids, frame origin/axes,
+local and world centers, diameter/radius, `ThroughAll`, host interval,
+`LocalFrameHoleBRepPlan` id, source declaration, AIR placement, plan-owned
+descendants, final topology ids, provenance, selections, diagnostics, and
+timings.
+
+The `construction-plane-through-hole` Cadmata fixture publishes the compiler-
+owned Concept Plane and Construction Plane, local center, drill axis, analytic
+cylindrical envelope, Mouth/Exit loops, and Shaft-wall descendants. Selecting
+the Hole uses stable correspondence to highlight its frame and material
+descendants; selecting the Construction Plane exposes the Hole as its consumer.
+The viewport does not infer the cylinder from tessellation.
+
+## Evidence
+
+The production fixture is
+`fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament`.
+Its exact source build exports a STEP artifact with SHA-256
+`A6B557BD3DC54A6FF88686B82FA96F7CCFA4F40FC00E3353F40A59704204FB8C`.
+The published local interval is `[0, 100]`, so the analytic removed volume is
+`pi * 4^2 * 100 = 1600*pi` cubic millimetres. The exact independent STEP
+analysis reports `72000 - 1600*pi = 66973.45175425633` cubic millimetres. It
+deduplicates the two seam-partitioned cylinder faces as one physical bore. STEP
+reimport reports one body, one enclosed shell, 8 faces, 18 edges, 12 vertices,
+6 planar faces, and 2 cylindrical faces. M8's deterministic trimmed-face
+boundary integral reports `66987.79421875` with conservative error bound
+`7300.494418725005`; it is enclosed and orientation-consistent. Both bodies'
+non-Z cylinder axis is the Construction Plane's world `+X` axis.
diff --git a/docs/firmament/construction-planes-x1.md b/docs/firmament/construction-planes-x1.md
index a9db8b90..8abeed86 100644
--- a/docs/firmament/construction-planes-x1.md
+++ b/docs/firmament/construction-planes-x1.md
@@ -39,4 +39,9 @@ Semantic descendants now publish `LocalStartBoundary`, `LocalEndBoundary`, `Loca
Construction Planes define local material coordinates. Authoritative BRepPlans carry those coordinates into exact topology. `ProfileExtrusionConstructionAir` normalizes a local Profile plus the immutable frame and local interval; `ProfileExtrusionBRepPlan` owns all vertices, supports, edges, directed uses, loops, faces, senses, shell/body, and source correspondence before any BRep is made. The default world-XY frame is the same route, not a parallel planner. `inspect-profile --json` includes that pre-materialization plan.
+Construction Plane semantic shaft Holes now use the same source-level frame
+contract: `From: Workplane`, local `Center: Point2(...)`, and local `+Z`
+`ThroughAll`. The bounded X3 route and compatibility policy are documented in
+[Construction Plane Hole source X3](construction-plane-hole-source-x3.md).
+
Current scope is a proper rigid frame and standalone/additive planar line/arc Profile extrusion. Reflections, scaling, shearing, arbitrary completed-plan transforms, mutable face attachment, generic constraints, and host-subtracted local-frame holes remain unsupported. LOCAL-FRAME-HOLE-X2 should consume `ConstructionPlane` directly for placement and add only the bounded host/subtraction contract; it must not add topology attachment or recompute the frame.
diff --git a/docs/firmament/local-frame-holes-x2.md b/docs/firmament/local-frame-holes-x2.md
new file mode 100644
index 00000000..7a16250c
--- /dev/null
+++ b/docs/firmament/local-frame-holes-x2.md
@@ -0,0 +1,31 @@
+# Local-frame semantic holes (X2)
+
+Construction Planes provide pre-solved local material coordinates. Holes remain ordinary local-Z drilling features.
+
+The first X2 production lane accepts a semantic shaft hole whose immutable
+`ConstructionPlanePlacement` carries the traced Concept Plane identity, frame
+origin, proper local axes, and a local XY center. It does not use an entry-face
+name, a raw topology identifier, or a completed-body transform. The legacy
+face-local `AirFaceLocalHolePlacement` remains the compatibility route for
+existing sources only.
+
+For an admitted rectangular Box host, the compiler transforms the eight host
+corners into the supplied local frame. It admits only a proper signed-permutation
+frame with the mouth on local Z=0 and material on local +Z. This proves one exact
+host interval `[0, span]`; directions away from the host and mouths outside the
+cross-section are rejected explicitly. The result is an authoritative
+`LocalFrameHoleBRepPlan` which owns Hole frame/interval/descendants and delegates
+shared vertices, analytic circle/cylinder supports, DirectedEdgeUse loops, faces,
+shell, and materialization to `ProfileExtrusionBRepPlan`.
+
+This lane currently implements only a simple `ThroughAll` shaft on a simple Box.
+It publishes Mouth loop/edge, Exit loop/edge, and Shaft wall-face descendants,
+then exports an exact analytic cylinder through the normal STEP path. Blind
+flat-bottom and DrillPoint (`ShaftDepth`/`TotalDepth`, default 118deg) are not
+implemented by this narrow lane yet; they must not silently fall back to an
+oversized cut or mutable face attachment.
+
+X3 makes this kernel lane reachable from ordinary Firmament source. See
+[Construction Plane Hole source X3](construction-plane-hole-source-x3.md) for
+the source declaration, typed placement union, inspection evidence, and the
+strict compatibility boundary with legacy face-local holes.
diff --git a/docs/firmament/semantic-selections-x1.md b/docs/firmament/semantic-selections-x1.md
index c149d367..cd336eec 100644
--- a/docs/firmament/semantic-selections-x1.md
+++ b/docs/firmament/semantic-selections-x1.md
@@ -44,6 +44,12 @@ The verification artifact is `artifacts/semantic-top-boundary-chamfer.step`, SHA
This is the Cadmata handoff shape. It intentionally includes geometry preview only where the producer has one, and does not add rendering or interactive selection editing.
+For a Construction Plane Hole, `inspect-selections` additionally resolves the
+compiler-published `MouthLoop`, `ExitLoop`, and `ShaftWallFaces` roles. The
+source frame, AIR placement, local-frame plan, final topology ids, and each
+result appear together; no geometric predicate is introduced. See
+[Construction Plane Hole source X3](construction-plane-hole-source-x3.md).
+
## Compose X2 extension
The section-stack emitter now publishes correspondence while it consumes normalized arrangement fragments. Each retained Profile segment retains its `arrangement.partN` provenance interval and becomes a stable BRepPlan-side edge/face descendant carrying its slab context. CTC X3 resolves `LeftTopEar.Outer.OuterArc` as one open top-boundary chain and all six `CentralHex` segments as one closed top-boundary loop. No CTC finish is claimed: the current chamfer materializer is intentionally limited to its history-known rectangular profile case.
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-blind.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-blind.invalid.firmament
new file mode 100644
index 00000000..dec0668c
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-blind.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; Center: Point2(10mm, 6mm); Diameter: 8mm; End: Blind } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-duplicate-placement.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-duplicate-placement.invalid.firmament
new file mode 100644
index 00000000..659a6a15
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-duplicate-placement.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; From: PositiveXWorkplane; Center: Point2(10mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-host-unsupported.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-host-unsupported.invalid.firmament
new file mode 100644
index 00000000..52994e47
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-host-unsupported.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Cylinder Base { Radius: 50mm; Height: 12mm }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; Center: Point2(10mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-missing-center.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-missing-center.invalid.firmament
new file mode 100644
index 00000000..03573e97
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-missing-center.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-mixed-placement.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-mixed-placement.invalid.firmament
new file mode 100644
index 00000000..0af9f79c
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-mixed-placement.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; On: Base.Top; Center: Point2(10mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-mouth-misses-host.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-mouth-misses-host.invalid.firmament
new file mode 100644
index 00000000..9bdf4d7e
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-mouth-misses-host.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: PositiveXWorkplane; Center: Point2(40mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-orientation.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-orientation.invalid.firmament
new file mode 100644
index 00000000..080a1f41
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-orientation.invalid.firmament
@@ -0,0 +1,8 @@
+Concept Struct SideLayout {
+ DiagonalDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [0.7071067811865476, 0.7071067811865476, 0]; Up: [0, 0, 1] }
+}
+Construction Plane DiagonalWorkplane { Trace: SideLayout.DiagonalDatum }
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: DiagonalWorkplane; Center: Point2(10mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/invalid/construction-plane-unknown.invalid.firmament b/fixtures/FirmamentV2/Hole/invalid/construction-plane-unknown.invalid.firmament
new file mode 100644
index 00000000..4469c1f4
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/invalid/construction-plane-unknown.invalid.firmament
@@ -0,0 +1,7 @@
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base { Hole<Shaft> SideMount { From: MissingWorkplane; Center: Point2(10mm, 6mm); Diameter: 8mm; End: ThroughAll } }
+}
diff --git a/fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament b/fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament
new file mode 100644
index 00000000..a2d06aa1
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/valid/construction-plane-through-hole.firmament
@@ -0,0 +1,22 @@
+// CONSTRUCTION-PLANE-HOLE-SOURCE-X3: source-level +X semantic shaft hole.
+// expected-stage: step-verified
+// current-stage: step-verified
+// roundtrip-required: true
+// build-command: aetheris build
+Concept Struct SideLayout {
+ PositiveXDatum: Plane { Origin: [-50mm, 0mm, 0mm]; Normal: [1, 0, 0]; Up: [0, 0, 1] }
+}
+
+Construction Plane PositiveXWorkplane { Trace: SideLayout.PositiveXDatum }
+
+Struct SideHoleBracket {
+ Box Base { Size: [100mm, 60mm, 12mm] }
+ Modify Base {
+ Hole<Shaft> SideMount {
+ From: PositiveXWorkplane
+ Center: Point2(10mm, 6mm)
+ Diameter: 8mm
+ End: ThroughAll
+ }
+ }
+}