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