Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F12 shell stitching dry-run evidence for box-cylinder

Yuechen Li5ab8f1298ea4
diff --git a/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs
new file mode 100644
index 00000000..72e6cf04
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/ShellStitchingDryRunTests.cs
@@ -0,0 +1,57 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class ShellStitchingDryRunTests
+{
+ [Fact]
+ public void ShellStitching_BoxMinusCylinder_ConsumesPlanarAndCylindricalPatches()
+ {
+ 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));
+ }
+
+ [Fact]
+ public void ShellStitching_BoxMinusCylinder_ReportsPairingEvidence()
+ {
+ 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)));
+ }
+
+ [Fact]
+ public void ShellStitching_BoxMinusCylinder_ReportsUnpairedOrDeferredBoundaries()
+ {
+ 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);
+ }
+
+ [Fact]
+ public void ShellStitching_BoxMinusCylinder_DoesNotClaimFullShell()
+ {
+ var result = ShellStitchingDryRunPlanner.Generate(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+
+ Assert.False(result.ShellAssemblyImplemented);
+ Assert.NotEqual(ShellClosureReadiness.ReadyForAssemblyEvidence, result.Readiness);
+ }
+
+ [Fact]
+ public void ShellStitching_DeterministicOrdering()
+ {
+ 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.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
new file mode 100644
index 00000000..e9daeaa9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/ShellStitchingDryRun.cs
@@ -0,0 +1,194 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum ShellClosureReadiness
+{
+ NotApplicable,
+ ReadyForAssemblyEvidence,
+ Deferred,
+ Unsupported
+}
+
+internal enum StitchingOrientationCompatibility
+{
+ Compatible,
+ Incompatible,
+ Deferred
+}
+
+internal sealed record PlannedShellPatch(
+ string SourceCandidateKey,
+ SurfacePatchFamily SurfaceFamily,
+ string EmittedPatchKind,
+ IReadOnlyList<string> LoopKeys,
+ ShellClosureReadiness Readiness,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record PlannedShellEdgePair(
+ string EdgeToken,
+ string PatchA,
+ string PatchB,
+ string LoopA,
+ string LoopB,
+ ShellClosureReadiness Readiness,
+ StitchingOrientationCompatibility OrientationCompatibility,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record UnpairedBoundaryEvidence(
+ string Patch,
+ string Loop,
+ string Reason,
+ ShellClosureReadiness Readiness);
+
+internal sealed record ShellStitchingDryRunResult(
+ bool Success,
+ ShellClosureReadiness Readiness,
+ IReadOnlyList<PlannedShellPatch> PlannedPatches,
+ IReadOnlyList<PlannedShellEdgePair> PlannedPairs,
+ IReadOnlyList<UnpairedBoundaryEvidence> UnpairedBoundaries,
+ IReadOnlyList<string> Diagnostics,
+ bool ShellAssemblyImplemented);
+
+internal static class ShellStitchingDryRunPlanner
+{
+ internal static ShellStitchingDryRunResult Generate(CirNode root)
+ {
+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ var generation = FacePatchCandidateGenerator.Generate(root);
+ var cylindricalCandidate = generation.Candidates.SingleOrDefault(c =>
+ c.SourceSurface.Family == SurfacePatchFamily.Cylindrical
+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
+
+ var synthReadiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0, 0, 0, 0, 0, 0, 0, [], false);
+ SurfaceMaterializationResult? cylindricalEmission = null;
+ if (cylindricalCandidate is not null)
+ {
+ cylindricalEmission = new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(cylindricalCandidate, synthReadiness));
+ }
+
+ var pairing = TopologyPairingEvidenceGenerator.Generate(root);
+ var diagnostics = new List<string>
+ {
+ "scope-note: shell stitching dry-run only; shell/body assembly is not implemented.",
+ "shell-assembly-not-implemented: dry-run emits patch/pairing evidence only."
+ };
+
+ var patches = BuildPatches(planar, cylindricalCandidate, cylindricalEmission, diagnostics);
+ var pairs = BuildPairs(pairing, diagnostics);
+ var unpaired = BuildUnpaired(pairing, pairs, diagnostics);
+
+ var readiness = ResolveReadiness(patches, pairs, unpaired);
+ return new ShellStitchingDryRunResult(
+ Success: patches.Count > 0,
+ Readiness: readiness,
+ PlannedPatches: patches,
+ PlannedPairs: pairs,
+ UnpairedBoundaries: unpaired,
+ Diagnostics: diagnostics.Distinct().ToArray(),
+ ShellAssemblyImplemented: false);
+ }
+
+ private static List<PlannedShellPatch> BuildPatches(
+ PlanarSurfaceMaterializer.PlanarPatchSetMaterializationResult planar,
+ FacePatchCandidate? cylindricalCandidate,
+ SurfaceMaterializationResult? cylindricalEmission,
+ List<string> diagnostics)
+ {
+ var patches = new List<PlannedShellPatch>();
+ foreach (var entry in planar.Entries.Where(e => e.Emitted).OrderBy(e => e.Candidate.SourceSurface.Provenance, StringComparer.Ordinal))
+ {
+ var loopKeys = entry.Candidate.RetainedRegionLoopGroups.Select(g => g.OrderingKey).DefaultIfEmpty("outer-boundary").OrderBy(k => k, StringComparer.Ordinal).ToArray();
+ patches.Add(new PlannedShellPatch(
+ SourceCandidateKey: entry.Candidate.SourceSurface.Provenance,
+ SurfaceFamily: SurfacePatchFamily.Planar,
+ EmittedPatchKind: "planar-retained-base-patch",
+ LoopKeys: loopKeys,
+ Readiness: ShellClosureReadiness.Deferred,
+ Diagnostics: entry.Diagnostics));
+ diagnostics.Add($"planar-patch-emitted: candidate={entry.Candidate.SourceSurface.Provenance}");
+ }
+
+ if (cylindricalCandidate is not null)
+ {
+ var loopKeys = cylindricalCandidate.RetainedRegionLoopGroups.Select(g => g.OrderingKey).OrderBy(k => k, StringComparer.Ordinal).ToArray();
+ var emitted = cylindricalEmission?.Success == true;
+ patches.Add(new PlannedShellPatch(
+ SourceCandidateKey: cylindricalCandidate.SourceSurface.Provenance,
+ SurfaceFamily: SurfacePatchFamily.Cylindrical,
+ EmittedPatchKind: emitted ? "cylindrical-retained-wall-patch" : "cylindrical-retained-wall-patch-deferred",
+ LoopKeys: loopKeys,
+ Readiness: emitted ? ShellClosureReadiness.Deferred : ShellClosureReadiness.Unsupported,
+ Diagnostics: cylindricalEmission?.Diagnostics ?? ["cylindrical-patch-emission-missing: no emitted cylindrical retained wall patch was available."]));
+ diagnostics.Add(emitted
+ ? $"cylindrical-patch-emitted: candidate={cylindricalCandidate.SourceSurface.Provenance}"
+ : $"cylindrical-patch-deferred: candidate={cylindricalCandidate.SourceSurface.Provenance}");
+ }
+
+ return patches.OrderBy(p => p.SourceCandidateKey, StringComparer.Ordinal).ToList();
+ }
+
+ private static List<PlannedShellEdgePair> BuildPairs(TopologyPairingEvidenceResult pairing, List<string> diagnostics)
+ {
+ var pairs = new List<PlannedShellEdgePair>();
+ foreach (var p in pairing.PlannedCoedgePairings.Where(p => p.PairingKind == PlannedCoedgePairingKind.SharedTrimIdentity).OrderBy(p => p.OrderingKey, StringComparer.Ordinal))
+ {
+ var orientation = p.EdgeUseA.OrientationPolicy == p.EdgeUseB.OrientationPolicy
+ ? StitchingOrientationCompatibility.Compatible
+ : StitchingOrientationCompatibility.Deferred;
+ pairs.Add(new PlannedShellEdgePair(
+ EdgeToken: p.EdgeUseA.IdentityToken?.OrderingKey ?? p.OrderingKey,
+ PatchA: p.EdgeUseA.SourceFaceKey,
+ PatchB: p.EdgeUseB.SourceFaceKey,
+ LoopA: p.EdgeUseA.SourceLoopKey,
+ LoopB: p.EdgeUseB.SourceLoopKey,
+ Readiness: ShellClosureReadiness.Deferred,
+ OrientationCompatibility: orientation,
+ Diagnostics: p.Diagnostics));
+ diagnostics.Add($"pairing-found-by-token: {p.Evidence}");
+ }
+
+ if (pairing.PlannedCoedgePairings.Any(p => p.PairingKind == PlannedCoedgePairingKind.Deferred))
+ {
+ diagnostics.Add("pairing-deferred: one or more boundaries are missing one-to-one identity token evidence.");
+ }
+
+ return pairs;
+ }
+
+ private static List<UnpairedBoundaryEvidence> BuildUnpaired(TopologyPairingEvidenceResult pairing, IReadOnlyList<PlannedShellEdgePair> pairs, List<string> diagnostics)
+ {
+ var pairedTokens = pairs.Select(p => p.EdgeToken).ToHashSet(StringComparer.Ordinal);
+ var unpaired = new List<UnpairedBoundaryEvidence>();
+ foreach (var edge in pairing.PlannedEdgeUses.OrderBy(e => e.OrderingKey, StringComparer.Ordinal))
+ {
+ var token = edge.IdentityToken?.OrderingKey;
+ if (token is not null && pairedTokens.Contains(token))
+ {
+ continue;
+ }
+
+ var reason = edge.IdentityToken is null
+ ? "unpaired-boundary-missing-identity-token"
+ : "unpaired-boundary-token-without-match";
+ unpaired.Add(new UnpairedBoundaryEvidence(edge.SourceFaceKey, edge.SourceLoopKey, reason, ShellClosureReadiness.Deferred));
+ }
+
+ if (unpaired.Count > 0) diagnostics.Add($"unpaired-boundary-remaining: count={unpaired.Count}");
+ diagnostics.Add("seam-closure-deferred: cylindrical seam self-closure accounting is diagnostic-only in CIR-F12.");
+ return unpaired;
+ }
+
+ private static ShellClosureReadiness ResolveReadiness(IReadOnlyList<PlannedShellPatch> patches, IReadOnlyList<PlannedShellEdgePair> pairs, 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))
+ {
+ return ShellClosureReadiness.ReadyForAssemblyEvidence;
+ }
+
+ return ShellClosureReadiness.Deferred;
+ }
+}
diff --git a/docs/cir-f12-shell-stitching-dry-run.md b/docs/cir-f12-shell-stitching-dry-run.md
new file mode 100644
index 00000000..730c7e1c
--- /dev/null
+++ b/docs/cir-f12-shell-stitching-dry-run.md
@@ -0,0 +1,64 @@
+# CIR-F12 — Shell stitching dry-run / coedge pairing validation (`Subtract(Box, Cylinder)`)
+
+## Purpose
+
+CIR-F12 adds a bounded, diagnostic-first **shell-stitching dry-run** that consumes real emitted patch evidence from:
+
+- planar retained base patch-set emission (`PlanarSurfaceMaterializer.EmitSupportedPlanarPatches`), and
+- retained cylindrical wall emission (`CylindricalSurfaceMaterializer.EmitRetainedWall`).
+
+It validates stitching evidence only. It does **not** assemble a shell/body and does not change STEP/export behavior.
+
+## Dry-run model
+
+`ShellStitchingDryRunPlanner.Generate` returns `ShellStitchingDryRunResult` with:
+
+- `PlannedPatches` inventory (planar + cylindrical pieces),
+- `PlannedPairs` inferred from `InternalTrimIdentityToken` evidence,
+- `UnpairedBoundaries` with explicit reasons,
+- `Readiness` reduced to `ReadyForAssemblyEvidence/Deferred/Unsupported`, and
+- `ShellAssemblyImplemented=false`.
+
+## Pairing / closure evidence behavior
+
+- Pairing is promoted from existing `TopologyPairingEvidenceGenerator` `SharedTrimIdentity` evidence.
+- Boundaries without one-to-one token matches remain unpaired and are reported as deferred.
+- Cylindrical seam closure is explicitly recorded as deferred diagnostic-only accounting in this milestone.
+- Orientation compatibility is currently conservative (`Compatible` only when loop policies match, else `Deferred`).
+
+## Expected box-cylinder outcome
+
+For `Subtract(Box,Cylinder)`, CIR-F12 is expected to report:
+
+- emitted planar retained patch entries,
+- emitted (or explicit deferred) cylindrical retained wall patch entry,
+- at least one token-driven pairing where evidence exists,
+- remaining unpaired/deferred boundaries where closure proof is incomplete,
+- `ShellAssemblyImplemented=false`.
+
+## What remains before real shell assembly
+
+- Explicit seam self-closure policy and accounting upgrade for cylindrical side seam.
+- Stronger orientation compatibility proof across planar cavity loops and cylindrical mouth loops.
+- Boundary completeness proof that all external/open boundaries are consumed by pairing or closure rules.
+- Actual BRep shell/body stitcher (out of CIR-F12 scope).
+
+## JudgmentEngine usage decision
+
+JudgmentEngine was **not** introduced in CIR-F12:
+
+- pairing selection reuses deterministic one-to-one token evidence already resolved by prior dry-run stages,
+- closure readiness is a deterministic reduction over patch/pair/unpaired states,
+- no competing bounded candidate strategies were introduced in this milestone.
+
+## SEM-A0 guardrail status
+
+SEM-A0 remains preserved:
+
+- no generated topology naming,
+- no public topology identity surface changes,
+- internal diagnostics/evidence only.
+
+## Recommended next step
+
+CIR-F13 should add deterministic seam accounting + orientation proof policy for planar/cylindrical loop pair compatibility, then re-evaluate readiness promotion criteria before any shell assembler implementation.