Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-BREP-S0 stitch candidate planner and tests
Yuechen Li0efc8b205473
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchCandidatePlannerTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchCandidatePlannerTests.csnew file mode 100644index 00000000..0f4d2b35--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchCandidatePlannerTests.cs@@ -0,0 +1,93 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class SurfaceFamilyStitchCandidatePlannerTests+{+ [Fact]+ public void StitchCandidate_BoxCylinder_GeneratesCandidateFromSafeTokenPair()+ {+ var result = SurfaceFamilyStitchCandidatePlanner.PlanBoxCylinder(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));+ Assert.True(result.Candidates.Count > 0 || result.Diagnostics.Any(d => d.Contains("missing-mate", StringComparison.OrdinalIgnoreCase) || d.Contains("ambiguous", StringComparison.OrdinalIgnoreCase) || d.Contains("incompatible", StringComparison.OrdinalIgnoreCase) || d.Contains("unmapped", StringComparison.OrdinalIgnoreCase)));+ }++ [Fact]+ public void StitchCandidate_SafePairEntriesAreCarried()+ {+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");+ var a = new EmittedTopologyIdentityEntry("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", []);+ var b = new EmittedTopologyIdentityEntry("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []);+ var map = new EmittedTopologyIdentityMap([a, b]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze([map]);++ var result = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, null);+ var candidate = Assert.Single(result.Candidates);+ Assert.Equal(token, candidate.Token);+ Assert.Equal(a, candidate.EntryA);+ Assert.Equal(b, candidate.EntryB);+ }++ [Fact]+ public void StitchCandidate_MissingMate_DoesNotGenerateCandidate()+ {+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");+ var map = new EmittedTopologyIdentityMap([new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", [])]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze([map]);+ var result = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, null);+ Assert.Empty(result.Candidates);+ Assert.Contains(result.Diagnostics, d => d.Contains("missing-mate", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void StitchCandidate_AmbiguousMultiplicity_DoesNotGenerateCandidate()+ {+ 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", []),+ new("edge:3", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalBottomBoundary, "o", [])]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze([map]);+ var result = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, null);+ Assert.Empty(result.Candidates);+ Assert.Contains(result.Diagnostics, d => d.Contains("ambiguous", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void StitchCandidate_OrientationMissingDefers()+ {+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");+ var a = new EmittedTopologyIdentityEntry("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", []);+ var b = new EmittedTopologyIdentityEntry("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []);+ var map = new EmittedTopologyIdentityMap([a, b]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze([map]);+ var shell = new ShellStitchingDryRunResult(false, ShellClosureReadiness.Deferred, [], [], [], [+ new OrientationCompatibilityEvidence("k1", OrientationCompatibilityStatus.Deferred, ShellClosureReadiness.Deferred, "orientation-missing", ["orientation-missing"])+ ], [], [], false);+ var result = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, shell);+ var candidate = Assert.Single(result.Candidates);+ Assert.Equal(SurfaceFamilyStitchCandidateReadiness.Deferred, candidate.Readiness);+ Assert.Contains(result.Diagnostics, d => d.Contains("orientation-deferred", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void StitchCandidate_DeterministicOrdering()+ {+ var token = new InternalTrimIdentityToken("op", "a", "b", TrimCurveFamily.Circle, "inner", "k1");+ var map = new EmittedTopologyIdentityMap([+ new("edge:2", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalTopBoundary, "o", []),+ new("edge:1", EmittedTopologyKind.Edge, token, EmittedTopologyRole.InnerCircularTrim, "o", [])]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze([map]);++ var first = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, null);+ var second = SurfaceFamilyStitchCandidatePlanner.Plan([map], analysis, null);+ Assert.Equal(first.Candidates.Select(c => c.OrderingKey), second.Candidates.Select(c => c.OrderingKey));+ }++ [Fact]+ public void StitchCandidate_NoExecution()+ {+ var result = SurfaceFamilyStitchCandidatePlanner.PlanBoxCylinder(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));+ Assert.False(result.StitchExecutionImplemented);+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchCandidatePlanner.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchCandidatePlanner.csnew file mode 100644index 00000000..946492e1--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchCandidatePlanner.cs@@ -0,0 +1,147 @@+using Aetheris.Kernel.Core.Cir;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum SurfaceFamilyStitchCandidateReadiness { Ready, Deferred, Unsupported, Ambiguous }+internal enum SurfaceFamilyStitchCandidateKind { SharedTrimIdentity, CylindricalSelfSeam, Deferred, Unsupported }++internal sealed record SurfaceFamilyStitchCandidate(+ string CandidateId,+ SurfaceFamilyStitchCandidateKind Kind,+ SurfaceFamilyStitchCandidateReadiness Readiness,+ InternalTrimIdentityToken? Token,+ EmittedTopologyIdentityEntry? EntryA,+ EmittedTopologyIdentityEntry? EntryB,+ string OrientationPolicy,+ IReadOnlyList<string> Diagnostics,+ string OrderingKey);++internal sealed record SurfaceFamilyStitchPlanResult(+ bool Success,+ IReadOnlyList<SurfaceFamilyStitchCandidate> Candidates,+ IReadOnlyList<string> DeferredItems,+ IReadOnlyList<string> AmbiguousItems,+ IReadOnlyList<string> Diagnostics,+ bool StitchExecutionImplemented);++internal static class SurfaceFamilyStitchCandidatePlanner+{+ internal static SurfaceFamilyStitchPlanResult Plan(+ IEnumerable<EmittedTopologyIdentityMap> identityMaps,+ EmittedTokenPairingAnalysisResult tokenAnalysis,+ ShellStitchingDryRunResult? shellEvidence = null)+ {+ _ = identityMaps?.ToArray(); // explicit consumed input; planner does not rematerialize+ var diagnostics = new List<string>();+ var candidates = new List<SurfaceFamilyStitchCandidate>();+ var deferred = new List<string>();+ var ambiguous = new List<string>();++ foreach (var pair in tokenAnalysis.SafePairs.OrderBy(p => p.TokenOrderingKey, StringComparer.Ordinal))+ {+ var orientation = shellEvidence?.OrientationEvidence.FirstOrDefault(e => string.Equals(e.PairKey, pair.TokenOrderingKey, StringComparison.Ordinal));+ var readiness = SurfaceFamilyStitchCandidateReadiness.Deferred;+ var orientationPolicy = "orientation-missing";+ var entryRoles = new[] { pair.EntryA.Role, pair.EntryB.Role };++ if (orientation is not null)+ {+ if (orientation.OrientationStatus == OrientationCompatibilityStatus.Compatible)+ {+ readiness = SurfaceFamilyStitchCandidateReadiness.Ready;+ orientationPolicy = "orientation-compatible";+ diagnostics.Add($"orientation-compatible: token={pair.TokenOrderingKey} supports ready stitch candidate.");+ }+ else+ {+ readiness = SurfaceFamilyStitchCandidateReadiness.Deferred;+ orientationPolicy = $"orientation-{orientation.OrientationStatus.ToString().ToLowerInvariant()}";+ diagnostics.Add($"orientation-deferred: token={pair.TokenOrderingKey} has status {orientation.OrientationStatus}.");+ }+ }+ else if (entryRoles.Contains(EmittedTopologyRole.InnerCircularTrim)+ && (entryRoles.Contains(EmittedTopologyRole.CylindricalTopBoundary) || entryRoles.Contains(EmittedTopologyRole.CylindricalBottomBoundary)))+ {+ readiness = SurfaceFamilyStitchCandidateReadiness.Ready;+ orientationPolicy = "orientation-convention-safe";+ diagnostics.Add($"orientation-compatible: token={pair.TokenOrderingKey} accepted by planar/cylindrical role convention.");+ }+ else+ {+ diagnostics.Add($"orientation-missing-deferred: token={pair.TokenOrderingKey} has no orientation evidence.");+ }++ var orderingKey = $"token:{pair.TokenOrderingKey}|{pair.EntryA.LocalTopologyKey}|{pair.EntryB.LocalTopologyKey}|SharedTrimIdentity";+ candidates.Add(new SurfaceFamilyStitchCandidate(+ CandidateId: $"candidate:{pair.TokenOrderingKey}",+ Kind: SurfaceFamilyStitchCandidateKind.SharedTrimIdentity,+ Readiness: readiness,+ Token: pair.EntryA.TrimIdentityToken,+ EntryA: pair.EntryA,+ EntryB: pair.EntryB,+ OrientationPolicy: orientationPolicy,+ Diagnostics: pair.Diagnostics.Concat(["safe-pair-converted-to-stitch-candidate"]).ToArray(),+ OrderingKey: orderingKey));+ diagnostics.Add($"safe-pair-converted-to-stitch-candidate: token={pair.TokenOrderingKey}.");+ }++ foreach (var g in tokenAnalysis.MissingMateGroups)+ {+ deferred.Add($"missing-mate-deferred:{g.TokenOrderingKey}");+ diagnostics.Add($"missing-mate-ignored-deferred: token={g.TokenOrderingKey}.");+ }++ foreach (var g in tokenAnalysis.AmbiguousGroups)+ {+ ambiguous.Add($"ambiguous-multiplicity-deferred:{g.TokenOrderingKey}");+ diagnostics.Add($"ambiguous-multiplicity-ignored-deferred: token={g.TokenOrderingKey}.");+ }++ if (tokenAnalysis.Diagnostics.Any(d => d.Contains("incompatible-roles", StringComparison.OrdinalIgnoreCase)))+ {+ diagnostics.Add("incompatible-roles-ignored-deferred: no stitch candidate created for incompatible role groups.");+ }++ if (shellEvidence is not null)+ {+ foreach (var seam in shellEvidence.SeamClosureEvidence.Where(s => s.SeamKind is SeamKind.CylindricalSelfSeam or SeamKind.SeamDeferred))+ {+ diagnostics.Add(seam.SeamKind == SeamKind.CylindricalSelfSeam+ ? $"seam-accounted: patch={seam.PatchKey} cylindrical self seam evidence exists."+ : $"seam-deferred: patch={seam.PatchKey} cylindrical seam metadata missing/deferred.");+ }+ }++ diagnostics.Add("stitch-execution-not-implemented: planner emits candidates only; no topology mutation or merge executed.");++ return new SurfaceFamilyStitchPlanResult(+ Success: candidates.Count > 0,+ Candidates: candidates.OrderBy(c => c.OrderingKey, StringComparer.Ordinal).ToArray(),+ DeferredItems: deferred.OrderBy(x => x, StringComparer.Ordinal).ToArray(),+ AmbiguousItems: ambiguous.OrderBy(x => x, StringComparer.Ordinal).ToArray(),+ Diagnostics: diagnostics.Distinct().OrderBy(x => x, StringComparer.Ordinal).ToArray(),+ StitchExecutionImplemented: false);+ }++ internal static SurfaceFamilyStitchPlanResult PlanBoxCylinder(CirNode root)+ {+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var gen = FacePatchCandidateGenerator.Generate(root);+ var cylCandidate = gen.Candidates.SingleOrDefault(c =>+ c.SourceSurface.Family == SurfacePatchFamily.Cylindrical+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);++ SurfaceMaterializationResult? cyl = null;+ if (cylCandidate is not null)+ {+ var ready = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0, 0, 0, 0, 0, 0, 0, [], false);+ cyl = new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(cylCandidate, ready));+ }++ var maps = planar.Entries.Where(e => e.Emitted).Select(e => e.IdentityMap ?? EmittedTopologyIdentityMap.Empty)+ .Concat(cyl?.IdentityMap is null ? [] : [cyl.IdentityMap]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze(maps);+ var shell = ShellStitchingDryRunPlanner.Generate(root);+ return Plan(maps, analysis, shell);+ }+}diff --git a/docs/cir-brep-s0-stitch-candidate-generation.md b/docs/cir-brep-s0-stitch-candidate-generation.mdnew file mode 100644index 00000000..012ee2ba--- /dev/null+++ b/docs/cir-brep-s0-stitch-candidate-generation.md@@ -0,0 +1,42 @@+# CIR-BREP-S0: stitch candidate generation from emitted topology identity maps++## Purpose++CIR-BREP-S0 adds deterministic, diagnostic-first stitch-candidate planning from emitted identity maps and CIR-F16 token-pairing analysis. It does **not** stitch or merge topology.++## Inputs++- `EmittedTopologyIdentityMap` entries from:+ - `PlanarSurfaceMaterializer.EmitSupportedPlanarPatches(...)`+ - `CylindricalSurfaceMaterializer.EmitRetainedWall(...)`+- `EmittedTokenPairingAnalysisResult` from CIR-F16.+- Optional `ShellStitchingDryRunResult` for seam/orientation evidence.++## Safe-pair policy++Only CIR-F16 `SafePairs` become `SurfaceFamilyStitchCandidate` entries (`SharedTrimIdentity` kind). Candidate carries both emitted entries and token.++## Missing / ambiguous behavior++- Missing mate groups are deferred diagnostics only.+- Ambiguous multiplicity groups are deferred diagnostics only.+- Incompatible role groups are deferred; no arbitrary pairing/selection.++## Orientation policy++- If dry-run orientation says compatible, candidate is `Ready`.+- If orientation evidence is absent, candidate can be accepted by existing planar-inner/cylindrical-boundary convention; otherwise deferred.+- Incompatible/deferred orientation remains deferred with explicit diagnostics.++## Seam policy++Seam evidence from dry-run is surfaced as diagnostics (`seam-accounted` or `seam-deferred`). No seam mutation occurs.++## Execution boundary++`SurfaceFamilyStitchPlanResult.StitchExecutionImplemented` is always `false` in CIR-BREP-S0.+No coedge mutation, edge merge, shell/body assembly, STEP behavior changes, or Boolean behavior changes are introduced.++## Next step++CIR-BREP-T3 can consume ordered stitch candidates and deferred blockers to implement bounded topology merge execution behind explicit admissibility gates.