Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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**