Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-F8.7 topology assembly dry-run planner contracts
Yuechen Li511dc406ccbd
diff --git a/Aetheris.Kernel.Firmament.Tests/TopologyAssemblyDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/TopologyAssemblyDryRunTests.csnew file mode 100644index 00000000..ef821448--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/TopologyAssemblyDryRunTests.cs@@ -0,0 +1,69 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class TopologyAssemblyDryRunTests+{+ [Fact]+ public void TopologyDryRun_BoxMinusCylinder_PlansFacesAndLoops()+ {+ var result = TopologyAssemblyDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));++ Assert.True(result.IsSuccess);+ Assert.NotEmpty(result.PlannedFaces);+ Assert.Contains(result.PlannedFaces, p => p.SurfaceFamily == SurfacePatchFamily.Cylindrical);+ Assert.Contains(result.PlannedFaces.SelectMany(p => p.LoopGroups), g => g.Readiness is TopologyAssemblyReadiness.ExactPlanReady or TopologyAssemblyReadiness.SpecialCasePlanReady or TopologyAssemblyReadiness.Deferred);+ Assert.False(result.TopologyEmissionImplemented);+ }++ [Fact]+ public void TopologyDryRun_BoxMinusSphere_PlansSphericalPatchWithoutUnsupported()+ {+ var result = TopologyAssemblyDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3)));++ Assert.Contains(result.PlannedFaces, p => p.SurfaceFamily == SurfacePatchFamily.Spherical);+ Assert.Contains(result.PlannedFaces.Where(p => p.SurfaceFamily == SurfacePatchFamily.Spherical).SelectMany(p => p.LoopGroups.SelectMany(g => g.LoopDescriptors)), l => l.TrimCurveFamily == TrimCurveFamily.Circle);+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("generic unsupported", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void TopologyDryRun_BoxMinusTorus_DefersDueTrimLoops()+ {+ var result = TopologyAssemblyDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1)));++ Assert.Contains(result.PlannedFaces, p => p.SurfaceFamily == SurfacePatchFamily.Toroidal);+ Assert.Equal(TopologyAssemblyReadiness.Deferred, result.Readiness);+ Assert.Contains(result.Diagnostics, d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void TopologyDryRun_NonSubtract_NotApplicable()+ {+ var result = TopologyAssemblyDryRunPlanner.Generate(new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2)));++ Assert.False(result.IsSuccess);+ Assert.Equal(TopologyAssemblyReadiness.NotApplicable, result.Readiness);+ Assert.Empty(result.PlannedFaces);+ }++ [Fact]+ public void TopologyDryRun_DeterministicOrdering()+ {+ var node = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var first = TopologyAssemblyDryRunPlanner.Generate(node);+ var second = TopologyAssemblyDryRunPlanner.Generate(node);++ Assert.Equal(first.PlannedFaces.Select(p => p.OrderingKey), second.PlannedFaces.Select(p => p.OrderingKey));+ Assert.Equal(first.PlannedFaces.SelectMany(p => p.LoopGroups.Select(l => l.OrderingKey)), second.PlannedFaces.SelectMany(p => p.LoopGroups.Select(l => l.OrderingKey)));+ }++ [Fact]+ public void TopologyDryRun_DoesNotEmitBRepTopology()+ {+ var result = TopologyAssemblyDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));++ Assert.False(result.TopologyEmissionImplemented);+ Assert.Contains(result.Diagnostics, d => d.Contains("topology-emission-not-implemented", StringComparison.Ordinal));+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/TopologyAssemblyDryRun.cs b/Aetheris.Kernel.Firmament/Execution/TopologyAssemblyDryRun.csnew file mode 100644index 00000000..5bed1831--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/TopologyAssemblyDryRun.cs@@ -0,0 +1,165 @@+using Aetheris.Kernel.Core.Cir;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum TopologyAssemblyReadiness+{+ NotApplicable,+ ExactPlanReady,+ SpecialCasePlanReady,+ Deferred,+ Unsupported+}++internal sealed record PlannedLoop(+ RetainedRegionLoopGroupKind GroupKind,+ TopologyAssemblyReadiness Readiness,+ RetainedRegionLoopOrientationPolicy OrientationPolicy,+ string OrderingKey,+ IReadOnlyList<RetainedRegionLoopDescriptor> LoopDescriptors,+ IReadOnlyList<string> Diagnostics);++internal sealed record PlannedFacePatch(+ FacePatchCandidate SourceCandidate,+ SurfacePatchFamily SurfaceFamily,+ FacePatchRetentionRole RetentionRole,+ RetainedRegionLoopOrientationPolicy OrientationPolicy,+ IReadOnlyList<PlannedLoop> LoopGroups,+ TopologyAssemblyReadiness Readiness,+ string OrderingKey,+ IReadOnlyList<string> Diagnostics);++internal sealed record PlannedAdjacency(+ string SourceFaceA,+ string SourceFaceB,+ TrimCurveFamily TrimCurveFamily,+ TopologyAssemblyReadiness Readiness,+ string Diagnostic);++internal sealed record TopologyAssemblyDryRunResult(+ bool IsSuccess,+ TopologyAssemblyReadiness Readiness,+ IReadOnlyList<PlannedFacePatch> PlannedFaces,+ IReadOnlyList<PlannedAdjacency> PlannedAdjacencies,+ IReadOnlyList<string> Diagnostics,+ bool TopologyEmissionImplemented);++internal static class TopologyAssemblyDryRunPlanner+{+ internal static TopologyAssemblyDryRunResult Generate(CirNode root)+ => Generate(FacePatchCandidateGenerator.Generate(root));++ internal static TopologyAssemblyDryRunResult Generate(FacePatchCandidateGenerationResult candidateResult)+ {+ var diagnostics = new List<string>+ {+ "topology-emission-not-implemented: this dry-run only plans descriptors; no BRep face/loop/edge/coedge/vertex/shell entities are created."+ };++ if (!candidateResult.Candidates.Any(c => c.RetentionRole != FacePatchRetentionRole.NotApplicable))+ {+ diagnostics.Add("topology-plan-not-applicable: non-subtract candidate set does not produce subtract topology planning contracts.");+ return new TopologyAssemblyDryRunResult(false, TopologyAssemblyReadiness.NotApplicable, [], [], diagnostics, TopologyEmissionImplemented: false);+ }++ var plannedFaces = candidateResult.Candidates+ .Where(c => c.RetentionRole is FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool or FacePatchRetentionRole.ToolBoundaryRetainedInsideBase)+ .Select(PlanFace)+ .OrderBy(p => p.OrderingKey, StringComparer.Ordinal)+ .ToArray();++ var plannedAdjacencies = BuildAdjacencyHints(plannedFaces, diagnostics);+ diagnostics.AddRange(plannedFaces.SelectMany(f => f.SourceCandidate.Diagnostics));+ diagnostics.AddRange(plannedFaces.SelectMany(f => f.Diagnostics));++ var readiness = ReduceReadiness(plannedFaces.Select(f => f.Readiness).Concat(plannedAdjacencies.Select(a => a.Readiness)).ToArray());+ return new TopologyAssemblyDryRunResult(plannedFaces.Length > 0, readiness, plannedFaces, plannedAdjacencies, diagnostics.Distinct().ToArray(), TopologyEmissionImplemented: false);+ }++ private static PlannedFacePatch PlanFace(FacePatchCandidate candidate)+ {+ var loops = candidate.RetainedRegionLoopGroups+ .Select(g => new PlannedLoop(g.GroupKind, MapLoopReadiness(g.Readiness), g.OrientationPolicy, g.OrderingKey, g.Loops, g.Diagnostics))+ .OrderBy(g => g.OrderingKey, StringComparer.Ordinal)+ .ToArray();++ var faceReadiness = loops.Length == 0+ ? TopologyAssemblyReadiness.Deferred+ : ReduceReadiness(loops.Select(l => l.Readiness).ToArray());++ var diags = new List<string>+ {+ faceReadiness switch+ {+ TopologyAssemblyReadiness.ExactPlanReady => "planned-face-exact-ready: loop groups support exact dry-run face planning; loop closure and parameter solving remain deferred.",+ TopologyAssemblyReadiness.SpecialCasePlanReady => "planned-face-special-case-ready: loop groups support special-case dry-run planning with constrained trim policies.",+ TopologyAssemblyReadiness.Deferred => "planned-face-deferred: one or more loop groups are deferred; loop closure has not been proven.",+ TopologyAssemblyReadiness.Unsupported => "planned-face-unsupported: one or more loop groups are unsupported for topology planning.",+ _ => "planned-face-not-applicable"+ }+ };+ diags.Add("loop-closure-not-proven: dry-run planning carries loop grouping/orientation only.");++ var orientation = loops.FirstOrDefault()?.OrientationPolicy ?? RetainedRegionLoopOrientationPolicy.Deferred;+ var key = $"{candidate.SourceSurface.Family}|{candidate.RetentionRole}|{faceReadiness}|{orientation}|{loops.Length}";+ return new PlannedFacePatch(candidate, candidate.SourceSurface.Family, candidate.RetentionRole, orientation, loops, faceReadiness, key, diags);+ }++ private static PlannedAdjacency[] BuildAdjacencyHints(IReadOnlyList<PlannedFacePatch> faces, List<string> diagnostics)+ {+ var list = new List<PlannedAdjacency>();+ for (var i = 0; i < faces.Count; i++)+ for (var j = i + 1; j < faces.Count; j++)+ {+ var shared = faces[i].LoopGroups.SelectMany(l => l.LoopDescriptors)+ .Select(l => l.TrimCurveFamily)+ .Intersect(faces[j].LoopGroups.SelectMany(l => l.LoopDescriptors).Select(l => l.TrimCurveFamily))+ .Where(f => f != TrimCurveFamily.Unsupported)+ .Distinct()+ .ToArray();++ if (shared.Length == 0)+ {+ diagnostics.Add($"adjacency-inference-deferred: {faces[i].SurfaceFamily} and {faces[j].SurfaceFamily} do not share a trim curve family hint.");+ continue;+ }++ foreach (var family in shared)+ {+ list.Add(new PlannedAdjacency(+ faces[i].OrderingKey,+ faces[j].OrderingKey,+ family,+ ReduceReadiness([faces[i].Readiness, faces[j].Readiness]),+ "adjacency-hint-ready: shared trim curve family found; edge/coedge and closure solving remain deferred."));+ }+ }++ if (list.Count == 0)+ {+ diagnostics.Add("adjacency-inference-deferred: no deterministic shared trim-family pairing was available for planned faces.");+ }++ return list.OrderBy(a => a.SourceFaceA, StringComparer.Ordinal).ThenBy(a => a.SourceFaceB, StringComparer.Ordinal).ThenBy(a => a.TrimCurveFamily).ToArray();+ }++ private static TopologyAssemblyReadiness MapLoopReadiness(RetainedRegionLoopGroupReadiness readiness)+ => readiness switch+ {+ RetainedRegionLoopGroupReadiness.ExactReady => TopologyAssemblyReadiness.ExactPlanReady,+ RetainedRegionLoopGroupReadiness.SpecialCaseReady => TopologyAssemblyReadiness.SpecialCasePlanReady,+ RetainedRegionLoopGroupReadiness.Deferred => TopologyAssemblyReadiness.Deferred,+ RetainedRegionLoopGroupReadiness.Unsupported => TopologyAssemblyReadiness.Unsupported,+ _ => TopologyAssemblyReadiness.NotApplicable+ };++ private static TopologyAssemblyReadiness ReduceReadiness(IReadOnlyList<TopologyAssemblyReadiness> readiness)+ {+ if (readiness.Count == 0) return TopologyAssemblyReadiness.NotApplicable;+ if (readiness.Any(r => r == TopologyAssemblyReadiness.Unsupported)) return TopologyAssemblyReadiness.Unsupported;+ if (readiness.Any(r => r == TopologyAssemblyReadiness.Deferred)) return TopologyAssemblyReadiness.Deferred;+ if (readiness.Any(r => r == TopologyAssemblyReadiness.SpecialCasePlanReady)) return TopologyAssemblyReadiness.SpecialCasePlanReady;+ if (readiness.All(r => r == TopologyAssemblyReadiness.ExactPlanReady)) return TopologyAssemblyReadiness.ExactPlanReady;+ return TopologyAssemblyReadiness.NotApplicable;+ }+}diff --git a/docs/cir-f87-topology-assembly-dry-run.md b/docs/cir-f87-topology-assembly-dry-run.mdnew file mode 100644index 00000000..d0d8c995--- /dev/null+++ b/docs/cir-f87-topology-assembly-dry-run.md@@ -0,0 +1,71 @@+# CIR-F8.7: topology assembly dry-run contracts for surface-family materialization++CIR-F8.7 introduces a topology **planning** dry-run layer that consumes F8.3/F8.4/F8.5/F8.6 candidate and loop-group contracts and reports whether future BRep topology assembly appears exact-ready, special-case-ready, deferred, unsupported, or not applicable.++## Scope++Added dry-run contracts:++- `TopologyAssemblyDryRunResult`+- `PlannedFacePatch`+- `PlannedLoop`+- `PlannedAdjacency`+- `TopologyAssemblyReadiness`++Still explicitly deferred:++- no `BrepFace`/`BrepLoop`/`BrepEdge`/`BrepCoedge`/`BrepVertex`/`BrepShell` emission,+- no trim parameter solving,+- no loop closure proof,+- no STEP export behavior change,+- no boolean behavior expansion.++## Readiness semantics and escalation++`TopologyAssemblyReadiness` values:++- `ExactPlanReady`+- `SpecialCasePlanReady`+- `Deferred`+- `Unsupported`+- `NotApplicable`++Deterministic conservative reduction:++1. any `Unsupported` => `Unsupported`+2. else any `Deferred` => `Deferred`+3. else any `SpecialCasePlanReady` => `SpecialCasePlanReady`+4. else all `ExactPlanReady` => `ExactPlanReady`+5. else `NotApplicable`++## Deterministic ordering++Planned faces are ordered by:++`{surfaceFamily}|{retentionRole}|{readiness}|{orientationPolicy}|{loopGroupCount}`++Planned loops preserve F8.6 group ordering keys.++## Adjacency hints++Adjacency hints are emitted only when two planned faces share at least one trim curve family from loop descriptors.+If no shared trim-family hint exists, adjacency is marked deferred with explicit diagnostics.++## JudgmentEngine usage decision++`JudgmentEngine` was not used in F8.7 because readiness and ordering are pure monotonic reductions over existing dry-run descriptors, and adjacency hints use deterministic shared-family intersection without competing scored alternatives.++## Expected outcomes++- `Subtract(Box, Cylinder)`: planned base/tool faces and planned loops are emitted; readiness typically exact or special-case depending on loop-group statuses.+- `Subtract(Box, Sphere)`: spherical planned face is emitted; circular loop groups represented without generic unsupported claims.+- `Subtract(Box, Torus)`: toroidal planned face exists; readiness remains deferred and diagnostics retain trim-matrix rationale (including quartic/algebraic deferral reason).+- non-subtract roots: `NotApplicable` with explicit topology-plan-not-applicable diagnostic.++## SEM-A0 status++SEM-A0 guardrails preserved: no generated topology naming was introduced.++## Recommended next step++CIR-F8.8 should formalize dry-run edge-use/coedge-use pairing and minimal loop-closure evidence contracts so adjacency hints can evolve from shared trim-family signals to deterministic edge pairing plans.