Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.8 topology pairing and loop-closure dry-run evidence

Yuechen Li547285c6f6a6
diff --git a/Aetheris.Kernel.Firmament.Tests/TopologyPairingEvidenceTests.cs b/Aetheris.Kernel.Firmament.Tests/TopologyPairingEvidenceTests.cs
new file mode 100644
index 00000000..db76d6af
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/TopologyPairingEvidenceTests.cs
@@ -0,0 +1,69 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class TopologyPairingEvidenceTests
+{
+ [Fact]
+ public void PairingEvidence_BoxMinusCylinder_CreatesEdgeUses()
+ {
+ var result = TopologyPairingEvidenceGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+
+ Assert.True(result.IsSuccess);
+ Assert.NotEmpty(result.PlannedEdgeUses);
+ Assert.Contains(result.PlannedEdgeUses, e => e.SourceSurfaceFamily == SurfacePatchFamily.Planar && e.OppositeSurfaceFamily == SurfacePatchFamily.Cylindrical);
+ Assert.False(result.TopologyEmissionImplemented);
+ }
+
+ [Fact]
+ public void PairingEvidence_BoxMinusSphere_CircularLoopsHaveClosureEvidence()
+ {
+ var result = TopologyPairingEvidenceGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3)));
+
+ Assert.Contains(result.PlannedEdgeUses, e => e.TrimCurveFamily == TrimCurveFamily.Circle);
+ Assert.Contains(result.LoopClosureEvidence, c => c.ClosureStatus is LoopClosureStatus.ClosedByDescriptor or LoopClosureStatus.ClosureDeferred);
+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("generic unsupported", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PairingEvidence_BoxMinusTorus_DefersClosureAndPairing()
+ {
+ var result = TopologyPairingEvidenceGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1)));
+
+ Assert.Equal(TopologyPairingReadiness.Deferred, result.Readiness);
+ Assert.Contains(result.PlannedCoedgePairings, p => p.Readiness == TopologyPairingReadiness.Deferred);
+ Assert.Contains(result.Diagnostics, d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase) || d.Contains("deferred", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PairingEvidence_CoedgePairingDeferredWhenIdentityMissing()
+ {
+ var result = TopologyPairingEvidenceGenerator.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3)));
+
+ Assert.Contains(result.PlannedCoedgePairings, p => p.PairingKind == PlannedCoedgePairingKind.Deferred);
+ Assert.Contains(result.Diagnostics, d => d.Contains("missing one-to-one identity", StringComparison.OrdinalIgnoreCase) || d.Contains("missing-identity", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PairingEvidence_NonSubtract_NotApplicable()
+ {
+ var result = TopologyPairingEvidenceGenerator.Generate(new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2)));
+
+ Assert.False(result.IsSuccess);
+ Assert.Equal(TopologyPairingReadiness.NotApplicable, result.Readiness);
+ Assert.Empty(result.PlannedEdgeUses);
+ }
+
+ [Fact]
+ public void PairingEvidence_DeterministicOrdering()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var first = TopologyPairingEvidenceGenerator.Generate(root);
+ var second = TopologyPairingEvidenceGenerator.Generate(root);
+
+ Assert.Equal(first.PlannedEdgeUses.Select(x => x.OrderingKey), second.PlannedEdgeUses.Select(x => x.OrderingKey));
+ Assert.Equal(first.PlannedCoedgePairings.Select(x => x.OrderingKey), second.PlannedCoedgePairings.Select(x => x.OrderingKey));
+ Assert.Equal(first.LoopClosureEvidence.Select(x => x.OrderingKey), second.LoopClosureEvidence.Select(x => x.OrderingKey));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/TopologyPairingEvidenceDryRun.cs b/Aetheris.Kernel.Firmament/Execution/TopologyPairingEvidenceDryRun.cs
new file mode 100644
index 00000000..831094d8
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/TopologyPairingEvidenceDryRun.cs
@@ -0,0 +1,233 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum TopologyPairingReadiness
+{
+ NotApplicable,
+ ExactReady,
+ SpecialCaseReady,
+ Deferred,
+ Unsupported
+}
+
+internal enum PlannedCoedgePairingKind
+{
+ SharedTrimCurve,
+ SameSurfaceDeferred,
+ UnpairedBoundary,
+ Deferred,
+ Unsupported,
+ NotApplicable
+}
+
+internal enum LoopClosureStatus
+{
+ ClosedByDescriptor,
+ ClosureDeferred,
+ Unsupported,
+ NotApplicable
+}
+
+internal sealed record PlannedEdgeUse(
+ string SourceFaceKey,
+ string SourceLoopKey,
+ RetainedRegionLoopGroupKind SourceLoopKind,
+ SurfacePatchFamily SourceSurfaceFamily,
+ SurfacePatchFamily OppositeSurfaceFamily,
+ TrimCurveFamily TrimCurveFamily,
+ RetainedRegionLoopOrientationPolicy OrientationPolicy,
+ string OrderingKey,
+ TopologyPairingReadiness Readiness,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record PlannedCoedgePairing(
+ PlannedEdgeUse EdgeUseA,
+ PlannedEdgeUse EdgeUseB,
+ PlannedCoedgePairingKind PairingKind,
+ TopologyPairingReadiness Readiness,
+ string Evidence,
+ string OrderingKey,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record LoopClosureEvidence(
+ string SourceFaceKey,
+ string SourceLoopKey,
+ LoopClosureStatus ClosureStatus,
+ TopologyPairingReadiness Readiness,
+ string Evidence,
+ string OrderingKey,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record TopologyPairingEvidenceResult(
+ bool IsSuccess,
+ TopologyPairingReadiness Readiness,
+ IReadOnlyList<PlannedEdgeUse> PlannedEdgeUses,
+ IReadOnlyList<PlannedCoedgePairing> PlannedCoedgePairings,
+ IReadOnlyList<LoopClosureEvidence> LoopClosureEvidence,
+ IReadOnlyList<string> Diagnostics,
+ bool TopologyEmissionImplemented);
+
+internal static class TopologyPairingEvidenceGenerator
+{
+ internal static TopologyPairingEvidenceResult Generate(CirNode root) => Generate(TopologyAssemblyDryRunPlanner.Generate(root));
+
+ internal static TopologyPairingEvidenceResult Generate(TopologyAssemblyDryRunResult dryRun)
+ {
+ var diagnostics = new List<string>
+ {
+ "topology-emission-not-implemented: pairing evidence is dry-run only; no BRep edge/coedge/loop/face/vertex/shell entities are created."
+ };
+
+ if (!dryRun.PlannedFaces.Any() || dryRun.Readiness == TopologyAssemblyReadiness.NotApplicable)
+ {
+ diagnostics.Add("pairing-not-applicable: topology dry-run has no subtract planned faces for pairing/closure evidence.");
+ return new(false, TopologyPairingReadiness.NotApplicable, [], [], [], diagnostics, TopologyEmissionImplemented: false);
+ }
+
+ var edgeUses = BuildEdgeUses(dryRun.PlannedFaces, diagnostics);
+ var pairings = BuildPairings(edgeUses, dryRun.PlannedAdjacencies, diagnostics);
+ var closure = BuildClosureEvidence(dryRun.PlannedFaces, diagnostics);
+ var readiness = ReduceReadiness(edgeUses.Select(e => e.Readiness)
+ .Concat(pairings.Select(p => p.Readiness))
+ .Concat(closure.Select(c => c.Readiness))
+ .ToArray());
+
+ diagnostics.Add("judgment-engine-not-used: CIR-F8.8 pairing currently has deterministic single-candidate matching keyed by trim-family + complementary surface families + adjacency hints.");
+ return new(edgeUses.Count > 0, readiness, edgeUses, pairings, closure, diagnostics.Distinct().ToArray(), TopologyEmissionImplemented: false);
+ }
+
+ private static List<PlannedEdgeUse> BuildEdgeUses(IReadOnlyList<PlannedFacePatch> faces, List<string> diagnostics)
+ {
+ var list = new List<PlannedEdgeUse>();
+ foreach (var face in faces)
+ foreach (var loop in face.LoopGroups)
+ {
+ if (!loop.LoopDescriptors.Any())
+ {
+ diagnostics.Add($"edge-use-deferred: face={face.OrderingKey} loop={loop.OrderingKey} has no loop descriptors.");
+ continue;
+ }
+
+ foreach (var descriptor in loop.LoopDescriptors)
+ {
+ var readiness = MapStatus(descriptor.Status);
+ var key = $"{face.OrderingKey}|{loop.OrderingKey}|{descriptor.TrimCurveFamily}|{descriptor.SourceSurfaceFamily}|{descriptor.OppositeSurfaceFamily}|{descriptor.LoopKind}";
+ list.Add(new PlannedEdgeUse(face.OrderingKey, loop.OrderingKey, loop.GroupKind, descriptor.SourceSurfaceFamily, descriptor.OppositeSurfaceFamily, descriptor.TrimCurveFamily, loop.OrientationPolicy, key, readiness,
+ [$"edge-use-created: trim={descriptor.TrimCurveFamily} source={descriptor.SourceSurfaceFamily} opposite={descriptor.OppositeSurfaceFamily} orientation={loop.OrientationPolicy}.", descriptor.Diagnostic]));
+ }
+ }
+
+ return list.OrderBy(e => e.OrderingKey, StringComparer.Ordinal).ToList();
+ }
+
+ private static List<PlannedCoedgePairing> BuildPairings(IReadOnlyList<PlannedEdgeUse> edgeUses, IReadOnlyList<PlannedAdjacency> adjacencies, List<string> diagnostics)
+ {
+ var list = new List<PlannedCoedgePairing>();
+ var used = new HashSet<string>(StringComparer.Ordinal);
+ for (var i = 0; i < edgeUses.Count; i++)
+ {
+ var a = edgeUses[i];
+ if (used.Contains(a.OrderingKey)) continue;
+
+ var matches = edgeUses.Where((b, bi) => bi != i && !used.Contains(b.OrderingKey)
+ && b.TrimCurveFamily == a.TrimCurveFamily
+ && b.SourceSurfaceFamily == a.OppositeSurfaceFamily
+ && b.OppositeSurfaceFamily == a.SourceSurfaceFamily
+ && adjacencies.Any(adj => adj.TrimCurveFamily == a.TrimCurveFamily
+ && ((adj.SourceFaceA == a.SourceFaceKey && adj.SourceFaceB == b.SourceFaceKey) || (adj.SourceFaceA == b.SourceFaceKey && adj.SourceFaceB == a.SourceFaceKey))))
+ .OrderBy(b => b.OrderingKey, StringComparer.Ordinal)
+ .ToArray();
+
+ if (matches.Length == 1)
+ {
+ var b = matches[0];
+ used.Add(a.OrderingKey);
+ used.Add(b.OrderingKey);
+ var readiness = ReduceReadiness([a.Readiness, b.Readiness]);
+ var key = $"{a.OrderingKey}<->{b.OrderingKey}";
+ list.Add(new PlannedCoedgePairing(a, b, PlannedCoedgePairingKind.SharedTrimCurve, readiness,
+ "pair-ready: shared trim-family and complementary source/opposite families with adjacency hint.", key,
+ ["pair-ready: deterministic coedge pairing evidence produced."]));
+ }
+ else
+ {
+ var reason = matches.Length > 1
+ ? $"pairing-deferred-ambiguous: edge-use={a.OrderingKey} has {matches.Length} matching candidates; missing one-to-one identity/provenance key."
+ : $"pairing-deferred-missing-identity: edge-use={a.OrderingKey} has no deterministic complementary match with adjacency evidence.";
+ diagnostics.Add(reason);
+ var key = $"{a.OrderingKey}<->deferred";
+ list.Add(new PlannedCoedgePairing(a, a, PlannedCoedgePairingKind.Deferred, TopologyPairingReadiness.Deferred, reason, key, [reason]));
+ used.Add(a.OrderingKey);
+ }
+ }
+
+ return list.OrderBy(p => p.OrderingKey, StringComparer.Ordinal).ToList();
+ }
+
+ private static List<LoopClosureEvidence> BuildClosureEvidence(IReadOnlyList<PlannedFacePatch> faces, List<string> diagnostics)
+ {
+ var list = new List<LoopClosureEvidence>();
+ foreach (var face in faces)
+ foreach (var loop in face.LoopGroups)
+ {
+ if (!loop.LoopDescriptors.Any())
+ {
+ var msg = $"closure-deferred-no-descriptors: face={face.OrderingKey} loop={loop.OrderingKey} has no loop descriptors.";
+ diagnostics.Add(msg);
+ list.Add(new LoopClosureEvidence(face.OrderingKey, loop.OrderingKey, LoopClosureStatus.ClosureDeferred, TopologyPairingReadiness.Deferred, msg,
+ $"{face.OrderingKey}|{loop.OrderingKey}|closure", [msg]));
+ continue;
+ }
+
+ var families = loop.LoopDescriptors.Select(d => d.TrimCurveFamily).Distinct().ToArray();
+ var hasUnsupported = loop.LoopDescriptors.Any(d => d.Status == RetainedRegionLoopStatus.Unsupported || d.TrimCurveFamily == TrimCurveFamily.Unsupported);
+ var allCircleExact = loop.LoopDescriptors.All(d => d.TrimCurveFamily == TrimCurveFamily.Circle && d.Status == RetainedRegionLoopStatus.ExactReady);
+ LoopClosureStatus status;
+ TopologyPairingReadiness readiness;
+ string evidence;
+ if (hasUnsupported)
+ {
+ status = LoopClosureStatus.Unsupported;
+ readiness = TopologyPairingReadiness.Unsupported;
+ evidence = "closure-unsupported: loop contains unsupported trim family/status; exact closure cannot be claimed.";
+ }
+ else if (allCircleExact)
+ {
+ status = LoopClosureStatus.ClosedByDescriptor;
+ readiness = TopologyPairingReadiness.ExactReady;
+ evidence = "closure-ready-by-descriptor: exact circular trim descriptor implies closed loop boundary in dry-run evidence.";
+ }
+ else
+ {
+ status = LoopClosureStatus.ClosureDeferred;
+ readiness = TopologyPairingReadiness.Deferred;
+ evidence = $"closure-deferred: trim families={string.Join(',', families)} need explicit parameter/order solving beyond descriptor-only dry-run.";
+ }
+
+ list.Add(new LoopClosureEvidence(face.OrderingKey, loop.OrderingKey, status, readiness, evidence,
+ $"{face.OrderingKey}|{loop.OrderingKey}|closure", [evidence]));
+ }
+
+ return list.OrderBy(c => c.OrderingKey, StringComparer.Ordinal).ToList();
+ }
+
+ private static TopologyPairingReadiness MapStatus(RetainedRegionLoopStatus status) => status switch
+ {
+ RetainedRegionLoopStatus.ExactReady => TopologyPairingReadiness.ExactReady,
+ RetainedRegionLoopStatus.SpecialCaseReady => TopologyPairingReadiness.SpecialCaseReady,
+ RetainedRegionLoopStatus.Deferred => TopologyPairingReadiness.Deferred,
+ RetainedRegionLoopStatus.Unsupported => TopologyPairingReadiness.Unsupported,
+ _ => TopologyPairingReadiness.NotApplicable
+ };
+
+ private static TopologyPairingReadiness ReduceReadiness(IReadOnlyList<TopologyPairingReadiness> readiness)
+ {
+ if (readiness.Count == 0) return TopologyPairingReadiness.NotApplicable;
+ if (readiness.Any(r => r == TopologyPairingReadiness.Unsupported)) return TopologyPairingReadiness.Unsupported;
+ if (readiness.Any(r => r == TopologyPairingReadiness.Deferred)) return TopologyPairingReadiness.Deferred;
+ if (readiness.Any(r => r == TopologyPairingReadiness.SpecialCaseReady)) return TopologyPairingReadiness.SpecialCaseReady;
+ if (readiness.All(r => r == TopologyPairingReadiness.ExactReady)) return TopologyPairingReadiness.ExactReady;
+ return TopologyPairingReadiness.NotApplicable;
+ }
+}
diff --git a/docs/cir-f88-edge-coedge-pairing-evidence.md b/docs/cir-f88-edge-coedge-pairing-evidence.md
new file mode 100644
index 00000000..d93aaa7d
--- /dev/null
+++ b/docs/cir-f88-edge-coedge-pairing-evidence.md
@@ -0,0 +1,89 @@
+# CIR-F8.8: edge/coedge pairing + loop-closure evidence contracts
+
+CIR-F8.8 layers descriptor-only topology evidence on top of CIR-F8.7 topology dry-run planning.
+
+## Purpose
+
+Provide deterministic, diagnostic-rich evidence for future BRep topology emission without creating any BRep entities.
+
+Added dry-run contracts:
+
+- `PlannedEdgeUse`
+- `PlannedCoedgePairing`
+- `LoopClosureEvidence`
+- `TopologyPairingEvidenceResult`
+- `TopologyPairingReadiness`
+
+Still deferred:
+
+- no `BrepEdge`/`BrepCoedge`/`BrepLoop`/`BrepFace`/`BrepVertex`/`BrepShell` emission,
+- no trim parameter solving,
+- no loop-parameter closure solving,
+- no STEP export behavior change,
+- no boolean behavior expansion.
+
+## Readiness semantics
+
+`TopologyPairingReadiness` values:
+
+- `ExactReady`
+- `SpecialCaseReady`
+- `Deferred`
+- `Unsupported`
+- `NotApplicable`
+
+Escalation is conservative and deterministic:
+
+1. any `Unsupported` => `Unsupported`
+2. else any `Deferred` => `Deferred`
+3. else any `SpecialCaseReady` => `SpecialCaseReady`
+4. else all `ExactReady` => `ExactReady`
+5. else `NotApplicable`
+
+## Deterministic ordering
+
+- Edge uses ordered by:
+ `{faceKey}|{loopKey}|{trimFamily}|{sourceSurface}|{oppositeSurface}|{loopKind}`
+- Pairings ordered by:
+ `{edgeUseA}<->{edgeUseB|deferred}`
+- Closure evidence ordered by:
+ `{faceKey}|{loopKey}|closure`
+
+## Closure semantics
+
+- `ClosedByDescriptor` is emitted only for exact circular loop descriptors.
+- Other families/statuses remain `ClosureDeferred` until explicit curve parameter/order solving exists.
+- Unsupported loop descriptor families/statuses report `Unsupported`.
+
+## Pairing semantics
+
+`SharedTrimCurve` pairing requires deterministic evidence:
+
+- same trim curve family,
+- complementary source/opposite surface families,
+- matching planned adjacency hint between source faces.
+
+If one-to-one identity is ambiguous or missing, pairing is deferred with explicit diagnostics describing missing evidence.
+
+## JudgmentEngine usage decision
+
+`JudgmentEngine` is not used in F8.8. Current pairing and closure decisions are deterministic reductions/filtering with at most one admissible candidate after required evidence keys; there are no bounded competing scored strategies yet.
+
+## Example outcomes
+
+- `Subtract(Box, Cylinder)`:
+ edge uses exist for base/tool retained loop descriptors, closure may defer for non-circular families, and pairings are either exact (where uniquely matchable) or deferred with identity diagnostics.
+- `Subtract(Box, Sphere)`:
+ circular edge uses exist and circular loops can be `ClosedByDescriptor`; coedge pairing may still defer when one-to-one identity is not provable.
+- `Subtract(Box, Torus)`:
+ evidence remains deferred due to trim-matrix deferral (`quartic/algebraic` rationale carried from prior milestones), with no exact closure claim.
+- non-subtract trees:
+ `NotApplicable`; no invented subtract pairings.
+
+## SEM-A0 guardrails status
+
+SEM-A0 preserved: no generated topology naming and no user-facing topology identity expansion were introduced.
+
+## Recommended next step
+
+CIR-F8.9 should add bounded provenance identity tokens to loop descriptors (or adjacency edges) so deferred pairing cases can be promoted from ambiguous to exact-ready without introducing generated topology naming.