Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add side-hole region integration decision trace
Yuechen Lib616831e442e
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.csindex a7b319ee..5fb93b74 100644--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs@@ -324,6 +324,14 @@ public sealed class AirTraceCommandTestsAssert.Contains("opposite-side exit deferred", output); Assert.Contains("cylindrical cut wall intent deferred", output);Assert.Contains("CutEntryLoop", output); Assert.Contains("CutWallFace", output);Assert.Contains("no parent topology mutation", output); Assert.Contains("no BRepPlan elements materialized", output);+ Assert.Contains("Region integration decision", output);+ Assert.Contains("Selected: DeferredIntegration", output);+ Assert.Contains("Status: Deferred", output);+ Assert.Contains("FaceAttachedConstructiveInsertion: Deferred", output);+ Assert.Contains("LocalBRepPlanPatch: Deferred", output);+ Assert.Contains("BRepBooleanFallback: Rejected", output);+ Assert.Contains("CirAnalysisMirrorOnly: AvailableForAnalysis", output);+ Assert.Contains("no BRep emission", output);}[Fact]@@ -334,7 +342,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-brep-boundary", root.GetProperty("actualStageReached").GetString());+ Assert.Equal("region-integration-decision", root.GetProperty("actualStageReached").GetString());var regions = root.GetProperty("regions");Assert.Equal(2, regions.GetProperty("regionCount").GetInt32());Assert.True(regions.GetProperty("hasNestedRegions").GetBoolean());@@ -389,6 +397,21 @@ public sealed class AirTraceCommandTestsAssert.Contains("no-emitted-cut-wall-face-identity", boundaryLosses);Assert.Contains("no-brep-plan-element-materialization", boundaryLosses);Assert.Equal("Deferred", brepBoundary.GetProperty("integrationStatus").GetString());+ var decision = side.GetProperty("integrationDecision");+ Assert.Equal("DeferredIntegration", decision.GetProperty("selectedRouteKind").GetString());+ Assert.Equal("Deferred", decision.GetProperty("selectedStatus").GetString());+ Assert.Equal("SwitchMatch", decision.GetProperty("selectionMode").GetString());+ var candidates = decision.GetProperty("candidates").EnumerateArray().ToDictionary(c => c.GetProperty("routeKind").GetString()!, c => c);+ Assert.Equal("Deferred", candidates["FaceAttachedConstructiveInsertion"].GetProperty("status").GetString());+ Assert.Equal("side-hole-constructive-insertion-not-implemented", candidates["FaceAttachedConstructiveInsertion"].GetProperty("reasonCode").GetString());+ Assert.Equal("Deferred", candidates["LocalBRepPlanPatch"].GetProperty("status").GetString());+ Assert.Equal("local-brep-plan-patch-not-implemented", candidates["LocalBRepPlanPatch"].GetProperty("reasonCode").GetString());+ Assert.Equal("Rejected", candidates["BRepBooleanFallback"].GetProperty("status").GetString());+ Assert.Equal("boolean-fallback-not-admitted", candidates["BRepBooleanFallback"].GetProperty("reasonCode").GetString());+ Assert.Equal("AvailableForAnalysis", candidates["CirAnalysisMirrorOnly"].GetProperty("status").GetString());+ Assert.Equal("cir-mirror-analysis-only", candidates["CirAnalysisMirrorOnly"].GetProperty("reasonCode").GetString());+ Assert.Equal("Selected", candidates["DeferredIntegration"].GetProperty("status").GetString());+ Assert.Equal("no-topology-integration-route-admitted", candidates["DeferredIntegration"].GetProperty("reasonCode").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());@@ -411,10 +434,11 @@ public sealed class AirTraceCommandTestsAssert.False(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());var side = root.GetProperty("regions").GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion");Assert.False(side.TryGetProperty("brepBoundary", out _));+ Assert.False(side.TryGetProperty("integrationDecision", out _));}[Fact]- public void RegionBRepBoundarySummaries_AreDeterministic()+ public void RegionIntegrationDecisionSummaries_AreDeterministic(){var valid = RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture");var invalid = RegionFixture("invalid/implicit-parent-mutation.invalid.firmfixture");@@ -458,6 +482,7 @@ public sealed class AirTraceCommandTestsAssert.Equal(1, regions.GetProperty("regionCount").GetInt32());Assert.DoesNotContain("SideHole", output, StringComparison.Ordinal);Assert.DoesNotContain("brepBoundary", output, StringComparison.Ordinal);+ Assert.DoesNotContain("integrationDecision", output, StringComparison.Ordinal);}[Fact]diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.csindex c441c465..aa70b7d1 100644--- a/Aetheris.CLI/AirTrace.cs+++ b/Aetheris.CLI/AirTrace.cs@@ -192,12 +192,12 @@ internal static class AirTraceReportBuilderprivate static AirTraceReport BuildSideHoleFaceAttachedRegionFixture(FirmFixture fixture){var regions = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();- var actualStage = "region-brep-boundary";+ var actualStage = "region-integration-decision";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", "air-region-x4-firmfixture-boundary-contract-created", expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();- return new("AIR-REGION-X4", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole reports a trace-only BRepPlan boundary contract; parent integration remains deferred and no topology or geometry is emitted.",- new("RegionFixture", "none", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X4"),- new("none", null, false, "region integration deferred; no route selection invoked", "none", "none", []),+ var fxDiagnostics = Stable([.. fixture.Diagnostics, .. regions.Diagnostics, "air-region-x1-firmfixture-case-mapped", "air-region-x4-firmfixture-boundary-contract-created", "air-region-x5-firmfixture-integration-decision-created", expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();+ return new("AIR-REGION-X5", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole reports trace-only integration route candidates; DeferredIntegration is selected and no topology or geometry is emitted.",+ new("RegionFixture", "DeferredIntegration", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X5"),+ new("SwitchMatch", "DeferredIntegration", false, "region integration deferred; no topology integration route admitted", "FaceAttachedRegion", "SideHole", []),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, []),@@ -355,6 +355,28 @@ internal static class AirTraceTextRendererb.AppendLine(" Guarantees:");foreach (var guarantee in bb.Guarantees) b.AppendLine($" - {guarantee}");}+++ if (region.IntegrationDecision is not null)+ {+ var decision = region.IntegrationDecision;+ b.AppendLine(" Region integration decision");+ b.AppendLine($" Region: {decision.SourceRegionId}");+ b.AppendLine($" Feature: {decision.YieldFeatureKind}");+ b.AppendLine($" Effect: {decision.EffectKind}");+ b.AppendLine($" Boundary: {decision.BoundaryContractKind}");+ b.AppendLine($" Mode: {decision.SelectionMode}");+ b.AppendLine($" Selected: {decision.SelectedRouteKind}");+ b.AppendLine($" Status: {decision.SelectedStatus}");+ b.AppendLine(" Candidates:");+ foreach (var c in decision.Candidates)+ {+ b.AppendLine($" - {c.RouteKind}: {c.Status}");+ b.AppendLine($" Reason: {c.Reason}");+ }+ b.AppendLine(" Guarantees:");+ foreach (var guarantee in decision.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/Air/AirRegions.cs b/Aetheris.Kernel.Core/Air/AirRegions.csindex 8f253416..54389325 100644--- a/Aetheris.Kernel.Core/Air/AirRegions.cs+++ b/Aetheris.Kernel.Core/Air/AirRegions.cs@@ -9,6 +9,9 @@ internal enum AirLocalFrameHandedness { RightHanded, LeftHanded, Unknown }internal enum AirRegionIntegrationStatus { NotRequired, Deferred, Rejected, Admitted, Unsupported }internal enum AirRegionCirMirrorStatus { MirrorAdmittedConservative, MirrorUnavailable, MirrorRejectedLossyForRequest }internal enum AirRegionBRepBoundaryStatus { PlannedContractOnly, Deferred, Rejected, Unsupported }+internal enum AirRegionIntegrationRouteKind { FaceAttachedConstructiveInsertion, LocalBRepPlanPatch, BRepBooleanFallback, CirAnalysisMirrorOnly, DeferredIntegration, Unsupported }+internal enum AirRegionIntegrationCandidateStatus { Admitted, AvailableForAnalysis, Deferred, Rejected, Unavailable, NotApplicable, Selected }+internal sealed record AirVectorSummary(double X, double Y, double Z);@@ -22,6 +25,8 @@ internal sealed record AirRegionAffectedScopeSummary(string ScopeKind, bool Pareinternal 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 AirRegionBRepBoundarySummary(string SourceRegionId, AirRegionKind SourceRegionKind, string YieldId, string FeatureKind, AirRegionBRepBoundaryStatus Status, AirRegionAffectedParentSummary AffectedParent, AirRegionEntryBoundarySummary EntryBoundary, AirRegionExitBoundarySummary ExitBoundary, AirRegionCutWallIntentSummary CutWallIntent, string PatchIntent, IReadOnlyList<string> PlannedRoles, IReadOnlyList<string> DeferredElements, AirRegionIntegrationStatus IntegrationStatus, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Guarantees);+internal sealed record AirRegionIntegrationCandidate(AirRegionIntegrationRouteKind RouteKind, AirRegionIntegrationCandidateStatus Status, string ReasonCode, string Reason, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Guarantees);+internal sealed record AirRegionIntegrationDecisionSummary(string SourceRegionId, AirRegionKind SourceRegionKind, string YieldFeatureKind, AirRegionEffectKind EffectKind, AirRegionBoundaryContractKind BoundaryContractKind, string SelectionMode, AirRegionIntegrationRouteKind SelectedRouteKind, AirRegionIntegrationStatus SelectedStatus, IReadOnlyList<AirRegionIntegrationCandidate> Candidates, string Recommendation, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Guarantees);internal sealed record AirRegionAffectedParentSummary(string ParentRegionId, string ParentBody, string AffectedFaceSelector, string AffectedFaceRole, string AffectedScope, string Locality);internal sealed record AirRegionEntryBoundarySummary(string BoundaryKind, string ProfileKind, string ProfileSource, string LocalFrameId, string LoopIntent, string Role);internal sealed record AirRegionExitBoundarySummary(string BoundaryKind, string ExitKind, string Role, string Status, IReadOnlyList<string> Diagnostics);@@ -75,6 +80,29 @@ internal static class AirSideHoleRegionCirMirrorAdapterprivate static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);}++internal static class AirSideHoleRegionIntegrationSelector+{+ public static AirRegionIntegrationDecisionSummary Decide(AirRegionSummary region, AirRegionCirMirrorSummary mirror, AirRegionBRepBoundarySummary boundary)+ {+ if (region.Yield is null) throw new ArgumentException("Side-hole region must carry a yield summary.", nameof(region));+ var candidates = new AirRegionIntegrationCandidate[]+ {+ new(AirRegionIntegrationRouteKind.FaceAttachedConstructiveInsertion, AirRegionIntegrationCandidateStatus.Deferred, "side-hole-constructive-insertion-not-implemented", "no side-hole constructive insertion route yet", ["air-region-x5-face-attached-constructive-insertion-deferred", "air-region-x5-constructive-insertion-not-implemented"], ["constructive-insertion-not-implemented"], ["no parent topology mutation"]),+ new(AirRegionIntegrationRouteKind.LocalBRepPlanPatch, AirRegionIntegrationCandidateStatus.Deferred, "local-brep-plan-patch-not-implemented", "BRepPlan boundary contract exists; patch materialization not implemented", ["air-region-x5-local-brep-plan-patch-deferred", "air-region-x5-brep-plan-patch-not-implemented"], ["brep-plan-patch-not-implemented", "no-brep-plan-materialization"], ["BRepPlan boundary remains topology-side intent only"]),+ new(AirRegionIntegrationRouteKind.BRepBooleanFallback, AirRegionIntegrationCandidateStatus.Rejected, "boolean-fallback-not-admitted", "Boolean fallback not admitted for region integration in this milestone", ["air-region-x5-boolean-fallback-rejected-not-admitted", "air-region-x5-boolean-fallback-not-admitted"], ["boolean-fallback-not-admitted"], ["no Boolean"]),+ new(AirRegionIntegrationRouteKind.CirAnalysisMirrorOnly, AirRegionIntegrationCandidateStatus.AvailableForAnalysis, "cir-mirror-analysis-only", "CIR mirror exists from AIR-REGION-X3; cannot integrate topology", ["air-region-x5-cir-analysis-mirror-available-not-integration"], ["no-topology-authority"], ["CIR mirror remains analysis-only"]),+ new(AirRegionIntegrationRouteKind.DeferredIntegration, AirRegionIntegrationCandidateStatus.Selected, "no-topology-integration-route-admitted", "no topology integration route admitted; region remains deferred", ["air-region-x5-deferred-integration-selected", "air-region-x5-no-topology-integration-route-admitted"], ["integration-deferred"], ["parent integration deferred"])+ };+ var diagnostics = Stable(["air-region-x5-integration-decision-created", "air-region-x5-side-hole-integration-candidates-created", "air-region-x5-no-judgment-utility-required", "air-region-x5-parent-integration-deferred", "air-region-x5-no-boolean", "air-region-x5-no-brep-plan-materialization", "air-region-x5-no-brep-emission", "air-region-x5-no-step-smoke", "air-region-x5-no-parent-topology-mutation", .. candidates.SelectMany(c => c.Diagnostics)]).ToArray();+ var knownLosses = Stable(["no-topology-integration-route-admitted", "side-hole-constructive-insertion-not-implemented", "local-brep-plan-patch-not-implemented", "boolean-fallback-not-admitted", .. candidates.SelectMany(c => c.KnownLosses)]).ToArray();+ var guarantees = Stable(["selected integration result is Deferred", "no topology integration", "Boolean fallback rejected", "CIR mirror analysis-only", "BRepPlan boundary contract does not materialize topology", "no Boolean", "no BRepPlan materialization", "no BRep emission", "no STEP smoke", "no parent topology mutation", .. candidates.SelectMany(c => c.Guarantees)]).ToArray();+ return new(region.RegionId, region.RegionKind, region.Yield.FeatureKind, region.EffectKind, region.BoundaryContractKind, "SwitchMatch", AirRegionIntegrationRouteKind.DeferredIntegration, AirRegionIntegrationStatus.Deferred, candidates, "side-hole integration deferred; future BRepPlan patch or constructive insertion needed", diagnostics, knownLosses, guarantees);+ }++ private static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);+}+internal sealed record AirLocalFrameSummary(string FrameId,AirLocalFrameKind FrameKind,@@ -107,7 +135,9 @@ internal sealed record AirRegionSummary(AirRegionYieldSummary? Yield = null,AirRegionCirMirrorSummary? CirMirror = null,[property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]- AirRegionBRepBoundarySummary? BrepBoundary = null);+ AirRegionBRepBoundarySummary? BrepBoundary = null,+ [property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]+ AirRegionIntegrationDecisionSummary? IntegrationDecision = null);internal sealed record AirRegionTraceSummary(IReadOnlyList<AirRegionSummary> Regions,@@ -146,17 +176,20 @@ internal static class AirRegionTraceFactorySideHoleYield(root.RegionId));var mirror = AirSideHoleRegionCirMirrorAdapter.Admit(sideBase);var boundary = SideHoleBRepBoundary(sideBase);+ var decision = AirSideHoleRegionIntegrationSelector.Decide(sideBase, mirror.Summary, boundary);var side = sideBase with{- StageReached = "region-brep-boundary",- Provenance = "AIR-REGION-X4 metadata-driven fixture",- Diagnostics = Stable([.. sideBase.Diagnostics.Where(d => d != "air-region-x2-no-cir-mirror"), .. mirror.Summary.Diagnostics, .. boundary.Diagnostics]).ToArray(),- KnownLosses = Stable([.. sideBase.KnownLosses, .. mirror.Summary.KnownLosses, .. boundary.KnownLosses]).ToArray(),- Guarantees = Stable([.. sideBase.Guarantees, .. mirror.Summary.Guarantees, .. boundary.Guarantees]).ToArray(),+ StageReached = "region-integration-decision",+ Provenance = "AIR-REGION-X5 metadata-driven fixture",+ Diagnostics = Stable([.. sideBase.Diagnostics.Where(d => d != "air-region-x2-no-cir-mirror"), .. mirror.Summary.Diagnostics, .. boundary.Diagnostics, .. decision.Diagnostics]).ToArray(),+ KnownLosses = Stable([.. sideBase.KnownLosses, .. mirror.Summary.KnownLosses, .. boundary.KnownLosses, .. decision.KnownLosses]).ToArray(),+ Guarantees = Stable([.. sideBase.Guarantees, .. mirror.Summary.Guarantees, .. boundary.Guarantees, .. decision.Guarantees]).ToArray(),+ IntegrationRoute = "DeferredIntegration",CirMirror = mirror.Summary,- BrepBoundary = boundary+ BrepBoundary = boundary,+ IntegrationDecision = decision};- 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, .. side.BrepBoundary!.Diagnostics], ["escapes only through explicit yield", "no Boolean", "no geometry", "no BRep emission", "no STEP smoke", "no production route replacement", .. side.CirMirror.Guarantees, .. side.BrepBoundary.Guarantees]);+ 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, .. side.BrepBoundary!.Diagnostics, .. side.IntegrationDecision!.Diagnostics], ["escapes only through explicit yield", "no Boolean", "no geometry", "no BRep emission", "no STEP smoke", "no production route replacement", .. side.CirMirror.Guarantees, .. side.BrepBoundary.Guarantees, .. side.IntegrationDecision.Guarantees]);}public static AirRegionTraceSummary ForImplicitParentMutationRejected()diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.mdindex 3483d62c..3b7531f0 100644--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md@@ -801,3 +801,7 @@ The AIR Region side-hole CIR mirror is a side-channel analysis summary only. It## AIR-REGION-X4 side-hole BRep boundary contract noteAIR-REGION-X4 treats side-hole BRepPlan boundary information as a trace-only contract, not as topology materialization. The side-hole `FaceAttachedRegion` may report affected parent face intent, entry/exit boundary intent, cut-wall intent, planned role strings, deferred elements, losses, and guarantees while retaining deferred parent integration and denying Boolean, BRepPlan element, BRep, STEP, CIR topology authority, grammar, and route-selection behavior changes.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md b/docs/air-a1-air-regions-scoped-feature-lowering-audit.mdindex afa262cf..572049a6 100644--- a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md+++ b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md@@ -641,3 +641,7 @@ AIR-REGION-X3 demonstrates the A1 doctrine that region effects may be mirrored f### AIR-REGION-X4 status noteAIR-REGION-X4 adds a trace-only BRepPlan boundary contract for the side-hole `FaceAttachedRegion`. The summary records the affected `+X` parent face, circular entry-loop intent, deferred opposite-side exit intent, deferred cylindrical cut-wall intent, planned semantic role strings, deferred elements, losses, and guarantees. It preserves A1 locality: no parent topology mutation, no BRepPlan materialization, no Boolean, no BRep emission, no STEP smoke, and no production route replacement.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-region-x2-side-hole-yield-boundary-contract.md b/docs/air-region-x2-side-hole-yield-boundary-contract.mdindex 2e139565..1dc23fea 100644--- a/docs/air-region-x2-side-hole-yield-boundary-contract.md+++ b/docs/air-region-x2-side-hole-yield-boundary-contract.md@@ -88,3 +88,7 @@ AIR-REGION-X3 preserves the X2 side-hole yield boundary contract and adds a trac## AIR-REGION-X4 boundary-contract noteAIR-REGION-X4 builds on the X2 yield contract by adding a trace-only BRepPlan boundary contract summary under the side-hole `FaceAttachedRegion`. The summary reuses X2 attachment/profile/direction/scope facts and records future topology-planning roles as strings while keeping parent integration deferred and denying emitted entry loop, exit loop, cut-wall face, boundary patch, BRepPlan element, BRep, Boolean, and STEP identities.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-region-x3-side-hole-cir-mirror-analysis.md b/docs/air-region-x3-side-hole-cir-mirror-analysis.mdindex 307f4f1d..faf1a542 100644--- a/docs/air-region-x3-side-hole-cir-mirror-analysis.md+++ b/docs/air-region-x3-side-hole-cir-mirror-analysis.md@@ -76,3 +76,7 @@ Recommended next milestone: **AIR-REGION-X4 — Region-to-CIR occupancy sample a## AIR-REGION-X4 boundary-contract noteAIR-REGION-X4 preserves the X3 CIR mirror as analysis-only and adds a separate `brepBoundary` trace summary for side-hole topology-side intent. The BRep boundary summary records affected `+X` parent face intent, circular entry-loop intent, deferred opposite-side exit intent, deferred cylindrical cut-wall intent, planned semantic role strings, losses, and guarantees. It does not grant CIR topology authority and does not materialize BRepPlan, BRep, Boolean, or STEP output.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-region-x4-side-hole-brep-boundary-contract.md b/docs/air-region-x4-side-hole-brep-boundary-contract.mdindex 9294bec5..a7c66b9f 100644--- a/docs/air-region-x4-side-hole-brep-boundary-contract.md+++ b/docs/air-region-x4-side-hole-brep-boundary-contract.md@@ -96,3 +96,7 @@ JSON trace includes stable `regions.regions[].brepBoundary` fields such as `statRecommended: **AIR-REGION-X5 — Side-hole integration route decision scaffold, no integration**.X4 now records enough topology-planning intent to evaluate future routes without immediately materializing BRepPlan elements. The next blocker is route decision scaffolding that can compare direct BRepPlan placeholder planning, constructive side-hole insertion, or Boolean fallback as explicit deferred candidates without changing production behavior.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-region-x5-side-hole-integration-route-decision.md b/docs/air-region-x5-side-hole-integration-route-decision.mdnew file mode 100644index 00000000..dcb09060--- /dev/null+++ b/docs/air-region-x5-side-hole-integration-route-decision.md@@ -0,0 +1,65 @@+# AIR-REGION-X5 — Side-hole integration route decision scaffold++## Purpose and scope++AIR-REGION-X5 adds a trace-only integration route decision summary for the metadata-driven side-hole `FaceAttachedRegion` fixture:++`fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`++The purpose is to prevent side-hole regions from silently falling through to any backend. The trace now names candidate parent integration routes, gives deterministic statuses and reasons, and selects `DeferredIntegration`.++## Relationship to earlier milestones++AIR-A1 defines regions as scoped construction islands whose effects escape only through explicit yields. AIR-REGION-X1 introduced `RootRegion` and `FaceAttachedRegion` trace summaries. AIR-REGION-X2 established the side-hole subtractive yield and boundary contract. AIR-REGION-X3 added the CIR analysis mirror. AIR-REGION-X4 added BRepPlan boundary intent without materializing topology.++AIR-X2 route-selection doctrine says deterministic closed classifications should use switch/match rather than JudgmentUtility. X5 follows that doctrine: no competing admitted topology route exists, so the side-hole integration decision is a deterministic scaffold, not utility scoring.++## Why integration route decisions matter++A region yield is not an implicit command to mutate parent topology. X5 records what integration routes were considered and why each is unavailable, rejected, or analysis-only. This makes deferral explicit and machine-checkable.++## Candidate route taxonomy++| Candidate | Status | Reason |+| --- | --- | --- |+| `FaceAttachedConstructiveInsertion` | `Deferred` | No side-hole constructive insertion route has been implemented. |+| `LocalBRepPlanPatch` | `Deferred` | BRepPlan boundary intent exists, but patch/materialization is not implemented. |+| `BRepBooleanFallback` | `Rejected` | Boolean fallback is not admitted for region integration in this milestone. |+| `CirAnalysisMirrorOnly` | `AvailableForAnalysis` | CIR mirror can assist occupancy/containment/bounds analysis but cannot integrate topology. |+| `DeferredIntegration` | `Selected` | No topology integration route is admitted. |++## Decision result++The selected route is `DeferredIntegration` with selected status `Deferred`. Topology integration remains deferred.++## Boolean fallback rejection doctrine++Boolean is not the region model. Boolean fallback would need explicit admission plus provenance and topology-loss accounting. X5 does not admit that fallback and records `boolean-fallback-not-admitted`.++## CIR analysis-only candidate doctrine++The AIR-REGION-X3 CIR mirror remains an analysis side channel only. It has no topology authority, no face identity authority, and no STEP/export authority.++## Relationship to BRep boundary contract++The AIR-REGION-X4 BRepPlan boundary contract still records the affected `+X` face, circular entry loop intent, deferred opposite-side exit, deferred cylindrical cut wall intent, and future role names. X5 does not create BRepPlan elements or parent topology patches.++## Guarantees++X5 keeps these guarantees: no side-hole geometry, no Boolean invocation, no BRepPlan materialization, no parent topology mutation, no BRep emission, and no STEP smoke.++## Trace output example++Text trace includes a `Region integration decision` section with `Mode: SwitchMatch`, `Selected: DeferredIntegration`, `Status: Deferred`, and the candidate table above. JSON includes `regions.regions[].integrationDecision` for the side-hole `FaceAttachedRegion`.++## Non-goals++X5 does not implement side-hole geometry, Boolean integration, BRepPlan patch materialization, production route replacement, Firmament grammar expansion, CIR evaluator/tape changes, BRep topology changes, STEP exporter/importer changes, arbitrary graph support, import/recovery, triangle migration, or NURBS/freeform expansion.++## Tests run++Focused CLI trace tests were updated for text, JSON, non-integration guarantees, invalid implicit parent mutation, parser-backed root-region behavior, and deterministic output.++## Recommended next milestone++AIR-REGION-X6 should add region BRepPlan placeholder elements without parent mutation. X5 left the cleanest next blocker at patch/materialization intent: the boundary contract and route decision now agree that a local BRepPlan patch route is the likely topology-side next step, but it must still avoid parent mutation.diff --git a/docs/air-x2-route-selection-and-admissibility.md b/docs/air-x2-route-selection-and-admissibility.mdindex 8997c6aa..11aea5a4 100644--- a/docs/air-x2-route-selection-and-admissibility.md+++ b/docs/air-x2-route-selection-and-admissibility.md@@ -81,3 +81,7 @@ The AIR-X2 switch/match-selected `TopFaceLoopChamferPrismatic` route now has AIR## AIR-X7 invalid fixture trace noteAIR-X7 reuses AIR-X2 route-selection/admissibility decisions for invalid Firmament fixture traces. Arbitrary graph chamfers, non-uniform loop chamfers, and deferred loop fillets stop at route-selection/rejected/deferred stages with stable reason codes and no geometry emission.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.mdindex b662a1ef..872e3747 100644--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md@@ -180,3 +180,7 @@ For the side-hole region fixture, `aetheris trace` now renders a `Region yield`## AIR-REGION-X4 region BRep boundary trace noteFor `fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`, `aetheris trace` now reports a `Region BRepPlan boundary` text section and a structured `regions.regions[].brepBoundary` JSON object. The summary is contract-only: it records affected parent face, circular entry intent, deferred exit intent, deferred cylindrical cut-wall intent, planned role strings, losses, and guarantees while keeping integration deferred and materializing no topology.++## AIR-REGION-X5 note++AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. The side-hole `FaceAttachedRegion` now reports deterministic candidate statuses, selects `DeferredIntegration`, rejects Boolean fallback as not admitted, keeps the CIR mirror analysis-only, and keeps the BRepPlan boundary contract as topology-side intent without materialization.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 b3decdf7..e356972b 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-brep-boundary+// expected-stage: region-integration-decision// expected-region-kind: FaceAttachedRegion// expected-effect: Subtractive// expected-yield: YieldSubtractiveVolume@@ -26,6 +26,14 @@// expected-brep-role: CutEntryLoop// expected-brep-role: CutWallFace// expected-brep-loss: no-emitted-entry-loop-identity+// expected-integration-route: DeferredIntegration+// expected-integration-status: Deferred+// expected-candidate: FaceAttachedConstructiveInsertion:Deferred+// expected-candidate: LocalBRepPlanPatch:Deferred+// expected-candidate: BRepBooleanFallback:Rejected+// expected-candidate: CirAnalysisMirrorOnly:AvailableForAnalysis+// expected-candidate: DeferredIntegration:Selected+// expected-reason: no-topology-integration-route-admitted// description: Trace-only face-attached side-hole region fixture; integration deferred.solid box = Box(width: 10, depth: 8, height: 6);