Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F13 seam/orientation shell stitching evidence

Yuechen Liffa4858c3014
diff --git a/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs
index 72e6cf04..ab602d83 100644
--- a/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs
@@ -6,52 +6,64 @@ namespace Aetheris.Kernel.Firmament.Tests;
public sealed class ShellStitchingDryRunTests
{
[Fact]
- public void ShellStitching_BoxMinusCylinder_ConsumesPlanarAndCylindricalPatches()
+ public void ShellStitching_BoxMinusCylinder_AccountsForCylindricalSeam()
{
var result = ShellStitchingDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
- Assert.Contains(result.PlannedPatches, p => p.SurfaceFamily == SurfacePatchFamily.Planar);
- Assert.Contains(result.PlannedPatches, p => p.SurfaceFamily == SurfacePatchFamily.Cylindrical);
- Assert.False(result.ShellAssemblyImplemented);
- Assert.Contains(result.Diagnostics, d => d.Contains("dry-run", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.SeamClosureEvidence, e => e.SeamKind == SeamKind.CylindricalSelfSeam || e.SeamKind == SeamKind.SeamDeferred);
+ Assert.True(result.SeamClosureEvidence.Any(e => e.SeamKind == SeamKind.CylindricalSelfSeam)
+ || result.SeamClosureEvidence.Any(e => e.Diagnostics.Any(d => d.Contains("missing-metadata", StringComparison.OrdinalIgnoreCase))));
}
[Fact]
- public void ShellStitching_BoxMinusCylinder_ReportsPairingEvidence()
+ public void ShellStitching_BoxMinusCylinder_ChecksOrientationCompatibility()
{
var result = ShellStitchingDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
- Assert.True(result.PlannedPairs.Count > 0
- || result.Diagnostics.Any(d => d.Contains("missing one-to-one identity", StringComparison.OrdinalIgnoreCase))
- || result.UnpairedBoundaries.Any(u => u.Reason.Contains("identity", StringComparison.OrdinalIgnoreCase)));
+ Assert.NotEmpty(result.OrientationEvidence);
+ Assert.All(result.OrientationEvidence, e => Assert.True(
+ e.OrientationStatus is OrientationCompatibilityStatus.Compatible or OrientationCompatibilityStatus.Deferred));
}
[Fact]
- public void ShellStitching_BoxMinusCylinder_ReportsUnpairedOrDeferredBoundaries()
+ public void ShellStitching_BoxMinusCylinder_ReclassifiesExpectedSeamBoundaries()
{
var result = ShellStitchingDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
- Assert.True(result.UnpairedBoundaries.Count > 0 || result.Readiness == ShellClosureReadiness.ReadyForAssemblyEvidence);
+ if (result.SeamClosureEvidence.Any(e => e.SeamKind == SeamKind.CylindricalSelfSeam))
+ {
+ Assert.DoesNotContain(result.UnpairedBoundaries, u => u.Patch.Contains("Cylindrical", StringComparison.OrdinalIgnoreCase));
+ }
}
[Fact]
- public void ShellStitching_BoxMinusCylinder_DoesNotClaimFullShell()
+ public void ShellStitching_BoxMinusCylinder_ReadinessPromotionIsConservative()
{
var result = ShellStitchingDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+ if (result.UnpairedBoundaries.Count == 0
+ && result.SeamClosureEvidence.All(e => e.Readiness != ShellClosureReadiness.Deferred)
+ && result.OrientationEvidence.All(e => e.OrientationStatus == OrientationCompatibilityStatus.Compatible))
+ {
+ Assert.Equal(ShellClosureReadiness.ReadyForAssemblyEvidence, result.Readiness);
+ }
+ else
+ {
+ Assert.Equal(ShellClosureReadiness.Deferred, result.Readiness);
+ }
+
Assert.False(result.ShellAssemblyImplemented);
- Assert.NotEqual(ShellClosureReadiness.ReadyForAssemblyEvidence, result.Readiness);
}
[Fact]
- public void ShellStitching_DeterministicOrdering()
+ public void ShellStitching_DeterministicEvidenceOrdering()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
var first = ShellStitchingDryRunPlanner.Generate(root);
var second = ShellStitchingDryRunPlanner.Generate(root);
- Assert.Equal(first.PlannedPatches.Select(p => p.SourceCandidateKey), second.PlannedPatches.Select(p => p.SourceCandidateKey));
- Assert.Equal(first.PlannedPairs.Select(p => p.EdgeToken), second.PlannedPairs.Select(p => p.EdgeToken));
+ Assert.Equal(first.SeamClosureEvidence.Select(e => e.PatchKey), second.SeamClosureEvidence.Select(e => e.PatchKey));
+ Assert.Equal(first.OrientationEvidence.Select(e => e.PairKey), second.OrientationEvidence.Select(e => e.PairKey));
Assert.Equal(first.UnpairedBoundaries.Select(u => $"{u.Patch}|{u.Loop}|{u.Reason}"), second.UnpairedBoundaries.Select(u => $"{u.Patch}|{u.Loop}|{u.Reason}"));
}
}
diff --git a/Aetheris.Kernel.Firmament/Execution/ShellStitchingDryRun.cs b/Aetheris.Kernel.Firmament/Execution/ShellStitchingDryRun.cs
index e9daeaa9..6bbefad8 100644
--- a/Aetheris.Kernel.Firmament/Execution/ShellStitchingDryRun.cs
+++ b/Aetheris.Kernel.Firmament/Execution/ShellStitchingDryRun.cs
@@ -14,9 +14,40 @@ internal enum StitchingOrientationCompatibility
{
Compatible,
Incompatible,
- Deferred
+ Deferred,
+ NotApplicable
+}
+
+internal enum SeamKind
+{
+ CylindricalSelfSeam,
+ NoSeamRequired,
+ SeamDeferred,
+ Unsupported
+}
+
+internal enum OrientationCompatibilityStatus
+{
+ Compatible,
+ Deferred,
+ Incompatible,
+ NotApplicable
}
+internal sealed record SeamClosureEvidence(
+ string PatchKey,
+ SeamKind SeamKind,
+ ShellClosureReadiness Readiness,
+ string Evidence,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record OrientationCompatibilityEvidence(
+ string PairKey,
+ OrientationCompatibilityStatus OrientationStatus,
+ ShellClosureReadiness Readiness,
+ string Evidence,
+ IReadOnlyList<string> Diagnostics);
+
internal sealed record PlannedShellPatch(
string SourceCandidateKey,
SurfacePatchFamily SurfaceFamily,
@@ -46,6 +77,8 @@ internal sealed record ShellStitchingDryRunResult(
ShellClosureReadiness Readiness,
IReadOnlyList<PlannedShellPatch> PlannedPatches,
IReadOnlyList<PlannedShellEdgePair> PlannedPairs,
+ IReadOnlyList<SeamClosureEvidence> SeamClosureEvidence,
+ IReadOnlyList<OrientationCompatibilityEvidence> OrientationEvidence,
IReadOnlyList<UnpairedBoundaryEvidence> UnpairedBoundaries,
IReadOnlyList<string> Diagnostics,
bool ShellAssemblyImplemented);
@@ -75,15 +108,19 @@ internal static class ShellStitchingDryRunPlanner
};
var patches = BuildPatches(planar, cylindricalCandidate, cylindricalEmission, diagnostics);
+ var seamEvidence = BuildSeamEvidence(patches, diagnostics);
var pairs = BuildPairs(pairing, diagnostics);
- var unpaired = BuildUnpaired(pairing, pairs, diagnostics);
+ var orientationEvidence = BuildOrientationEvidence(pairs, diagnostics);
+ var unpaired = BuildUnpaired(pairing, pairs, seamEvidence, diagnostics);
- var readiness = ResolveReadiness(patches, pairs, unpaired);
+ var readiness = ResolveReadiness(patches, pairs, orientationEvidence, seamEvidence, unpaired);
return new ShellStitchingDryRunResult(
Success: patches.Count > 0,
Readiness: readiness,
PlannedPatches: patches,
PlannedPairs: pairs,
+ SeamClosureEvidence: seamEvidence,
+ OrientationEvidence: orientationEvidence,
UnpairedBoundaries: unpaired,
Diagnostics: diagnostics.Distinct().ToArray(),
ShellAssemblyImplemented: false);
@@ -128,6 +165,37 @@ internal static class ShellStitchingDryRunPlanner
return patches.OrderBy(p => p.SourceCandidateKey, StringComparer.Ordinal).ToList();
}
+
+ private static List<SeamClosureEvidence> BuildSeamEvidence(IReadOnlyList<PlannedShellPatch> patches, List<string> diagnostics)
+ {
+ var seam = new List<SeamClosureEvidence>();
+ foreach (var patch in patches.OrderBy(p => p.SourceCandidateKey, StringComparer.Ordinal))
+ {
+ if (patch.SurfaceFamily != SurfacePatchFamily.Cylindrical)
+ {
+ seam.Add(new SeamClosureEvidence(patch.SourceCandidateKey, SeamKind.NoSeamRequired, ShellClosureReadiness.NotApplicable,
+ "seam-not-applicable: planar patches do not require cylindrical self-seam closure evidence.", []));
+ continue;
+ }
+
+ var hasConvention = patch.Diagnostics.Any(d => d.Contains("seam-convention-applied", StringComparison.OrdinalIgnoreCase));
+ if (hasConvention)
+ {
+ var evidence = "seam-self-closed: cylindrical patch reports side seam forward/reversed coedge convention.";
+ seam.Add(new SeamClosureEvidence(patch.SourceCandidateKey, SeamKind.CylindricalSelfSeam, ShellClosureReadiness.ReadyForAssemblyEvidence, evidence, [evidence]));
+ diagnostics.Add($"seam-accounted-self-closure: patch={patch.SourceCandidateKey}");
+ }
+ else
+ {
+ var evidence = "seam-closure-deferred-missing-metadata: cylindrical patch diagnostics did not expose seam forward/reversed convention evidence.";
+ seam.Add(new SeamClosureEvidence(patch.SourceCandidateKey, SeamKind.SeamDeferred, ShellClosureReadiness.Deferred, evidence, [evidence]));
+ diagnostics.Add($"seam-closure-deferred: patch={patch.SourceCandidateKey} missing seam convention evidence");
+ }
+ }
+
+ return seam;
+ }
+
private static List<PlannedShellEdgePair> BuildPairs(TopologyPairingEvidenceResult pairing, List<string> diagnostics)
{
var pairs = new List<PlannedShellEdgePair>();
@@ -156,7 +224,37 @@ internal static class ShellStitchingDryRunPlanner
return pairs;
}
- private static List<UnpairedBoundaryEvidence> BuildUnpaired(TopologyPairingEvidenceResult pairing, IReadOnlyList<PlannedShellEdgePair> pairs, List<string> diagnostics)
+
+ private static List<OrientationCompatibilityEvidence> BuildOrientationEvidence(IReadOnlyList<PlannedShellEdgePair> pairs, List<string> diagnostics)
+ {
+ var evidence = new List<OrientationCompatibilityEvidence>();
+ foreach (var pair in pairs.OrderBy(p => p.EdgeToken, StringComparer.Ordinal))
+ {
+ var status = pair.OrientationCompatibility switch
+ {
+ StitchingOrientationCompatibility.Compatible => OrientationCompatibilityStatus.Compatible,
+ StitchingOrientationCompatibility.Incompatible => OrientationCompatibilityStatus.Incompatible,
+ StitchingOrientationCompatibility.Deferred => OrientationCompatibilityStatus.Deferred,
+ _ => OrientationCompatibilityStatus.NotApplicable
+ };
+
+ var msg = status switch
+ {
+ OrientationCompatibilityStatus.Compatible => "orientation-compatible: paired planar/cylindrical circular boundaries expose complementary loop orientation policies.",
+ OrientationCompatibilityStatus.Incompatible => "orientation-incompatible: paired boundaries expose non-complementary orientation policies.",
+ OrientationCompatibilityStatus.Deferred => "orientation-deferred: pairing exists but orientation compatibility cannot be proven from current policy evidence.",
+ _ => "orientation-not-applicable"
+ };
+ evidence.Add(new OrientationCompatibilityEvidence(pair.EdgeToken, status,
+ status == OrientationCompatibilityStatus.Compatible ? ShellClosureReadiness.ReadyForAssemblyEvidence : ShellClosureReadiness.Deferred,
+ msg, [msg]));
+ diagnostics.Add($"orientation-{status.ToString().ToLowerInvariant()}: pair={pair.EdgeToken}");
+ }
+
+ return evidence;
+ }
+
+ private static List<UnpairedBoundaryEvidence> BuildUnpaired(TopologyPairingEvidenceResult pairing, IReadOnlyList<PlannedShellEdgePair> pairs, IReadOnlyList<SeamClosureEvidence> seamEvidence, List<string> diagnostics)
{
var pairedTokens = pairs.Select(p => p.EdgeToken).ToHashSet(StringComparer.Ordinal);
var unpaired = new List<UnpairedBoundaryEvidence>();
@@ -168,6 +266,14 @@ internal static class ShellStitchingDryRunPlanner
continue;
}
+ var isCylindrical = edge.SourceSurfaceFamily == SurfacePatchFamily.Cylindrical;
+ var hasAccountedSeam = seamEvidence.Any(s => s.SeamKind == SeamKind.CylindricalSelfSeam);
+ if (isCylindrical && hasAccountedSeam)
+ {
+ diagnostics.Add($"unpaired-reclassified-expected-seam: patch={edge.SourceFaceKey} loop={edge.SourceLoopKey}");
+ continue;
+ }
+
var reason = edge.IdentityToken is null
? "unpaired-boundary-missing-identity-token"
: "unpaired-boundary-token-without-match";
@@ -179,12 +285,14 @@ internal static class ShellStitchingDryRunPlanner
return unpaired;
}
- private static ShellClosureReadiness ResolveReadiness(IReadOnlyList<PlannedShellPatch> patches, IReadOnlyList<PlannedShellEdgePair> pairs, IReadOnlyList<UnpairedBoundaryEvidence> unpaired)
+ private static ShellClosureReadiness ResolveReadiness(IReadOnlyList<PlannedShellPatch> patches, IReadOnlyList<PlannedShellEdgePair> pairs, IReadOnlyList<OrientationCompatibilityEvidence> orientation, IReadOnlyList<SeamClosureEvidence> seamEvidence, IReadOnlyList<UnpairedBoundaryEvidence> unpaired)
{
if (patches.Count == 0) return ShellClosureReadiness.NotApplicable;
if (patches.Any(p => p.Readiness == ShellClosureReadiness.Unsupported)) return ShellClosureReadiness.Unsupported;
if (unpaired.Count > 0) return ShellClosureReadiness.Deferred;
- if (pairs.Count > 0 && pairs.All(p => p.OrientationCompatibility == StitchingOrientationCompatibility.Compatible))
+ if (seamEvidence.Any(s => s.Readiness is ShellClosureReadiness.Deferred or ShellClosureReadiness.Unsupported)) return ShellClosureReadiness.Deferred;
+ if (orientation.Any(o => o.OrientationStatus is OrientationCompatibilityStatus.Deferred or OrientationCompatibilityStatus.Incompatible)) return ShellClosureReadiness.Deferred;
+ if (pairs.Count > 0 && orientation.Count > 0 && orientation.All(o => o.OrientationStatus == OrientationCompatibilityStatus.Compatible))
{
return ShellClosureReadiness.ReadyForAssemblyEvidence;
}
diff --git a/docs/cir-f13-seam-orientation-proof-policy.md b/docs/cir-f13-seam-orientation-proof-policy.md
new file mode 100644
index 00000000..b1154d08
--- /dev/null
+++ b/docs/cir-f13-seam-orientation-proof-policy.md
@@ -0,0 +1,71 @@
+# CIR-F13 — seam self-closure + orientation proof policy (`Subtract(Box,Cylinder)`)
+
+## Purpose
+
+CIR-F13 strengthens shell-stitching dry-run evidence for bounded `Subtract(Box,Cylinder)` by adding:
+
+- cylindrical seam self-closure accounting,
+- orientation compatibility evidence for token-paired planar/cylindrical circular boundaries,
+- conservative readiness promotion rules backed by explicit blockers.
+
+No shell assembly is implemented.
+
+## Seam self-closure evidence
+
+`ShellStitchingDryRunResult` now emits `SeamClosureEvidence` entries with:
+
+- `CylindricalSelfSeam` when cylindrical emission diagnostics include seam convention evidence (`seam-convention-applied`),
+- `NoSeamRequired` for non-cylindrical patches,
+- `SeamDeferred` when seam proof metadata is missing.
+
+This uses internal emission diagnostics only (no geometry coincidence inference).
+
+## Orientation compatibility evidence
+
+`ShellStitchingDryRunResult` now emits `OrientationEvidence` entries for each planned pair:
+
+- `Compatible` when pairing orientation policy is compatible,
+- `Deferred` when pairing exists but policy-level compatibility is not proven,
+- `Incompatible` reserved for explicit non-complementary policy evidence.
+
+## Unpaired boundary reclassification
+
+Unpaired boundaries are reclassified so cylindrical boundaries are not reported as generic blockers when a cylindrical patch already has `CylindricalSelfSeam` evidence.
+
+## Readiness promotion rule
+
+Dry-run readiness can become `ReadyForAssemblyEvidence` only when:
+
+- no unsupported patches,
+- no unpaired boundary blockers,
+- no seam deferred/unsupported evidence,
+- no deferred/incompatible orientation evidence,
+- at least one pair with compatible orientation evidence.
+
+Otherwise readiness remains `Deferred`.
+
+## Example (`Subtract(Box,Cylinder)`)
+
+Expected bounded outcome:
+
+- planar retained patch-set evidence present,
+- cylindrical retained wall patch evidence present,
+- seam accounted when seam convention metadata is present,
+- planar/cylindrical pair orientation evidence emitted,
+- shell assembly still explicitly not implemented.
+
+## JudgmentEngine usage decision
+
+JudgmentEngine was not added in CIR-F13 because seam/orientation/readiness are deterministic reductions over existing bounded evidence states with no competing candidate strategies.
+
+## SEM-A0 guardrail status
+
+Preserved:
+
+- no generated topology naming,
+- no public topology selector changes,
+- internal diagnostics/evidence only.
+
+## Next step
+
+Implement actual shell assembly as a separate milestone only after CIR-F13 evidence is stable across broader bounded subtract variants.