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.csnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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"+```