Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add FrepMaterializer policy planner scaffold
Yuechen Li32c59e13e9af
diff --git a/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPlannerTests.cs b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPlannerTests.csnew file mode 100644index 00000000..e4ad27d6--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/FrepMaterializerPlannerTests.cs@@ -0,0 +1,95 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Firmament.Execution;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class FrepMaterializerPlannerTests+{+ [Fact]+ public void Planner_SelectsHighestScoringAdmissiblePolicy()+ {+ var decision = FrepMaterializerPlanner.Decide(BuildContext(), [+ new FakePolicy("low", FrepMaterializerPolicyEvaluation.Admitted("low", 1d, FrepMaterializerCapability.CirOnly)),+ new FakePolicy("high", FrepMaterializerPolicyEvaluation.Admitted("high", 5d, FrepMaterializerCapability.ExactBRep))+ ]);++ Assert.Equal(FrepMaterializerDecisionStatus.Selected, decision.Status);+ Assert.Equal("high", decision.SelectedPolicyName);+ }++ [Fact]+ public void Planner_IgnoresRejectedPoliciesButKeepsEvaluations()+ {+ var rejection = FrepMaterializerPolicyEvaluation.Rejected("reject", "not canonical");+ var decision = FrepMaterializerPlanner.Decide(BuildContext(), [+ new FakePolicy("reject", rejection),+ new FakePolicy("winner", FrepMaterializerPolicyEvaluation.Admitted("winner", 2d, FrepMaterializerCapability.DiagnosticOnly))+ ]);++ Assert.Equal("winner", decision.SelectedPolicyName);+ Assert.Contains(decision.Evaluations, e => e.PolicyName == "reject" && !e.Admissible && e.RejectionReasons.Contains("not canonical"));+ }++ [Fact]+ public void Planner_NoAdmissiblePolicy_ReturnsNoAdmissibleDecision()+ {+ var decision = FrepMaterializerPlanner.Decide(BuildContext(), [+ new FakePolicy("reject1", FrepMaterializerPolicyEvaluation.Rejected("reject1", "x")),+ new FakePolicy("reject2", FrepMaterializerPolicyEvaluation.Rejected("reject2", "y"))+ ]);++ Assert.Equal(FrepMaterializerDecisionStatus.NoAdmissiblePolicy, decision.Status);+ Assert.Contains("No admissible policy found.", decision.Diagnostics);+ }++ [Fact]+ public void Planner_TieBreakIsDeterministic()+ {+ var decision = FrepMaterializerPlanner.Decide(BuildContext(), [+ new FakePolicy("beta", FrepMaterializerPolicyEvaluation.Admitted("beta", 3d, FrepMaterializerCapability.CirOnly)),+ new FakePolicy("alpha", FrepMaterializerPolicyEvaluation.Admitted("alpha", 3d, FrepMaterializerCapability.ExactBRep))+ ]);++ Assert.Equal("beta", decision.SelectedPolicyName);+ Assert.Contains(decision.Diagnostics, d => d.Contains("Deterministic tie-break applied", StringComparison.Ordinal));+ }++ [Fact]+ public void Context_IsNodeFirstAndReplayOptional()+ {+ var root = new CirBoxNode(1, 2, 3);+ var rootOnly = new FrepMaterializerContext(root);+ var replay = new NativeGeometryReplayLog([]);+ var withReplay = new FrepMaterializerContext(root, replay, "fixture");++ Assert.Same(root, rootOnly.Root);+ Assert.Null(rootOnly.ReplayLog);+ Assert.Same(replay, withReplay.ReplayLog);+ Assert.Equal("fixture", withReplay.SourceLabel);+ }++ [Fact]+ public void Decision_PreservesAllEvaluationsAndDiagnostics()+ {+ var decision = FrepMaterializerPlanner.Decide(BuildContext(), [+ new FakePolicy("r", FrepMaterializerPolicyEvaluation.Rejected("r", "reason")),+ new FakePolicy("w", FrepMaterializerPolicyEvaluation.Admitted("w", 1d, FrepMaterializerCapability.DiagnosticOnly, diagnostics: ["diag"]))+ ]);++ Assert.Equal(2, decision.Evaluations.Count);+ Assert.Contains("FrepMaterializerPlanner started.", decision.Diagnostics);+ Assert.Contains("Policy count: 2.", decision.Diagnostics);+ Assert.Contains("Rejected policy count: 1.", decision.Diagnostics);+ Assert.Contains("Selected policy: w.", decision.Diagnostics);+ }++ private static FrepMaterializerContext BuildContext() => new(new CirBoxNode(2, 2, 2));++ private sealed class FakePolicy(string name, FrepMaterializerPolicyEvaluation evaluation) : IFrepMaterializerPolicy+ {+ public string Name => name;++ public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context) => evaluation;+ }+}diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.csnew file mode 100644index 00000000..1890d36f--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/FrepMaterializerPlanner.cs@@ -0,0 +1,124 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Judgment;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Materializer;++public interface IFrepMaterializerPolicy+{+ string Name { get; }++ FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context);+}++public sealed record FrepMaterializerContext(+ CirNode Root,+ NativeGeometryReplayLog? ReplayLog = null,+ string? SourceLabel = null);++public enum FrepMaterializerCapability+{+ ExactBRep,+ DiagnosticOnly,+ CirOnly,+ Unsupported+}++public sealed record FrepMaterializerPolicyEvaluation(+ string PolicyName,+ bool Admissible,+ double Score,+ FrepMaterializerCapability Capability,+ IReadOnlyList<string> Evidence,+ IReadOnlyList<string> RejectionReasons,+ IReadOnlyList<string> Diagnostics)+{+ public static FrepMaterializerPolicyEvaluation Admitted(+ string policyName,+ double score,+ FrepMaterializerCapability capability,+ IReadOnlyList<string>? evidence = null,+ IReadOnlyList<string>? diagnostics = null)+ => new(policyName, true, score, capability, evidence ?? Array.Empty<string>(), Array.Empty<string>(), diagnostics ?? Array.Empty<string>());++ public static FrepMaterializerPolicyEvaluation Rejected(+ string policyName,+ params string[] rejectionReasons)+ => new(policyName, false, 0d, FrepMaterializerCapability.Unsupported, Array.Empty<string>(), rejectionReasons, Array.Empty<string>());+}++public enum FrepMaterializerDecisionStatus+{+ Selected,+ NoAdmissiblePolicy,+ InvalidInput+}++public sealed record FrepMaterializerDecision(+ FrepMaterializerDecisionStatus Status,+ string? SelectedPolicyName,+ FrepMaterializerCapability Capability,+ IReadOnlyList<FrepMaterializerPolicyEvaluation> Evaluations,+ IReadOnlyList<string> Diagnostics);++public static class FrepMaterializerPlanner+{+ private static readonly JudgmentEngine<FrepMaterializerContext> Engine = new();++ public static FrepMaterializerDecision Decide(+ FrepMaterializerContext context,+ IReadOnlyList<IFrepMaterializerPolicy> policies)+ {+ ArgumentNullException.ThrowIfNull(context);+ ArgumentNullException.ThrowIfNull(policies);++ var diagnostics = new List<string>+ {+ "FrepMaterializerPlanner started.",+ $"Policy count: {policies.Count}."+ };++ if (context.Root is null)+ {+ diagnostics.Add("Invalid input: CIR root is null.");+ return new(FrepMaterializerDecisionStatus.InvalidInput, null, FrepMaterializerCapability.Unsupported, Array.Empty<FrepMaterializerPolicyEvaluation>(), diagnostics);+ }++ var evaluations = policies.Select(p => p.Evaluate(context)).ToArray();+ var candidates = evaluations+ .Select((evaluation, index) => new JudgmentCandidate<FrepMaterializerContext>(+ evaluation.PolicyName,+ _ => evaluation.Admissible,+ _ => evaluation.Score,+ _ => evaluation.RejectionReasons.Count == 0+ ? "Policy evaluation was non-admissible."+ : string.Join(" | ", evaluation.RejectionReasons),+ index))+ .ToArray();++ var judgment = Engine.Evaluate(context, candidates);+ var rejectedCount = evaluations.Count(e => !e.Admissible);+ diagnostics.Add($"Rejected policy count: {rejectedCount}.");++ if (!judgment.IsSuccess)+ {+ diagnostics.Add("No admissible policy found.");+ return new(FrepMaterializerDecisionStatus.NoAdmissiblePolicy, null, FrepMaterializerCapability.Unsupported, evaluations, diagnostics);+ }++ var selectedName = judgment.Selection!.Value.Candidate.Name;+ var selected = evaluations.Single(e => string.Equals(e.PolicyName, selectedName, StringComparison.Ordinal));+ diagnostics.Add($"Selected policy: {selectedName}.");++ var tiedPeers = evaluations+ .Where(e => e.Admissible && double.Abs(e.Score - selected.Score) <= 1e-12)+ .Select(e => e.PolicyName)+ .ToArray();+ if (tiedPeers.Length > 1)+ {+ diagnostics.Add($"Deterministic tie-break applied among: {string.Join(", ", tiedPeers)}.");+ }++ return new(FrepMaterializerDecisionStatus.Selected, selected.PolicyName, selected.Capability, evaluations, diagnostics);+ }+}diff --git a/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.mdnew file mode 100644index 00000000..80e31b03--- /dev/null+++ b/docs/cir-recovery-v1a-frep-materializer-policy-scaffold.md@@ -0,0 +1,44 @@+# CIR-RECOVERY-V1A: FrepMaterializer policy scaffold++## Why this exists++FRep/CIR to BRep is an intent recovery (decompilation) problem, not a direct syntax translation problem. Multiple bounded strategies may be plausible for one input, so policy scoring and admissibility must be explicit and deterministic.++## What this milestone adds++This milestone introduces production scaffolding under `Aetheris.Kernel.Firmament.Materializer`:++- `IFrepMaterializerPolicy`+- `FrepMaterializerContext`+- `FrepMaterializerCapability`+- `FrepMaterializerPolicyEvaluation`+- `FrepMaterializerDecisionStatus`+- `FrepMaterializerDecision`+- `FrepMaterializerPlanner`++The planner evaluates all policies, retains all evaluations (including rejected ones), and selects an admissible policy via `JudgmentEngine<TContext>`.++## Context shape (v1)++The context is node-first and intentionally minimal:++- `CirNode Root`+- optional `NativeGeometryReplayLog`+- optional `SourceLabel`++No lowering plan or execution-state dependency is required in V1A.++## JudgmentEngine usage++`FrepMaterializerPlanner` maps each policy evaluation to a `JudgmentCandidate<FrepMaterializerContext>` and uses score as utility. Determinism follows `JudgmentEngine` ordering: score, tie-break priority, name, declaration order.++## Not included in V1A++- no production `BoxCylinderThroughHolePolicy`+- no BRep body emission+- no STEP export wiring+- no rematerializer integration changes++## Next milestone++CIR-RECOVERY-V1B should add a first production semantic policy (`BoxCylinderThroughHolePolicy`) that emits diagnostic-rich evaluation only (or bounded exact path if explicitly scoped), while preserving existing behavior gates.