Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add JudgmentEngine STEP solid-root export planner
Yuechen Li8342a6604f4b
diff --git a/Aetheris.Kernel.Core.Tests/Step242/StepSolidRootExportPlannerTests.cs b/Aetheris.Kernel.Core.Tests/Step242/StepSolidRootExportPlannerTests.csnew file mode 100644index 00000000..584a36e5--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Step242/StepSolidRootExportPlannerTests.cs@@ -0,0 +1,89 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Step242;++namespace Aetheris.Kernel.Core.Tests.Step242;++public sealed class StepSolidRootExportPlannerTests+{+ [Fact]+ public void Planner_SingleShell_SelectsManifoldSolidBrep()+ {+ var box = BrepPrimitives.CreateBox(4d, 4d, 4d);+ Assert.True(box.IsSuccess);++ var decision = StepSolidRootExportPlanner.Decide(box.Value);++ Assert.Equal(StepSolidRootExportKind.ManifoldSolidBrep, decision.Kind);+ }++ [Fact]+ public void Planner_OuterAndInnerShells_SelectsBrepWithVoids()+ {+ var body = LoadVoidFixture();++ var decision = StepSolidRootExportPlanner.Decide(body);++ Assert.Equal(StepSolidRootExportKind.BrepWithVoids, decision.Kind);+ }++ [Fact]+ public void Planner_MultiShellWithoutRoles_SelectsUnsupported()+ {+ var imported = LoadVoidFixture();+ var noRoles = new BrepBody(imported.Topology, imported.Geometry, imported.Bindings, vertexPoints: null, safeBooleanComposition: imported.SafeBooleanComposition, shellRepresentation: null);++ var decision = StepSolidRootExportPlanner.Decide(noRoles);++ Assert.Equal(StepSolidRootExportKind.Unsupported, decision.Kind);+ Assert.Contains(decision.Diagnostics, d => d.Contains("missing", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void Planner_DiagnosticsIncludeRejectedPolicies()+ {+ var imported = LoadVoidFixture();+ var noRoles = new BrepBody(imported.Topology, imported.Geometry, imported.Bindings, vertexPoints: null, safeBooleanComposition: imported.SafeBooleanComposition, shellRepresentation: null);++ var decision = StepSolidRootExportPlanner.Decide(noRoles);++ var manifoldEval = decision.Evaluations.Single(e => e.PolicyName == "ManifoldSolidBrepExportPolicy");+ var voidEval = decision.Evaluations.Single(e => e.PolicyName == "BrepWithVoidsExportPolicy");+ Assert.False(manifoldEval.Admissible);+ Assert.False(voidEval.Admissible);+ Assert.NotEmpty(manifoldEval.RejectionReasons);+ Assert.NotEmpty(voidEval.RejectionReasons);+ }++ [Fact]+ public void Export_ExplicitVoidShells_StillEmitsBrepWithVoids()+ {+ var body = LoadVoidFixture();++ var export = Step242Exporter.ExportBody(body);++ Assert.True(export.IsSuccess);+ Assert.Contains("BREP_WITH_VOIDS", export.Value, StringComparison.Ordinal);+ }++ [Fact]+ public void Export_ThroughHole_RemainsManifold()+ {+ var fixturePath = Path.Combine(Step242CorpusManifestRunner.RepoRoot(), "testdata", "firmament", "exports", "boolean_box_cylinder_hole.step");+ var import = Step242Importer.ImportBody(File.ReadAllText(fixturePath));+ Assert.True(import.IsSuccess);++ var export = Step242Exporter.ExportBody(import.Value);++ Assert.True(export.IsSuccess);+ Assert.Contains("MANIFOLD_SOLID_BREP", export.Value, StringComparison.Ordinal);+ Assert.DoesNotContain("BREP_WITH_VOIDS", export.Value, StringComparison.Ordinal);+ }++ private static BrepBody LoadVoidFixture()+ {+ var fixturePath = Path.Combine(Step242CorpusManifestRunner.RepoRoot(), "testdata", "firmament", "exports", "boolean_box_sphere_cavity_basic.step");+ var import = Step242Importer.ImportBody(File.ReadAllText(fixturePath));+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));+ return import.Value;+ }+}diff --git a/Aetheris.Kernel.Core/Step242/Step242Exporter.cs b/Aetheris.Kernel.Core/Step242/Step242Exporter.csindex 14ded27c..c23e794a 100644--- a/Aetheris.Kernel.Core/Step242/Step242Exporter.cs+++ b/Aetheris.Kernel.Core/Step242/Step242Exporter.cs@@ -28,15 +28,19 @@ public static class Step242Exporterreturn Failure("Only single-body export is supported.", "Topology.Bodies");}- var shellIds = bodyNodes[0].ShellIds.OrderBy(s => s.Value).ToArray();+ var rootDecision = StepSolidRootExportPlanner.Decide(body);var shellRepresentation = body.ShellRepresentation;- if (shellRepresentation is null)+ if (rootDecision.Kind == StepSolidRootExportKind.Unsupported){- if (shellIds.Length != 1)- {- return Failure("Multi-shell export requires an explicit BrepBody shell representation.", "Topology.Shells");- }+ var plannerReason = rootDecision.Evaluations+ .FirstOrDefault(e => e.PolicyName == "UnsupportedShellTopologyPolicy")?+ .Diagnostics.FirstOrDefault() ?? "Unsupported shell topology for STEP solid root export.";+ return Failure(plannerReason, "Topology.Shells");+ }+ if (shellRepresentation is null)+ {+ var shellIds = bodyNodes[0].ShellIds.OrderBy(s => s.Value).ToArray();shellRepresentation = new BrepBodyShellRepresentation(shellIds[0], []);}@@ -60,7 +64,7 @@ public static class Step242Exporter}string brepId;- if (shellRepresentation.InnerShellIds.Count == 0)+ if (rootDecision.Kind == StepSolidRootExportKind.ManifoldSolidBrep){brepId = writer.AddEntity("MANIFOLD_SOLID_BREP", Step242TextWriter.String(options.ProductName), Step242TextWriter.Ref(outerClosedShellId));}diff --git a/Aetheris.Kernel.Core/Step242/StepSolidRootExportPlanner.cs b/Aetheris.Kernel.Core/Step242/StepSolidRootExportPlanner.csnew file mode 100644index 00000000..a90bce7a--- /dev/null+++ b/Aetheris.Kernel.Core/Step242/StepSolidRootExportPlanner.cs@@ -0,0 +1,186 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Judgment;+using Aetheris.Kernel.Core.Topology;++namespace Aetheris.Kernel.Core.Step242;++public enum StepSolidRootExportKind+{+ ManifoldSolidBrep,+ BrepWithVoids,+ Unsupported+}++public enum StepSolidRootExportCapability+{+ Supported,+ Unsupported+}++public sealed record StepSolidRootExportPolicyEvaluation(+ string PolicyName,+ bool Admissible,+ double Score,+ StepSolidRootExportKind Kind,+ IReadOnlyList<string> RejectionReasons,+ IReadOnlyList<string> Diagnostics);++public sealed record StepSolidRootExportDecision(+ StepSolidRootExportKind Kind,+ string SelectedPolicyName,+ StepSolidRootExportCapability Capability,+ IReadOnlyList<StepSolidRootExportPolicyEvaluation> Evaluations,+ IReadOnlyList<string> Diagnostics,+ int TopologyBodyCount,+ int TopologyShellCount,+ ShellId? OuterShellId,+ IReadOnlyList<ShellId> InnerShellIds);++public static class StepSolidRootExportPlanner+{+ private static readonly JudgmentEngine<BrepBody> Engine = new();++ public static StepSolidRootExportDecision Decide(BrepBody body)+ {+ ArgumentNullException.ThrowIfNull(body);++ var bodyNodes = body.Topology.Bodies.OrderBy(b => b.Id.Value).ToArray();+ var topologyBodyCount = bodyNodes.Length;+ var topologyShellCount = bodyNodes.Length == 1 ? bodyNodes[0].ShellIds.Count : 0;+ var shellRepresentation = body.ShellRepresentation;+ var innerShellIds = shellRepresentation?.InnerShellIds?.OrderBy(id => id.Value).ToArray() ?? Array.Empty<ShellId>();++ var diagnostics = new List<string>+ {+ "StepSolidRootExportPlanner started.",+ $"Topology body count: {topologyBodyCount}.",+ $"Topology shell count: {topologyShellCount}.",+ shellRepresentation is null ? "Shell representation: missing." : "Shell representation: found.",+ $"Outer shell id: {(shellRepresentation is null ? "<none>" : shellRepresentation.OuterShellId.Value.ToString())}.",+ $"Inner shell ids: {(innerShellIds.Length == 0 ? "<none>" : string.Join(",", innerShellIds.Select(s => s.Value)))}."+ };++ var evaluations = new[]+ {+ EvaluateManifold(body, bodyNodes, shellRepresentation),+ EvaluateBrepWithVoids(body, bodyNodes, shellRepresentation),+ EvaluateUnsupported(body, bodyNodes, shellRepresentation)+ };++ var candidates = evaluations.Select((evaluation, index) => new JudgmentCandidate<BrepBody>(+ 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(body, candidates);++ var manifoldAdmissible = evaluations.Single(e => e.Kind == StepSolidRootExportKind.ManifoldSolidBrep).Admissible;+ var voidsAdmissible = evaluations.Single(e => e.Kind == StepSolidRootExportKind.BrepWithVoids).Admissible;+ diagnostics.Add($"Manifold policy: {(manifoldAdmissible ? "admissible" : "rejected")}.");+ diagnostics.Add($"BrepWithVoids policy: {(voidsAdmissible ? "admissible" : "rejected")}.");++ if (manifoldAdmissible && voidsAdmissible)+ {+ diagnostics.Add("Conflict: both manifold and brep-with-voids policies are admissible.");+ }++ if (!judgment.IsSuccess)+ {+ diagnostics.Add("Unsupported fallback selected: no admissible policy from judgment engine.");+ return new(+ StepSolidRootExportKind.Unsupported,+ nameof(UnsupportedShellTopologyPolicy),+ StepSolidRootExportCapability.Unsupported,+ evaluations,+ diagnostics,+ topologyBodyCount,+ topologyShellCount,+ shellRepresentation?.OuterShellId,+ innerShellIds);+ }++ var selectedName = judgment.Selection!.Value.Candidate.Name;+ var selected = evaluations.Single(e => string.Equals(e.PolicyName, selectedName, StringComparison.Ordinal));+ diagnostics.Add($"Selected root kind: {selected.Kind} via {selected.PolicyName}.");+ if (selected.Kind == StepSolidRootExportKind.Unsupported)+ {+ diagnostics.Add("Unsupported fallback selected.");+ }++ return new(+ selected.Kind,+ selected.PolicyName,+ selected.Kind == StepSolidRootExportKind.Unsupported ? StepSolidRootExportCapability.Unsupported : StepSolidRootExportCapability.Supported,+ evaluations,+ diagnostics,+ topologyBodyCount,+ topologyShellCount,+ shellRepresentation?.OuterShellId,+ innerShellIds);+ }++ private static StepSolidRootExportPolicyEvaluation EvaluateManifold(BrepBody body, Body[] bodyNodes, BrepBodyShellRepresentation? shellRepresentation)+ {+ var reject = new List<string>();+ if (bodyNodes.Length != 1) reject.Add("Multiple topology bodies are unsupported for manifold export.");+ if (shellRepresentation is null)+ {+ if (bodyNodes.Length == 1 && bodyNodes[0].ShellIds.Count != 1)+ {+ reject.Add("Missing shell representation for multi-shell topology.");+ }+ }+ else+ {+ if (shellRepresentation.InnerShellIds.Count > 0) reject.Add("Inner shell ids exist.");+ if (!body.Topology.TryGetShell(shellRepresentation.OuterShellId, out _)) reject.Add("Outer shell id is missing in topology.");+ if (shellRepresentation.InnerShellIds.Count == 0 && bodyNodes.Length == 1 && bodyNodes[0].ShellIds.Count > 1) reject.Add("Ambiguous multi-shell role state.");+ }++ return new(nameof(ManifoldSolidBrepExportPolicy), reject.Count == 0, reject.Count == 0 ? 1000d : 0d, StepSolidRootExportKind.ManifoldSolidBrep, reject, []);+ }++ private static StepSolidRootExportPolicyEvaluation EvaluateBrepWithVoids(BrepBody body, Body[] bodyNodes, BrepBodyShellRepresentation? shellRepresentation)+ {+ var reject = new List<string>();+ if (bodyNodes.Length != 1) reject.Add("Multiple topology bodies are unsupported for brep-with-voids export.");+ if (shellRepresentation is null) reject.Add("Shell representation is missing.");+ else+ {+ if (shellRepresentation.InnerShellIds.Count == 0) reject.Add("No inner shells are present.");+ if (!body.Topology.TryGetShell(shellRepresentation.OuterShellId, out _)) reject.Add("Outer shell id is missing in topology.");+ foreach (var inner in shellRepresentation.InnerShellIds)+ {+ if (!body.Topology.TryGetShell(inner, out _)) reject.Add($"Inner shell id {inner.Value} is missing in topology.");+ }+ }++ return new(nameof(BrepWithVoidsExportPolicy), reject.Count == 0, reject.Count == 0 ? 1000d : 0d, StepSolidRootExportKind.BrepWithVoids, reject, []);+ }++ private static StepSolidRootExportPolicyEvaluation EvaluateUnsupported(BrepBody body, Body[] bodyNodes, BrepBodyShellRepresentation? shellRepresentation)+ {+ var blockers = new List<string>();+ if (bodyNodes.Length == 0) blockers.Add("No body present.");+ if (bodyNodes.Length > 1) blockers.Add("Multiple topology bodies are unsupported.");+ if (bodyNodes.Length == 1 && bodyNodes[0].ShellIds.Count > 1 && shellRepresentation is null) blockers.Add("Missing shell representation for multi-shell topology.");+ if (shellRepresentation is not null)+ {+ if (!body.Topology.TryGetShell(shellRepresentation.OuterShellId, out _)) blockers.Add("Invalid outer shell id.");+ foreach (var inner in shellRepresentation.InnerShellIds)+ {+ if (!body.Topology.TryGetShell(inner, out _)) blockers.Add($"Invalid inner shell id {inner.Value}.");+ }+ if (shellRepresentation.InnerShellIds.Count == 0 && bodyNodes.Length == 1 && bodyNodes[0].ShellIds.Count > 1) blockers.Add("Ambiguous multi-shell roles.");+ }++ var admissible = blockers.Count > 0;+ return new(nameof(UnsupportedShellTopologyPolicy), admissible, admissible ? 1d : 0d, StepSolidRootExportKind.Unsupported, admissible ? Array.Empty<string>() : new[] { "No unsupported blockers were detected." }, blockers);+ }++ private sealed class ManifoldSolidBrepExportPolicy;+ private sealed class BrepWithVoidsExportPolicy;+ private sealed class UnsupportedShellTopologyPolicy;+}diff --git a/docs/step-void-a2-solid-root-export-planner.md b/docs/step-void-a2-solid-root-export-planner.mdnew file mode 100644index 00000000..2eb613cb--- /dev/null+++ b/docs/step-void-a2-solid-root-export-planner.md@@ -0,0 +1,64 @@+# STEP-VOID-A2: JudgmentEngine STEP solid-root export planner++Date: 2026-05-14+Status: Outcome A — success++## Purpose++A2 formalizes STEP solid-root selection behind a bounded planner using `JudgmentEngine`, while preserving existing export behavior.++## Planner++`StepSolidRootExportPlanner` evaluates three bounded policies:++- `ManifoldSolidBrepExportPolicy`+- `BrepWithVoidsExportPolicy`+- `UnsupportedShellTopologyPolicy`++Decision model includes:++- selected `StepSolidRootExportKind` (`ManifoldSolidBrep`, `BrepWithVoids`, `Unsupported`),+- selected policy name,+- policy evaluations (admissible/rejected, score, reasons),+- decision diagnostics,+- shell summary (body count, shell count, outer shell, inner shells).++## JudgmentEngine usage++Planner evaluates all policy candidates through `JudgmentEngine<BrepBody>` with deterministic tie-breaking.++- manifold/void policies score high when admissible,+- unsupported fallback scores low and is admissible when blockers exist,+- diagnostics record both admitted and rejected policy states.++## Behavior preservation guarantee++Exporter emission semantics are unchanged:++- single-shell/no inner shell => `MANIFOLD_SOLID_BREP`+- explicit outer+inner shells => `BREP_WITH_VOIDS`+- multi-shell without explicit shell roles => deterministic unsupported failure++No geometry, topology, importer, or Firmament materialization behavior was changed in A2.++## Through-hole vs void distinction++Through-hole shapes remain `MANIFOLD_SOLID_BREP` when represented as one connected shell.++`BREP_WITH_VOIDS` remains reserved for explicit enclosed inner void shells (`ShellRepresentation.InnerShellIds`).++## Unsupported and ambiguous cases++Unsupported policy blockers include:++- no body,+- multiple topology bodies,+- missing shell representation for multi-shell topology,+- invalid shell ids,+- ambiguous multi-shell role states.++Diagnostics make blocker reasons explicit.++## A3 next++A3 should harden planner diagnostics propagation into exporter diagnostics and add focused negative corpus tests for ambiguous/invalid multi-shell shell-role maps.