Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add ThroughHoleRecoveryPolicy semantic scaffold and plan

Yuechen Li27acdd6cd9f4
diff --git a/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.cs b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.cs
new file mode 100644
index 00000000..56cb2177
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/ThroughHoleRecoveryPolicyTests.cs
@@ -0,0 +1,96 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class ThroughHoleRecoveryPolicyTests
+{
+ private readonly ThroughHoleRecoveryPolicy _policy = new();
+
+ [Fact]
+ public void ThroughHolePolicy_DirectBoxCylinder_AdmitsAndCreatesPlan()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))));
+ Assert.True(eval.Admissible);
+ Assert.Equal(FrepMaterializerCapability.ExactBRep, eval.Capability);
+ var plan = Assert.IsType<ThroughHoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(ThroughHoleHostKind.RectangularBox, plan.HostKind);
+ Assert.Equal(ThroughHoleToolKind.Cylindrical, plan.ToolKind);
+ Assert.Equal(ThroughHoleProfileKind.Circular, plan.ProfileKind);
+ Assert.Equal(ThroughHoleAxisKind.Z, plan.Axis);
+ Assert.Equal(20d, plan.ThroughLength, 6);
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_TranslatedBoxCylinder_Admits()
+ {
+ 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 eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.True(eval.Admissible);
+ Assert.Contains("translation-wrapper-supported", eval.Evidence);
+ }
+
+ [Fact]
+ public void Planner_SelectsThroughHolePolicy_OverFallback()
+ {
+ var context = new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20)));
+ var decision = FrepMaterializerPlanner.Decide(context, [
+ _policy,
+ new FakePolicy("fallback", FrepMaterializerPolicyEvaluation.Admitted("fallback", 1d, FrepMaterializerCapability.CirOnly))
+ ]);
+ Assert.Equal(nameof(ThroughHoleRecoveryPolicy), decision.SelectedPolicyName);
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_RejectsBoxSphere()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2))));
+ Assert.False(eval.Admissible);
+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedRightNotCylinder", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_RejectsBlindCylinder()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8))));
+ Assert.False(eval.Admissible);
+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedNotThroughHole", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_RejectsTangentOrGrazing()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateTranslation(new Vector3D(3, 0, 0))))));
+ Assert.False(eval.Admissible);
+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedTangentOrGrazing", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_RejectsUnsupportedTransform()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateRotationX(0.2)))));
+ Assert.False(eval.Admissible);
+ Assert.Contains(eval.RejectionReasons, r => r.Contains("UnsupportedTransform", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void ThroughHolePolicy_DecisionTraceContainsPlanEvidence()
+ {
+ var decision = FrepMaterializerPlanner.Decide(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))), [_policy]);
+ var eval = Assert.Single(decision.Evaluations);
+ Assert.Contains("semantic-through-hole", eval.Evidence);
+ Assert.Contains(eval.Evidence, e => e.Contains("expected-patches", StringComparison.Ordinal));
+ Assert.Contains(eval.Evidence, e => e.Contains("expected-trims", StringComparison.Ordinal));
+ }
+
+ private sealed class FakePolicy(string name, FrepMaterializerPolicyEvaluation evaluation) : IFrepMaterializerPolicy
+ {
+ public string Name => name;
+
+ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context) => evaluation;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs
index 1890d36f..08b0d9b3 100644
--- a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs
@@ -31,20 +31,29 @@ public sealed record FrepMaterializerPolicyEvaluation(
FrepMaterializerCapability Capability,
IReadOnlyList<string> Evidence,
IReadOnlyList<string> RejectionReasons,
- IReadOnlyList<string> Diagnostics)
+ IReadOnlyList<string> Diagnostics,
+ object? Plan = null)
{
public static FrepMaterializerPolicyEvaluation Admitted(
string policyName,
double score,
FrepMaterializerCapability capability,
IReadOnlyList<string>? evidence = null,
- IReadOnlyList<string>? diagnostics = null)
- => new(policyName, true, score, capability, evidence ?? Array.Empty<string>(), Array.Empty<string>(), diagnostics ?? Array.Empty<string>());
+ IReadOnlyList<string>? diagnostics = null,
+ object? plan = null)
+ => new(policyName, true, score, capability, evidence ?? Array.Empty<string>(), Array.Empty<string>(), diagnostics ?? Array.Empty<string>(), plan);
public static FrepMaterializerPolicyEvaluation Rejected(
string policyName,
params string[] rejectionReasons)
=> new(policyName, false, 0d, FrepMaterializerCapability.Unsupported, Array.Empty<string>(), rejectionReasons, Array.Empty<string>());
+
+ public static FrepMaterializerPolicyEvaluation Rejected(
+ string policyName,
+ IReadOnlyList<string>? evidence = null,
+ IReadOnlyList<string>? diagnostics = null,
+ params string[] rejectionReasons)
+ => new(policyName, false, 0d, FrepMaterializerCapability.Unsupported, evidence ?? Array.Empty<string>(), rejectionReasons, diagnostics ?? Array.Empty<string>());
}
public enum FrepMaterializerDecisionStatus
diff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.cs
new file mode 100644
index 00000000..d63551f9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPlan.cs
@@ -0,0 +1,65 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+public enum ThroughHoleHostKind
+{
+ RectangularBox,
+ Unsupported
+}
+
+public enum ThroughHoleToolKind
+{
+ Cylindrical,
+ Unsupported
+}
+
+public enum ThroughHoleProfileKind
+{
+ Circular,
+ Unsupported
+}
+
+public enum ThroughHoleAxisKind
+{
+ Z,
+ Unsupported
+}
+
+public enum ThroughHoleSurfaceRole
+{
+ EntryFace,
+ ExitFace,
+ HostRetainedPlanarFaces,
+ CylindricalWall
+}
+
+public enum ThroughHoleTrimRole
+{
+ CircularRimTrim,
+ Deferred
+}
+
+public sealed record ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole Role, string Description);
+
+public sealed record ThroughHoleExpectedPatch(ThroughHoleSurfaceRole Role, string Description);
+
+public sealed record ThroughHoleExpectedTrim(ThroughHoleTrimRole Role, string Description);
+
+public sealed record ThroughHoleRecoveryPlan(
+ ThroughHoleHostKind HostKind,
+ ThroughHoleToolKind ToolKind,
+ ThroughHoleProfileKind ProfileKind,
+ ThroughHoleAxisKind Axis,
+ double ThroughLength,
+ double ToolRadius,
+ double HostSizeX,
+ double HostSizeY,
+ double HostSizeZ,
+ Vector3D HostTranslation,
+ Vector3D ToolTranslation,
+ IReadOnlyList<ThroughHoleSurfaceParticipation> EntryExitSurfaces,
+ IReadOnlyList<ThroughHoleExpectedPatch> ExpectedPatches,
+ IReadOnlyList<ThroughHoleExpectedTrim> ExpectedTrims,
+ FrepMaterializerCapability Capability,
+ IReadOnlyList<string> Diagnostics);
diff --git a/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs
new file mode 100644
index 00000000..a8d1f496
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs
@@ -0,0 +1,72 @@
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+public sealed class ThroughHoleRecoveryPolicy : IFrepMaterializerPolicy
+{
+ private const double SemanticThroughHoleScore = 1000d;
+
+ public string Name => nameof(ThroughHoleRecoveryPolicy);
+
+ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)
+ {
+ ArgumentNullException.ThrowIfNull(context);
+
+ var recognition = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(context.Root, context.ReplayLog, context.SourceLabel));
+ if (!recognition.Success || recognition.Value is null)
+ {
+ return FrepMaterializerPolicyEvaluation.Rejected(
+ Name,
+ evidence: ["semantic-through-hole", $"recognizer-reason:{recognition.Reason}"],
+ diagnostics: recognition.Diagnostics,
+ rejectionReasons: [recognition.Diagnostic, $"recognizer-reason:{recognition.Reason}"]);
+ }
+
+ var recognized = recognition.Value;
+ var evidence = new List<string>
+ {
+ "semantic-through-hole",
+ "rectangular-box-host",
+ "cylindrical-tool",
+ "through-hole",
+ "strict-clearance"
+ };
+
+ var supportsTranslation = recognized.BoxTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero
+ || recognized.CylinderTranslation != Aetheris.Kernel.Core.Math.Vector3D.Zero;
+ evidence.Add(supportsTranslation ? "translation-wrapper-supported" : "translation-wrapper-not-required");
+ evidence.Add(recognition.Reason == CirBoxCylinderRecognitionReason.ReplayMismatch ? "replay-diagnostic" : "replay-consistent");
+ evidence.Add("expected-patches:entry-exit-planar,cylindrical-wall");
+ evidence.Add("expected-trims:circular-rim");
+
+ var plan = new ThroughHoleRecoveryPlan(
+ ThroughHoleHostKind.RectangularBox,
+ ThroughHoleToolKind.Cylindrical,
+ ThroughHoleProfileKind.Circular,
+ ThroughHoleAxisKind.Z,
+ recognized.ThroughLength,
+ recognized.CylinderRadius,
+ recognized.BoxWidth,
+ recognized.BoxHeight,
+ recognized.BoxDepth,
+ recognized.BoxTranslation,
+ recognized.CylinderTranslation,
+ [
+ new ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole.EntryFace, "Cylinder intersects host entry face with circular profile."),
+ new ThroughHoleSurfaceParticipation(ThroughHoleSurfaceRole.ExitFace, "Cylinder intersects host exit face with circular profile.")
+ ],
+ [
+ new ThroughHoleExpectedPatch(ThroughHoleSurfaceRole.HostRetainedPlanarFaces, "Host planar faces are retained after through-hole subtraction."),
+ new ThroughHoleExpectedPatch(ThroughHoleSurfaceRole.CylindricalWall, "One cylindrical inner wall patch is expected.")
+ ],
+ [new ThroughHoleExpectedTrim(ThroughHoleTrimRole.CircularRimTrim, "Circular trims on entry and exit rims are expected.")],
+ FrepMaterializerCapability.ExactBRep,
+ recognition.Diagnostics);
+
+ return FrepMaterializerPolicyEvaluation.Admitted(
+ Name,
+ SemanticThroughHoleScore,
+ FrepMaterializerCapability.ExactBRep,
+ evidence,
+ recognition.Diagnostics,
+ plan);
+ }
+}
diff --git a/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md
index 80e31b03..7e2eaa6d 100644
--- a/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md
+++ b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md
@@ -41,4 +41,4 @@ No lowering plan or execution-state dependency is required in V1A.
## Next milestone
-CIR-RECOVERY-V1B should add a first production semantic policy (`BoxCylinderThroughHolePolicy`) that emits diagnostic-rich evaluation only (or bounded exact path if explicitly scoped), while preserving existing behavior gates.
+CIR-RECOVERY-V1B should add a first production semantic policy (`ThroughHoleRecoveryPolicy`) with an internal box+cylinder specialization that emits a diagnostic-rich semantic plan, while preserving existing behavior gates.
diff --git a/docs/cir-recovery-v1b-through-hole-policy.md b/docs/cir-recovery-v1b-through-hole-policy.md
new file mode 100644
index 00000000..1d6a1e8c
--- /dev/null
+++ b/docs/cir-recovery-v1b-through-hole-policy.md
@@ -0,0 +1,61 @@
+# CIR-RECOVERY-V1B: ThroughHoleRecoveryPolicy scaffold
+
+## Why semantic-through-hole (not pair-specific top-level)
+
+CIR-BREP-X6 recommended a semantic policy lane (`ThroughHoleRecoveryPolicy`) with bounded internal host/tool specializations instead of promoting a pair-specific `BoxCylinderThroughHolePolicy` to top level. This keeps policy growth manageable as feature families expand.
+
+## First specialization in V1B
+
+V1B adds one internal specialization through existing production recognizer behavior:
+- host: rectangular box
+- tool: cylindrical subtractor
+- feature: strict-clearance through-hole along Z
+
+Recognizer source remains `CirBoxCylinderRecognizer`.
+
+## Recovery plan shape
+
+`ThroughHoleRecoveryPlan` carries semantic execution intent for V2:
+- host/tool/profile/axis kinds
+- through length, host/tool dimensions, translations
+- entry/exit surface participation
+- expected patch roles and trim roles
+- capability + diagnostics
+
+This is intentionally semantic and bounded (not a topology graph).
+
+## Scoring and evidence
+
+`ThroughHoleRecoveryPolicy` uses deterministic fixed score `1000` for recognized canonical semantic through-hole with `ExactBRep` capability, intentionally above fallback bands.
+
+Evidence includes:
+- `semantic-through-hole`
+- `rectangular-box-host`
+- `cylindrical-tool`
+- `through-hole`
+- `strict-clearance`
+- translation support note
+- replay consistency/diagnostic note
+- expected patch/trim role hints
+
+## Rejected cases
+
+Policy rejects and forwards recognizer reasons/diagnostics for:
+- non subtract roots
+- non box/cylinder operands
+- blind cylinders
+- tangent/grazing cuts
+- unsupported transforms
+- other unsupported recognizer cases
+
+## Not included in V1B
+
+- no BRep body construction
+- no STEP export wiring
+- no rematerializer/fall-forward changes
+- no boolean-generic recovery
+- no shell stitching / topology mutation / naming
+
+## Next milestone (V2)
+
+Consume `ThroughHoleRecoveryPlan` in an executor that builds exact BRep surfaces/trims for this semantic lane, then integrate into materialization pipeline with capability-gated fallback.