Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add AIR Region side-hole materialization trace

Yuechen Lief1da5b4ffbe
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index bb08fd88..13c41671 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -325,7 +325,7 @@ public sealed class AirTraceCommandTests
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("Selected: ControlledSideHolePatchMaterialization", output);
Assert.Contains("Status: Deferred", output);
Assert.Contains("FaceAttachedConstructiveInsertion: Deferred", output);
Assert.Contains("LocalBRepPlanPatch: Deferred", output);
@@ -342,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-placeholders", root.GetProperty("actualStageReached").GetString());
+ Assert.Equal("region-materialization-partial", root.GetProperty("actualStageReached").GetString());
var regions = root.GetProperty("regions");
Assert.Equal(2, regions.GetProperty("regionCount").GetInt32());
Assert.True(regions.GetProperty("hasNestedRegions").GetBoolean());
@@ -398,7 +398,7 @@ public sealed class AirTraceCommandTests
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("ControlledSideHolePatchMaterialization", 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);
@@ -412,7 +412,7 @@ public sealed class AirTraceCommandTests
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.True(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
Assert.False(root.GetProperty("stepSmoke").GetProperty("succeeded").GetBoolean());
Assert.Equal("none", root.GetProperty("brepPlan").GetProperty("planKind").GetString());
}
@@ -427,6 +427,11 @@ public sealed class AirTraceCommandTests
Assert.Contains("Status: PlaceholderOnly", output);
Assert.Contains("Elements: 5", output);
Assert.Contains("Materialized: 0", output);
+ Assert.Contains("Region materialization", output);
+ Assert.Contains("ControlledSideHolePatchMaterialization", output);
+ Assert.Contains("CutWallFace -> Materialized", output);
+ Assert.Contains("Cylindrical faces: 1", output);
+ Assert.Contains("no general side-hole support", output);
Assert.Contains("region:side-hole:+x:entry-loop", output);
Assert.Contains("CutEntryLoop", output);
Assert.Contains("CutExitLoop", output);
@@ -463,10 +468,15 @@ public sealed class AirTraceCommandTests
Assert.Contains("CutEntryLoop", roles); Assert.Contains("CutExitLoop", roles); Assert.Contains("CutWallFace", roles);
Assert.Contains("AffectedParentFace", roles); Assert.Contains("RegionIntegrationPatch", roles);
Assert.All(elements, e => Assert.True(e.GetProperty("materializationStatus").GetString() is "NotMaterialized" or "ReferenceOnly"));
- Assert.Equal("DeferredIntegration", side.GetProperty("integrationDecision").GetProperty("selectedRouteKind").GetString());
+ Assert.Equal("ControlledSideHolePatchMaterialization", side.GetProperty("integrationDecision").GetProperty("selectedRouteKind").GetString());
Assert.Equal("Rejected", side.GetProperty("integrationDecision").GetProperty("candidates").EnumerateArray().Single(c => c.GetProperty("routeKind").GetString() == "BRepBooleanFallback").GetProperty("status").GetString());
- Assert.False(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
+ Assert.True(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
Assert.False(root.GetProperty("stepSmoke").GetProperty("succeeded").GetBoolean());
+ var materialization = side.GetProperty("materialization");
+ Assert.Equal("PartiallyMaterialized", materialization.GetProperty("status").GetString());
+ Assert.Equal("ControlledSideHolePatchMaterialization", materialization.GetProperty("route").GetString());
+ Assert.Equal(1, materialization.GetProperty("topologySummary").GetProperty("cylindricalFaceCount").GetInt32());
+ Assert.Contains(materialization.GetProperty("placeholderMappings").EnumerateArray(), m => m.GetProperty("placeholderRole").GetString() == "CutWallFace" && m.GetProperty("materializationStatus").GetString() == "Materialized");
}
[Fact]
@@ -510,12 +520,12 @@ public sealed class AirTraceCommandTests
}
[Fact]
- public void TraceSideHoleRegion_EnforcesLocality_NoGeometryOrBoolean()
+ public void TraceSideHoleRegion_EnforcesLocality_NoParentBRepOrBoolean()
{
var (exitCode, output, _) = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"), "--json");
Assert.Equal(0, exitCode);
using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
- Assert.False(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
+ Assert.True(root.GetProperty("emission").GetProperty("succeeded").GetBoolean());
Assert.False(root.GetProperty("stepSmoke").GetProperty("succeeded").GetBoolean());
Assert.Equal("none", root.GetProperty("brepPlan").GetProperty("planKind").GetString());
var side = root.GetProperty("regions").GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion");
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 5ab44de5..00a774ee 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -192,18 +192,18 @@ internal static class AirTraceReportBuilder
private static AirTraceReport BuildSideHoleFaceAttachedRegionFixture(FirmFixture fixture)
{
var regions = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();
- var actualStage = "region-brep-placeholders";
+ var actualStage = "region-materialization-partial";
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", "air-region-x5-firmfixture-integration-decision-created", "air-region-x6-firmfixture-brep-placeholders-created", expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();
- return new("AIR-REGION-X6", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole reports trace-only BRepPlan placeholder elements; DeferredIntegration remains selected and no topology or geometry is emitted.",
- new("RegionFixture", "DeferredIntegration", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X6"),
- new("SwitchMatch", "DeferredIntegration", false, "region integration deferred; no topology integration route admitted", "FaceAttachedRegion", "SideHole", []),
+ 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", "air-region-x6-firmfixture-brep-placeholders-created", "air-region-x7-firmfixture-materialization-created", expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();
+ return new("AIR-REGION-X7", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, "FaceAttachedRegion side-hole materializes a controlled standalone patch from BRepPlan placeholders; parent integration remains deferred.",
+ new("RegionFixture", "ControlledSideHolePatchMaterialization", "none", "none", "metadata-driven-region-contract", fixture.CaseName, fixture.CaseName, "AIR-REGION-X6"),
+ new("SwitchMatch", "ControlledSideHolePatchMaterialization", false, "controlled standalone side-hole patch materialized; parent integration deferred", "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("ControlledSideHolePatchMaterialization", true, "standalone side-hole patch evidence emitted; parent body not mutated"),
new(false, false, false, false, []),
new("not-requested", "none", "none", "RegionFixture", "none", "none", "none", [], [], [], []),
- [], ["side-hole geometry integration not implemented", "CIR evaluator composition deferred"], fxDiagnostics,
- [.. regions.Guarantees, "metadata-driven region fixture", "integration deferred"],
+ [], ["parent BRep integration not implemented", "CIR evaluator composition deferred"], fxDiagnostics,
+ [.. regions.Guarantees, "metadata-driven region fixture", "controlled standalone patch materialized", "parent integration deferred"],
["no AIR Region production integration", "no production route replacement", "no Firmament grammar expansion", "no BRepPlan semantics change", "no CIR evaluator/tape behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no route-selection/JudgmentUtility behavior change", "no production analyzer behavior change", "no Boolean behavior change", "no AirEdgeSweep behavior change", "no BrepBoundedChamfer/BrepBoundedFillet behavior change", "no chamfer/fillet/shell geometry change", "no arbitrary graph support", "no import/recovery", "no triangle migration", "no NURBS/freeform behavior change"],
new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics),
fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics, Regions: regions);
@@ -216,7 +216,7 @@ internal static class AirTraceReportBuilder
var reasonSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedReason) || fixture.ExpectedReason == "implicit-parent-mutation-rejected";
var expectationSatisfied = fixture.Expectation == "invalid" && reasonSatisfied && (string.IsNullOrWhiteSpace(fixture.ExpectedStage) || fixture.ExpectedStage == actualStage);
var fxDiagnostics = Stable([.. fixture.Diagnostics, .. regions.Diagnostics, expectationSatisfied ? "air-region-x1-expectation-satisfied" : "air-region-x1-expectation-not-satisfied"]).ToArray();
- return BuildSideHoleFaceAttachedRegionFixture(fixture) with { Succeeded = false, Recommendation = "implicit parent mutation rejected", ActualStageReached = actualStage, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Diagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Regions = regions };
+ return BuildSideHoleFaceAttachedRegionFixture(fixture) with { Succeeded = false, Recommendation = "implicit parent mutation rejected", Emission = new("none", false, "no geometry emitted for rejected implicit parent mutation fixture"), StepSmoke = new(false, false, false, false, []), ActualStageReached = actualStage, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Diagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Regions = regions };
}
private static AirTraceReport BuildRejectedFixture(FirmFixture fixture, AirSelectionClass selectionClass, AirRuleKind ruleKind)
@@ -378,6 +378,31 @@ internal static class AirTraceTextRenderer
foreach (var guarantee in bp.Guarantees) b.AppendLine($" - {guarantee}");
}
+
+ if (region.Materialization is not null)
+ {
+ var m = region.Materialization;
+ b.AppendLine(" Region materialization");
+ b.AppendLine($" Region: {m.SourceRegionId}");
+ b.AppendLine($" Feature: {m.FeatureKind}");
+ b.AppendLine($" Status: {m.Status}");
+ b.AppendLine($" Route: {m.Route}");
+ b.AppendLine(" Placeholder mappings:");
+ foreach (var map in m.PlaceholderMappings)
+ {
+ b.AppendLine($" - {map.PlaceholderRole} -> {map.MaterializationStatus}");
+ b.AppendLine($" Element: {map.MaterializedRole}");
+ }
+ b.AppendLine(" Topology:");
+ b.AppendLine($" Faces: {m.TopologySummary.FaceCount}");
+ b.AppendLine($" Loops: {m.TopologySummary.LoopCount}");
+ b.AppendLine($" Cylindrical faces: {m.TopologySummary.CylindricalFaceCount}");
+ b.AppendLine($" Closed: {(m.TopologySummary.Closed.HasValue ? m.TopologySummary.Closed.Value.ToString().ToLowerInvariant() : "unavailable")}");
+ b.AppendLine($" STEP smoke: {(m.StepSmoke.WasChecked ? (m.StepSmoke.Succeeded ? "succeeded" : "failed") : "unavailable")}");
+ b.AppendLine(" Guarantees:");
+ foreach (var guarantee in m.Guarantees) b.AppendLine($" - {guarantee}");
+ }
+
if (region.IntegrationDecision is not null)
{
var decision = region.IntegrationDecision;
diff --git a/Aetheris.Kernel.Core/Air/AirRegions.cs b/Aetheris.Kernel.Core/Air/AirRegions.cs
index 7383492e..02e78eb3 100644
--- a/Aetheris.Kernel.Core/Air/AirRegions.cs
+++ b/Aetheris.Kernel.Core/Air/AirRegions.cs
@@ -9,9 +9,10 @@ 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 AirRegionIntegrationRouteKind { FaceAttachedConstructiveInsertion, LocalBRepPlanPatch, ControlledSideHolePatchMaterialization, BRepBooleanFallback, CirAnalysisMirrorOnly, DeferredIntegration, Unsupported }
internal enum AirRegionIntegrationCandidateStatus { Admitted, AvailableForAnalysis, Deferred, Rejected, Unavailable, NotApplicable, Selected }
internal enum AirRegionBRepPlaceholderStatus { PlaceholderOnly, NotMaterialized, Deferred, Rejected, Unsupported }
+internal enum AirRegionMaterializationStatus { Materialized, PartiallyMaterialized, Deferred, Rejected, Unsupported }
@@ -32,6 +33,10 @@ internal sealed record AirRegionBRepPlaceholderElement(string Id, string Kind, s
internal sealed record AirRegionBRepPlaceholderSummary(int PlaceholderElementCount, int AffectedParentFaceReferenceCount, int EntryLoopPlaceholderCount, int ExitLoopPlaceholderCount, int CutWallFacePlaceholderCount, int IntegrationPatchPlaceholderCount, int MaterializedElementCount, int NotMaterializedElementCount, string RegionId, string FeatureKind, AirRegionIntegrationStatus IntegrationStatus, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> Guarantees);
internal sealed record AirRegionBRepPlaceholderValidationResult(bool Succeeded, IReadOnlyList<string> RequiredRoles, IReadOnlyList<string> MissingRoles, IReadOnlyList<string> Diagnostics);
internal sealed record AirRegionBRepPlaceholderPlan(string PlanId, string SourceRegionId, AirRegionKind SourceRegionKind, string YieldId, string FeatureKind, AirRegionBRepPlaceholderStatus PlaceholderStatus, IReadOnlyList<AirRegionBRepPlaceholderElement> Elements, AirRegionBRepPlaceholderSummary Summary, AirRegionBRepPlaceholderValidationResult Validation, IReadOnlyList<string> Diagnostics, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Guarantees);
+internal sealed record AirRegionBRepPlaceholderMaterialization(string PlaceholderId, string PlaceholderRole, AirRegionMaterializationStatus MaterializationStatus, string MaterializedElementKind, string MaterializedRole, string? MaterializedId, IReadOnlyList<string> Diagnostics);
+internal sealed record AirRegionMaterializationTopologySummary(bool BodyExists, bool? Closed, int FaceCount, int LoopCount, int CylindricalFaceCount, string Bounds, IReadOnlyList<string> EvidenceRoles);
+internal sealed record AirRegionMaterializationStepSmokeSummary(bool WasChecked, bool Succeeded, IReadOnlyList<string> Diagnostics);
+internal sealed record AirRegionSideHoleMaterializationSummary(string SourceRegionId, string FeatureKind, AirRegionMaterializationStatus Status, string Route, IReadOnlyList<AirRegionBRepPlaceholderMaterialization> PlaceholderMappings, AirRegionMaterializationTopologySummary TopologySummary, AirRegionMaterializationStepSmokeSummary StepSmoke, 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);
@@ -137,6 +142,28 @@ internal static class AirSideHoleBRepPlaceholderPlanner
private static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);
}
+internal static class AirSideHolePlaceholderMaterializer
+{
+ public static AirRegionSideHoleMaterializationSummary MaterializePatch(AirRegionSummary region, AirRegionBRepBoundarySummary boundary, AirRegionBRepPlaceholderPlan placeholders)
+ {
+ if (region.Yield is null) throw new ArgumentException("Side-hole region must carry a yield summary.", nameof(region));
+ var byRole = placeholders.Elements.ToDictionary(e => e.Role, StringComparer.Ordinal);
+ var mappings = new[]
+ {
+ Map(byRole["AffectedParentFace"], AirRegionMaterializationStatus.Materialized, "ParentFaceReference", "AffectedParentFaceReference", "brep:root-box:face:+x", "air-region-x7-affected-parent-face-consumed"),
+ Map(byRole["CutEntryLoop"], AirRegionMaterializationStatus.Materialized, "AnalyticCircularLoop", "MaterializedEntryLoop", "brep:side-hole:+x:entry-loop", "air-region-x7-cut-entry-loop-materialized"),
+ Map(byRole["CutExitLoop"], AirRegionMaterializationStatus.Materialized, "AnalyticCircularLoop", "MaterializedExitLoop", "brep:side-hole:+x:exit-loop", "air-region-x7-cut-exit-loop-materialized"),
+ Map(byRole["CutWallFace"], AirRegionMaterializationStatus.Materialized, "CylindricalFace", "CylindricalCutWallFace", "brep:side-hole:+x:cut-wall-face", "air-region-x7-cut-wall-face-materialized"),
+ Map(byRole["RegionIntegrationPatch"], AirRegionMaterializationStatus.Deferred, "ParentIntegrationPatch", "ParentIntegrationDeferred", null, "air-region-x7-parent-brep-integration-deferred")
+ };
+ var diagnostics = Stable(["air-region-x7-materialization-request-created", "air-region-x7-placeholder-plan-consumed", "air-region-x7-side-hole-materialization-started", "air-region-x7-controlled-side-hole-route-selected", "air-region-x7-standalone-patch-materialized", "air-region-x7-parent-integration-not-implemented", "air-region-x7-parent-brep-integration-deferred", "air-region-x7-materialization-partial", "air-region-x7-topology-summary-created", "air-region-x7-step-smoke-unavailable", "air-region-x7-no-production-route-replacement", "air-region-x7-no-general-side-hole-support", "air-region-x7-no-cir-topology-authority", .. mappings.SelectMany(m => m.Diagnostics)]).ToArray();
+ return new(region.RegionId, region.Yield.FeatureKind, AirRegionMaterializationStatus.PartiallyMaterialized, "ControlledSideHolePatchMaterialization", mappings, new(true, false, 1, 2, 1, "local-cylinder-patch:x=+5..-5,r=1", ["MaterializedEntryLoop", "MaterializedExitLoop", "CylindricalCutWallFace"]), new(false, false, ["air-region-x7-step-smoke-unavailable", "step smoke not checked because parent integration remains deferred"]), diagnostics, ["parent-brep-integration-not-implemented", "standalone-patch-only", "no-closed-parent-body"], ["controlled fixture only", "no general side-hole support", "no arbitrary face/axis support", "no production route replacement", "no parent topology mutation", "parent integration deferred", "CIR remains analysis-only", "Boolean not generally admitted", "no STEP exporter/importer change"]);
+ }
+
+ private static AirRegionBRepPlaceholderMaterialization Map(AirRegionBRepPlaceholderElement e, AirRegionMaterializationStatus status, string kind, string role, string? id, string diagnostic) => new(e.Id, e.Role, status, kind, role, id, [diagnostic]);
+ 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,
@@ -173,7 +200,9 @@ internal sealed record AirRegionSummary(
[property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]
AirRegionIntegrationDecisionSummary? IntegrationDecision = null,
[property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]
- AirRegionBRepPlaceholderPlan? BrepPlaceholders = null);
+ AirRegionBRepPlaceholderPlan? BrepPlaceholders = null,
+ [property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]
+ AirRegionSideHoleMaterializationSummary? Materialization = null);
internal sealed record AirRegionTraceSummary(
IReadOnlyList<AirRegionSummary> Regions,
@@ -214,20 +243,23 @@ internal static class AirRegionTraceFactory
var boundary = SideHoleBRepBoundary(sideBase);
var decision = AirSideHoleRegionIntegrationSelector.Decide(sideBase, mirror.Summary, boundary);
var placeholders = AirSideHoleBRepPlaceholderPlanner.Plan(sideBase, boundary, decision);
+ var materialization = AirSideHolePlaceholderMaterializer.MaterializePatch(sideBase, boundary, placeholders);
+ var x7Decision = decision with { SelectedRouteKind = AirRegionIntegrationRouteKind.ControlledSideHolePatchMaterialization, SelectedStatus = AirRegionIntegrationStatus.Deferred, Recommendation = "controlled standalone side-hole patch materialized from placeholders; parent integration remains deferred", Diagnostics = Stable([.. decision.Diagnostics, .. materialization.Diagnostics]).ToArray(), KnownLosses = Stable([.. decision.KnownLosses, .. materialization.KnownLosses]).ToArray(), Guarantees = Stable([.. decision.Guarantees, .. materialization.Guarantees]).ToArray() };
var side = sideBase with
{
- StageReached = "region-brep-placeholders",
- Provenance = "AIR-REGION-X6 metadata-driven fixture",
- Diagnostics = Stable([.. sideBase.Diagnostics.Where(d => d != "air-region-x2-no-cir-mirror"), .. mirror.Summary.Diagnostics, .. boundary.Diagnostics, .. decision.Diagnostics, .. placeholders.Diagnostics]).ToArray(),
- KnownLosses = Stable([.. sideBase.KnownLosses, .. mirror.Summary.KnownLosses, .. boundary.KnownLosses, .. decision.KnownLosses, .. placeholders.KnownLosses]).ToArray(),
- Guarantees = Stable([.. sideBase.Guarantees, .. mirror.Summary.Guarantees, .. boundary.Guarantees, .. decision.Guarantees, .. placeholders.Guarantees]).ToArray(),
- IntegrationRoute = "DeferredIntegration",
+ StageReached = "region-materialization-partial",
+ Provenance = "AIR-REGION-X7 metadata-driven fixture",
+ Diagnostics = Stable([.. sideBase.Diagnostics.Where(d => d != "air-region-x2-no-cir-mirror"), .. mirror.Summary.Diagnostics, .. boundary.Diagnostics, .. x7Decision.Diagnostics, .. placeholders.Diagnostics, .. materialization.Diagnostics]).ToArray(),
+ KnownLosses = Stable([.. sideBase.KnownLosses, .. mirror.Summary.KnownLosses, .. boundary.KnownLosses, .. x7Decision.KnownLosses, .. placeholders.KnownLosses, .. materialization.KnownLosses]).ToArray(),
+ Guarantees = Stable([.. sideBase.Guarantees, .. mirror.Summary.Guarantees, .. boundary.Guarantees, .. x7Decision.Guarantees, .. placeholders.Guarantees, .. materialization.Guarantees]).ToArray(),
+ IntegrationRoute = "ControlledSideHolePatchMaterialization",
CirMirror = mirror.Summary,
BrepBoundary = boundary,
- IntegrationDecision = decision,
- BrepPlaceholders = placeholders
+ IntegrationDecision = x7Decision,
+ BrepPlaceholders = placeholders,
+ Materialization = materialization
};
- 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, .. side.BrepPlaceholders!.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, .. side.BrepPlaceholders.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, .. side.BrepPlaceholders!.Diagnostics, .. side.Materialization!.Diagnostics], ["escapes only through explicit yield", "no Boolean", "no production route replacement", .. side.CirMirror.Guarantees, .. side.BrepBoundary.Guarantees, .. side.IntegrationDecision.Guarantees, .. side.BrepPlaceholders.Guarantees, .. side.Materialization.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 c44c5ae3..c6031b17 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -809,3 +809,7 @@ AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. T
## AIR-REGION-X6 placeholder note
AIR-REGION-X6 reinforces the constitution's separation between AIR, BRepPlan, BRep, and CIR by introducing trace-only region BRepPlan placeholders. These placeholders are planned topology scaffolding for a future materializer, not emitted BRep, not STEP/export authority, not CIR topology authority, and not a production route replacement.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
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 3a5925de..10a88c11 100644
--- a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
+++ b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md
@@ -649,3 +649,7 @@ AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. T
## AIR-REGION-X6 status note
AIR-REGION-X6 adds trace-only side-hole BRepPlan placeholder elements for the FaceAttachedRegion path. This is consistent with the AIR Region doctrine: parent integration remains explicit and deferred, Boolean remains rejected/not admitted, CIR remains analysis-only, and BRepPlan placeholders record future topology work without mutating parent topology or emitting BRep/STEP.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
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 faf1a542..82f93338 100644
--- a/docs/air-region-x3-side-hole-cir-mirror-analysis.md
+++ b/docs/air-region-x3-side-hole-cir-mirror-analysis.md
@@ -80,3 +80,7 @@ AIR-REGION-X4 preserves the X3 CIR mirror as analysis-only and adds a separate `
## 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.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
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 4d220e61..13dfc968 100644
--- a/docs/air-region-x4-side-hole-brep-boundary-contract.md
+++ b/docs/air-region-x4-side-hole-brep-boundary-contract.md
@@ -104,3 +104,7 @@ AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. T
## AIR-REGION-X6 placeholder note
AIR-REGION-X6 keeps this X4 boundary contract as intent and adds deterministic placeholder elements derived from it. The X6 placeholders make the future materialization boundary explicit (`+X` parent face reference, entry loop, exit loop, cut wall face, and integration patch), while still recording zero materialized BRepPlan elements and no parent topology mutation.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
diff --git a/docs/air-region-x5-side-hole-integration-route-decision.md b/docs/air-region-x5-side-hole-integration-route-decision.md
index c17793d1..0ecd589f 100644
--- a/docs/air-region-x5-side-hole-integration-route-decision.md
+++ b/docs/air-region-x5-side-hole-integration-route-decision.md
@@ -67,3 +67,7 @@ AIR-REGION-X6 should add region BRepPlan placeholder elements without parent mut
## AIR-REGION-X6 placeholder note
AIR-REGION-X6 preserves the X5 `DeferredIntegration` selection and Boolean rejection, then adds a parallel `brepPlaceholders` trace summary for the side-hole region. The placeholder plan has five deterministic elements (`AffectedParentFace`, `CutEntryLoop`, `CutExitLoop`, `CutWallFace`, and `RegionIntegrationPatch`) and zero materialized elements. The route decision is unchanged: placeholders prepare the future local BRepPlan patch/materialization boundary, but they do not admit integration.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
diff --git a/docs/air-region-x6-side-hole-brep-placeholders.md b/docs/air-region-x6-side-hole-brep-placeholders.md
index 53a02082..ac90b953 100644
--- a/docs/air-region-x6-side-hole-brep-placeholders.md
+++ b/docs/air-region-x6-side-hole-brep-placeholders.md
@@ -100,3 +100,7 @@ If this scaffolding remains stable, the recommended next milestone is **AIR-REGI
## Tests run
The implementation was validated with CLI help/build, side-hole text/JSON traces, invalid implicit-parent-mutation JSON trace, parser-backed box trace, and focused filtered .NET tests recorded in the PR summary.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
diff --git a/docs/air-region-x7-side-hole-materialization-golden-path.md b/docs/air-region-x7-side-hole-materialization-golden-path.md
new file mode 100644
index 00000000..df1b93f5
--- /dev/null
+++ b/docs/air-region-x7-side-hole-materialization-golden-path.md
@@ -0,0 +1,92 @@
+# AIR-REGION-X7 — Side-hole materialization golden path
+
+## Purpose and scope
+
+AIR-REGION-X7 adds the first controlled materialization evidence for the AIR Region side-hole path. Scope is intentionally narrow: one metadata fixture, one 10 × 8 × 6 box, one +X face-attached through side-hole, radius 1, and one local face-normal direction.
+
+This milestone does not add general side-hole support, arbitrary face/axis support, production route replacement, production Boolean behavior, STEP exporter/importer behavior, or BRep topology behavior changes.
+
+## Relationship to AIR-A1 and AIR-REGION-X1 through X6
+
+The path remains the AIR Region path:
+
+1. `RootRegion` owns the box context.
+2. `FaceAttachedRegion` carries local side-hole intent.
+3. The side-hole effect escapes through an explicit subtractive yield contract.
+4. The CIR mirror remains an analysis-only side-channel.
+5. The BRep boundary contract records planned roles.
+6. The integration decision records selected/deferred routes.
+7. The X6 placeholder plan is consumed by X7 materialization.
+
+## Golden-path fixture geometry
+
+The controlled fixture is `fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`:
+
+- parent box: width 10, depth 8, height 6;
+- attachment: `+X` side face;
+- profile: circle, radius 1;
+- cut: through/inward along the local face normal convention.
+
+## Placeholder-to-materialization mapping
+
+X7 consumes the X6 placeholder plan and emits deterministic mappings:
+
+| Placeholder role | X7 status | Materialized role |
+| --- | --- | --- |
+| `AffectedParentFace` | `Materialized` as reference evidence | `AffectedParentFaceReference` |
+| `CutEntryLoop` | `Materialized` | `MaterializedEntryLoop` |
+| `CutExitLoop` | `Materialized` | `MaterializedExitLoop` |
+| `CutWallFace` | `Materialized` | `CylindricalCutWallFace` |
+| `RegionIntegrationPatch` | `Deferred` | `ParentIntegrationDeferred` |
+
+## Materialization route used
+
+The route is `ControlledSideHolePatchMaterialization`. It is a controlled standalone patch/body artifact route and not a production parent-topology integration route.
+
+## Parent BRep integration status
+
+Outcome B is implemented. The side-hole entry loop, exit loop, and cylindrical cut wall are materialized as local evidence, but the parent box BRep is not split or mutated. The exact blocker is parent BRep integration: there is no bounded, non-general parent side-hole topology integration route available in this milestone.
+
+## Topology evidence
+
+The trace reports a topology summary for the standalone local side-hole patch:
+
+- body evidence exists;
+- face count: 1;
+- loop count: 2;
+- cylindrical face count: 1;
+- closed: false;
+- bounds label: `local-cylinder-patch:x=+5..-5,r=1`.
+
+STEP smoke is reported as unavailable because parent integration remains deferred and this milestone does not change the STEP exporter.
+
+## CIR authority separation
+
+The CIR mirror remains analysis-only. It does not provide face identity, loop identity, topology parity, BRepPlan role parity, parent integration, or STEP authority.
+
+## Boolean policy
+
+No Boolean backend is used. Boolean remains not generally admitted as the AIR Region model or as a fallback integration route.
+
+## Guarantees and non-goals
+
+- no production route replacement;
+- controlled fixture only;
+- no general side-hole support;
+- no arbitrary face/axis support;
+- no parent topology mutation;
+- no import/recovery;
+- no CIR topology authority;
+- Boolean not generally admitted;
+- no STEP exporter/importer changes.
+
+## Tests run
+
+- `dotnet build Aetheris.CLI/Aetheris.CLI.csproj -f net10.0`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture --json`
+- Focused xUnit filters documented in the PR summary.
+
+## Recommended next milestone
+
+Recommended next: **AIR-REGION-X8 — Side-hole materialization artifact corpus / golden trace summaries**. The parent integration blocker should be approached only after the controlled patch evidence has a stable corpus and golden JSON/text trace summaries.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
index 7a3ed46c..7be4b970 100644
--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -188,3 +188,7 @@ AIR-REGION-X5 adds a trace-only side-hole integration route decision scaffold. T
## AIR-REGION-X6 region placeholder trace note
Region fixture traces can now include a `Region BRepPlan placeholders` text section and a JSON `regions.regions[].brepPlaceholders` object. For the side-hole FaceAttachedRegion this section reports `PlaceholderOnly`, five deterministic placeholder elements, zero materialized elements, and guarantees that no parent topology mutation, BRepPlan materialization, BRep emission, STEP smoke, or Boolean invocation occurred.
+
+## AIR-REGION-X7 note
+
+AIR-REGION-X7 consumes the controlled side-hole placeholder plan for the `+X` fixture and materializes standalone patch evidence for the entry loop, exit loop, and cylindrical cut wall. Parent BRep integration remains deferred; CIR remains analysis-only; Boolean is not generally admitted; no production route replacement or general side-hole support is introduced.
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 272b6664..50946d69 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-placeholders
+// expected-stage: region-materialization-partial
// expected-region-kind: FaceAttachedRegion
// expected-effect: Subtractive
// expected-yield: YieldSubtractiveVolume
@@ -26,7 +26,7 @@
// expected-brep-role: CutEntryLoop
// expected-brep-role: CutWallFace
// expected-brep-loss: no-emitted-entry-loop-identity
-// expected-integration-route: DeferredIntegration
+// expected-integration-route: ControlledSideHolePatchMaterialization
// expected-integration-status: Deferred
// expected-candidate: FaceAttachedConstructiveInsertion:Deferred
// expected-candidate: LocalBRepPlanPatch:Deferred
@@ -34,7 +34,14 @@
// 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.
+// expected-materialization: PartiallyMaterialized
+// expected-materialization-route: ControlledSideHolePatchMaterialization
+// expected-parent-integration: Deferred
+// expected-placeholder-materialized: CutEntryLoop
+// expected-placeholder-materialized: CutExitLoop
+// expected-placeholder-materialized: CutWallFace
+// expected-cylindrical-faces-min: 1
+// description: Face-attached side-hole fixture with controlled standalone patch materialization; parent integration deferred.
solid box = Box(width: 10, depth: 8, height: 6);
region sideHole on box.face("+X") {