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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.