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.csindex 01e87eec..184b392a 100644--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs@@ -314,6 +314,9 @@ public sealed class AirTraceCommandTestsAssert.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 AirTraceCommandTestsusing 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 AirTraceCommandTestsAssert.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 AirTraceCommandTestsAssert.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.csindex 37a25a59..92be15d6 100644--- a/Aetheris.CLI/AirTrace.cs+++ b/Aetheris.CLI/AirTrace.cs@@ -192,17 +192,17 @@ internal static class AirTraceReportBuilderprivate 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 AirTraceTextRendererb.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.csnew file mode 100644index 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.csindex 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, YieldsCinternal 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, AirPoint2Summinternal 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 AirRegionTraceFactorypublic 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 AirRegionTraceFactoryprivate 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.mdindex 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 noteAIR-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.mdindex 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 noteAIR-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.mdindex 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 noteAIR-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.mdindex 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 milestoneRecommended: **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.mdnew file mode 100644index 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.mdindex 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 noteThe 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.mdindex 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 noteFor 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.firmfixtureindex 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.