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.csnew file mode 100644index 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.csindex 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 : IFrepMaterializerPolicyif (!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 : IFrepMaterializerPolicyvar 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.mdnew file mode 100644index 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.