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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.