Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-BREP-X5 FrictionLab FRep→BRep recovery policy prototype

Yuechen Liab61cd865f20
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/FrepBrepRecoveryPolicyLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/FrepBrepRecoveryPolicyLab.cs
new file mode 100644
index 00000000..9c85e723
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/FrepBrepRecoveryPolicyLab.cs
@@ -0,0 +1,133 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Judgment;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.FrictionLab;
+
+public enum FrepBrepRecoveryCapability
+{
+ ExactBrepAndStep,
+ BoundedBrepPreview,
+ IntentOnlyFallback
+}
+
+public sealed record FrepBrepRecoveryContext(
+ CirNode Root,
+ NativeGeometryReplayLog? ReplayLog = null,
+ IReadOnlyList<string>? UpstreamDiagnostics = null,
+ bool TrimOracleAgreementAvailable = false,
+ bool TrimOracleAgreement = false,
+ bool VolumeAgreementAvailable = false,
+ bool VolumeAgreement = false,
+ bool ExportCapabilityAvailable = true,
+ bool TopologyTemplateReady = false);
+
+public sealed record FrepBrepRecoveryPolicyEvaluation(
+ string PolicyName,
+ bool Admissible,
+ double Score,
+ FrepBrepRecoveryCapability Capability,
+ string RecommendedRoute,
+ IReadOnlyList<string> Evidence,
+ IReadOnlyList<string> RejectionReasons,
+ IReadOnlyList<string> Diagnostics);
+
+public sealed record FrepBrepRecoveryDecision(
+ string? SelectedPolicy,
+ string? SelectedRoute,
+ IReadOnlyList<FrepBrepRecoveryPolicyEvaluation> Candidates,
+ IReadOnlyList<string> Diagnostics);
+
+public interface IFrepBrepRecoveryPolicy
+{
+ string Name { get; }
+ int TieBreakerPriority { get; }
+ FrepBrepRecoveryPolicyEvaluation Evaluate(FrepBrepRecoveryContext context);
+}
+
+public static class FrepBrepRecoveryPolicyLab
+{
+ public static readonly IFrepBrepRecoveryPolicy[] DefaultPolicies =
+ [
+ new BoxCylinderThroughHolePolicy(),
+ new GenericNumericalContourPolicy(),
+ new CirOnlyFallbackPolicy()
+ ];
+
+ public static FrepBrepRecoveryDecision SelectBestPolicy(FrepBrepRecoveryContext context, IReadOnlyList<IFrepBrepRecoveryPolicy>? policies = null)
+ {
+ var policySet = policies ?? DefaultPolicies;
+ var evals = policySet.Select(p => p.Evaluate(context)).ToArray();
+ var map = evals.ToDictionary(e => e.PolicyName, StringComparer.Ordinal);
+ var engine = new JudgmentEngine<FrepBrepRecoveryContext>();
+ var candidates = policySet.Select(p => new JudgmentCandidate<FrepBrepRecoveryContext>(
+ p.Name,
+ c => map[p.Name].Admissible,
+ c => map[p.Name].Score,
+ c => map[p.Name].RejectionReasons.Count == 0 ? "inadmissible" : string.Join(" | ", map[p.Name].RejectionReasons),
+ p.TieBreakerPriority)).ToArray();
+ var result = engine.Evaluate(context, candidates);
+ var diagnostics = new List<string> { $"policy_count={policySet.Count}" };
+ diagnostics.AddRange(evals.Select(e => $"candidate:{e.PolicyName}:admissible={e.Admissible}:score={e.Score:F3}"));
+ diagnostics.Add(result.IsSuccess
+ ? $"selected={result.Selection!.Value.Candidate.Name}"
+ : "selected=<none>");
+ diagnostics.AddRange(result.Rejections.Select(r => $"rejection:{r.CandidateName}:{r.Reason}"));
+
+ var selectedName = result.IsSuccess ? result.Selection!.Value.Candidate.Name : null;
+ return new(selectedName, selectedName is null ? null : map[selectedName].RecommendedRoute, evals, diagnostics);
+ }
+
+ private sealed class BoxCylinderThroughHolePolicy : IFrepBrepRecoveryPolicy
+ {
+ public string Name => "BoxCylinderThroughHolePolicy";
+ public int TieBreakerPriority => 0;
+
+ public FrepBrepRecoveryPolicyEvaluation Evaluate(FrepBrepRecoveryContext context)
+ {
+ var evidence = new List<string>();
+ var rejects = new List<string>();
+ var diagnostics = new List<string>();
+ var recognition = CirBrepX4RecognizerSourceContractLab.Recognize(CirBoxCylinderRecognizerInput.FromNode(context.Root, context.ReplayLog));
+ if (!recognition.Recognition.Success)
+ {
+ rejects.Add($"recognizer_failed:{recognition.Recognition.Reason}");
+ diagnostics.Add(recognition.Recognition.Diagnostic);
+ }
+ else
+ {
+ evidence.Add("recognizer=canonical_box_cylinder");
+ evidence.Add("transform=v1_translation_supported");
+ evidence.Add("through_hole=passed");
+ evidence.Add("strict_clearance=passed");
+ }
+
+ var score = 0d;
+ if (recognition.Recognition.Success) score += 60;
+ if (context.ReplayLog is not null) { evidence.Add("replay=available"); score += recognition.ReplayGeometryMismatch ? 0 : 8; }
+ else diagnostics.Add("replay=missing");
+ if (context.TrimOracleAgreementAvailable) { evidence.Add($"trim_oracle={context.TrimOracleAgreement}"); score += context.TrimOracleAgreement ? 10 : 0; } else diagnostics.Add("trim_oracle=deferred");
+ if (context.VolumeAgreementAvailable) { evidence.Add($"volume_probe={context.VolumeAgreement}"); score += context.VolumeAgreement ? 8 : 0; } else diagnostics.Add("volume_probe=deferred");
+ if (context.ExportCapabilityAvailable) { evidence.Add("export=elementary_supported"); score += 8; }
+ if (context.TopologyTemplateReady) { evidence.Add("topology_template=ready"); score += 6; } else diagnostics.Add("topology_template=deferred");
+ diagnostics.AddRange(recognition.Diagnostics);
+ return new(Name, rejects.Count == 0, score, FrepBrepRecoveryCapability.ExactBrepAndStep, "Use existing BRep primitive + BrepBoolean.Subtract exact path", evidence, rejects, diagnostics);
+ }
+ }
+
+ private sealed class GenericNumericalContourPolicy : IFrepBrepRecoveryPolicy
+ {
+ public string Name => "GenericNumericalContourPolicy";
+ public int TieBreakerPriority => 1;
+ public FrepBrepRecoveryPolicyEvaluation Evaluate(FrepBrepRecoveryContext context)
+ => new(Name, true, 25d, FrepBrepRecoveryCapability.BoundedBrepPreview, "Use restricted-field trim oracle / numerical contour fallback", ["fallback=numerical_contour"], [], ["exact STEP not guaranteed"]);
+ }
+
+ private sealed class CirOnlyFallbackPolicy : IFrepBrepRecoveryPolicy
+ {
+ public string Name => "CirOnlyFallbackPolicy";
+ public int TieBreakerPriority => 2;
+ public FrepBrepRecoveryPolicyEvaluation Evaluate(FrepBrepRecoveryContext context)
+ => new(Name, true, 5d, FrepBrepRecoveryCapability.IntentOnlyFallback, "Retain CIR intent only; defer BRep recovery", ["fallback=cir_only"], [], ["intent-preserving fallback"]);
+ }
+}
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/FrepBrepRecoveryPolicyLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/FrepBrepRecoveryPolicyLabTests.cs
new file mode 100644
index 00000000..537deee1
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/FrepBrepRecoveryPolicyLabTests.cs
@@ -0,0 +1,92 @@
+using Aetheris.FrictionLab;
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public sealed class FrepBrepRecoveryPolicyLabTests
+{
+ [Fact]
+ public void RecoveryPolicy_BoxCylinder_SelectsSemanticPolicy()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 8, 6), new CirCylinderNode(2, 8));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.Equal("BoxCylinderThroughHolePolicy", result.SelectedPolicy);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_TranslatedBoxCylinder_SelectsSemanticPolicy()
+ {
+ var root = new CirSubtractNode(
+ new CirTransformNode(new CirBoxNode(10, 8, 6), Transform3D.CreateTranslation(new(2, 1, 5))),
+ new CirTransformNode(new CirCylinderNode(2, 8), Transform3D.CreateTranslation(new(2.5, 1.5, 5))));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.Equal("BoxCylinderThroughHolePolicy", result.SelectedPolicy);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_BoxSphere_DoesNotSelectBoxCylinderPolicy()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 8, 6), new CirSphereNode(2));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.NotEqual("BoxCylinderThroughHolePolicy", result.SelectedPolicy);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_BlindCylinder_RejectsSemanticPolicy()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 8, 6), new CirCylinderNode(2, 4));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.Contains(result.Candidates, c => c.PolicyName == "BoxCylinderThroughHolePolicy" && !c.Admissible && c.RejectionReasons.Any(r => r.Contains("recognizer_failed")));
+ }
+
+ [Fact]
+ public void RecoveryPolicy_TangentCylinder_RejectsSemanticPolicy()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 8, 6), new CirTransformNode(new CirCylinderNode(2, 8), Transform3D.CreateTranslation(new(3,0,0))));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.Contains(result.Candidates, c => c.PolicyName == "BoxCylinderThroughHolePolicy" && !c.Admissible);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_UnsupportedTransform_RejectsSemanticPolicy()
+ {
+ var root = new CirSubtractNode(new CirTransformNode(new CirBoxNode(10, 8, 6), Transform3D.CreateRotationX(Math.PI/4)), new CirCylinderNode(2, 8));
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(root));
+ Assert.Contains(result.Candidates, c => c.PolicyName == "BoxCylinderThroughHolePolicy" && !c.Admissible);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_DiagnosticsIncludeAllCandidates()
+ {
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(new CirBoxNode(1,1,1)));
+ Assert.Contains("candidate:BoxCylinderThroughHolePolicy", string.Join(";", result.Diagnostics));
+ Assert.Contains("candidate:GenericNumericalContourPolicy", string.Join(";", result.Diagnostics));
+ Assert.Contains("candidate:CirOnlyFallbackPolicy", string.Join(";", result.Diagnostics));
+ }
+
+ [Fact]
+ public void RecoveryPolicy_TieBreakIsDeterministic()
+ {
+ var policies = new IFrepBrepRecoveryPolicy[] { new SameScore("z"), new SameScore("a") };
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(new CirBoxNode(1,1,1)), policies);
+ Assert.Equal("a", result.SelectedPolicy);
+ }
+
+ [Fact]
+ public void RecoveryPolicy_ReportEvidenceShape()
+ {
+ var result = FrepBrepRecoveryPolicyLab.SelectBestPolicy(new(new CirSubtractNode(new CirBoxNode(10,8,6), new CirCylinderNode(2,8))));
+ var semantic = result.Candidates.Single(c => c.PolicyName == "BoxCylinderThroughHolePolicy");
+ Assert.NotEmpty(semantic.Evidence);
+ Assert.False(string.IsNullOrWhiteSpace(semantic.RecommendedRoute));
+ Assert.NotNull(result.SelectedRoute);
+ }
+
+ private sealed class SameScore(string name) : IFrepBrepRecoveryPolicy
+ {
+ public string Name => name;
+ public int TieBreakerPriority => 0;
+ public FrepBrepRecoveryPolicyEvaluation Evaluate(FrepBrepRecoveryContext context) => new(Name, true, 10, FrepBrepRecoveryCapability.IntentOnlyFallback, "r", [], [], []);
+ }
+}
diff --git a/docs/frictionlab/cir-brep-x5-frep-brep-recovery-policy-lab.md b/docs/frictionlab/cir-brep-x5-frep-brep-recovery-policy-lab.md
new file mode 100644
index 00000000..b3cc23f8
--- /dev/null
+++ b/docs/frictionlab/cir-brep-x5-frep-brep-recovery-policy-lab.md
@@ -0,0 +1,63 @@
+# CIR-BREP-X5: JudgmentEngine FRep→BRep recovery policy lab
+
+## 1) Purpose and scope
+Lab-only prototype for selecting bounded FRep/CIR→BRep recovery strategies via JudgmentEngine under `Aetheris.Firmament.FrictionLab/CIRLab` and `Aetheris.FrictionLab.Tests/CIRLab`.
+
+## 2) Analytic recovery lane findings
+`Step242BsplineSurfaceRecoveryLane` uses bounded candidates (`analytic_cylinder`, `reject`) with explicit admissibility gates (rational-like + cylinder probe), fixed utility scores, and concrete rejection reasons. It probes geometric invariants (ring profile, radius consistency, rail parallelism) before candidate admission.
+
+## 3) JudgmentEngine usage findings
+`JudgmentEngine<TContext>` provides deterministic selection by score, then tie-break priority, then name, then declaration order. This is appropriate because X5 is a bounded competing-strategy decision problem.
+
+## 4) Proposed FRep→BRep recovery policy architecture
+Use policy registry of admissibility-scored candidates over a shared `FrepBrepRecoveryContext`, returning rich evaluations and a global decision trace.
+
+## 5) Candidate policy interface/result shape
+Implemented:
+- `IFrepBrepRecoveryPolicy`
+- `FrepBrepRecoveryContext`
+- `FrepBrepRecoveryPolicyEvaluation`
+- `FrepBrepRecoveryDecision`
+
+## 6) Evidence categories and score policy
+Prototype evidence buckets:
+- semantic recognizer match
+- transform admissibility
+- through-hole + strict clearance
+- replay consistency
+- trim-oracle agreement (available/deferred)
+- volume/field agreement (available/deferred)
+- export capability
+- topology-template readiness
+
+## 7) BoxCylinderThroughHolePolicy behavior
+Uses `CirBrepX4RecognizerSourceContractLab` (which wraps production-recognizer semantics) and admits only recognized canonical box-cylinder through-hole pattern. Recommended route: existing BRep primitives + `BrepBoolean.Subtract` exact path.
+
+## 8) Competing/fallback policy behavior
+- `GenericNumericalContourPolicy`: always admissible bounded fallback for preview/analysis, lower score.
+- `CirOnlyFallbackPolicy`: always admissible intent-preserving lowest-score fallback.
+
+## 9) Positive canonical decision result
+Canonical and translated box-cylinder fixtures select `BoxCylinderThroughHolePolicy` with highest score.
+
+## 10) Rejection/fallback decision results
+Non-subtract, box-sphere, blind cylinder, tangent/grazing, and unsupported transform cases reject semantic policy with explicit recognizer-derived reasons, then select fallback policy.
+
+## 11) Generalized hypothesis
+Best recovery should choose highest-level admissible semantic policy first, and only then fall back to lower-level numerical/intent routes.
+
+## 12) Recommended production architecture
+Productionize this as a dedicated FRep→BRep policy planner that consumes existing CIR recognizers, replay diagnostics, trim-oracle channels, readiness analyzers, and exporter capability probes.
+
+## 13) Recommended first production milestone
+Implement production `BoxCylinderThroughHolePolicy` planner lane, wired to materialization readiness + trim-oracle diagnostics, without changing exporter fallback behavior.
+
+## 14) Known blockers/deferred evidence channels
+- trim-oracle agreement currently represented as external context flags in lab
+- volume agreement currently external context flags
+- topology-template readiness not yet auto-derived in lab
+
+## 15) Confidence ratings
+- Policy architecture: High
+- Semantic box-cylinder route: High
+- Deferred evidence channel wiring: Medium