Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add parser-backed Firmament box fixture trace

Yuechen Li0a8d347f9861
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index b0c6c44b..8ba671c2 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -105,6 +105,55 @@ public sealed class AirTraceCommandTests
}
+
+ [Fact]
+ public void TraceParserBackedFixture_ValidBox_DefaultsToText()
+ {
+ var (exitCode, output, error) = Run("trace", "--fixture", PrimitiveFixture("valid/box.valid.firmfixture"));
+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.False(output.TrimStart().StartsWith("{", StringComparison.Ordinal));
+ Assert.Contains("Fixture", output); Assert.Contains("Frontend", output);
+ Assert.Contains("Parser-backed: true", output); Assert.Contains("Parse succeeded: true", output);
+ Assert.Contains("Expected stage: parsed", output); Assert.Contains("Actual stage: parsed", output);
+ Assert.Contains("Expectation satisfied: true", output);
+ }
+
+ [Fact]
+ public void TraceParserBackedFixture_ValidBox_JsonParses()
+ {
+ var (exitCode, output, _) = Run("trace", "--fixture", PrimitiveFixture("valid/box.valid.firmfixture"), "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.Equal("firmfixture", root.GetProperty("inputKind").GetString());
+ Assert.Equal("valid", root.GetProperty("fixture").GetProperty("expectation").GetString());
+ Assert.True(root.GetProperty("fixture").GetProperty("parserBacked").GetBoolean());
+ Assert.True(root.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean());
+ Assert.True(root.GetProperty("frontend").GetProperty("parserBacked").GetBoolean());
+ Assert.True(root.GetProperty("frontend").GetProperty("parseSucceeded").GetBoolean());
+ Assert.Equal("parsed", root.GetProperty("frontend").GetProperty("frontendStageReached").GetString());
+ Assert.Contains("air-x8-firmament-parse-succeeded", output);
+ }
+
+ [Fact]
+ public void TraceParserBackedFixture_ExpectationFailure_ReturnsNonZero()
+ {
+ var path = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N") + ".valid.firmfixture");
+ File.WriteAllText(path, "// case: box\n// expected: valid\n// expected-stage: parsed\n// parser-backed: true\n\nnot valid firmament");
+ var (exitCode, output, error) = Run("trace", "--fixture", path, "--json");
+ Assert.NotEqual(0, exitCode); Assert.Contains("expectation", error, StringComparison.OrdinalIgnoreCase);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.False(root.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean());
+ Assert.False(root.GetProperty("frontend").GetProperty("parseSucceeded").GetBoolean());
+ Assert.Contains("air-x8-firmament-parse-failed", output);
+ }
+
+ [Fact]
+ public void TraceParserBackedFixture_JsonOutput_IsDeterministic()
+ {
+ var valid = PrimitiveFixture("valid/box.valid.firmfixture");
+ Assert.Equal(Run("trace", "--fixture", valid, "--json").Stdout, Run("trace", "--fixture", valid, "--json").Stdout);
+ }
+
[Fact]
public void TraceFixtureValidTopFaceLoopChamfer_DefaultsToText()
{
@@ -166,6 +215,7 @@ public sealed class AirTraceCommandTests
}
private static string Fixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Chamfer", relative));
+ private static string PrimitiveFixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Primitive", relative));
private static (int ExitCode, string Stdout, string Stderr) Run(params string[] args)
{
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 94b71add..2b5eee16 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -3,6 +3,7 @@ using System.Text.Json.Serialization;
using Aetheris.Kernel.Core.Air;
using Aetheris.Kernel.Core.Air.BRepPlan;
using Aetheris.Kernel.Core.Brep.Prismatic;
+using Aetheris.Kernel.Firmament;
namespace Aetheris.CLI;
@@ -34,9 +35,11 @@ internal sealed record AirTraceReport(
string? ExpectedRoute = null,
string? ExpectedReason = null,
bool? ExpectationSatisfied = null,
- IReadOnlyList<string>? FixtureDiagnostics = null);
+ IReadOnlyList<string>? FixtureDiagnostics = null,
+ AirTraceFrontendSummary? Frontend = null);
-internal sealed record AirTraceFixtureSummary(string Path, string Expectation, string CaseName, string? ExpectedStage, string ActualStageReached, string? ExpectedRoute, string? ExpectedReason, bool ExpectationSatisfied, IReadOnlyList<string> Diagnostics);
+internal sealed record AirTraceFixtureSummary(string Path, string Expectation, string CaseName, string? ExpectedStage, string ActualStageReached, string? ExpectedRoute, string? ExpectedReason, bool ExpectationSatisfied, bool ParserBacked, IReadOnlyList<string> Diagnostics);
+internal sealed record AirTraceFrontendSummary(bool ParserBacked, string? ParserName, bool? ParseSucceeded, IReadOnlyList<string> ParseDiagnostics, string? FrontendStageReached, string? FrontendSummary);
internal sealed record AirTraceAirSummary(string Node, string Route, string SelectionClass, string Rule, string ConstructionHistory, string FeatureName, string FeatureId, string ProvenanceMilestone);
internal sealed record AirTraceRouteDecisionSummary(string Mode, string? SelectedRoute, bool Succeeded, string Recommendation, string SelectionClass, string Rule, IReadOnlyList<string> Diagnostics);
internal sealed record AirTraceBRepPlanSummary(string PlanKind, int Vertices, int Curves, int Edges, int Faces, int Loops, int Coedges, int Surfaces, int CapFaces, int TransitionFaces, int ChamferFaces, int SideFaces, string SplitPolicy, string Bounds, string? RouteSelectionMode, IReadOnlyList<string> Diagnostics);
@@ -47,7 +50,7 @@ internal sealed record AirTraceCirMirrorSummary(string Status, string Backend, s
internal static class AirTraceReportBuilder
{
public static readonly string[] SupportedCases = ["prismatic-section-transition", "top-face-loop-chamfer"];
- public static readonly string[] SupportedFixtureCases = ["arbitrary-graph-chamfer", "loop-fillet-deferred", "non-uniform-loop-chamfer", "top-face-loop-chamfer"];
+ public static readonly string[] SupportedFixtureCases = ["arbitrary-graph-chamfer", "box", "loop-fillet-deferred", "non-uniform-loop-chamfer", "top-face-loop-chamfer"];
public static AirTraceReport Build(string caseName)
{
@@ -71,6 +74,8 @@ internal static class AirTraceReportBuilder
public static AirTraceReport BuildFixture(FirmFixture fixture)
{
+ if (fixture.ParserBacked) return BuildParserBackedFixture(fixture);
+
var caseName = fixture.CaseName;
var report = caseName switch
{
@@ -89,10 +94,35 @@ internal static class AirTraceReportBuilder
var fxDiagnostics = Stable([.. fixture.Diagnostics, "air-x7-firmfixture-case-mapped", "air-x7-firmfixture-trace-created", "air-x7-lowering-stage-recorded", expectationSatisfied ? "air-x7-expectation-satisfied" : "air-x7-fixture-expectation-not-satisfied"]).ToArray();
return report with
{
- Milestone = "AIR-X7", InputKind = "firmfixture", FixturePath = fixture.Path, FixtureExpectation = fixture.Expectation, FixtureCaseName = caseName, ExpectedStage = fixture.ExpectedStage, ActualStageReached = actualStage, ExpectedRoute = fixture.ExpectedRoute, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, caseName, fixture.ExpectedStage, actualStage, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, fxDiagnostics), Diagnostics = Stable([.. report.Diagnostics, .. fxDiagnostics]).ToArray()
+ Milestone = "AIR-X7", InputKind = "firmfixture", FixturePath = fixture.Path, FixtureExpectation = fixture.Expectation, FixtureCaseName = caseName, ExpectedStage = fixture.ExpectedStage, ActualStageReached = actualStage, ExpectedRoute = fixture.ExpectedRoute, ExpectedReason = fixture.ExpectedReason, ExpectationSatisfied = expectationSatisfied, FixtureDiagnostics = fxDiagnostics, Fixture = new(fixture.Path, fixture.Expectation, caseName, fixture.ExpectedStage, actualStage, fixture.ExpectedRoute, fixture.ExpectedReason, expectationSatisfied, false, fxDiagnostics), Diagnostics = Stable([.. report.Diagnostics, .. fxDiagnostics]).ToArray()
};
}
+ private static AirTraceReport BuildParserBackedFixture(FirmFixture fixture)
+ {
+ var frontend = FirmamentFrontendTraceProbe.ParseOnly(fixture.SourceBody);
+ var actualStage = frontend.FrontendStageReached;
+ var expectedStageSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedStage) || string.Equals(actualStage, fixture.ExpectedStage, StringComparison.Ordinal);
+ var expectationSatisfied = fixture.Expectation == "valid"
+ ? frontend.ParseSucceeded && expectedStageSatisfied
+ : !frontend.ParseSucceeded && expectedStageSatisfied;
+ var fxDiagnostics = Stable([.. fixture.Diagnostics, .. frontend.Diagnostics, "air-x8-parser-backed-fixture-trace-created", expectationSatisfied ? "air-x8-parser-backed-expectation-satisfied" : "air-x8-parser-backed-expectation-not-satisfied"]).ToArray();
+
+ return new("AIR-X8", "trace", "lowering", "firmfixture", fixture.CaseName, expectationSatisfied, frontend.FrontendSummary,
+ new("FirmamentPrimitive", "none", "none", "none", "parser-backed-source-fixture", fixture.CaseName, fixture.CaseName, "AIR-X8"),
+ new("none", null, false, "AIR lowering is not wired for parser-backed trace fixtures in AIR-X8.", "none", "none", []),
+ new("none", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, "none", "none", null, []),
+ new("none", false, "parser-backed fixture stops at truthful frontend boundary"),
+ new(false, false, false, false, []),
+ new("not-requested", "none", "none", "FirmamentPrimitive", "none", "none", "none", [], [], [], []),
+ [], ["AIR lowering not wired for parser-backed fixture"], fxDiagnostics,
+ ["real Firmament parser invoked", "parser-backed fixture stops at truthful frontend boundary", "no production grammar expansion", "no new geometry"],
+ ["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));
+ }
+
public static string FixtureFileStem(FirmFixture fixture) => $"air-x7-{fixture.CaseName}-firmfixture-trace";
private static AirTraceReport BuildPrismatic()
@@ -164,7 +194,11 @@ internal static class AirTraceTextRenderer
b.AppendLine($"Case: {r.CaseName}"); b.AppendLine($"Trace kind: {r.TraceKind}"); b.AppendLine($"Input kind: {r.InputKind}"); b.AppendLine();
if (r.Fixture is not null)
{
- b.AppendLine("Fixture"); b.AppendLine($" Path: {r.Fixture.Path}"); b.AppendLine($" Expectation: {r.Fixture.Expectation}"); b.AppendLine($" Expected stage: {r.Fixture.ExpectedStage}"); b.AppendLine($" Actual stage: {r.Fixture.ActualStageReached}"); b.AppendLine($" Expected route: {r.Fixture.ExpectedRoute}"); b.AppendLine($" Expected reason: {r.Fixture.ExpectedReason}"); b.AppendLine($" Expectation satisfied: {r.Fixture.ExpectationSatisfied.ToString().ToLowerInvariant()}"); b.AppendLine();
+ b.AppendLine("Fixture"); b.AppendLine($" Path: {r.Fixture.Path}"); b.AppendLine($" Expectation: {r.Fixture.Expectation}"); b.AppendLine($" Expected stage: {r.Fixture.ExpectedStage}"); b.AppendLine($" Actual stage: {r.Fixture.ActualStageReached}"); b.AppendLine($" Expected route: {r.Fixture.ExpectedRoute}"); b.AppendLine($" Expected reason: {r.Fixture.ExpectedReason}"); b.AppendLine($" Parser-backed: {r.Fixture.ParserBacked.ToString().ToLowerInvariant()}"); b.AppendLine($" Expectation satisfied: {r.Fixture.ExpectationSatisfied.ToString().ToLowerInvariant()}"); b.AppendLine();
+ }
+ if (r.Frontend is not null)
+ {
+ b.AppendLine("Frontend"); b.AppendLine($" Parser-backed: {r.Frontend.ParserBacked.ToString().ToLowerInvariant()}"); b.AppendLine($" Parser name: {r.Frontend.ParserName}"); b.AppendLine($" Parse succeeded: {r.Frontend.ParseSucceeded?.ToString().ToLowerInvariant()}"); b.AppendLine($" Frontend stage reached: {r.Frontend.FrontendStageReached}"); b.AppendLine(" Diagnostics:"); foreach (var d in r.Frontend.ParseDiagnostics) b.AppendLine($" - {d}"); b.AppendLine();
}
b.AppendLine("AIR"); b.AppendLine($" Node: {r.Air.Node}"); b.AppendLine($" Route: {r.Air.Route}"); b.AppendLine($" Selection class: {r.Air.SelectionClass}"); b.AppendLine($" Rule: {r.Air.Rule}"); b.AppendLine($" Construction history: {r.Air.ConstructionHistory}"); b.AppendLine();
b.AppendLine("Route decision"); b.AppendLine($" Mode: {r.RouteDecision.Mode}"); b.AppendLine($" Selected route: {r.RouteDecision.SelectedRoute}"); b.AppendLine($" Succeeded: {r.RouteDecision.Succeeded.ToString().ToLowerInvariant()}"); b.AppendLine();
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 9e3e700d..0c8f3932 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -260,12 +260,6 @@ public static class CliRunner
return 1;
}
report = AirTraceReportBuilder.BuildFixture(fixture);
- if (report.ExpectationSatisfied != true)
- {
- stderr.WriteLine("Firmament fixture expectation was not satisfied.");
- stderr.WriteLine("air-x7-fixture-expectation-not-satisfied");
- return 1;
- }
fileStem = AirTraceReportBuilder.FixtureFileStem(fixture);
}
else
@@ -310,6 +304,12 @@ public static class CliRunner
}
stdout.WriteLine(text);
+ if (report.ExpectationSatisfied == false)
+ {
+ stderr.WriteLine("Firmament fixture expectation was not satisfied.");
+ stderr.WriteLine("air-x7-fixture-expectation-not-satisfied");
+ return 1;
+ }
return 0;
}
diff --git a/Aetheris.CLI/FirmFixture.cs b/Aetheris.CLI/FirmFixture.cs
index 266b4beb..f6619b4c 100644
--- a/Aetheris.CLI/FirmFixture.cs
+++ b/Aetheris.CLI/FirmFixture.cs
@@ -8,6 +8,8 @@ internal sealed record FirmFixture(
string? ExpectedRoute,
string? ExpectedReason,
IReadOnlyDictionary<string, string> Metadata,
+ string SourceBody,
+ bool ParserBacked,
IReadOnlyList<string> Diagnostics);
internal static class FirmFixtureLoader
@@ -40,14 +42,31 @@ internal static class FirmFixtureLoader
if (metadata.TryGetValue("expected", out var expected) && !string.Equals(expected, expectation, StringComparison.Ordinal))
throw new FirmFixtureException("air-x7-firmfixture-metadata-invalid", $"Fixture extension implies '{expectation}' but metadata expected '{expected}'.");
+ var sourceBody = ExtractSourceBody(lines);
+ var parserBacked = metadata.TryGetValue("parser-backed", out var parserBackedValue) && string.Equals(parserBackedValue, "true", StringComparison.OrdinalIgnoreCase);
var diagnostics = new[]
{
"air-x7-firmfixture-loaded",
"air-x7-firmfixture-extension-classified",
"air-x7-firmfixture-metadata-parsed",
- expectation == "valid" ? "air-x7-firmfixture-expectation-valid" : "air-x7-firmfixture-expectation-invalid"
+ expectation == "valid" ? "air-x7-firmfixture-expectation-valid" : "air-x7-firmfixture-expectation-invalid",
+ parserBacked ? "air-x8-parser-backed-fixture-loaded" : "air-x7-metadata-driven-fixture-loaded",
+ parserBacked ? "air-x8-firmfixture-source-body-extracted" : "air-x7-firmfixture-source-body-not-required"
}.Order(StringComparer.Ordinal).ToArray();
- return new(normalized, caseName, expectation, metadata.GetValueOrDefault("expected-stage"), metadata.GetValueOrDefault("expected-route"), metadata.GetValueOrDefault("expected-reason"), metadata, diagnostics);
+ return new(normalized, caseName, expectation, metadata.GetValueOrDefault("expected-stage"), metadata.GetValueOrDefault("expected-route"), metadata.GetValueOrDefault("expected-reason"), metadata, sourceBody, parserBacked, diagnostics);
+ }
+
+ private static string ExtractSourceBody(string[] lines)
+ {
+ var bodyStart = 0;
+ for (; bodyStart < lines.Length; bodyStart++)
+ {
+ var line = lines[bodyStart].Trim();
+ if (line.Length == 0) continue;
+ if (!line.StartsWith("//", StringComparison.Ordinal)) break;
+ }
+
+ return string.Join(Environment.NewLine, lines.Skip(bodyStart)).Trim();
}
public static string ClassifyExpectation(string path)
diff --git a/Aetheris.Kernel.Firmament/FirmamentFrontendTraceProbe.cs b/Aetheris.Kernel.Firmament/FirmamentFrontendTraceProbe.cs
new file mode 100644
index 00000000..abf2fba6
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentFrontendTraceProbe.cs
@@ -0,0 +1,50 @@
+using Aetheris.Kernel.Firmament.Parsing;
+
+namespace Aetheris.Kernel.Firmament;
+
+public sealed record FirmamentFrontendTraceProbeResult(
+ string ParserName,
+ bool ParseSucceeded,
+ string FrontendStageReached,
+ string FrontendSummary,
+ IReadOnlyList<string> Diagnostics);
+
+public static class FirmamentFrontendTraceProbe
+{
+ public static FirmamentFrontendTraceProbeResult ParseOnly(string sourceText)
+ {
+ ArgumentNullException.ThrowIfNull(sourceText);
+
+ var parseResult = FirmamentTopLevelParser.Parse(sourceText);
+ if (parseResult.IsSuccess)
+ {
+ var opCount = parseResult.Value.Ops.Entries.Count;
+ return new(
+ "FirmamentTopLevelParser",
+ true,
+ "parsed",
+ $"Parsed Firmament document with {opCount} op(s). AIR lowering is not wired for parser-backed trace fixtures in AIR-X8.",
+ [
+ "air-x8-firmament-parser-invoked",
+ "air-x8-firmament-parse-succeeded",
+ "air-x8-frontend-stage-recorded",
+ "air-x8-air-lowering-not-wired-for-parser-backed-fixture",
+ "air-x8-parser-backed-lowering-boundary-reached",
+ "air-x8-parser-backed-fixture-does-not-change-production-grammar"
+ ]);
+ }
+
+ return new(
+ "FirmamentTopLevelParser",
+ false,
+ "parsed",
+ "Firmament parser rejected the fixture source body.",
+ [
+ "air-x8-firmament-parser-invoked",
+ "air-x8-firmament-parse-failed",
+ "air-x8-frontend-stage-recorded",
+ .. parseResult.Diagnostics.Select(d => d.Code.ToString()).Order(StringComparer.Ordinal),
+ "air-x8-parser-backed-fixture-does-not-change-production-grammar"
+ ]);
+ }
+}
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index 2d2ed13c..f448df29 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -765,3 +765,7 @@ AIR-X6 adds `aetheris trace` as a top-level compiler-lowering report command for
## AIR-X7 fixture corpus note
Firmament `.valid.firmfixture` and `.invalid.firmfixture` files are source/lowering contract fixtures. They document accepted and rejected/deferred authoring-intent programs and let `aetheris trace --fixture` report compiler lowering stages without treating STEP as construction truth or changing production geometry behavior.
+
+## AIR-X8 parser-backed fixture anchor
+
+AIR-X8 anchors the Firmament fixture corpus to the real Firmament frontend for one minimal primitive source form. The primitive box `.valid.firmfixture` is parser-backed, reaches the truthful `parsed` frontend stage, and deliberately does not claim AIR/BRepPlan/CIR/STEP lowering until that bridge is explicitly wired. Metadata-driven AIR-X7 Chamfer fixtures remain valid lowering contracts.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
index 0b6b5132..cefcbcce 100644
--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -142,3 +142,7 @@ Recommended AIR-X7: **unified trace artifact corpus / golden summaries**. AIR-X6
## AIR-X7 fixture input extension
AIR-X7 extends `aetheris trace` with `--fixture <path>` while keeping AIR-X6 built-in `--case` traces intact. Fixture paths must end in `.valid.firmfixture` or `.invalid.firmfixture`; `--case` and `--fixture` are mutually exclusive. Text remains default, JSON is emitted only with `--json`, and `--out-dir` writes the corresponding `.txt` or `.json` report. Fixture trace reports add fixture expectation, expected/actual lowering stage, expected route/reason, expectation satisfaction, and deterministic fixture diagnostics. Arbitrary STEP input remains rejected by `trace`; use `analyze` for STEP geometry.
+
+## AIR-X8 parser-backed fixture frontend section
+
+For `.firmfixture` inputs with `// parser-backed: true`, `aetheris trace --fixture` now includes a `Frontend` section in text output and a `frontend` object in JSON. The fields record whether parser-backed mode was requested, the parser/frontend name, parse success, deterministic parse diagnostics, and the truthful frontend stage reached. The first parser-backed primitive box fixture stops at `parsed` because Firmament-to-AIR fixture lowering is not wired in AIR-X8.
diff --git a/docs/air-x7-firmament-fixture-trace-corpus.md b/docs/air-x7-firmament-fixture-trace-corpus.md
index d1c21f21..0e65f3a8 100644
--- a/docs/air-x7-firmament-fixture-trace-corpus.md
+++ b/docs/air-x7-firmament-fixture-trace-corpus.md
@@ -99,3 +99,9 @@ AIR-X7 does not change production Firmament syntax or behavior, production route
## Recommended next milestone
Recommended AIR-X8: **Firmament parser-backed trace fixture for one real source form**. AIR-X7 found that metadata-driven fixture contracts are sufficient for stable trace semantics, but the next convergence blocker is tying at least one `.firmfixture` body to real frontend parsing without prematurely expanding unsupported language forms.
+
+## AIR-X8 parser-backed fixture mode
+
+AIR-X8 adds opt-in parser-backed fixture mode with `// parser-backed: true`. Metadata-driven AIR-X7 fixtures remain the default. Parser-backed fixtures extract the non-metadata body, invoke the existing Firmament frontend, report parse success/failure and `frontendStageReached`, and satisfy the fixture expectation from the truthful frontend stage reached.
+
+The first parser-backed fixture is `fixtures/Firmament/Primitive/valid/box.valid.firmfixture`. It reaches `parsed` and records the explicit AIR-X8 boundary diagnostic that AIR lowering is not wired for parser-backed fixtures yet.
diff --git a/docs/air-x8-parser-backed-firmament-fixture.md b/docs/air-x8-parser-backed-firmament-fixture.md
new file mode 100644
index 00000000..e3222ad5
--- /dev/null
+++ b/docs/air-x8-parser-backed-firmament-fixture.md
@@ -0,0 +1,96 @@
+# AIR-X8 — Parser-backed Firmament fixture
+
+## Purpose and scope
+
+AIR-X8 anchors the `.firmfixture` corpus to real Firmament frontend behavior for one smallest source form. The new fixture proves that `aetheris trace --fixture` can load fixture metadata, extract the source body, invoke the existing Firmament parser, record frontend fields, and satisfy or fail the fixture expectation from the parser result.
+
+## Relationship to AIR-X7
+
+AIR-X7 introduced source-level `.valid.firmfixture` and `.invalid.firmfixture` contracts, but the first Chamfer fixtures were metadata-driven lowering contracts. AIR-X8 keeps that behavior and adds an opt-in parser-backed mode.
+
+## Metadata-driven vs parser-backed fixtures
+
+Metadata-driven fixtures remain the default when `parser-backed: true` is absent. Parser-backed fixtures add:
+
+```text
+// parser-backed: true
+```
+
+When present, trace invokes the existing Firmament frontend on the non-metadata body.
+
+## First parser-backed fixture
+
+The first parser-backed fixture is:
+
+```text
+fixtures/Firmament/Primitive/valid/box.valid.firmfixture
+```
+
+It uses existing TOON-style Firmament syntax already present in Firmament tests:
+
+```text
+firmament:
+ version: 1
+
+model:
+ name: air-x8-box
+ units: mm
+
+ops[1]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 10
+ 8
+ 6
+```
+
+This is intentionally a primitive box document rather than a new call-expression syntax. No grammar was expanded for AIR-X8.
+
+## Frontend trace fields
+
+Parser-backed reports include frontend fields:
+
+- `parserBacked`
+- `parserName`
+- `parseSucceeded`
+- `parseDiagnostics`
+- `frontendStageReached`
+- `frontendSummary`
+- `expectationSatisfied`
+
+Text output includes a `Frontend` section. JSON output includes a stable `frontend` object.
+
+## Stage truthfulness
+
+The AIR-X8 fixture reaches `parsed`. Trace does not claim Firmament-to-AIR, BRepPlan, CIR mirror, or STEP smoke for this parser-backed fixture because that lowering bridge is not wired into fixture trace yet. The report records `air-x8-air-lowering-not-wired-for-parser-backed-fixture` and stops at the truthful frontend boundary.
+
+## Existing Chamfer fixtures
+
+The AIR-X7 Chamfer fixtures remain metadata-driven. They continue to map to existing AIR route-selection/lowering trace behavior and are not converted to parser-backed mode.
+
+## Invalid parser-backed behavior
+
+A `.valid.firmfixture` with `parser-backed: true` and invalid source fails the fixture contract, emits parser failure diagnostics, and returns nonzero. An optional `.invalid.firmfixture` can later be added when the corpus needs a stable parser-rejection contract.
+
+## Non-goals
+
+- no production Firmament grammar expansion;
+- no full Firmament-to-AIR migration;
+- no geometry changes;
+- no route replacement;
+- no BRepPlan semantic changes;
+- no CIR evaluator/tape behavior changes;
+- no STEP exporter/importer changes;
+- no BRep topology changes;
+- no Boolean, chamfer, fillet, shell, AirEdgeSweep, BrepBoundedChamfer, or BrepBoundedFillet behavior changes;
+- no arbitrary graph, import/recovery, triangle migration, or NURBS/freeform expansion.
+
+## Tests run
+
+AIR-X8 validation used CLI help, parser-backed text/JSON trace, existing metadata-driven Chamfer trace, and focused `dotnet test` filters for CLI/Firmament/Core/FrictionLab where available.
+
+## Recommended next milestone
+
+Recommended AIR-X9: **Firmament-to-AIR frontend boundary for parsed box primitive**. AIR-X8 proves parser invocation and isolates the next blocker: parsed primitive source is not yet wired into AIR trace lowering.
diff --git a/fixtures/Firmament/Primitive/valid/box.valid.firmfixture b/fixtures/Firmament/Primitive/valid/box.valid.firmfixture
new file mode 100644
index 00000000..5f1ad7c5
--- /dev/null
+++ b/fixtures/Firmament/Primitive/valid/box.valid.firmfixture
@@ -0,0 +1,21 @@
+// case: box
+// expected: valid
+// expected-stage: parsed
+// parser-backed: true
+// description: Minimal parser-backed Firmament primitive fixture.
+
+firmament:
+ version: 1
+
+model:
+ name: air-x8-box
+ units: mm
+
+ops[1]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 10
+ 8
+ 6