Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-F15 emitted topology identity metadata bridge
Yuechen Lif4517c5d1706
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.csindex 7f061ce5..a7061e92 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs@@ -42,4 +42,22 @@ public sealed class SurfaceFamilyShellAssemblerTestsAssert.True(result.PlanarPatchCount > 0);Assert.True(result.CylindricalPatchConsumed);}++ [Fact]+ public void ShellAssembler_CanSeeTokenMatchedEmittedTopologyCandidates()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));+ var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);+ Assert.Contains(result.Diagnostics, d => d.Contains("token-match-candidates", StringComparison.OrdinalIgnoreCase));+ Assert.False(result.FullShellAssembled);+ }++ [Fact]+ public void EmittedIdentity_DoesNotExposeUserFacingTopologyNames()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));+ var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("firmament selector", StringComparison.OrdinalIgnoreCase));+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("user-facing topology names", StringComparison.OrdinalIgnoreCase));+ }}diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.csindex 520c21ef..ec407731 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs@@ -284,6 +284,41 @@ public sealed class SurfacePatchDescriptorScaffoldTestsAssert.Contains(result.Diagnostics, d => d.Contains("no shell assembly attempted", StringComparison.OrdinalIgnoreCase));}+ [Fact]+ public void EmittedIdentity_PlanarInnerCircle_CarriesTrimToken()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var generation = FacePatchCandidateGenerator.Generate(root);+ var hasInner = generation.Candidates.Any(c =>+ c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool+ && c.SourceSurface.Family == SurfacePatchFamily.Planar+ && c.RetainedRegionLoops.Any(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null && l.Status == RetainedRegionLoopStatus.ExactReady));+ var innerEntries = result.Entries.SelectMany(e => e.IdentityMap?.Entries ?? []).Where(e => e.Role == EmittedTopologyRole.InnerCircularTrim && e.Kind == EmittedTopologyKind.Edge).ToArray();+ if (hasInner)+ {+ Assert.NotEmpty(innerEntries);+ Assert.Contains(innerEntries, e => e.TrimIdentityToken is not null || e.Diagnostics.Any(d => d.Contains("missing", StringComparison.OrdinalIgnoreCase)));+ }+ else+ {+ Assert.Empty(innerEntries);+ }+ }++ [Fact]+ public void EmittedIdentity_PlanarPatchSet_PropagatesInnerCircleToken()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var generation = FacePatchCandidateGenerator.Generate(root);+ var hasInner = generation.Candidates.Any(c =>+ c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool+ && c.SourceSurface.Family == SurfacePatchFamily.Planar+ && c.RetainedRegionLoops.Any(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null && l.Status == RetainedRegionLoopStatus.ExactReady));+ if (hasInner) Assert.Contains(result.Entries, e => e.IdentityMap is not null && e.IdentityMap.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim));+ }+[Fact]public void CylindricalSurfaceMaterializer_BoxMinusCylinder_ToolWall_FromRealEvidence_EmitsTopology(){@@ -340,6 +375,30 @@ public sealed class SurfacePatchDescriptorScaffoldTestsAssert.Contains(result.Diagnostics, d => d.Contains("not cylindrical", StringComparison.OrdinalIgnoreCase));}+ [Fact]+ public void EmittedIdentity_CylindricalWall_CarriesBoundaryTokensOrPreciseDiagnostics()+ {+ var candidate = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)))+ .Candidates.Single(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);+ var result = new CylindricalSurfaceMaterializer().EmitRetainedWall(new(candidate, readiness));+ var entries = result.IdentityMap!.Entries;+ Assert.Contains(entries, e => e.Role == EmittedTopologyRole.CylindricalTopBoundary);+ Assert.Contains(entries, e => e.Role == EmittedTopologyRole.CylindricalBottomBoundary);+ Assert.All(entries.Where(e => e.Role is EmittedTopologyRole.CylindricalTopBoundary or EmittedTopologyRole.CylindricalBottomBoundary),+ e => Assert.True(e.TrimIdentityToken is not null || e.Diagnostics.Any(d => d.Contains("missing", StringComparison.OrdinalIgnoreCase))));+ }++ [Fact]+ public void EmittedIdentity_CylindricalSeam_IsRoleTagged()+ {+ var candidate = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)))+ .Candidates.Single(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);+ var result = new CylindricalSurfaceMaterializer().EmitRetainedWall(new(candidate, readiness));+ Assert.Contains(result.IdentityMap!.Entries, e => e.Role == EmittedTopologyRole.CylindricalSeam && e.Kind == EmittedTopologyKind.Seam);+ }+[Fact]public void PlanarPayloadBuilder_RejectsNonPlanarSource(){diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.csindex aa18cadd..b03e426a 100644--- a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs@@ -21,6 +21,20 @@ internal static class SurfaceFamilyShellAssembler{_ = replayLog;var dryRun = ShellStitchingDryRunPlanner.Generate(root);+ var planarSet = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var generation = FacePatchCandidateGenerator.Generate(root);+ var cylindricalCandidate = generation.Candidates.SingleOrDefault(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);+ SurfaceMaterializationResult? cylindricalEmission = null;+ if (cylindricalCandidate is not null)+ {+ var synthReadiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0, 0, 0, 0, 0, 0, 0, [], false);+ cylindricalEmission = new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(cylindricalCandidate, synthReadiness));+ }+ var pairedTokens = TopologyPairingEvidenceGenerator.Generate(root).PlannedCoedgePairings+ .Where(p => p.PairingKind == PlannedCoedgePairingKind.SharedTrimIdentity)+ .Select(p => p.EdgeUseA.IdentityToken?.OrderingKey)+ .Where(t => !string.IsNullOrWhiteSpace(t))+ .ToHashSet(StringComparer.Ordinal);var diagnostics = new List<string>{"pattern: subtract(box,cylinder)",@@ -31,6 +45,17 @@ internal static class SurfaceFamilyShellAssemblervar hasCylinderPatch = dryRun.PlannedPatches.Any(p => p.SurfaceFamily == SurfacePatchFamily.Cylindrical);diagnostics.Add($"planar-patches-consumed: {planarPatchCount}");diagnostics.Add($"cylindrical-patch-consumed: {hasCylinderPatch}");+ var emittedEntries = planarSet.Entries.Where(e => e.Emitted).SelectMany(e => e.IdentityMap?.Entries ?? []).Concat(cylindricalEmission?.IdentityMap?.Entries ?? []).ToArray();+ diagnostics.Add(emittedEntries.Any(e => e.Role == EmittedTopologyRole.InnerCircularTrim && e.TrimIdentityToken is not null)+ ? "emitted-identity-planar-inner-circle-token-attached: planar emitted topology exposes inner-circle token."+ : "emitted-identity-planar-inner-circle-token-missing: planar emitted topology did not expose an inner-circle token.");+ diagnostics.Add(emittedEntries.Any(e => e.Role == EmittedTopologyRole.CylindricalSeam)+ ? "emitted-identity-cylindrical-seam-role-tagged: cylindrical seam metadata is available."+ : "emitted-identity-cylindrical-seam-role-missing: cylindrical seam metadata not found.");+ var matched = emittedEntries.Where(e => e.TrimIdentityToken is { } tok && pairedTokens.Contains(tok.OrderingKey)).ToArray();+ diagnostics.Add(matched.Length > 0+ ? $"emitted-identity-token-match-candidates: found {matched.Length} emitted topology candidate(s) matching dry-run shared trim identity tokens."+ : "emitted-identity-token-match-candidates-missing: no emitted topology entries matched dry-run shared trim identity tokens.");if (dryRun.Readiness != ShellClosureReadiness.ReadyForAssemblyEvidence){@@ -40,8 +65,7 @@ internal static class SurfaceFamilyShellAssembler}diagnostics.Add("readiness-gate-accepted: shell evidence is ready.");- diagnostics.Add("shell-assembly-blocked: emitted patch bodies do not currently provide stable cross-patch topology identity remap metadata required for deterministic merge-by-evidence.");- diagnostics.Add("next-blocker: add explicit emitted-edge identity mapping from InternalTrimIdentityToken -> patch-local edge/coedge ids.");+ diagnostics.Add("shell-assembly-blocked: identity metadata bridge is present, but topology merge/stitch execution is still intentionally unimplemented.");diagnostics.AddRange(dryRun.Diagnostics);return new(false, null, CirBrepMaterializer.BoxMinusCylinderPattern, dryRun.Readiness, false, planarPatchCount, hasCylinderPatch, diagnostics);diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.csindex 93d1a4dd..5872b733 100644--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs@@ -165,6 +165,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializerFacePatchCandidate Candidate,SurfaceMaterializationResult? Emission,bool Emitted,+ EmittedTopologyIdentityMap? IdentityMap,IReadOnlyList<string> Diagnostics);internal sealed record PlanarPatchSetMaterializationResult(@@ -306,19 +307,19 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer{if (candidate.RetentionRole != FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-candidate: retention role is not base-boundary retained outside tool."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-candidate: retention role is not base-boundary retained outside tool."]));continue;}if (candidate.SourceSurface.Family != SurfacePatchFamily.Planar){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-non-planar-candidate: planar patch set emitter supports planar family only."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-non-planar-candidate: planar patch set emitter supports planar family only."]));continue;}if (candidate.Readiness is FacePatchCandidateReadiness.RetentionDeferred or FacePatchCandidateReadiness.TrimDeferred or FacePatchCandidateReadiness.Unsupported){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, [$"skipped-candidate-readiness: {candidate.Readiness}."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-candidate-readiness: {candidate.Readiness}."]));continue;}@@ -332,13 +333,13 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer{if (candidate.SourceSurface.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle }){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required."]));continue;}if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var rectanglePayload, out var payloadDiagnostic)){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, [$"skipped-missing-rectangular-geometry: {payloadDiagnostic}"]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-missing-rectangular-geometry: {payloadDiagnostic}"]));continue;}@@ -347,25 +348,25 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializeremission = Emit(normalizedPatch, readiness);if (!emission.Success){- entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.Diagnostics));+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, emission.Diagnostics));continue;}emittedBodies.Add(emission.Body!);- entries.Add(new PlanarPatchSetEntry(candidate, emission, true, ["emitted-untrimmed-planar-patch: retained planar rectangle emitted without inner loops."]));+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, ["emitted-untrimmed-planar-patch: retained planar rectangle emitted without inner loops."]));continue;}if (retainedCircles.Length > 1){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-multiple-inner-loops: multiple retained circular loops are unsupported in CIR-F10.8."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-multiple-inner-loops: multiple retained circular loops are unsupported in CIR-F10.8."]));continue;}var normalizedTrimmedSource = candidate.SourceSurface;if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var trimmedPayload, out _)){- entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch."]));+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch."]));continue;}@@ -373,12 +374,12 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializeremission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, retainedCircles[0], null, readiness));if (!emission.Success){- entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.Diagnostics));+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, emission.Diagnostics));continue;}emittedBodies.Add(emission.Body!);- entries.Add(new PlanarPatchSetEntry(candidate, emission, true, ["emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop."]));+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, ["emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop."]));}var emittedCount = entries.Count(e => e.Emitted);@@ -432,13 +433,23 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializerfor (var i = 0; i < 4; i++) bindings.AddEdgeBinding(new EdgeGeometryBinding(e[i], new CurveGeometryId(i + 1), new ParameterInterval(0d, 1d)));bindings.AddEdgeBinding(new EdgeGeometryBinding(e[4], new CurveGeometryId(5), new ParameterInterval(0d, 2d * double.Pi)));bindings.AddFaceBinding(new FaceGeometryBinding(face, new SurfaceGeometryId(1)));+ InternalTrimIdentityToken? innerToken = string.IsNullOrWhiteSpace(inner.OrderingToken)+ ? (InternalTrimIdentityToken?)null+ : new InternalTrimIdentityToken("emitted:planar", inner.OrderingToken, inner.OrderingToken, TrimCurveFamily.Circle, "inner-trim", $"planar-inner:{inner.OrderingToken}");+ var identityEntries = new List<EmittedTopologyIdentityEntry>+ {+ new($"loop:{outerLoopId.Value}", EmittedTopologyKind.Loop, null, EmittedTopologyRole.OuterBoundary, "follow-face-boundary", ["outer boundary intentionally unmapped/internal-only."]),+ new($"edge:{e[4].Value}", EmittedTopologyKind.Edge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; token not fabricated." : "inner circular trim token attached from retained loop evidence."]),+ new($"coedge:{innerCoedgeId.Value}", EmittedTopologyKind.Coedge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; coedge left unmapped." : "inner circular trim token attached on emitted coedge."]),+ new($"loop:{innerLoopId.Value}", EmittedTopologyKind.Loop, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; loop identity recorded without token." : "inner circular trim token attached on emitted inner loop."])+ };return new(true, new BrepBody(builder.Model, geometry, bindings), SurfacePatchFamily.Planar, true,["inner-loop-emitted: one circular inner loop emitted from canonical retained loop geometry.","orientation-policy-applied: inner loop coedge orientation follows face-bound convention for cavity loops.","topology-emitted: planar trimmed face emitted as one face with outer rectangle then inner circle.","scope-note: full shell/solid assembly not attempted."- ]);+ ], new EmittedTopologyIdentityMap(identityEntries));}private static SurfaceMaterializationResult EmitRectangleBody(IReadOnlyList<Point3D> p)@@ -628,8 +639,42 @@ internal sealed record SurfaceMaterializationResult(BrepBody? Body,SurfacePatchFamily EmittedSurfaceFamily,bool TopologyEmissionImplemented,+ IReadOnlyList<string> Diagnostics,+ EmittedTopologyIdentityMap? IdentityMap = null);++internal enum EmittedTopologyKind+{+ Edge,+ Coedge,+ Loop,+ Face,+ Seam+}++internal enum EmittedTopologyRole+{+ OuterBoundary,+ InnerCircularTrim,+ CylindricalTopBoundary,+ CylindricalBottomBoundary,+ CylindricalSeam,+ Unmapped+}++internal sealed record EmittedTopologyIdentityEntry(+ string LocalTopologyKey,+ EmittedTopologyKind Kind,+ InternalTrimIdentityToken? TrimIdentityToken,+ EmittedTopologyRole Role,+ string OrientationPolicy,IReadOnlyList<string> Diagnostics);+internal sealed record EmittedTopologyIdentityMap(+ IReadOnlyList<EmittedTopologyIdentityEntry> Entries)+{+ internal static readonly EmittedTopologyIdentityMap Empty = new([]);+}+internal sealed class CylindricalSurfaceMaterializer : ISurfaceFamilyMaterializer{internal sealed record RetainedWallEmissionRequest(@@ -737,12 +782,27 @@ internal sealed class CylindricalSurfaceMaterializer : ISurfaceFamilyMaterialize{return new(false, null, SurfacePatchFamily.Cylindrical, false, ["cylindrical-wall-emission-failed: emitted cylindrical wall topology failed BRep binding validation."]);}+ InternalTrimIdentityToken? topToken = null;+ InternalTrimIdentityToken? bottomToken = null;+ foreach (var loop in mouthLoops)+ {+ if (loop.CircularGeometry is not { } circular || string.IsNullOrWhiteSpace(circular.OrderingToken)) continue;+ var token = new InternalTrimIdentityToken("emitted:cylindrical", circular.OrderingToken, circular.OrderingToken, TrimCurveFamily.Circle, loop.LoopKind.ToString(), $"cyl-loop:{circular.OrderingToken}");+ if (circular.OrientationPolicy == RetainedRegionLoopOrientationPolicy.UseCandidateOrientation) topToken ??= token;+ else bottomToken ??= token;+ }+ var cylIdentity = new EmittedTopologyIdentityMap(+ [+ new($"edge:{seamEdge.Value}", EmittedTopologyKind.Seam, null, EmittedTopologyRole.CylindricalSeam, "self-closure-forward-reverse", ["cylindrical seam role tagged for self-closure evidence."]),+ new($"edge:{topCircleEdge.Value}", EmittedTopologyKind.Edge, topToken, EmittedTopologyRole.CylindricalTopBoundary, "follow-mouth-loop", [topToken is null ? "cylindrical top boundary token missing or ambiguous in retained loop evidence." : "cylindrical top boundary token attached from retained loop evidence."]),+ new($"edge:{bottomCircleEdge.Value}", EmittedTopologyKind.Edge, bottomToken, EmittedTopologyRole.CylindricalBottomBoundary, "follow-mouth-loop", [bottomToken is null ? "cylindrical bottom boundary token missing or ambiguous in retained loop evidence." : "cylindrical bottom boundary token attached from retained loop evidence."])+ ]);return new(true, body, SurfacePatchFamily.Cylindrical, true,["cylindrical-wall-emitted: retained cylindrical wall patch emitted as one cylindrical face.","seam-convention-applied: side face uses cylinder primitive seam strategy (one seam edge used forward/reversed).","scope-note: full shell/solid assembly not attempted."- ]);+ ], cylIdentity);}private static Direction3D BuildReferenceAxis(Direction3D normal)diff --git a/docs/cir-f15-emitted-topology-identity-map.md b/docs/cir-f15-emitted-topology-identity-map.mdnew file mode 100644index 00000000..597cee07--- /dev/null+++ b/docs/cir-f15-emitted-topology-identity-map.md@@ -0,0 +1,37 @@+# CIR-F15: emitted topology identity map bridge++## Why this metadata exists++CIR-F14 proved dry-run pairing evidence can match boundaries via `InternalTrimIdentityToken`, but emitted patch topology had no deterministic mapping back to those tokens. CIR-F15 adds internal emitted-topology identity metadata so later shell stitching can map emitted edges/coedges/loops back to pairing evidence without introducing public topology naming.++## Model++`EmittedTopologyIdentityMap` and `EmittedTopologyIdentityEntry` are internal/test-facing only. Entries carry:++- stable patch-local key (`edge:<id>`, `coedge:<id>`, `loop:<id>`)+- kind (`Edge`, `Coedge`, `Loop`, `Seam`, `Face`)+- optional `InternalTrimIdentityToken`+- role (`InnerCircularTrim`, `CylindricalTopBoundary`, `CylindricalBottomBoundary`, `CylindricalSeam`, `OuterBoundary`, `Unmapped`)+- orientation policy and diagnostics++## SEM-A0 boundary++This bridge is diagnostic identity only. It does **not** expose Firmament selectors, public topology names, PMI topology references, merge behavior, or STEP behavior changes.++## Behavior++- Planar `EmitRectangleWithInnerCircle` attaches an internal identity token to emitted inner circular edge/coedge/loop metadata when retained loop token evidence exists.+- Planar outer rectangle boundaries are intentionally tagged as unmapped/internal-only.+- Cylindrical retained wall emission tags seam role metadata and attaches top/bottom boundary token metadata when loop evidence can be mapped; missing/ambiguous mappings emit explicit diagnostics.+- Planar patch-set results propagate per-entry emitted identity metadata.+- Shell assembler diagnostics now report whether token-attached emitted candidates are visible and token-match candidates exist, while keeping assembly blocked.++## Remaining work before stitching++- deterministic remap alignment against dry-run `PlannedEdgeUse`/`PlannedCoedgePairing` ordering keys+- tie-break policy when multiple emitted entries could satisfy one token+- actual shell stitch/merge execution (future milestone)++## Recommended next step++CIR-F16 should consume `EmittedTopologyIdentityMap` entries in a bounded stitch candidate resolver that maps dry-run planned pairs to concrete emitted coedge pairs, with deterministic ambiguity rejection diagnostics.