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.csnew file mode 100644index 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.csindex 7e6b96a2..ffce36ae 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs@@ -51,6 +51,7 @@ public sealed class SurfaceFamilyShellAssemblerTestsAssert.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.csnew file mode 100644index 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.csindex 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.mdnew file mode 100644index 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.