Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add gated AirChamfer corpus stability check

Yuechen Licf2a5e354ca4
diff --git a/Aetheris.CLI.Tests/AirChamferCorpusStabilityTests.cs b/Aetheris.CLI.Tests/AirChamferCorpusStabilityTests.cs
new file mode 100644
index 00000000..36002b6d
--- /dev/null
+++ b/Aetheris.CLI.Tests/AirChamferCorpusStabilityTests.cs
@@ -0,0 +1,206 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+using Xunit.Abstractions;
+
+namespace Aetheris.CLI.Tests;
+
+public sealed class AirChamferCorpusStabilityTests
+{
+ private const string RunArtifactCorpusTestsEnvironmentVariable = "AETHERIS_RUN_ARTIFACT_CORPUS_TESTS";
+ private readonly ITestOutputHelper output;
+
+ public AirChamferCorpusStabilityTests(ITestOutputHelper output)
+ {
+ this.output = output;
+ }
+
+ [Fact]
+ [Trait("Category", "ArtifactCorpus")]
+ public void AirChamferCorpusStability_Repeated_Cli_Runs_Produce_Stable_Json_Markers_Topology_And_Step_Hashes()
+ {
+ if (!string.Equals(Environment.GetEnvironmentVariable(RunArtifactCorpusTestsEnvironmentVariable), "1", StringComparison.Ordinal))
+ {
+ output.WriteLine(
+ $"Skipping gated EDGE-X12 AirChamfer artifact corpus stability check. Set {RunArtifactCorpusTestsEnvironmentVariable}=1 and filter by AirChamferCorpusStability or Category=ArtifactCorpus to run it explicitly.");
+ return;
+ }
+
+ var root = Path.Combine(Path.GetTempPath(), $"edge-x12-airchamfer-corpus-stability-{Guid.NewGuid():N}");
+ var firstDir = Path.Combine(root, "first");
+ var secondDir = Path.Combine(root, "second");
+
+ try
+ {
+ var first = GenerateAndSummarizeCorpus(firstDir);
+ var second = GenerateAndSummarizeCorpus(secondDir);
+
+ Assert.Equal(first.StableJsonSummaryJson, second.StableJsonSummaryJson);
+ Assert.Equal(first.StepSha256ByArtifactFileName, second.StepSha256ByArtifactFileName);
+ }
+ finally
+ {
+ if (Directory.Exists(root))
+ {
+ Directory.Delete(root, recursive: true);
+ }
+ }
+ }
+
+ private static AirChamferCorpusStabilityRun GenerateAndSummarizeCorpus(string outputDir)
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+
+ var exitCode = Aetheris.CLI.CliRunner.Run(["experimental", "airchamfer-corpus", "--out-dir", outputDir, "--json"], stdout, stderr);
+
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()), stderr.ToString());
+
+ var summaryPath = Path.Combine(outputDir, "edge-x11-airchamfer-corpus.json");
+ Assert.True(File.Exists(summaryPath));
+
+ using var stdoutJson = JsonDocument.Parse(stdout.ToString());
+ using var fileJson = JsonDocument.Parse(File.ReadAllText(summaryPath));
+ Assert.Equal(stdoutJson.RootElement.GetProperty("corpusVersion").GetString(), fileJson.RootElement.GetProperty("corpusVersion").GetString());
+ Assert.Equal(stdoutJson.RootElement.GetProperty("milestone").GetString(), fileJson.RootElement.GetProperty("milestone").GetString());
+ Assert.Equal(stdoutJson.RootElement.GetProperty("cases").GetArrayLength(), fileJson.RootElement.GetProperty("cases").GetArrayLength());
+
+ var stableSummary = AirChamferCorpusStabilitySummary.FromJson(stdoutJson.RootElement);
+ Assert.Contains("edge-x11-legacy-authority-preserved", stableSummary.Diagnostics);
+ Assert.Contains("edge-x11-no-production-route-replacement", stableSummary.Diagnostics);
+ Assert.Contains("edge-x11-no-3d-boolean-used", stableSummary.Diagnostics);
+ Assert.True(stableSummary.LegacyAuthorityPreserved);
+ Assert.False(stableSummary.ProductionOutputChanged);
+ Assert.True(stableSummary.NoProductionRouteReplacement);
+ Assert.True(stableSummary.No3DBooleanUsed);
+
+ var shaByArtifact = new SortedDictionary<string, string>(StringComparer.Ordinal);
+ foreach (var corpusCase in stableSummary.Cases.Where(c => string.Equals(c.Status, "succeeded", StringComparison.Ordinal)))
+ {
+ Assert.False(string.IsNullOrWhiteSpace(corpusCase.ArtifactFileName));
+ var stepPath = Path.Combine(outputDir, corpusCase.ArtifactFileName!);
+ Assert.True(File.Exists(stepPath), $"Expected STEP artifact '{stepPath}' to exist.");
+ Assert.True(new FileInfo(stepPath).Length > 0, $"Expected STEP artifact '{stepPath}' to be non-empty.");
+
+ var stepText = File.ReadAllText(stepPath);
+ AssertStepMarkers(stepText);
+ shaByArtifact.Add(corpusCase.ArtifactFileName!, Sha256(stepPath));
+ }
+
+ Assert.Equal(new[] { "edge-x11-airchamfer-cube-canonical.step", "edge-x11-airchamfer-cube-nonorthogonal.step" }, shaByArtifact.Keys.ToArray());
+
+ return new AirChamferCorpusStabilityRun(JsonSerializer.Serialize(stableSummary), shaByArtifact);
+ }
+
+ private static void AssertStepMarkers(string stepText)
+ {
+ Assert.False(string.IsNullOrWhiteSpace(stepText));
+ Assert.Contains("ISO-10303-21", stepText, StringComparison.Ordinal);
+ Assert.Contains("MANIFOLD_SOLID_BREP", stepText, StringComparison.Ordinal);
+ Assert.Contains("ADVANCED_FACE", stepText, StringComparison.Ordinal);
+ Assert.Contains("PLANE", stepText, StringComparison.Ordinal);
+ Assert.DoesNotContain("CYLINDRICAL_SURFACE", stepText, StringComparison.Ordinal);
+ Assert.DoesNotContain("BREP_WITH_VOIDS", stepText, StringComparison.Ordinal);
+ }
+
+ private static string Sha256(string path)
+ {
+ using var stream = File.OpenRead(path);
+ return Convert.ToHexString(SHA256.HashData(stream));
+ }
+
+ private sealed record AirChamferCorpusStabilityRun(
+ string StableJsonSummaryJson,
+ SortedDictionary<string, string> StepSha256ByArtifactFileName);
+
+ private sealed record AirChamferCorpusStabilitySummary(
+ string CorpusVersion,
+ string Milestone,
+ string CandidatePath,
+ string Route,
+ bool LegacyAuthorityPreserved,
+ bool ProductionOutputChanged,
+ bool NoProductionRouteReplacement,
+ bool No3DBooleanUsed,
+ string[] Diagnostics,
+ string[] Errors,
+ AirChamferCorpusStabilityCaseSummary[] Cases)
+ {
+ public static AirChamferCorpusStabilitySummary FromJson(JsonElement root)
+ => new(
+ root.GetProperty("corpusVersion").GetString()!,
+ root.GetProperty("milestone").GetString()!,
+ root.GetProperty("candidatePath").GetString()!,
+ root.GetProperty("route").GetString()!,
+ root.GetProperty("legacyAuthorityPreserved").GetBoolean(),
+ root.GetProperty("productionOutputChanged").GetBoolean(),
+ root.GetProperty("noProductionRouteReplacement").GetBoolean(),
+ root.GetProperty("no3DBooleanUsed").GetBoolean(),
+ ReadStringArray(root.GetProperty("diagnostics")),
+ ReadStringArray(root.GetProperty("errors")),
+ root.GetProperty("cases")
+ .EnumerateArray()
+ .Select(AirChamferCorpusStabilityCaseSummary.FromJson)
+ .OrderBy(c => c.CaseName, StringComparer.Ordinal)
+ .ToArray());
+ }
+
+ private sealed record AirChamferCorpusStabilityCaseSummary(
+ string CaseName,
+ string Status,
+ string? ArtifactFileName,
+ string CandidatePath,
+ string Route,
+ bool? RequiredPresentSatisfied,
+ bool? ForbiddenAbsentSatisfied,
+ string? MarkerBooleansJson,
+ string? TopologySummaryJson,
+ bool LegacyAuthorityPreserved,
+ bool ProductionOutputChanged,
+ bool NoProductionRouteReplacement,
+ bool No3DBooleanUsed,
+ string[] Diagnostics,
+ string[] Errors)
+ {
+ public static AirChamferCorpusStabilityCaseSummary FromJson(JsonElement element)
+ {
+ var stepMarkerSummary = element.GetProperty("stepMarkerSummary");
+ string? markerBooleansJson = null;
+ bool? requiredPresentSatisfied = null;
+ bool? forbiddenAbsentSatisfied = null;
+ if (stepMarkerSummary.ValueKind != JsonValueKind.Null)
+ {
+ requiredPresentSatisfied = stepMarkerSummary.GetProperty("requiredPresentSatisfied").GetBoolean();
+ forbiddenAbsentSatisfied = stepMarkerSummary.GetProperty("forbiddenAbsentSatisfied").GetBoolean();
+ markerBooleansJson = stepMarkerSummary.GetProperty("markers").GetRawText();
+ }
+
+ var topologySummary = element.GetProperty("topologySummary");
+ return new AirChamferCorpusStabilityCaseSummary(
+ element.GetProperty("caseName").GetString()!,
+ element.GetProperty("status").GetString()!,
+ ReadNullableString(element.GetProperty("artifactFileName")),
+ element.GetProperty("candidatePath").GetString()!,
+ element.GetProperty("route").GetString()!,
+ requiredPresentSatisfied,
+ forbiddenAbsentSatisfied,
+ markerBooleansJson,
+ topologySummary.ValueKind == JsonValueKind.Null ? null : topologySummary.GetRawText(),
+ element.GetProperty("legacyAuthorityPreserved").GetBoolean(),
+ element.GetProperty("productionOutputChanged").GetBoolean(),
+ element.GetProperty("noProductionRouteReplacement").GetBoolean(),
+ element.GetProperty("no3DBooleanUsed").GetBoolean(),
+ ReadStringArray(element.GetProperty("diagnostics")),
+ ReadStringArray(element.GetProperty("errors")));
+ }
+ }
+
+ private static string[] ReadStringArray(JsonElement element)
+ => element.EnumerateArray()
+ .Select(x => x.GetString()!)
+ .OrderBy(x => x, StringComparer.Ordinal)
+ .ToArray();
+
+ private static string? ReadNullableString(JsonElement element)
+ => element.ValueKind == JsonValueKind.Null ? null : element.GetString();
+}
diff --git a/docs/frictionlab/edge-x11-airchamfer-step-artifact-corpus.md b/docs/frictionlab/edge-x11-airchamfer-step-artifact-corpus.md
index 7f3d65b6..69736e35 100644
--- a/docs/frictionlab/edge-x11-airchamfer-step-artifact-corpus.md
+++ b/docs/frictionlab/edge-x11-airchamfer-step-artifact-corpus.md
@@ -150,6 +150,10 @@ EDGE-X11 does not add or change:
- clipping engine behavior
- NURBS/freeform support
+## EDGE-X12 gated stability check
+
+EDGE-X12 adds an explicitly gated/manual repeated-run stability check for this corpus. See `docs/frictionlab/edge-x12-airchamfer-corpus-stability.md` for the opt-in command, `Category=ArtifactCorpus` trait, `AETHERIS_RUN_ARTIFACT_CORPUS_TESTS=1` guard, and the raw STEP SHA256 plus normalized JSON/marker/topology comparisons. The check is intentionally not part of normal/default unit-test execution unless explicitly requested.
+
## Recommended next milestone
-Recommended next milestone: EDGE-X12 should compare the corpus summaries across known-good generated outputs and tighten deterministic diagnostic drift checks before considering any broader AirChamfer corpus shape expansion. Any route comparison must remain analyzer/shadow evidence only until a separate production authorization milestone exists.
+After EDGE-X12, any broader AirChamfer corpus shape expansion should remain analyzer/shadow evidence only until a separate production authorization milestone exists.
diff --git a/docs/frictionlab/edge-x12-airchamfer-corpus-stability.md b/docs/frictionlab/edge-x12-airchamfer-corpus-stability.md
new file mode 100644
index 00000000..453478fd
--- /dev/null
+++ b/docs/frictionlab/edge-x12-airchamfer-corpus-stability.md
@@ -0,0 +1,155 @@
+# EDGE-X12 — Gated AirChamfer artifact corpus stability check
+
+## Purpose and scope
+
+EDGE-X12 adds an explicitly gated/manual stability check for the EDGE-X11 AirChamfer STEP artifact corpus. The check exists to prove that repeated runs of the experimental/lab corpus route produce stable JSON evidence, stable STEP marker summaries, stable topology summaries, and stable STEP artifact bytes for the current controlled cases.
+
+The route under check remains:
+
+```text
+AirChamferShadowRoute -> AirChamferRealBodyPrototype
+```
+
+This is only an artifact-corpus guard for the experimental CLI lane. It is not a production chamfer route, not a replacement for legacy `BrepBoundedChamfer`, and not a broad geometry feature expansion.
+
+## EDGE-X11 reference
+
+EDGE-X11 introduced the experimental CLI corpus route:
+
+```bash
+dotnet run --project Aetheris.CLI --framework net10.0 -- experimental airchamfer-corpus --out-dir <dir> --json
+```
+
+That command generates successful STEP artifacts plus the corpus JSON summary:
+
+- `edge-x11-airchamfer-cube-canonical.step`
+- `edge-x11-airchamfer-cube-nonorthogonal.step`
+- `edge-x11-airchamfer-corpus.json`
+
+Rejected or deferred corpus rows remain JSON-only evidence and do not write STEP files.
+
+## Manual corpus generation
+
+Generate the corpus manually with:
+
+```bash
+tmp=$(mktemp -d)
+dotnet run --project Aetheris.CLI --framework net10.0 -- experimental airchamfer-corpus --out-dir "$tmp/edge-x11" --json
+```
+
+## Gated stability test
+
+The EDGE-X12 check lives in `Aetheris.CLI.Tests` as:
+
+```text
+AirChamferCorpusStability_Repeated_Cli_Runs_Produce_Stable_Json_Markers_Topology_And_Step_Hashes
+```
+
+It is marked with the xUnit trait:
+
+```text
+Category=ArtifactCorpus
+```
+
+It also has an environment-variable guard so normal/default test runs do not execute the expensive/manual artifact corpus comparison body:
+
+```text
+AETHERIS_RUN_ARTIFACT_CORPUS_TESTS=1
+```
+
+Run it explicitly with either the name filter:
+
+```bash
+AETHERIS_RUN_ARTIFACT_CORPUS_TESTS=1 dotnet test Aetheris.CLI.Tests/Aetheris.CLI.Tests.csproj --filter "AirChamferCorpusStability"
+```
+
+or the trait filter:
+
+```bash
+AETHERIS_RUN_ARTIFACT_CORPUS_TESTS=1 dotnet test Aetheris.CLI.Tests/Aetheris.CLI.Tests.csproj --filter "Category=ArtifactCorpus"
+```
+
+If the environment variable is omitted, the test reports a clear skip/no-op message and returns without generating or comparing the corpus. This keeps `dotnet test` and `./scripts/test-all.sh` on their normal/default paths unless a developer explicitly opts in.
+
+## What is compared
+
+The stability check creates two independent temporary output directories and invokes the CLI corpus route twice through `CliRunner`, matching existing CLI test conventions.
+
+For each run it verifies:
+
+- stdout JSON parses successfully;
+- `edge-x11-airchamfer-corpus.json` exists and parses successfully;
+- stdout/file JSON agree on corpus version, milestone, and case count;
+- top-level diagnostics include:
+ - `edge-x11-legacy-authority-preserved`;
+ - `edge-x11-no-production-route-replacement`;
+ - `edge-x11-no-3d-boolean-used`;
+- top-level guard booleans preserve legacy authority, no production output change, no production route replacement, and no 3D Boolean;
+- stable projected JSON fields match across repeated runs, ignoring run-specific output directory and summary path values.
+
+For each case it compares:
+
+- case names;
+- statuses;
+- artifact filenames for successful cases;
+- required-present marker result booleans;
+- forbidden-absent marker result booleans;
+- raw marker booleans from `stepMarkerSummary.markers`;
+- topology summary JSON when present;
+- case-level guard booleans for legacy authority, production output, production route replacement, and 3D Boolean;
+- diagnostics and errors.
+
+For successful STEP artifacts it verifies the marker smoke contract:
+
+Required present:
+
+- `ISO-10303-21`
+- `MANIFOLD_SOLID_BREP`
+- `ADVANCED_FACE`
+- `PLANE`
+
+Forbidden absent:
+
+- `CYLINDRICAL_SURFACE`
+- `BREP_WITH_VOIDS`
+
+## STEP comparison mode
+
+EDGE-X12 uses raw STEP SHA256 hash comparison for the current EDGE-X11 artifacts. Local repeated runs showed that the raw STEP text is deterministic for both successful corpus cases, and the gated test compares hashes by artifact filename.
+
+If a future exporter introduces legitimate run-specific identifiers, timestamps, or ordering into these experimental artifacts, the test should be intentionally changed to a normalized comparison mode rather than forcing raw hash parity. The normalized mode should keep comparing JSON schema/status, STEP marker booleans, relevant entity counts if available, and topology summaries.
+
+## Why this is not part of normal unit tests
+
+The check writes artifact directories, runs the corpus route twice, parses JSON summaries, reads STEP files, and hashes the generated STEP bytes. That is valuable for manual artifact-corpus validation but too specific for default unit-test execution. The explicit trait/name filter plus environment guard prevents accidental inclusion in normal test sweeps while preserving an exact command for release/milestone validation.
+
+## Non-goals
+
+EDGE-X12 does not add or change:
+
+- production chamfer behavior;
+- production fillet behavior;
+- production chamfer route replacement;
+- STEP exporter/importer behavior;
+- Boolean core behavior;
+- arbitrary edge selection;
+- 3D Boolean usage;
+- fillet geometry;
+- chain/corner support;
+- sketch solver behavior;
+- clipping engine behavior;
+- NURBS/freeform support.
+
+## Tests run
+
+Recommended validation for this milestone:
+
+```bash
+dotnet run --project Aetheris.CLI --framework net10.0 -- --help
+tmp=$(mktemp -d) && dotnet run --project Aetheris.CLI --framework net10.0 -- experimental airchamfer-corpus --out-dir "$tmp/edge-x11" --json
+AETHERIS_RUN_ARTIFACT_CORPUS_TESTS=1 dotnet test Aetheris.CLI.Tests/Aetheris.CLI.Tests.csproj --filter "AirChamferCorpusStability"
+dotnet test Aetheris.CLI.Tests/Aetheris.CLI.Tests.csproj --filter "AirChamfer|Experimental|Lab|Step|CliBaseline|Export|Corpus"
+dotnet test Aetheris.FrictionLab.Tests/Aetheris.FrictionLab.Tests.csproj -c Release -f net10.0 --filter "AirChamferShadow|AirChamferFeatureRecognition|AirChamferControlledBody|AirChamferTopologyGraft|AirChamferClosedWitness|AirChamferGeometryArtifact|AirChamferTopologyPlan|AirChamferJudgment|AirChamferPolicy|AirChamferPatch|EdgeSweep|Chamfer|Fillet|EdgeFinish|CIRLab"
+dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj --filter "Chamfer|Fillet|Corner|TriangularPrism|FirmamentPrimitive|FirmamentStepExporter|LineArcProfileExtrude|SemanticRecovery|FrepMaterializer|Rematerialize"
+dotnet test Aetheris.Kernel.Core.Tests/Aetheris.Kernel.Core.Tests.csproj --filter "Judgment|Chamfer|Fillet|Corner|TriangularPrism|BrepPrimitives|Step242|Primitive|Extrude|Boolean|SafeComposition"
+```