Skip to content

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