Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add AIR region trace skeleton

Yuechen Lif0e3d96af1c2
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index a78d924b..1ade5308 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -288,8 +288,81 @@ public sealed class AirTraceCommandTests
Assert.Equal(Run("trace", "--fixture", invalid, "--json").Stdout, Run("trace", "--fixture", invalid, "--json").Stdout);
}
+
+ [Fact]
+ public void TraceParserBackedBoxFixture_IncludesRootRegion()
+ {
+ var (exitCode, output, _) = Run("trace", "--fixture", PrimitiveFixture("valid/box.valid.firmfixture"), "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var regions = doc.RootElement.GetProperty("regions");
+ Assert.Equal(1, regions.GetProperty("regionCount").GetInt32());
+ Assert.False(regions.GetProperty("hasNestedRegions").GetBoolean());
+ var rootRegion = regions.GetProperty("regions")[0];
+ Assert.Equal("RootRegion", rootRegion.GetProperty("regionKind").GetString());
+ Assert.Equal("WorldRoot", rootRegion.GetProperty("localFrame").GetProperty("frameKind").GetString());
+ Assert.Equal("PureConstruction", rootRegion.GetProperty("effectKind").GetString());
+ Assert.Equal("NotRequired", rootRegion.GetProperty("integrationStatus").GetString());
+ }
+
+ [Fact]
+ public void TraceSideHoleFaceAttachedRegion_DefaultText()
+ {
+ var (exitCode, output, error) = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"));
+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.Contains("Regions", output); Assert.Contains("FaceAttachedRegion", output);
+ Assert.Contains("Subtractive", output); Assert.Contains("YieldSubtractiveVolume", output);
+ Assert.Contains("YieldsCutVolume", output); Assert.Contains("Integration: Deferred", output);
+ Assert.Contains("no Boolean", output); Assert.Contains("no BRep emission", output);
+ }
+
+ [Fact]
+ public void TraceSideHoleFaceAttachedRegion_Json()
+ {
+ var (exitCode, output, _) = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"), "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.Equal("valid", root.GetProperty("fixture").GetProperty("expectation").GetString());
+ Assert.True(root.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean());
+ Assert.Equal("region-integration-deferred", root.GetProperty("actualStageReached").GetString());
+ var regions = root.GetProperty("regions");
+ Assert.Equal(2, regions.GetProperty("regionCount").GetInt32());
+ Assert.True(regions.GetProperty("hasNestedRegions").GetBoolean());
+ var side = regions.GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion");
+ Assert.Equal("region:root", side.GetProperty("parentRegionId").GetString());
+ Assert.Equal("Subtractive", side.GetProperty("effectKind").GetString());
+ Assert.Equal("YieldSubtractiveVolume", side.GetProperty("yieldKind").GetString());
+ Assert.Equal("YieldsCutVolume", side.GetProperty("boundaryContractKind").GetString());
+ Assert.Equal("Deferred", side.GetProperty("integrationStatus").GetString());
+ Assert.False(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
+ Assert.False(root.GetProperty("stepSmoke").GetProperty("succeeded").GetBoolean());
+ Assert.Equal("none", root.GetProperty("brepPlan").GetProperty("planKind").GetString());
+ }
+
+ [Fact]
+ public void TraceImplicitParentMutationRegion_Rejected()
+ {
+ var (exitCode, output, _) = Run("trace", "--fixture", RegionFixture("invalid/implicit-parent-mutation.invalid.firmfixture"), "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.Equal("invalid", root.GetProperty("fixture").GetProperty("expectation").GetString());
+ Assert.True(root.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean());
+ Assert.Equal("region-rejected", root.GetProperty("actualStageReached").GetString());
+ Assert.Contains("implicit parent mutation rejected", root.GetProperty("recommendation").GetString());
+ Assert.False(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
+ }
+
+ [Fact]
+ public void TraceRegionFixtures_DeterministicJson()
+ {
+ var valid = RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture");
+ var invalid = RegionFixture("invalid/implicit-parent-mutation.invalid.firmfixture");
+ Assert.Equal(Run("trace", "--fixture", valid, "--json").Stdout, Run("trace", "--fixture", valid, "--json").Stdout);
+ Assert.Equal(Run("trace", "--fixture", invalid, "--json").Stdout, Run("trace", "--fixture", invalid, "--json").Stdout);
+ }
+
private static string Fixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Chamfer", relative));
private static string PrimitiveFixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Primitive", relative));
+ private static string RegionFixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Region", relative));
private static (int ExitCode, string Stdout, string Stderr) Run(params string[] args)
{
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 31614433..0c8d737f 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -2,6 +2,7 @@ using System.Text;
using System.Text.Json.Serialization;
using Aetheris.Kernel.Core.Air;
using Aetheris.Kernel.Core.Air.BRepPlan;
+using Aetheris.Kernel.Core.Air.Regions;
using Aetheris.Kernel.Core.Brep.Prismatic;
using Aetheris.Kernel.Firmament;
@@ -39,7 +40,8 @@ internal sealed record AirTraceReport(
AirTraceFrontendSummary? Frontend = null,
AirTraceFeatureAirSummary? FeatureAir = null,
AirTraceConstructiveAirSummary? ConstructiveAir = null,
- AirTraceProfileEmissionSummary? ProfileEmission = null);
+ AirTraceProfileEmissionSummary? ProfileEmission = null,
+ [property: JsonPropertyName("regions")] AirRegionTraceSummary? Regions = null);
internal sealed record AirTraceFixtureSummary(string Path, string Expectation, string CaseName, string? ExpectedStage, string ActualStageReached, string? ExpectedRoute, string? ExpectedReason, bool ExpectationSatisfied, bool ParserBacked, IReadOnlyList<string> Diagnostics);
internal sealed record AirTraceFrontendSummary(bool ParserBacked, string? ParserName, bool? ParseSucceeded, IReadOnlyList<string> ParseDiagnostics, string? FrontendStageReached, string? FrontendSummary);
@@ -59,7 +61,7 @@ internal sealed record AirTraceCirMirrorSummary(string Status, string Backend, s
internal static class AirTraceReportBuilder
{
public static readonly string[] SupportedCases = ["prismatic-section-transition", "top-face-loop-chamfer"];
- public static readonly string[] SupportedFixtureCases = ["arbitrary-graph-chamfer", "box", "loop-fillet-deferred", "non-uniform-loop-chamfer", "top-face-loop-chamfer"];
+ public static readonly string[] SupportedFixtureCases = ["arbitrary-graph-chamfer", "box", "implicit-parent-mutation-region", "loop-fillet-deferred", "non-uniform-loop-chamfer", "side-hole-face-attached-region", "top-face-loop-chamfer"];
public static AirTraceReport Build(string caseName)
{
@@ -86,6 +88,8 @@ internal static class AirTraceReportBuilder
if (fixture.ParserBacked) return BuildParserBackedFixture(fixture);
var caseName = fixture.CaseName;
+ if (caseName == "side-hole-face-attached-region") return BuildSideHoleFaceAttachedRegionFixture(fixture);
+ if (caseName == "implicit-parent-mutation-region") return BuildImplicitParentMutationRegionFixture(fixture);
var report = caseName switch
{
"top-face-loop-chamfer" => BuildTopFaceLoopChamfer(),
@@ -103,7 +107,7 @@ internal static class AirTraceReportBuilder
var fxDiagnostics = Stable([.. fixture.Diagnostics, "air-x7-firmfixture-case-mapped", "air-x7-firmfixture-trace-created", "air-x7-lowering-stage-recorded", expectationSatisfied ? "air-x7-expectation-satisfied" : "air-x7-fixture-expectation-not-satisfied"]).ToArray();
return report with
{
- Milestone = "AIR-X7", InputKind = "firmfixture", FixturePath = fixture.Path, FixtureExpectation = fixture.Expectation, FixtureCaseName = caseName, ExpectedStage = fixture.ExpectedStage, ActualStageReached = actualStage, ExpectedRoute = fixture.ExpectedRoute, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, caseName, fixture.ExpectedStage, actualStage, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Diagnostics = Stable([.. report.Diagnostics, .. fxDiagnostics]).ToArray()
+ Milestone = "AIR-X7", InputKind = "firmfixture", FixturePath = fixture.Path, FixtureExpectation = fixture.Expectation, FixtureCaseName = caseName, ExpectedStage = fixture.ExpectedStage, ActualStageReached = actualStage, ExpectedRoute = fixture.ExpectedRoute, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, caseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Diagnostics = Stable([.. report.Diagnostics, .. fxDiagnostics]).ToArray()
};
}
@@ -111,7 +115,7 @@ internal static class AirTraceReportBuilder
{
var frontend = FirmamentFrontendTraceProbe.ParseOnly(fixture.SourceBody);
var profileEmissionProbe = frontend.ConstructiveAir is null ? null : BoxConstructiveAirToProfileEmissionTraceProbe.Invoke(frontend.ConstructiveAir);
- var actualStage = profileEmissionProbe?.StageReached ?? frontend.FrontendStageReached;
+ var actualStage = profileEmissionProbe?.StageReached ?? frontend.FrontendStageReached ?? "frontend-unavailable";
var expectedStageSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedStage) || string.Equals(actualStage, fixture.ExpectedStage, StringComparison.Ordinal);
var expectationSatisfied = fixture.Expectation == "valid"
? frontend.ParseSucceeded && expectedStageSatisfied && (profileEmissionProbe?.Succeeded ?? true)
@@ -133,6 +137,8 @@ internal static class AirTraceReportBuilder
? null
: new AirTraceConstructiveAirSummary(frontend.ConstructiveAir.NodeKind, frontend.ConstructiveAir.CanonicalForm, frontend.ConstructiveAir.SourceFeatureAirNodeKind, frontend.ConstructiveAir.ProfileKind, frontend.ConstructiveAir.Dimensions.Width, frontend.ConstructiveAir.Dimensions.Depth, frontend.ConstructiveAir.Dimensions.Height, frontend.ConstructiveAir.ExtrusionAxis, frontend.ConstructiveAir.ConstructionIntent, frontend.ConstructiveAir.RouteKind, frontend.ConstructiveAir.StageReached, frontend.ConstructiveAir.Diagnostics, frontend.ConstructiveAir.Guarantees);
+ var regions = AirRegionTraceFactory.ForRootBody(actualStage ?? "emitted-brep");
+ fxDiagnostics = Stable([.. fxDiagnostics, .. regions.Diagnostics]).ToArray();
var profileEmission = profileEmissionProbe is null ? null : new AirTraceProfileEmissionSummary(
profileEmissionProbe.WrapperInvoked,
profileEmissionProbe.EmitterName,
@@ -156,10 +162,10 @@ internal static class AirTraceReportBuilder
[], ["BRepPlan/CIR deferred for parser-backed box fixture", "STEP smoke unavailable for parser-backed box fixture"], fxDiagnostics,
["real Firmament parser invoked", "parser-backed fixture reaches Feature AIR summary", "parser-backed fixture reaches Constructive AIR summary", "ProfileExtrude wrapper invoked", "no production grammar expansion", "no production route replacement", "no new geometry", "no profile emitter rewrite"],
["no production Firmament grammar expansion", "no production route replacement", "no production analyzer behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no route-selection/JudgmentUtility behavior change", "no CIR evaluator/tape behavior change", "no Boolean behavior change", "no AirEdgeSweep behavior change", "no BrepBoundedChamfer/BrepBoundedFillet behavior change", "no chamfer/fillet/shell geometry change", "no new geometry"],
- new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, true, fxDiagnostics),
- fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics,
- new(true, frontend.ParserName, frontend.ParseSucceeded, frontend.Diagnostics, actualStage, frontend.FrontendSummary),
- featureAir, constructiveAir, profileEmission);
+ new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, true, fxDiagnostics),
+ fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics,
+ new(true, frontend.ParserName, frontend.ParseSucceeded, frontend.Diagnostics, actualStage!, frontend.FrontendSummary),
+ featureAir, constructiveAir, profileEmission, regions);
}
public static string FixtureFileStem(FirmFixture fixture) => $"air-x7-{fixture.CaseName}-firmfixture-trace";
@@ -183,6 +189,35 @@ internal static class AirTraceReportBuilder
return Compose("top-face-loop-chamfer", lowering, route, brepPlan, mirror, "PrismaticTopFaceLoopChamferPrototype / PrismaticSectionTransitionEmitter", SpecificGuarantees(["no AirEdgeSweep", "no BrepBoundedChamfer", "no topology graft", "no 3D Boolean", "no coplanar merge", "not four independent single-edge chamfers"]));
}
+ private static AirTraceReport BuildSideHoleFaceAttachedRegionFixture(FirmFixture fixture)
+ {
+ var regions = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();
+ var actualStage = "region-integration-deferred";
+ var expectationSatisfied = fixture.Expectation == "valid" && (string.IsNullOrWhiteSpace(fixture.ExpectedStage) || fixture.ExpectedStage == actualStage);
+ var fxDiagnostics = Stable([.. fixture.Diagnostics, .. regions.Diagnostics, "air-region-x1-firmfixture-case-mapped", expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();
+ return new("AIR-REGION-X1", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole yield is valid but parent integration is deferred; no geometry emitted.",
+ new("RegionFixture", "none", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X1"),
+ new("none", null, false, "region integration deferred; no route selection invoked", "none", "none", []),
+ new("none", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, "none", "none", null, []),
+ new("none", false, "no geometry emitted for trace-only region fixture"),
+ new(false, false, false, false, []),
+ new("not-requested", "none", "none", "RegionFixture", "none", "none", "none", [], [], [], []),
+ [], ["side-hole geometry integration not implemented"], fxDiagnostics,
+ [.. regions.Guarantees, "metadata-driven region fixture", "integration deferred"],
+ ["no AIR Region production integration", "no production route replacement", "no Firmament grammar expansion", "no BRepPlan semantics change", "no CIR evaluator/tape behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no route-selection/JudgmentUtility behavior change", "no production analyzer behavior change", "no Boolean behavior change", "no AirEdgeSweep behavior change", "no BrepBoundedChamfer/BrepBoundedFillet behavior change", "no chamfer/fillet/shell geometry change", "no arbitrary graph support", "no import/recovery", "no triangle migration", "no NURBS/freeform behavior change"],
+ new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics),
+ fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics, Regions: regions);
+ }
+
+ private static AirTraceReport BuildImplicitParentMutationRegionFixture(FirmFixture fixture)
+ {
+ var regions = AirRegionTraceFactory.ForImplicitParentMutationRejected();
+ var actualStage = "region-rejected";
+ var reasonSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedReason) || fixture.ExpectedReason == "implicit-parent-mutation-rejected";
+ var expectationSatisfied = fixture.Expectation == "invalid" && reasonSatisfied && (string.IsNullOrWhiteSpace(fixture.ExpectedStage) || fixture.ExpectedStage == actualStage);
+ var fxDiagnostics = Stable([.. fixture.Diagnostics, .. regions.Diagnostics, expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();
+ return BuildSideHoleFaceAttachedRegionFixture(fixture) with { Succeeded = false, Recommendation = "implicit parent mutation rejected", ActualStageReached = actualStage, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Diagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Regions = regions };
+ }
private static AirTraceReport BuildRejectedFixture(FirmFixture fixture, AirSelectionClass selectionClass, AirRuleKind ruleKind)
{
@@ -255,6 +290,20 @@ internal static class AirTraceTextRenderer
if (r.ProfileEmission.TopologySummary is not null) b.AppendLine($" Topology: vertices={r.ProfileEmission.TopologySummary.Vertices}, edges={r.ProfileEmission.TopologySummary.Edges}, faces={r.ProfileEmission.TopologySummary.Faces}, planarFaces={r.ProfileEmission.TopologySummary.PlanarFaces}, cylindricalFaces={r.ProfileEmission.TopologySummary.CylindricalFaces}, bounds={r.ProfileEmission.TopologySummary.Bounds}");
b.AppendLine($" STEP smoke: {(r.ProfileEmission.StepSmoke.Succeeded ? "succeeded" : r.ProfileEmission.StepSmoke.WasChecked ? "failed" : "unavailable")}"); b.AppendLine(" Diagnostics:"); foreach (var d in r.ProfileEmission.Diagnostics) b.AppendLine($" - {d}"); b.AppendLine();
}
+ if (r.Regions is not null)
+ {
+ b.AppendLine("Regions"); b.AppendLine($" Count: {r.Regions.RegionCount}"); b.AppendLine($" Root: {r.Regions.RootRegionId}");
+ foreach (var region in r.Regions.Regions)
+ {
+ b.AppendLine(); b.AppendLine($" Region {region.RegionId}"); b.AppendLine($" Kind: {region.RegionKind}");
+ if (region.ParentRegionId is not null) b.AppendLine($" Parent: {region.ParentRegionId}");
+ b.AppendLine($" Effect: {region.EffectKind}"); b.AppendLine($" Yield: {region.YieldKind}"); b.AppendLine($" Boundary: {region.BoundaryContractKind}");
+ b.AppendLine($" Frame: {FrameLabel(region.LocalFrame)}"); b.AppendLine($" Integration: {region.IntegrationStatus}");
+ foreach (var loss in region.KnownLosses) b.AppendLine($" Reason: {loss}");
+ foreach (var guarantee in region.Guarantees) b.AppendLine($" Guarantee: {guarantee}");
+ }
+ b.AppendLine();
+ }
b.AppendLine("AIR"); b.AppendLine($" Node: {r.Air.Node}"); b.AppendLine($" Route: {r.Air.Route}"); b.AppendLine($" Selection class: {r.Air.SelectionClass}"); b.AppendLine($" Rule: {r.Air.Rule}"); b.AppendLine($" Construction history: {r.Air.ConstructionHistory}"); b.AppendLine();
b.AppendLine("Route decision"); b.AppendLine($" Mode: {r.RouteDecision.Mode}"); b.AppendLine($" Selected route: {r.RouteDecision.SelectedRoute}"); b.AppendLine($" Succeeded: {r.RouteDecision.Succeeded.ToString().ToLowerInvariant()}"); b.AppendLine();
b.AppendLine("BRepPlan"); b.AppendLine($" Plan kind: {r.BRepPlan.PlanKind}"); b.AppendLine($" Vertices: {r.BRepPlan.Vertices}"); b.AppendLine($" Edges: {r.BRepPlan.Edges}"); b.AppendLine($" Faces: {r.BRepPlan.Faces}"); b.AppendLine($" Loops: {r.BRepPlan.Loops}"); b.AppendLine($" Coedges: {r.BRepPlan.Coedges}"); b.AppendLine($" Cap faces: {r.BRepPlan.CapFaces}"); b.AppendLine($" Transition faces: {r.BRepPlan.TransitionFaces}"); b.AppendLine($" Chamfer faces: {r.BRepPlan.ChamferFaces}"); b.AppendLine($" Split policy: {r.BRepPlan.SplitPolicy}"); b.AppendLine($" Bounds: {r.BRepPlan.Bounds}"); b.AppendLine();
@@ -264,4 +313,6 @@ internal static class AirTraceTextRenderer
b.AppendLine("Diagnostics"); foreach (var d in r.Diagnostics) b.AppendLine($" - {d}");
return b.ToString();
}
+
+ private static string FrameLabel(AirLocalFrameSummary frame) => frame.FrameKind == AirLocalFrameKind.FaceAttached && frame.SourceFace is not null ? $"FaceAttached({frame.SourceFace})" : frame.FrameKind.ToString();
}
diff --git a/Aetheris.Kernel.Core/Air/AirRegions.cs b/Aetheris.Kernel.Core/Air/AirRegions.cs
new file mode 100644
index 00000000..7d211788
--- /dev/null
+++ b/Aetheris.Kernel.Core/Air/AirRegions.cs
@@ -0,0 +1,89 @@
+namespace Aetheris.Kernel.Core.Air.Regions;
+
+internal enum AirRegionKind { RootRegion, FaceAttachedRegion, Unsupported }
+internal enum AirRegionEffectKind { PureConstruction, Additive, Subtractive, Replacement, SelectionOnly, AnnotationOnly, Unsupported }
+internal enum AirRegionYieldKind { None, YieldBody, YieldAdditiveBody, YieldSubtractiveVolume, YieldReplacementPatch, YieldProfileBoundary, YieldSectionStack, YieldFaceLoopRewrite, YieldAttachmentInterface, YieldSelection, YieldUnsupported }
+internal enum AirRegionBoundaryContractKind { DoesNotEscape, YieldsBody, YieldsCutVolume, YieldsPatch, YieldsLoopRewrite, YieldsAttachmentInterface, YieldsSelection, RejectedOrDeferred }
+internal enum AirLocalFrameKind { WorldRoot, FaceAttached, Unsupported }
+internal enum AirLocalFrameHandedness { RightHanded, LeftHanded, Unknown }
+internal enum AirRegionIntegrationStatus { NotRequired, Deferred, Rejected, Admitted, Unsupported }
+
+internal sealed record AirVectorSummary(double X, double Y, double Z);
+
+internal sealed record AirLocalFrameSummary(
+ string FrameId,
+ AirLocalFrameKind FrameKind,
+ AirVectorSummary Origin,
+ AirVectorSummary XAxis,
+ AirVectorSummary YAxis,
+ AirVectorSummary ZAxis,
+ AirLocalFrameHandedness Handedness,
+ string? AttachmentSource,
+ string? SourceFace,
+ string? ReferenceDirection,
+ bool IsValid,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record AirRegionSummary(
+ string RegionId,
+ AirRegionKind RegionKind,
+ string? ParentRegionId,
+ AirRegionEffectKind EffectKind,
+ AirRegionYieldKind YieldKind,
+ AirRegionBoundaryContractKind BoundaryContractKind,
+ AirLocalFrameSummary LocalFrame,
+ AirRegionIntegrationStatus IntegrationStatus,
+ string IntegrationRoute,
+ string StageReached,
+ string Provenance,
+ IReadOnlyList<string> Diagnostics,
+ IReadOnlyList<string> KnownLosses,
+ IReadOnlyList<string> Guarantees);
+
+internal sealed record AirRegionTraceSummary(
+ IReadOnlyList<AirRegionSummary> Regions,
+ string RootRegionId,
+ int RegionCount,
+ bool HasNestedRegions,
+ IReadOnlyList<string> Diagnostics,
+ IReadOnlyList<string> Guarantees);
+
+internal static class AirRegionTraceFactory
+{
+ public static AirRegionTraceSummary ForRootBody(string stageReached = "emitted-brep")
+ {
+ var root = RootRegion(stageReached);
+ return Summary([root], ["air-region-x1-region-trace-created", "air-region-x1-root-region-created", "air-region-x1-world-root-frame-created"], ["AIR Region trace-only summary", "root region does not change BRepPlan semantics"]);
+ }
+
+ public static AirRegionTraceSummary ForFaceAttachedSideHoleDeferred()
+ {
+ var root = RootRegion("region-created");
+ var side = new AirRegionSummary(
+ "region:side-hole:+x",
+ AirRegionKind.FaceAttachedRegion,
+ root.RegionId,
+ AirRegionEffectKind.Subtractive,
+ AirRegionYieldKind.YieldSubtractiveVolume,
+ AirRegionBoundaryContractKind.YieldsCutVolume,
+ new AirLocalFrameSummary("frame:side-hole:+x", AirLocalFrameKind.FaceAttached, new(5, 0, 0), new(0, 1, 0), new(0, 0, 1), new(1, 0, 0), AirLocalFrameHandedness.RightHanded, "box.face(\"+X\")", "+X", "+Z", true, ["air-region-x1-face-attached-frame-created"]),
+ AirRegionIntegrationStatus.Deferred,
+ "deferred:no-geometry-integration",
+ "region-integration-deferred",
+ "AIR-REGION-X1 metadata-driven fixture",
+ ["air-region-x1-face-attached-region-created", "air-region-x1-region-effect-declared", "air-region-x1-region-yield-declared", "air-region-x1-boundary-contract-declared", "air-region-x1-parent-integration-deferred"],
+ ["side-hole geometry integration not implemented"],
+ ["no implicit parent mutation", "no Boolean", "no BRep emission", "no production route replacement", "trace-only"]);
+ return Summary([root, side], ["air-region-x1-region-trace-created", "air-region-x1-no-implicit-parent-mutation", "air-region-x1-no-boolean", "air-region-x1-no-brep-emission", "air-region-x1-no-production-route-replacement", "air-region-x1-trace-only"], ["no Boolean", "no geometry", "no BRep emission", "no STEP smoke", "no production route replacement"]);
+ }
+
+ public static AirRegionTraceSummary ForImplicitParentMutationRejected()
+ {
+ var root = RootRegion("region-created");
+ var bad = new AirRegionSummary("region:implicit-parent-mutation", AirRegionKind.FaceAttachedRegion, root.RegionId, AirRegionEffectKind.Subtractive, AirRegionYieldKind.None, AirRegionBoundaryContractKind.RejectedOrDeferred, new AirLocalFrameSummary("frame:implicit-parent-mutation", AirLocalFrameKind.FaceAttached, new(5, 0, 0), new(0, 1, 0), new(0, 0, 1), new(1, 0, 0), AirLocalFrameHandedness.RightHanded, "box.face(\"+X\")", "+X", "+Z", true, ["air-region-x1-face-attached-frame-created"]), AirRegionIntegrationStatus.Rejected, "rejected:implicit-parent-mutation", "region-rejected", "AIR-REGION-X1 metadata-driven fixture", ["air-region-x1-implicit-parent-mutation-rejected"], ["implicit parent mutation rejected"], ["no geometry", "no BRep emission", "no Boolean"]);
+ return Summary([root, bad], ["air-region-x1-region-trace-created", "air-region-x1-implicit-parent-mutation-rejected", "air-region-x1-no-brep-emission", "air-region-x1-no-boolean"], ["no Boolean", "no geometry", "no BRep emission"]);
+ }
+
+ private static AirRegionSummary RootRegion(string stageReached) => new("region:root", AirRegionKind.RootRegion, null, AirRegionEffectKind.PureConstruction, AirRegionYieldKind.YieldBody, AirRegionBoundaryContractKind.YieldsBody, new AirLocalFrameSummary("frame:world-root", AirLocalFrameKind.WorldRoot, new(0, 0, 0), new(1, 0, 0), new(0, 1, 0), new(0, 0, 1), AirLocalFrameHandedness.RightHanded, null, null, null, true, ["air-region-x1-world-root-frame-created"]), AirRegionIntegrationStatus.NotRequired, "root-body", stageReached, "AIR-REGION-X1", ["air-region-x1-root-region-created"], [], ["root region is a trace-only summary"]);
+ private static AirRegionTraceSummary Summary(IReadOnlyList<AirRegionSummary> regions, IReadOnlyList<string> diagnostics, IReadOnlyList<string> guarantees) => new(regions, "region:root", regions.Count, regions.Any(r => r.ParentRegionId is not null), diagnostics.Order(StringComparer.Ordinal).ToArray(), guarantees.Order(StringComparer.Ordinal).ToArray());
+}
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index 4ee95808..afea151e 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -784,3 +784,7 @@ AIR-X10 creates the first parser-backed Feature AIR to Constructive AIR boundary
## AIR-X11 parser-backed emission boundary note
AIR-X11 establishes the first parser-backed Constructive AIR to existing emission-evidence boundary: a Firmament `box` fixture reaches `AirProfileExtrude` and then the existing profile extrusion wrapper/emitter summary. The boundary is trace-only and does not alter grammar, production routes, geometry implementation, BRepPlan semantics, CIR behavior, STEP export/import, route selection, or topology behavior.
+
+## AIR-REGION-X1 status note
+
+AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures report a `RootRegion`, region fixtures can report metadata-driven `FaceAttachedRegion` yields with deferred integration, and no Boolean, geometry emission, production route replacement, grammar expansion, BRepPlan semantics, or CIR behavior is changed. See `docs/air-region-x1-region-model-skeleton-trace-fixtures.md`.
diff --git a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
index a57cb7eb..b6dba3b0 100644
--- a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
+++ b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
@@ -624,3 +624,7 @@ AIR-A1 explicitly does not include:
- no BrepBoundedChamfer/BrepBoundedFillet behavior changes;
- no chamfer/fillet/shell geometry changes;
- no test weakening.
+
+## AIR-REGION-X1 status note
+
+AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures report a `RootRegion`, region fixtures can report metadata-driven `FaceAttachedRegion` yields with deferred integration, and no Boolean, geometry emission, production route replacement, grammar expansion, BRepPlan semantics, or CIR behavior is changed. See `docs/air-region-x1-region-model-skeleton-trace-fixtures.md`.
diff --git a/docs/air-region-x1-region-model-skeleton-trace-fixtures.md b/docs/air-region-x1-region-model-skeleton-trace-fixtures.md
new file mode 100644
index 00000000..d7a94a6d
--- /dev/null
+++ b/docs/air-region-x1-region-model-skeleton-trace-fixtures.md
@@ -0,0 +1,43 @@
+# AIR-REGION-X1 — Region model skeleton and trace fixtures
+
+AIR-REGION-X1 adds the first minimal AIR Region trace model. It implements trace-only `RootRegion` and metadata-driven `FaceAttachedRegion` summaries so AIR-A1 scoped construction islands are visible without changing production geometry.
+
+## Scope
+
+Implemented model fields cover region kind, effect kind, yield kind, boundary contract, local frame, and integration status. The DTOs currently live in `Aetheris.Kernel.Core.Air.Regions` and are consumed by `aetheris trace`.
+
+## Relationship to AIR-A1
+
+AIR-A1 says a different-axis feature is a scoped AIR Region with a local frame, explicit yield, and explicit parent integration route; it is not immediate global Boolean. X1 makes that doctrine inspectable in trace reports only.
+
+## RootRegion
+
+Parser-backed `fixtures/Firmament/Primitive/valid/box.valid.firmfixture` now reports a single `RootRegion` with a `WorldRoot` frame, `PureConstruction` effect, `YieldBody`, `YieldsBody`, and `NotRequired` integration. The fixture still reaches `emitted-brep` through the existing AIR-X11 box path.
+
+## FaceAttachedRegion side-hole fixture
+
+`fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture` is metadata-driven and trace-only. It reports `RootRegion` plus `FaceAttachedRegion` with `Subtractive` effect, `YieldSubtractiveVolume`, `YieldsCutVolume`, and `Deferred` integration. It does not parse new Firmament grammar and does not emit geometry.
+
+## Local frame convention
+
+For the +X face-attached mock, the frame origin is the deterministic placeholder `(5, 0, 0)`. The local Z axis follows the +X face normal `(1, 0, 0)`, the local X axis is `(0, 1, 0)`, and the local Y axis is `(0, 0, 1)`, making a right-handed conceptual frame for trace evidence only.
+
+## Guarantees and non-goals
+
+X1 guarantees no Boolean, no BRep emission, no STEP smoke, no production route replacement, no production Firmament grammar expansion, no BRepPlan region integration or semantic change, no CIR region mirror, and no side-hole geometry.
+
+## Invalid fixture
+
+`fixtures/Firmament/Region/invalid/implicit-parent-mutation.invalid.firmfixture` rejects a region that attempts implicit parent mutation without explicit yield. The actual stage is `region-rejected` and no geometry is emitted.
+
+## Trace output additions
+
+Text reports include a concise `Regions` section when a region trace summary exists. JSON reports include a stable `regions` object with `rootRegionId`, `regionCount`, `hasNestedRegions`, and region entries.
+
+## Tests run during implementation
+
+Focused CLI tests cover root-region box reporting, side-hole text and JSON, implicit parent mutation rejection, deterministic JSON, and existing fixture behavior.
+
+## Recommended next milestone
+
+AIR-REGION-X2 — Side-hole FaceAttachedRegion mock yield refinement and boundary contract. The implementation showed that trace contracts are now visible, but the next blocker is sharpening yield/boundary metadata before any BRepPlan or CIR analysis is attempted.
diff --git a/docs/air-x11-box-constructive-air-to-profile-emission-trace.md b/docs/air-x11-box-constructive-air-to-profile-emission-trace.md
index 5a4c3941..5892d326 100644
--- a/docs/air-x11-box-constructive-air-to-profile-emission-trace.md
+++ b/docs/air-x11-box-constructive-air-to-profile-emission-trace.md
@@ -107,3 +107,7 @@ Validation included CLI build/help/trace commands, parser-backed box text and JS
## Recommended next milestone
Recommended next milestone: **AIR-X12 — ProfileExtrude BRepPlan for parser-backed box**. AIR-X11 shows the existing emitter can produce BRep evidence from parser-backed Constructive AIR, while BRepPlan remains the next explicitly deferred topology-planning boundary.
+
+## AIR-REGION-X1 status note
+
+AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures report a `RootRegion`, region fixtures can report metadata-driven `FaceAttachedRegion` yields with deferred integration, and no Boolean, geometry emission, production route replacement, grammar expansion, BRepPlan semantics, or CIR behavior is changed. See `docs/air-region-x1-region-model-skeleton-trace-fixtures.md`.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
index b65b3937..d9c43a6d 100644
--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -163,3 +163,7 @@ For parser-backed Firmament primitive fixtures, `aetheris trace --fixture` can n
## AIR-X11 profile emission section
For parser-backed Firmament box fixtures, `aetheris trace --fixture` may include a `Profile extrusion emission` text section and a `profileEmission` JSON object. These fields report wrapper invocation, emitter name, propagated dimensions, topology summary when exposed by the existing wrapper, STEP smoke availability, diagnostics, and guarantees. BRepPlan and CIR are still reported separately and remain deferred/not-requested unless actually wired for the lane.
+
+## AIR-REGION-X1 status note
+
+AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures report a `RootRegion`, region fixtures can report metadata-driven `FaceAttachedRegion` yields with deferred integration, and no Boolean, geometry emission, production route replacement, grammar expansion, BRepPlan semantics, or CIR behavior is changed. See `docs/air-region-x1-region-model-skeleton-trace-fixtures.md`.
diff --git a/docs/air-x7-firmament-fixture-trace-corpus.md b/docs/air-x7-firmament-fixture-trace-corpus.md
index 4f60c13a..33834c24 100644
--- a/docs/air-x7-firmament-fixture-trace-corpus.md
+++ b/docs/air-x7-firmament-fixture-trace-corpus.md
@@ -118,3 +118,7 @@ The primitive parser-backed fixture `fixtures/Firmament/Primitive/valid/box.vali
## AIR-X11 corpus note
The parser-backed primitive box fixture advances to existing profile extrusion emission evidence with expected stage `emitted-brep`. The AIR-X7 chamfer fixtures remain metadata-driven and continue to validate their previous valid/deferred/rejected paths.
+
+## AIR-REGION-X1 status note
+
+AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures report a `RootRegion`, region fixtures can report metadata-driven `FaceAttachedRegion` yields with deferred integration, and no Boolean, geometry emission, production route replacement, grammar expansion, BRepPlan semantics, or CIR behavior is changed. See `docs/air-region-x1-region-model-skeleton-trace-fixtures.md`.
diff --git a/fixtures/Firmament/Primitive/valid/box.valid.firmfixture b/fixtures/Firmament/Primitive/valid/box.valid.firmfixture
index bc4e24d0..b7378112 100644
--- a/fixtures/Firmament/Primitive/valid/box.valid.firmfixture
+++ b/fixtures/Firmament/Primitive/valid/box.valid.firmfixture
@@ -4,6 +4,8 @@
// expected-feature-air: CreateBox
// expected-constructive-air: AirProfileExtrude
// expected-emitter: LineArcProfileExtrudeEmitter
+// expected-region-kind: RootRegion
+// expected-region-count: 1
// parser-backed: true
// description: Parser-backed Firmament box fixture reaching existing profile extrusion emission evidence.
diff --git a/fixtures/Firmament/Region/invalid/implicit-parent-mutation.invalid.firmfixture b/fixtures/Firmament/Region/invalid/implicit-parent-mutation.invalid.firmfixture
new file mode 100644
index 00000000..607e474e
--- /dev/null
+++ b/fixtures/Firmament/Region/invalid/implicit-parent-mutation.invalid.firmfixture
@@ -0,0 +1,10 @@
+// case: implicit-parent-mutation-region
+// expected: invalid
+// expected-stage: region-rejected
+// expected-reason: implicit-parent-mutation-rejected
+// description: Region fixture that attempts parent mutation without explicit yield.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+region bad on box.face("+X") {
+ mutate parent directly;
+}
diff --git a/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture b/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture
new file mode 100644
index 00000000..0b042aed
--- /dev/null
+++ b/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture
@@ -0,0 +1,16 @@
+// case: side-hole-face-attached-region
+// expected: valid
+// expected-stage: region-integration-deferred
+// expected-region-kind: FaceAttachedRegion
+// expected-effect: Subtractive
+// expected-yield: YieldSubtractiveVolume
+// expected-boundary: YieldsCutVolume
+// expected-integration: Deferred
+// description: Trace-only face-attached side-hole region fixture; integration deferred.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+region sideHole on box.face("+X") {
+ frame faceAttached;
+ circle center(0, 0) radius 1;
+ cut through;
+}