Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add V12 hole-family coverage matrix and diagnostics hardening

Yuechen Li9e291ba71f53
diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs
new file mode 100644
index 00000000..a54854e7
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/HoleRecoveryPolicyCoverageMatrixTests.cs
@@ -0,0 +1,134 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class HoleRecoveryPolicyCoverageMatrixTests
+{
+ private readonly HoleRecoveryPolicy _policy = new();
+
+ public static TheoryData<string, CirNode, string, HoleKind, HoleDepthKind, FrepMaterializerCapability> SupportedRows =>
+ new()
+ {
+ { "ThroughHole", BuildThroughHole(), nameof(ThroughHoleVariant), HoleKind.Through, HoleDepthKind.Through, FrepMaterializerCapability.ExactBRep },
+ { "Counterbore", BuildCounterbore(), nameof(CounterboreVariant), HoleKind.Counterbore, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep },
+ { "BlindHoleTop", BuildBlindHoleTop(), nameof(BlindHoleVariant), HoleKind.Blind, HoleDepthKind.Blind, FrepMaterializerCapability.ExactBRep },
+ { "BlindHoleBottom", BuildBlindHoleBottom(), nameof(BlindHoleVariant), HoleKind.Blind, HoleDepthKind.Blind, FrepMaterializerCapability.ExactBRep },
+ { "Countersink", BuildCountersink(), nameof(CountersinkVariant), HoleKind.Countersink, HoleDepthKind.ThroughWithEntryRelief, FrepMaterializerCapability.ExactBRep }
+ };
+
+ public static TheoryData<string, CirNode> UnsupportedRows =>
+ new()
+ {
+ { "BoxSphere", new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirSphereNode(3)) },
+ { "TangentCylinder", new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(10, 20), Transform3D.CreateTranslation(new Vector3D(0,0,0)))) },
+ { "UnsupportedTransform", new CirSubtractNode(new CirTransformNode(new CirBoxNode(20, 20, 10), Transform3D.CreateRotationX(Math.PI / 6d)), new CirCylinderNode(2, 20)) },
+ { "NonCoaxialCounterboreOrCountersink", new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(2,0,-3)))) }
+ };
+
+ [Theory]
+ [MemberData(nameof(SupportedRows))]
+ public void HoleCoverageMatrix_SelectsExpectedVariantForSupportedCases(string _, CirNode root, string expectedVariant, HoleKind kind, HoleDepthKind depth, FrepMaterializerCapability capability)
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.True(eval.Admissible);
+ Assert.Equal(capability, eval.Capability);
+ Assert.Contains($"selected-variant:{expectedVariant}", eval.Evidence);
+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(kind, plan.HoleKind);
+ Assert.Equal(depth, plan.DepthKind);
+ Assert.NotEmpty(eval.Diagnostics);
+ }
+
+ [Theory]
+ [MemberData(nameof(UnsupportedRows))]
+ public void HoleCoverageMatrix_UnsupportedCasesFallBackOrReject(string _, CirNode root)
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.False(eval.Admissible);
+ Assert.Null(eval.Plan);
+ Assert.NotEmpty(eval.RejectionReasons);
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Fallback selected", StringComparison.Ordinal));
+ }
+
+ [Theory]
+ [MemberData(nameof(SupportedRows))]
+ public void HoleCoverageMatrix_WrongVariantsRejectSupportedCases(string rowName, CirNode root, string expectedVariant, HoleKind expectedHoleKind, HoleDepthKind expectedDepthKind, FrepMaterializerCapability expectedCapability)
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.True(eval.Admissible);
+ Assert.False(string.IsNullOrWhiteSpace(rowName));
+ Assert.Equal(expectedCapability, eval.Capability);
+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(expectedHoleKind, plan.HoleKind);
+ Assert.Equal(expectedDepthKind, plan.DepthKind);
+ var all = new[] { nameof(ThroughHoleVariant), nameof(CounterboreVariant), nameof(BlindHoleVariant), nameof(CountersinkVariant) };
+ foreach (var variant in all.Where(v => !string.Equals(v, expectedVariant, StringComparison.Ordinal)))
+ {
+ Assert.Contains(eval.Diagnostics, d => d.Contains($"Variant considered: {variant}; admissible=False.", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains($"Variant rejected: {variant};", StringComparison.Ordinal));
+ }
+ }
+
+ [Fact]
+ public void HoleCoverageMatrix_DiagnosticsIncludeVariantTrace()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(BuildCounterbore()));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Variants evaluated", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Variant considered: ThroughHoleVariant", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Variant considered: CounterboreVariant", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Selected hole variant: CounterboreVariant", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Produced plan kind", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void HoleCoverageMatrix_ProfileStackSummariesArePresent()
+ {
+ var eval = _policy.Evaluate(new FrepMaterializerContext(BuildCountersink()));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Profile stack summary", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Conical", StringComparison.Ordinal));
+ Assert.Contains(eval.Diagnostics, d => d.Contains("Cylindrical", StringComparison.Ordinal));
+ }
+
+ [Theory]
+ [MemberData(nameof(SupportedRows))]
+ public void HoleCoverageMatrix_ExecutableVariantsProduceBRep(string rowName, CirNode root, string expectedVariant, HoleKind expectedHoleKind, HoleDepthKind expectedDepthKind, FrepMaterializerCapability expectedCapability)
+ {
+ Assert.False(string.IsNullOrWhiteSpace(rowName));
+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.Contains($"selected-variant:{expectedVariant}", eval.Evidence);
+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(expectedHoleKind, plan.HoleKind);
+ Assert.Equal(expectedDepthKind, plan.DepthKind);
+ Assert.Equal(expectedCapability, eval.Capability);
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, exec.Status);
+ Assert.NotNull(exec.Body);
+ }
+
+ [Theory]
+ [MemberData(nameof(SupportedRows))]
+ public void HoleCoverageMatrix_CurrentHoleVariantsAreManifoldNotVoids(string rowName, CirNode root, string expectedVariant, HoleKind expectedHoleKind, HoleDepthKind expectedDepthKind, FrepMaterializerCapability expectedCapability)
+ {
+ Assert.False(string.IsNullOrWhiteSpace(rowName));
+ var eval = _policy.Evaluate(new FrepMaterializerContext(root));
+ Assert.Contains($"selected-variant:{expectedVariant}", eval.Evidence);
+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(expectedHoleKind, plan.HoleKind);
+ Assert.Equal(expectedDepthKind, plan.DepthKind);
+ Assert.Equal(expectedCapability, eval.Capability);
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ var step = Step242Exporter.ExportBody(exec.Body!);
+ Assert.True(step.IsSuccess);
+ Assert.Contains("MANIFOLD_SOLID_BREP", step.Value, StringComparison.Ordinal);
+ Assert.DoesNotContain("BREP_WITH_VOIDS", step.Value, StringComparison.Ordinal);
+ }
+
+ private static CirNode BuildThroughHole() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20));
+ private static CirNode BuildBlindHoleTop() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(2, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3))));
+ private static CirNode BuildBlindHoleBottom() => new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTransformNode(new CirCylinderNode(2, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));
+ private static CirNode BuildCounterbore() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)), new CirTransformNode(new CirCylinderNode(4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));
+ private static CirNode BuildCountersink() => new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)), new CirTransformNode(new CirConeNode(2, 4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3))));
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
index 71b77b6d..d6bbe797 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
@@ -28,6 +28,11 @@ public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy
{
var traces = _variants.Select(v => v.Evaluate(context)).ToArray();
var diagnostics = new List<string> {$"{Name} evaluated.", $"Variants evaluated: {traces.Length}."};
+ diagnostics.AddRange(traces.Select(t => $"Variant considered: {t.VariantName}; admissible={t.Admissible}."));
+ diagnostics.AddRange(traces.Where(t => !t.Admissible)
+ .SelectMany(t => t.RejectionReasons.Select(r => $"Variant rejected: {t.VariantName}; reason={r}.")));
+ diagnostics.AddRange(traces.Where(t => !t.Admissible && t.RejectionReasons.Count == 0)
+ .Select(t => $"Variant rejected: {t.VariantName}; reason=NoReasonProvided."));
diagnostics.AddRange(traces.SelectMany(t => t.Diagnostics.Select(d => $"variant:{t.VariantName}:{d}")));
var candidates = traces.Select((t, i) => new JudgmentCandidate<FrepMaterializerContext>(t.VariantName, _ => t.Admissible, _ => t.Score, _ => t.RejectionReasons.Count == 0 ? "variant rejected" : string.Join(" | ", t.RejectionReasons), i)).ToArray();
@@ -35,6 +40,7 @@ public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy
if (!judgment.IsSuccess)
{
var reasons = traces.SelectMany(t => t.RejectionReasons.Select(r => $"{t.VariantName}:{r}")).ToArray();
+ diagnostics.Add("Fallback selected: no hole variant admitted.");
diagnostics.Add("No admissible hole variant.");
return FrepMaterializerPolicyEvaluation.Rejected(Name, traces.SelectMany(t => t.Evidence).Append("semantic-hole-family").ToArray(), diagnostics, reasons);
}
@@ -44,6 +50,11 @@ public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy
var evidence = new List<string> { "semantic-hole-family", $"selected-variant:{selected.VariantName}" };
evidence.AddRange(selected.Evidence);
diagnostics.Add($"Selected hole variant: {selected.VariantName}.");
+ diagnostics.Add($"Produced plan kind: {selected.Plan?.HoleKind}/{selected.Plan?.DepthKind}.");
+ if (selected.Plan is not null)
+ {
+ diagnostics.Add($"Profile stack summary: {string.Join(",", selected.Plan.ProfileStack.Select(s => s.SegmentKind))}.");
+ }
diagnostics.Add("Hole recovery plan produced.");
return FrepMaterializerPolicyEvaluation.Admitted(Name, selected.Score, FrepMaterializerCapability.ExactBRep, evidence, diagnostics, selected.Plan);
}
diff --git a/docs/cir-recovery-v12-hole-family-coverage-matrix.md b/docs/cir-recovery-v12-hole-family-coverage-matrix.md
new file mode 100644
index 00000000..8d6f1903
--- /dev/null
+++ b/docs/cir-recovery-v12-hole-family-coverage-matrix.md
@@ -0,0 +1,57 @@
+# CIR-RECOVERY-V12: hole-family coverage matrix + diagnostics hardening
+
+## Summary
+V12 hardens production `HoleRecoveryPolicy` coverage and diagnostics for the current hole-family variants:
+
+- `ThroughHoleVariant`
+- `CounterboreVariant`
+- `BlindHoleVariant`
+- `CountersinkVariant`
+
+This milestone adds matrix-style test coverage and diagnostics trace assertions. It does **not** add variants, change executor semantics, or change STEP exporter behavior.
+
+## Coverage matrix
+
+### Supported exact rows
+- ThroughHole -> `ThroughHoleVariant`, `HoleKind.Through`, executable.
+- Counterbore -> `CounterboreVariant`, `HoleKind.Counterbore`, executable.
+- BlindHoleTop -> `BlindHoleVariant`, `HoleKind.Blind`, executable.
+- BlindHoleBottom -> `BlindHoleVariant`, `HoleKind.Blind`, executable.
+- Countersink -> `CountersinkVariant`, `HoleKind.Countersink`, executable.
+
+### Unsupported/fallback rows
+- BoxSphere -> no variant admits; fallback/reject path.
+- TangentCylinder -> no variant admits; fallback/reject path.
+- UnsupportedTransform -> no variant admits; fallback/reject path.
+- NonCoaxialCounterboreOrCountersink -> no variant admits; fallback/reject path.
+
+## Cross-steal policy
+Each supported case is asserted to:
+- select the expected variant, and
+- produce rejection evidence from non-selected variants.
+
+This guards against silent over-admission and variant stealing.
+
+## Diagnostics hardening
+`HoleRecoveryPolicy` diagnostics now include stable matrix-debug details:
+- policy evaluated,
+- variant count,
+- per-variant considered/admissible lines,
+- per-variant rejection reason lines,
+- selected variant,
+- produced plan kind,
+- profile stack summary,
+- fallback selection when no variant admits.
+
+## Non-goals preserved
+- no new hole recovery variants,
+- no executor architecture changes,
+- no STEP exporter behavior changes,
+- no public CLI/API expansion,
+- no generic boolean recovery.
+
+## Recommended next family expansion
+If/when expansion resumes, keep the same pattern:
+1. bounded admissibility first,
+2. explicit rejection diagnostics for all peer variants,
+3. matrix row + cross-steal + manifold STEP sanity tests with each new variant.