Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Firmament fixture trace corpus

Yuechen Lie3c2c7af72cc
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index 9342d306..b0c6c44b 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -104,6 +104,69 @@ public sealed class AirTraceCommandTests
Assert.Equal(Run("trace", "--case", "top-face-loop-chamfer", "--json").Stdout, Run("trace", "--case", "top-face-loop-chamfer", "--json").Stdout);
}
+
+ [Fact]
+ public void TraceFixtureValidTopFaceLoopChamfer_DefaultsToText()
+ {
+ var (exitCode, output, error) = Run("trace", "--fixture", Fixture("valid/top-face-loop-chamfer.valid.firmfixture"));
+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.False(output.TrimStart().StartsWith("{", StringComparison.Ordinal));
+ Assert.Contains("Fixture", output); Assert.Contains("Expectation: valid", output);
+ Assert.Contains("Actual stage: cir-mirror", output); Assert.Contains("Expectation satisfied: true", output);
+ Assert.Contains("TopFaceLoopChamfer", output); Assert.Contains("FaceBoundaryLoop", output);
+ Assert.Contains("UniformChamfer", output); Assert.Contains("Chamfer faces: 4", output);
+ }
+
+ [Fact]
+ public void TraceFixtureValidTopFaceLoopChamfer_JsonParses()
+ {
+ var (exitCode, output, _) = Run("trace", "--fixture", Fixture("valid/top-face-loop-chamfer.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("fixtureExpectation").GetString());
+ Assert.True(root.GetProperty("expectationSatisfied").GetBoolean());
+ Assert.Equal("top-face-loop-chamfer", root.GetProperty("fixtureCaseName").GetString());
+ Assert.True(root.TryGetProperty("air", out _)); Assert.True(root.TryGetProperty("routeDecision", out _));
+ Assert.True(root.TryGetProperty("brepPlan", out _)); Assert.True(root.TryGetProperty("cirMirror", out _));
+ }
+
+ [Theory]
+ [InlineData("invalid/arbitrary-graph-chamfer.invalid.firmfixture", "arbitrary-graph-unsupported")]
+ [InlineData("invalid/non-uniform-loop-chamfer.invalid.firmfixture", "non-uniform-rule-unsupported")]
+ [InlineData("invalid/loop-fillet-deferred.invalid.firmfixture", "loop-fillet-deferred")]
+ public void TraceFixtureInvalid_StopsBeforeGeometry(string path, string reason)
+ {
+ var (exitCode, output, error) = Run("trace", "--fixture", Fixture(path));
+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.Contains("Expectation: invalid", output); Assert.Contains("Expectation satisfied: true", output);
+ Assert.Contains(reason, output); Assert.Contains("Faces: 0", output);
+ Assert.Contains("STEP smoke: unavailable", output); Assert.Contains("Status: not-requested", output);
+ }
+
+ [Fact]
+ public void TraceFixtureUsageErrors_AreHelpful()
+ {
+ var both = Run("trace", "--case", "top-face-loop-chamfer", "--fixture", Fixture("valid/top-face-loop-chamfer.valid.firmfixture"));
+ Assert.NotEqual(0, both.ExitCode); Assert.Contains("mutually exclusive", both.Stderr);
+ var wrongPath = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N") + ".txt"); File.WriteAllText(wrongPath, "// case: nope");
+ var wrong = Run("trace", "--fixture", wrongPath); Assert.NotEqual(0, wrong.ExitCode); Assert.Contains(".valid.firmfixture", wrong.Stderr);
+ var missing = Run("trace", "--fixture", "fixtures/Firmament/Chamfer/missing.valid.firmfixture"); Assert.NotEqual(0, missing.ExitCode); Assert.Contains("not found", missing.Stderr);
+ var unknownPath = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N") + ".valid.firmfixture"); File.WriteAllText(unknownPath, "// case: nope\n// expected: valid\n");
+ var unknown = Run("trace", "--fixture", unknownPath); Assert.NotEqual(0, unknown.ExitCode); Assert.Contains("Supported fixture cases", unknown.Stderr);
+ }
+
+ [Fact]
+ public void TraceFixtureOutput_IsDeterministic()
+ {
+ var valid = Fixture("valid/top-face-loop-chamfer.valid.firmfixture");
+ var invalid = Fixture("invalid/arbitrary-graph-chamfer.invalid.firmfixture");
+ Assert.Equal(Run("trace", "--fixture", valid, "--json").Stdout, Run("trace", "--fixture", valid, "--json").Stdout);
+ Assert.Equal(Run("trace", "--fixture", invalid, "--json").Stdout, Run("trace", "--fixture", invalid, "--json").Stdout);
+ }
+
+ private static string Fixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Chamfer", relative));
+
private static (int ExitCode, string Stdout, string Stderr) Run(params string[] args)
{
var stdout = new StringWriter(); var stderr = new StringWriter();
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 38106368..94b71add 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -24,8 +24,19 @@ internal sealed record AirTraceReport(
IReadOnlyList<string> KnownLosses,
IReadOnlyList<string> Diagnostics,
IReadOnlyList<string> Guarantees,
- IReadOnlyList<string> UnchangedBehavior);
+ IReadOnlyList<string> UnchangedBehavior,
+ AirTraceFixtureSummary? Fixture = null,
+ string? FixturePath = null,
+ string? FixtureExpectation = null,
+ string? FixtureCaseName = null,
+ string? ExpectedStage = null,
+ string? ActualStageReached = null,
+ string? ExpectedRoute = null,
+ string? ExpectedReason = null,
+ bool? ExpectationSatisfied = null,
+ IReadOnlyList<string>? FixtureDiagnostics = 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 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);
@@ -36,6 +47,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 AirTraceReport Build(string caseName)
{
@@ -57,6 +69,32 @@ internal static class AirTraceReportBuilder
public static string FileStem(string caseName) => $"air-x6-{Normalize(caseName)}-trace";
+ public static AirTraceReport BuildFixture(FirmFixture fixture)
+ {
+ var caseName = fixture.CaseName;
+ var report = caseName switch
+ {
+ "top-face-loop-chamfer" => BuildTopFaceLoopChamfer(),
+ "arbitrary-graph-chamfer" => BuildRejectedFixture(fixture, AirSelectionClass.ArbitraryGraph, AirRuleKind.UniformChamfer),
+ "non-uniform-loop-chamfer" => BuildRejectedFixture(fixture, AirSelectionClass.FaceBoundaryLoop, AirRuleKind.Unsupported),
+ "loop-fillet-deferred" => BuildRejectedFixture(fixture, AirSelectionClass.FaceBoundaryLoop, AirRuleKind.ConstantRadiusFillet),
+ _ => throw new ArgumentOutOfRangeException(nameof(fixture), caseName, "Unsupported fixture case.")
+ };
+
+ var actualStage = caseName == "top-face-loop-chamfer" ? "cir-mirror" : (report.RouteDecision.Recommendation.Contains("deferred", StringComparison.Ordinal) ? "deferred" : "rejected");
+ var expectedReasonSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedReason) || report.RouteDecision.Recommendation.Contains(fixture.ExpectedReason, StringComparison.Ordinal) || report.Diagnostics.Any(d => d.Contains(fixture.ExpectedReason, StringComparison.Ordinal));
+ var expectedRouteSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedRoute) || string.Equals(report.RouteDecision.SelectedRoute, fixture.ExpectedRoute, StringComparison.Ordinal) || string.Equals(report.Air.Route, fixture.ExpectedRoute, StringComparison.Ordinal);
+ var expectationSatisfied = fixture.Expectation == "valid" ? report.Succeeded && expectedRouteSatisfied : !report.RouteDecision.Succeeded && expectedReasonSatisfied;
+ if (!string.IsNullOrWhiteSpace(fixture.ExpectedStage)) expectationSatisfied &= string.Equals(actualStage, fixture.ExpectedStage, StringComparison.Ordinal) || (fixture.ExpectedStage == "route-selection" && (actualStage == "rejected" || actualStage == "deferred"));
+ 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()
+ };
+ }
+
+ public static string FixtureFileStem(FirmFixture fixture) => $"air-x7-{fixture.CaseName}-firmfixture-trace";
+
private static AirTraceReport BuildPrismatic()
{
var lowering = AirPrismaticSectionTransitionWrapper.LowerCanonicalRectangleInset();
@@ -76,6 +114,22 @@ internal static class AirTraceReportBuilder
return Compose("top-face-loop-chamfer", lowering, route, brepPlan, mirror, "PrismaticTopFaceLoopChamferPrototype / PrismaticSectionTransitionEmitter", SpecificGuarantees(["no AirEdgeSweep", "no BrepBoundedChamfer", "no topology graft", "no 3D Boolean", "no coplanar merge", "not four independent single-edge chamfers"]));
}
+
+ private static AirTraceReport BuildRejectedFixture(FirmFixture fixture, AirSelectionClass selectionClass, AirRuleKind ruleKind)
+ {
+ var route = AirRouteSelector.Decide(AirRouteSelector.ForEdgeFinish(fixture.CaseName, selectionClass, ruleKind, "fixture/firmament-contract"));
+ var candidate = route.Candidates.First();
+ var diagnostics = Stable(["air-x7-firmfixture-invalid-route-trace-created", .. route.Diagnostics.Select(d => d.Code)]).ToArray();
+ return new("AIR-X7", "trace", "lowering", "firmfixture", fixture.CaseName, false, route.Recommendation,
+ new("Unsupported", "Unsupported", selectionClass.ToString(), ruleKind.ToString(), "fixture/firmament-contract", fixture.CaseName, fixture.CaseName, "AIR-X7"),
+ new(route.SelectionMode.ToString(), route.SelectedRouteKind?.ToString(), route.Succeeded, route.Recommendation, route.Summary.SelectionClass.ToString(), route.Summary.RuleKind.ToString(), route.Diagnostics.Select(d => d.Code).Order().ToArray()),
+ new("none", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, "none", "none", null, []),
+ new("none", false, "no geometry emitted for expected invalid fixture"),
+ new(false, false, false, false, []),
+ new("not-requested", "none", "none", "Unsupported", selectionClass.ToString(), ruleKind.ToString(), "none", [], [], [], []),
+ [], [], diagnostics, ["invalid fixture stops before geometry emission", "no production route replacement", "no arbitrary graph support"], ["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 Firmament lowering behavior change", "no Boolean behavior change", "no CIR evaluator/tape behavior change", "no new geometry"]);
+ }
+
private static AirTraceReport Compose(string caseName, AirLoweringSummary lowering, AirRouteDecision route, AirBRepPlanResult planResult, AirCirMirrorAdapterResult mirror, string emitterPath, IReadOnlyList<string> guarantees)
{
var plan = planResult.Plan?.Summary ?? planResult.Validation.ExpectedTopologySummary;
@@ -106,8 +160,12 @@ internal static class AirTraceTextRenderer
public static string Render(AirTraceReport r)
{
var b = new StringBuilder();
- b.AppendLine("Aetheris trace — AIR-X6 lowering report");
+ b.AppendLine($"Aetheris trace — {r.Milestone} lowering report");
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("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();
b.AppendLine("BRepPlan"); b.AppendLine($" Plan kind: {r.BRepPlan.PlanKind}"); b.AppendLine($" Vertices: {r.BRepPlan.Vertices}"); b.AppendLine($" Edges: {r.BRepPlan.Edges}"); b.AppendLine($" Faces: {r.BRepPlan.Faces}"); b.AppendLine($" Loops: {r.BRepPlan.Loops}"); b.AppendLine($" Coedges: {r.BRepPlan.Coedges}"); b.AppendLine($" Cap faces: {r.BRepPlan.CapFaces}"); b.AppendLine($" Transition faces: {r.BRepPlan.TransitionFaces}"); b.AppendLine($" Chamfer faces: {r.BRepPlan.ChamferFaces}"); b.AppendLine($" Split policy: {r.BRepPlan.SplitPolicy}"); b.AppendLine($" Bounds: {r.BRepPlan.Bounds}"); b.AppendLine();
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 2219e9b0..9e3e700d 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -24,7 +24,7 @@ public static class CliRunner
private const string AnalyzeSectionUsage = "Usage: aetheris analyze section <file.step> (--xy|--xz|--yz) --offset <value> --json";
private const string AnalyzeVolumeUsage = "Usage: aetheris analyze volume <file.step> [--approximate --resolution <N>] [--json]";
private const string AnalyzeCompareUsage = "Usage: aetheris analyze compare <reference.step> <candidate.step> [--approximate-volume --resolution <N>] [--json]";
- private const string TraceUsage = "Usage: aetheris trace --case <name> [--out-dir <dir>] [--json]";
+ private const string TraceUsage = "Usage: aetheris trace (--case <name>|--fixture <path>) [--out-dir <dir>] [--json]";
private const string CanonUsage = "Usage: aetheris canon <file.step> --out <canonical.step> [--json]";
private const string AsmExecUsage = "Usage: aetheris asm exec <file.firmasm> [--json]";
private const string AsmExportUsage = "Usage: aetheris asm export <file.firmasm> --out <directory> [--json]";
@@ -187,6 +187,7 @@ public static class CliRunner
}
string? caseName = null;
+ string? fixturePath = null;
string? outDir = null;
var json = false;
for (var i = 0; i < args.Length; i++)
@@ -196,6 +197,13 @@ public static class CliRunner
case "--case" when i + 1 < args.Length:
caseName = args[++i];
break;
+ case "--fixture" when i + 1 < args.Length:
+ fixturePath = args[++i];
+ break;
+ case "--fixture":
+ stderr.WriteLine("Trace option --fixture requires a fixture path.");
+ stderr.WriteLine(TraceUsage);
+ return 1;
case "--case":
stderr.WriteLine("Trace option --case requires a case name.");
stderr.WriteLine(TraceUsage);
@@ -229,30 +237,66 @@ public static class CliRunner
}
}
- if (string.IsNullOrWhiteSpace(caseName))
+ if (!string.IsNullOrWhiteSpace(caseName) && !string.IsNullOrWhiteSpace(fixturePath))
{
- stderr.WriteLine("Trace requires --case <name>.");
- stderr.WriteLine("air-x6-missing-case-rejected");
- stderr.WriteLine($"Supported cases: {string.Join(", ", AirTraceReportBuilder.SupportedCases)}");
+ stderr.WriteLine("Trace options --case and --fixture are mutually exclusive.");
+ stderr.WriteLine("air-x7-case-and-fixture-mutually-exclusive");
stderr.WriteLine(TraceUsage);
return 1;
}
- caseName = AirTraceReportBuilder.Normalize(caseName);
- if (!AirTraceReportBuilder.SupportedCases.Contains(caseName, StringComparer.Ordinal))
+ AirTraceReport report;
+ string fileStem;
+ if (!string.IsNullOrWhiteSpace(fixturePath))
{
- stderr.WriteLine($"Unknown trace case '{caseName}'.");
- stderr.WriteLine("air-x6-unknown-case-rejected");
- stderr.WriteLine($"Supported cases: {string.Join(", ", AirTraceReportBuilder.SupportedCases)}");
- return 1;
+ FirmFixture fixture;
+ try { fixture = FirmFixtureLoader.Load(fixturePath); }
+ catch (FirmFixtureException ex) { stderr.WriteLine(ex.Message); stderr.WriteLine(ex.Code); stderr.WriteLine(TraceUsage); return 1; }
+ if (!AirTraceReportBuilder.SupportedFixtureCases.Contains(fixture.CaseName, StringComparer.Ordinal))
+ {
+ stderr.WriteLine($"Unknown Firmament fixture case '{fixture.CaseName}'.");
+ stderr.WriteLine("air-x7-unknown-firmfixture-case");
+ stderr.WriteLine($"Supported fixture cases: {string.Join(", ", AirTraceReportBuilder.SupportedFixtureCases)}");
+ 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
+ {
+ if (string.IsNullOrWhiteSpace(caseName))
+ {
+ stderr.WriteLine("Trace requires one of --case <name> or --fixture <path>.");
+ stderr.WriteLine("air-x7-missing-case-or-fixture");
+ stderr.WriteLine($"Supported cases: {string.Join(", ", AirTraceReportBuilder.SupportedCases)}");
+ stderr.WriteLine(TraceUsage);
+ return 1;
+ }
+
+ caseName = AirTraceReportBuilder.Normalize(caseName);
+ if (!AirTraceReportBuilder.SupportedCases.Contains(caseName, StringComparer.Ordinal))
+ {
+ stderr.WriteLine($"Unknown trace case '{caseName}'.");
+ stderr.WriteLine("air-x6-unknown-case-rejected");
+ stderr.WriteLine($"Supported cases: {string.Join(", ", AirTraceReportBuilder.SupportedCases)}");
+ return 1;
+ }
+ report = AirTraceReportBuilder.Build(caseName);
+ fileStem = AirTraceReportBuilder.FileStem(caseName);
}
- var report = AirTraceReportBuilder.Build(caseName);
+ report = report with { Diagnostics = (json ? report.Diagnostics.Append("air-x7-json-output-requested").Append("air-x7-json-fixture-report-created") : report.Diagnostics.Append("air-x7-default-text-output").Append("air-x7-text-fixture-report-created")).Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal).ToArray() };
var text = json ? JsonSerializer.Serialize(report, JsonOptions) : AirTraceTextRenderer.Render(report);
if (!string.IsNullOrWhiteSpace(outDir))
{
Directory.CreateDirectory(outDir);
- var path = Path.Combine(outDir, AirTraceReportBuilder.FileStem(caseName) + (json ? ".json" : ".txt"));
+ var path = Path.Combine(outDir, fileStem + (json ? ".json" : ".txt"));
File.WriteAllText(path, text);
if (json)
{
@@ -1905,6 +1949,7 @@ public static class CliRunner
stdout.WriteLine(" aetheris analyze model.step");
stdout.WriteLine(" aetheris analyze model.step --json");
stdout.WriteLine(" aetheris trace --case top-face-loop-chamfer");
+ stdout.WriteLine(" aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture");
stdout.WriteLine(" aetheris trace --case prismatic-section-transition --json");
stdout.WriteLine(" aetheris canon input.step --out canonical.step --json");
stdout.WriteLine(" aetheris asm exec assembly.firmasm --json");
@@ -1941,12 +1986,14 @@ public static class CliRunner
stdout.WriteLine();
stdout.WriteLine("Scope:");
stdout.WriteLine(" trace reports compiler lowering; analyze reports geometric analysis of existing STEP/BRep artifacts.");
- stdout.WriteLine(" Supported cases: prismatic-section-transition, top-face-loop-chamfer.");
+ stdout.WriteLine(" Supported cases: prismatic-section-transition, top-face-loop-chamfer");
+ stdout.WriteLine(" Supported fixture extensions: .valid.firmfixture, .invalid.firmfixture.");
stdout.WriteLine(" Optional aliases: prismatic, loop-chamfer.");
stdout.WriteLine(" No STEP input is accepted by trace.");
stdout.WriteLine();
stdout.WriteLine("Options:");
- stdout.WriteLine(" --case <name> Required built-in lowering case name.");
+ stdout.WriteLine(" --case <name> Built-in lowering case name.");
+ stdout.WriteLine(" --fixture <path> Firmament fixture trace input (.valid/.invalid.firmfixture).");
stdout.WriteLine(" --json Emit deterministic machine-readable JSON (default output is human-readable text).");
stdout.WriteLine(" --out-dir <dir> Write the trace report artifact into a directory.");
stdout.WriteLine(" -h, --help Show this help.");
@@ -1954,7 +2001,8 @@ public static class CliRunner
stdout.WriteLine("Examples:");
stdout.WriteLine(" aetheris trace --case prismatic-section-transition");
stdout.WriteLine(" aetheris trace --case top-face-loop-chamfer --json");
- stdout.WriteLine(" aetheris trace --case top-face-loop-chamfer --out-dir artifacts/air-x6");
+ stdout.WriteLine(" aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --json");
+ stdout.WriteLine(" aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --out-dir artifacts/air-x7");
}
private static void WriteAnalyzeHelp(TextWriter stdout)
diff --git a/Aetheris.CLI/FirmFixture.cs b/Aetheris.CLI/FirmFixture.cs
new file mode 100644
index 00000000..266b4beb
--- /dev/null
+++ b/Aetheris.CLI/FirmFixture.cs
@@ -0,0 +1,64 @@
+namespace Aetheris.CLI;
+
+internal sealed record FirmFixture(
+ string Path,
+ string CaseName,
+ string Expectation,
+ string? ExpectedStage,
+ string? ExpectedRoute,
+ string? ExpectedReason,
+ IReadOnlyDictionary<string, string> Metadata,
+ IReadOnlyList<string> Diagnostics);
+
+internal static class FirmFixtureLoader
+{
+ public static readonly string[] ValidExtensions = [".valid.firmfixture", ".invalid.firmfixture"];
+
+ public static FirmFixture Load(string path)
+ {
+ var normalized = path.Replace('\\', '/');
+ if (!File.Exists(path)) throw new FirmFixtureException("air-x7-fixture-file-not-found", $"Firmament fixture file was not found: {path}");
+ var expectation = ClassifyExpectation(path);
+ var lines = File.ReadAllLines(path);
+ var metadata = new SortedDictionary<string, string>(StringComparer.Ordinal);
+ foreach (var raw in lines)
+ {
+ var line = raw.Trim();
+ if (line.Length == 0) continue;
+ if (!line.StartsWith("//", StringComparison.Ordinal)) break;
+ var body = line[2..].Trim();
+ var colon = body.IndexOf(':');
+ if (colon <= 0) continue;
+ var key = body[..colon].Trim();
+ var value = body[(colon + 1)..].Trim();
+ if (key.Length == 0 || value.Length == 0) throw new FirmFixtureException("air-x7-firmfixture-metadata-invalid", $"Invalid fixture metadata line: {raw}");
+ metadata[key] = value;
+ }
+
+ if (!metadata.TryGetValue("case", out var caseName) || string.IsNullOrWhiteSpace(caseName))
+ throw new FirmFixtureException("air-x7-firmfixture-metadata-invalid", "Firmament fixture requires leading metadata `// case: <name>`.");
+ 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 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"
+ }.Order(StringComparer.Ordinal).ToArray();
+ return new(normalized, caseName, expectation, metadata.GetValueOrDefault("expected-stage"), metadata.GetValueOrDefault("expected-route"), metadata.GetValueOrDefault("expected-reason"), metadata, diagnostics);
+ }
+
+ public static string ClassifyExpectation(string path)
+ {
+ if (path.EndsWith(".valid.firmfixture", StringComparison.Ordinal)) return "valid";
+ if (path.EndsWith(".invalid.firmfixture", StringComparison.Ordinal)) return "invalid";
+ throw new FirmFixtureException("air-x7-invalid-firmfixture-extension", "Trace fixtures must use `.valid.firmfixture` or `.invalid.firmfixture`.");
+ }
+}
+
+internal sealed class FirmFixtureException(string code, string message) : Exception(message)
+{
+ public string Code { get; } = code;
+}
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index 3b2cc351..2d2ed13c 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -761,3 +761,7 @@ AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for gene
## AIR-X6 trace status
AIR-X6 adds `aetheris trace` as a top-level compiler-lowering report command for built-in AIR cases. The command reports AIR, route selection, BRepPlan, emitted BRep/STEP smoke, CIR mirror admission, diagnostics, guarantees, and known losses without making STEP serialization or CIR evaluation topology authority.
+
+## 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.
diff --git a/docs/air-x2-route-selection-and-admissibility.md b/docs/air-x2-route-selection-and-admissibility.md
index 3c6c234f..8997c6aa 100644
--- a/docs/air-x2-route-selection-and-admissibility.md
+++ b/docs/air-x2-route-selection-and-admissibility.md
@@ -77,3 +77,7 @@ The AIR-X2 switch/match-selected `TopFaceLoopChamferPrismatic` route now has AIR
## AIR-X6 trace reporting
`aetheris trace` reports AIR-X2 route decisions for supported built-in cases, including Direct prismatic selection and SwitchMatch top-face loop chamfer selection. This is read-only reporting and does not alter JudgmentUtility, admissibility, tie-breaking, or rejection semantics.
+
+## AIR-X7 invalid fixture trace note
+
+AIR-X7 reuses AIR-X2 route-selection/admissibility decisions for invalid Firmament fixture traces. Arbitrary graph chamfers, non-uniform loop chamfers, and deferred loop fillets stop at route-selection/rejected/deferred stages with stable reason codes and no geometry emission.
diff --git a/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md b/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
index 1f323919..396d4395 100644
--- a/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
+++ b/docs/air-x4-brep-plan-top-face-loop-chamfer-roles.md
@@ -103,3 +103,7 @@ AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for gene
## AIR-X6 trace reporting
`aetheris trace` reports the AIR-X4 top-face loop chamfer role overlay, including Class B face-boundary-loop provenance, UniformChamfer rule provenance, and the four chamfer-face semantic roles. This preserves the doctrine that the case is not four independent single-edge chamfers.
+
+## AIR-X7 fixture note
+
+The AIR-X7 valid Chamfer corpus includes `fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture`, which traces the Class B top-face boundary-loop uniform chamfer through the existing `TopFaceLoopChamferPrismatic` route and preserves the AIR-X4 BRepPlan chamfer-face role count of four.
diff --git a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
index b12d4555..b633687d 100644
--- a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
+++ b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
@@ -97,3 +97,7 @@ Implementation showed that AIR-X3/X4 already carry useful BRepPlan topology-role
## AIR-X6 trace reporting
`aetheris trace` reports AIR-X5 CIR mirror admission, backend, capabilities, provenance, and losses. CIR remains an evaluation side-channel and does not gain face identity, loop identity, topology parity, chamfer-face identity, or BRepPlan role parity authority.
+
+## AIR-X7 fixture note
+
+The AIR-X7 valid top-face loop chamfer fixture reaches the `cir-mirror` trace stage by reusing the existing admitted AIR-X5 top-face loop chamfer mirror envelope. The fixture does not make CIR a topology authority.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
index 67a0465f..0b6b5132 100644
--- a/docs/air-x6-aetheris-trace-lowering-report-cli.md
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -138,3 +138,7 @@ Focused AIR-X6 validation used CLI help, text output, JSON parsing/determinism,
## Recommended next milestone
Recommended AIR-X7: **unified trace artifact corpus / golden summaries**. AIR-X6 showed that deterministic reports can be composed from existing AIR-X1 through AIR-X5 summary surfaces without replacing production behavior; golden trace artifacts would lock the text/JSON contracts before adding source-file trace input.
+
+## 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.
diff --git a/docs/air-x7-firmament-fixture-trace-corpus.md b/docs/air-x7-firmament-fixture-trace-corpus.md
new file mode 100644
index 00000000..d1c21f21
--- /dev/null
+++ b/docs/air-x7-firmament-fixture-trace-corpus.md
@@ -0,0 +1,101 @@
+# AIR-X7 — Firmament fixture trace corpus
+
+## Purpose and scope
+
+AIR-X7 introduces source-level Firmament fixture trace inputs for `aetheris trace`. A `.firmfixture` is a language/lowering contract fixture: valid fixtures describe accepted Firmament feature programs, invalid fixtures describe rejected or deferred programs, and trace reports record the lowering stage reached and why.
+
+AIR-X7 extends AIR-X6 without changing production geometry, route behavior, STEP import/export, BRep topology, CIR evaluator/tape behavior, Boolean behavior, or Firmament grammar.
+
+## Relationship to AIR-X6 trace
+
+AIR-X6 added built-in trace cases. AIR-X7 keeps those cases and adds fixture input:
+
+```bash
+aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture
+aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --json
+aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --out-dir artifacts/air-x7
+aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --out-dir artifacts/air-x7 --json
+```
+
+Text output remains the default. JSON is emitted only when `--json` is present. `--case` and `--fixture` are mutually exclusive, and one of them is required.
+
+## Trace vs analyze
+
+`aetheris trace` is the compiler lowering flight recorder for AIR/Firmament-derived inputs. `aetheris analyze` is geometric forensics for existing STEP/BRep artifacts. AIR-X7 deliberately does not accept arbitrary STEP files in `trace`; STEP remains the job of `analyze`.
+
+## Fixture convention and directory structure
+
+AIR-X7 adds two source fixture extensions:
+
+- `*.valid.firmfixture` for accepted source/lowering contracts.
+- `*.invalid.firmfixture` for expected rejection or deferral contracts.
+
+The first corpus is committed under:
+
+```text
+fixtures/Firmament/Chamfer/
+ valid/top-face-loop-chamfer.valid.firmfixture
+ invalid/arbitrary-graph-chamfer.invalid.firmfixture
+ invalid/non-uniform-loop-chamfer.invalid.firmfixture
+ invalid/loop-fillet-deferred.invalid.firmfixture
+```
+
+## Fixture metadata format
+
+A fixture may start with leading `// key: value` metadata comments. AIR-X7 recognizes:
+
+- `case`
+- `expected`
+- `expected-stage`
+- `expected-route`
+- `expected-reason`
+- `description`
+
+The extension is the source of truth for valid/invalid expectation. If `// expected:` conflicts with the extension, the loader rejects the fixture.
+
+## Fixture source text role
+
+The current first-scope implementation treats fixture bodies as Firmament-like language-contract text plus metadata-driven trace mapping. It does **not** expand production Firmament syntax to make these examples parse. As Firmament syntax matures, these same `.firmfixture` files should become parser-backed frontend/lowering fixtures.
+
+## Lowering stage model
+
+Trace reports include fixture fields such as `inputKind = firmfixture`, fixture path, expectation, case name, expected stage, actual stage reached, expected route/reason, expectation satisfaction, and deterministic fixture diagnostics.
+
+The stage vocabulary includes `fixture-loaded`, `parsed`, `bound`, `feature-air`, `route-selection`, `constructive-air`, `brep-plan`, `emitted-brep`, `step-smoke`, `cir-mirror`, `rejected`, `deferred`, and `unsupported`. AIR-X7 derives the first corpus stages from fixture metadata and existing AIR-X6/AIR-X2 trace results.
+
+## Valid fixture behavior
+
+`top-face-loop-chamfer.valid.firmfixture` maps to the existing top-face loop chamfer trace. It reaches `cir-mirror`, selects `TopFaceLoopChamferPrismatic` by `SwitchMatch`, reports AIR node `TopFaceLoopChamfer`, selection class `FaceBoundaryLoop`, rule `UniformChamfer`, and BRepPlan chamfer face count `4`.
+
+## Invalid and deferred fixture behavior
+
+Invalid fixtures succeed at the CLI level when the expected invalid/deferred behavior is explained deterministically. They stop at route selection/rejected/deferred stages and do not emit geometry, BRepPlan topology, STEP smoke, or CIR mirror success.
+
+The first invalid corpus maps to existing AIR-X2 admissibility diagnostics:
+
+- arbitrary graph chamfer: `arbitrary-graph-unsupported`;
+- non-uniform loop chamfer: `non-uniform-rule-unsupported`;
+- loop fillet: `loop-fillet-deferred-until-single-edge-fillet-evidence`.
+
+CLI misuse, missing fixture files, invalid extensions, unknown fixture cases, and expectation mismatches return nonzero.
+
+## Golden report policy
+
+AIR-X7 keeps JSON deterministic enough for normalized comparison in tests. Text is human/LLM-facing, so tests assert key sections and phrases rather than exact full text. Stable generated golden report files are deferred; the committed source `.firmfixture` corpus is the authoritative first artifact.
+
+## Non-goals
+
+AIR-X7 does not change production Firmament syntax or behavior, production routes, route-selection/JudgmentUtility behavior, geometry implementation, BRepPlan semantics, CIR evaluator/tape behavior, STEP exporter/importer behavior, BRep topology behavior, production analyzer behavior, Boolean behavior, AirEdgeSweep behavior, BrepBoundedChamfer/BrepBoundedFillet behavior, chamfer/fillet/shell geometry, arbitrary graph support, import/recovery, triangle migration, or NURBS/freeform behavior.
+
+## Tests run
+
+- `dotnet run --project Aetheris.CLI -f net10.0 -- --help`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --help`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture --json`
+- `dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Chamfer/invalid/arbitrary-graph-chamfer.invalid.firmfixture`
+- Focused .NET CLI/core/Firmament/FrictionLab test filters for Trace/Fixture/AIR/CIR/BRepPlan/etc.
+
+## 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.
diff --git a/fixtures/Firmament/Chamfer/invalid/arbitrary-graph-chamfer.invalid.firmfixture b/fixtures/Firmament/Chamfer/invalid/arbitrary-graph-chamfer.invalid.firmfixture
new file mode 100644
index 00000000..a7b39555
--- /dev/null
+++ b/fixtures/Firmament/Chamfer/invalid/arbitrary-graph-chamfer.invalid.firmfixture
@@ -0,0 +1,8 @@
+// case: arbitrary-graph-chamfer
+// expected: invalid
+// expected-stage: route-selection
+// expected-reason: arbitrary-graph-unsupported
+// description: Arbitrary graph chamfer remains unsupported and must not emit geometry.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+chamfer graph(box.edges[0], box.edges[3], box.edges[7]) distance 1;
diff --git a/fixtures/Firmament/Chamfer/invalid/loop-fillet-deferred.invalid.firmfixture b/fixtures/Firmament/Chamfer/invalid/loop-fillet-deferred.invalid.firmfixture
new file mode 100644
index 00000000..a1b3e025
--- /dev/null
+++ b/fixtures/Firmament/Chamfer/invalid/loop-fillet-deferred.invalid.firmfixture
@@ -0,0 +1,8 @@
+// case: loop-fillet-deferred
+// expected: invalid
+// expected-stage: route-selection
+// expected-reason: loop-fillet-deferred-until-single-edge-fillet-evidence
+// description: Loop fillet is deferred until single-edge and corner fillet evidence exists.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+fillet box.top.outerLoop radius 1;
diff --git a/fixtures/Firmament/Chamfer/invalid/non-uniform-loop-chamfer.invalid.firmfixture b/fixtures/Firmament/Chamfer/invalid/non-uniform-loop-chamfer.invalid.firmfixture
new file mode 100644
index 00000000..2dae0f41
--- /dev/null
+++ b/fixtures/Firmament/Chamfer/invalid/non-uniform-loop-chamfer.invalid.firmfixture
@@ -0,0 +1,8 @@
+// case: non-uniform-loop-chamfer
+// expected: invalid
+// expected-stage: route-selection
+// expected-reason: non-uniform-rule-unsupported
+// description: Non-uniform loop chamfer rule is rejected before geometry emission.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+chamfer box.top.outerLoop distances [1, 1.5, 1, 1.5];
diff --git a/fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture b/fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture
new file mode 100644
index 00000000..a3104392
--- /dev/null
+++ b/fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture
@@ -0,0 +1,8 @@
+// case: top-face-loop-chamfer
+// expected: valid
+// expected-stage: cir-mirror
+// expected-route: TopFaceLoopChamferPrismatic
+// description: Class B top-face outer-loop uniform chamfer fixture contract.
+
+solid box = Box(width: 10, depth: 8, height: 6);
+chamfer box.top.outerLoop distance 1;