Skip to content

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.cs
index a7b319ee..5fb93b74 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -324,6 +324,14 @@ public sealed class AirTraceCommandTests
Assert.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 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-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 AirTraceCommandTests
Assert.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 AirTraceCommandTests
Assert.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 AirTraceCommandTests
Assert.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.cs
index c441c465..aa70b7d1 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -192,12 +192,12 @@ internal static class AirTraceReportBuilder
private 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 AirTraceTextRenderer
b.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.cs
index 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 Pare
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 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 AirSideHoleRegionCirMirrorAdapter
private 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 AirRegionTraceFactory
SideHoleYield(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.md
index 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 note
AIR-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.md
index 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 note
AIR-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.md
index 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 note
AIR-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.md
index 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 note
AIR-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.md
index 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 `stat
Recommended: **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.md
new file mode 100644
index 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.md
index 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 note
AIR-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.md
index 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 note
For `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.firmfixture
index 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);