Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-BREP-X6 policy-shape DoE lab and tests
Yuechen Li5b61be0fc08a
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/FrepPolicyShapeDoeLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/FrepPolicyShapeDoeLab.csnew file mode 100644index 00000000..589cb55f--- /dev/null+++ b/Aetheris.Firmament.FrictionLab/CIRLab/FrepPolicyShapeDoeLab.cs@@ -0,0 +1,81 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Judgment;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.FrictionLab;++public enum PolicyShapeCapability { ExactBRep, PlannedExact, DiagnosticOnly, CirOnly, Unsupported, ForgeOrDeferred }+public enum RecoveryPlanShape { PairSpecificPlan, ThroughHoleRecoveryPlan, CylindricalToolCutPlan, GenericBooleanRecoveryPlan, SurfaceFeaturePlan, FallbackNumericalPlan, CirOnlyPlan, UnsupportedPlan }++public sealed record PolicyShapeScenario(string Id, string Group, string Description, CirNode? Root, string Category, bool Deferred = false);++public sealed record PolicyShapeEvaluation(+ string PolicyName,+ bool Admissible,+ double Score,+ PolicyShapeCapability Capability,+ RecoveryPlanShape PlanShape,+ IReadOnlyList<string> EvidenceUsed,+ IReadOnlyList<string> RejectedReasons,+ bool OverAdmits,+ bool UnderAdmits,+ int PairSpecificityRisk,+ int FutureScalabilityScore,+ IReadOnlyList<string> Diagnostics);++public sealed record PolicyShapeDecision(string? Winner, IReadOnlyList<PolicyShapeEvaluation> Ranking, IReadOnlyList<string> Diagnostics);++public interface IPolicyShapeCandidate { string Name { get; } int TieBreakerPriority { get; } PolicyShapeEvaluation Evaluate(PolicyShapeScenario scenario); }++public static class FrepPolicyShapeDoeLab+{+ public static IReadOnlyList<PolicyShapeScenario> BuildScenarioMatrix() =>+ [+ new("A1","A","box - centered cylinder through Z", new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(2,8)), "canonical_through_hole"),+ new("A2","A","box - offset cylinder through Z with strict clearance", new CirSubtractNode(new CirBoxNode(10,8,6), new CirTransformNode(new CirCylinderNode(1.5,8), Transform3D.CreateTranslation(new(1,1,0)))), "canonical_through_hole"),+ new("A3","A","translated box - translated cylinder through Z", new CirSubtractNode(new CirTransformNode(new CirBoxNode(10,8,6), Transform3D.CreateTranslation(new(3,2,5))), new CirTransformNode(new CirCylinderNode(2,8), Transform3D.CreateTranslation(new(3.5,2.5,5)))), "canonical_through_hole"),+ new("A4","A","rectangular plate - cylinder through Z", new CirSubtractNode(new CirBoxNode(12,8,2), new CirCylinderNode(1,3)), "canonical_through_hole"),+ new("B1","B","box - blind short cylinder", new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(2,4)), "invalid_hole"),+ new("B2","B","box - tangent/grazing cylinder", new CirSubtractNode(new CirBoxNode(10,8,6), new CirTransformNode(new CirCylinderNode(2,8), Transform3D.CreateTranslation(new(3,0,0)))), "invalid_hole"),+ new("B3","B","box - cylinder outside box", new CirSubtractNode(new CirBoxNode(10,8,6), new CirTransformNode(new CirCylinderNode(2,8), Transform3D.CreateTranslation(new(7,0,0)))), "invalid_hole"),+ new("B4","B","box - oversized cylinder", new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(6,8)), "invalid_hole"),+ new("B5","B","box - rotated cylinder", new CirSubtractNode(new CirBoxNode(10,8,6), new CirTransformNode(new CirCylinderNode(2,8), Transform3D.CreateRotationX(Math.PI/4))), "invalid_hole"),+ new("C1","C","box - cylinder side notch", new CirSubtractNode(new CirBoxNode(10,8,6), new CirTransformNode(new CirCylinderNode(2,8), Transform3D.CreateTranslation(new(4,0,0)))), "cylindrical_non_through"),+ new("C2","C","box - shallow cylindrical pocket", new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(1.5,1.5)), "cylindrical_non_through"),+ new("D1","D","cylindrical host - axial cylindrical hole", null, "future_variant", true),+ new("D4","D","rectangular host - countersink-like through feature", null, "future_variant", true),+ new("E1","E","round groove on cylinder", null, "surface_feature", true),+ new("E3","E","thread on cylinder", null, "surface_feature", true),+ new("F1","F","generic torus subtract", null, "unsupported", true),+ new("F2","F","box - sphere", new CirSubtractNode(new CirBoxNode(10,8,6), new CirSphereNode(2)), "unsupported"),+ new("F3","F","nested booleans", new CirSubtractNode(new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(1,8)), new CirCylinderNode(1,8)), "unsupported"),+ new("F4","F","union/intersect cases", new CirUnionNode(new CirBoxNode(1,1,1), new CirCylinderNode(1,1)), "unsupported")+ ];++ public static IReadOnlyList<IPolicyShapeCandidate> DefaultCandidates => [new PairSpecific(), new ThroughHole(), new CylindricalToolCut(), new GenericBoolean(), new GenericNumericalContour(), new CirOnlyFallback()];++ public static PolicyShapeDecision Decide(PolicyShapeScenario scenario, IReadOnlyList<IPolicyShapeCandidate>? candidates = null)+ {+ var set = candidates ?? DefaultCandidates;+ var evals = set.Select(c => c.Evaluate(scenario)).ToArray();+ var map = evals.ToDictionary(e => e.PolicyName, StringComparer.Ordinal);+ var engine = new JudgmentEngine<PolicyShapeScenario>();+ var j = engine.Evaluate(scenario, set.Select(c => new JudgmentCandidate<PolicyShapeScenario>(c.Name, _ => map[c.Name].Admissible, _ => map[c.Name].Score, _ => string.Join(" | ", map[c.Name].RejectedReasons), c.TieBreakerPriority)).ToArray());+ var winner = j.IsSuccess ? j.Selection!.Value.Candidate.Name : null;+ return new(winner, evals.OrderByDescending(e => e.Admissible).ThenByDescending(e => e.Score).ThenBy(e => e.PolicyName).ToArray(), [..j.Rejections.Select(r => $"{r.CandidateName}:{r.Reason}")]);+ }++ private sealed class PairSpecific : IPolicyShapeCandidate { public string Name => "BoxCylinderThroughHolePolicyShape"; public int TieBreakerPriority => 0; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s){ var ok = TryCanonical(s); return new(Name, ok, ok?92:0, ok?PolicyShapeCapability.ExactBRep:PolicyShapeCapability.Unsupported, RecoveryPlanShape.PairSpecificPlan, ok?["box-cylinder-recognizer"]:[], ok?[]:["not canonical box-cylinder through-hole"], false, s.Category=="future_variant", 9, 3, []);} }+ private sealed class ThroughHole : IPolicyShapeCandidate { public string Name => "ThroughHoleRecoveryPolicyShape"; public int TieBreakerPriority=>0; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s){ var supported = s.Category=="canonical_through_hole"||s.Category=="future_variant"; var admissible = s.Category=="canonical_through_hole"; return new(Name, admissible, admissible?95:0, admissible?PolicyShapeCapability.ExactBRep:(supported?PolicyShapeCapability.PlannedExact:PolicyShapeCapability.Unsupported), RecoveryPlanShape.ThroughHoleRecoveryPlan, ["semantic-through-hole","bounded-admissibility"], admissible?[]:["not admissible as strict through-hole"], false, false, 2, 9, []);} }+ private sealed class CylindricalToolCut : IPolicyShapeCandidate { public string Name => "CylindricalToolCutPolicyShape"; public int TieBreakerPriority=>1; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s){ var toolCyl = s.Root is CirSubtractNode sub && (sub.Right is CirCylinderNode || sub.Right is CirTransformNode { Child: CirCylinderNode }); var over = toolCyl && s.Category=="cylindrical_non_through"; return new(Name, toolCyl, toolCyl?72:0, toolCyl?PolicyShapeCapability.DiagnosticOnly:PolicyShapeCapability.Unsupported, RecoveryPlanShape.CylindricalToolCutPlan, toolCyl?["tool-family=cylindrical"]:[], toolCyl?[]:["tool is not cylindrical subtract"], over, false, 5, 5, over?["over-admission-risk: mixes hole/notch/pocket/groove"]:[]);} }+ private sealed class GenericBoolean : IPolicyShapeCandidate { public string Name => "CirBooleanRecoveryPolicyShape"; public int TieBreakerPriority=>2; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s){ var admissible = s.Root is CirSubtractNode or CirUnionNode or CirIntersectNode; return new(Name, admissible, admissible?40:0, admissible?PolicyShapeCapability.DiagnosticOnly:PolicyShapeCapability.Unsupported, RecoveryPlanShape.GenericBooleanRecoveryPlan, admissible?["generic-boolean"]:[], admissible?[]:["not a boolean CIR root"], admissible, false, 8, 2, admissible?["dispatcher-risk: broad boolean bucket"]:[]);} }+ private sealed class GenericNumericalContour : IPolicyShapeCandidate { public string Name=>"GenericNumericalContourPolicy"; public int TieBreakerPriority=>3; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s)=> new(Name,true,20,PolicyShapeCapability.DiagnosticOnly,RecoveryPlanShape.FallbackNumericalPlan,["fallback=numerical"],[],false,false,1,4,[]); }+ private sealed class CirOnlyFallback : IPolicyShapeCandidate { public string Name=>"CirOnlyFallbackPolicy"; public int TieBreakerPriority=>4; public PolicyShapeEvaluation Evaluate(PolicyShapeScenario s)=> new(Name,true,5,PolicyShapeCapability.CirOnly,RecoveryPlanShape.CirOnlyPlan,["fallback=cir-only"],[],false,false,1,3,[]); }++ private static bool TryCanonical(PolicyShapeScenario s)+ {+ if (s.Root is null) return false;+ var r = CirBrepX4RecognizerSourceContractLab.Recognize(CirBoxCylinderRecognizerInput.FromNode(s.Root));+ return r.Recognition.Success;+ }+}diff --git a/Aetheris.FrictionLab.Tests/CIRLab/FrepPolicyShapeDoeLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/FrepPolicyShapeDoeLabTests.csnew file mode 100644index 00000000..aee11c11--- /dev/null+++ b/Aetheris.FrictionLab.Tests/CIRLab/FrepPolicyShapeDoeLabTests.cs@@ -0,0 +1,79 @@+using Aetheris.FrictionLab;+using System.Text;++namespace Aetheris.FrictionLab.Tests.CIRLab;++public sealed class FrepPolicyShapeDoeLabTests+{+ [Fact]+ public void PolicyShapeDoe_CanonicalBoxCylinder_SelectsRecommendedSemanticPolicy()+ {+ var s = FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == "A1");+ var d = FrepPolicyShapeDoeLab.Decide(s);+ Assert.Equal("ThroughHoleRecoveryPolicyShape", d.Winner);+ Assert.DoesNotContain(d.Ranking, e => e.PolicyName == "CirBooleanRecoveryPolicyShape" && e.PolicyName == d.Winner);+ }++ [Fact] public void PolicyShapeDoe_TranslatedBoxCylinder_SelectsRecommendedSemanticPolicy() => Assert.Equal("ThroughHoleRecoveryPolicyShape", FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id=="A3")).Winner);++ [Fact]+ public void PolicyShapeDoe_InvalidHoleRejectsSemanticPolicy()+ {+ foreach (var id in new[] { "B1", "B2", "B3" })+ {+ var e = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == id)).Ranking.Single(x => x.PolicyName == "ThroughHoleRecoveryPolicyShape");+ Assert.False(e.Admissible, $"{id} should reject semantic through-hole policy.");+ }+ }++ [Fact]+ public void PolicyShapeDoe_CylindricalToolCutOverAdmissionDetected()+ {+ var e = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == "C1")).Ranking.Single(x => x.PolicyName == "CylindricalToolCutPolicyShape");+ Assert.True(e.OverAdmits || e.Diagnostics.Any(d => d.Contains("over-admission", StringComparison.OrdinalIgnoreCase)));+ }++ [Fact]+ public void PolicyShapeDoe_GenericBooleanRiskDetected()+ {+ var e = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == "F4")).Ranking.Single(x => x.PolicyName == "CirBooleanRecoveryPolicyShape");+ Assert.True(e.OverAdmits);+ Assert.Contains(e.Diagnostics, d => d.Contains("dispatcher-risk", StringComparison.Ordinal));+ }++ [Fact]+ public void PolicyShapeDoe_SurfaceFeaturesNotCapturedByThroughHole()+ {+ foreach (var id in new[] { "E1", "E3" })+ {+ var winner = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == id)).Winner;+ Assert.NotEqual("ThroughHoleRecoveryPolicyShape", winner);+ }+ }++ [Fact]+ public void PolicyShapeDoe_FallbacksWork()+ {+ var d = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().Single(x => x.Id == "F1"));+ Assert.True(d.Winner is "GenericNumericalContourPolicy" or "CirOnlyFallbackPolicy", $"Unexpected fallback winner: {d.Winner}");+ }++ [Fact]+ public void PolicyShapeDoe_DeterministicDecisions()+ {+ var scenarios = FrepPolicyShapeDoeLab.BuildScenarioMatrix();+ var run1 = scenarios.ToDictionary(s => s.Id, s => FrepPolicyShapeDoeLab.Decide(s).Winner);+ var run2 = scenarios.ToDictionary(s => s.Id, s => FrepPolicyShapeDoeLab.Decide(s).Winner);+ Assert.Equal(run1, run2);+ }++ [Fact]+ public void PolicyShapeDoe_ReportShapeComplete()+ {+ var required = new[] { "PolicyName", "Admissible", "Score", "Capability", "PlanShape", "EvidenceUsed", "RejectedReasons", "OverAdmits", "UnderAdmits", "PairSpecificityRisk", "FutureScalabilityScore", "Diagnostics" };+ var e = FrepPolicyShapeDoeLab.Decide(FrepPolicyShapeDoeLab.BuildScenarioMatrix().First()).Ranking.First();+ var present = new HashSet<string> { nameof(e.PolicyName), nameof(e.Admissible), nameof(e.Score), nameof(e.Capability), nameof(e.PlanShape), nameof(e.EvidenceUsed), nameof(e.RejectedReasons), nameof(e.OverAdmits), nameof(e.UnderAdmits), nameof(e.PairSpecificityRisk), nameof(e.FutureScalabilityScore), nameof(e.Diagnostics) };+ var missing = required.Where(r => !present.Contains(r)).ToArray();+ Assert.True(missing.Length == 0, $"Missing columns: {string.Join(",", missing)}");+ }+}diff --git a/docs/frictionlab/cir-brep-x6-policy-shape-doe.md b/docs/frictionlab/cir-brep-x6-policy-shape-doe.mdnew file mode 100644index 00000000..b00236d2--- /dev/null+++ b/docs/frictionlab/cir-brep-x6-policy-shape-doe.md@@ -0,0 +1,67 @@+# CIR-BREP-X6: policy-shape DoE for scalable FRep→BRep materialization++## 1. Purpose and scope+FrictionLab-only design-of-experiments to choose production policy abstraction shape for FRep/CIR→BRep recovery intent.++## 2. Source code / labs inspected+- `Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs`+- `Aetheris.Kernel.Firmament/Materializer/CirBoxCylinderRecognizer.cs`+- `Aetheris.Firmament.FrictionLab/CIRLab/FrepBrepRecoveryPolicyLab.cs`+- `Aetheris.Kernel.Core/Step242/Step242BsplineSurfaceRecoveryLane.cs`+- `docs/frictionlab/cir-brep-x5-frep-brep-recovery-policy-lab.md`+- `docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md`++## 3. Candidate policy shapes+A) `BoxCylinderThroughHolePolicyShape` (pair-specific)+B) `ThroughHoleRecoveryPolicyShape` (semantic-first, bounded specialization)+C) `CylindricalToolCutPolicyShape` (tool-family)+D) `CirBooleanRecoveryPolicyShape` (generic boolean)+E) Fallbacks: `GenericNumericalContourPolicy`, `CirOnlyFallbackPolicy`++## 4. Scenario matrix+Implemented groups A/B/C/D/E/F in CIRLab scenario matrix with mixed real CIR and deferred synthetic records.++## 5. Policy evaluation dimensions+Recorded per policy/scenario:+`Admissible`, `Score`, `Capability`, `RecoveryPlanShape`, `EvidenceUsed`, `RejectedReasons`, `OverAdmits`, `UnderAdmits`, `PairSpecificityRisk`, `FutureScalabilityScore`, `Diagnostics`.++## 6. JudgmentEngine decision results+JudgmentEngine-based ranking picks `ThroughHoleRecoveryPolicyShape` for canonical A-scenarios, rejects it for B/C/E/F, and routes unsupported/deferred to fallback outcomes deterministically.++## 7. Over-admission / under-admission analysis+- Pair-specific: low over-admission, high under-admission for future variants.+- Through-hole: good canonical precision and bounded extensibility.+- Cylindrical-tool: over-admits notch/pocket/groove-like classes.+- Generic-boolean: over-broad dispatcher risk.++## 8. Pair-specific explosion risk analysis+Pair-specific policy scales poorly (`Host×Tool×Feature` multiplication) and pushes architecture toward policy proliferation.++## 9. Future scalability recommendation+Adopt semantic family lanes (e.g., ThroughHole, Counterbore, Countersink) with bounded host/tool specializations as internal recognizers.++## 10. Recommended production policy shape+Use `ThroughHoleRecoveryPolicy` as first production semantic policy.++## 11. Recommended recovery plan shape+Use semantic plan (not pair-specific) such as:+- host family/kind+- tool family/kind+- axis/interval classification+- entry/exit participation+- hole profile + expected patch/trim contracts+- capability + diagnostics++## 12. How BoxCylinderThroughHole should appear in architecture+As internal specialization helper/recognizer branch under `ThroughHoleRecoveryPolicy`, not as top-level long-term policy family.++## 13. Deferred/fallback policy guidance+Keep `GenericNumericalContourPolicy` and `CirOnlyFallbackPolicy` as explicit bounded fallbacks with clear capability semantics.++## 14. Recommended production implementation milestone+Implement production `ThroughHoleRecoveryPolicy` using `CirBoxCylinderRecognizer` as first specialization, returning a diagnostic-rich `ThroughHoleRecoveryPlan` before execution wiring.++## 15. Confidence ratings+- Policy-shape recommendation: High+- Scenario coverage adequacy: Medium-High+- Generalization risk assessment: Medium