Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add side-hole BRepPlan placeholders
Yuechen Lid852b3a1846f
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.csindex 5fb93b74..bb08fd88 100644--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs@@ -342,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-integration-decision", root.GetProperty("actualStageReached").GetString());+ Assert.Equal("region-brep-placeholders", root.GetProperty("actualStageReached").GetString());var regions = root.GetProperty("regions");Assert.Equal(2, regions.GetProperty("regionCount").GetInt32());Assert.True(regions.GetProperty("hasNestedRegions").GetBoolean());@@ -417,6 +417,68 @@ public sealed class AirTraceCommandTestsAssert.Equal("none", root.GetProperty("brepPlan").GetProperty("planKind").GetString());}++ [Fact]+ public void TraceSideHoleRegion_BRepPlaceholders_DefaultText()+ {+ var (exitCode, output, error) = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"));+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));+ Assert.Contains("Region BRepPlan placeholders", output);+ Assert.Contains("Status: PlaceholderOnly", output);+ Assert.Contains("Elements: 5", output);+ Assert.Contains("Materialized: 0", output);+ Assert.Contains("region:side-hole:+x:entry-loop", output);+ Assert.Contains("CutEntryLoop", output);+ Assert.Contains("CutExitLoop", output);+ Assert.Contains("CutWallFace", output);+ Assert.Contains("AffectedParentFace", output);+ Assert.Contains("RegionIntegrationPatch", output);+ Assert.Contains("no parent topology mutation", output);+ Assert.Contains("no BRep emission", output);+ Assert.Contains("no Boolean", output);+ }++ [Fact]+ public void TraceSideHoleRegion_BRepPlaceholders_Json()+ {+ 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;+ var side = root.GetProperty("regions").GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion");+ var placeholders = side.GetProperty("brepPlaceholders");+ Assert.Equal("PlaceholderOnly", placeholders.GetProperty("placeholderStatus").GetString());+ var summary = placeholders.GetProperty("summary");+ Assert.Equal(5, summary.GetProperty("placeholderElementCount").GetInt32());+ Assert.Equal(0, summary.GetProperty("materializedElementCount").GetInt32());+ Assert.Equal(5, summary.GetProperty("notMaterializedElementCount").GetInt32());+ var elements = placeholders.GetProperty("elements").EnumerateArray().ToArray();+ Assert.Equal(5, elements.Length);+ var ids = elements.Select(e => e.GetProperty("id").GetString()).ToArray();+ Assert.Contains("region:side-hole:+x:parent-face:+x", ids);+ Assert.Contains("region:side-hole:+x:entry-loop", ids);+ Assert.Contains("region:side-hole:+x:exit-loop", ids);+ Assert.Contains("region:side-hole:+x:cut-wall", ids);+ Assert.Contains("region:side-hole:+x:integration-patch", ids);+ var roles = elements.Select(e => e.GetProperty("role").GetString()).ToArray();+ 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("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.False(root.GetProperty("stepSmoke").GetProperty("succeeded").GetBoolean());+ }++ [Fact]+ public void TraceSideHoleRegion_BRepPlaceholders_StableIds()+ {+ var first = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"), "--json").Stdout;+ var second = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"), "--json").Stdout;+ using var d1 = JsonDocument.Parse(first); using var d2 = JsonDocument.Parse(second);+ static string[] P(JsonDocument d) => d.RootElement.GetProperty("regions").GetProperty("regions").EnumerateArray().Single(r => r.GetProperty("regionKind").GetString() == "FaceAttachedRegion").GetProperty("brepPlaceholders").GetProperty("elements").EnumerateArray().Select(e => e.GetProperty("id").GetString() + ":" + e.GetProperty("role").GetString()).ToArray();+ Assert.Equal(P(d1), P(d2));+ }+[Fact]public void TraceImplicitParentMutationRegion_RejectedWithYieldContractReason(){@@ -435,6 +497,7 @@ public sealed class AirTraceCommandTestsvar 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 _));+ Assert.False(side.TryGetProperty("brepPlaceholders", out _));}[Fact]diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.csindex aa70b7d1..5ab44de5 100644--- a/Aetheris.CLI/AirTrace.cs+++ b/Aetheris.CLI/AirTrace.cs@@ -192,11 +192,11 @@ internal static class AirTraceReportBuilderprivate static AirTraceReport BuildSideHoleFaceAttachedRegionFixture(FirmFixture fixture){var regions = AirRegionTraceFactory.ForFaceAttachedSideHoleDeferred();- var actualStage = "region-integration-decision";+ var actualStage = "region-brep-placeholders";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", 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"),+ 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", []),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"),@@ -357,6 +357,27 @@ internal static class AirTraceTextRenderer}+ if (region.BrepPlaceholders is not null)+ {+ var bp = region.BrepPlaceholders;+ b.AppendLine(" Region BRepPlan placeholders");+ b.AppendLine($" Region: {bp.SourceRegionId}");+ b.AppendLine($" Feature: {bp.FeatureKind}");+ b.AppendLine($" Status: {bp.PlaceholderStatus}");+ b.AppendLine($" Elements: {bp.Summary.PlaceholderElementCount}");+ b.AppendLine($" Materialized: {bp.Summary.MaterializedElementCount}");+ b.AppendLine(" Placeholders:");+ foreach (var e in bp.Elements)+ {+ b.AppendLine($" - {e.Id}");+ b.AppendLine($" Kind: {e.Kind}");+ b.AppendLine($" Role: {e.Role}");+ b.AppendLine($" Materialization: {e.MaterializationStatus}");+ }+ b.AppendLine(" Guarantees:");+ foreach (var guarantee in bp.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.csindex 54389325..7383492e 100644--- a/Aetheris.Kernel.Core/Air/AirRegions.cs+++ b/Aetheris.Kernel.Core/Air/AirRegions.cs@@ -11,6 +11,7 @@ internal enum AirRegionCirMirrorStatus { MirrorAdmittedConservative, MirrorUnavainternal 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 enum AirRegionBRepPlaceholderStatus { PlaceholderOnly, NotMaterialized, Deferred, Rejected, Unsupported }@@ -27,6 +28,10 @@ internal sealed record AirRegionCirMirrorSummary(string SourceRegionId, AirRegiointernal 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 AirRegionBRepPlaceholderElement(string Id, string Kind, string Role, IReadOnlyList<string> SemanticRoles, string SourceRegionId, string SourceYieldId, string ParentReference, string MaterializationStatus, IReadOnlyList<string> Diagnostics);+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 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);@@ -103,6 +108,35 @@ internal static class AirSideHoleRegionIntegrationSelectorprivate static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);}++internal static class AirSideHoleBRepPlaceholderPlanner+{+ public static AirRegionBRepPlaceholderPlan Plan(AirRegionSummary region, AirRegionBRepBoundarySummary boundary, AirRegionIntegrationDecisionSummary decision)+ {+ if (region.Yield is null) throw new ArgumentException("Side-hole region must carry a yield summary.", nameof(region));+ var y = region.Yield;+ var elements = new[]+ {+ Element(region.RegionId + ":parent-face:" + y.Attachment.FaceSelector.ToLowerInvariant(), "AffectedParentFaceReference", "AffectedParentFace", ["SideHoleFeature", "DeferredIntegration", "NotMaterialized"], region, y, "parent-face:+X", "ReferenceOnly", "air-region-x6-affected-parent-face-placeholder-created"),+ Element(region.RegionId + ":entry-loop", "EntryLoopPlaceholder", "CutEntryLoop", ["SideHoleFeature", "DeferredIntegration", "NotMaterialized"], region, y, "profile:Circle(radius=1);frame:side-hole:+x", "NotMaterialized", "air-region-x6-entry-loop-placeholder-created"),+ Element(region.RegionId + ":exit-loop", "ExitLoopPlaceholder", "CutExitLoop", ["SideHoleFeature", "DeferredIntegration", "NotMaterialized"], region, y, "opposite-side-exit:deferred", "NotMaterialized", "air-region-x6-exit-loop-placeholder-created"),+ Element(region.RegionId + ":cut-wall", "CutWallFacePlaceholder", "CutWallFace", ["SideHoleFeature", "DeferredIntegration", "NotMaterialized"], region, y, "cylindrical-cut-wall:intent", "NotMaterialized", "air-region-x6-cut-wall-placeholder-created"),+ Element(region.RegionId + ":integration-patch", "IntegrationPatchPlaceholder", "RegionIntegrationPatch", ["SideHoleFeature", "DeferredIntegration", "NotMaterialized"], region, y, "parent-body-local-patch:deferred", "NotMaterialized", "air-region-x6-integration-patch-placeholder-created")+ };+ var required = new[] { "AffectedParentFace", "CutEntryLoop", "CutExitLoop", "CutWallFace", "RegionIntegrationPatch" };+ var roles = elements.Select(e => e.Role).ToArray();+ var missing = required.Except(roles, StringComparer.Ordinal).Order(StringComparer.Ordinal).ToArray();+ var diagnostics = Stable(["air-region-x6-brep-placeholder-plan-created", "air-region-x6-side-hole-brep-placeholders-created", "air-region-x6-stable-placeholder-ids-created", "air-region-x6-placeholder-validation-succeeded", "air-region-x6-no-materialized-elements", "air-region-x6-parent-integration-still-deferred", "air-region-x6-no-parent-topology-mutation", "air-region-x6-no-brep-emission", "air-region-x6-no-step-smoke", "air-region-x6-no-boolean", "air-region-x6-x7-materialization-prep", .. elements.SelectMany(e => e.Diagnostics)]).ToArray();+ var guarantees = new[] { "no parent topology mutation", "no BRepPlan materialization", "no BRep emission", "no STEP smoke", "no Boolean", "no production route replacement", "integration still deferred", "prepared for future X7 materialization" };+ var losses = new[] { "air-region-x6-entry-loop-placeholder-not-materialized", "air-region-x6-exit-loop-placeholder-not-materialized", "air-region-x6-cut-wall-placeholder-not-materialized", "air-region-x6-integration-patch-not-materialized" };+ var summary = new AirRegionBRepPlaceholderSummary(elements.Length, 1, 1, 1, 1, 1, elements.Count(e => e.MaterializationStatus != "NotMaterialized" && e.MaterializationStatus != "ReferenceOnly"), elements.Length, region.RegionId, y.FeatureKind, AirRegionIntegrationStatus.Deferred, diagnostics, guarantees);+ return new("brep-placeholder-plan:side-hole:+x", region.RegionId, region.RegionKind, y.YieldId, y.FeatureKind, AirRegionBRepPlaceholderStatus.PlaceholderOnly, elements, summary, new(missing.Length == 0, required, missing, ["air-region-x6-placeholder-validation-succeeded"]), diagnostics, losses, guarantees);+ }++ private static AirRegionBRepPlaceholderElement Element(string id, string kind, string role, IReadOnlyList<string> semanticRoles, AirRegionSummary region, AirRegionYieldSummary yield, string parentReference, string materialization, string diagnostic) => new(id, kind, role, semanticRoles, region.RegionId, yield.YieldId, parentReference, materialization, [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,@@ -137,7 +171,9 @@ internal sealed record AirRegionSummary([property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]AirRegionBRepBoundarySummary? BrepBoundary = null,[property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]- AirRegionIntegrationDecisionSummary? IntegrationDecision = null);+ AirRegionIntegrationDecisionSummary? IntegrationDecision = null,+ [property: System.Text.Json.Serialization.JsonIgnore(Condition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull)]+ AirRegionBRepPlaceholderPlan? BrepPlaceholders = null);internal sealed record AirRegionTraceSummary(IReadOnlyList<AirRegionSummary> Regions,@@ -177,19 +213,21 @@ internal static class AirRegionTraceFactoryvar mirror = AirSideHoleRegionCirMirrorAdapter.Admit(sideBase);var boundary = SideHoleBRepBoundary(sideBase);var decision = AirSideHoleRegionIntegrationSelector.Decide(sideBase, mirror.Summary, boundary);+ var placeholders = AirSideHoleBRepPlaceholderPlanner.Plan(sideBase, boundary, decision);var side = sideBase with{- 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(),+ 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",CirMirror = mirror.Summary,BrepBoundary = boundary,- IntegrationDecision = decision+ IntegrationDecision = decision,+ BrepPlaceholders = placeholders};- 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]);+ 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]);}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 3b7531f0..c44c5ae3 100644--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md@@ -805,3 +805,7 @@ AIR-REGION-X4 treats side-hole BRepPlan boundary information as a trace-only con## AIR-REGION-X5 noteAIR-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-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.diff --git a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md b/docs/air-a1-air-regions-scoped-feature-lowering-audit.mdindex 572049a6..3a5925de 100644--- a/docs/air-a1-air-regions-scoped-feature-lowering-audit.md+++ b/docs/air-a1-air-regions-scoped-feature-lowering-audit.md@@ -645,3 +645,7 @@ AIR-REGION-X4 adds a trace-only BRepPlan boundary contract for the side-hole `Fa## AIR-REGION-X5 noteAIR-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-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.diff --git a/docs/air-region-x4-side-hole-brep-boundary-contract.md b/docs/air-region-x4-side-hole-brep-boundary-contract.mdindex a7c66b9f..4d220e61 100644--- a/docs/air-region-x4-side-hole-brep-boundary-contract.md+++ b/docs/air-region-x4-side-hole-brep-boundary-contract.md@@ -100,3 +100,7 @@ X4 now records enough topology-planning intent to evaluate future routes without## AIR-REGION-X5 noteAIR-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-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.diff --git a/docs/air-region-x5-side-hole-integration-route-decision.md b/docs/air-region-x5-side-hole-integration-route-decision.mdindex dcb09060..c17793d1 100644--- a/docs/air-region-x5-side-hole-integration-route-decision.md+++ b/docs/air-region-x5-side-hole-integration-route-decision.md@@ -63,3 +63,7 @@ Focused CLI trace tests were updated for text, JSON, non-integration guarantees,## Recommended next milestoneAIR-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.++## 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.diff --git a/docs/air-region-x6-side-hole-brep-placeholders.md b/docs/air-region-x6-side-hole-brep-placeholders.mdnew file mode 100644index 00000000..53a02082--- /dev/null+++ b/docs/air-region-x6-side-hole-brep-placeholders.md@@ -0,0 +1,102 @@+# AIR-REGION-X6 — Side-hole BRepPlan placeholders++## Purpose and scope++AIR-REGION-X6 adds trace-only BRepPlan placeholder elements for the metadata-driven side-hole `FaceAttachedRegion` fixture at `fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture`.++This is scaffolding for future topology work. It does not materialize side-hole BRepPlan patches, emit BRep, invoke Boolean, smoke STEP, mutate parent topology, change production routing, or expand Firmament grammar.++## Relationship to AIR-A1/X1/X2/X3/X4/X5++- AIR-A1 defines AIR Regions as scoped construction islands whose effects escape through explicit yields and route-selected parent integration.+- X1 made root and face-attached regions visible in trace output.+- X2 made the side-hole yield contract explicit: +X face attachment, circular radius-1 profile, through/inward direction, subtractive effect, through-cut boundary, parent-body-local scope, and deferred integration.+- X3 added a CIR analysis mirror and denied topology authority.+- X4 added the BRepPlan boundary contract: affected +X parent face, circular entry loop intent, opposite-side exit deferred, cylindrical cut wall intent deferred, planned role strings, and no materialization.+- X5 selected `DeferredIntegration` while rejecting Boolean fallback and deferring constructive/local BRepPlan patch routes.+- X6 now turns the X4 role intent into deterministic placeholder elements while preserving the X5 deferred integration decision.++## Why placeholders are needed before materialization++A side-hole materializer should not rediscover topology work from raw geometry or infer role identity after mutation. X6 records the planned topology boundary as stable, inspectable placeholders so X7 can materialize from an explicit contract: which parent face is affected, which entry/exit loops are required, which cut wall face is required, and which integration patch remains deferred.++## Placeholder model++The trace model uses `AirRegionBRepPlaceholderPlan` with:++- `planId`, source region/yield IDs, source region kind, and feature kind;+- `placeholderStatus` (`PlaceholderOnly` for X6);+- `elements` carrying stable IDs, kind, role, semantic role strings, source region/yield, parent reference, materialization status, and diagnostics;+- `summary` with role/count totals and materialized/not-materialized counts;+- `validation` for required roles;+- diagnostics, known losses, and no-materialization guarantees.++Roles remain strings/semantic roles rather than global BRepPlan enum expansion. This keeps the X6 surface narrow and non-breaking.++## Stable IDs and roles++The side-hole placeholder IDs are deterministic and human-readable:++| ID | Kind | Role | Materialization |+| --- | --- | --- | --- |+| `region:side-hole:+x:parent-face:+x` | `AffectedParentFaceReference` | `AffectedParentFace` | `ReferenceOnly` |+| `region:side-hole:+x:entry-loop` | `EntryLoopPlaceholder` | `CutEntryLoop` | `NotMaterialized` |+| `region:side-hole:+x:exit-loop` | `ExitLoopPlaceholder` | `CutExitLoop` | `NotMaterialized` |+| `region:side-hole:+x:cut-wall` | `CutWallFacePlaceholder` | `CutWallFace` | `NotMaterialized` |+| `region:side-hole:+x:integration-patch` | `IntegrationPatchPlaceholder` | `RegionIntegrationPatch` | `NotMaterialized` |++Semantic roles include `SideHoleFeature`, `DeferredIntegration`, and `NotMaterialized`.++## Counts and expected roles++Expected X6 counts for the side-hole fixture:++- placeholder elements: 5;+- affected parent face references: 1;+- entry loop placeholders: 1;+- exit loop placeholders: 1;+- cut wall face placeholders: 1;+- integration patch placeholders: 1;+- materialized elements: 0;+- not-materialized/reference-only elements: 5.++Required roles are `AffectedParentFace`, `CutEntryLoop`, `CutExitLoop`, `CutWallFace`, and `RegionIntegrationPatch`.++## No materialization guarantees++Every successful side-hole placeholder trace records:++- no parent topology mutation;+- no BRepPlan materialization;+- no BRep emission;+- no STEP smoke;+- no Boolean;+- no production route replacement;+- integration still deferred;+- prepared for future X7 materialization.++These placeholders do not imply emitted face, loop, coedge, edge, vertex, or STEP entity identity.++## Relationship to the BRep boundary contract++X4 describes boundary intent. X6 creates placeholder element scaffolding from that intent. The placeholders are still not materialized BRepPlan elements: they are the deterministic shape of future topology work.++## Relationship to X7++If this scaffolding remains stable, the recommended next milestone is **AIR-REGION-X7 — Golden-path side-hole placeholder materialization to BRep**. X7 can use the placeholder set as the input boundary for a first constrained BRep materialization path. If that proves too risky, the fallback X7 should be **Placeholder corpus/golden summaries** to expand deterministic fixtures before materialization.++## Non-goals++- no side-hole geometry;+- no Boolean;+- no BRepPlan materialization;+- no BRep emission;+- no STEP;+- no production route replacement;+- no CIR evaluator/tape changes;+- no BRep topology behavior changes;+- no Firmament grammar expansion.++## 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.diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.mdindex 872e3747..7a3ed46c 100644--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md@@ -184,3 +184,7 @@ For `fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfi## AIR-REGION-X5 noteAIR-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-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.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 e356972b..272b6664 100644--- a/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture+++ b/fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture@@ -1,6 +1,6 @@// case: side-hole-face-attached-region// expected: valid-// expected-stage: region-integration-decision+// expected-stage: region-brep-placeholders// expected-region-kind: FaceAttachedRegion// expected-effect: Subtractive// expected-yield: YieldSubtractiveVolume@@ -42,3 +42,12 @@ region sideHole on box.face("+X") {circle center(0, 0) radius 1;cut through;}++// expected-brep-placeholder-status: PlaceholderOnly+// expected-brep-placeholder-count: 5+// expected-materialized-placeholder-count: 0+// expected-placeholder: CutEntryLoop+// expected-placeholder: CutExitLoop+// expected-placeholder: CutWallFace+// expected-placeholder: AffectedParentFace+// expected-placeholder: RegionIntegrationPatch