Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-F15.1: tighten planar patch-set token diagnostics

Yuechen Li4de9fa9c6b58
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
index a7061e92..7e6b96a2 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
@@ -44,10 +44,12 @@ public sealed class SurfaceFamilyShellAssemblerTests
}
[Fact]
- public void ShellAssembler_CanSeeTokenMatchedEmittedTopologyCandidates()
+ public void ShellAssembler_SeesMatchingPlanarAndCylindricalEmittedTokens()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));
var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);
+ Assert.Contains(result.Diagnostics, d => d.Contains("planar-inner-circle-token", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.Diagnostics, d => d.Contains("cylindrical-seam-role-tagged", StringComparison.OrdinalIgnoreCase));
Assert.Contains(result.Diagnostics, d => d.Contains("token-match-candidates", StringComparison.OrdinalIgnoreCase));
Assert.False(result.FullShellAssembled);
}
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index ec407731..6a4889d2 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -1,3 +1,4 @@
+using Aetheris.Kernel.Core.Brep;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Cir;
@@ -319,6 +320,16 @@ public sealed class SurfacePatchDescriptorScaffoldTests
if (hasInner) Assert.Contains(result.Entries, e => e.IdentityMap is not null && e.IdentityMap.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim));
}
+
+ [Fact]
+ public void PlanarPatchSet_BoxMinusCylinder_NoInnerCircleTokenWhenNoRetainedCircleEvidence()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.DoesNotContain(result.Entries.SelectMany(e => e.IdentityMap?.Entries ?? []), e => e.Role == EmittedTopologyRole.InnerCircularTrim && e.TrimIdentityToken is not null);
+ Assert.Contains(result.Entries, e => e.Emitted && e.Diagnostics.Any(d => d.Contains("emitted-untrimmed-planar-patch", StringComparison.OrdinalIgnoreCase)));
+ }
+
[Fact]
public void CylindricalSurfaceMaterializer_BoxMinusCylinder_ToolWall_FromRealEvidence_EmitsTopology()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index 5872b733..4c605b0f 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -307,7 +307,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
{
if (candidate.RetentionRole != FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-candidate: retention role is not base-boundary retained outside tool."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-candidate-role: retention role {candidate.RetentionRole} is not base-boundary retained outside tool."]));
continue;
}
@@ -333,7 +333,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
{
if (candidate.SourceSurface.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle })
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required.", "skipped-missing-retained-circle-geometry: no exact-ready canonical retained circular loop geometry found for this candidate."]));
continue;
}
@@ -359,14 +359,14 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
if (retainedCircles.Length > 1)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-multiple-inner-loops: multiple retained circular loops are unsupported in CIR-F10.8."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-multiple-inner-loops: found {retainedCircles.Length} exact-ready retained circular loops; only one is supported in CIR-F10.8."]));
continue;
}
var normalizedTrimmedSource = candidate.SourceSurface;
if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var trimmedPayload, out _))
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch.", "skipped-inner-circle-evidence-unusable: canonical inner loop evidence existed, but rectangle payload normalization failed."]));
continue;
}
@@ -379,7 +379,14 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
}
emittedBodies.Add(emission.Body!);
- entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, ["emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop."]));
+ var innerTokenPresent = emission.IdentityMap?.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim && x.TrimIdentityToken is not null) == true;
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap,
+ [
+ "emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop.",
+ innerTokenPresent
+ ? "emitted-identity-token-attached: inner circular trim token attached on emitted planar topology."
+ : "emitted-identity-token-missing: inner circular trim topology emitted but token evidence was unavailable."
+ ]));
}
var emittedCount = entries.Count(e => e.Emitted);
diff --git a/docs/cir-f151-planar-patchset-inner-circle-token.md b/docs/cir-f151-planar-patchset-inner-circle-token.md
new file mode 100644
index 00000000..b8210111
--- /dev/null
+++ b/docs/cir-f151-planar-patchset-inner-circle-token.md
@@ -0,0 +1,44 @@
+# CIR-F15.1 — real planar patch-set inner-circle token propagation
+
+## Root cause
+
+In the real `PlanarSurfaceMaterializer.EmitSupportedPlanarPatches(...)` path for `Subtract(Box,Cylinder)`, inner-circle patch emission already occurred when canonical retained circular loop evidence existed, but entry-level diagnostics were too weak to distinguish why candidates were skipped and whether emitted inner-circle topology carried a token.
+
+This made the gap look like missing emission/token propagation even when emission occurred, and blocked confident downstream visibility checks.
+
+Root-cause bucket: **G (diagnostic precision gap)**.
+
+## Fix scope
+
+- Tightened planar patch-set diagnostics with explicit skip categories:
+ - candidate role mismatch,
+ - readiness gate,
+ - missing rectangle geometry,
+ - missing retained-circle evidence,
+ - multiple inner loops.
+- Added explicit emitted diagnostics for inner-circle token attachment vs token-missing cases.
+- Preserved conservative behavior (no readiness bypass, no multi-loop emission, no non-planar emission).
+
+## Identity propagation behavior
+
+For base-side planar exact-ready candidates with one canonical retained circular loop, the real patch-set path emits a rectangular face with one inner circular loop and retains `InternalTrimIdentityToken` in emitted topology identity metadata (inner edge/coedge/loop entries).
+
+## Shell assembler visibility
+
+No shell merge was added.
+
+`SurfaceFamilyShellAssembler` continues dry-run visibility only, now with stronger diagnostics exercised in tests for:
+- planar inner-circle token visibility,
+- cylindrical token role visibility,
+- emitted token match-candidate visibility.
+
+## Non-goals preserved
+
+- No shell assembly/merge/stitch implementation.
+- No STEP export behavior change.
+- No boolean behavior expansion.
+- No generated user-facing topology naming (SEM-A0 preserved).
+
+## Recommended F16 next step
+
+Consume emitted identity maps + dry-run planned pairings in a bounded stitch planner that proves one deterministic shared-trim closure action for `Subtract(Box,Cylinder)` without introducing coordinate-based matching heuristics.