Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add side-hole region CIR mirror trace

Yuechen Li598e2c5a9da9
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index 01e87eec..184b392a 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -314,6 +314,9 @@ public sealed class AirTraceCommandTests
Assert.Contains("YieldsCutVolume", output); Assert.Contains("Integration: Deferred", output);
Assert.Contains("Region yield", output); Assert.Contains("SideHole", output); Assert.Contains("Circle", output);
Assert.Contains("radius=1", output); Assert.Contains("+X", output); Assert.Contains("through inward", output); Assert.Contains("ThroughCut", output);
+ Assert.Contains("Region CIR mirror", output); Assert.Contains("mirror-admitted-conservative", output); Assert.Contains("cir-region-parent-minus-cylinder", output);
+ Assert.Contains("Parent field: Box", output); Assert.Contains("Subtract field: Cylinder", output);
+ Assert.Contains("no topology authority", output); Assert.Contains("no face identity", output);
Assert.Contains("no Boolean", output); Assert.Contains("no BRep emission", output);
}
@@ -325,7 +328,7 @@ public sealed class AirTraceCommandTests
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());
+ Assert.Equal("region-cir-mirror", root.GetProperty("actualStageReached").GetString());
var regions = root.GetProperty("regions");
Assert.Equal(2, regions.GetProperty("regionCount").GetInt32());
Assert.True(regions.GetProperty("hasNestedRegions").GetBoolean());
@@ -349,6 +352,18 @@ public sealed class AirTraceCommandTests
Assert.True(yield.GetProperty("affectedScope").GetProperty("parentBodyOnly").GetBoolean());
Assert.True(yield.GetProperty("affectedScope").GetProperty("escapesOnlyThroughYield").GetBoolean());
Assert.Equal("Deferred", yield.GetProperty("integrationStatus").GetString());
+ var mirror = side.GetProperty("cirMirror");
+ Assert.Equal("SideHole", mirror.GetProperty("yieldFeatureKind").GetString());
+ Assert.Equal("mirror-admitted-conservative", mirror.GetProperty("status").GetString());
+ Assert.Equal("cir-region-parent-minus-cylinder", mirror.GetProperty("backend").GetString());
+ Assert.Equal("Subtractive", mirror.GetProperty("effect").GetString());
+ Assert.Equal("Box", mirror.GetProperty("parentField").GetString());
+ Assert.Equal("Cylinder", mirror.GetProperty("subtractField").GetString());
+ var capabilities = mirror.GetProperty("capabilities").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.Contains("occupancy", capabilities); Assert.Contains("containment", capabilities); Assert.Contains("bounds", capabilities);
+ var losses = mirror.GetProperty("knownLosses").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.Contains("no-topology-authority", losses); Assert.Contains("no-face-identity", losses);
+ Assert.Contains("no-brep-plan-role-parity", losses); Assert.Contains("no-step-export-authority", losses);
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());
@@ -372,7 +387,7 @@ public sealed class AirTraceCommandTests
}
[Fact]
- public void RegionYieldSummaries_AreDeterministic()
+ public void RegionCirMirrorSummaries_AreDeterministic()
{
var valid = RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture");
var invalid = RegionFixture("invalid/implicit-parent-mutation.invalid.firmfixture");
@@ -389,7 +404,16 @@ public sealed class AirTraceCommandTests
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());
- Assert.Equal("not-requested", root.GetProperty("cirMirror").GetProperty("status").GetString());
+ var side = root.GetProperty("regions").GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion");
+ var mirror = side.GetProperty("cirMirror");
+ var capabilities = mirror.GetProperty("capabilities").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.DoesNotContain("topology-authority", capabilities);
+ Assert.DoesNotContain("face-identity", capabilities);
+ Assert.DoesNotContain("entry-loop-identity", capabilities);
+ Assert.DoesNotContain("boundary-patch-identity", capabilities);
+ var losses = mirror.GetProperty("knownLosses").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.Contains("no-topology-authority", losses);
+ Assert.Contains("no-face-identity", losses);
var guarantees = root.GetProperty("guarantees").EnumerateArray().Select(x => x.GetString()).ToArray();
Assert.Contains("no Boolean", guarantees);
Assert.Contains("escapes only through explicit yield", guarantees);
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 37a25a59..92be15d6 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -192,17 +192,17 @@ internal static class AirTraceReportBuilder
private static AirTraceReport BuildSideHoleFaceAttachedRegionFixture(FirmFixture fixture)
{
var regions = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();
- var actualStage = "region-integration-deferred";
+ var actualStage = "region-cir-mirror";
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-X2", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole yield contract 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-X2"),
+ return new("AIR-REGION-X3", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole yield contract admits a conservative analysis-only CIR mirror summary; parent integration remains deferred and no geometry is emitted.",
+ new("RegionFixture", "none", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X3"),
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,
+ [], ["side-hole geometry integration not implemented", "CIR evaluator composition deferred"], 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),
@@ -317,6 +317,24 @@ internal static class AirTraceTextRenderer
b.AppendLine(" Guarantees:");
foreach (var guarantee in y.Guarantees) b.AppendLine($" - {guarantee}");
}
+
+ if (region.CirMirror is not null)
+ {
+ var m = region.CirMirror;
+ b.AppendLine(" Region CIR mirror");
+ b.AppendLine($" Region: {m.SourceRegionId}");
+ b.AppendLine($" Feature: {m.YieldFeatureKind}");
+ b.AppendLine($" Status: {m.Status}");
+ b.AppendLine($" Backend: {m.Backend}");
+ b.AppendLine($" Effect: {m.Effect}");
+ b.AppendLine($" Parent field: {m.ParentField}");
+ b.AppendLine($" Subtract field: {m.SubtractField}");
+ b.AppendLine($" Capabilities: {string.Join(", ", m.Capabilities)}");
+ b.AppendLine(" Known losses:");
+ foreach (var loss in m.KnownLosses) b.AppendLine($" - {loss.Replace('-', ' ')}");
+ b.AppendLine(" Guarantees:");
+ foreach (var guarantee in m.Guarantees) b.AppendLine($" - {guarantee}");
+ }
foreach (var loss in region.KnownLosses) b.AppendLine($" Reason: {loss}");
foreach (var guarantee in region.Guarantees) b.AppendLine($" Guarantee: {guarantee}");
}
diff --git a/Aetheris.Kernel.Core.Tests/AirRegionCirMirrorAdapterTests.cs b/Aetheris.Kernel.Core.Tests/AirRegionCirMirrorAdapterTests.cs
new file mode 100644
index 00000000..eff6809f
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/AirRegionCirMirrorAdapterTests.cs
@@ -0,0 +1,25 @@
+using Aetheris.Kernel.Core.Air.Regions;
+
+namespace Aetheris.Kernel.Core.Tests;
+
+public sealed class AirRegionCirMirrorAdapterTests
+{
+ [Fact]
+ public void SideHoleRegionCirMirror_RejectsForbiddenTopologyRequestsAsLossy()
+ {
+ var trace = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();
+ var side = trace.Regions.Single(r => r.RegionKind == AirRegionKind.FaceAttachedRegion);
+
+ var result = AirSideHoleRegionCirMirrorAdapter.Admit(side, ["occupancy", "face-identity", "topology-parity", "entry-loop-identity", "boundary-patch-identity"]);
+
+ Assert.False(result.Succeeded);
+ Assert.Equal("mirror-rejected-lossy-for-request", result.Summary.Status);
+ Assert.Empty(result.Summary.Capabilities);
+ Assert.Contains("air-region-x3-face-identity-request-rejected-lossy", result.Summary.Diagnostics);
+ Assert.Contains("air-region-x3-topology-parity-request-rejected-lossy", result.Summary.Diagnostics);
+ Assert.Contains("air-region-x3-entry-loop-identity-request-rejected-lossy", result.Summary.Diagnostics);
+ Assert.Contains("air-region-x3-boundary-patch-identity-request-rejected-lossy", result.Summary.Diagnostics);
+ Assert.Contains("no-topology-authority", result.Summary.KnownLosses);
+ Assert.Contains("no-face-identity", result.Summary.KnownLosses);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Air/AirRegions.cs b/Aetheris.Kernel.Core/Air/AirRegions.cs
index fc7f70f3..df083a0f 100644
--- a/Aetheris.Kernel.Core/Air/AirRegions.cs
+++ b/Aetheris.Kernel.Core/Air/AirRegions.cs
@@ -7,6 +7,8 @@ internal enum AirRegionBoundaryContractKind { DoesNotEscape, YieldsBody, YieldsC
internal enum AirLocalFrameKind { WorldRoot, FaceAttached, Unsupported }
internal enum AirLocalFrameHandedness { RightHanded, LeftHanded, Unknown }
internal enum AirRegionIntegrationStatus { NotRequired, Deferred, Rejected, Admitted, Unsupported }
+internal enum AirRegionCirMirrorStatus { MirrorAdmittedConservative, MirrorUnavailable, MirrorRejectedLossyForRequest }
+
internal sealed record AirVectorSummary(double X, double Y, double Z);
internal sealed record AirPoint2Summary(double X, double Y);
@@ -17,6 +19,55 @@ internal sealed record AirRegionProfileSummary(string ProfileKind, AirPoint2Summ
internal sealed record AirRegionDirectionSummary(string DirectionKind, string Axis, string Sense, bool IsThrough, string Depth, IReadOnlyList<string> Diagnostics);
internal sealed record AirRegionAffectedScopeSummary(string ScopeKind, bool ParentBodyOnly, string AffectedFaceSelector, bool MayAffectSiblings, bool EscapesOnlyThroughYield, IReadOnlyList<string> Diagnostics);
internal sealed record AirRegionBoundaryIntentSummary(string BoundaryKind, string EntryBoundary, string ExitBoundary, string RimIntent, string PatchIntent, IReadOnlyList<string> Diagnostics);
+internal sealed record AirRegionCirMirrorSummary(string SourceRegionId, AirRegionKind SourceRegionKind, string YieldId, string YieldFeatureKind, string Status, string Backend, AirRegionEffectKind Effect, string ParentField, string SubtractField, IReadOnlyList<string> Capabilities, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> Guarantees);
+
+internal sealed record AirRegionCirMirrorRequest(AirRegionSummary Region, AirRegionYieldSummary Yield, IReadOnlyList<string> RequestedCapabilities);
+internal sealed record AirRegionCirMirrorResult(bool Succeeded, AirRegionCirMirrorSummary Summary);
+
+internal static class AirSideHoleRegionCirMirrorAdapter
+{
+ private static readonly string[] AllowedCapabilities = ["occupancy", "containment", "bounds"];
+ private static readonly string[] KnownLosses = ["no-topology-authority", "no-face-identity", "no-entry-loop-identity", "no-exit-loop-identity", "no-boundary-patch-identity", "no-brep-plan-role-parity", "no-step-export-authority", "no-production-integration"];
+ private static readonly string[] Guarantees = ["analysis mirror only", "integration deferred", "no Boolean", "no BRep emission", "no STEP smoke", "summary-only; CIR evaluator composition deferred"];
+
+ public static AirRegionCirMirrorResult Admit(AirRegionSummary region, IReadOnlyList<string>? requestedCapabilities = null)
+ {
+ if (region.Yield is null) throw new ArgumentException("Region must carry a yield summary.", nameof(region));
+ var requested = requestedCapabilities ?? AllowedCapabilities;
+ var diagnostics = new List<string>
+ {
+ "air-region-x3-cir-mirror-request-created",
+ "air-region-x3-side-hole-cir-mirror-created",
+ "air-region-x3-parent-box-field-recorded",
+ "air-region-x3-subtract-cylinder-field-recorded",
+ "air-region-x3-region-effect-mirrored",
+ "air-region-x3-cir-analysis-side-channel-only",
+ "air-region-x3-no-topology-authority",
+ "air-region-x3-no-face-identity",
+ "air-region-x3-no-entry-loop-identity",
+ "air-region-x3-no-exit-loop-identity",
+ "air-region-x3-no-boundary-patch-identity",
+ "air-region-x3-no-brep-plan-role-parity",
+ "air-region-x3-no-step-export-authority",
+ "air-region-x3-parent-integration-deferred",
+ "air-region-x3-no-boolean",
+ "air-region-x3-no-brep-emission",
+ "air-region-x3-no-step-smoke",
+ "air-region-x3-cir-composition-deferred",
+ "air-region-x3-cir-mirror-summary-only"
+ };
+ if (requested.Contains("face-identity", StringComparer.Ordinal)) diagnostics.Add("air-region-x3-face-identity-request-rejected-lossy");
+ if (requested.Contains("topology-parity", StringComparer.Ordinal)) diagnostics.Add("air-region-x3-topology-parity-request-rejected-lossy");
+ if (requested.Contains("entry-loop-identity", StringComparer.Ordinal)) diagnostics.Add("air-region-x3-entry-loop-identity-request-rejected-lossy");
+ if (requested.Contains("boundary-patch-identity", StringComparer.Ordinal)) diagnostics.Add("air-region-x3-boundary-patch-identity-request-rejected-lossy");
+ var forbidden = requested.Any(x => x is "face-identity" or "topology-parity" or "entry-loop-identity" or "boundary-patch-identity");
+ var status = forbidden ? "mirror-rejected-lossy-for-request" : "mirror-admitted-conservative";
+ var caps = forbidden ? Array.Empty<string>() : AllowedCapabilities;
+ return new(!forbidden, new(region.RegionId, region.RegionKind, region.Yield.YieldId, region.Yield.FeatureKind, status, "cir-region-parent-minus-cylinder", region.EffectKind, "Box", "Cylinder", Stable(caps).ToArray(), KnownLosses, Stable(diagnostics).ToArray(), Guarantees));
+ }
+
+ private static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);
+}
internal sealed record AirLocalFrameSummary(
string FrameId,
@@ -47,7 +98,8 @@ internal sealed record AirRegionSummary(
IReadOnlyList<string> Diagnostics,
IReadOnlyList<string> KnownLosses,
IReadOnlyList<string> Guarantees,
- AirRegionYieldSummary? Yield = null);
+ AirRegionYieldSummary? Yield = null,
+ AirRegionCirMirrorSummary? CirMirror = null);
internal sealed record AirRegionTraceSummary(
IReadOnlyList<AirRegionSummary> Regions,
@@ -68,7 +120,7 @@ internal static class AirRegionTraceFactory
public static AirRegionTraceSummary ForFaceAttachedSideHoleDeferred()
{
var root = RootRegion("region-created");
- var side = new AirRegionSummary(
+ AirRegionSummary sideBase = new(
"region:side-hole:+x",
AirRegionKind.FaceAttachedRegion,
root.RegionId,
@@ -84,7 +136,17 @@ internal static class AirRegionTraceFactory
["side-hole geometry integration not implemented", "concrete through depth deferred", "opposite-side exit boundary deferred"],
["escapes only through explicit yield", "no implicit parent mutation", "no Boolean", "no BRep emission", "no production route replacement", "trace-only"],
SideHoleYield(root.RegionId));
- 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", "air-region-x2-yield-contract-created", "air-region-x2-side-hole-yield-created", "air-region-x2-region-locality-enforced", "air-region-x2-explicit-yield-only", "air-region-x2-parent-integration-deferred", "air-region-x2-no-boolean", "air-region-x2-no-brep-emission", "air-region-x2-no-step-smoke", "air-region-x2-no-cir-mirror", "air-region-x2-trace-only"], ["escapes only through explicit yield", "no Boolean", "no geometry", "no BRep emission", "no STEP smoke", "no production route replacement"]);
+ var mirror = AirSideHoleRegionCirMirrorAdapter.Admit(sideBase);
+ var side = sideBase with
+ {
+ StageReached = "region-cir-mirror",
+ Provenance = "AIR-REGION-X3 metadata-driven fixture",
+ Diagnostics = Stable([.. sideBase.Diagnostics.Where(d => d != "air-region-x2-no-cir-mirror"), .. mirror.Summary.Diagnostics]).ToArray(),
+ KnownLosses = Stable([.. sideBase.KnownLosses, .. mirror.Summary.KnownLosses]).ToArray(),
+ Guarantees = Stable([.. sideBase.Guarantees, .. mirror.Summary.Guarantees]).ToArray(),
+ CirMirror = mirror.Summary
+ };
+ 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", "air-region-x2-yield-contract-created", "air-region-x2-side-hole-yield-created", "air-region-x2-region-locality-enforced", "air-region-x2-explicit-yield-only", "air-region-x2-parent-integration-deferred", "air-region-x2-no-boolean", "air-region-x2-no-brep-emission", "air-region-x2-no-step-smoke", "air-region-x2-trace-only", .. side.CirMirror!.Diagnostics], ["escapes only through explicit yield", "no Boolean", "no geometry", "no BRep emission", "no STEP smoke", "no production route replacement", .. side.CirMirror.Guarantees]);
}
public static AirRegionTraceSummary ForImplicitParentMutationRejected()
@@ -108,4 +170,5 @@ internal static class AirRegionTraceFactory
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());
+ private static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);
}
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index e614cc39..3d844838 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -792,3 +792,8 @@ AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures
## AIR-REGION-X2 constitution note
AIR-REGION-X2 reinforces that AIR Region yields carry construction intent across scoped boundaries. The side-hole `FaceAttachedRegion` yield is explicit, local, and deferred, allowing later lowering to choose an integration route without treating Boolean subtraction as the region model.
+
+
+## AIR-REGION-X3 constitutional note
+
+The AIR Region side-hole CIR mirror is a side-channel analysis summary only. It reinforces that CIR evaluation mirrors can describe field behavior while AIR/BRepPlan/BRep/STEP retain their separate authority boundaries.
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 006a0242..b828047f 100644
--- a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
+++ b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
@@ -632,3 +632,8 @@ AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures
## AIR-REGION-X2 status note
AIR-REGION-X2 implements a trace-only side-hole yield boundary contract for the metadata-driven `FaceAttachedRegion` fixture. The contract records `SideHole` feature intent, face attachment, circular profile radius, through/inward direction, parent-body-local affected scope, through-cut boundary intent, deferred exit boundary, and explicit-yield-only locality guarantees. Parent integration remains deferred and no production geometry, Boolean, BRepPlan, CIR, STEP, or grammar behavior changes.
+
+
+## AIR-REGION-X3 status note
+
+AIR-REGION-X3 demonstrates the A1 doctrine that region effects may be mirrored for analysis without transferring topology authority to CIR. The side-hole region reports an analysis-only parent-box-minus-cylinder mirror summary while BRepPlan, BRep, STEP, Boolean, and production integration remain deferred.
diff --git a/docs/air-region-x1-region-model-skeleton-trace-fixtures.md b/docs/air-region-x1-region-model-skeleton-trace-fixtures.md
index 3edda5f6..3dd0aaef 100644
--- a/docs/air-region-x1-region-model-skeleton-trace-fixtures.md
+++ b/docs/air-region-x1-region-model-skeleton-trace-fixtures.md
@@ -45,3 +45,8 @@ AIR-REGION-X2 — Side-hole FaceAttachedRegion mock yield refinement and boundar
## AIR-REGION-X2 note
AIR-REGION-X2 extends the X1 side-hole `FaceAttachedRegion` trace with a structured yield contract. The region still reports `YieldSubtractiveVolume`, `YieldsCutVolume`, and `Deferred` integration, but the emitted trace now includes feature kind, attachment, profile, direction, affected scope, boundary intent, diagnostics, known losses, and locality guarantees. This remains metadata-driven and trace-only: no side-hole geometry, Boolean, BRepPlan, CIR, STEP smoke, or production route replacement is introduced.
+
+
+## AIR-REGION-X3 region CIR mirror note
+
+The side-hole `FaceAttachedRegion` fixture now includes a region-local CIR mirror summary under the region trace. The RootRegion-only parser-backed box fixture remains unchanged and does not gain a side-hole mirror.
diff --git a/docs/air-region-x2-side-hole-yield-boundary-contract.md b/docs/air-region-x2-side-hole-yield-boundary-contract.md
index 789c81a7..49fa57d2 100644
--- a/docs/air-region-x2-side-hole-yield-boundary-contract.md
+++ b/docs/air-region-x2-side-hole-yield-boundary-contract.md
@@ -79,3 +79,8 @@ The implementation was validated with CLI help, side-hole text and JSON traces,
## Recommended next milestone
Recommended: **AIR-REGION-X3 — Region BRepPlan boundary contract for side-hole, no integration**. X2 now carries enough attachment/profile/direction/boundary/scope intent to define an analysis-only BRepPlan boundary contract without committing to Boolean integration or production side-hole geometry.
+
+
+## AIR-REGION-X3 CIR mirror note
+
+AIR-REGION-X3 preserves the X2 side-hole yield boundary contract and adds a trace-only CIR mirror admission summary for the same `FaceAttachedRegion`. The summary backend is `cir-region-parent-minus-cylinder`, records parent `Box` and subtract `Cylinder` fields, remains analysis-only, and keeps parent integration deferred with no Boolean, no BRep emission, no BRepPlan integration, and no STEP authority.
diff --git a/docs/air-region-x3-side-hole-cir-mirror-analysis.md b/docs/air-region-x3-side-hole-cir-mirror-analysis.md
new file mode 100644
index 00000000..7d59d24f
--- /dev/null
+++ b/docs/air-region-x3-side-hole-cir-mirror-analysis.md
@@ -0,0 +1,74 @@
+# AIR-REGION-X3 — Side-hole CIR mirror analysis
+
+## Purpose and scope
+
+AIR-REGION-X3 adds trace-only evidence that the metadata-driven side-hole `FaceAttachedRegion` yield can be admitted to an analysis-side CIR mirror summary. The milestone does not implement side-hole BRep geometry, BRepPlan integration, production Boolean, STEP export, parser grammar, or production analyzer behavior.
+
+## Relationship to AIR-A1, X1, X2, and AIR-X5
+
+AIR-A1 defines AIR Regions as local construction-intent islands whose effects escape through explicit yields. AIR-REGION-X1 introduced the trace-only root/face-attached region skeleton, and AIR-REGION-X2 made the side-hole yield boundary contract explicit. AIR-X5 requires AIR-to-CIR mirrors to remain side-channel adapters with explicit status, capabilities, provenance, losses, and no topology authority.
+
+X3 applies that envelope to the side-hole region yield: AIR owns the local side-hole intent, while the CIR mirror records an evaluation-field interpretation only.
+
+## Side-hole CIR mirror doctrine
+
+The side-hole region may mirror as:
+
+```text
+parent box field minus local cylinder field
+```
+
+This is analysis evidence only. It does not make CIR the owner of topology, face identity, entry/exit loop identity, boundary patch identity, BRepPlan roles, STEP/export authority, or production integration.
+
+## Mirror model
+
+The trace summary records:
+
+- backend: `cir-region-parent-minus-cylinder`;
+- status: `mirror-admitted-conservative`;
+- effect: `Subtractive`;
+- parent field: `Box`;
+- subtract field: `Cylinder`;
+- capabilities: `bounds`, `containment`, and `occupancy` as summary-level analysis claims;
+- losses: topology, face, entry loop, exit loop, boundary patch, BRepPlan role parity, STEP/export authority, and production integration.
+
+Actual CIR evaluator/tape composition is deferred. X3 intentionally implements a deterministic admission summary rather than constructing executable CIR nodes.
+
+## Fixture path and expected trace stage
+
+Fixture: `fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`.
+
+Expected stage advances to `region-cir-mirror` because the fixture now reports an admitted region CIR mirror summary. Parent integration remains `Deferred` on the region yield.
+
+## Capabilities actually admitted
+
+The summary admits only `occupancy`, `containment`, and `bounds`. It does not admit map, volume estimate, face identity, topology parity, loop identity, or patch identity.
+
+## Known losses
+
+The mirror explicitly records:
+
+- no topology authority;
+- no face identity;
+- no entry-loop identity;
+- no exit-loop identity;
+- no boundary patch identity;
+- no BRepPlan role parity;
+- no STEP/export authority;
+- no production integration.
+
+## No Boolean, BRep, or STEP guarantees
+
+The trace keeps the AIR-REGION-X2 guarantees: no production Boolean invocation, no side-hole BRep emission, no BRepPlan success, no STEP smoke, and no production route replacement.
+
+## Actual CIR composition status
+
+X3 is summary-only. The intended model is parent-box field minus cylinder field, but executable CIR primitive composition and sampling are deferred to a later milestone.
+
+## Tests run
+
+Validation used the focused CLI trace commands and filtered test commands recorded in the PR summary.
+
+## Recommended next milestone
+
+Recommended next milestone: **AIR-REGION-X4 — Region-to-CIR occupancy sample artifact**. X3 found the mirror summary boundary clean, so the next narrow step is to add an explicit trace/test-only sample artifact without changing production analyzer behavior or claiming topology authority.
diff --git a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
index b633687d..1b0de929 100644
--- a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
+++ b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
@@ -101,3 +101,8 @@ Implementation showed that AIR-X3/X4 already carry useful BRepPlan topology-role
## AIR-X7 fixture note
The AIR-X7 valid top-face loop chamfer fixture reaches the `cir-mirror` trace stage by reusing the existing admitted AIR-X5 top-face loop chamfer mirror envelope. The fixture does not make CIR a topology authority.
+
+
+## AIR-REGION-X3 side-hole region mirror envelope
+
+The side-hole `FaceAttachedRegion` now has an analysis-only AIR Region to CIR mirror envelope. It uses a summary backend named `cir-region-parent-minus-cylinder`, admits conservative occupancy/containment/bounds summary capabilities, and denies topology, face, loop, boundary patch, BRepPlan role, STEP/export, and production integration authority.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
index f0e027c8..ba5e9e6d 100644
--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -171,3 +171,8 @@ AIR-REGION-X1 adds a trace-only AIR Region skeleton: parser-backed box fixtures
## AIR-REGION-X2 region yield contract trace note
For the side-hole region fixture, `aetheris trace` now renders a `Region yield` block in text and a structured `regions.regions[].yield` object in JSON. The fields are stable trace summaries for attachment, profile, direction, affected scope, boundary intent, integration status, diagnostics, known losses, and guarantees. The side-hole route remains trace-only and deferred.
+
+
+## AIR-REGION-X3 trace note
+
+`aetheris trace --fixture fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture` now prints a `Region CIR mirror` section for the side-hole `FaceAttachedRegion`. The JSON region entry includes `cirMirror` with stable status, backend, fields, capabilities, losses, diagnostics, and guarantees.
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
index 360658e4..3715e797 100644
--- a/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture
+++ b/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture
@@ -1,6 +1,6 @@
// case: side-hole-face-attached-region
// expected: valid
-// expected-stage: region-integration-deferred
+// expected-stage: region-cir-mirror
// expected-region-kind: FaceAttachedRegion
// expected-effect: Subtractive
// expected-yield: YieldSubtractiveVolume
@@ -12,6 +12,12 @@
// expected-attachment-face: +X
// expected-direction: through-inward
// expected-boundary-kind: ThroughCut
+// expected-cir-mirror: admitted
+// expected-cir-backend: cir-region-parent-minus-cylinder
+// expected-cir-effect: Subtractive
+// expected-cir-loss: no-topology-authority
+// expected-cir-loss: no-face-identity
+// expected-cir-loss: no-entry-loop-identity
// expected-affected-scope: ParentBodyLocalFeature
// description: Trace-only face-attached side-hole region fixture; integration deferred.