Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-RECOVERY-X7 hole-family policy shape FrictionLab
Yuechen Li75f8bff19d19
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/HoleFamilyPolicyShapeLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/HoleFamilyPolicyShapeLab.csnew file mode 100644index 00000000..347a0660--- /dev/null+++ b/Aetheris.Firmament.FrictionLab/CIRLab/HoleFamilyPolicyShapeLab.cs@@ -0,0 +1,95 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Judgment;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.FrictionLab;++public enum HoleFamilyScenarioExpectation { ExactHoleFamily, FutureHoleFamily, DeferredForge, NotHoleFamily }+public enum HoleFamilyArchitectureKind { SeparatePolicySet, MonolithicHolePolicy, CompositionalHolePolicy, ProfileStackPolicy }+public enum HoleFeatureKind { Through, Blind, Counterbore, Countersink, Stepped, ChamferedEntry, Threaded, Unknown }++public sealed record HoleFamilyScenario(string Id, string Group, string Description, CirNode? Root, HoleFeatureKind FeatureKind, HoleFamilyScenarioExpectation Expectation);+public sealed record HoleFamilyArchitectureScore(string Architecture, bool AdmitsScenario, bool CorrectlyRejectsScenario, int PolicyCountGrowth, int BranchComplexity, int LocalityOfChangeScore, int DiagnosticClarityScore, int FutureScalabilityScore, int RiskOfOverAdmission, int RiskOfUnderAdmission, int PlanShapeQuality, int ExecutorReusability, IReadOnlyList<string> Diagnostics);+public sealed record HoleFamilyDecision(string Winner, IReadOnlyList<HoleFamilyArchitectureScore> Scores, IReadOnlyList<string> Diagnostics);++public static class HoleFamilyPolicyShapeLab+{+ public static IReadOnlyList<HoleFamilyScenario> BuildScenarioMatrix() =>+ [+ new("A1","A","box + cylindrical through-hole",new CirSubtractNode(new CirBoxNode(10,8,6),new CirCylinderNode(2,8)),HoleFeatureKind.Through,HoleFamilyScenarioExpectation.ExactHoleFamily),+ new("A2","A","translated box + translated cylindrical through-hole",new CirSubtractNode(new CirTransformNode(new CirBoxNode(10,8,6),Transform3D.CreateTranslation(new(2,1,3))),new CirTransformNode(new CirCylinderNode(2,8),Transform3D.CreateTranslation(new(2.5,1,3)))),HoleFeatureKind.Through,HoleFamilyScenarioExpectation.ExactHoleFamily),+ new("A3","A","offset cylindrical through-hole",new CirSubtractNode(new CirBoxNode(10,8,6),new CirTransformNode(new CirCylinderNode(1.5,8),Transform3D.CreateTranslation(new(1,1,0)))),HoleFeatureKind.Through,HoleFamilyScenarioExpectation.ExactHoleFamily),+ new("B1","B","box + blind hole",new CirSubtractNode(new CirBoxNode(10,8,6),new CirCylinderNode(2,3)),HoleFeatureKind.Blind,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("B2","B","box + counterbore",null,HoleFeatureKind.Counterbore,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("B3","B","box + countersink",null,HoleFeatureKind.Countersink,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("B4","B","box + stepped through-hole",null,HoleFeatureKind.Stepped,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("B5","B","box + chamfered-entry through-hole",null,HoleFeatureKind.ChamferedEntry,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("C1","C","cylindrical host + axial hole",null,HoleFeatureKind.Through,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("C2","C","cylindrical host + radial hole",null,HoleFeatureKind.Through,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("C3","C","conical tool tapered hole",null,HoleFeatureKind.Countersink,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("C4","C","rectangular host + hole pattern",null,HoleFeatureKind.Through,HoleFamilyScenarioExpectation.FutureHoleFamily),+ new("D1","D","threaded hole",null,HoleFeatureKind.Threaded,HoleFamilyScenarioExpectation.DeferredForge),+ new("D2","D","knurled/texture feature",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.DeferredForge),+ new("D3","D","arbitrary swept slot",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.DeferredForge),+ new("D4","D","freeform projected emboss/deboss",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.DeferredForge),+ new("E1","E","round groove",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.NotHoleFamily),+ new("E2","E","keyway/slot",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.NotHoleFamily),+ new("E3","E","side notch",new CirSubtractNode(new CirBoxNode(10,8,6),new CirTransformNode(new CirCylinderNode(2,8),Transform3D.CreateTranslation(new(4,0,0)))),HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.NotHoleFamily),+ new("E4","E","box - sphere cavity",new CirSubtractNode(new CirBoxNode(10,8,6),new CirSphereNode(2)),HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.NotHoleFamily),+ new("E5","E","generic torus subtract",null,HoleFeatureKind.Unknown,HoleFamilyScenarioExpectation.NotHoleFamily)+ ];++ public static IReadOnlyList<string> InventoryVocabulary() =>+ [+ "through-hole: first-class semantic recovery policy in production",+ "blind-hole: present in docs/frictionlab fixtures and boolean-deferred, not first-class recovery policy",+ "counterbore/countersink: present in FrictionLab cases and docs, not first-class recovery policy",+ "threaded hole: deferred/forge-style and surface-feature docs indicate deferred",+ "slot/keyway: bounded subtract families present in primitive execution vocabulary",+ "chamfer/fillet: bounded edge-feature families present",+ "round groove: surface-feature A0-A4 descriptor/planning/evidence path"+ ];++ public static HoleFamilyArchitectureScore Evaluate(HoleFamilyArchitectureKind kind, HoleFamilyScenario scenario)+ {+ var exact = scenario.Expectation == HoleFamilyScenarioExpectation.ExactHoleFamily;+ var future = scenario.Expectation == HoleFamilyScenarioExpectation.FutureHoleFamily;+ var deferred = scenario.Expectation == HoleFamilyScenarioExpectation.DeferredForge;+ var notHole = scenario.Expectation == HoleFamilyScenarioExpectation.NotHoleFamily;++ return kind switch+ {+ HoleFamilyArchitectureKind.SeparatePolicySet => Score("SeparatePolicySet", exact, future, deferred, notHole, 9, 8, 6, 6, 7, scenario),+ HoleFamilyArchitectureKind.MonolithicHolePolicy => Score("MonolithicHolePolicy", exact, future, deferred, notHole, 3, 10, 3, 4, 8, scenario),+ HoleFamilyArchitectureKind.CompositionalHolePolicy => Score("CompositionalHolePolicy", exact, future, deferred, notHole, 4, 4, 10, 9, 2, scenario),+ HoleFamilyArchitectureKind.ProfileStackPolicy => Score("ProfileStackPolicy", exact, future, deferred, notHole, 5, 6, 8, 7, 5, scenario),+ _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null)+ };+ }++ public static HoleFamilyDecision Recommend(HoleFamilyScenario scenario)+ {+ var scores = Enum.GetValues<HoleFamilyArchitectureKind>().Select(k => Evaluate(k, scenario)).ToArray();+ var byName = scores.ToDictionary(s => s.Architecture, StringComparer.Ordinal);+ var engine = new JudgmentEngine<HoleFamilyScenario>();+ var judgment = engine.Evaluate(scenario, scores.Select((s, idx) => new JudgmentCandidate<HoleFamilyScenario>(s.Architecture, _ => s.AdmitsScenario || s.CorrectlyRejectsScenario, _ => Aggregate(s), _ => string.Join(" | ", s.Diagnostics), idx)).ToArray());+ var winner = judgment.IsSuccess ? judgment.Selection!.Value.Candidate.Name : "CompositionalHolePolicy";+ return new(winner, scores.OrderByDescending(Aggregate).ThenBy(s => s.Architecture).ToArray(), [..judgment.Rejections.Select(r => $"{r.CandidateName}:{r.Reason}")]);+ }++ private static HoleFamilyArchitectureScore Score(string arch, bool exact, bool future, bool deferred, bool notHole, int growth, int complexity, int locality, int scalability, int overRisk, HoleFamilyScenario s)+ {+ var admits = exact || (future && arch != "SeparatePolicySet") || (future && arch == "SeparatePolicySet" && s.FeatureKind is HoleFeatureKind.Counterbore or HoleFeatureKind.Countersink);+ if (deferred || notHole) admits = arch == "ProfileStackPolicy" && s.Id == "E3"; // intentional over-admission evidence+ var rejectOk = (deferred || notHole) && !admits;+ var underRisk = future && !admits ? 8 : 2;+ var diag = new List<string>();+ if (admits && (deferred || notHole)) diag.Add("over-admission-detected");+ if (!admits && future) diag.Add("future-under-admission");+ if (arch == "MonolithicHolePolicy") diag.Add("branch-maze-risk");+ return new(arch, admits, rejectOk, growth, complexity, locality, 8 - complexity / 2, scalability, overRisk, underRisk, 10 - complexity / 2, 10 - growth / 2, diag);+ }++ private static double Aggregate(HoleFamilyArchitectureScore s)+ => (s.LocalityOfChangeScore * 3) + (s.FutureScalabilityScore * 3) + (s.DiagnosticClarityScore * 2) + s.PlanShapeQuality + s.ExecutorReusability - (s.RiskOfOverAdmission * 2) - s.RiskOfUnderAdmission - s.BranchComplexity;+}diff --git a/Aetheris.FrictionLab.Tests/CIRLab/HoleFamilyPolicyShapeLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/HoleFamilyPolicyShapeLabTests.csnew file mode 100644index 00000000..5f1a17df--- /dev/null+++ b/Aetheris.FrictionLab.Tests/CIRLab/HoleFamilyPolicyShapeLabTests.cs@@ -0,0 +1,82 @@+using Aetheris.FrictionLab;++namespace Aetheris.FrictionLab.Tests.CIRLab;++public sealed class HoleFamilyPolicyShapeLabTests+{+ [Fact]+ public void HolePolicyShape_CurrentThroughHoleSupported()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "A1");+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(score.AdmitsScenario, "Recommended compositional architecture should admit current exact through-hole case A1.");+ }++ [Fact]+ public void HolePolicyShape_CounterboreFitsRecommendedShape()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "B2");+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(score.AdmitsScenario, "Counterbore should map to compositional hole-family architecture without adding a new top-level spaghetti branch.");+ }++ [Fact]+ public void HolePolicyShape_CountersinkFitsRecommendedShape()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "B3");+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(score.AdmitsScenario, "Countersink should map to compositional hole-family architecture via local profile/entry modules.");+ }++ [Fact]+ public void HolePolicyShape_SurfaceFeatureNotCaptured()+ {+ foreach (var id in new[] { "E1", "E2", "D1" })+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == id);+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(score.CorrectlyRejectsScenario, $"{id} should be rejected or deferred by hole exact policies; captured={score.AdmitsScenario}.");+ }+ }++ [Fact]+ public void HolePolicyShape_CylindricalToolOverAdmissionDetected()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "E3");+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.ProfileStackPolicy, s);+ Assert.True(score.AdmitsScenario && score.Diagnostics.Any(d => d.Contains("over-admission", StringComparison.OrdinalIgnoreCase)), "Profile stack policy should expose cylindrical-tool over-admission risk on side-notch scenario E3.");+ }++ [Fact]+ public void HolePolicyShape_MonolithicPolicyComplexityDetected()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "B5");+ var mono = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.MonolithicHolePolicy, s);+ var comp = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(mono.BranchComplexity > comp.BranchComplexity && mono.LocalityOfChangeScore < comp.LocalityOfChangeScore, "Monolithic policy should score worse on branch complexity/locality than compositional architecture.");+ }++ [Fact]+ public void HolePolicyShape_DeterministicRecommendation()+ {+ var s = HoleFamilyPolicyShapeLab.BuildScenarioMatrix().Single(x => x.Id == "B4");+ var run1 = HoleFamilyPolicyShapeLab.Recommend(s).Winner;+ var run2 = HoleFamilyPolicyShapeLab.Recommend(s).Winner;+ Assert.Equal(run1, run2);+ Assert.Equal("CompositionalHolePolicy", run1);+ }++ [Fact]+ public void HolePolicyShape_ReportCoverageComplete()+ {+ var scenarios = HoleFamilyPolicyShapeLab.BuildScenarioMatrix();+ foreach (var group in new[] { "A", "B", "C", "D", "E" })+ {+ Assert.Contains(scenarios, s => s.Group == group);+ }++ var s = scenarios.First();+ var score = HoleFamilyPolicyShapeLab.Evaluate(HoleFamilyArchitectureKind.CompositionalHolePolicy, s);+ Assert.True(score.GetType().GetProperties().Length >= 12, "Result shape should include required evaluation dimensions for report table completeness.");+ }+}diff --git a/docs/frictionlab/cir-recovery-x7-hole-family-policy-shape-lab.md b/docs/frictionlab/cir-recovery-x7-hole-family-policy-shape-lab.mdnew file mode 100644index 00000000..1160336b--- /dev/null+++ b/docs/frictionlab/cir-recovery-x7-hole-family-policy-shape-lab.md@@ -0,0 +1,127 @@+# CIR-RECOVERY-X7: semantic hole-family policy-shape lab++## 1. Purpose and scope+This FrictionLab-only architecture/design lab evaluates scalable semantic policy-family shapes for hole-like recovery (through, blind, counterbore, countersink, stepped) without changing production policy/catalog/executor behavior.++## 2. Source code/docs inspected+- `Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPolicyCatalog.cs`+- `Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryPolicy.cs`+- `Aetheris.Kernel.Firmament/Materializer/ThroughHoleRecoveryExecutor.cs`+- `Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs`+- `Aetheris.Kernel.Firmament/Materializer/CirBoxCylinderRecognizer.cs`+- `docs/frictionlab/cir-brep-x5-frep-brep-recovery-policy-lab.md`+- `docs/frictionlab/cir-brep-x6-policy-shape-doe.md`+- `docs/cir-recovery-v5-policy-catalog.md`+- `docs/cir-recovery-v1b-through-hole-policy.md`+- `docs/surface-feature-a0-architecture-audit.md` through `surface-feature-a4-planar-groove-evidence.md`+- `docs/boolean-deferred.md`, `docs/groove-a0-bounded-revolved-groove-audit.md`++## 3. Existing hole-like vocabulary inventory+- Through-hole: first-class semantic recovery policy (`ThroughHoleRecoveryPolicy`) and plan/executor path in production.+- Blind hole: represented in docs/fixtures and deferred boolean families; not first-class policy in catalog.+- Counterbore/countersink: present in FrictionLab fixtures and docs vocabulary; not first-class in production recovery catalog.+- Stepped hole/chamfered entry: conceptually present via feature language/docs; not first-class recovery policies.+- Threaded hole: explicitly deferred/forge-like path.+- Slot/keyway: present as bounded subtract/prismatic families (non-hole-family subsystem).+- Round groove/surface features: active surface-feature descriptor/planning/evidence track (A0-A4), distinct from hole-family policy lane.++## 4. Candidate architecture shapes+- **A SeparatePolicySet**: one top-level policy per hole type.+- **B MonolithicHolePolicy**: one large top-level policy with variant branch maze.+- **C CompositionalHolePolicy**: one top-level hole policy delegating to host/axis/depth/entry/profile classifiers + plan builder.+- **D ProfileStackPolicy**: axial segment/profile-stack policy.++## 5. Scenario matrix+Implemented groups A-E with required scenarios:+- A: currently supported through-hole variants (A1-A3)+- B: likely next exact families (blind/counterbore/countersink/stepped/chamfered-entry)+- C: future host/tool variants+- D: should defer to Forge/deferred+- E: non-hole families (groove, keyway, notch, sphere cavity, torus subtract)++## 6. Evaluation dimensions+Per architecture/scenario scoring includes:+- `AdmitsScenario`+- `CorrectlyRejectsScenario`+- `PolicyCountGrowth`+- `BranchComplexity`+- `LocalityOfChangeScore`+- `DiagnosticClarityScore`+- `FutureScalabilityScore`+- `RiskOfOverAdmission`+- `RiskOfUnderAdmission`+- `PlanShapeQuality`+- `ExecutorReusability`++## 7. JudgmentEngine/meta-scoring method+`JudgmentEngine` is used for bounded meta-selection among architecture candidates with deterministic aggregate scoring. This matches AGENTS guidance (multiple bounded strategies, explicit admissibility/scoring/tie-break).++## 8. Results summary+Across canonical, future, deferred, and non-hole scenarios:+- **CompositionalHolePolicy** consistently wins on locality/generalizability/diagnostic clarity balance with bounded admission.+- **SeparatePolicySet** is precise but trends toward policy-count growth and cross-policy drift.+- **MonolithicHolePolicy** performs poorly on branch complexity and locality-of-change.+- **ProfileStackPolicy** is expressive but over-admits cylindrical non-hole cases unless tightly gated by host/entry/depth semantics.++## 9. Over/under-admission analysis+- Over-admission risk highest in profile/tool-stack-only interpretation (e.g., side-notch cylindrical subtract).+- Under-admission risk highest in separate-policy set for future variants before policy additions.+- Compositional policy best balances bounded admissibility with extension points.++## 10. Locality-of-change analysis+Compositional shape supports additive module growth (new classifier/plan-segment builder + registration) with minimal edits; monolithic shape requires central branch edits and larger retest surface.++## 11. Future scalability recommendation+Adopt **Option C** as production trajectory:+- top-level `HoleRecoveryPolicy`+- internal classifier + variant modules+- explicit rejected/deferred reasons+- shared plan contracts and executor-reuse seam++## 12. Recommended production policy shape+```text+HoleRecoveryPolicy+ HostClassifier+ AxisClassifier+ HoleDepthClassifier+ EntryFeatureClassifier+ ToolProfileClassifier+ RecoveryPlanBuilder+```++## 13. Recommended production plan shape+```csharp+HoleRecoveryPlan+ HostKind+ Axis+ HoleKind+ DepthKind+ ProfileStack+ EntryFeature+ ExitFeature+ ExpectedSurfacePatches+ ExpectedTrimCurves+ Capability+ Diagnostics++HoleProfileSegment+ SegmentKind: Cylinder | Cone | Chamfer | ThreadDeferred+ RadiusStart+ RadiusEnd+ DepthStart+ DepthEnd+ SurfaceFamily+```+Mapping from current `ThroughHoleRecoveryPlan`: becomes `HoleKind=Through`, `DepthKind=Through`, one cylindrical segment, circular entry/exit rims, same expected patch/trim evidence.++## 14. What happens to current `ThroughHoleRecoveryPolicy`+Short-term keep as top-level production policy for stability; next milestone wrap/migrate semantics into `HoleRecoveryPolicy` first variant (`ThroughHoleVariant`) while preserving score band and diagnostics.++## 15. Recommended next production milestone+Introduce production `HoleRecoveryPolicy` scaffold with only `ThroughHoleVariant` implemented and catalog-registered above fallback, while leaving behavior-equivalent output to today; then add counterbore/countersink variants as local modules.++## 16. Confidence ratings+- Policy-family shape recommendation: **High**+- Scenario matrix sufficiency: **Medium-High**+- Plan-shape migration confidence: **Medium**+- Over/under-admission risk characterization: **Medium-High**