Skip to content

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