Skip to content

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.cs
new file mode 100644
index 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.cs
index 14ded27c..c23e794a 100644
--- a/Aetheris.Kernel.Core/Step242/Step242Exporter.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242Exporter.cs
@@ -28,15 +28,19 @@ public static class Step242Exporter
return 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.