Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Implement CIR-BREP-T7 bounded shared-edge coedge rewrite
Yuechen Li9d05db7fc2b3
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.csindex 5c7cf94b..d6d37723 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs@@ -6,7 +6,7 @@ namespace Aetheris.Kernel.Firmament.Tests;public sealed class SurfaceFamilyStitchExecutorTests{[Fact]- public void StitchExecutor_BoxCylinder_AppliesOneSharedEdgeStitchOrReportsPreciseBlocker()+ public void StitchExecutor_BoxCylinder_AppliesOneSharedEdgeRewriteOrPreciseBlocker(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);@@ -18,15 +18,23 @@ public sealed class SurfaceFamilyStitchExecutorTestsvar result = SurfaceFamilyStitchExecutor.TryExecute(plan, planar, cylindrical);- if (result.AppliedCandidateCount > 0)+ if (result.Success){+ Assert.Equal(1, result.AppliedCandidateCount);Assert.NotNull(result.Body);- Assert.Contains(result.Operations.SelectMany(o => o.Diagnostics), d => d.Contains("shared-edge-remap-applied", StringComparison.Ordinal));+ Assert.Contains(result.Operations.SelectMany(o => o.Diagnostics), d => d.Contains("shared-edge-rewrite-applied", StringComparison.Ordinal));+ var applied = result.Operations.Single(o => o.Status == SurfaceFamilyStitchExecutionStatus.AssembledPartialBody);+ var canonical = applied.EdgeOrCoedgeIds.First(id => id.StartsWith("E", StringComparison.Ordinal));+ var canonicalEdgeId = new Aetheris.Kernel.Core.Topology.EdgeId(int.Parse(canonical.Split(':')[1]));+ var cA = new Aetheris.Kernel.Core.Topology.CoedgeId(int.Parse(applied.EdgeOrCoedgeIds[2].Split(':')[1]));+ var cB = new Aetheris.Kernel.Core.Topology.CoedgeId(int.Parse(applied.EdgeOrCoedgeIds[3].Split(':')[1]));+ Assert.Equal(canonicalEdgeId, result.Body!.Topology.GetCoedge(cA).EdgeId);+ Assert.Equal(canonicalEdgeId, result.Body!.Topology.GetCoedge(cB).EdgeId);}else{- Assert.True(- result.Operations.SelectMany(o => o.Diagnostics).Any(d => d.Contains("mutation-unsupported-topology-model", StringComparison.Ordinal))+ Assert.True(result.Operations.SelectMany(o => o.Diagnostics).Any(d => d.Contains("mutation-unsupported-topology-model", StringComparison.Ordinal)+ || d.Contains("candidate-deferred", StringComparison.Ordinal))|| result.Diagnostics.Any(d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal)));}@@ -35,7 +43,7 @@ public sealed class SurfaceFamilyStitchExecutorTests}[Fact]- public void StitchExecutor_RequiresConcreteRefs()+ public void StitchExecutor_RequiresRemappedRefs(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);@@ -58,7 +66,7 @@ public sealed class SurfaceFamilyStitchExecutorTests}[Fact]- public void StitchExecutor_RequiresTokenMatch()+ public void StitchExecutor_RejectsTokenMismatch(){var tokenA = new InternalTrimIdentityToken("a", "b", "tok:A", TrimCurveFamily.Circle, "role", "a");var tokenB = new InternalTrimIdentityToken("a", "b", "tok:B", TrimCurveFamily.Circle, "role", "b");@@ -74,22 +82,7 @@ public sealed class SurfaceFamilyStitchExecutorTests}[Fact]- public void StitchExecutor_RequiresCompatibleRoles()- {- var token = new InternalTrimIdentityToken("a", "b", "tok:A", TrimCurveFamily.Circle, "role", "a");- var candidate = new SurfaceFamilyStitchCandidate("c", SurfaceFamilyStitchCandidateKind.SharedTrimIdentity, SurfaceFamilyStitchCandidateReadiness.Ready, token,- new EmittedTopologyIdentityEntry("ea", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalSeam, "orientation-compatible", []),- new EmittedTopologyIdentityEntry("eb", EmittedTopologyKind.Edge, token, EmittedTopologyRole.CylindricalBottomBoundary, "orientation-compatible", []),- "orientation-compatible", [], "a");- var plan = new SurfaceFamilyStitchPlanResult(true, [candidate], [], [], [], false);-- var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));- var result = SurfaceFamilyStitchExecutor.TryExecute(plan, new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root), null);- Assert.Contains(result.Operations.SelectMany(o => o.Diagnostics), d => d.Contains("incompatible-roles", StringComparison.Ordinal));- }-- [Fact]- public void StitchExecutor_NoFullShellClaim()+ public void StitchExecutor_DoesNotMergeVerticesYet(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));var result = SurfaceFamilyStitchExecutor.TryExecute(@@ -97,11 +90,11 @@ public sealed class SurfaceFamilyStitchExecutorTestsnew PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root),EmitCylinder(root));- Assert.False(result.FullShellClaimed);+ Assert.Contains(result.Diagnostics, d => d.Contains("vertex-merge-deferred", StringComparison.Ordinal));}[Fact]- public void StitchExecutor_NoStepExport()+ public void StitchExecutor_NoFullShellClaim(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));var result = SurfaceFamilyStitchExecutor.TryExecute(@@ -109,12 +102,11 @@ public sealed class SurfaceFamilyStitchExecutorTestsnew PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root),EmitCylinder(root));- Assert.False(result.StepExportAttempted);+ Assert.False(result.FullShellClaimed);}-[Fact]- public void StitchExecutor_RefsReady_CanRemapButDoesNotMutate()+ public void StitchExecutor_NoStepExport(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));var result = SurfaceFamilyStitchExecutor.TryExecute(@@ -122,12 +114,9 @@ public sealed class SurfaceFamilyStitchExecutorTestsnew PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root),EmitCylinder(root));- Assert.True(result.Diagnostics.Any(d => d.Contains("shared-edge-remap-not-applied", StringComparison.Ordinal))- || result.Diagnostics.Any(d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal)));- Assert.True(result.Operations.SelectMany(o => o.Diagnostics).Any(d => d.Contains("combined-body-remap-ready", StringComparison.Ordinal))- || result.Diagnostics.Any(d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal)));- Assert.Equal(0, result.AppliedCandidateCount);+ Assert.False(result.StepExportAttempted);}+private static SurfaceMaterializationResult? EmitCylinder(CirNode root){var gen = FacePatchCandidateGenerator.Generate(root);diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.csindex 5b609d6e..2b53c797 100644--- a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Topology;namespace Aetheris.Kernel.Firmament.Execution;@@ -41,7 +42,8 @@ internal static class SurfaceFamilyStitchExecutor{"stitch-execution-started: bounded stitch executor entered.","step-export-not-attempted: bounded stitch execution does not invoke STEP export.",- "full-shell-not-claimed: bounded stitch execution does not prove shell closure in CIR-BREP-T5."+ "full-shell-not-claimed: bounded stitch execution does not prove shell closure in CIR-BREP-T7.",+ "vertex-merge-deferred: CIR-BREP-T7 rewrites coedge edge references only."};if (plan is null)@@ -71,7 +73,6 @@ internal static class SurfaceFamilyStitchExecutorvar deferredCount = 0;var appliedCount = 0;- var attemptedMutation = false;foreach (var candidate in ready){@@ -120,53 +121,143 @@ internal static class SurfaceFamilyStitchExecutorcontinue;}- var entryA = byKey[candidate.EntryA.LocalTopologyKey];- var entryB = byKey[candidate.EntryB.LocalTopologyKey];- if (entryA.TopologyReference is not { FaceId: not null, LoopId: not null, EdgeId: not null, CoedgeId: not null } aRef- || entryB.TopologyReference is not { FaceId: not null, LoopId: not null, EdgeId: not null, CoedgeId: not null } bRef)- {- deferredCount++;- opDiagnostics.Add("candidate-deferred-topology-contract-blocker: concrete face/loop/edge/coedge refs are required for mutation.");- operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));- continue;- }-- attemptedMutation = true;- opDiagnostics.Add("ready-candidate-selected: bounded T5 picked deterministic first ready candidate.");- opDiagnostics.Add($"topology-refs-resolved: a(face={aRef.FaceId},loop={aRef.LoopId},edge={aRef.EdgeId},coedge={aRef.CoedgeId}) b(face={bRef.FaceId},loop={bRef.LoopId},edge={bRef.EdgeId},coedge={bRef.CoedgeId}).");- opDiagnostics.Add("body-remap-started: evaluating whether emitted patch bodies can be safely copied/remapped into one combined body.");var remapInputs = planarPatches.Entries.Where(e => e.Emission is { Success: true, Body: not null }).Select(e => e.Emission!).ToList();if (cylindricalPatch is { Success: true, Body: not null }) remapInputs.Add(cylindricalPatch);var remapMaps = planarPatches.Entries.Where(e => e.IdentityMap is not null).Select(e => e.IdentityMap!).Concat(cylindricalPatch?.IdentityMap is null ? [] : [cylindricalPatch.IdentityMap]).ToArray();var remap = CombinedPatchBodyRemapper.TryCombine(remapInputs, remapMaps);- if (remap.Success)+ if (!remap.Success)+ {+ deferredCount++;+ opDiagnostics.AddRange(remap.Diagnostics);+ opDiagnostics.Add("mutation-unsupported-topology-model: combined-body remap not ready; shared-edge mutation remains blocked.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));+ break;+ }++ var remapByKey = remap.RemappedIdentityMaps.SelectMany(m => m.Entries).GroupBy(e => e.LocalTopologyKey, StringComparer.Ordinal).ToDictionary(g => g.Key, g => g.First(), StringComparer.Ordinal);+ if (!remapByKey.TryGetValue(candidate.EntryA.LocalTopologyKey, out var remappedA)+ || !remapByKey.TryGetValue(candidate.EntryB.LocalTopologyKey, out var remappedB))+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-remapped-refs-missing: combined body remap succeeded but one or both candidate entries have no remapped identity entry.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ break;+ }++ if (remappedA.TopologyReference is not { EdgeId: not null, CoedgeId: not null } aRef+ || remappedB.TopologyReference is not { EdgeId: not null, CoedgeId: not null } bRef)+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-topology-contract-blocker: remapped edge/coedge refs are required for mutation.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ break;+ }++ var aEdgeId = ParseId<EdgeId>(aRef.EdgeId, static n => new EdgeId(n));+ var bEdgeId = ParseId<EdgeId>(bRef.EdgeId, static n => new EdgeId(n));+ var aCoedgeId = ParseId<CoedgeId>(aRef.CoedgeId, static n => new CoedgeId(n));+ var bCoedgeId = ParseId<CoedgeId>(bRef.CoedgeId, static n => new CoedgeId(n));+ if (aEdgeId is null || bEdgeId is null || aCoedgeId is null || bCoedgeId is null){- opDiagnostics.Add("stitch-executor: combined-body-remap-ready");- opDiagnostics.Add("stitch-executor: shared-edge-mutation-not-implemented");- operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [aRef.EdgeId, bRef.EdgeId, aRef.CoedgeId, bRef.CoedgeId], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));deferredCount++;+ opDiagnostics.Add("candidate-deferred-id-parse-failed: remapped edge/coedge ids are not parseable.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [aRef.EdgeId!, bRef.EdgeId!, aRef.CoedgeId!, bRef.CoedgeId!], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));break;}- opDiagnostics.AddRange(remap.Diagnostics);- opDiagnostics.Add("mutation-unsupported-topology-model: combined-body remap not ready; shared-edge mutation remains blocked.");- operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [aRef.EdgeId, bRef.EdgeId, aRef.CoedgeId, bRef.CoedgeId], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));- deferredCount++;- break;+ var combined = remap.CombinedBody!;+ if (!combined.Topology.TryGetCoedge(aCoedgeId.Value, out _) || !combined.Topology.TryGetCoedge(bCoedgeId.Value, out _)+ || !combined.Topology.TryGetEdge(aEdgeId.Value, out _) || !combined.Topology.TryGetEdge(bEdgeId.Value, out _))+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-remapped-topology-missing: remapped coedge/edge ids do not resolve in combined body topology.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [aRef.EdgeId!, bRef.EdgeId!, aRef.CoedgeId!, bRef.CoedgeId!], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ break;+ }++ var canonicalEdge = aEdgeId.Value;+ var duplicateEdge = bEdgeId.Value;+ var rewritten = RewriteCoedgesWithCanonicalEdge(combined, aCoedgeId.Value, bCoedgeId.Value, canonicalEdge);+ if (!rewritten.success)+ {+ deferredCount++;+ opDiagnostics.Add(rewritten.diagnostic);+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [aRef.EdgeId!, bRef.EdgeId!, aRef.CoedgeId!, bRef.CoedgeId!], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));+ break;+ }++ var validation = ValidateTopologyConsistency(rewritten.body!);+ if (!validation.success)+ {+ deferredCount++;+ opDiagnostics.AddRange(validation.diagnostics);+ opDiagnostics.Add("invariant-validation-failed: stitched topology failed bounded consistency checks.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [canonicalEdge.ToString(), duplicateEdge.ToString(), aCoedgeId.ToString()!, bCoedgeId.ToString()!], SurfaceFamilyStitchExecutionStatus.Failed, opDiagnostics));+ break;+ }++ opDiagnostics.Add("ready-candidate-selected: bounded T7 picked deterministic first ready candidate.");+ opDiagnostics.Add($"canonical-edge-selected: canonical={canonicalEdge} duplicate={duplicateEdge} rewritten-coedges={aCoedgeId},{bCoedgeId}.");+ opDiagnostics.Add("shared-edge-rewrite-applied: two boundary coedges now reference one canonical edge in combined body.");+ opDiagnostics.Add("duplicate-edge-retained-unreferenced: duplicate edge is intentionally retained for bounded T7; no coedge references it after rewrite.");+ opDiagnostics.Add("geometry-binding-policy: canonical edge binding retained; duplicate edge binding retained for deferred cleanup.");+ opDiagnostics.Add("invariant-validation-passed: coedge/loop/face/binding references resolve after rewrite.");+ opDiagnostics.Add("full-shell-not-claimed: bounded shared-edge rewrite does not claim closed-shell completion.");+ opDiagnostics.Add("step-export-not-attempted: bounded shared-edge rewrite does not invoke STEP export.");++ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [canonicalEdge.ToString(), duplicateEdge.ToString(), aCoedgeId.ToString()!, bCoedgeId.ToString()!], SurfaceFamilyStitchExecutionStatus.AssembledPartialBody, opDiagnostics));+ appliedCount = 1;+ diagnostics.Add("bounded-scope-single-candidate: CIR-BREP-T7 applies at most one deterministic ready candidate.");+ diagnostics.Add("shared-edge-rewrite-applied: one bounded coedge edge-reference rewrite completed.");+ return Build(true, SurfaceFamilyStitchExecutionStatus.AssembledPartialBody, rewritten.body, appliedCount, deferredCount, operations, diagnostics);}diagnostics.Add($"ready-candidates-processed: {ready.Length}.");diagnostics.Add($"stitch-applied-count: {appliedCount}.");diagnostics.Add($"stitch-deferred-count: {deferredCount}.");- if (ready.Length > 1) diagnostics.Add("bounded-scope-single-candidate: CIR-BREP-T5 processes at most one ready candidate deterministically.");+ if (ready.Length > 1) diagnostics.Add("bounded-scope-single-candidate: CIR-BREP-T7 processes at most one ready candidate deterministically.");+ return Build(false, SurfaceFamilyStitchExecutionStatus.Deferred, null, appliedCount, deferredCount, operations, diagnostics);+ }- if (attemptedMutation)+ private static (bool success, BrepBody? body, string diagnostic) RewriteCoedgesWithCanonicalEdge(BrepBody source, CoedgeId aCoedgeId, CoedgeId bCoedgeId, EdgeId canonicalEdge)+ {+ var topology = new TopologyModel();+ foreach (var v in source.Topology.Vertices.OrderBy(v => v.Id.Value)) topology.AddVertex(v);+ foreach (var e in source.Topology.Edges.OrderBy(e => e.Id.Value)) topology.AddEdge(e);+ foreach (var c in source.Topology.Coedges.OrderBy(c => c.Id.Value)){- diagnostics.Add("shared-edge-remap-not-applied: topology mutation blocked by missing safe remap capability for emitted-body merge.");- return Build(false, SurfaceFamilyStitchExecutionStatus.Unsupported, null, appliedCount, deferredCount, operations, diagnostics);+ if (c.Id == aCoedgeId || c.Id == bCoedgeId) topology.AddCoedge(c with { EdgeId = canonicalEdge });+ else topology.AddCoedge(c);}+ foreach (var l in source.Topology.Loops.OrderBy(l => l.Id.Value)) topology.AddLoop(l);+ foreach (var f in source.Topology.Faces.OrderBy(f => f.Id.Value)) topology.AddFace(f);+ foreach (var s in source.Topology.Shells.OrderBy(s => s.Id.Value)) topology.AddShell(s);+ foreach (var b in source.Topology.Bodies.OrderBy(b => b.Id.Value)) topology.AddBody(b);+ return (true, new BrepBody(topology, source.Geometry, source.Bindings), string.Empty);+ }- return Build(false, SurfaceFamilyStitchExecutionStatus.Deferred, null, appliedCount, deferredCount, operations, diagnostics);+ private static (bool success, IReadOnlyList<string> diagnostics) ValidateTopologyConsistency(BrepBody body)+ {+ var diagnostics = new List<string>();+ foreach (var c in body.Topology.Coedges)+ if (!body.Topology.TryGetEdge(c.EdgeId, out _)) diagnostics.Add($"missing-edge-for-coedge:{c.Id}->{c.EdgeId}");+ foreach (var l in body.Topology.Loops)+ foreach (var cid in l.CoedgeIds)+ if (!body.Topology.TryGetCoedge(cid, out _)) diagnostics.Add($"missing-coedge-for-loop:{l.Id}->{cid}");+ foreach (var f in body.Topology.Faces)+ foreach (var lid in f.LoopIds)+ if (!body.Topology.TryGetLoop(lid, out _)) diagnostics.Add($"missing-loop-for-face:{f.Id}->{lid}");+ foreach (var binding in body.Bindings.EdgeBindings)+ if (!body.Topology.TryGetEdge(binding.EdgeId, out _)) diagnostics.Add($"missing-edge-for-binding:{binding.EdgeId}");+ foreach (var binding in body.Bindings.FaceBindings)+ if (!body.Topology.TryGetFace(binding.FaceId, out _)) diagnostics.Add($"missing-face-for-binding:{binding.FaceId}");+ return (diagnostics.Count == 0, diagnostics);+ }++ 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;}private static SurfaceFamilyStitchExecutionResult Build(bool success, SurfaceFamilyStitchExecutionStatus status, BrepBody? body, int applied, int deferred, IReadOnlyList<AppliedStitchOperation> operations, IReadOnlyList<string> diagnostics)diff --git a/docs/cir-brep-t7-shared-edge-rewrite.md b/docs/cir-brep-t7-shared-edge-rewrite.mdnew file mode 100644index 00000000..4c93c9e0--- /dev/null+++ b/docs/cir-brep-t7-shared-edge-rewrite.md@@ -0,0 +1,64 @@+# CIR-BREP-T7: One bounded shared-edge/coedge rewrite using remapped topology references++## Scope++CIR-BREP-T7 performs exactly one bounded shared-edge rewrite inside the stitch executor, only after T6 combined-body remap succeeds and remapped concrete topology references are available.++## Topology mutability diagnosis++- `TopologyModel` stores entities in dictionaries and supports only `Add*` APIs.+- Topology entities (`Edge`, `Coedge`, `Loop`, `Face`, etc.) are immutable records.+- Coedge edge-reference rewrite is therefore implemented as bounded body rebuild: copy topology, replace the two target `Coedge.EdgeId` values with the canonical edge id, preserve all other topology and bindings.++## Duplicate edge policy (T7)++- **Policy A (bounded): keep duplicate edge** after coedge rewrite.+- Duplicate edge is intentionally retained and becomes unreferenced by coedges.+- Edge binding for duplicate edge is retained in T7 to avoid expanding cleanup scope.++## Geometry binding policy++- Canonical edge binding remains unchanged.+- Rewritten coedges now point to canonical edge id.+- Duplicate edge binding is retained (deferred cleanup milestone).+- Invariant check verifies all bindings still point to existing topology ids.++## Vertex policy++- Vertex merge is explicitly deferred.+- T7 does not merge or rewrite vertices.+- Diagnostics include `vertex-merge-deferred`.++## Invariant checks after rewrite++- Every coedge references an existing edge.+- Every loop references existing coedges.+- Every face references existing loops.+- Every edge binding references existing edge.+- Every face binding references existing face.++## Execution behavior++Mutation is attempted only when all gates pass:++- ready stitch candidate exists,+- candidate kind is `SharedTrimIdentity`,+- entry tokens match,+- roles + orientation are compatible,+- T6 remap succeeded,+- remapped candidate entries exist,+- remapped refs include edge + coedge ids,+- remapped ids resolve in combined body.++If any gate fails, executor returns deferred/unsupported with precise diagnostics and no mutation.++## Claims and non-claims++- Full shell closure is **not claimed**.+- STEP export is **not attempted**.+- Single-candidate bounded scope remains explicit and deterministic.++## Next milestone++- Add bounded duplicate-edge cleanup and binding cleanup policy (only when proven invariant-safe).+- Evaluate bounded vertex equivalence/merge strategy for stitched trim endpoints.