Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.