Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-F14 scaffold bounded surface-family shell assembler

Yuechen Li80d25fdc5190
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
new file mode 100644
index 00000000..7f061ce5
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyShellAssemblerTests.cs
@@ -0,0 +1,45 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfaceFamilyShellAssemblerTests
+{
+ [Fact]
+ public void SurfaceFamilyShellAssembler_BoxMinusCylinder_RejectsWhenReadinessDeferred()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2));
+
+ var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);
+
+ Assert.False(result.Success);
+ Assert.Null(result.Body);
+ Assert.Contains(result.Diagnostics, d => d.Contains("readiness-gate-rejected", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFamilyShellAssembler_BoxMinusCylinder_ReportsReadinessBlockerForCanonicalCase()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));
+
+ var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);
+
+ Assert.False(result.Success);
+ Assert.Null(result.Body);
+ Assert.True(result.PlanarPatchCount > 0);
+ Assert.True(result.CylindricalPatchConsumed);
+ Assert.Equal(ShellClosureReadiness.Deferred, result.Readiness);
+ Assert.Contains(result.Diagnostics, d => d.Contains("readiness-gate-rejected", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFamilyShellAssembler_BoxMinusCylinder_SummaryIncludesPlanarAndCylindricalFamilies()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 12));
+
+ var result = SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder(root);
+
+ Assert.True(result.PlanarPatchCount > 0);
+ Assert.True(result.CylindricalPatchConsumed);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs
new file mode 100644
index 00000000..aa18cadd
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyShellAssembler.cs
@@ -0,0 +1,49 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal sealed record SurfaceFamilyShellAssemblyResult(
+ bool Success,
+ BrepBody? Body,
+ string Pattern,
+ ShellClosureReadiness Readiness,
+ bool FullShellAssembled,
+ int PlanarPatchCount,
+ bool CylindricalPatchConsumed,
+ IReadOnlyList<string> Diagnostics);
+
+internal static class SurfaceFamilyShellAssembler
+{
+ internal static SurfaceFamilyShellAssemblyResult TryAssembleBoxMinusCylinder(
+ CirNode root,
+ NativeGeometryReplayLog? replayLog = null)
+ {
+ _ = replayLog;
+ var dryRun = ShellStitchingDryRunPlanner.Generate(root);
+ var diagnostics = new List<string>
+ {
+ "pattern: subtract(box,cylinder)",
+ $"readiness-gate-state: {dryRun.Readiness}"
+ };
+
+ var planarPatchCount = dryRun.PlannedPatches.Count(p => p.SurfaceFamily == SurfacePatchFamily.Planar);
+ var hasCylinderPatch = dryRun.PlannedPatches.Any(p => p.SurfaceFamily == SurfacePatchFamily.Cylindrical);
+ diagnostics.Add($"planar-patches-consumed: {planarPatchCount}");
+ diagnostics.Add($"cylindrical-patch-consumed: {hasCylinderPatch}");
+
+ if (dryRun.Readiness != ShellClosureReadiness.ReadyForAssemblyEvidence)
+ {
+ diagnostics.Add("readiness-gate-rejected: no shell-readiness, no assembly.");
+ diagnostics.AddRange(dryRun.Diagnostics);
+ return new(false, null, CirBrepMaterializer.BoxMinusCylinderPattern, dryRun.Readiness, false, planarPatchCount, hasCylinderPatch, diagnostics);
+ }
+
+ diagnostics.Add("readiness-gate-accepted: shell evidence is ready.");
+ diagnostics.Add("shell-assembly-blocked: emitted patch bodies do not currently provide stable cross-patch topology identity remap metadata required for deterministic merge-by-evidence.");
+ diagnostics.Add("next-blocker: add explicit emitted-edge identity mapping from InternalTrimIdentityToken -> patch-local edge/coedge ids.");
+ diagnostics.AddRange(dryRun.Diagnostics);
+
+ return new(false, null, CirBrepMaterializer.BoxMinusCylinderPattern, dryRun.Readiness, false, planarPatchCount, hasCylinderPatch, diagnostics);
+ }
+}
diff --git a/docs/cir-f14-first-shell-assembly.md b/docs/cir-f14-first-shell-assembly.md
new file mode 100644
index 00000000..4ec36dad
--- /dev/null
+++ b/docs/cir-f14-first-shell-assembly.md
@@ -0,0 +1,39 @@
+# CIR-F14 — First Surface-Family Shell Assembly (Bounded `subtract(box,cylinder)`)
+
+## Outcome
+
+**Meaningful progression**.
+
+A bounded assembler entrypoint was added and hard-gated by F13 readiness (`no shell-readiness, no assembly`).
+The real blocker is now isolated: emitted patch bodies do not yet expose deterministic cross-patch topology identity remap metadata needed to merge patch-local topology into one coherent shell using evidence-only pairing.
+
+## Supported shape (current)
+
+- `subtract(box,cylinder)` only (canonical through-hole family).
+
+## Readiness gate
+
+`SurfaceFamilyShellAssembler.TryAssembleBoxMinusCylinder` always runs `ShellStitchingDryRunPlanner.Generate(root)` first.
+
+- If readiness is not `ReadyForAssemblyEvidence`: reject and return diagnostics.
+- If readiness is accepted: still refuse assembly until topology identity remap metadata exists.
+
+## Assembly strategy status
+
+Current implementation is **diagnostic-first scaffold**.
+It consumes F10.8/F11/F13 evidence and emitted-patch summaries, but intentionally does not guess topology merges.
+
+## Evidence requirements for next step
+
+Need explicit mapping from pairing evidence token (`InternalTrimIdentityToken` / planned pair token) to emitted patch-local edge/coedge identities so assembly can stitch by evidence, not coordinate coincidence.
+
+## Non-goals preserved
+
+- no production rematerializer replacement,
+- no STEP behavior changes,
+- no CLI exposure changes,
+- no generated topology naming/selectors.
+
+## Next step
+
+Extend planar/cylindrical emission results with stable edge/coedge identity metadata keyed by pairing evidence tokens, then implement deterministic shell merge and add success-path export smoke.