Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
C3: close analyze honesty contract gaps
Yuechen Li05ef91ef80a3
diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.csindex 5fdd816f..53aec3f7 100644--- a/Aetheris.CLI.Tests/CliBaselineTests.cs+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs@@ -32,7 +32,7 @@ public sealed class CliBaselineTests}[Fact]- public void Analyze_Command_Reports_Summary_Facts()+ public void Analyze_Command_Reports_Summary_Facts_And_Discoverability(){var stdout = new StringWriter();var stderr = new StringWriter();@@ -44,8 +44,7 @@ public sealed class CliBaselineTestsAssert.Equal(0, exitCode);using var doc = JsonDocument.Parse(stdout.ToString());- var root = doc.RootElement;- var summary = root.GetProperty("summary");+ var summary = doc.RootElement.GetProperty("summary");Assert.Equal(1, summary.GetProperty("bodyCount").GetInt32());Assert.Equal(1, summary.GetProperty("shellCount").GetInt32());Assert.Equal(6, summary.GetProperty("faceCount").GetInt32());@@ -53,25 +52,37 @@ public sealed class CliBaselineTestsAssert.Equal(8, summary.GetProperty("vertexCount").GetInt32());Assert.Equal("enclosed-manifold", summary.GetProperty("structuralAssessment").GetString());Assert.Equal(0, summary.GetProperty("surfaceFamilies").GetProperty("bspline").GetInt32());++ Assert.Equal("mm", summary.GetProperty("lengthUnit").GetString());+ Assert.Contains("assumed", summary.GetProperty("lengthUnitBasis").GetString(), StringComparison.OrdinalIgnoreCase);++ var faceIds = summary.GetProperty("faceIds");+ Assert.Equal(1, faceIds.GetProperty("min").GetInt32());+ Assert.Equal(6, faceIds.GetProperty("max").GetInt32());+ Assert.Equal(6, faceIds.GetProperty("count").GetInt32());+ Assert.True(faceIds.GetProperty("contiguous").GetBoolean());++ var edgeIds = summary.GetProperty("edgeIds");+ Assert.Equal(1, edgeIds.GetProperty("min").GetInt32());+ Assert.Equal(12, edgeIds.GetProperty("max").GetInt32());+ Assert.Equal(12, edgeIds.GetProperty("count").GetInt32());+ Assert.True(edgeIds.GetProperty("contiguous").GetBoolean());++ var vertexIds = summary.GetProperty("vertexIds");+ Assert.Equal(1, vertexIds.GetProperty("min").GetInt32());+ Assert.Equal(8, vertexIds.GetProperty("max").GetInt32());+ Assert.Equal(8, vertexIds.GetProperty("count").GetInt32());+ Assert.True(vertexIds.GetProperty("contiguous").GetBoolean());}[Fact]public void Analyze_Command_Provides_Numeric_Face_Detail_Anchors(){var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(5d, 12d).Value, "cli-cylinder-face-truth");- var stdout = new StringWriter();- var stderr = new StringWriter();-- var exitCode = Aetheris.CLI.CliRunner.Run(- ["analyze", stepPath, "--face", "2", "--json"],- stdout,- stderr);-- Assert.Equal(0, exitCode);- using var doc = JsonDocument.Parse(stdout.ToString());- var face = doc.RootElement.GetProperty("face");+ var face = AnalyzeFace(stepPath, 2);Assert.Equal(2, face.GetProperty("faceId").GetInt32());Assert.Equal("Plane", face.GetProperty("surfaceType").GetString());+ Assert.Equal("bound", face.GetProperty("surfaceStatus").GetString());AssertPoint(face.GetProperty("anchorPoint"), 0d, 0d, 6d);AssertVector(face.GetProperty("planarNormal"), 0d, 0d, 1d);Assert.Single(face.GetProperty("adjacentEdgeIds").EnumerateArray());@@ -81,34 +92,43 @@ public sealed class CliBaselineTestspublic void Analyze_Command_Reports_Truthful_Edge_Length_Fields(){var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(5d, 8d).Value, "cli-cylinder-edge-truth");- var stdout = new StringWriter();- var stderr = new StringWriter();- var exitCode = Aetheris.CLI.CliRunner.Run(- ["analyze", stepPath, "--edge", "1", "--json"],- stdout,- stderr);+ var lineEdge = AnalyzeEdge(stepPath, 1);+ Assert.Equal(1, lineEdge.GetProperty("edgeId").GetInt32());+ Assert.Equal("Line3", lineEdge.GetProperty("curveType").GetString());+ Assert.Equal(8d, lineEdge.GetProperty("arcLength").GetDouble(), 8);+ Assert.Equal(8d, lineEdge.GetProperty("parameterRange").GetDouble(), 8);+ Assert.Equal("computed", lineEdge.GetProperty("arcLengthStatus").GetString());- Assert.Equal(0, exitCode);- using var doc = JsonDocument.Parse(stdout.ToString());- var edge = doc.RootElement.GetProperty("edge");- Assert.Equal(1, edge.GetProperty("edgeId").GetInt32());- Assert.Equal("Line3", edge.GetProperty("curveType").GetString());- Assert.Equal(8d, edge.GetProperty("arcLength").GetDouble(), 8);- Assert.Equal(8d, edge.GetProperty("parameterRange").GetDouble(), 8);-- stdout.GetStringBuilder().Clear();- stderr.GetStringBuilder().Clear();- exitCode = Aetheris.CLI.CliRunner.Run(- ["analyze", stepPath, "--edge", "2", "--json"],- stdout,- stderr);- Assert.Equal(0, exitCode);- using var circleDoc = JsonDocument.Parse(stdout.ToString());- var circleEdge = circleDoc.RootElement.GetProperty("edge");+ var circleEdge = AnalyzeEdge(stepPath, 2);Assert.Equal("Circle3", circleEdge.GetProperty("curveType").GetString());Assert.Equal(2d * double.Pi, circleEdge.GetProperty("parameterRange").GetDouble(), 8);Assert.Equal(10d * double.Pi, circleEdge.GetProperty("arcLength").GetDouble(), 8);+ Assert.Equal("computed", circleEdge.GetProperty("arcLengthStatus").GetString());+ }++ [Fact]+ public void Analyze_Command_Explains_Null_ArcLength_For_Unsupported_Curve_Kinds()+ {+ var stepPath = Path.Combine(RepoRoot, "testdata/step242/nist/STC/nist_stc_06_asme1_ap242-e3.stp");+ var summary = AnalyzeSummary(stepPath);+ var maxEdgeId = summary.GetProperty("edgeIds").GetProperty("max").GetInt32();++ for (var edgeId = 1; edgeId <= maxEdgeId; edgeId++)+ {+ var edge = AnalyzeEdge(stepPath, edgeId);+ var curveType = edge.GetProperty("curveType").GetString();+ if (curveType is "Line3" or "Circle3")+ {+ continue;+ }++ Assert.True(edge.GetProperty("arcLength").ValueKind == JsonValueKind.Null);+ Assert.Equal("unsupported-for-curve-kind", edge.GetProperty("arcLengthStatus").GetString());+ return;+ }++ throw new Xunit.Sdk.XunitException("Expected at least one non-line/non-circle edge in NIST fixture.");}[Fact]@@ -131,7 +151,7 @@ public sealed class CliBaselineTests}[Fact]- public void Analyze_Command_Provides_Cylinder_Sphere_And_Torus_Anchors()+ public void Analyze_Command_Provides_Cylinder_Sphere_And_Torus_Anchors_With_Sphere_Axis_Omitted(){var cylinderStepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(4d, 12d).Value, "cli-cylinder-face-anchor");var sphereStepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateSphere(3d).Value, "cli-sphere-face-anchor");@@ -146,7 +166,7 @@ public sealed class CliBaselineTestsvar sphereFace = AnalyzeFace(sphereStepPath, 1);Assert.Equal("Sphere", sphereFace.GetProperty("surfaceType").GetString());AssertPoint(sphereFace.GetProperty("anchorPoint"), 0d, 0d, 0d);- AssertVector(sphereFace.GetProperty("axis"), 0d, 0d, 1d);+ Assert.False(sphereFace.TryGetProperty("axis", out _));Assert.Equal(3d, sphereFace.GetProperty("radius").GetDouble(), 8);var torusFace = AnalyzeFace(torusStepPath, 1);@@ -157,6 +177,18 @@ public sealed class CliBaselineTestsAssert.Equal(2d, torusFace.GetProperty("minorRadius").GetDouble(), 8);}+ [Fact]+ public void Analyze_Command_Uses_Binding_Missing_Surface_Status_Instead_Of_Unknown_Surface_Type()+ {+ var boxBody = BrepPrimitives.CreateBox(10d, 6d, 4d).Value;+ var brokenBody = RemoveFaceBinding(boxBody, new[] { 1 });++ var result = StepAnalyzer.AnalyzeImportedBody(brokenBody, "in-memory", faceId: 1);+ Assert.NotNull(result.Face);+ Assert.Null(result.Face!.SurfaceType);+ Assert.Equal("binding-missing", result.Face.SurfaceStatus);+ }+[Fact]public void Analyze_Command_Returns_Structured_Json_Failure(){@@ -190,6 +222,45 @@ public sealed class CliBaselineTestsAssert.Contains("coedge incidence", summary.GetProperty("structuralAssessmentBasis").GetString(), StringComparison.OrdinalIgnoreCase);}+ private static BrepBody RemoveFaceBinding(BrepBody source, IReadOnlyCollection<int> faceIdsToSkip)+ {+ var bindings = new BrepBindingModel();+ foreach (var edgeBinding in source.Bindings.EdgeBindings)+ {+ bindings.AddEdgeBinding(edgeBinding);+ }++ foreach (var faceBinding in source.Bindings.FaceBindings)+ {+ if (!faceIdsToSkip.Contains(faceBinding.FaceId.Value))+ {+ bindings.AddFaceBinding(faceBinding);+ }+ }++ var vertexPoints = source.Topology.Vertices+ .Where(vertex => source.TryGetVertexPoint(vertex.Id, out _))+ .ToDictionary(+ vertex => vertex.Id,+ vertex =>+ {+ source.TryGetVertexPoint(vertex.Id, out var point);+ return point;+ });++ return new BrepBody(source.Topology, source.Geometry, bindings, vertexPoints);+ }++ private static JsonElement AnalyzeSummary(string stepPath)+ {+ var stdout = new StringWriter();+ var stderr = new StringWriter();+ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", stepPath, "--json"], stdout, stderr);+ Assert.Equal(0, exitCode);+ using var doc = JsonDocument.Parse(stdout.ToString());+ return doc.RootElement.GetProperty("summary").Clone();+ }+private static JsonElement AnalyzeFace(string stepPath, int faceId){var stdout = new StringWriter();@@ -200,6 +271,16 @@ public sealed class CliBaselineTestsreturn doc.RootElement.GetProperty("face").Clone();}+ private static JsonElement AnalyzeEdge(string stepPath, int edgeId)+ {+ var stdout = new StringWriter();+ var stderr = new StringWriter();+ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", stepPath, "--edge", edgeId.ToString(), "--json"], stdout, stderr);+ Assert.Equal(0, exitCode);+ using var doc = JsonDocument.Parse(stdout.ToString());+ return doc.RootElement.GetProperty("edge").Clone();+ }+private static string ExportPrimitiveToTempStep(BrepBody body, string stem){var export = Step242Exporter.ExportBody(body);diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex b2b56bbb..8599a3f2 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -191,6 +191,10 @@ public static class CliRunnerstdout.WriteLine($"Vertices: {summary.VertexCount}");stdout.WriteLine($"BoundingBox: {FormatBox(summary.BoundingBox)}");stdout.WriteLine($"Structure: {summary.StructuralAssessment} ({summary.StructuralAssessmentBasis})");+ stdout.WriteLine($"LengthUnit: {summary.LengthUnit} ({summary.LengthUnitBasis})");+ stdout.WriteLine($"FaceIds: min={summary.FaceIds.Min}, max={summary.FaceIds.Max}, count={summary.FaceIds.Count}, contiguous={summary.FaceIds.Contiguous}");+ stdout.WriteLine($"EdgeIds: min={summary.EdgeIds.Min}, max={summary.EdgeIds.Max}, count={summary.EdgeIds.Count}, contiguous={summary.EdgeIds.Contiguous}");+ stdout.WriteLine($"VertexIds: min={summary.VertexIds.Min}, max={summary.VertexIds.Max}, count={summary.VertexIds.Count}, contiguous={summary.VertexIds.Contiguous}");stdout.WriteLine("Surface Families:");foreach (var family in summary.SurfaceFamilies){@@ -199,12 +203,12 @@ public static class CliRunnerif (analysis.Face is not null){- stdout.WriteLine($"Face {analysis.Face.FaceId}: type={analysis.Face.SurfaceType}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");+ stdout.WriteLine($"Face {analysis.Face.FaceId}: type={analysis.Face.SurfaceType ?? "n/a"}, status={analysis.Face.SurfaceStatus}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");}if (analysis.Edge is not null){- stdout.WriteLine($"Edge {analysis.Edge.EdgeId}: curve={analysis.Edge.CurveType}, start={analysis.Edge.StartVertexId}:{FormatPoint(analysis.Edge.StartVertex)}, end={analysis.Edge.EndVertexId}:{FormatPoint(analysis.Edge.EndVertex)}, faces=[{string.Join(",", analysis.Edge.AdjacentFaceIds)}], parameterRange={FormatDouble(analysis.Edge.ParameterRange)}, arcLength={FormatDouble(analysis.Edge.ArcLength)}");+ stdout.WriteLine($"Edge {analysis.Edge.EdgeId}: curve={analysis.Edge.CurveType}, start={analysis.Edge.StartVertexId}:{FormatPoint(analysis.Edge.StartVertex)}, end={analysis.Edge.EndVertexId}:{FormatPoint(analysis.Edge.EndVertex)}, faces=[{string.Join(",", analysis.Edge.AdjacentFaceIds)}], parameterRange={FormatDouble(analysis.Edge.ParameterRange)}, arcLength={FormatDouble(analysis.Edge.ArcLength)}, arcLengthStatus={analysis.Edge.ArcLengthStatus}");}if (analysis.Vertex is not null)diff --git a/Aetheris.CLI/StepAnalysisModels.cs b/Aetheris.CLI/StepAnalysisModels.csindex 947011ab..8a2160a1 100644--- a/Aetheris.CLI/StepAnalysisModels.cs+++ b/Aetheris.CLI/StepAnalysisModels.cs@@ -1,7 +1,14 @@+using System.Text.Json.Serialization;using Aetheris.Kernel.Core.Math;namespace Aetheris.CLI;+public sealed record IdRangeSummary(+ int Min,+ int Max,+ int Count,+ bool Contiguous);+public sealed record AnalyzeSummary(int BodyCount,int ShellCount,@@ -11,17 +18,23 @@ public sealed record AnalyzeSummary(BoundingBox3D? BoundingBox,string StructuralAssessment,IReadOnlyDictionary<string, int> SurfaceFamilies,- string StructuralAssessmentBasis);+ string StructuralAssessmentBasis,+ string LengthUnit,+ string LengthUnitBasis,+ IdRangeSummary FaceIds,+ IdRangeSummary EdgeIds,+ IdRangeSummary VertexIds);public sealed record FaceDetail(int FaceId,- string SurfaceType,+ string? SurfaceType,+ string SurfaceStatus,BoundingBox3D? BoundingBox,Point3D? RepresentativePoint,Point3D? AnchorPoint,Point3D? Apex,Vector3D? PlanarNormal,- Vector3D? Axis,+ [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] Vector3D? Axis,double? Radius,double? PlacementRadius,double? MajorRadius,@@ -38,7 +51,8 @@ public sealed record EdgeDetail(Point3D? EndVertex,IReadOnlyList<int> AdjacentFaceIds,double? ParameterRange,- double? ArcLength);+ double? ArcLength,+ string ArcLengthStatus);public sealed record VertexDetail(int VertexId,diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.csindex 7d12be9b..6fa31789 100644--- a/Aetheris.CLI/StepAnalyzer.cs+++ b/Aetheris.CLI/StepAnalyzer.cs@@ -17,7 +17,11 @@ public static class StepAnalyzerthrow new InvalidOperationException(string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));}- var body = import.Value;+ return AnalyzeImportedBody(import.Value, fullPath, faceId, edgeId, vertexId);+ }++ public static AnalyzeResult AnalyzeImportedBody(BrepBody body, string stepPath, int? faceId = null, int? edgeId = null, int? vertexId = null)+ {var notes = new List<string>();var summary = BuildSummary(body, notes);@@ -25,7 +29,7 @@ public static class StepAnalyzervar edge = edgeId.HasValue ? BuildEdgeDetail(body, new EdgeId(edgeId.Value), notes) : null;var vertex = vertexId.HasValue ? BuildVertexDetail(body, new VertexId(vertexId.Value), notes) : null;- return new AnalyzeResult(fullPath, summary, face, edge, vertex, notes);+ return new AnalyzeResult(stepPath, summary, face, edge, vertex, notes);}private static AnalyzeSummary BuildSummary(BrepBody body, ICollection<string> notes)@@ -83,7 +87,12 @@ public static class StepAnalyzerbbox,structural,surfaceFamilies,- basis);+ basis,+ "mm",+ "assumed; STEP import length units not yet preserved",+ BuildIdRange(topology.Faces.Select(f => f.Id.Value)),+ BuildIdRange(topology.Edges.Select(e => e.Id.Value)),+ BuildIdRange(topology.Vertices.Select(v => v.Id.Value)));}private static FaceDetail BuildFaceDetail(BrepBody body, FaceId faceId, ICollection<string> notes)@@ -116,7 +125,7 @@ public static class StepAnalyzerif (!body.TryGetFaceSurface(faceId, out var surface) || surface is null){- return new FaceDetail(faceId.Value, "unknown", bbox, rep, null, null, null, null, null, null, null, null, null, edgeIds);+ return new FaceDetail(faceId.Value, null, "binding-missing", bbox, rep, null, null, null, null, null, null, null, null, null, edgeIds);}Point3D? anchor = null;@@ -154,8 +163,8 @@ public static class StepAnalyzerif (surface.Sphere is { } sphere){anchor = sphere.Center;- axis = sphere.Axis.ToVector();radius = sphere.Radius;+ notes.Add($"Face {faceId.Value} is spherical; axis omitted because spheres have no intrinsic axis.");}if (surface.Torus is { } torus)@@ -166,7 +175,7 @@ public static class StepAnalyzerminorRadius = torus.MinorRadius;}- return new FaceDetail(faceId.Value, surface.Kind.ToString(), bbox, rep, anchor, apex, normal, axis, radius, placementRadius, majorRadius, minorRadius, semiAngle, edgeIds);+ return new FaceDetail(faceId.Value, surface.Kind.ToString(), "bound", bbox, rep, anchor, apex, normal, axis, radius, placementRadius, majorRadius, minorRadius, semiAngle, edgeIds);}private static EdgeDetail BuildEdgeDetail(BrepBody body, EdgeId edgeId, ICollection<string> notes)@@ -179,6 +188,8 @@ public static class StepAnalyzervar curveType = "unknown";double? parameterRange = null;double? arcLength = null;+ var arcLengthStatus = "unavailable";+if (body.Bindings.TryGetEdgeBinding(edgeId, out var binding)){curveType = binding.TrimInterval is null ? "untrimmed" : "trimmed";@@ -196,17 +207,31 @@ public static class StepAnalyzer{case CurveGeometryKind.Line3:arcLength = double.Abs(trim.End - trim.Start);+ arcLengthStatus = "computed";break;case CurveGeometryKind.Circle3 when curve.Circle3 is { } circle:arcLength = circle.Radius * double.Abs(trim.End - trim.Start);+ arcLengthStatus = "computed";+ break;+ default:+ arcLengthStatus = "unsupported-for-curve-kind";break;}}+ else+ {+ arcLengthStatus = "unavailable-no-trim-interval";+ }+ }+ else+ {+ arcLengthStatus = "unavailable-curve-missing";}}else{notes.Add($"Edge {edgeId.Value} has no curve binding, so curve-type and length are limited.");+ arcLengthStatus = "unavailable-binding-missing";}Point3D? startPoint = body.TryGetVertexPoint(edge.StartVertexId, out var start) ? start : null;@@ -216,7 +241,7 @@ public static class StepAnalyzer? faces.Select(id => id.Value).OrderBy(v => v).ToArray(): [];- return new EdgeDetail(edgeId.Value, curveType, edge.StartVertexId.Value, startPoint, edge.EndVertexId.Value, endPoint, adjacentFaces, parameterRange, arcLength);+ return new EdgeDetail(edgeId.Value, curveType, edge.StartVertexId.Value, startPoint, edge.EndVertexId.Value, endPoint, adjacentFaces, parameterRange, arcLength, arcLengthStatus);}private static VertexDetail BuildVertexDetail(BrepBody body, VertexId vertexId, ICollection<string> notes)@@ -241,6 +266,27 @@ public static class StepAnalyzerreturn new VertexDetail(vertexId.Value, position, incidentEdges);}+ private static IdRangeSummary BuildIdRange(IEnumerable<int> ids)+ {+ var sorted = ids.OrderBy(id => id).ToArray();+ if (sorted.Length == 0)+ {+ return new IdRangeSummary(0, 0, 0, true);+ }++ var contiguous = true;+ for (var index = 1; index < sorted.Length; index++)+ {+ if (sorted[index] != sorted[index - 1] + 1)+ {+ contiguous = false;+ break;+ }+ }++ return new IdRangeSummary(sorted[0], sorted[^1], sorted.Length, contiguous);+ }+private static BoundingBox3D? TryComputeBodyBoundingBox(BrepBody body){var points = body.Topology.Verticesdiff --git a/docs/cli-baseline.md b/docs/cli-baseline.mdindex e5ad239e..bad58ff4 100644--- a/docs/cli-baseline.md+++ b/docs/cli-baseline.md@@ -1,4 +1,4 @@-# Aetheris.CLI baseline (C1)+# Aetheris.CLI baseline (C3)## Supported commands@@ -7,11 +7,11 @@ aetheris build <file.firmament> [--out <path>] [--json]aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json]```-### Contract notes+## Contract notes-- `build` runs the existing `FirmamentBuildAndExport.Run` pipeline; it does not implement a parallel compiler/export path.+- `build` runs `FirmamentBuildAndExport.Run`; no parallel compile/export path is introduced.- `build` default output path remains deterministic: `<repo>/testdata/firmament/exports/<source-filename>.step`.-- `analyze` imports STEP using `Step242Importer.ImportBody` and reports facts from imported topology/geometry bindings.+- `analyze` imports STEP with `Step242Importer.ImportBody` and reports imported topology/geometry facts.- At most one detail selector is allowed on `analyze`: `--face`, `--edge`, or `--vertex`.- `analyze --json` is the canonical machine-readable mode.@@ -28,15 +28,21 @@ aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json"vertexCount": 8,"boundingBox": { "min": { "x": 0, "y": 0, "z": 0 }, "max": { "x": 10, "y": 5, "z": 2 } },"structuralAssessment": "enclosed-manifold",+ "structuralAssessmentBasis": "derived from imported topology edge-to-face coedge incidence counts",+ "lengthUnit": "mm",+ "lengthUnitBasis": "assumed; STEP import length units not yet preserved","surfaceFamilies": {"plane": 6,"cylinder": 0,"cone": 0,"sphere": 0,"torus": 0,+ "bspline": 0,"other": 0},- "structuralAssessmentBasis": "derived from imported topology edge-to-face adjacency counts"+ "faceIds": { "min": 1, "max": 6, "count": 6, "contiguous": true },+ "edgeIds": { "min": 1, "max": 12, "count": 12, "contiguous": true },+ "vertexIds": { "min": 1, "max": 8, "count": 8, "contiguous": true }},"face": null,"edge": null,@@ -45,8 +51,67 @@ aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json}```-## Truthfulness and deferrals+### Structural assessment enum semantics-- Structural classification is based on edge-to-face adjacency counts from imported topology.-- If bounding boxes or points cannot be determined from available vertex coordinates, output is `null` (JSON) / `unknown` (text), and a note is emitted.-- No renderer/viewer, no schema redesign, and no generalized command framework are included in C1.+- `enclosed-manifold`: every imported edge is used by exactly two face coedges.+- `leaky-or-open`: at least one imported edge is used by only one face coedge.+- `non-manifold`: no leaky edges, but one or more edges have coedge incidence different from 2.++### Unit semantics (honesty contract)++- `lengthUnit` is currently emitted as `mm`.+- `lengthUnitBasis` communicates trust level of that value.+- Current C3 truth: `lengthUnit` is an Aetheris analyzer assumption/normalization output, not preserved STEP source-unit provenance.++## Face detail contract (`--face <id>`)++Common fields:++- `faceId`, `surfaceType`, `surfaceStatus`, `boundingBox`, `representativePoint`, `adjacentEdgeIds`++Surface binding semantics:++- Bound face: `surfaceStatus: "bound"`, `surfaceType` is a concrete kind (`Plane`, `Cylinder`, `Cone`, `Sphere`, `Torus`, `BSplineSurfaceWithKnots`, ...).+- Missing surface binding: `surfaceStatus: "binding-missing"`, `surfaceType: null`.++Kind-specific fields:++- Plane: `anchorPoint`, `planarNormal`+- Cylinder: `anchorPoint`, `axis`, `radius`+- Cone: `anchorPoint`, `apex`, `axis`, `semiAngleRadians`, `placementRadius`+- Sphere: `anchorPoint`, `radius` (no `axis` field is emitted; spheres have no intrinsic axis)+- Torus: `anchorPoint`, `axis`, `majorRadius`, `minorRadius`++## Edge detail contract (`--edge <id>`)++Fields:++- `edgeId`, `curveType`, `startVertexId`, `startVertex`, `endVertexId`, `endVertex`, `adjacentFaceIds`, `parameterRange`, `arcLength`, `arcLengthStatus`++`arcLengthStatus` enum semantics:++- `computed`: current curve-kind support computed a numeric `arcLength`.+- `unsupported-for-curve-kind`: `arcLength` is null because current analyzer does not implement that curve kind.+- `unavailable-no-trim-interval`: edge is present but has no trim interval.+- `unavailable-curve-missing`: curve binding exists but curve geometry is unresolved.+- `unavailable-binding-missing`: edge has no curve binding.+- `unavailable`: generic fallback when no narrower status applies.++## Analyze failure JSON shape++When `--json` is requested and analyze fails:++```json+{+ "success": false,+ "stepPath": "<resolved-path>",+ "error": "<message>"+}+```++## Truthfulness and scope boundaries++- Structural classification is derived from imported edge-to-face coedge incidence counts.+- Missing coordinate-dependent fields are emitted as null and accompanied by notes.+- C3 does not add arbitrary source-unit preservation/export redesign.+- C3 does not add renderer/viewer scope, language redesign, or broad CLI framework redesign.