Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Fix A1 regressions and restore STEP/Core/CLI gates
Yuechen Licb93470d5952
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex fd8facf8..9b4b818e 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -372,7 +372,7 @@ public static class CliRunnerreturn;}- var rigidRootCount = CountManifoldSolidRoots(multiRootDiagnostic.Message);+ var rigidRootCount = CountExactBrepRigidRoots(multiRootDiagnostic.Message);stdout.WriteLine(JsonSerializer.Serialize(new{success = false,@@ -392,7 +392,7 @@ public static class CliRunner}, JsonOptions));}- private static int? CountManifoldSolidRoots(string message)+ private static int? CountExactBrepRigidRoots(string message){const string token = "detected ";var detectedIndex = message.IndexOf(token, StringComparison.OrdinalIgnoreCase);@@ -402,13 +402,14 @@ public static class CliRunner}var start = detectedIndex + token.Length;- var end = message.IndexOf(" MANIFOLD_SOLID_BREP", start, StringComparison.OrdinalIgnoreCase);- if (end <= start)+ var countSlice = message[start..];+ var digits = new string(countSlice.TakeWhile(char.IsDigit).ToArray());+ if (digits.Length == 0){return null;}- return int.TryParse(message[start..end], out var value) ? value : null;+ return int.TryParse(digits, out var value) ? value : null;}private static int RunAnalyze(string[] args, TextWriter stdout, TextWriter stderr)@@ -772,7 +773,7 @@ public static class CliRunner{errorKind = "assembly-like-step";classification = "assembly-like";- rigidRootCount = CountManifoldSolidRoots(multiRootDiagnostic.Message);+ rigidRootCount = CountExactBrepRigidRoots(multiRootDiagnostic.Message);}else{@@ -1347,13 +1348,13 @@ public static class CliRunnervar multiRootDiagnostic = importFailure.Diagnostics.FirstOrDefault(d => string.Equals(d.Source, "Importer.AssemblyLike.StepMultiRoot", StringComparison.Ordinal));if (multiRootDiagnostic is not null){- var rigidRootCount = CountManifoldSolidRoots(multiRootDiagnostic.Message);+ var rigidRootCount = CountExactBrepRigidRoots(multiRootDiagnostic.Message);stderr.WriteLine($"Input file: {fullPath}");stderr.WriteLine("Success: no");- stderr.WriteLine("Classification: assembly-like STEP (multi-root manifold solids).");+ stderr.WriteLine("Classification: assembly-like STEP (multi-root exact BRep solids).");if (rigidRootCount.HasValue){- stderr.WriteLine($"Detected manifold-solid roots: {rigidRootCount.Value}");+ stderr.WriteLine($"Detected exact BRep rigid roots: {rigidRootCount.Value}");}stderr.WriteLine("Guidance: Use the assembly extraction/import workflow for this STEP input.");diff --git a/Aetheris.Kernel.Core.Tests/Step242/Step242BrepWithVoidsImportTests.cs b/Aetheris.Kernel.Core.Tests/Step242/Step242BrepWithVoidsImportTests.csnew file mode 100644index 00000000..915be215--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Step242/Step242BrepWithVoidsImportTests.cs@@ -0,0 +1,32 @@+using Aetheris.Kernel.Core.Step242;++namespace Aetheris.Kernel.Core.Tests.Step242;++public sealed class Step242BrepWithVoidsImportTests+{+ [Fact]+ public void Import_BrepWithVoids_MissingVoidShell_FailsClearly()+ {+ const string missingVoid = "ISO-10303-21;\nHEADER;\nENDSEC;\nDATA;\n#1=BREP_WITH_VOIDS('v',#2,());\n#2=CLOSED_SHELL($,());\nENDSEC;\nEND-ISO-10303-21;";+ var import = Step242Importer.ImportBody(missingVoid);+ Assert.False(import.IsSuccess);+ var diagnostic = Assert.Single(import.Diagnostics);+ Assert.Equal("Importer.TopologyRoot.BrepWithVoids", diagnostic.Source);+ Assert.Contains("at least one void shell", diagnostic.Message, StringComparison.Ordinal);+ }++ [Fact]+ public void Import_BrepWithVoids_MinimalOuterAndVoidShells_PreservesShellRepresentation()+ {+ var fixturePath = Path.Combine(Step242CorpusManifestRunner.RepoRoot(), "testdata", "firmament", "exports", "boolean_box_sphere_cavity_basic.step");+ var stepText = File.ReadAllText(fixturePath);+ Assert.Contains("BREP_WITH_VOIDS", stepText, StringComparison.Ordinal);++ var import = Step242Importer.ImportBody(stepText);+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));+ Assert.NotNull(import.Value.ShellRepresentation);+ Assert.Single(import.Value.Topology.Bodies);+ Assert.Equal(2, import.Value.Topology.Shells.Count());+ Assert.Single(import.Value.ShellRepresentation!.InnerShellIds);+ }+}diff --git a/Aetheris.Kernel.Core.Tests/Step242/Step242ImporterTests.cs b/Aetheris.Kernel.Core.Tests/Step242/Step242ImporterTests.csindex 4da17d5d..dca1c136 100644--- a/Aetheris.Kernel.Core.Tests/Step242/Step242ImporterTests.cs+++ b/Aetheris.Kernel.Core.Tests/Step242/Step242ImporterTests.cs@@ -87,7 +87,7 @@ public sealed class Step242ImporterTestsvar diagnostic = Assert.Single(import.Diagnostics);Assert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);Assert.Equal("Importer.TopologyRoot", diagnostic.Source);- Assert.StartsWith("Missing MANIFOLD_SOLID_BREP", diagnostic.Message, StringComparison.Ordinal);+ Assert.StartsWith("Missing MANIFOLD_SOLID_BREP or BREP_WITH_VOIDS", diagnostic.Message, StringComparison.Ordinal);}[Fact]@@ -102,7 +102,7 @@ public sealed class Step242ImporterTestsAssert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);Assert.Equal("Importer.AssemblyLike.StepMultiRoot", diagnostic.Source);Assert.Contains("assembly-like", diagnostic.Message, StringComparison.OrdinalIgnoreCase);- Assert.Contains("detected 2 MANIFOLD_SOLID_BREP rigid roots", diagnostic.Message, StringComparison.Ordinal);+ Assert.Contains("detected 2 exact BRep rigid roots", diagnostic.Message, StringComparison.Ordinal);}[Fact]@@ -129,7 +129,7 @@ public sealed class Step242ImporterTestsvar diagnostic = Assert.Single(import.Diagnostics);Assert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);Assert.Equal("Importer.TopologyRoot", diagnostic.Source);- Assert.StartsWith("Missing MANIFOLD_SOLID_BREP", diagnostic.Message, StringComparison.Ordinal);+ Assert.StartsWith("Missing MANIFOLD_SOLID_BREP or BREP_WITH_VOIDS", diagnostic.Message, StringComparison.Ordinal);}[Fact]diff --git a/Aetheris.Kernel.Core.Tests/Step242/Step242InnerShellExportTests.cs b/Aetheris.Kernel.Core.Tests/Step242/Step242InnerShellExportTests.csindex 5ca9504b..e203cf95 100644--- a/Aetheris.Kernel.Core.Tests/Step242/Step242InnerShellExportTests.cs+++ b/Aetheris.Kernel.Core.Tests/Step242/Step242InnerShellExportTests.cs@@ -44,7 +44,7 @@ public sealed class Step242InnerShellExportTests}[Fact]- public void ExportBody_InnerShellRepresentation_ImportRoundTrip_IsExplicitlyUnsupportedInCurrentSubset()+ public void ExportBody_InnerShellRepresentation_ImportRoundTrip_PreservesShellRepresentation(){var body = CreateSyntheticBodyWithInnerShell();var export = Step242Exporter.ExportBody(body);@@ -53,10 +53,9 @@ public sealed class Step242InnerShellExportTestsvar import = Step242Importer.ImportBody(export.Value);- Assert.False(import.IsSuccess);- var diagnostic = Assert.Single(import.Diagnostics);- Assert.Equal("Importer.TopologyRoot", diagnostic.Source);- Assert.StartsWith("Missing MANIFOLD_SOLID_BREP", diagnostic.Message, StringComparison.Ordinal);+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));+ Assert.NotNull(import.Value.ShellRepresentation);+ Assert.Single(import.Value.ShellRepresentation!.InnerShellIds);}[Fact]diff --git a/Aetheris.Kernel.Core/Step242/Step242Importer.cs b/Aetheris.Kernel.Core/Step242/Step242Importer.csindex f7ec6c22..ec9b1c30 100644--- a/Aetheris.Kernel.Core/Step242/Step242Importer.cs+++ b/Aetheris.Kernel.Core/Step242/Step242Importer.cs@@ -85,38 +85,62 @@ public static class Step242Importerif (rigidRootClassification.Kind == Step242RigidRootClassificationKind.MissingRigidRoot){return Step242ImportSharedUtilities.NotImplementedFailure<BrepBody>(- "Missing MANIFOLD_SOLID_BREP root entity.",+ "Missing MANIFOLD_SOLID_BREP or BREP_WITH_VOIDS root entity.","Importer.TopologyRoot");}if (rigidRootClassification.Kind == Step242RigidRootClassificationKind.AssemblyLikeMultipleRigidRoots){return Step242ImportSharedUtilities.NotImplementedFailure<BrepBody>(- $"STEP input is assembly-like: detected {rigidRootClassification.RigidRoots.Count} MANIFOLD_SOLID_BREP rigid roots. Single-part exact BRep import accepts exactly one rigid root; route this input through assembly extraction/import.",+ $"STEP input is assembly-like: detected {rigidRootClassification.RigidRoots.Count} exact BRep rigid roots (MANIFOLD_SOLID_BREP/BREP_WITH_VOIDS). Single-part exact BRep import accepts exactly one rigid root; route this input through assembly extraction/import.","Importer.AssemblyLike.StepMultiRoot");}var brepEntity = rigidRootClassification.SingleRigidRoot;+ var shellRoleDiagnostics = new List<KernelDiagnostic>();+ var shellFaceEntityIds = new List<IReadOnlyList<int>>();- var shellRefResult = Step242SubsetDecoder.ReadReference(brepEntity, 1, "MANIFOLD_SOLID_BREP shell");- if (!shellRefResult.IsSuccess)+ var isBrepWithVoids = string.Equals(brepEntity.Name, "BREP_WITH_VOIDS", StringComparison.OrdinalIgnoreCase);+ var outerShellRefResult = Step242SubsetDecoder.ReadReference(brepEntity, 1, isBrepWithVoids ? "BREP_WITH_VOIDS outer shell" : "MANIFOLD_SOLID_BREP shell");+ if (!outerShellRefResult.IsSuccess){- return KernelResult<BrepBody>.Failure(shellRefResult.Diagnostics);+ return KernelResult<BrepBody>.Failure(outerShellRefResult.Diagnostics);}- var shellEntityResult = document.TryGetEntity(shellRefResult.Value.TargetId, "CLOSED_SHELL");- if (!shellEntityResult.IsSuccess)+ var outerShellFacesResult = ReadShellFaceIds(document, outerShellRefResult.Value.TargetId, "outer", shellRoleDiagnostics);+ if (!outerShellFacesResult.IsSuccess){- return KernelResult<BrepBody>.Failure(shellEntityResult.Diagnostics);+ return KernelResult<BrepBody>.Failure(outerShellFacesResult.Diagnostics);}- var faceRefsResult = Step242SubsetDecoder.ReadReferenceList(shellEntityResult.Value, 1, "CLOSED_SHELL faces");- if (!faceRefsResult.IsSuccess)+ shellFaceEntityIds.Add(outerShellFacesResult.Value);++ if (isBrepWithVoids){- return KernelResult<BrepBody>.Failure(faceRefsResult.Diagnostics);+ var voidShellRefsResult = Step242SubsetDecoder.ReadReferenceList(brepEntity, 2, "BREP_WITH_VOIDS void shells");+ if (!voidShellRefsResult.IsSuccess)+ {+ return KernelResult<BrepBody>.Failure(voidShellRefsResult.Diagnostics);+ }++ if (voidShellRefsResult.Value.Count == 0)+ {+ return Step242ImportSharedUtilities.ValidationFailure<BrepBody>("BREP_WITH_VOIDS must reference at least one void shell.", "Importer.TopologyRoot.BrepWithVoids");+ }++ foreach (var voidShellRef in voidShellRefsResult.Value)+ {+ var voidShellFacesResult = ReadShellFaceIds(document, voidShellRef.TargetId, "void", shellRoleDiagnostics);+ if (!voidShellFacesResult.IsSuccess)+ {+ return KernelResult<BrepBody>.Failure(voidShellFacesResult.Diagnostics);+ }++ shellFaceEntityIds.Add(voidShellFacesResult.Value);+ }}- var faceEntityIds = faceRefsResult.Value.Select(r => r.TargetId).ToList();+ var faceEntityIds = shellFaceEntityIds.SelectMany(ids => ids).ToList();AppendSupportedOrphanPlanarFaces(document, faceEntityIds);var builder = new TopologyBuilder();@@ -130,6 +154,7 @@ public static class Step242Importervar nextCurveGeometryId = 1;var nextSurfaceGeometryId = 1;var faceIds = new List<FaceId>();+ var faceEntityToFaceId = new Dictionary<int, FaceId>();foreach (var faceEntityId in faceEntityIds){@@ -425,6 +450,7 @@ public static class Step242Importervar faceId = builder.AddFace(faceLoopIds);faceIds.Add(faceId);+ faceEntityToFaceId[faceEntityId] = faceId;var (surfaceGeometryId, surfaceGeometry) = bindSurfaceResult.Value;nextSurfaceGeometryId++;@@ -437,17 +463,95 @@ public static class Step242Importerbuilder.AddCoedge(coedge);}- var shellId = builder.AddShell(faceIds);- builder.AddBody([shellId]);+ var shellIds = new List<ShellId>(shellFaceEntityIds.Count);+ var assignedFaceIds = new HashSet<FaceId>();+ var referencedFaceIds = new HashSet<FaceId>(+ shellFaceEntityIds+ .SelectMany(faceSet => faceSet)+ .Where(faceEntityToFaceId.ContainsKey)+ .Select(faceEntityId => faceEntityToFaceId[faceEntityId]));+ foreach (var shellFaceSet in shellFaceEntityIds)+ {+ var shellFaceIds = new List<FaceId>(shellFaceSet.Count);+ foreach (var shellFaceEntityId in shellFaceSet)+ {+ if (!faceEntityToFaceId.TryGetValue(shellFaceEntityId, out var shellFaceId))+ {+ return Failure($"Shell references unknown face entity #{shellFaceEntityId}.", "Importer.TopologyRoot.BrepWithVoids");+ }++ shellFaceIds.Add(shellFaceId);+ assignedFaceIds.Add(shellFaceId);+ }++ if (shellIds.Count == 0)+ {+ foreach (var faceId in faceIds)+ {+ if (assignedFaceIds.Contains(faceId) || referencedFaceIds.Contains(faceId))+ {+ continue;+ }- var body = new BrepBody(builder.Model, geometry, bindings, vertexMap.Values.ToDictionary(entry => entry.VertexId, entry => entry.Point));+ shellFaceIds.Add(faceId);+ assignedFaceIds.Add(faceId);+ }+ }++ shellIds.Add(builder.AddShell(shellFaceIds));+ }++ builder.AddBody(shellIds);++ BrepBodyShellRepresentation? shellRepresentation = null;+ if (shellIds.Count > 0)+ {+ shellRepresentation = new BrepBodyShellRepresentation(shellIds[0], shellIds.Skip(1).ToArray());+ }++ var body = new BrepBody(builder.Model, geometry, bindings, vertexMap.Values.ToDictionary(entry => entry.VertexId, entry => entry.Point), shellRepresentation: shellRepresentation);var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);if (!validation.IsSuccess){return KernelResult<BrepBody>.Failure(validation.Diagnostics);}- return KernelResult<BrepBody>.Success(body, validation.Diagnostics);+ return KernelResult<BrepBody>.Success(body, validation.Diagnostics.Concat(shellRoleDiagnostics).ToArray());+ }++ private static KernelResult<IReadOnlyList<int>> ReadShellFaceIds(Step242ParsedDocument document, int shellEntityId, string role, ICollection<KernelDiagnostic> diagnostics)+ {+ var shellEntityResult = document.TryGetEntity(shellEntityId);+ if (!shellEntityResult.IsSuccess)+ {+ return KernelResult<IReadOnlyList<int>>.Failure(shellEntityResult.Diagnostics);+ }++ var shellEntity = shellEntityResult.Value;+ if (string.Equals(shellEntity.Name, "ORIENTED_CLOSED_SHELL", StringComparison.OrdinalIgnoreCase))+ {+ var orientedRefResult = Step242SubsetDecoder.ReadReference(shellEntity, 1, "ORIENTED_CLOSED_SHELL shell");+ if (!orientedRefResult.IsSuccess)+ {+ return KernelResult<IReadOnlyList<int>>.Failure(orientedRefResult.Diagnostics);+ }++ diagnostics.Add(new KernelDiagnostic(KernelDiagnosticCode.NotImplemented, KernelDiagnosticSeverity.Info, $"Resolved oriented {role} shell reference #{shellEntity.Id} -> #{orientedRefResult.Value.TargetId}.", "Importer.TopologyRoot.BrepWithVoids"));+ return ReadShellFaceIds(document, orientedRefResult.Value.TargetId, role, diagnostics);+ }++ if (!string.Equals(shellEntity.Name, "CLOSED_SHELL", StringComparison.OrdinalIgnoreCase))+ {+ return Step242ImportSharedUtilities.NotImplementedFailure<IReadOnlyList<int>>($"Unsupported {role} shell entity '{shellEntity.Name}' (expected CLOSED_SHELL or ORIENTED_CLOSED_SHELL).", "Importer.TopologyRoot.BrepWithVoids");+ }++ var faceRefsResult = Step242SubsetDecoder.ReadReferenceList(shellEntity, 1, $"CLOSED_SHELL {role} faces");+ if (!faceRefsResult.IsSuccess)+ {+ return KernelResult<IReadOnlyList<int>>.Failure(faceRefsResult.Diagnostics);+ }++ return KernelResult<IReadOnlyList<int>>.Success(faceRefsResult.Value.Select(r => r.TargetId).ToArray());}private static void AppendSupportedOrphanPlanarFaces(Step242ParsedDocument document, IList<int> faceEntityIds)diff --git a/Aetheris.Kernel.Core/Step242/Step242RigidRootClassifier.cs b/Aetheris.Kernel.Core/Step242/Step242RigidRootClassifier.csindex b10d6168..7191d825 100644--- a/Aetheris.Kernel.Core/Step242/Step242RigidRootClassifier.cs+++ b/Aetheris.Kernel.Core/Step242/Step242RigidRootClassifier.cs@@ -18,17 +18,18 @@ internal static class Step242RigidRootClassifier{internal static Step242RigidRootClassification Classify(Step242ParsedDocument document){- var manifoldSolidRoots = document.Entities- .Where(e => string.Equals(e.Name, "MANIFOLD_SOLID_BREP", StringComparison.OrdinalIgnoreCase))+ var supportedRigidRoots = document.Entities+ .Where(e => string.Equals(e.Name, "MANIFOLD_SOLID_BREP", StringComparison.OrdinalIgnoreCase)+ || string.Equals(e.Name, "BREP_WITH_VOIDS", StringComparison.OrdinalIgnoreCase)).ToList();- var kind = manifoldSolidRoots.Count switch+ var kind = supportedRigidRoots.Count switch{0 => Step242RigidRootClassificationKind.MissingRigidRoot,1 => Step242RigidRootClassificationKind.PartLikeSingleRigidRoot,_ => Step242RigidRootClassificationKind.AssemblyLikeMultipleRigidRoots};- return new Step242RigidRootClassification(kind, manifoldSolidRoots);+ return new Step242RigidRootClassification(kind, supportedRigidRoots);}}diff --git a/docs/step-void-a1-brep-with-voids-import.md b/docs/step-void-a1-brep-with-voids-import.mdnew file mode 100644index 00000000..bd156961--- /dev/null+++ b/docs/step-void-a1-brep-with-voids-import.md@@ -0,0 +1,77 @@+# STEP-VOID-A1: BREP_WITH_VOIDS import support and shell-role preservation++Date: 2026-05-14+Status: Outcome A — success++## Scope++A1 extends the exact STEP BRep importer to accept `BREP_WITH_VOIDS` rigid roots in addition to `MANIFOLD_SOLID_BREP`, then preserves shell roles by assigning imported shells into `BrepBodyShellRepresentation(outer, inner[])`.++No exporter behavior was changed.++## Root classification change++`Step242RigidRootClassifier` now classifies exact rigid roots from either:+- `MANIFOLD_SOLID_BREP`+- `BREP_WITH_VOIDS`++Assembly-like classification still triggers when multiple exact rigid roots are found.++## Import behavior for BREP_WITH_VOIDS++Importer now parses:+- outer shell reference at argument 1,+- void shell list at argument 2.++Rules:+- empty void list is a deterministic validation failure,+- each shell reference must resolve to `CLOSED_SHELL` directly or through `ORIENTED_CLOSED_SHELL`.++## Oriented shell handling++`ORIENTED_CLOSED_SHELL` is minimally supported for root shell references:+- importer resolves its referenced shell,+- importer records a deterministic info diagnostic for the resolution,+- no orientation normalization beyond reference resolution is introduced in A1.++## Shell role preservation++Importer builds one topology body with multiple shells and sets:+- `OuterShellId` = first (root outer) shell,+- `InnerShellIds` = remaining (void) shells.++This preserves topology role semantics without converting voids into booleans.++## Diagnostics added/clarified++- missing rigid root message now covers both root kinds,+- assembly-like message now references exact rigid roots generically,+- `BREP_WITH_VOIDS` empty void-list failure source: `Importer.TopologyRoot.BrepWithVoids`,+- unsupported shell-reference kinds return precise shell-type diagnostics.++## Through-hole policy unchanged++Through-hole exports remain governed by existing exporter semantics and still emit `MANIFOLD_SOLID_BREP` when represented as a single shell.++## A1.1 regression cleanup (gate restore)++Observed failures after initial A1 landing:+- `Step242ExporterTests.ExportBody_Ctc02RoundTrip_PreservesPlanarFaceWithCircularBoundaryNearExpectedCenter` failed.+- NIST canonical hash snapshots drifted.+- CLI assembly-like JSON test emitted `rigidRootCount: null`.++Root causes and fixes:+- **Shell assignment bug in importer shell-role materialization**: orphan planar faces were appended to the outer shell before later void-shell assignment, causing face sharing/omission side-effects in round-trip cases. Fix: map imported `faceEntityId -> FaceId`, assign shell face sets explicitly by entity id, and append only truly orphan (unreferenced) faces to the outer shell.+- **CLI root-count parser stale expectation**: parser only recognized legacy `" MANIFOLD_SOLID_BREP"` wording. Fix: parse numeric rigid-root count from the generalized assembly-like message and update human-readable labeling to “exact BRep rigid roots”.++Result:+- Named CTC02 regression passes.+- Focused `BrepWithVoids|Step242|Void|Shell` test filter passes.+- Canonical `./scripts/test-all.sh` gate passes (warnings unchanged; no suppression).++## Next step (A2)++Implement export root selection planning via JudgmentEngine policies while preserving current emission behavior:+- manifold policy,+- brep-with-voids policy,+- unsupported topology policy with explicit rejection reasons.