Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-BREP-T4 add concrete emitted topology references metadata

Yuechen Li47e74950d11d
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs
index f7fe755f..160c5862 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs
@@ -22,11 +22,21 @@ public sealed class SurfaceFamilyStitchExecutorTests
if (result.AppliedCandidateCount == 0)
{
Assert.True(
- result.Diagnostics.Any(d => d.Contains("shared-edge-merge-unsupported", StringComparison.Ordinal))
+ result.Operations.SelectMany(o => o.Diagnostics).Any(d => d.Contains("candidate topology refs ready", StringComparison.Ordinal))
+ || result.Diagnostics.Any(d => d.Contains("shared-edge-merge-unsupported", StringComparison.Ordinal))
|| result.Diagnostics.Any(d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal)));
}
}
+ [Fact]
+ public void EmittedTopologyRefs_CylindricalSeam_RefsOrDiagnosticsPresent()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var cylindrical = EmitCylinder(root);
+ var seam = cylindrical!.IdentityMap!.Entries.Single(e => e.Role == EmittedTopologyRole.CylindricalSeam);
+ Assert.True(seam.TopologyReference is not null || seam.Diagnostics.Any(d => d.Contains("missing", StringComparison.OrdinalIgnoreCase)));
+ }
+
[Fact]
public void StitchExecutor_NoCandidate_NoMutation()
{
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index 9893cdf1..0e378bbe 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -200,6 +200,54 @@ public sealed class SurfacePatchDescriptorScaffoldTests
Assert.Contains(result.Diagnostics, d => d.Contains("inner loop", StringComparison.OrdinalIgnoreCase));
}
+ [Fact]
+ public void EmittedTopologyRefs_PlanarInnerCircle_HasConcreteIds()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var generation = FacePatchCandidateGenerator.Generate(root);
+ var candidate = generation.Candidates.First(c => c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool
+ && c.SourceSurface.BoundedPlanarGeometry is { Kind: BoundedPlanarPatchGeometryKind.Rectangle }
+ && c.RetainedRegionLoops.Any(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null));
+ var inner = candidate.RetainedRegionLoops.First(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null).CircularGeometry!.Value;
+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);
+ var result = new PlanarSurfaceMaterializer().EmitRectangleWithInnerCircle(new(candidate.SourceSurface, inner, null, readiness));
+ var entry = result.IdentityMap!.Entries.First(e => e.Role == EmittedTopologyRole.InnerCircularTrim && e.Kind == EmittedTopologyKind.Edge);
+ Assert.NotNull(entry.TopologyReference);
+ Assert.False(string.IsNullOrWhiteSpace(entry.TopologyReference!.FaceId));
+ Assert.False(string.IsNullOrWhiteSpace(entry.TopologyReference.LoopId));
+ Assert.False(string.IsNullOrWhiteSpace(entry.TopologyReference.EdgeId));
+ Assert.False(string.IsNullOrWhiteSpace(entry.TopologyReference.CoedgeId));
+ Assert.Contains(entry.TopologyReference.Diagnostics, d => d.Contains("planar-inner-circle attached", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void EmittedTopologyRefs_PlanarPatchSet_PropagatesConcreteIds()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ var entry = result.Entries
+ .Where(e => e.Emitted && e.IdentityMap is not null)
+ .SelectMany(e => e.IdentityMap!.Entries)
+ .FirstOrDefault(e => e.Role == EmittedTopologyRole.InnerCircularTrim && e.TopologyReference is not null);
+ Assert.NotNull(entry);
+ Assert.False(string.IsNullOrWhiteSpace(entry!.TopologyReference!.EdgeId));
+ }
+
+ [Fact]
+ public void EmittedTopologyRefs_CylindricalWall_BoundaryRefsPresent()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var generation = FacePatchCandidateGenerator.Generate(root);
+ var candidate = generation.Candidates.Single(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);
+ var result = new CylindricalSurfaceMaterializer().EmitRetainedWall(new(candidate, readiness));
+ var boundaries = result.IdentityMap!.Entries.Where(e => e.Role is EmittedTopologyRole.CylindricalTopBoundary or EmittedTopologyRole.CylindricalBottomBoundary).ToArray();
+ Assert.Equal(2, boundaries.Length);
+ Assert.All(boundaries, b => Assert.NotNull(b.TopologyReference));
+ Assert.All(boundaries, b => Assert.False(string.IsNullOrWhiteSpace(b.TopologyReference!.FaceId)));
+ Assert.All(boundaries, b => Assert.False(string.IsNullOrWhiteSpace(b.TopologyReference!.EdgeId)));
+ }
+
[Fact]
public void PlanarSurfaceMaterializer_RectangleWithInnerCircle_RejectsDeferredReadiness()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs
index 2dc62c27..8eac23ff 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs
@@ -118,10 +118,22 @@ internal static class SurfaceFamilyStitchExecutor
continue;
}
+ var entryA = byKey[candidate.EntryA.LocalTopologyKey];
+ var entryB = byKey[candidate.EntryB.LocalTopologyKey];
+ if (entryA.TopologyReference is not { EdgeId: not null } aRef || entryB.TopologyReference is not { EdgeId: not null } bRef)
+ {
+ deferredCount++;
+ opDiagnostics.Add("candidate-deferred-topology-contract-blocker: emitted identity entries are missing concrete topology references required for stitch mutation safety.");
+ 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;
+ }
+
+ opDiagnostics.Add("stitch-executor: candidate topology refs ready");
+ opDiagnostics.Add($"stitch-executor: candidate edge refs ready a={aRef.EdgeId} b={bRef.EdgeId}");
unsupported = true;
deferredCount++;
- opDiagnostics.Add("candidate-deferred-topology-contract-blocker: emitted identity entries currently provide edge-local keys only; concrete coedge/loop/face ids are required for safe shared-edge stitch mutation.");
- opDiagnostics.Add("candidate-deferred-topology-remap-blocker: bounded patch bodies are independent Brep bodies and CIR-BREP-T3 has no safe cross-body topology id remap contract.");
+ opDiagnostics.Add("candidate-deferred-mutation-not-implemented: topology refs ready but CIR-BREP-T4 does not mutate/merge topology.");
+ opDiagnostics.Add("candidate-deferred-topology-remap-blocker: bounded patch bodies are independent Brep bodies and stitch remap/mutation implementation is deferred.");
operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));
}
@@ -131,7 +143,7 @@ internal static class SurfaceFamilyStitchExecutor
if (unsupported)
{
- diagnostics.Add("shared-edge-merge-unsupported: blocked by missing concrete coedge/loop/face identity contract and cross-body remap support.");
+ diagnostics.Add("shared-edge-merge-unsupported: topology refs can be ready, but stitch mutation/remap remains deferred.");
return Build(false, SurfaceFamilyStitchExecutionStatus.Unsupported, null, appliedCount, deferredCount, operations, diagnostics);
}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index e049dc3c..e17906b7 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -632,9 +632,9 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
var identityEntries = new List<EmittedTopologyIdentityEntry>
{
new($"loop:{outerLoopId.Value}", EmittedTopologyKind.Loop, null, EmittedTopologyRole.OuterBoundary, "follow-face-boundary", ["outer boundary intentionally unmapped/internal-only."]),
- new($"edge:{e[4].Value}", EmittedTopologyKind.Edge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; token not fabricated." : "inner circular trim token attached from retained loop evidence."]),
- new($"coedge:{innerCoedgeId.Value}", EmittedTopologyKind.Coedge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; coedge left unmapped." : "inner circular trim token attached on emitted coedge."]),
- new($"loop:{innerLoopId.Value}", EmittedTopologyKind.Loop, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; loop identity recorded without token." : "inner circular trim token attached on emitted inner loop."])
+ new($"edge:{e[4].Value}", EmittedTopologyKind.Edge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; token not fabricated." : "inner circular trim token attached from retained loop evidence."], new EmittedTopologyReference("emitted:planar-inner-circle", $"edge:{e[4].Value}", face.Value.ToString(), innerLoopId.Value.ToString(), e[4].Value.ToString(), innerCoedgeId.Value.ToString(), v[4].Value.ToString(), ["topology-ref: planar-inner-circle attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"])),
+ new($"coedge:{innerCoedgeId.Value}", EmittedTopologyKind.Coedge, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; coedge left unmapped." : "inner circular trim token attached on emitted coedge."], new EmittedTopologyReference("emitted:planar-inner-circle", $"coedge:{innerCoedgeId.Value}", face.Value.ToString(), innerLoopId.Value.ToString(), e[4].Value.ToString(), innerCoedgeId.Value.ToString(), v[4].Value.ToString(), ["topology-ref: planar-inner-circle attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"])),
+ new($"loop:{innerLoopId.Value}", EmittedTopologyKind.Loop, innerToken, EmittedTopologyRole.InnerCircularTrim, "reverse-for-tool-cavity", [innerToken is null ? "inner circular trim token missing from retained loop evidence; loop identity recorded without token." : "inner circular trim token attached on emitted inner loop."], new EmittedTopologyReference("emitted:planar-inner-circle", $"loop:{innerLoopId.Value}", face.Value.ToString(), innerLoopId.Value.ToString(), e[4].Value.ToString(), innerCoedgeId.Value.ToString(), v[4].Value.ToString(), ["topology-ref: planar-inner-circle attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"]))
};
return new(true, new BrepBody(builder.Model, geometry, bindings), SurfacePatchFamily.Planar, true,
[
@@ -860,6 +860,17 @@ internal sealed record EmittedTopologyIdentityEntry(
InternalTrimIdentityToken? TrimIdentityToken,
EmittedTopologyRole Role,
string OrientationPolicy,
+ IReadOnlyList<string> Diagnostics,
+ EmittedTopologyReference? TopologyReference = null);
+
+internal sealed record EmittedTopologyReference(
+ string PatchKey,
+ string LocalTopologyKey,
+ string? FaceId,
+ string? LoopId,
+ string? EdgeId,
+ string? CoedgeId,
+ string? VertexId,
IReadOnlyList<string> Diagnostics);
internal sealed record EmittedTopologyIdentityMap(
@@ -986,9 +997,9 @@ internal sealed class CylindricalSurfaceMaterializer : ISurfaceFamilyMaterialize
}
var cylIdentity = new EmittedTopologyIdentityMap(
[
- new($"edge:{seamEdge.Value}", EmittedTopologyKind.Seam, null, EmittedTopologyRole.CylindricalSeam, "self-closure-forward-reverse", ["cylindrical seam role tagged for self-closure evidence."]),
- new($"edge:{topCircleEdge.Value}", EmittedTopologyKind.Edge, topToken, EmittedTopologyRole.CylindricalTopBoundary, "follow-mouth-loop", [topToken is null ? "cylindrical top boundary token missing or ambiguous in retained loop evidence." : "cylindrical top boundary token attached from retained loop evidence."]),
- new($"edge:{bottomCircleEdge.Value}", EmittedTopologyKind.Edge, bottomToken, EmittedTopologyRole.CylindricalBottomBoundary, "follow-mouth-loop", [bottomToken is null ? "cylindrical bottom boundary token missing or ambiguous in retained loop evidence." : "cylindrical bottom boundary token attached from retained loop evidence."])
+ new($"edge:{seamEdge.Value}", EmittedTopologyKind.Seam, null, EmittedTopologyRole.CylindricalSeam, "self-closure-forward-reverse", ["cylindrical seam role tagged for self-closure evidence."], new EmittedTopologyReference(candidate.SourceSurface.Provenance, $"edge:{seamEdge.Value}", face.Value.ToString(), loopId.Value.ToString(), seamEdge.Value.ToString(), coedgeIds[0].Value.ToString(), seamStart.Value.ToString(), ["topology-ref: cylindrical-seam attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"])),
+ new($"edge:{topCircleEdge.Value}", EmittedTopologyKind.Edge, topToken, EmittedTopologyRole.CylindricalTopBoundary, "follow-mouth-loop", [topToken is null ? "cylindrical top boundary token missing or ambiguous in retained loop evidence." : "cylindrical top boundary token attached from retained loop evidence."], new EmittedTopologyReference(candidate.SourceSurface.Provenance, $"edge:{topCircleEdge.Value}", face.Value.ToString(), loopId.Value.ToString(), topCircleEdge.Value.ToString(), coedgeIds[1].Value.ToString(), topVertex.Value.ToString(), ["topology-ref: cylindrical-boundary attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"])),
+ new($"edge:{bottomCircleEdge.Value}", EmittedTopologyKind.Edge, bottomToken, EmittedTopologyRole.CylindricalBottomBoundary, "follow-mouth-loop", [bottomToken is null ? "cylindrical bottom boundary token missing or ambiguous in retained loop evidence." : "cylindrical bottom boundary token attached from retained loop evidence."], new EmittedTopologyReference(candidate.SourceSurface.Provenance, $"edge:{bottomCircleEdge.Value}", face.Value.ToString(), loopId.Value.ToString(), bottomCircleEdge.Value.ToString(), coedgeIds[3].Value.ToString(), bottomVertex.Value.ToString(), ["topology-ref: cylindrical-boundary attached", "topology-ref-face-id: attached", "topology-ref-loop-id: attached", "topology-ref-edge-id: attached", "topology-ref-coedge-id: attached"]))
]);
return new(true, body, SurfacePatchFamily.Cylindrical, true,
[
diff --git a/docs/cir-brep-t4-emitted-topology-references.md b/docs/cir-brep-t4-emitted-topology-references.md
new file mode 100644
index 00000000..40f2c094
--- /dev/null
+++ b/docs/cir-brep-t4-emitted-topology-references.md
@@ -0,0 +1,30 @@
+# CIR-BREP-T4: concrete emitted topology references in identity maps
+
+## Purpose
+CIR-BREP-T4 extends internal emitted topology identity metadata with concrete BRep topology references (face/loop/edge/coedge/vertex ids) so bounded stitch execution can locate emitted entities deterministically.
+
+## Reference model
+`EmittedTopologyIdentityEntry` now carries optional `TopologyReference` (`EmittedTopologyReference`) with:
+- patch key
+- local topology key
+- face/loop/edge/coedge/vertex ids (nullable where not applicable)
+- diagnostics
+
+## Behavior
+- Planar rectangle-with-inner-circle emission attaches topology references on inner circular trim identity entries.
+- Planar patch-set entry identity maps preserve those references unchanged.
+- Cylindrical retained wall emission attaches topology references for seam/top/bottom boundary entries.
+
+## Stitch executor awareness
+`SurfaceFamilyStitchExecutor` now distinguishes:
+- missing concrete topology references (still deferred), versus
+- topology references ready (diagnosed), but mutation/remap not implemented in T4.
+
+No topology mutation/merge is performed in this milestone.
+
+## SEM-A0 boundary
+These references are internal emitted-topology diagnostics only.
+They are not public topology names, selectors, or PMI references.
+
+## Next step (T5)
+Implement bounded cross-body topology remap + mutation path that consumes ready topology references and performs deterministic stitch operations behind explicit admissibility gates.