Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR through-hole recovery executor for box-cylinder plans

Yuechen Lif271b854e6e0
diff --git a/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs
new file mode 100644
index 00000000..bb4128cf
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryExecutorTests.cs
@@ -0,0 +1,116 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class ThroughHoleRecoveryExecutorTests
+{
+ private static readonly ThroughHoleRecoveryPolicy Policy = new();
+
+ [Fact]
+ public void ThroughHoleExecutor_BoxCylinderPlan_ProducesBrepBody()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(20d, 10d, 8d), new CirCylinderNode(2d, 20d));
+ var plan = BuildPlanFromPlanner(root);
+
+ var result = ThroughHoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.NotNull(result.Body);
+ Assert.Contains("Box primitive constructed.", result.Diagnostics);
+ Assert.Contains(result.Diagnostics, d => d.Contains("Cylinder primitive constructed", StringComparison.Ordinal));
+ Assert.Contains("Boolean subtract succeeded.", result.Diagnostics);
+ }
+
+ [Fact]
+ public void ThroughHoleExecutor_TranslatedBoxCylinderPlan_ProducesBrepBody()
+ {
+ var root = new CirSubtractNode(
+ new CirTransformNode(new CirBoxNode(20, 20, 10), Transform3D.CreateTranslation(new Vector3D(5, 2, 4))),
+ new CirTransformNode(new CirCylinderNode(3, 16), Transform3D.CreateTranslation(new Vector3D(4, 1, 4))));
+ var plan = BuildPlanFromPlanner(root);
+
+ var result = ThroughHoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.NotNull(result.Body);
+ Assert.Contains("Boolean subtract succeeded.", result.Diagnostics);
+ }
+
+ [Fact]
+ public void ThroughHoleExecutor_RejectsUnsupportedPlanShape()
+ {
+ var unsupportedPlan = new ThroughHoleRecoveryPlan(
+ ThroughHoleHostKind.Unsupported,
+ ThroughHoleToolKind.Cylindrical,
+ ThroughHoleProfileKind.Circular,
+ ThroughHoleAxisKind.Z,
+ 10d,
+ 2d,
+ 20d,
+ 20d,
+ 10d,
+ Vector3D.Zero,
+ Vector3D.Zero,
+ [],
+ [],
+ [],
+ FrepMaterializerCapability.ExactBRep,
+ []);
+
+ var result = ThroughHoleRecoveryExecutor.Execute(unsupportedPlan);
+
+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, result.Status);
+ Assert.Null(result.Body);
+ Assert.Contains(result.Diagnostics, d => d.Contains("unsupported specialization", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void ThroughHoleExecutor_BodyHasExpectedSurfaceFamiliesOrTopologySummary()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(30d, 20d, 12d), new CirCylinderNode(4d, 24d));
+ var plan = BuildPlanFromPlanner(root);
+
+ var result = ThroughHoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.NotNull(result.Body);
+ var body = result.Body!;
+
+ Assert.True(body.Topology.Faces.Any());
+ Assert.True(body.Topology.Edges.Any());
+ Assert.True(body.Topology.Loops.Any());
+ Assert.Contains(body.Topology.Faces, face =>
+ {
+ Assert.True(body.TryGetFaceSurfaceGeometry(face.Id, out var surface));
+ return surface?.Kind == SurfaceGeometryKind.Cylinder;
+ });
+ Assert.Contains(body.Topology.Faces, face =>
+ {
+ Assert.True(body.TryGetFaceSurfaceGeometry(face.Id, out var surface));
+ return surface?.Kind == SurfaceGeometryKind.Plane;
+ });
+ }
+
+ [Fact]
+ public void ThroughHoleExecutor_DoesNotExportStep()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(20d, 10d, 8d), new CirCylinderNode(2d, 20d));
+ var plan = BuildPlanFromPlanner(root);
+
+ var result = ThroughHoleRecoveryExecutor.Execute(plan);
+
+ Assert.Equal(ThroughHoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.Contains("No STEP export attempted in CIR-RECOVERY-V2.", result.Diagnostics);
+ }
+
+ private static ThroughHoleRecoveryPlan BuildPlanFromPlanner(CirNode root)
+ {
+ var decision = FrepMaterializerPlanner.Decide(new FrepMaterializerContext(root), [Policy]);
+ var evaluation = Assert.Single(decision.Evaluations);
+ return Assert.IsType<ThroughHoleRecoveryPlan>(evaluation.Plan);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs
new file mode 100644
index 00000000..7c2ffbb6
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs
@@ -0,0 +1,91 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+public enum ThroughHoleRecoveryExecutionStatus
+{
+ Succeeded,
+ UnsupportedPlan,
+ PrimitiveConstructionFailed,
+ BooleanFailed,
+ InvalidResult,
+ Failed
+}
+
+public sealed record ThroughHoleRecoveryExecutionResult(
+ ThroughHoleRecoveryExecutionStatus Status,
+ BrepBody? Body,
+ IReadOnlyList<string> Diagnostics);
+
+public static class ThroughHoleRecoveryExecutor
+{
+ public static ThroughHoleRecoveryExecutionResult Execute(ThroughHoleRecoveryPlan plan)
+ {
+ ArgumentNullException.ThrowIfNull(plan);
+
+ var diagnostics = new List<string>
+ {
+ "ThroughHoleRecoveryExecutor started.",
+ "No STEP export attempted in CIR-RECOVERY-V2.",
+ "No rematerializer/fall-forward wiring attempted in CIR-RECOVERY-V2."
+ };
+
+ if (plan.HostKind != ThroughHoleHostKind.RectangularBox
+ || plan.ToolKind != ThroughHoleToolKind.Cylindrical
+ || plan.ProfileKind != ThroughHoleProfileKind.Circular
+ || plan.Axis != ThroughHoleAxisKind.Z)
+ {
+ diagnostics.Add($"Plan rejected: unsupported specialization host={plan.HostKind}, tool={plan.ToolKind}, profile={plan.ProfileKind}, axis={plan.Axis}.");
+ return new(ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
+
+ diagnostics.Add("Plan specialization accepted: rectangular-box + cylindrical + circular + Z-axis.");
+
+ var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);
+ if (!boxResult.IsSuccess)
+ {
+ diagnostics.Add($"Box primitive construction failed: {string.Join(" | ", boxResult.Diagnostics.Select(d => d.Message))}");
+ return new(ThroughHoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ }
+
+ var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
+ diagnostics.Add("Box primitive constructed.");
+
+ var throughLength = double.Max(plan.ThroughLength, plan.HostSizeZ);
+ var cylinderResult = BrepPrimitives.CreateCylinder(plan.ToolRadius, throughLength);
+ if (!cylinderResult.IsSuccess)
+ {
+ diagnostics.Add($"Cylinder primitive construction failed: {string.Join(" | ", cylinderResult.Diagnostics.Select(d => d.Message))}");
+ return new(ThroughHoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ }
+
+ var cylinderBody = TranslateBody(cylinderResult.Value, plan.ToolTranslation);
+ diagnostics.Add($"Cylinder primitive constructed (height={throughLength:G17}).");
+
+ diagnostics.Add("Boolean subtract invoked.");
+ var subtract = BrepBoolean.Subtract(boxBody, cylinderBody);
+ if (!subtract.IsSuccess)
+ {
+ diagnostics.Add($"Boolean subtract failed: {string.Join(" | ", subtract.Diagnostics.Select(d => d.Message))}");
+ return new(ThroughHoleRecoveryExecutionStatus.BooleanFailed, null, diagnostics);
+ }
+
+ diagnostics.Add("Boolean subtract succeeded.");
+
+ if (subtract.Value is null)
+ {
+ diagnostics.Add("Invalid result: subtract success returned null body.");
+ return new(ThroughHoleRecoveryExecutionStatus.InvalidResult, null, diagnostics);
+ }
+
+ diagnostics.Add("Result BRep body produced.");
+ return new(ThroughHoleRecoveryExecutionStatus.Succeeded, subtract.Value, diagnostics);
+ }
+
+ private static BrepBody TranslateBody(BrepBody body, Aetheris.Kernel.Core.Math.Vector3D translation)
+ => translation == Aetheris.Kernel.Core.Math.Vector3D.Zero
+ ? body
+ : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);
+}
diff --git a/docs/cir-recovery-v2-through-hole-executor.md b/docs/cir-recovery-v2-through-hole-executor.md
new file mode 100644
index 00000000..8a14b16d
--- /dev/null
+++ b/docs/cir-recovery-v2-through-hole-executor.md
@@ -0,0 +1,60 @@
+# CIR-RECOVERY-V2 — Through-hole recovery executor (box/cylinder exact BRep)
+
+## Scope
+
+CIR-RECOVERY-V2 executes an already-selected `ThroughHoleRecoveryPlan` for exactly one specialization:
+
+- host: rectangular box
+- tool: cylindrical
+- profile: circular
+- axis: Z
+
+It is internal-only execution and does not change STEP/export, public API, fall-forward, or rematerializer wiring.
+
+## Execution route
+
+The executor uses existing trusted BRep machinery:
+
+1. `BrepPrimitives.CreateBox(width,height,depth)`
+2. `BrepPrimitives.CreateCylinder(radius,height)`
+3. translate both bodies by plan translations
+4. `BrepBoolean.Subtract(box,cylinder)`
+5. return `BrepBody`
+
+## Constructor conventions confirmed
+
+From existing primitive + boolean tests and primitive implementations:
+
+- `CreateBox(width,height,depth)` creates a body centered at origin with extents `[-w/2,+w/2]`, `[-h/2,+h/2]`, `[-d/2,+d/2]`.
+- `CreateCylinder(radius,height)` creates a Z-axis cylinder centered at origin with caps at `z=±height/2`.
+- translation is applied by `FirmamentPrimitiveExecutionTranslation.TranslateBody` after primitive creation.
+- plan `ThroughLength` is used as cylinder height, clamped to at least host depth to preserve through-span semantics (`max(ThroughLength, HostSizeZ)`).
+
+## Diagnostics
+
+The executor emits deterministic stage diagnostics for:
+
+- executor start
+- plan acceptance/rejection
+- box primitive construction
+- cylinder primitive construction
+- subtract invocation/success/failure
+- result production
+- explicit V2 non-goals: no STEP export and no rematerializer/fall-forward wiring
+
+## Non-goals (preserved)
+
+- no STEP export wiring
+- no `NativeGeometryRematerializer` integration
+- no `CirBrepMaterializer` behavior changes
+- no new topology builder
+- no generic boolean/through-hole recovery expansion
+- no generated topology naming
+
+## SEM-A0 alignment
+
+SEM-A0 guardrails remain preserved (`docs/firmament-semantic-topology-naming.md`): this milestone adds no generated topology naming and no new selector/provenance exposure.
+
+## V3 next milestone
+
+CIR-RECOVERY-V3 should add a narrow STEP smoke path for successful executor output while keeping execution strategy bounded.