Skip to content

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.cs
index 7f061ce5..a7061e92 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
@@ -42,4 +42,22 @@ public sealed class SurfaceFamilyShellAssemblerTests
Assert.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.cs
index 520c21ef..ec407731 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -284,6 +284,41 @@ public sealed class SurfacePatchDescriptorScaffoldTests
Assert.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 SurfacePatchDescriptorScaffoldTests
Assert.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.cs
index 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 SurfaceFamilyShellAssembler
var 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.cs
index 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 : ISurfaceFamilyMaterializer
FacePatchCandidate 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 : ISurfaceFamilyMaterializer
emission = 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 : ISurfaceFamilyMaterializer
emission = 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 : ISurfaceFamilyMaterializer
for (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.md
new file mode 100644
index 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.