Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add AIR-X5 CIR mirror adapter envelope

Yuechen Lie3e9f48a32f5
diff --git a/Aetheris.Kernel.Core.Tests/Air/AirCirMirrorAdapterTests.cs b/Aetheris.Kernel.Core.Tests/Air/AirCirMirrorAdapterTests.cs
new file mode 100644
index 00000000..70bf961a
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Air/AirCirMirrorAdapterTests.cs
@@ -0,0 +1,127 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Air.BRepPlan;
+using Aetheris.Kernel.Core.Brep.Prismatic;
+using Aetheris.Kernel.Core.Cir.Mirrors;
+
+namespace Aetheris.Kernel.Core.Tests.Air;
+
+public sealed class AirCirMirrorAdapterTests
+{
+ [Fact]
+ public void AirCirMirrorAdapter_PrismaticSectionTransition_AdmitsConvexMirror()
+ {
+ var result = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition();
+
+ Assert.True(result.Succeeded);
+ Assert.Equal(AirNodeKind.PrismaticSectionTransition, result.Summary.SourceNodeKind);
+ Assert.Equal("cir-convex-polyhedron", result.Summary.MirrorBackend);
+ Assert.Equal(CirMirrorStatus.MirrorAdmittedExact, result.Summary.Status);
+ Assert.True(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.Occupancy));
+ Assert.True(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.Map));
+ Assert.True(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.Containment));
+ Assert.True(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.Bounds));
+ Assert.True(result.Summary.KnownLosses.HasFlag(AirCirMirrorKnownLoss.FaceIdentity));
+ Assert.True(result.Summary.KnownLosses.HasFlag(AirCirMirrorKnownLoss.TopologyParity));
+ Assert.Contains("air-x5-cir-evaluation-side-channel-only", result.Summary.Diagnostics);
+ Assert.Contains("air-x5-no-topology-authority", result.Summary.Diagnostics);
+ Assert.Contains("air-x5-convex-polyhedron-mirror-admitted", result.Summary.Diagnostics);
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_TopFaceLoopChamfer_AdmitsConvexMirrorWithClassBProvenance()
+ {
+ var result = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer();
+
+ Assert.True(result.Succeeded);
+ Assert.Equal(AirNodeKind.TopFaceLoopChamfer, result.Summary.SourceNodeKind);
+ Assert.Equal(AirRouteKind.TopFaceLoopChamferPrismatic, result.Summary.RouteKind);
+ Assert.Equal(AirSelectionClass.FaceBoundaryLoop, result.Summary.SelectionClass);
+ Assert.Equal(AirRuleKind.UniformChamfer, result.Summary.RuleKind);
+ Assert.Equal("cir-convex-polyhedron", result.Summary.MirrorBackend);
+ Assert.True(result.Summary.KnownLosses.HasFlag(AirCirMirrorKnownLoss.ChamferFaceIdentity));
+ Assert.True(result.Summary.KnownLosses.HasFlag(AirCirMirrorKnownLoss.BRepPlanRoleParity));
+ Assert.Contains("air-x5-class-b-provenance-preserved", result.Summary.Diagnostics);
+ Assert.Contains("air-x5-cir-does-not-claim-chamfer-face-identity", result.Summary.Diagnostics);
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_TopFaceLoopChamfer_DoesNotClaimTopologyOrRoleParity()
+ {
+ var result = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer();
+ Assert.False(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.FaceIdentity));
+ Assert.False(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.LoopIdentity));
+ Assert.False(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.TopologyParity));
+ Assert.False(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.ChamferFaceIdentity));
+ Assert.False(result.Summary.Capabilities.HasFlag(AirCirMirrorCapability.BRepPlanRoleParity));
+
+ var lossy = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer(new AirCirMirrorRequest(
+ AirNodeKind.TopFaceLoopChamfer,
+ AirRouteKind.TopFaceLoopChamferPrismatic,
+ AirCirMirrorSourceKind.GeneratedNativeAir,
+ "air-x5-lossy-request",
+ AirCirMirrorCapability.FaceIdentity | AirCirMirrorCapability.TopologyParity | AirCirMirrorCapability.ChamferFaceIdentity | AirCirMirrorCapability.BRepPlanRoleParity,
+ AirSelectionClass.FaceBoundaryLoop,
+ AirRuleKind.UniformChamfer,
+ "generated/history-known"));
+
+ Assert.False(lossy.Succeeded);
+ Assert.Equal(CirMirrorStatus.MirrorRejectedLossyForRequest, lossy.Summary.Status);
+ Assert.Contains("air-x5-face-identity-request-rejected-lossy", lossy.Summary.Diagnostics);
+ Assert.Contains("air-x5-topology-parity-request-rejected-lossy", lossy.Summary.Diagnostics);
+ Assert.Contains("air-x5-chamfer-face-identity-request-rejected-lossy", lossy.Summary.Diagnostics);
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_ImportedOrBRepOnlySource_DoesNotInferMirror()
+ {
+ var imported = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition(new AirCirMirrorRequest(AirNodeKind.PrismaticSectionTransition, AirRouteKind.PrismaticSectionTransitionEmitter, AirCirMirrorSourceKind.ImportedOrRecovered, "imported-step"));
+ var brepOnly = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition(new AirCirMirrorRequest(AirNodeKind.PrismaticSectionTransition, AirRouteKind.PrismaticSectionTransitionEmitter, AirCirMirrorSourceKind.BRepOnly, "brep-only"));
+
+ Assert.False(imported.Succeeded);
+ Assert.False(brepOnly.Succeeded);
+ Assert.Equal(CirMirrorStatus.MirrorUnavailable, imported.Summary.Status);
+ Assert.Equal(CirMirrorStatus.MirrorUnavailable, brepOnly.Summary.Status);
+ Assert.Contains("air-x5-imported-source-mirror-inference-rejected", imported.Summary.Diagnostics);
+ Assert.Contains("air-x5-brep-only-source-mirror-unavailable", brepOnly.Summary.Diagnostics);
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_UnsupportedAirNode_ReturnsUnavailable()
+ {
+ var result = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition(new AirCirMirrorRequest(AirNodeKind.Unsupported, AirRouteKind.Unsupported, AirCirMirrorSourceKind.Unsupported, "unsupported"));
+
+ Assert.False(result.Succeeded);
+ Assert.Equal(CirMirrorStatus.MirrorUnavailable, result.Summary.Status);
+ Assert.Contains("air-x5-unsupported-air-node-mirror-unavailable", result.Summary.Diagnostics);
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_DeterministicSummaries()
+ {
+ var a = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition().Summary;
+ var b = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition().Summary;
+ var c = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer().Summary;
+ var d = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer().Summary;
+
+ Assert.Equal(Project(a), Project(b));
+ Assert.Equal(Project(c), Project(d));
+ }
+
+ [Fact]
+ public void AirCirMirrorAdapter_NonConvexPrismaticSectionTransition_ReturnsRejectedUnsupported()
+ {
+ var sections = new[]
+ {
+ new PrismaticSection(0, [(-5, -4), (5, -4), (5, 4), (-5, 4)]),
+ new PrismaticSection(5, [(-5, -4), (5, -4), (5, 4), (-5, 4)]),
+ new PrismaticSection(6, [(-4, -3), (0, -1), (4, -3), (4, 3), (-4, 3)]),
+ };
+ var result = AirCirMirrorAdapter.AdmitPrismaticSectionTransition(new PrismaticSectionTransitionRequest(sections, PrismaticCorrespondenceMap.Identity(5)));
+
+ Assert.False(result.Succeeded);
+ Assert.Equal(CirMirrorStatus.MirrorRejectedUnsupportedAtom, result.Summary.Status);
+ Assert.Contains("air-x5-non-convex-prismatic-mirror-rejected", result.Summary.Diagnostics);
+ }
+
+ private static string Project(AirCirMirrorAdapterSummary s) => string.Join("|", s.StatusText, s.MirrorBackend, s.Capabilities, s.KnownLosses, string.Join(",", s.Diagnostics), string.Join(",", s.Provenance));
+}
diff --git a/Aetheris.Kernel.Core/Air/AirCirMirrorAdapter.cs b/Aetheris.Kernel.Core/Air/AirCirMirrorAdapter.cs
new file mode 100644
index 00000000..8ba098a2
--- /dev/null
+++ b/Aetheris.Kernel.Core/Air/AirCirMirrorAdapter.cs
@@ -0,0 +1,185 @@
+using Aetheris.Kernel.Core.Brep.Prismatic;
+using Aetheris.Kernel.Core.Air.BRepPlan;
+using Aetheris.Kernel.Core.Cir.Mirrors;
+
+namespace Aetheris.Kernel.Core.Air;
+
+[Flags]
+internal enum AirCirMirrorCapability
+{
+ None = 0,
+ Occupancy = 1 << 0,
+ Map = 1 << 1,
+ Containment = 1 << 2,
+ Bounds = 1 << 3,
+ VolumeEstimate = 1 << 4,
+ ThicknessSummary = 1 << 5,
+ FaceIdentity = 1 << 16,
+ LoopIdentity = 1 << 17,
+ TopologyParity = 1 << 18,
+ FeatureLabels = 1 << 19,
+ ChamferFaceIdentity = 1 << 20,
+ BRepPlanRoleParity = 1 << 21,
+}
+
+[Flags]
+internal enum AirCirMirrorKnownLoss
+{
+ None = 0,
+ FaceIdentity = 1 << 0,
+ LoopIdentity = 1 << 1,
+ EdgeIdentity = 1 << 2,
+ TopologyParity = 1 << 3,
+ FeatureLabels = 1 << 4,
+ ChamferFaceIdentity = 1 << 5,
+ BRepPlanRoleParity = 1 << 6,
+}
+
+internal enum AirCirMirrorSourceKind { GeneratedNativeAir, ImportedOrRecovered, BRepOnly, Unsupported }
+
+internal sealed record AirCirMirrorRequest(
+ AirNodeKind SourceNodeKind,
+ AirRouteKind RouteKind,
+ AirCirMirrorSourceKind SourceKind,
+ string SourceNodeId,
+ AirCirMirrorCapability RequestedCapabilities = AirCirMirrorCapability.Occupancy | AirCirMirrorCapability.Map | AirCirMirrorCapability.Containment | AirCirMirrorCapability.Bounds,
+ AirSelectionClass SelectionClass = AirSelectionClass.None,
+ AirRuleKind RuleKind = AirRuleKind.None,
+ string ConstructionHistoryKind = "generated/constructive");
+
+internal sealed record AirCirMirrorAdapterSummary(
+ AirNodeKind SourceNodeKind,
+ AirRouteKind RouteKind,
+ CirMirrorStatus Status,
+ string StatusText,
+ string MirrorBackend,
+ AirCirMirrorCapability Capabilities,
+ AirCirMirrorKnownLoss KnownLosses,
+ AirCirMirrorSourceKind SourceKind,
+ string SourceNodeId,
+ AirSelectionClass SelectionClass,
+ AirRuleKind RuleKind,
+ string MirrorBuilderRoute,
+ IReadOnlyList<string> Provenance,
+ IReadOnlyList<string> Diagnostics,
+ IReadOnlyList<string> Guarantees);
+
+internal sealed record AirCirMirrorAdapterResult(
+ bool Succeeded,
+ AirCirMirrorAdapterSummary Summary,
+ CirPrismaticMirrorResult? PrismaticMirrorResult = null,
+ CirPrismaticMirrorSummary? TopViewSummary = null);
+
+internal static class AirCirMirrorAdapter
+{
+ private const string Backend = "cir-convex-polyhedron";
+ private const string BuilderRoute = "CirPrismaticMirrorBuilder.BuildFromSections";
+
+ private static readonly AirCirMirrorCapability TopologyClaims = AirCirMirrorCapability.FaceIdentity | AirCirMirrorCapability.LoopIdentity | AirCirMirrorCapability.TopologyParity | AirCirMirrorCapability.FeatureLabels | AirCirMirrorCapability.ChamferFaceIdentity | AirCirMirrorCapability.BRepPlanRoleParity;
+ private static readonly AirCirMirrorKnownLoss BaseLosses = AirCirMirrorKnownLoss.FaceIdentity | AirCirMirrorKnownLoss.LoopIdentity | AirCirMirrorKnownLoss.EdgeIdentity | AirCirMirrorKnownLoss.TopologyParity | AirCirMirrorKnownLoss.FeatureLabels;
+ private static readonly string[] BaseGuarantees = ["evaluation side-channel only", "no topology authority", "no production analyzer change", "no production route replacement", "no BRepPlan behavior change"];
+
+ public static AirCirMirrorAdapterResult AdmitPrismaticSectionTransition(PrismaticSectionTransitionRequest request, AirCirMirrorRequest? mirrorRequest = null)
+ {
+ mirrorRequest ??= new(AirNodeKind.PrismaticSectionTransition, AirRouteKind.PrismaticSectionTransitionEmitter, AirCirMirrorSourceKind.GeneratedNativeAir, "air-x5-prismatic-canonical");
+ var diagnostics = new List<string> { "air-x5-cir-mirror-adapter-created", "air-x5-prismatic-cir-mirror-request-created" };
+ var rejected = RejectInvalidSourceOrClaim(mirrorRequest, diagnostics, BaseLosses);
+ if (rejected is not null) return rejected;
+
+ var result = CirPrismaticMirrorBuilder.BuildFromSections(mirrorRequest.SourceNodeId, request.Sections, request.Correspondence);
+ diagnostics.AddRange(result.Diagnostics);
+ if (result.Succeeded) diagnostics.Add("air-x5-convex-polyhedron-mirror-admitted");
+ else diagnostics.Add("air-x5-non-convex-prismatic-mirror-rejected");
+ AddBoundaryDiagnostics(diagnostics);
+ return FromMirrorResult(mirrorRequest, result, BaseLosses, diagnostics);
+ }
+
+ public static AirCirMirrorAdapterResult AdmitCanonicalPrismaticSectionTransition(AirCirMirrorRequest? mirrorRequest = null) =>
+ AdmitPrismaticSectionTransition(new PrismaticSectionTransitionRequest(AirPrismaticSectionTransitionWrapper.CanonicalSections(), PrismaticCorrespondenceMap.Identity(4), new PrismaticSectionTransitionOptions(TraceLabel: "air-x5-prismatic-cir-mirror")), mirrorRequest);
+
+ public static AirCirMirrorAdapterResult AdmitTopFaceLoopChamfer(PrismaticTopFaceLoopChamferRequest request, AirCirMirrorRequest? mirrorRequest = null, AirBRepPlanFeatureContext? featureContext = null)
+ {
+ mirrorRequest ??= new(AirNodeKind.TopFaceLoopChamfer, AirRouteKind.TopFaceLoopChamferPrismatic, AirCirMirrorSourceKind.GeneratedNativeAir, "air-x5-top-face-loop-chamfer-canonical", SelectionClass: AirSelectionClass.FaceBoundaryLoop, RuleKind: AirRuleKind.UniformChamfer, ConstructionHistoryKind: "generated/history-known");
+ featureContext ??= AirTopFaceLoopChamferBRepPlanner.CanonicalFeatureContext();
+ var losses = BaseLosses | AirCirMirrorKnownLoss.ChamferFaceIdentity | AirCirMirrorKnownLoss.BRepPlanRoleParity;
+ var diagnostics = new List<string> { "air-x5-cir-mirror-adapter-created", "air-x5-top-face-loop-chamfer-cir-mirror-request-created" };
+ var rejected = RejectInvalidSourceOrClaim(mirrorRequest, diagnostics, losses);
+ if (rejected is not null) return rejected;
+ if (featureContext.SourceNodeKind != AirNodeKind.TopFaceLoopChamfer || featureContext.SelectionClass != AirSelectionClass.FaceBoundaryLoop || featureContext.RuleKind != AirRuleKind.UniformChamfer || featureContext.RouteKind != AirRouteKind.TopFaceLoopChamferPrismatic)
+ {
+ diagnostics.Add("air-x5-missing-air-provenance-rejected");
+ AddBoundaryDiagnostics(diagnostics);
+ return Unavailable(mirrorRequest, CirMirrorStatus.MirrorRejectedStaleOrMismatched, losses, diagnostics);
+ }
+
+ diagnostics.Add("air-x5-class-b-provenance-preserved");
+ diagnostics.Add("air-x5-uniform-chamfer-provenance-preserved");
+ diagnostics.Add("air-x5-cir-does-not-claim-chamfer-face-identity");
+ diagnostics.Add("air-x5-cir-does-not-claim-brep-plan-role-parity");
+ var result = CirPrismaticMirrorBuilder.BuildFromSections(mirrorRequest.SourceNodeId, PrismaticTopFaceLoopChamferPrototype.CreateSectionStack(request), PrismaticCorrespondenceMap.Identity(4));
+ diagnostics.AddRange(result.Diagnostics);
+ if (result.Succeeded) diagnostics.Add("air-x5-top-face-loop-chamfer-convex-mirror-admitted");
+ else diagnostics.Add("air-x5-non-convex-prismatic-mirror-rejected");
+ AddBoundaryDiagnostics(diagnostics);
+ return FromMirrorResult(mirrorRequest, result, losses, diagnostics);
+ }
+
+ public static AirCirMirrorAdapterResult AdmitCanonicalTopFaceLoopChamfer(AirCirMirrorRequest? mirrorRequest = null) =>
+ AdmitTopFaceLoopChamfer(new PrismaticTopFaceLoopChamferRequest(10, 8, 6, 1), mirrorRequest);
+
+ private static AirCirMirrorAdapterResult? RejectInvalidSourceOrClaim(AirCirMirrorRequest request, List<string> diagnostics, AirCirMirrorKnownLoss losses)
+ {
+ if (request.SourceKind == AirCirMirrorSourceKind.ImportedOrRecovered) { diagnostics.Add("air-x5-imported-source-mirror-inference-rejected"); return Unavailable(request, CirMirrorStatus.MirrorUnavailable, losses, diagnostics); }
+ if (request.SourceKind == AirCirMirrorSourceKind.BRepOnly) { diagnostics.Add("air-x5-brep-only-source-mirror-unavailable"); return Unavailable(request, CirMirrorStatus.MirrorUnavailable, losses, diagnostics); }
+ if (request.SourceNodeKind == AirNodeKind.Unsupported || request.RouteKind == AirRouteKind.Unsupported || request.SourceKind == AirCirMirrorSourceKind.Unsupported) { diagnostics.Add("air-x5-unsupported-air-node-mirror-unavailable"); return Unavailable(request, CirMirrorStatus.MirrorUnavailable, losses, diagnostics); }
+ if ((request.RequestedCapabilities & AirCirMirrorCapability.FaceIdentity) != 0) diagnostics.Add("air-x5-face-identity-request-rejected-lossy");
+ if ((request.RequestedCapabilities & AirCirMirrorCapability.TopologyParity) != 0) diagnostics.Add("air-x5-topology-parity-request-rejected-lossy");
+ if ((request.RequestedCapabilities & AirCirMirrorCapability.ChamferFaceIdentity) != 0) diagnostics.Add("air-x5-chamfer-face-identity-request-rejected-lossy");
+ if ((request.RequestedCapabilities & TopologyClaims) != 0) return Unavailable(request, CirMirrorStatus.MirrorRejectedLossyForRequest, losses, diagnostics);
+ return null;
+ }
+
+ private static AirCirMirrorAdapterResult FromMirrorResult(AirCirMirrorRequest request, CirPrismaticMirrorResult result, AirCirMirrorKnownLoss losses, List<string> diagnostics)
+ {
+ var capabilities = result.Succeeded ? MapCapabilities(result.Admission.AllowedCapabilities) | AirCirMirrorCapability.Bounds | AirCirMirrorCapability.ThicknessSummary : AirCirMirrorCapability.None;
+ var topView = result.Mirror?.CreateTopViewSummary(4, 4);
+ var summary = CreateSummary(request, result.Status, result.Succeeded ? Backend : "none", capabilities, losses, diagnostics, result.Recommendation);
+ return new(result.Succeeded, summary, result, topView);
+ }
+
+ private static AirCirMirrorAdapterResult Unavailable(AirCirMirrorRequest request, CirMirrorStatus status, AirCirMirrorKnownLoss losses, List<string> diagnostics)
+ {
+ AddBoundaryDiagnostics(diagnostics);
+ return new(false, CreateSummary(request, status, "none", AirCirMirrorCapability.None, losses, diagnostics, status.ToStableString()));
+ }
+
+ private static AirCirMirrorCapability MapCapabilities(CirMirrorCapability caps)
+ {
+ var mapped = AirCirMirrorCapability.None;
+ if ((caps & CirMirrorCapability.PointContainment) != 0) mapped |= AirCirMirrorCapability.Containment | AirCirMirrorCapability.Occupancy;
+ if ((caps & CirMirrorCapability.MapOccupancy) != 0) mapped |= AirCirMirrorCapability.Map | AirCirMirrorCapability.Occupancy;
+ if ((caps & CirMirrorCapability.ApproximateVolume) != 0) mapped |= AirCirMirrorCapability.VolumeEstimate;
+ if ((caps & CirMirrorCapability.SectionSampling) != 0) mapped |= AirCirMirrorCapability.ThicknessSummary;
+ return mapped;
+ }
+
+ private static AirCirMirrorAdapterSummary CreateSummary(AirCirMirrorRequest request, CirMirrorStatus status, string backend, AirCirMirrorCapability capabilities, AirCirMirrorKnownLoss losses, IEnumerable<string> diagnostics, string recommendation)
+ {
+ var stableDiagnostics = Stable(diagnostics).ToArray();
+ var provenance = Stable(["generated/native AIR", $"source-node-id:{request.SourceNodeId}", $"route:{request.RouteKind}", $"selection-class:{request.SelectionClass}", $"rule-kind:{request.RuleKind}", $"mirror-builder-route:{BuilderRoute}", $"recommendation:{recommendation}"]).ToArray();
+ return new(request.SourceNodeKind, request.RouteKind, status, status.ToStableString(), backend, capabilities, losses, request.SourceKind, request.SourceNodeId, request.SelectionClass, request.RuleKind, BuilderRoute, provenance, stableDiagnostics, BaseGuarantees);
+ }
+
+ private static void AddBoundaryDiagnostics(List<string> diagnostics)
+ {
+ diagnostics.Add("air-x5-cir-evaluation-side-channel-only");
+ diagnostics.Add("air-x5-no-topology-authority");
+ diagnostics.Add("air-x5-no-face-identity");
+ diagnostics.Add("air-x5-no-loop-identity");
+ diagnostics.Add("air-x5-no-topology-parity");
+ diagnostics.Add("air-x5-no-production-analyzer-change");
+ diagnostics.Add("air-x5-no-production-route-replacement");
+ }
+
+ private static IEnumerable<string> Stable(IEnumerable<string> values) => values.Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal);
+}
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index c06c8a7a..24fb5cdd 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -753,3 +753,7 @@ AIR-X3 adds the first minimal internal BRepPlan proof for `AirPrismaticSectionTr
## AIR-X4 status note
AIR-X4 adds feature-role-aware BRepPlan evidence for the Class B top-face loop chamfer lane. It preserves AIR-A0 authority boundaries: AIR remains constructive MIR, BRepPlan remains a non-materializing backend plan, BRep remains explicit topology/export authority, CIR remains a side-channel, and STEP remains serialization.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
diff --git a/docs/air-cir-a0-authority-and-mirror-contract.md b/docs/air-cir-a0-authority-and-mirror-contract.md
index 8f9a692b..8e4774b2 100644
--- a/docs/air-cir-a0-authority-and-mirror-contract.md
+++ b/docs/air-cir-a0-authority-and-mirror-contract.md
@@ -413,3 +413,7 @@ This milestone does not do any of the following:
## AIR-A0 constitutional follow-up
AIR-A0 formalizes this authority contract as the Aetheris V2 compiler IR constitution. It names AIR as the topology-generating constructive MIR, keeps CIR as an admitted mirror/evaluation side-channel, and introduces BRepPlan as the proposed backend topology emission plan between Constructive AIR and materialized BRep. See `docs/air-a0-aetheris-v2-compiler-ir-constitution.md`.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
diff --git a/docs/air-cir-x1-mirror-metadata-prototype.md b/docs/air-cir-x1-mirror-metadata-prototype.md
index 58570dbe..95f67d6b 100644
--- a/docs/air-cir-x1-mirror-metadata-prototype.md
+++ b/docs/air-cir-x1-mirror-metadata-prototype.md
@@ -137,3 +137,7 @@ The AIR-CIR-X1 production admission service remains intentionally conservative:
## CIR-PRISMATIC-X2 bounded prismatic availability note
CIR-PRISMATIC-X2 adds a bounded internal prismatic mirror availability path outside the AIR-CIR-X1 primitive admission service. For supported convex all-planar prismatic section stacks, `CirPrismaticMirrorBuilder` can return `mirror-admitted-exact` for point containment and map occupancy while carrying the established loss flags for face identity, loop identity, split-face lineage, feature role labels, and topology parity. This does not change production analyzer behavior or the X1 primitive dispatch contract.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
diff --git a/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md b/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
index e15af13e..a3c3b000 100644
--- a/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
+++ b/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
@@ -95,3 +95,7 @@ AIR-X4 does not change production routing, emitters, STEP exporter/importer, BRe
## Recommended next milestone
Recommended: **AIR-X5 — BRepPlan materialization adapter for prismatic transition, still non-production**. AIR-X4 showed that roles/provenance can be layered without changing production emitters; the next useful evidence is a non-production adapter that consumes these plans while preserving BRep as topology authority and keeping production routes untouched.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
diff --git a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
new file mode 100644
index 00000000..01100ae0
--- /dev/null
+++ b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
@@ -0,0 +1,95 @@
+# AIR-X5 — AIR-to-CIR mirror adapter envelope
+
+## Purpose and scope
+
+AIR-X5 adds a minimal internal/test-visible adapter that lets selected Constructive AIR nodes expose admitted CIR mirror metadata for analysis and evaluation side channels. It is intentionally an envelope around existing mirror evidence, not a CIR geometry expansion, analyzer replacement, topology parity milestone, or production route change.
+
+The first supported source nodes are:
+
+- `AirPrismaticSectionTransition` through the existing convex/all-planar prismatic mirror path.
+- `AirTopFaceLoopChamfer` when the generated prismatic/chamfer section stack is convex/all-planar and can be admitted by the same mirror builder.
+
+## Relationship to AIR-A0 through AIR-X4
+
+AIR-A0 defines the authority boundary: AIR owns constructive intent, BRepPlan/BRep own explicit topology and export planning, and CIR is an admitted field/evaluation side-channel. AIR-X1 provided minimal wrappers over proven lanes, AIR-X2 documented route-selection/admissibility, AIR-X3 introduced prismatic BRepPlan topology roles, and AIR-X4 overlaid top-face loop chamfer Class B provenance and chamfer-face BRepPlan roles.
+
+AIR-X5 consumes those facts without changing their authority. AIR provenance may be preserved in adapter metadata, but CIR mirror metadata remains evaluation-only and does not become topology or feature-role truth.
+
+## AIR-to-CIR side-channel doctrine
+
+The side channel is:
+
+`Constructive AIR -> admitted CIR mirror -> analysis/map/containment/bounds/thickness checks`
+
+It is not:
+
+`CIR -> BRep topology`, `CIR -> STEP construction truth`, or `CIR -> feature/face identity authority`.
+
+## Adapter model
+
+The adapter model is implemented by `AirCirMirrorAdapter` and related internal records/enums under `Aetheris.Kernel.Core.Air`.
+
+- Request: source AIR node kind, route kind, source kind, source node id, requested capabilities, selection class, rule kind, and construction-history kind.
+- Result: success flag, stable summary, optional prismatic mirror result, and optional deterministic top-view mirror summary.
+- Status: reuses existing CIR mirror statuses such as `mirror-admitted-exact`, `mirror-unavailable`, `mirror-rejected-unsupported-atom`, `mirror-rejected-lossy-for-request`, and `mirror-rejected-stale-or-mismatched`.
+- Backend: admitted first-scope mirrors report `cir-convex-polyhedron`.
+- Capabilities: occupancy, map, containment, bounds, and thickness summary are surfaced only when the existing convex mirror supports the underlying operations.
+- Losses: face identity, loop identity, edge identity, topology parity, feature labels, chamfer-face identity, and BRepPlan role parity are explicit AIR-level losses.
+- Provenance: generated/native AIR, source node id, route, selection class, rule kind, mirror-builder route, and recommendation are recorded as metadata.
+- Diagnostics: stable AIR-X5 diagnostics describe adapter creation, mirror request creation, admission/rejection, authority denial, and no production-route/analyzer changes.
+- Guarantees: evaluation side-channel only; no topology authority; no production analyzer, production route, or BRepPlan behavior change.
+
+## Prismatic section transition adapter
+
+The canonical prismatic case uses the existing three-section stack:
+
+- width `10`, depth `8`, height `6`, inset/chamfer distance `1`;
+- z0 = `0` full rectangle;
+- z1 = `5` full rectangle;
+- z2 = `6` inset rectangle.
+
+AIR-X5 routes this through `CirPrismaticMirrorBuilder.BuildFromSections`. When the builder admits the convex polyhedron, the adapter reports the convex mirror backend and evaluation capabilities (occupancy/map/containment/bounds and thickness summary where available). Known losses include no face identity, no loop identity, no edge identity, no topology parity, and no feature labels.
+
+## Top-face loop chamfer adapter
+
+The top-face loop chamfer adapter builds the same generated prismatic/chamfer section stack used by the existing prototype. It preserves Class B provenance in AIR adapter metadata:
+
+- source node kind: `TopFaceLoopChamfer`;
+- route: `TopFaceLoopChamferPrismatic`;
+- selection class: `FaceBoundaryLoop`;
+- rule kind: `UniformChamfer`.
+
+The admitted CIR backend is still the convex polyhedron mirror. Additional losses declare that CIR does not claim chamfer-face identity and does not claim BRepPlan role parity.
+
+## Provenance metadata is not topology capability
+
+AIR-X5 may record that a source operation was a generated Class B face-boundary loop uniform chamfer. That metadata helps downstream analysis understand the source path. It does not grant the CIR mirror the ability to identify chamfer faces, loops, BRepPlan roles, or topology parity. Those remain explicit losses until a future milestone admits them with evidence.
+
+## Rejected and deferred cases
+
+The adapter returns deterministic unavailable/rejected summaries for:
+
+- imported or recovered STEP/BRep sources: no AIR mirror is inferred from imported topology;
+- BRep-only bodies with no AIR source: mirror unavailable;
+- unsupported AIR nodes or routes: mirror unavailable;
+- non-convex or otherwise unsupported prismatic stacks: mirror rejected/unavailable according to existing builder evidence;
+- missing top-face loop chamfer Class B provenance: stale/mismatched rejection;
+- requests for face identity, topology parity, or chamfer-face identity: lossy-for-request rejection.
+
+## No production analyzer behavior change
+
+AIR-X5 does not replace production analyzer/map dispatch, production route selection, CIR evaluator/tape behavior, BRepPlan behavior, STEP exporter/importer behavior, BRep topology behavior, Firmament lowering behavior, Boolean behavior, AirEdgeSweep behavior, BrepBoundedChamfer/BrepBoundedFillet behavior, chamfer/fillet/shell geometry, arbitrary graph support, import/recovery, triangle migration, or NURBS/freeform behavior.
+
+## No topology authority
+
+CIR remains an evaluation mirror only. BRepPlan and BRep remain the authorities for planned and explicit topology.
+
+## Tests run
+
+Focused AIR-X5 tests were added to `Aetheris.Kernel.Core.Tests` for prismatic admission, top-face loop chamfer admission with Class B provenance, topology/role parity denial, imported/BRep-only rejection, unsupported AIR nodes, deterministic summaries, and non-convex rejection.
+
+## Recommended next milestone
+
+Recommended: **AIR-X6 — AIR/BRepPlan/CIR unified artifact summary for prismatic + loop chamfer**.
+
+Implementation showed that AIR-X3/X4 already carry useful BRepPlan topology-role metadata while AIR-X5 now carries evaluation-mirror metadata. A unified non-production artifact summary would make the authority boundaries easier to inspect without changing production routes or claiming CIR topology parity.
diff --git a/docs/cir-prismatic-x2-convex-polyhedron-mirror.md b/docs/cir-prismatic-x2-convex-polyhedron-mirror.md
index 40d2e8f4..3a7ac21c 100644
--- a/docs/cir-prismatic-x2-convex-polyhedron-mirror.md
+++ b/docs/cir-prismatic-x2-convex-polyhedron-mirror.md
@@ -178,3 +178,7 @@ EDGE-PRISMATIC-X8 consumes the X2 `CirConvexPolyhedronMirror` in a lab/test-only
## EDGE-PRISMATIC-X9 CLI consumption note
EDGE-PRISMATIC-X9 consumes the CIR-PRISMATIC-X2 convex-polyhedron mirror from an explicit experimental CLI route: `aetheris experimental prismatic-map --case <case> --rows <n> --cols <n> --json`. The route admits generated prismatic sources for map occupancy only and reports known losses for face identity, loop identity, split-face lineage, feature role labels, and topology parity. It does not add CIR-to-BRep extraction and does not infer mirrors from imported STEP.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
diff --git a/docs/frictionlab/edge-loop-x2-top-face-loop-chamfer-corpus.md b/docs/frictionlab/edge-loop-x2-top-face-loop-chamfer-corpus.md
index f2778db3..ad793657 100644
--- a/docs/frictionlab/edge-loop-x2-top-face-loop-chamfer-corpus.md
+++ b/docs/frictionlab/edge-loop-x2-top-face-loop-chamfer-corpus.md
@@ -223,3 +223,7 @@ AIR-X2 can select the top-face loop chamfer wrapper through deterministic switch
## AIR-X4 BRepPlan mapping note
AIR-X4 maps the corpus chamfer transition faces into BRepPlan `ChamferFace` semantic roles while preserving the existing prismatic/top-face loop chamfer emitter summaries and corpus expectations.
+
+## AIR-X5 status note
+
+AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](../air-x5-air-to-cir-mirror-adapter-envelope.md).