Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F16 emitted token pairing diagnostics analysis

Yuechen Lic4b5fa160bd5
diff --git a/Aetheris.Kernel.Firmament.Tests/EmittedTokenPairingAnalyzerTests.cs b/Aetheris.Kernel.Firmament.Tests/EmittedTokenPairingAnalyzerTests.cs
new file mode 100644
index 00000000..a70c44b2
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/EmittedTokenPairingAnalyzerTests.cs
@@ -0,0 +1,87 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class EmittedTokenPairingAnalyzerTests
+{
+ [Fact]
+ public void TokenPairingAnalyzer_ExactlyTwoCompatibleEntries_AreSafePair()
+ {
+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");
+ var map = new EmittedTopologyIdentityMap([
+ new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", []),
+ new("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", [])]);
+
+ var result = EmittedTokenPairingAnalyzer.Analyze([map]);
+ Assert.Single(result.SafePairs);
+ Assert.Equal(TokenPairingStatus.SafePair, result.SafePairs[0].Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("token-safe-pair", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void TokenPairingAnalyzer_SingleEntry_IsMissingMate()
+ {
+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");
+ var result = EmittedTokenPairingAnalyzer.Analyze([
+ new EmittedTopologyIdentityMap([new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", [])])]);
+ Assert.Single(result.MissingMateGroups);
+ Assert.Empty(result.SafePairs);
+ }
+
+ [Fact]
+ public void TokenPairingAnalyzer_MoreThanTwoEntries_IsAmbiguous()
+ {
+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");
+ var result = EmittedTokenPairingAnalyzer.Analyze([
+ new EmittedTopologyIdentityMap([
+ new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", []),
+ new("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []),
+ new("edge:3", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalBottomBoundary, "o", [])])]);
+ Assert.Single(result.AmbiguousGroups);
+ Assert.Empty(result.SafePairs);
+ }
+
+ [Fact]
+ public void TokenPairingAnalyzer_IncompatibleRoles_NotSafe()
+ {
+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");
+ var result = EmittedTokenPairingAnalyzer.Analyze([
+ new EmittedTopologyIdentityMap([
+ new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []),
+ new("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalBottomBoundary, "o", [])])]);
+ Assert.Empty(result.SafePairs);
+ Assert.Contains(result.Diagnostics, d => d.Contains("incompatible-roles", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void TokenPairingAnalyzer_RealBoxCylinderPath_ReportsSafeOrPreciseMissing()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ var gen = FacePatchCandidateGenerator.Generate(root);
+ var cylCandidate = gen.Candidates.First(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
+ var ready = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0,0,0,0,0,0,0,[],false);
+ var cyl = new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(cylCandidate, ready));
+
+ var result = EmittedTokenPairingAnalyzer.Analyze(planar.Entries.Where(e => e.Emitted).Select(e => e.IdentityMap ?? EmittedTopologyIdentityMap.Empty).Concat(cyl.IdentityMap is null ? [] : [cyl.IdentityMap]));
+
+ Assert.True(result.SafePairs.Count > 0 || result.MissingMateGroups.Count > 0 || result.NullTokenEntries.Count > 0);
+ if (result.SafePairs.Count == 0)
+ Assert.Contains(result.Diagnostics, d => d.Contains("missing-mate", StringComparison.OrdinalIgnoreCase) || d.Contains("unmapped-entries", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void DeterministicOrdering()
+ {
+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");
+ var maps = new[] { new EmittedTopologyIdentityMap([
+ new("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []),
+ new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", [])])};
+
+ var first = EmittedTokenPairingAnalyzer.Analyze(maps);
+ var second = EmittedTokenPairingAnalyzer.Analyze(maps);
+ Assert.Equal(first.SafePairs.Select(x => x.TokenOrderingKey), second.SafePairs.Select(x => x.TokenOrderingKey));
+ Assert.Equal(first.Diagnostics, second.Diagnostics);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
index 7e6b96a2..ffce36ae 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
@@ -51,6 +51,7 @@ public sealed class SurfaceFamilyShellAssemblerTests
Assert.Contains(result.Diagnostics, d => d.Contains("planar-inner-circle-token", StringComparison.OrdinalIgnoreCase));
Assert.Contains(result.Diagnostics, d => d.Contains("cylindrical-seam-role-tagged", StringComparison.OrdinalIgnoreCase));
Assert.Contains(result.Diagnostics, d => d.Contains("token-match-candidates", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.Diagnostics, d => d.Contains("token-pairing-summary", StringComparison.OrdinalIgnoreCase));
Assert.False(result.FullShellAssembled);
}
diff --git a/Aetheris.Kernel.Firmament/Execution/EmittedTokenPairingAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/EmittedTokenPairingAnalyzer.cs
new file mode 100644
index 00000000..6ffea1c3
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/EmittedTokenPairingAnalyzer.cs
@@ -0,0 +1,118 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum TokenPairingStatus
+{
+ SafePair,
+ MissingMate,
+ AmbiguousMultiplicity,
+ NoToken,
+ Deferred,
+ Unsupported
+}
+
+internal sealed record EmittedTokenGroup(
+ string TokenOrderingKey,
+ IReadOnlyList<EmittedTopologyIdentityEntry> Entries,
+ TokenPairingStatus Status,
+ string OrderingKey,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record EmittedTokenPairCandidate(
+ string TokenOrderingKey,
+ EmittedTopologyIdentityEntry EntryA,
+ EmittedTopologyIdentityEntry EntryB,
+ TokenPairingStatus Status,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record EmittedTokenPairingAnalysisResult(
+ IReadOnlyList<EmittedTokenPairCandidate> SafePairs,
+ IReadOnlyList<EmittedTokenGroup> MissingMateGroups,
+ IReadOnlyList<EmittedTokenGroup> AmbiguousGroups,
+ IReadOnlyList<EmittedTopologyIdentityEntry> NullTokenEntries,
+ IReadOnlyList<string> Diagnostics,
+ ShellClosureReadiness Readiness);
+
+internal static class EmittedTokenPairingAnalyzer
+{
+ internal static EmittedTokenPairingAnalysisResult Analyze(IEnumerable<EmittedTopologyIdentityMap> identityMaps)
+ {
+ var allEntries = identityMaps.Where(m => m is not null).SelectMany(m => m.Entries ?? []).OrderBy(BuildEntryOrderingKey, StringComparer.Ordinal).ToArray();
+ var diagnostics = new List<string> { "token-pairing-analysis-started: emitted identity entries grouped by InternalTrimIdentityToken ordering key." };
+
+ var nullTokenEntries = allEntries.Where(e => e.TrimIdentityToken is null).ToArray();
+ if (nullTokenEntries.Length > 0)
+ {
+ diagnostics.Add($"token-pairing-unmapped-entries: {nullTokenEntries.Length} emitted entries have null token and are excluded from pairing.");
+ }
+
+ var safePairs = new List<EmittedTokenPairCandidate>();
+ var missing = new List<EmittedTokenGroup>();
+ var ambiguous = new List<EmittedTokenGroup>();
+
+ var tokenGroups = allEntries
+ .Where(e => e.TrimIdentityToken is not null)
+ .GroupBy(e => e.TrimIdentityToken!.Value.OrderingKey, StringComparer.Ordinal)
+ .OrderBy(g => g.Key, StringComparer.Ordinal);
+
+ foreach (var group in tokenGroups)
+ {
+ var entries = group.OrderBy(BuildEntryOrderingKey, StringComparer.Ordinal).ToArray();
+ var orderingKey = $"token:{group.Key}";
+
+ if (entries.Length == 1)
+ {
+ var d = $"token-missing-mate: token={group.Key} appears once; missing opposite emitted boundary evidence.";
+ diagnostics.Add(d);
+ missing.Add(new EmittedTokenGroup(group.Key, entries, TokenPairingStatus.MissingMate, orderingKey, [d]));
+ continue;
+ }
+
+ if (entries.Length > 2)
+ {
+ var d = $"token-ambiguous-multiplicity: token={group.Key} appears {entries.Length} times; arbitrary pairing is forbidden.";
+ diagnostics.Add(d);
+ ambiguous.Add(new EmittedTokenGroup(group.Key, entries, TokenPairingStatus.AmbiguousMultiplicity, orderingKey, [d]));
+ continue;
+ }
+
+ var compatibility = AreRolesCompatible(entries[0].Role, entries[1].Role);
+ if (!compatibility.compatible)
+ {
+ var d = $"token-incompatible-roles: token={group.Key} has role pair ({entries[0].Role},{entries[1].Role}) not admissible for safe boundary pairing evidence.";
+ diagnostics.Add(d);
+ missing.Add(new EmittedTokenGroup(group.Key, entries, TokenPairingStatus.Deferred, orderingKey, [d]));
+ continue;
+ }
+
+ var safeDiagnostic = $"token-safe-pair: token={group.Key} forms deterministic compatible pair ({entries[0].Role},{entries[1].Role}).";
+ diagnostics.Add(safeDiagnostic);
+ safePairs.Add(new EmittedTokenPairCandidate(group.Key, entries[0], entries[1], TokenPairingStatus.SafePair, [safeDiagnostic]));
+ }
+
+ var readiness = ambiguous.Count == 0 && missing.All(m => m.Status != TokenPairingStatus.Deferred) && missing.Count == 0
+ ? ShellClosureReadiness.ReadyForAssemblyEvidence
+ : ShellClosureReadiness.Deferred;
+ diagnostics.Add("shell-assembly-still-unimplemented: analysis only; no coedge mutation, edge merge, or shell stitching executed.");
+
+ return new EmittedTokenPairingAnalysisResult(
+ safePairs.OrderBy(p => p.TokenOrderingKey, StringComparer.Ordinal).ToArray(),
+ missing.OrderBy(m => m.OrderingKey, StringComparer.Ordinal).ToArray(),
+ ambiguous.OrderBy(a => a.OrderingKey, StringComparer.Ordinal).ToArray(),
+ nullTokenEntries,
+ diagnostics.Distinct().OrderBy(d => d, StringComparer.Ordinal).ToArray(),
+ readiness);
+ }
+
+ private static (bool compatible, TokenPairingStatus status) AreRolesCompatible(EmittedTopologyRole a, EmittedTopologyRole b)
+ {
+ var pair = new[] { a, b }.OrderBy(r => r.ToString(), StringComparer.Ordinal).ToArray();
+ var isPlanarCyl = pair[0] == EmittedTopologyRole.CylindricalBottomBoundary && pair[1] == EmittedTopologyRole.InnerCircularTrim
+ || pair[0] == EmittedTopologyRole.CylindricalTopBoundary && pair[1] == EmittedTopologyRole.InnerCircularTrim;
+ return isPlanarCyl ? (true, TokenPairingStatus.SafePair) : (false, TokenPairingStatus.Deferred);
+ }
+
+ private static string BuildEntryOrderingKey(EmittedTopologyIdentityEntry entry)
+ => $"{entry.LocalTopologyKey}|{entry.Kind}|{entry.Role}|{entry.OrientationPolicy}";
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs
index 9212e974..85c382f4 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs
@@ -61,6 +61,11 @@ internal static class SurfaceFamilyShellAssembler
? $"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.");
+ var tokenAnalysis = EmittedTokenPairingAnalyzer.Analyze(planarSet.Entries.Where(e => e.Emitted).Select(e => e.IdentityMap ?? EmittedTopologyIdentityMap.Empty)
+ .Concat(cylindricalEmission?.IdentityMap is null ? [] : [cylindricalEmission.IdentityMap]));
+ diagnostics.Add($"token-pairing-summary: safe-pairs={tokenAnalysis.SafePairs.Count}; missing-mates={tokenAnalysis.MissingMateGroups.Count}; ambiguous={tokenAnalysis.AmbiguousGroups.Count}; null-token-entries={tokenAnalysis.NullTokenEntries.Count}.");
+ diagnostics.AddRange(tokenAnalysis.Diagnostics.Take(8));
+
if (dryRun.Readiness != ShellClosureReadiness.ReadyForAssemblyEvidence)
{
diagnostics.Add("readiness-gate-rejected: no shell-readiness, no assembly.");
diff --git a/docs/cir-f16-emitted-token-pairing-analysis.md b/docs/cir-f16-emitted-token-pairing-analysis.md
new file mode 100644
index 00000000..473cc86e
--- /dev/null
+++ b/docs/cir-f16-emitted-token-pairing-analysis.md
@@ -0,0 +1,53 @@
+# CIR-F16 — Emitted token pairing analysis before stitching
+
+CIR-F16 adds a deterministic internal diagnostics layer over emitted topology identity metadata so future shell stitching can distinguish safe one-to-one token matches from missing, ambiguous, or incompatible cases.
+
+## Why this exists
+
+CIR-F15 bridged emitted topology to `InternalTrimIdentityToken`. CIR-F16 hardens that bridge by classifying multiplicity and compatibility before any stitch execution.
+
+## Multiplicity/status rules
+
+For each non-null token key:
+
+- exactly 2 entries + compatible roles → `SafePair`
+- exactly 1 entry → `MissingMate`
+- more than 2 entries → `AmbiguousMultiplicity`
+- exactly 2 entries with incompatible roles → deferred diagnostic (not safe)
+
+Entries with null token are not paired and are reported as unmapped/internal-only diagnostics.
+
+## Role compatibility (current bounded policy)
+
+Safe emitted-token pairing is currently accepted only for:
+
+- `InnerCircularTrim` + `CylindricalTopBoundary`, or
+- `InnerCircularTrim` + `CylindricalBottomBoundary`.
+
+Any other role pair remains deferred with explicit incompatibility diagnostics.
+
+## Canonical subtract(box,cylinder)
+
+The analyzer consumes emitted identity maps from:
+
+- `PlanarSurfaceMaterializer.EmitSupportedPlanarPatches(...)`
+- `CylindricalSurfaceMaterializer.EmitRetainedWall(...)`
+
+Expected result is either:
+
+- at least one `SafePair`, or
+- an exact `MissingMate` diagnostic with the token key.
+
+## SEM-A0 boundary
+
+CIR-F16 is evidence-only:
+
+- no shell merge,
+- no coedge mutation,
+- no edge merge,
+- no STEP/export behavior change,
+- no public topology naming.
+
+## Recommended next step
+
+Use `EmittedTokenPairingAnalysisResult` as the admissibility gate for future bounded stitch-candidate generation. Keep >2 multiplicity and incompatible roles as explicit deferred blockers unless a bounded disambiguation strategy is introduced.