Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-BREP-X1 duplicate-edge cleanup planning contract

Yuechen Li4b7fb59d57d7
diff --git a/Aetheris.Kernel.Firmament.Tests/DuplicateEdgeCleanupPlannerTests.cs b/Aetheris.Kernel.Firmament.Tests/DuplicateEdgeCleanupPlannerTests.cs
new file mode 100644
index 00000000..89fd100c
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/DuplicateEdgeCleanupPlannerTests.cs
@@ -0,0 +1,93 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class DuplicateEdgeCleanupPlannerTests
+{
+ [Fact]
+ public void DuplicateEdgeCleanup_BoxCylinder_IdentifiesStitchDuplicateCandidate()
+ {
+ var (exec, body) = RunBoxCylinder();
+ var plan = DuplicateEdgeCleanupPlanner.Plan(exec, body);
+
+ Assert.True(plan.Success);
+ Assert.True(plan.Candidates.Count > 0 || exec.AppliedCandidateCount == 0 || plan.Diagnostics.Any(d => d.Contains("missing-operation-metadata", StringComparison.Ordinal)));
+ if (plan.Candidates.Count > 0)
+ {
+ Assert.All(plan.Candidates, c =>
+ {
+ Assert.False(string.IsNullOrWhiteSpace(c.Token));
+ Assert.StartsWith("E:", c.CanonicalEdgeId, StringComparison.Ordinal);
+ Assert.StartsWith("E:", c.DuplicateEdgeId, StringComparison.Ordinal);
+ });
+ }
+ }
+
+ [Fact]
+ public void DuplicateEdgeCleanup_ClassifiesZeroCoedgeDuplicate()
+ {
+ var (exec, body) = RunBoxCylinder();
+ var plan = DuplicateEdgeCleanupPlanner.Plan(exec, body);
+ var zeroDup = plan.BoundaryClassifications.Where(c => c.Classification == BoundaryEdgeClassificationKind.StitchDuplicateUnreferenced).ToArray();
+ Assert.True(zeroDup.Length > 0 || exec.AppliedCandidateCount == 0 || plan.Diagnostics.Any(d => d.Contains("no-canonical-duplicate-evidence", StringComparison.Ordinal)));
+ }
+
+ [Fact]
+ public void DuplicateEdgeCleanup_ClassifiesOneCoedgeShellBlockers()
+ {
+ var (exec, body) = RunBoxCylinder();
+ var plan = DuplicateEdgeCleanupPlanner.Plan(exec, body);
+ Assert.All(plan.BoundaryClassifications.Where(c => c.CoedgeUseCount == 1), c => Assert.Equal(BoundaryEdgeClassificationKind.ShellClosureBlocker, c.Classification));
+ }
+
+ [Fact]
+ public void DuplicateEdgeCleanup_DoesNotMutateByDefault()
+ {
+ var (exec, body) = RunBoxCylinder();
+ var plan = DuplicateEdgeCleanupPlanner.Plan(exec, body);
+ Assert.False(plan.CleanupMutationImplemented);
+ }
+
+ [Fact]
+ public void PressureTest_ReportsDuplicateCleanupCandidates()
+ {
+ var result = SurfaceFamilyBoxCylinderPressureTest.Run(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+ var stage = result.Stages.Single(s => s.Stage == "DuplicateEdgeCleanup");
+ Assert.True(stage.Counts.ContainsKey("DuplicateCleanupCandidateCount"));
+ Assert.Contains(stage.Diagnostics, d => d.Contains("cleanup-mutation-not-implemented", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void PressureTest_ShellStillNotClaimedAfterCleanupPlanning()
+ {
+ var result = SurfaceFamilyBoxCylinderPressureTest.Run(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+ Assert.False(result.ShellClosureValidated);
+ }
+
+ private static (SurfaceFamilyStitchExecutionResult exec, Aetheris.Kernel.Core.Brep.BrepBody body) RunBoxCylinder()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ var cylindrical = EmitCylinder(root);
+ var maps = planar.Entries.Where(e => e.Emitted).Select(e => e.IdentityMap ?? EmittedTopologyIdentityMap.Empty)
+ .Concat(cylindrical?.IdentityMap is null ? [] : [cylindrical.IdentityMap]);
+ var analysis = EmittedTokenPairingAnalyzer.Analyze(maps);
+ var plan = SurfaceFamilyStitchCandidatePlanner.Plan(maps, analysis, ShellStitchingDryRunPlanner.Generate(root));
+ var exec = SurfaceFamilyStitchExecutor.TryExecute(plan, planar, cylindrical);
+
+ var patchResults = planar.Entries.Where(e => e.Emission is { Success: true, Body: not null }).Select(e => e.Emission!).Concat(cylindrical is { Success: true, Body: not null } ? [cylindrical] : []).ToArray();
+ var remap = CombinedPatchBodyRemapper.TryCombine(patchResults, maps.ToArray());
+ return (exec, exec.Body ?? remap.CombinedBody!);
+ }
+
+ private static SurfaceMaterializationResult? EmitCylinder(CirNode root)
+ {
+ var gen = FacePatchCandidateGenerator.Generate(root);
+ var candidate = gen.Candidates.SingleOrDefault(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical
+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
+ if (candidate is null) return null;
+ var ready = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0, 0, 0, 0, 0, 0, 0, [], false);
+ return new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(candidate, ready));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/DuplicateEdgeCleanupPlanner.cs b/Aetheris.Kernel.Firmament/Execution/DuplicateEdgeCleanupPlanner.cs
new file mode 100644
index 00000000..38df93ef
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/DuplicateEdgeCleanupPlanner.cs
@@ -0,0 +1,169 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum DuplicateEdgeCleanupStatus
+{
+ CleanupCandidate,
+ AlreadyClean,
+ Deferred,
+ Unsupported,
+ NotRelatedToStitch
+}
+
+internal enum BoundaryEdgeClassificationKind
+{
+ ExpectedOpenBoundary,
+ StitchDuplicateUnreferenced,
+ ShellClosureBlocker,
+ Ambiguous
+}
+
+internal sealed record DuplicateEdgeCleanupCandidate(
+ string Token,
+ string CanonicalEdgeId,
+ string DuplicateEdgeId,
+ string RewrittenCoedgeId,
+ string EvidenceSource,
+ bool SafeToRemoveLater,
+ DuplicateEdgeCleanupStatus Status,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record BoundaryEdgeClassification(
+ string EdgeId,
+ int CoedgeUseCount,
+ BoundaryEdgeClassificationKind Classification,
+ string? RelatedToken,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record DuplicateEdgeCleanupPlanResult(
+ bool Success,
+ IReadOnlyList<DuplicateEdgeCleanupCandidate> Candidates,
+ IReadOnlyList<BoundaryEdgeClassification> BoundaryClassifications,
+ IReadOnlyList<string> Diagnostics,
+ bool CleanupMutationImplemented);
+
+internal static class DuplicateEdgeCleanupPlanner
+{
+ internal static DuplicateEdgeCleanupPlanResult Plan(SurfaceFamilyStitchExecutionResult execution, BrepBody? body)
+ {
+ var diagnostics = new List<string>
+ {
+ "duplicate-edge-cleanup-planning-started: evidence-only duplicate cleanup analysis after shared-edge rewrite.",
+ "no-coordinate-coincidence-policy: duplicate classification uses stitch operation/remap identity evidence only."
+ };
+
+ if (execution is null || body is null)
+ {
+ diagnostics.Add("duplicate-edge-cleanup-blocked-missing-input: stitch execution result and body are both required.");
+ return new(false, [], [], diagnostics, CleanupMutationImplemented: false);
+ }
+
+ var edgeUse = body.Topology.Edges.ToDictionary(e => e.Id, e => body.Topology.Coedges.Count(c => c.EdgeId == e.Id));
+ var stitchDuplicates = new Dictionary<string, (EdgeId edgeId, string token, string canonicalEdge, string rewrittenCoedge)>(StringComparer.Ordinal);
+ var candidates = new List<DuplicateEdgeCleanupCandidate>();
+
+ foreach (var op in execution.Operations.OrderBy(o => o.CandidateId, StringComparer.Ordinal))
+ {
+ if (op.Status != SurfaceFamilyStitchExecutionStatus.AssembledPartialBody)
+ {
+ continue;
+ }
+
+ if (op.EdgeOrCoedgeIds.Count < 4)
+ {
+ diagnostics.Add($"duplicate-edge-cleanup-blocked-missing-operation-metadata:candidate={op.CandidateId}; expected canonical/duplicate/rewritten coedge ids from T7.");
+ continue;
+ }
+
+ var canonicalToken = op.EdgeOrCoedgeIds[0];
+ var duplicateToken = op.EdgeOrCoedgeIds[1];
+ var rewrittenCoedgeToken = op.EdgeOrCoedgeIds[2];
+ var canonicalEdge = ParseId<EdgeId>(canonicalToken, static i => new EdgeId(i));
+ var duplicateEdge = ParseId<EdgeId>(duplicateToken, static i => new EdgeId(i));
+ if (canonicalEdge is null || duplicateEdge is null)
+ {
+ diagnostics.Add($"duplicate-edge-cleanup-blocked-unparseable-operation-ids:candidate={op.CandidateId};canonical={canonicalToken};duplicate={duplicateToken}.");
+ continue;
+ }
+
+ var duplicateEdgeIdText = duplicateEdge.Value.ToString()!;
+ stitchDuplicates[duplicateEdgeIdText] = (duplicateEdge.Value, op.Token, canonicalToken, rewrittenCoedgeToken);
+ diagnostics.Add($"applied-stitch-recorded-canonical-duplicate-edge:candidate={op.CandidateId};token={op.Token};canonical={canonicalToken};duplicate={duplicateToken};rewritten={rewrittenCoedgeToken}.");
+
+ if (!edgeUse.TryGetValue(duplicateEdge.Value, out var uses))
+ {
+ diagnostics.Add($"duplicate-edge-cleanup-blocked-duplicate-edge-missing: duplicate edge {duplicateToken} not present in topology.");
+ continue;
+ }
+
+ if (uses == 0)
+ {
+ candidates.Add(new DuplicateEdgeCleanupCandidate(op.Token, canonicalToken, duplicateToken, rewrittenCoedgeToken, "applied-stitch-operation", true, DuplicateEdgeCleanupStatus.CleanupCandidate,
+ ["duplicate-edge-has-zero-coedges-after-rewrite: safe candidate for future bounded removal.", "duplicate-edge-cleanup: candidate identified; mutation deferred."]));
+ diagnostics.Add($"duplicate-edge-cleanup-candidate-identified: duplicate={duplicateToken};canonical={canonicalToken};token={op.Token}.");
+ }
+ else
+ {
+ candidates.Add(new DuplicateEdgeCleanupCandidate(op.Token, canonicalToken, duplicateToken, rewrittenCoedgeToken, "applied-stitch-operation", false, DuplicateEdgeCleanupStatus.Deferred,
+ [$"duplicate-edge-still-referenced: duplicate edge has {uses} coedge use(s); removal deferred."]));
+ diagnostics.Add($"duplicate-edge-cleanup-deferred-still-referenced: duplicate={duplicateToken};uses={uses}.");
+ }
+ }
+
+ if (execution.Operations.Any(o => o.Status == SurfaceFamilyStitchExecutionStatus.AssembledPartialBody) && stitchDuplicates.Count == 0)
+ {
+ diagnostics.Add("duplicate-edge-cleanup-blocked-no-canonical-duplicate-evidence: applied stitch operation did not yield parseable duplicate edge metadata.");
+ }
+
+ var boundaries = new List<BoundaryEdgeClassification>();
+ foreach (var edge in body.Topology.Edges.OrderBy(e => e.Id.Value))
+ {
+ var idText = edge.Id.ToString()!;
+ var uses = edgeUse[edge.Id];
+ if (uses == 0)
+ {
+ if (stitchDuplicates.TryGetValue(idText, out var stitch))
+ {
+ boundaries.Add(new(idText, uses, BoundaryEdgeClassificationKind.StitchDuplicateUnreferenced, stitch.token,
+ ["zero-coedge edge tied to applied stitch duplicate; expected unreferenced duplicate after T7 rewrite."]));
+ }
+ else
+ {
+ boundaries.Add(new(idText, uses, BoundaryEdgeClassificationKind.Ambiguous, null,
+ ["zero-coedge edge not related to applied stitch duplicate evidence."]));
+ diagnostics.Add($"edge-not-related-to-stitch-zero-coedge:{idText}.");
+ }
+ }
+ else if (uses == 1)
+ {
+ boundaries.Add(new(idText, uses, BoundaryEdgeClassificationKind.ShellClosureBlocker, stitchDuplicates.TryGetValue(idText, out var stitch) ? stitch.token : null,
+ ["one-coedge edge remains shell-closure blocker in bounded X1 planning."]));
+ }
+ else if (uses == 2)
+ {
+ boundaries.Add(new(idText, uses, BoundaryEdgeClassificationKind.ExpectedOpenBoundary, null,
+ ["two-coedge edge is not a shell-closure blocker under bounded edge-use policy."]));
+ }
+ else
+ {
+ boundaries.Add(new(idText, uses, BoundaryEdgeClassificationKind.Ambiguous, null,
+ ["edge has more than two coedges; bounded cleanup planner marks ambiguous/invalid."]));
+ diagnostics.Add($"edge-use-ambiguous-more-than-two-coedges:{idText};uses={uses}.");
+ }
+ }
+
+ diagnostics.Add($"duplicate-edge-cleanup-candidate-count:{candidates.Count(c => c.Status == DuplicateEdgeCleanupStatus.CleanupCandidate)}.");
+ diagnostics.Add($"boundary-shell-blocker-count:{boundaries.Count(b => b.Classification == BoundaryEdgeClassificationKind.ShellClosureBlocker)}.");
+ diagnostics.Add("cleanup-mutation-not-implemented: planner is metadata-only in CIR-BREP-X1.");
+
+ return new(true, candidates, boundaries, diagnostics.Distinct().ToArray(), CleanupMutationImplemented: false);
+ }
+
+ private static TId? ParseId<TId>(string token, Func<int, TId> factory) where TId : struct
+ {
+ var parts = token.Split(':', StringSplitOptions.TrimEntries);
+ return parts.Length == 2 && int.TryParse(parts[1], out var numeric) ? factory(numeric) : null;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyBoxCylinderPressureTest.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyBoxCylinderPressureTest.cs
index a7b32e80..f6f10692 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyBoxCylinderPressureTest.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyBoxCylinderPressureTest.cs
@@ -116,8 +116,27 @@ internal static class SurfaceFamilyBoxCylinderPressureTest
["DeferredStitchCandidateCount"] = exec.DeferredCandidateCount
}));
- stages.Add(new("DuplicateEdgeCleanup", SurfaceFamilyPressureStageStatus.Deferred, ["duplicate-edge-cleanup-not-implemented: diagnostic-only stage in X0.1."], new Dictionary<string, int>()));
- blockers.Add(Block("DuplicateEdgeCleanup", "duplicate-edge-cleanup-not-implemented", "Duplicate/unreferenced edge cleanup is intentionally deferred.", "Implement bounded unreferenced duplicate-edge cleanup after rewrite stability is validated."));
+ var cleanupPlan = DuplicateEdgeCleanupPlanner.Plan(exec, exec.Body ?? remap.CombinedBody);
+ tokenCounts["DuplicateCleanupCandidateCount"] = cleanupPlan.Candidates.Count(c => c.Status == DuplicateEdgeCleanupStatus.CleanupCandidate);
+ tokenCounts["DuplicateCleanupDeferredCount"] = cleanupPlan.Candidates.Count(c => c.Status == DuplicateEdgeCleanupStatus.Deferred);
+ tokenCounts["BoundaryShellBlockerCount"] = cleanupPlan.BoundaryClassifications.Count(c => c.Classification == BoundaryEdgeClassificationKind.ShellClosureBlocker);
+ tokenCounts["BoundaryAmbiguousCount"] = cleanupPlan.BoundaryClassifications.Count(c => c.Classification == BoundaryEdgeClassificationKind.Ambiguous);
+ var cleanupStatus = cleanupPlan.Success ? SurfaceFamilyPressureStageStatus.Succeeded : SurfaceFamilyPressureStageStatus.Deferred;
+ stages.Add(new("DuplicateEdgeCleanup", cleanupStatus, cleanupPlan.Diagnostics, new Dictionary<string, int>
+ {
+ ["DuplicateCleanupCandidateCount"] = tokenCounts["DuplicateCleanupCandidateCount"],
+ ["DuplicateCleanupDeferredCount"] = tokenCounts["DuplicateCleanupDeferredCount"],
+ ["BoundaryShellBlockerCount"] = tokenCounts["BoundaryShellBlockerCount"],
+ ["BoundaryAmbiguousCount"] = tokenCounts["BoundaryAmbiguousCount"]
+ }));
+ if (!cleanupPlan.Success)
+ {
+ blockers.Add(Block("DuplicateEdgeCleanup", "duplicate-edge-cleanup-planning-blocked", "Duplicate-edge cleanup planning could not classify stitch duplicates safely.", "Provide canonical/duplicate stitch metadata and rerun bounded duplicate-edge planning."));
+ }
+ else
+ {
+ blockers.Add(Block("DuplicateEdgeCleanup", "duplicate-edge-cleanup-mutation-deferred", "Duplicate-edge cleanup candidates identified; mutation intentionally deferred in X1.", "Implement bounded remove-unused-duplicate-edge mutation only after topology/binding safety contract is validated."));
+ }
stages.Add(new("VertexMergePlanning", SurfaceFamilyPressureStageStatus.Deferred, ["vertex-merge-needed-analysis-only: no vertex merge mutation in X0.1."], new Dictionary<string, int>()));
blockers.Add(Block("VertexMergePlanning", "vertex-merge-needed", "Vertex merge planning indicates deferred endpoint consolidation work.", "Define and validate bounded vertex merge contract before shell-closure claims."));
diff --git a/docs/cir-brep-x1-duplicate-edge-cleanup.md b/docs/cir-brep-x1-duplicate-edge-cleanup.md
new file mode 100644
index 00000000..bed0ccac
--- /dev/null
+++ b/docs/cir-brep-x1-duplicate-edge-cleanup.md
@@ -0,0 +1,49 @@
+# CIR-BREP-X1 — bounded duplicate-edge cleanup contract after stitch rewrite
+
+## Purpose
+CIR-BREP-X1 adds an evidence-only duplicate-edge cleanup planner for the topology state after CIR-BREP-T7 shared-edge rewrite.
+
+## Evidence-only duplicate classification
+`DuplicateEdgeCleanupPlanner` classifies duplicate edges only from stitch evidence:
+- `AppliedStitchOperation` canonical edge id,
+- duplicate edge id,
+- rewritten coedge id,
+- token ordering key.
+
+No duplicate inference by geometric or coordinate coincidence is permitted.
+
+## Boundary edge classification policy
+For each edge in combined/rewrite topology, classify by coedge use count:
+- `0` + stitch duplicate evidence → `StitchDuplicateUnreferenced`.
+- `1` → `ShellClosureBlocker`.
+- `2` → `ExpectedOpenBoundary` (non-blocker in this bounded check).
+- `>2` → `Ambiguous`.
+- `0` without stitch relation → `Ambiguous`.
+
+## Cleanup mutation status
+CIR-BREP-X1 is planning-only:
+- `CleanupMutationImplemented=false` always.
+- Diagnostic emitted: `duplicate-edge-cleanup: candidate identified; mutation deferred`.
+
+No topology mutation, no vertex merge, no shell closure claim, and no STEP behavior change.
+
+## Pressure test integration
+`SurfaceFamilyBoxCylinderPressureTest` now runs duplicate-edge cleanup planning and records:
+- candidate/deferred counts,
+- shell blocker count,
+- ambiguous count,
+- stage diagnostics proving planning-only behavior.
+
+## Observed blocker priorities
+Primary remaining blockers stay explicit:
+- `duplicate-edge-cleanup-mutation-deferred`,
+- `vertex-merge-needed`,
+- `shell-not-proven-closed`,
+- `edges-with-one-coedge`,
+- `step-smoke-skipped-shell-not-closed`.
+
+## JudgmentEngine decision
+JudgmentEngine is not used in X1 because classification is deterministic map/reduce from stitch evidence + edge-use counts, with ambiguous cases explicitly marked instead of scored.
+
+## Next milestone
+CIR-BREP-X2 should add bounded, safe removal for stitch-linked zero-coedge duplicate edges only after validating topology and geometry-binding deletion contracts end-to-end.