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