Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Wire V2 box AP242 pipeline

Yuechen Lia59f0466f6d5
diff --git a/Aetheris.CLI.Tests/FirmamentV2BoxStepPipelineTests.cs b/Aetheris.CLI.Tests/FirmamentV2BoxStepPipelineTests.cs
new file mode 100644
index 00000000..a53dec40
--- /dev/null
+++ b/Aetheris.CLI.Tests/FirmamentV2BoxStepPipelineTests.cs
@@ -0,0 +1,45 @@
+using System.Text.RegularExpressions;
+using Aetheris.Kernel.Core.Step242;
+
+namespace Aetheris.CLI.Tests;
+
+public sealed class FirmamentV2BoxStepPipelineTests
+{
+ private static readonly string FixturePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture"));
+
+ [Fact]
+ public void STEP_V2_A1_pipeline_v2_box_step_verified_builds_emits_reimports_and_matches_volume()
+ {
+ var outDir = Path.Combine(Path.GetTempPath(), "aetheris-step-v2-a1", Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(outDir);
+ var stepPath = Path.Combine(outDir, "pipeline-v2-box-step-verified.step");
+
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exit = Aetheris.CLI.CliRunner.Run(["build", FixturePath, "--out", stepPath, "--json"], stdout, stderr);
+
+ Assert.True(exit == 0, stderr.ToString());
+ Assert.True(File.Exists(stepPath), "pipeline-v2-box-reaches-build-command");
+
+ var stepText = File.ReadAllText(stepPath);
+ Assert.Contains("ISO-10303-21", stepText, StringComparison.Ordinal);
+ Assert.True(CountStepEntities(stepText, "ADVANCED_FACE") >= 6, "pipeline-v2-box-emits-real-step advanced faces");
+ Assert.True(CountStepEntities(stepText, "VERTEX_POINT") > 0, "pipeline-v2-box-emits-real-step vertices");
+ Assert.DoesNotContain("controlled fixture only", stepText, StringComparison.OrdinalIgnoreCase);
+ Assert.DoesNotContain("trace", stepText, StringComparison.OrdinalIgnoreCase);
+
+ var import = Step242Importer.ImportBody(stepText);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));
+ Assert.Equal(6, import.Value.Topology.Faces.Count());
+ Assert.Equal(8, import.Value.Topology.Vertices.Count());
+ Assert.Equal(12, import.Value.Topology.Edges.Count());
+
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+ Assert.True(volume.Success, "pipeline-v2-box-volume-matches-expected");
+ Assert.True(volume.Exact, "V2 Box volume should use exact closed-shell analysis.");
+ Assert.InRange(Math.Abs(volume.Volume - 480d), 0d, 1e-9);
+ }
+
+ private static int CountStepEntities(string stepText, string entityName) =>
+ Regex.Matches(stepText, "=\\s*" + Regex.Escape(entityName) + "\\s*\\(", RegexOptions.CultureInvariant).Count;
+}
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index b99b5456..0f8877f7 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -1,9 +1,11 @@
using System.Text;
using System.Text.Json.Serialization;
+using System.Text.RegularExpressions;
using Aetheris.Kernel.Core.Air;
using Aetheris.Kernel.Core.Air.BRepPlan;
using Aetheris.Kernel.Core.Air.Regions;
using Aetheris.Kernel.Core.Brep.Prismatic;
+using Aetheris.Kernel.Core.Step242;
using Aetheris.Kernel.Firmament;
using Aetheris.Kernel.Firmament.FirmamentV2;
@@ -127,11 +129,21 @@ internal static class AirTraceReportBuilder
var frontend = isFirmamentV2 ? FirmamentFrontendTraceProbe.ParseV2Only(fixture.SourceBody) : FirmamentFrontendTraceProbe.ParseOnly(fixture.SourceBody);
var profileEmissionProbe = frontend.ConstructiveAir is null ? null : BoxConstructiveAirToProfileEmissionTraceProbe.Invoke(frontend.ConstructiveAir);
var actualStage = profileEmissionProbe?.StageReached ?? frontend.FrontendStageReached ?? "frontend-unavailable";
+ var stepVerifiedDiagnostics = Array.Empty<string>();
+ if (isFirmamentV2 && string.Equals(fixture.ExpectedStage, "step-verified", StringComparison.Ordinal))
+ {
+ var stepVerified = TryVerifyV2BoxStepFixture(fixture);
+ if (stepVerified.Succeeded)
+ {
+ actualStage = "step-verified";
+ }
+ stepVerifiedDiagnostics = stepVerified.Diagnostics;
+ }
var expectedStageSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedStage) || string.Equals(actualStage, fixture.ExpectedStage, StringComparison.Ordinal);
var expectationSatisfied = fixture.Expectation == "valid"
? frontend.ParseSucceeded && expectedStageSatisfied && (profileEmissionProbe?.Succeeded ?? true)
: !frontend.ParseSucceeded && expectedStageSatisfied;
- var fxDiagnostics = Stable([.. fixture.Diagnostics, .. frontend.Diagnostics, .. profileEmissionProbe?.Diagnostics ?? [], "air-x8-parser-backed-fixture-trace-created", "air-x11-parser-backed-fixture-loaded", isFirmamentV2 ? "firmament-v2-parser-invoked" : "air-x11-firmament-parser-invoked", frontend.ParseSucceeded ? (isFirmamentV2 ? "firmament-v2-parse-succeeded" : "air-x11-firmament-parse-succeeded") : (isFirmamentV2 ? "firmament-v2-parse-failed" : "air-x11-firmament-parse-failed"), expectationSatisfied ? "air-x11-parser-backed-expectation-satisfied" : "air-x11-profile-emission-expectation-not-satisfied"]).ToArray();
+ var fxDiagnostics = Stable([.. fixture.Diagnostics, .. frontend.Diagnostics, .. profileEmissionProbe?.Diagnostics ?? [], .. stepVerifiedDiagnostics, "air-x8-parser-backed-fixture-trace-created", "air-x11-parser-backed-fixture-loaded", isFirmamentV2 ? "firmament-v2-parser-invoked" : "air-x11-firmament-parser-invoked", frontend.ParseSucceeded ? (isFirmamentV2 ? "firmament-v2-parse-succeeded" : "air-x11-firmament-parse-succeeded") : (isFirmamentV2 ? "firmament-v2-parse-failed" : "air-x11-firmament-parse-failed"), expectationSatisfied ? "air-x11-parser-backed-expectation-satisfied" : "air-x11-profile-emission-expectation-not-satisfied"]).ToArray();
var featureAir = frontend.FeatureAir is null
? null
@@ -172,11 +184,15 @@ internal static class AirTraceReportBuilder
new(profileEmission?.EmitterName ?? "none", profileEmission?.Succeeded ?? false, profileEmission is null ? "parser-backed fixture stops before profile emission" : "parser-backed fixture invoked existing profile extrusion wrapper/emitter summary"),
new(profileEmission?.StepSmoke.WasChecked ?? false, profileEmission?.StepSmoke.Succeeded ?? false, profileEmission?.StepSmoke.RequiredMarkersPresent ?? false, profileEmission?.StepSmoke.ForbiddenMarkersAbsent ?? false, profileEmission?.StepSmoke.Diagnostics ?? []),
new("not-requested", "none", "none", "FirmamentPrimitive", "none", "none", "none", [], [], [], []),
- [], ["BRepPlan/CIR deferred for parser-backed box fixture", "STEP smoke unavailable for parser-backed box fixture"], fxDiagnostics,
+ [], string.Equals(actualStage, "step-verified", StringComparison.Ordinal) ? ["Box-only BRep/AP242 path verified by build/export", "non-Box V2 features deferred"] : ["BRepPlan/CIR deferred for parser-backed box fixture", "STEP smoke unavailable for parser-backed box fixture"], fxDiagnostics,
(isFirmamentV2
- ? ["real Firmament V2 parser invoked", "parser-backed fixture reaches Feature AIR summary", "no V1 parser route", "no production route replacement", "no new geometry"]
+ ? string.Equals(actualStage, "step-verified", StringComparison.Ordinal)
+ ? ["real Firmament V2 parser invoked", "V2 Box lowered to existing FirmamentLoweredBoxParameters", "existing primitive executor produced BrepBody", "real Step242Exporter emitted AP242", "STEP reimport/topology/volume verified", "no V1 parser route"]
+ : ["real Firmament V2 parser invoked", "parser-backed fixture reaches Feature AIR summary", "no V1 parser route", "no production route replacement", "no new geometry"]
: ["real Firmament parser invoked", "parser-backed fixture reaches Feature AIR summary", "parser-backed fixture reaches Constructive AIR summary", "ProfileExtrude wrapper invoked", "no production grammar expansion", "no production route replacement", "no new geometry", "no profile emitter rewrite"]),
- ["no production Firmament grammar expansion", "no production route replacement", "no production analyzer behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no route-selection/JudgmentUtility behavior change", "no CIR evaluator/tape behavior change", "no Boolean behavior change", "no AirEdgeSweep behavior change", "no BrepBoundedChamfer/BrepBoundedFillet behavior change", "no chamfer/fillet/shell geometry change", "no new geometry"],
+ string.Equals(actualStage, "step-verified", StringComparison.Ordinal)
+ ? ["V2 Box only", "no non-Box primitive wiring", "no side-hole exporter reroute", "no patterns", "no PMI", "no DFM enforcement", "no hardcoded STEP template", "no trace-only output"]
+ : ["no production Firmament grammar expansion", "no production route replacement", "no production analyzer behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no route-selection/JudgmentUtility behavior change", "no CIR evaluator/tape behavior change", "no Boolean behavior change", "no AirEdgeSweep behavior change", "no BrepBoundedChamfer/BrepBoundedFillet behavior change", "no chamfer/fillet/shell geometry change", "no new geometry"],
new(fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, true, fxDiagnostics),
fixture.Path, fixture.Expectation, fixture.CaseName, fixture.ExpectedStage, actualStage!, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics,
new(true, frontend.ParserName, frontend.ParseSucceeded, frontend.Diagnostics, actualStage!, frontend.FrontendSummary),
@@ -184,6 +200,65 @@ internal static class AirTraceReportBuilder
}
+
+ private static (bool Succeeded, string[] Diagnostics) TryVerifyV2BoxStepFixture(FirmFixture fixture)
+ {
+ var diagnostics = new List<string> { "step-v2-a1-build-command-invoked" };
+ try
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-step-v2-a1-trace", Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(dir);
+ var stepPath = Path.Combine(dir, "pipeline-v2-box-step-verified.step");
+ var build = FirmamentBuildAndExport.Run(fixture.Path, stepPath);
+ if (!build.IsSuccess)
+ {
+ diagnostics.Add("step-v2-a1-build-failed");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var stepText = File.ReadAllText(stepPath);
+ if (CountStepEntities(stepText, "ADVANCED_FACE") < 6 || CountStepEntities(stepText, "VERTEX_POINT") <= 0)
+ {
+ diagnostics.Add("step-v2-a1-step-topology-markers-missing");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var import = Step242Importer.ImportBody(stepText);
+ if (!import.IsSuccess)
+ {
+ diagnostics.Add("step-v2-a1-step-reimport-failed");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ if (import.Value.Topology.Faces.Count() != 6 || import.Value.Topology.Vertices.Count() != 8 || import.Value.Topology.Edges.Count() != 12)
+ {
+ diagnostics.Add("step-v2-a1-topology-count-mismatch");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+ if (!volume.Success || Math.Abs(volume.Volume - 480d) > 1e-9)
+ {
+ diagnostics.Add("step-v2-a1-volume-mismatch");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ diagnostics.Add("step-v2-a1-real-ap242-emitted");
+ diagnostics.Add("step-v2-a1-step-roundtrip-succeeded");
+ diagnostics.Add("step-v2-a1-topology-verified");
+ diagnostics.Add("step-v2-a1-volume-verified");
+ return (true, Stable(diagnostics).ToArray());
+ }
+ catch
+ {
+ diagnostics.Add("step-v2-a1-step-verification-threw");
+ return (false, Stable(diagnostics).ToArray());
+ }
+ }
+
+ private static int CountStepEntities(string stepText, string entityName) =>
+ Regex.Matches(stepText, "=\\s*" + Regex.Escape(entityName) + "\\s*\\(", RegexOptions.CultureInvariant).Count;
+
private static bool IsMetadataOnlyFixture(FirmFixture fixture)
{
var implementation = fixture.Metadata.GetValueOrDefault("implementation");
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 4814e0e2..9b361d8e 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -1,5 +1,8 @@
using System.Text;
using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Execution;
+using Aetheris.Kernel.Firmament.FirmamentV2;
namespace Aetheris.Kernel.Firmament;
@@ -11,7 +14,7 @@ public static class FirmamentBuildAndExport
var fullSourcePath = Path.GetFullPath(sourcePath);
var sourceText = NormalizeLf(File.ReadAllText(fullSourcePath, Encoding.UTF8));
- var exportResult = FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
+ var exportResult = ExportSource(sourceText);
if (!exportResult.IsSuccess)
{
return KernelResult<FirmamentBuildAndExportResult>.Failure(exportResult.Diagnostics);
@@ -31,6 +34,49 @@ public static class FirmamentBuildAndExport
exportResult.Value));
}
+
+ private static KernelResult<FirmamentStepExportResult> ExportSource(string sourceText)
+ {
+ var v2Parse = FirmamentV2Parser.Parse(sourceText);
+ if (v2Parse.IsSuccess && v2Parse.Document is not null)
+ {
+ var lowering = FirmamentV2BuildLowering.LowerBoxOnly(v2Parse.Document);
+ if (!lowering.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(lowering.Diagnostics);
+ }
+
+ var execution = FirmamentPrimitiveExecutor.Execute(lowering.Value);
+ if (!execution.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(execution.Diagnostics);
+ }
+
+ var executedBox = execution.Value.ExecutedPrimitives.LastOrDefault();
+ if (executedBox is null)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(execution.Diagnostics);
+ }
+
+ var step = Step242Exporter.ExportBody(executedBox.Body);
+ if (!step.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
+ }
+
+ return KernelResult<FirmamentStepExportResult>.Success(
+ new FirmamentStepExportResult(
+ step.Value,
+ executedBox.FeatureId,
+ executedBox.OpIndex,
+ "primitive",
+ "box",
+ DatumInspection: [],
+ DimensionInspection: []));
+ }
+
+ return FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
+ }
private static string ResolveDefaultOutputPath(string fullSourcePath)
{
var root = FindRepositoryRoot(Path.GetDirectoryName(fullSourcePath)!);
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2BuildLowering.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2BuildLowering.cs
new file mode 100644
index 00000000..75389989
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2BuildLowering.cs
@@ -0,0 +1,49 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Firmament.Diagnostics;
+using Aetheris.Kernel.Firmament.Lowering;
+
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+internal static class FirmamentV2BuildLowering
+{
+ public static KernelResult<FirmamentPrimitiveLoweringPlan> LowerBoxOnly(FirmamentV2Document document)
+ {
+ ArgumentNullException.ThrowIfNull(document);
+
+ if (document.ModifyBlocks is { Count: > 0 })
+ {
+ return Failure("Firmament V2 build/export currently admits only a single Box solid with no modify blocks.");
+ }
+
+ if (document.Solids.Count != 1)
+ {
+ return Failure("Firmament V2 build/export currently admits exactly one Box solid.");
+ }
+
+ var solid = document.Solid;
+ if (!string.Equals(solid.RecordType, "Box", StringComparison.Ordinal) || solid.Box.Size.Count != 3)
+ {
+ return Failure("Firmament V2 build/export currently admits only Box solids.");
+ }
+
+ var primitive = new FirmamentLoweredPrimitive(
+ OpIndex: 0,
+ FeatureId: solid.Name,
+ Kind: FirmamentLoweredPrimitiveKind.Box,
+ Parameters: new FirmamentLoweredBoxParameters(solid.Box.Size[0], solid.Box.Size[1], solid.Box.Size[2]),
+ Placement: null);
+
+ return KernelResult<FirmamentPrimitiveLoweringPlan>.Success(new FirmamentPrimitiveLoweringPlan([primitive], [], []));
+ }
+
+ private static KernelResult<FirmamentPrimitiveLoweringPlan> Failure(string message) =>
+ KernelResult<FirmamentPrimitiveLoweringPlan>.Failure(
+ [
+ new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ message,
+ FirmamentDiagnosticConventions.Source)
+ ]);
+}
diff --git a/docs/implementation/step-v2-a1-box-ap242-pipeline.md b/docs/implementation/step-v2-a1-box-ap242-pipeline.md
new file mode 100644
index 00000000..de4a62b6
--- /dev/null
+++ b/docs/implementation/step-v2-a1-box-ap242-pipeline.md
@@ -0,0 +1,70 @@
+# STEP-V2-A1 — Firmament V2 Box AP242 pipeline
+
+STEP-V2-A1 connects the smallest Firmament V2 production path to the existing AP242 back half for **Box only**.
+
+## Pipeline path
+
+The implemented path is:
+
+```text
+Firmament V2 Box source
+ -> FirmamentV2Parser
+ -> FirmamentV2BuildLowering
+ -> FirmamentLoweredBoxParameters
+ -> FirmamentPrimitiveExecutor
+ -> BrepBody
+ -> Step242Exporter
+ -> emitted AP242
+ -> Step242Importer / StepAnalyzer verification
+```
+
+`FirmamentV2BuildLowering` is intentionally narrow. It accepts exactly one V2 `Box` solid with no `modify` blocks and lowers only that solid into the existing lowered primitive representation. It does not introduce a V2-only BRep builder or exporter.
+
+## Fixture
+
+The Tier 0 proof fixture is:
+
+```text
+fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture
+```
+
+It declares:
+
+- `fixture-id: pipeline-v2-box-step-verified`
+- `expected-stage: step-verified`
+- `build-command: aetheris build`
+- expected topology: 6 faces, 8 vertices, 12 edges
+- expected volume: 480 mm^3 for size `[10, 8, 6]`
+
+## Command under test
+
+The integration test invokes the real production CLI path:
+
+```bash
+aetheris build fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture --out <temp>/pipeline-v2-box-step-verified.step --json
+```
+
+This reaches `FirmamentBuildAndExport.Run`, uses the V2 Box lowering bridge, executes the existing primitive executor to produce a real `BrepBody`, and calls the real `Step242Exporter`.
+
+## Verification checks
+
+The integration proof in `Aetheris.CLI.Tests/FirmamentV2BoxStepPipelineTests.cs` checks that:
+
+1. the real build command accepts the V2 Box fixture;
+2. the emitted STEP file exists;
+3. the AP242 text contains at least 6 `ADVANCED_FACE` entities;
+4. the AP242 text contains `VERTEX_POINT` entities;
+5. the output is not a trace-only artifact;
+6. `Step242Importer.ImportBody` reimports the emitted AP242;
+7. reimported topology is exactly 6 faces, 8 vertices, and 12 edges;
+8. `StepAnalyzer.AnalyzeVolume` reports exact volume 480 within tolerance.
+
+The fixture trace path also performs these checks before reporting `step-verified`, so the stage label is not parser-only or trace-only.
+
+## Deferred scope
+
+STEP-V2-A1 intentionally does **not** wire Cylinder, Cone, Sphere, Torus, prism families, slots, rounded boxes, chamfers, fillets, drafts, library parts, side-hole exporter rerouting, patterns, PMI, or DFM enforcement. Those remain outside this Box-only Tier 0 gate.
+
+## MVP contract relationship
+
+This milestone is the first implementation slice for `docs/mvp/firmament-v2-ap242-mvp-readiness-contract.md`: a Firmament V2 fixture is considered ready only when real AP242 is emitted from a real `BrepBody` by `Step242Exporter` and independently verified by reimport, topology checks, and volume checks.
diff --git a/fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture
new file mode 100644
index 00000000..69453177
--- /dev/null
+++ b/fixtures/FirmamentV2/Primitive/valid/pipeline-v2-box-step-verified.valid.firmfixture
@@ -0,0 +1,28 @@
+// fixture-id: pipeline-v2-box-step-verified
+// case: pipeline-v2-box-step-verified
+// category: Primitive
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// expected-feature-air: CreateBox
+// dimensions: 10, 8, 6
+// units: mm
+// tier: 0
+// mvp-required: true
+// feature-area: pipeline/box
+// build-command: aetheris build
+// expected-topology: faces=6, vertices=8, edges=12
+// expected-volume: 480
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-A1 Tier 0 V2 Box fixture; verified by build/export integration test through real BrepBody and Step242Exporter.
+
+model BoxStepVerified {
+ units mm
+
+ solid base: Box {
+ size: [10, 8, 6]
+ }
+}