Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add AIR-X6 trace lowering CLI

Yuechen Li7574317e135a
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
new file mode 100644
index 00000000..9342d306
--- /dev/null
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -0,0 +1,113 @@
+using System.Text.Json;
+
+namespace Aetheris.CLI.Tests;
+
+public sealed class AirTraceCommandTests
+{
+ [Fact]
+ public void TraceHelp_IsDiscoverable()
+ {
+ var stdout = new StringWriter(); var stderr = new StringWriter();
+ Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["--help"], stdout, stderr));
+ Assert.Contains("trace", stdout.ToString(), StringComparison.Ordinal);
+
+ stdout = new StringWriter(); stderr = new StringWriter();
+ Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["trace", "--help"], stdout, stderr));
+ var text = stdout.ToString();
+ Assert.Contains("default output is human-readable text", text, StringComparison.Ordinal);
+ Assert.Contains("--json", text, StringComparison.Ordinal);
+ Assert.Contains("analyze", text, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void TracePrismatic_DefaultsToText()
+ {
+ var (exitCode, output, error) = Run("trace", "--case", "prismatic-section-transition");
+ Assert.Equal(0, exitCode); Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.False(output.TrimStart().StartsWith("{", StringComparison.Ordinal));
+ Assert.Contains("Aetheris trace", output); Assert.Contains("Case: prismatic-section-transition", output);
+ Assert.Contains("Trace kind: lowering", output); Assert.Contains("Route decision", output);
+ Assert.Contains("BRepPlan", output); Assert.Contains("CIR mirror", output); Assert.Contains("STEP smoke", output);
+ Assert.Contains("no production route replacement", output);
+ }
+
+ [Fact]
+ public void TraceTopFaceLoopChamfer_DefaultsToText()
+ {
+ var (exitCode, output, _) = Run("trace", "--case", "top-face-loop-chamfer");
+ Assert.Equal(0, exitCode); Assert.False(output.TrimStart().StartsWith("{", StringComparison.Ordinal));
+ Assert.Contains("TopFaceLoopChamfer", output); Assert.Contains("FaceBoundaryLoop", output);
+ Assert.Contains("UniformChamfer", output); Assert.Contains("SwitchMatch", output);
+ Assert.Contains("Chamfer faces: 4", output); Assert.Contains("not four independent single-edge chamfers", output);
+ Assert.Contains("no AirEdgeSweep", output); Assert.Contains("no BrepBoundedChamfer", output);
+ }
+
+ [Fact]
+ public void TracePrismatic_JsonOutput_IsDeterministicAndParses()
+ {
+ var (exitCode, output, _) = Run("trace", "--case", "prismatic-section-transition", "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.Equal("trace", root.GetProperty("command").GetString());
+ Assert.Equal("lowering", root.GetProperty("traceKind").GetString());
+ Assert.Equal("built-in-case", root.GetProperty("inputKind").GetString());
+ Assert.Equal("prismatic-section-transition", root.GetProperty("caseName").GetString());
+ Assert.Equal("Direct", root.GetProperty("routeDecision").GetProperty("mode").GetString());
+ var plan = root.GetProperty("brepPlan");
+ Assert.Equal(12, plan.GetProperty("vertices").GetInt32()); Assert.Equal(20, plan.GetProperty("edges").GetInt32());
+ Assert.Equal(10, plan.GetProperty("faces").GetInt32()); Assert.Equal(40, plan.GetProperty("coedges").GetInt32());
+ Assert.True(root.TryGetProperty("cirMirror", out _));
+ Assert.Contains("topology-parity", root.GetProperty("knownLosses").EnumerateArray().Select(x => x.GetString()));
+ }
+
+ [Fact]
+ public void TraceTopFaceLoopChamfer_JsonOutput_IsDeterministicAndParses()
+ {
+ var (exitCode, output, _) = Run("trace", "--case", "top-face-loop-chamfer", "--json");
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(output); var root = doc.RootElement;
+ Assert.Equal("top-face-loop-chamfer", root.GetProperty("caseName").GetString());
+ Assert.Equal("FaceBoundaryLoop", root.GetProperty("air").GetProperty("selectionClass").GetString());
+ Assert.Equal("UniformChamfer", root.GetProperty("air").GetProperty("rule").GetString());
+ Assert.Equal("SwitchMatch", root.GetProperty("routeDecision").GetProperty("mode").GetString());
+ Assert.Equal(4, root.GetProperty("brepPlan").GetProperty("chamferFaces").GetInt32());
+ var losses = root.GetProperty("cirMirror").GetProperty("knownLosses").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.Contains("chamfer-face-identity", losses); Assert.Contains("brep-plan-role-parity", losses);
+ Assert.Contains("not four independent single-edge chamfers", root.GetProperty("guarantees").EnumerateArray().Select(x => x.GetString()));
+ }
+
+ [Fact]
+ public void TraceOutDir_WritesTextOrJsonReport()
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ var (textExit, textOut, _) = Run("trace", "--case", "top-face-loop-chamfer", "--out-dir", dir);
+ Assert.Equal(0, textExit); Assert.Contains("Trace report written:", textOut);
+ var textPath = Path.Combine(dir, "air-x6-top-face-loop-chamfer-trace.txt"); Assert.True(File.Exists(textPath));
+ Assert.Contains("Aetheris trace", File.ReadAllText(textPath));
+ var (jsonExit, jsonOut, _) = Run("trace", "--case", "top-face-loop-chamfer", "--out-dir", dir, "--json");
+ Assert.Equal(0, jsonExit); JsonDocument.Parse(jsonOut).Dispose();
+ Assert.True(File.Exists(Path.Combine(dir, "air-x6-top-face-loop-chamfer-trace.json")));
+ }
+
+ [Fact]
+ public void TraceInvalidUsage_IsHelpful()
+ {
+ var missing = Run("trace"); Assert.NotEqual(0, missing.ExitCode); Assert.Contains("--case", missing.Stderr); Assert.Contains("Supported cases", missing.Stderr);
+ var unknown = Run("trace", "--case", "nope"); Assert.NotEqual(0, unknown.ExitCode); Assert.Contains("Supported cases", unknown.Stderr);
+ var step = Run("trace", "some.step"); Assert.NotEqual(0, step.ExitCode); Assert.Contains("trace does not analyze STEP files", step.Stderr); Assert.Contains("aetheris analyze", step.Stderr);
+ }
+
+ [Fact]
+ public void TraceOutput_IsDeterministic()
+ {
+ Assert.Equal(Run("trace", "--case", "prismatic-section-transition", "--json").Stdout, Run("trace", "--case", "prismatic-section-transition", "--json").Stdout);
+ Assert.Equal(Run("trace", "--case", "top-face-loop-chamfer", "--json").Stdout, Run("trace", "--case", "top-face-loop-chamfer", "--json").Stdout);
+ }
+
+ private static (int ExitCode, string Stdout, string Stderr) Run(params string[] args)
+ {
+ var stdout = new StringWriter(); var stderr = new StringWriter();
+ var exitCode = Aetheris.CLI.CliRunner.Run(args, stdout, stderr);
+ return (exitCode, stdout.ToString(), stderr.ToString());
+ }
+}
diff --git a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs b/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
index aa26874a..6f981be6 100644
--- a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
+++ b/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
@@ -19,10 +19,11 @@ public sealed class CliHelpAndUsageTests
Assert.Equal(0, exitCode);
Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()));
var text = stdout.ToString();
- Assert.Contains("Usage: aetheris <build|analyze|canon|asm|experimental>", text, StringComparison.Ordinal);
+ Assert.Contains("Usage: aetheris <build|analyze|trace|canon|asm|experimental>", text, StringComparison.Ordinal);
Assert.Contains("Commands:", text, StringComparison.Ordinal);
Assert.Contains("build", text, StringComparison.Ordinal);
Assert.Contains("analyze", text, StringComparison.Ordinal);
+ Assert.Contains("trace", text, StringComparison.Ordinal);
Assert.Contains("canon", text, StringComparison.Ordinal);
Assert.Contains("asm", text, StringComparison.Ordinal);
Assert.Contains("experimental", text, StringComparison.Ordinal);
@@ -36,6 +37,7 @@ public sealed class CliHelpAndUsageTests
[InlineData("analyze")]
[InlineData("analyze", "map")]
[InlineData("analyze", "section")]
+ [InlineData("trace")]
[InlineData("experimental")]
[InlineData("experimental", "airchamfer-cube")]
[InlineData("experimental", "airchamfer-corpus")]
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
new file mode 100644
index 00000000..38106368
--- /dev/null
+++ b/Aetheris.CLI/AirTrace.cs
@@ -0,0 +1,120 @@
+using System.Text;
+using System.Text.Json.Serialization;
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Air.BRepPlan;
+using Aetheris.Kernel.Core.Brep.Prismatic;
+
+namespace Aetheris.CLI;
+
+internal sealed record AirTraceReport(
+ string Milestone,
+ string Command,
+ string TraceKind,
+ string InputKind,
+ string CaseName,
+ bool Succeeded,
+ string Recommendation,
+ AirTraceAirSummary Air,
+ AirTraceRouteDecisionSummary RouteDecision,
+ [property: JsonPropertyName("brepPlan")] AirTraceBRepPlanSummary BRepPlan,
+ AirTraceEmissionSummary Emission,
+ AirTraceStepSmokeSummary StepSmoke,
+ AirTraceCirMirrorSummary CirMirror,
+ IReadOnlyList<string> Capabilities,
+ IReadOnlyList<string> KnownLosses,
+ IReadOnlyList<string> Diagnostics,
+ IReadOnlyList<string> Guarantees,
+ IReadOnlyList<string> UnchangedBehavior);
+
+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);
+internal sealed record AirTraceEmissionSummary(string ExistingEmitterPath, bool Succeeded, string Recommendation);
+internal sealed record AirTraceStepSmokeSummary(bool WasChecked, bool Succeeded, bool RequiredMarkersPresent, bool ForbiddenMarkersAbsent, IReadOnlyList<string> Diagnostics);
+internal sealed record AirTraceCirMirrorSummary(string Status, string Backend, string SourceNode, string SourceKind, string SelectionClass, string Rule, string MirrorBuilderRoute, IReadOnlyList<string> Capabilities, IReadOnlyList<string> KnownLosses, IReadOnlyList<string> Provenance, IReadOnlyList<string> Diagnostics);
+
+internal static class AirTraceReportBuilder
+{
+ public static readonly string[] SupportedCases = ["prismatic-section-transition", "top-face-loop-chamfer"];
+
+ public static AirTraceReport Build(string caseName)
+ {
+ caseName = Normalize(caseName);
+ return caseName switch
+ {
+ "prismatic-section-transition" => BuildPrismatic(),
+ "top-face-loop-chamfer" => BuildTopFaceLoopChamfer(),
+ _ => throw new ArgumentOutOfRangeException(nameof(caseName), caseName, "Unsupported trace case.")
+ };
+ }
+
+ public static string Normalize(string value) => value switch
+ {
+ "prismatic" => "prismatic-section-transition",
+ "loop-chamfer" => "top-face-loop-chamfer",
+ _ => value
+ };
+
+ public static string FileStem(string caseName) => $"air-x6-{Normalize(caseName)}-trace";
+
+ private static AirTraceReport BuildPrismatic()
+ {
+ var lowering = AirPrismaticSectionTransitionWrapper.LowerCanonicalRectangleInset();
+ var route = AirRouteSelector.Decide(AirRouteSelector.ForPrismaticSectionTransition());
+ var brepPlan = AirPrismaticSectionTransitionBRepPlanner.Plan(new PrismaticSectionTransitionRequest(AirPrismaticSectionTransitionWrapper.CanonicalSections(), PrismaticCorrespondenceMap.Identity(4), new PrismaticSectionTransitionOptions(RunStepSmoke: true, TraceLabel: "air-x6-prismatic-section-transition-trace")));
+ var mirror = AirCirMirrorAdapter.AdmitCanonicalPrismaticSectionTransition();
+ return Compose("prismatic-section-transition", lowering, route, brepPlan, mirror, "PrismaticSectionTransitionEmitter", SpecificGuarantees([]));
+ }
+
+ private static AirTraceReport BuildTopFaceLoopChamfer()
+ {
+ var lowering = AirTopFaceLoopChamferWrapper.LowerCanonicalTopFaceLoopChamfer();
+ var route = AirRouteSelector.Decide(AirRouteSelector.ForEdgeFinish("canonical-top-face-loop-chamfer", AirSelectionClass.FaceBoundaryLoop, AirRuleKind.UniformChamfer, "generated/history-known/top-face"));
+ var request = new PrismaticTopFaceLoopChamferRequest(10, 8, 6, 1, ExportStep: true);
+ var brepPlan = AirTopFaceLoopChamferBRepPlanner.Plan(request);
+ var mirror = AirCirMirrorAdapter.AdmitCanonicalTopFaceLoopChamfer();
+ 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 Compose(string caseName, AirLoweringSummary lowering, AirRouteDecision route, AirBRepPlanResult planResult, AirCirMirrorAdapterResult mirror, string emitterPath, IReadOnlyList<string> guarantees)
+ {
+ var plan = planResult.Plan?.Summary ?? planResult.Validation.ExpectedTopologySummary;
+ var capabilities = SplitFlags(mirror.Summary.Capabilities).ToArray();
+ var losses = SplitFlags(mirror.Summary.KnownLosses).ToArray();
+ var diagnostics = Stable([
+ "air-x6-trace-command-started", $"air-x6-trace-case-selected:{caseName}", "air-x6-air-summary-created", "air-x6-route-decision-summary-created", "air-x6-brep-plan-summary-created", "air-x6-emission-summary-created", "air-x6-step-smoke-summary-created", "air-x6-cir-mirror-summary-created", "air-x6-lowering-report-created", "air-x6-trace-not-analyze", "air-x6-no-production-route-replacement", "air-x6-no-production-analyzer-change", "air-x6-no-step-exporter-change", "air-x6-no-brep-topology-change",
+ .. lowering.Diagnostics.Select(d => d.Code), .. route.Diagnostics.Select(d => d.Code), .. plan.Diagnostics.Select(d => d.Code), .. mirror.Summary.Diagnostics
+ ]).ToArray();
+ return new("AIR-X6", "trace", "lowering", "built-in-case", caseName, lowering.Succeeded && route.Succeeded && planResult.Succeeded, lowering.Recommendation,
+ new(lowering.NodeKind.ToString(), lowering.RouteKind.ToString(), lowering.Provenance.SelectionClass.ToString(), lowering.Provenance.RuleKind.ToString(), lowering.Provenance.ConstructionHistoryKind, lowering.Provenance.FeatureName, lowering.Provenance.FeatureId, lowering.Provenance.Milestone),
+ 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(plan.PlanKind.ToString(), plan.VertexCount, plan.CurveCount, plan.EdgeCount, plan.FaceCount, plan.LoopCount, plan.CoedgeCount, plan.SurfaceCount, plan.CapFaceCount, plan.TransitionFaceCount, plan.ChamferFaceCount, plan.SideFaceCount, plan.SplitPolicy, plan.Bounds, plan.FeatureContext?.RouteSelectionMode, plan.Diagnostics.Select(d => d.Code).Order().ToArray()),
+ new(emitterPath, lowering.Succeeded, lowering.Recommendation),
+ new(lowering.StepSmokeSummary.WasChecked, lowering.StepSmokeSummary.Succeeded, lowering.StepSmokeSummary.RequiredMarkersPresent, lowering.StepSmokeSummary.ForbiddenMarkersAbsent, lowering.StepSmokeSummary.Diagnostics.Select(d => d.Code).Order().ToArray()),
+ new(mirror.Summary.StatusText, mirror.Summary.MirrorBackend, mirror.Summary.SourceNodeId, mirror.Summary.SourceKind.ToString(), mirror.Summary.SelectionClass.ToString(), mirror.Summary.RuleKind.ToString(), mirror.Summary.MirrorBuilderRoute, capabilities, losses, mirror.Summary.Provenance, mirror.Summary.Diagnostics),
+ capabilities, losses, diagnostics, guarantees, ["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 IReadOnlyList<string> SpecificGuarantees(IEnumerable<string> extra) => Stable(["no production route replacement", "no default production CLI behavior change outside adding trace command", "no production analyzer behavior change", "no STEP exporter/importer change", "no BRep topology behavior change", "no Boolean behavior change", "no Firmament lowering behavior change", "no CIR evaluator/tape behavior change", "no new geometry", "no import/recovery", "no arbitrary graph support", .. extra]).ToArray();
+ private static IEnumerable<string> Stable(IEnumerable<string> x) => x.Distinct(StringComparer.Ordinal).OrderBy(s => s, StringComparer.Ordinal);
+ private static IEnumerable<string> SplitFlags<T>(T value) where T : Enum => Enum.GetValues(typeof(T)).Cast<T>().Where(v => Convert.ToInt64(v) != 0 && value.HasFlag(v)).Select(v => Kebab(v.ToString())).OrderBy(x => x, StringComparer.Ordinal);
+ private static string Kebab(string value) => string.Concat(value.Replace("BRep", "Brep", StringComparison.Ordinal).SelectMany((c, i) => char.IsUpper(c) && i > 0 ? new[] { '-', char.ToLowerInvariant(c) } : new[] { char.ToLowerInvariant(c) }));
+}
+
+internal static class AirTraceTextRenderer
+{
+ public static string Render(AirTraceReport r)
+ {
+ var b = new StringBuilder();
+ b.AppendLine("Aetheris trace — AIR-X6 lowering report");
+ b.AppendLine($"Case: {r.CaseName}"); b.AppendLine($"Trace kind: {r.TraceKind}"); b.AppendLine($"Input kind: {r.InputKind}"); 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();
+ b.AppendLine("Emission / STEP"); b.AppendLine($" Existing emitter path: {r.Emission.ExistingEmitterPath}"); b.AppendLine($" STEP smoke: {(r.StepSmoke.Succeeded ? "succeeded" : "unavailable")}"); b.AppendLine();
+ b.AppendLine("CIR mirror"); b.AppendLine($" Status: {r.CirMirror.Status}"); b.AppendLine($" Backend: {r.CirMirror.Backend}"); b.AppendLine($" Capabilities: {string.Join(", ", r.CirMirror.Capabilities)}"); b.AppendLine($" Known losses: {string.Join(", ", r.CirMirror.KnownLosses.Select(x => "no " + x.Replace('-', ' ')))}"); b.AppendLine();
+ b.AppendLine("Guarantees"); foreach (var g in r.Guarantees) b.AppendLine($" - {g}"); b.AppendLine();
+ b.AppendLine("Diagnostics"); foreach (var d in r.Diagnostics) b.AppendLine($" - {d}");
+ return b.ToString();
+ }
+}
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index eb6de065..2219e9b0 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -17,13 +17,14 @@ public static class CliRunner
string? Error,
string? Classification = null,
int? RigidRootCount = null);
- private const string TopLevelUsage = "Usage: aetheris <build|analyze|canon|asm|experimental> <path> [options]";
+ private const string TopLevelUsage = "Usage: aetheris <build|analyze|trace|canon|asm|experimental> <path> [options]";
private const string BuildUsage = "Usage: aetheris build <file.firmament> [--out <path>] [--json]";
private const string AnalyzeUsage = "Usage: aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json]";
private const string AnalyzeMapUsage = "Usage: aetheris analyze map <file.step> (--top|--bottom|--front|--back|--left|--right) --rows <N> --cols <N> --json";
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 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]";
@@ -72,6 +73,7 @@ public static class CliRunner
{
"build" => RunBuild(args.Skip(1).ToArray(), stdout, stderr),
"analyze" => RunAnalyze(args.Skip(1).ToArray(), stdout, stderr),
+ "trace" => RunTrace(args.Skip(1).ToArray(), stdout, stderr),
"canon" => RunCanon(args.Skip(1).ToArray(), stdout, stderr),
"asm" => RunAsm(args.Skip(1).ToArray(), stdout, stderr),
"experimental" => RunExperimental(args.Skip(1).ToArray(), stdout, stderr),
@@ -176,6 +178,97 @@ public static class CliRunner
return 0;
}
+ private static int RunTrace(string[] args, TextWriter stdout, TextWriter stderr)
+ {
+ if (args.Length > 0 && IsHelpFlag(args[0]))
+ {
+ WriteTraceHelp(stdout);
+ return 0;
+ }
+
+ string? caseName = null;
+ string? outDir = null;
+ var json = false;
+ for (var i = 0; i < args.Length; i++)
+ {
+ switch (args[i])
+ {
+ case "--case" when i + 1 < args.Length:
+ caseName = args[++i];
+ break;
+ case "--case":
+ stderr.WriteLine("Trace option --case requires a case name.");
+ stderr.WriteLine(TraceUsage);
+ return 1;
+ case "--out-dir" when i + 1 < args.Length:
+ outDir = args[++i];
+ break;
+ case "--out-dir":
+ stderr.WriteLine("Trace option --out-dir requires a directory path.");
+ stderr.WriteLine("air-x6-output-directory-invalid");
+ stderr.WriteLine(TraceUsage);
+ return 1;
+ case "--json":
+ json = true;
+ break;
+ case "-h":
+ case "--help":
+ WriteTraceHelp(stdout);
+ return 0;
+ default:
+ if (!args[i].StartsWith("-", StringComparison.Ordinal))
+ {
+ stderr.WriteLine("trace does not analyze STEP files; use `aetheris analyze ...`.");
+ stderr.WriteLine("air-x6-step-input-rejected-use-analyze");
+ stderr.WriteLine(TraceUsage);
+ return 1;
+ }
+ stderr.WriteLine($"Unknown trace option '{args[i]}'.");
+ stderr.WriteLine(TraceUsage);
+ return 1;
+ }
+ }
+
+ if (string.IsNullOrWhiteSpace(caseName))
+ {
+ stderr.WriteLine("Trace requires --case <name>.");
+ stderr.WriteLine("air-x6-missing-case-rejected");
+ 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;
+ }
+
+ var report = AirTraceReportBuilder.Build(caseName);
+ 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"));
+ File.WriteAllText(path, text);
+ if (json)
+ {
+ stdout.WriteLine(text);
+ }
+ else
+ {
+ stdout.WriteLine($"Trace report written: {path}");
+ }
+ return 0;
+ }
+
+ stdout.WriteLine(text);
+ return 0;
+ }
+
private static int RunCanon(string[] args, TextWriter stdout, TextWriter stderr)
{
if (args.Length == 0)
@@ -1770,7 +1863,7 @@ public static class CliRunner
private static int UnknownCommand(string command, TextWriter stderr)
{
- stderr.WriteLine($"Unknown command '{command}'. Expected one of: build, analyze, canon, asm, experimental.");
+ stderr.WriteLine($"Unknown command '{command}'. Expected one of: build, analyze, trace, canon, asm, experimental.");
stderr.WriteLine("Run 'aetheris --help' for usage and examples.");
return 1;
}
@@ -1798,6 +1891,7 @@ public static class CliRunner
stdout.WriteLine("Commands:");
stdout.WriteLine(" build Build a .firmament source file into STEP.");
stdout.WriteLine(" analyze Analyze STEP topology, geometry, map, and sections.");
+ stdout.WriteLine(" trace Trace built-in AIR lowering cases through route, BRepPlan, STEP smoke, and CIR mirror.");
stdout.WriteLine(" canon Import and re-export STEP/AP242 as canonical STEP.");
stdout.WriteLine(" asm Execute/export .firmasm assembly IR using rigid world-space composition.");
stdout.WriteLine(" experimental Experimental/lab-only artifact export and generated-source inspection commands.");
@@ -1810,6 +1904,8 @@ public static class CliRunner
stdout.WriteLine(" aetheris build model.firmament --out model.step");
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 --case prismatic-section-transition --json");
stdout.WriteLine(" aetheris canon input.step --out canonical.step --json");
stdout.WriteLine(" aetheris asm exec assembly.firmasm --json");
stdout.WriteLine(" aetheris asm export assembly.firmasm --out out/assembly-roundtrip --json");
@@ -1837,6 +1933,30 @@ public static class CliRunner
stdout.WriteLine(" aetheris build part.firmament --out part.step --json");
}
+ private static void WriteTraceHelp(TextWriter stdout)
+ {
+ stdout.WriteLine("Trace a built-in Aetheris lowering case through AIR, route selection, BRepPlan, emitted BRep/STEP smoke, and CIR mirror admission. Use `analyze` for existing STEP/BRep geometry.");
+ stdout.WriteLine();
+ stdout.WriteLine(TraceUsage);
+ 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(" 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(" --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.");
+ stdout.WriteLine();
+ 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");
+ }
+
private static void WriteAnalyzeHelp(TextWriter stdout)
{
stdout.WriteLine("Analyze part-like STEP geometry and topology.");
diff --git a/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs b/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs
index af5bf8ea..131e6511 100644
--- a/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs
+++ b/Aetheris.Kernel.Core/Properties/InternalsVisibleTo.cs
@@ -5,3 +5,4 @@ using System.Runtime.CompilerServices;
[assembly: InternalsVisibleTo("Aetheris.FrictionLab.Tests")]
[assembly: InternalsVisibleTo("Aetheris.Kernel.Firmament")]
[assembly: InternalsVisibleTo("Aetheris.Kernel.Firmament.Tests")]
+[assembly: InternalsVisibleTo("aetheris")]
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index 24fb5cdd..3b2cc351 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -757,3 +757,7 @@ AIR-X4 adds feature-role-aware BRepPlan evidence for the Class B top-face loop c
## AIR-X5 status note
AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
+
+## 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.
diff --git a/docs/air-x1-minimal-air-wrappers-for-proven-lanes.md b/docs/air-x1-minimal-air-wrappers-for-proven-lanes.md
index 45b5ef20..c1e2d910 100644
--- a/docs/air-x1-minimal-air-wrappers-for-proven-lanes.md
+++ b/docs/air-x1-minimal-air-wrappers-for-proven-lanes.md
@@ -84,3 +84,7 @@ AIR-X1 wrappers remain thin envelopes around proven lanes. AIR-X3 adds a non-pro
## AIR-X4 top-face loop chamfer BRepPlan role note
The AIR-X1 top-face loop chamfer wrapper remains the existing proven lane. AIR-X4 adds a non-production BRepPlan wrapper that reuses the prismatic plan and records Class B provenance plus chamfer semantic roles for upper transition faces without replacing this wrapper.
+
+## AIR-X6 trace consumption
+
+`aetheris trace` consumes the AIR-X1 wrapper summaries for `prismatic-section-transition` and `top-face-loop-chamfer` as source/provenance evidence. The wrappers remain non-production lowering evidence and are not route replacements.
diff --git a/docs/air-x2-route-selection-and-admissibility.md b/docs/air-x2-route-selection-and-admissibility.md
index 62991754..3c6c234f 100644
--- a/docs/air-x2-route-selection-and-admissibility.md
+++ b/docs/air-x2-route-selection-and-admissibility.md
@@ -73,3 +73,7 @@ AIR-X3 proves that the direct `AirPrismaticSectionTransition` route can produce
## AIR-X4 evidence note
The AIR-X2 switch/match-selected `TopFaceLoopChamferPrismatic` route now has AIR-X4 BRepPlan evidence carrying `FaceBoundaryLoop`, `UniformChamfer`, `SwitchMatch`, and not-four-independent-single-edge-chamfers provenance. Route selection and JudgmentUtility behavior are unchanged.
+
+## 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.
diff --git a/docs/air-x3-brep-plan-prismatic-section-transition.md b/docs/air-x3-brep-plan-prismatic-section-transition.md
index 1230f0dd..a00f2ad8 100644
--- a/docs/air-x3-brep-plan-prismatic-section-transition.md
+++ b/docs/air-x3-brep-plan-prismatic-section-transition.md
@@ -93,3 +93,7 @@ Recommended next milestone: **AIR-X4 — BRepPlan roles/provenance for top-face
## AIR-X4 extension note
AIR-X4 extends this prismatic BRepPlan through a feature role overlay rather than duplicating the planner. The top-face loop chamfer wrapper preserves primary prismatic transition roles and adds `ChamferFace` semantic roles to upper transition faces only when the feature context is the Class B top-face loop chamfer.
+
+## AIR-X6 trace reporting
+
+`aetheris trace` reports the AIR-X3 prismatic BRepPlan summary, including split policy, bounds, and stable topology counts. The trace command uses the planner read-only and does not materialize new production topology or change emitter behavior.
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 a3c3b000..1f323919 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
@@ -99,3 +99,7 @@ Recommended: **AIR-X5 — BRepPlan materialization adapter for prismatic transit
## AIR-X5 status note
AIR-X5 adds an internal/test-visible AIR-to-CIR mirror adapter envelope for generated prismatic section transitions and top-face loop chamfers when existing convex polyhedron mirror evidence admits them. The adapter preserves AIR provenance metadata but explicitly denies CIR face identity, loop identity, topology parity, chamfer-face identity, feature labels, and BRepPlan role parity. It does not change production analyzer behavior, route selection, BRepPlan behavior, BRep topology, STEP import/export, CIR evaluator/tape behavior, Firmament lowering, Boolean behavior, or chamfer/fillet/shell geometry. See [AIR-X5 — AIR-to-CIR mirror adapter envelope](air-x5-air-to-cir-mirror-adapter-envelope.md).
+
+## 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.
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 01100ae0..b12d4555 100644
--- a/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
+++ b/docs/air-x5-air-to-cir-mirror-adapter-envelope.md
@@ -93,3 +93,7 @@ Focused AIR-X5 tests were added to `Aetheris.Kernel.Core.Tests` for prismatic ad
Recommended: **AIR-X6 — AIR/BRepPlan/CIR unified artifact summary for prismatic + loop chamfer**.
Implementation showed that AIR-X3/X4 already carry useful BRepPlan topology-role metadata while AIR-X5 now carries evaluation-mirror metadata. A unified non-production artifact summary would make the authority boundaries easier to inspect without changing production routes or claiming CIR topology parity.
+
+## 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.
diff --git a/docs/air-x6-aetheris-trace-lowering-report-cli.md b/docs/air-x6-aetheris-trace-lowering-report-cli.md
new file mode 100644
index 00000000..67a0465f
--- /dev/null
+++ b/docs/air-x6-aetheris-trace-lowering-report-cli.md
@@ -0,0 +1,140 @@
+# AIR-X6 — `aetheris trace` lowering report CLI
+
+## Purpose and scope
+
+AIR-X6 adds the first explicit top-level lowering trace command:
+
+```bash
+aetheris trace --case <name> [--json] [--out-dir <dir>]
+```
+
+`trace` is a compiler flight recorder for known built-in AIR/Firmament-derived cases. It reports how an authored feature is represented as AIR, admitted by route selection, summarized as BRepPlan, checked through existing BRep/STEP smoke, and mirrored into CIR when admitted.
+
+## `trace` vs `analyze`
+
+* `aetheris trace` inspects compiler lowering: AIR, route decision, BRepPlan, emitted BRep/STEP smoke, CIR mirror, diagnostics, guarantees, and losses.
+* `aetheris analyze` inspects existing geometry/artifacts: STEP/BRep topology, faces, edges, maps, sections, and volume.
+* `trace` accepts no arbitrary STEP input. STEP files remain the job of `aetheris analyze ...`.
+
+## Supported cases
+
+* `prismatic-section-transition`
+* `top-face-loop-chamfer`
+
+Optional aliases are accepted for convenience:
+
+* `prismatic`
+* `loop-chamfer`
+
+## Output behavior
+
+Text output is the default because the command exists to help humans and LLMs inspect what Aetheris is doing. `--json` emits deterministic machine-readable JSON.
+
+Examples:
+
+```bash
+aetheris trace --case prismatic-section-transition
+aetheris trace --case top-face-loop-chamfer
+aetheris trace --case prismatic-section-transition --json
+aetheris trace --case top-face-loop-chamfer --json
+```
+
+With `--out-dir`, text mode writes a `.txt` report and prints the written path. JSON mode writes the `.json` report and also emits the JSON to stdout for parser-friendly CLI use.
+
+Preferred artifact names are used:
+
+* `air-x6-prismatic-section-transition-trace.txt`
+* `air-x6-prismatic-section-transition-trace.json`
+* `air-x6-top-face-loop-chamfer-trace.txt`
+* `air-x6-top-face-loop-chamfer-trace.json`
+
+## Report contents
+
+Each successful report includes:
+
+* input/source case identity;
+* AIR node and provenance summary;
+* route-selection summary;
+* BRepPlan counts, split policy, bounds, and semantic role counts;
+* existing emitted BRep / STEP smoke summary;
+* CIR mirror admission, backend, capabilities, provenance, and known losses;
+* deterministic diagnostics;
+* guarantees and unchanged behavior.
+
+## Text output example
+
+```text
+Aetheris trace — AIR-X6 lowering report
+Case: top-face-loop-chamfer
+Trace kind: lowering
+Input kind: built-in-case
+
+AIR
+ Node: TopFaceLoopChamfer
+ Route: TopFaceLoopChamferPrismatic
+ Selection class: FaceBoundaryLoop
+ Rule: UniformChamfer
+
+Route decision
+ Mode: SwitchMatch
+ Selected route: TopFaceLoopChamferPrismatic
+
+BRepPlan
+ Plan kind: PrismaticSectionTransition
+ Vertices: 12
+ Edges: 20
+ Faces: 10
+ Loops: 10
+ Coedges: 40
+ Cap faces: 2
+ Chamfer faces: 4
+
+Emission / STEP
+ STEP smoke: succeeded
+
+CIR mirror
+ Status: mirror-admitted-exact
+ Backend: cir-convex-polyhedron
+```
+
+## JSON output example
+
+```json
+{
+ "milestone": "AIR-X6",
+ "command": "trace",
+ "traceKind": "lowering",
+ "inputKind": "built-in-case",
+ "caseName": "top-face-loop-chamfer",
+ "succeeded": true,
+ "air": { "node": "TopFaceLoopChamfer" },
+ "routeDecision": { "mode": "SwitchMatch" },
+ "bRepPlan": { "vertices": 12, "edges": 20, "faces": 10, "chamferFaces": 4 },
+ "emission": {},
+ "stepSmoke": {},
+ "cirMirror": {},
+ "capabilities": [],
+ "knownLosses": [],
+ "diagnostics": [],
+ "guarantees": []
+}
+```
+
+## Invalid usage behavior
+
+* Missing `--case` returns nonzero, reports that `--case` is required, and lists supported cases.
+* Unknown cases return nonzero and list supported cases.
+* Positional STEP-like input returns nonzero with: `trace does not analyze STEP files; use \`aetheris analyze ...\`.`
+* Unsupported options follow existing CLI error style.
+
+## Non-goals
+
+AIR-X6 does not change production geometry or topology behavior. It specifically does not add STEP input to trace, replace production routes, alter production analyzer behavior, change STEP exporter/importer behavior, change BRep topology behavior, add geometry implementation, add import/recovery, add arbitrary graph support, change route-selection/JudgmentUtility semantics, change Firmament lowering, change Boolean behavior, change CIR evaluator/tape behavior, or expand NURBS/freeform support.
+
+## Tests run
+
+Focused AIR-X6 validation used CLI help, text output, JSON parsing/determinism, `--out-dir` writing, and invalid usage tests. Broader gates should include CLI/core/Firmament/FrictionLab AIR, CIR, BRepPlan, STEP, prismatic, and chamfer filters.
+
+## 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.