Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Lock Firmament V2 side-hole artifacts

Yuechen Lid3a3237ad4e4
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
index 3c26ddfd..d4dcc969 100644
--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs
+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs
@@ -998,6 +998,114 @@ public sealed class AirTraceCommandTests
Assert.Contains("firmament-v2-unknown-record-type", output);
}
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_OutDirWritesStableFiles()
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ var (exitCode, output, error) = Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", dir);
+
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.Contains("Trace artifacts written:", output, StringComparison.Ordinal);
+ foreach (var name in new[] { "side-hole-v2.step", "side-hole-v2.trace.json", "side-hole-v2.trace.txt", "manifest.json" })
+ {
+ var path = Path.Combine(dir, name);
+ Assert.True(File.Exists(path), path);
+ Assert.True(new FileInfo(path).Length > 0, path);
+ }
+ }
+
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_ManifestContainsGoldenPathFacts()
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", dir).ExitCode);
+
+ using var doc = JsonDocument.Parse(File.ReadAllText(Path.Combine(dir, "manifest.json")));
+ var root = doc.RootElement;
+ Assert.Equal("AIR-FIRMAMENT-X5", root.GetProperty("milestone").GetString());
+ Assert.Equal("FirmamentV2", root.GetProperty("syntaxVersion").GetString());
+ Assert.EndsWith("fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture", root.GetProperty("fixture").GetString()!.Replace('\\', '/'), StringComparison.Ordinal);
+ Assert.Equal("region-parent-integrated", root.GetProperty("stage").GetString());
+ Assert.Equal("Integrated", root.GetProperty("parentIntegration").GetString());
+ Assert.Equal("Closed", root.GetProperty("shellClosure").GetString());
+ Assert.Equal("Succeeded", root.GetProperty("stepSmoke").GetString());
+ Assert.True(root.GetProperty("controlledFixtureOnly").GetBoolean());
+ Assert.False(root.GetProperty("generalSideHoleSupport").GetBoolean());
+ }
+
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_TraceReportsArtifactPaths()
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", dir).ExitCode);
+
+ var text = File.ReadAllText(Path.Combine(dir, "side-hole-v2.trace.txt"));
+ Assert.Contains("Artifacts", text);
+ Assert.Contains(Path.Combine(dir, "side-hole-v2.step"), text);
+ using var doc = JsonDocument.Parse(File.ReadAllText(Path.Combine(dir, "side-hole-v2.trace.json")));
+ Assert.Equal(Path.Combine(dir, "side-hole-v2.step"), doc.RootElement.GetProperty("artifacts").GetProperty("step").GetString());
+ }
+
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_ParityWithX13GoldenPath()
+ {
+ var (_, v2Output, _) = Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--json");
+ var (_, x13Output, _) = Run("trace", "--fixture", RegionFixture("valid/side-hole-face-attached-region.valid.firmfixture"), "--json");
+ using var v2 = JsonDocument.Parse(v2Output);
+ using var x13 = JsonDocument.Parse(x13Output);
+
+ Assert.Equal(x13.RootElement.GetProperty("actualStageReached").GetString(), v2.RootElement.GetProperty("actualStageReached").GetString());
+ var v2Region = v2.RootElement.GetProperty("regions").GetProperty("regions")[1];
+ var x13Region = x13.RootElement.GetProperty("regions").GetProperty("regions")[1];
+ Assert.Equal("Integrated", v2Region.GetProperty("parentIntegration").GetProperty("status").GetString());
+ Assert.Equal(v2Region.GetProperty("parentIntegration").GetProperty("status").GetString(), x13Region.GetProperty("parentIntegration").GetProperty("status").GetString());
+ Assert.Equal("Closed", v2Region.GetProperty("shellClosure").GetProperty("status").GetString());
+ Assert.Equal("Succeeded", v2Region.GetProperty("parentIntegration").GetProperty("stepSmoke").GetProperty("status").GetString());
+ Assert.Equal("+X", v2Region.GetProperty("yield").GetProperty("attachment").GetProperty("faceSelector").GetString());
+ Assert.Contains("-X", v2Region.GetRawText(), StringComparison.Ordinal);
+ Assert.Contains("\"radius\": 1", v2Region.GetRawText(), StringComparison.Ordinal);
+ Assert.Contains("Cylinder", v2Region.GetRawText(), StringComparison.Ordinal);
+ foreach (var marker in new[] { "CutEntryLoop", "CutExitLoop", "CutWallFace", "RegionIntegrationPatch", "analysis-only", "Boolean" })
+ {
+ Assert.Contains(marker, v2Region.GetRawText(), StringComparison.OrdinalIgnoreCase);
+ Assert.Contains(marker, x13Region.GetRawText(), StringComparison.OrdinalIgnoreCase);
+ }
+ Assert.Equal(JsonValueKind.Null, v2Region.GetProperty("parentIntegration").GetProperty("blocker").ValueKind);
+ }
+
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_DeterministicTraceJson()
+ {
+ var firstDir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ var secondDir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", firstDir).ExitCode);
+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", secondDir).ExitCode);
+ var first = File.ReadAllText(Path.Combine(firstDir, "side-hole-v2.trace.json")).Replace(firstDir, "<OUT>");
+ var second = File.ReadAllText(Path.Combine(secondDir, "side-hole-v2.trace.json")).Replace(secondDir, "<OUT>");
+ Assert.Equal(first, second);
+ }
+
+ [Fact]
+ public void FirmamentV2SideHoleArtifacts_DoNotDeleteOutDirFiles()
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-trace-tests", Guid.NewGuid().ToString("N"));
+ Assert.Equal(0, Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"), "--out-dir", dir).ExitCode);
+ Assert.All(new[] { "side-hole-v2.step", "side-hole-v2.trace.json", "side-hole-v2.trace.txt", "manifest.json" }, name => Assert.True(File.Exists(Path.Combine(dir, name)), name));
+ }
+
+ [Fact]
+ public void FirmamentV2SideHole_GoldenPathStillGreen()
+ {
+ var (exitCode, output, error) = Run("trace", "--fixture", FirmamentV2Fixture("Region/valid/side-hole-v2.valid.firmfixture"));
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(error));
+ Assert.Contains("Actual stage: region-parent-integrated", output);
+ Assert.Contains("Parent integration: Integrated", output);
+ Assert.Contains("Shell closure: Closed", output);
+ Assert.Contains("STEP smoke: Succeeded", output);
+ }
+
private static string Fixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Chamfer", relative));
private static string PrimitiveFixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Primitive", relative));
private static string RegionFixture(string relative) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Firmament/Region", relative));
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 8dc52831..a7e24eaf 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -16,39 +16,46 @@ internal static class SideHoleGoldenPathArtifacts
public static AirTraceArtifactsSummary Write(string outDir, AirTraceReport report)
{
Directory.CreateDirectory(outDir);
+ var stem = IsFirmamentV2SideHole(report) ? "side-hole-v2" : "side-hole";
var artifacts = new AirTraceArtifactsSummary(
- Path.Combine(outDir, StepFileName),
- Path.Combine(outDir, JsonFileName),
- Path.Combine(outDir, TextFileName),
+ Path.Combine(outDir, stem + ".step"),
+ Path.Combine(outDir, stem + ".trace.json"),
+ Path.Combine(outDir, stem + ".trace.txt"),
Path.Combine(outDir, ManifestFileName));
- File.WriteAllText(artifacts.Step, StepText(report));
+ File.WriteAllText(artifacts.Step, StepText(report, stem));
return artifacts;
}
public static string Manifest(AirTraceReport report, AirTraceArtifactsSummary artifacts) => JsonSerializer.Serialize(new
{
- milestone = "AIR-REGION-X13",
+ milestone = IsFirmamentV2SideHole(report) ? "AIR-FIRMAMENT-X5" : "AIR-REGION-X13",
+ syntaxVersion = report.FirmamentV2?.SyntaxVersion,
fixture = report.FixturePath,
stage = report.ActualStageReached,
+ parentIntegration = report.FirmamentV2?.ParentIntegration ?? "Integrated",
+ shellClosure = report.FirmamentV2?.ShellClosure ?? "Closed",
+ stepSmoke = report.FirmamentV2?.StepSmoke ?? "Succeeded",
step = Path.GetFileName(artifacts.Step),
traceJson = Path.GetFileName(artifacts.TraceJson),
traceText = Path.GetFileName(artifacts.TraceText),
- parentIntegration = "Integrated",
- shellClosure = "Closed",
- stepSmoke = "Succeeded",
- controlledFixtureOnly = true
+ sourcePath = IsFirmamentV2SideHole(report) ? "FirmamentV2Parser" : "FirmamentFixtureMetadata",
+ controlledFixtureOnly = true,
+ generalSideHoleSupport = false
}, CliRunner.JsonOptions);
- private static string StepText(AirTraceReport report) => "ISO-10303-21;\n" +
+ private static bool IsFirmamentV2SideHole(AirTraceReport report) =>
+ report.FirmamentV2 is { SyntaxVersion: "FirmamentV2", SemanticIntent: not null };
+
+ private static string StepText(AirTraceReport report, string stem) => "ISO-10303-21;\n" +
"HEADER;\nFILE_DESCRIPTION(('AIR-REGION-X13 controlled side-hole golden path artifact'),'2;1');\n" +
- "FILE_NAME('side-hole.step','2026-06-18T00:00:00Z',('Aetheris'),('Aetheris'),'Aetheris.CLI trace','Aetheris','');\n" +
+ $"FILE_NAME('{stem}.step','2026-06-18T00:00:00Z',('Aetheris'),('Aetheris'),'Aetheris.CLI trace','Aetheris','');\n" +
"FILE_SCHEMA(('AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF { 1 0 10303 442 1 1 4 }'));\nENDSEC;\n" +
"DATA;\n" +
- "/* controlled fixture only: fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture */\n" +
+ $"/* controlled fixture only: {report.FixturePath} */\n" +
"/* stage=region-parent-integrated; parentIntegration=Integrated; shellClosure=Closed; stepSmoke=Succeeded */\n" +
"/* materialized: CutEntryLoop, CutExitLoop, CutWallFace, RegionIntegrationPatchConsumed */\n" +
"/* cylindrical cut wall evidence; CIR analysis-only; Boolean unused/not generally admitted */\n" +
- "#1=PRODUCT('AIR-REGION-X13-SIDE-HOLE','controlled side-hole golden path','generated-on-demand fixture artifact',());\n" +
+ $"#1=PRODUCT('{(IsFirmamentV2SideHole(report) ? "AIR-FIRMAMENT-X5-SIDE-HOLE-V2" : "AIR-REGION-X13-SIDE-HOLE")}','controlled side-hole golden path','generated-on-demand fixture artifact',());\n" +
"ENDSEC;\nEND-ISO-10303-21;\n";
}
@@ -332,14 +339,14 @@ public static class CliRunner
}
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() };
- if (!string.IsNullOrWhiteSpace(outDir) && string.Equals(report.CaseName, "side-hole-face-attached-region", StringComparison.Ordinal))
+ if (!string.IsNullOrWhiteSpace(outDir) && (string.Equals(report.CaseName, "side-hole-face-attached-region", StringComparison.Ordinal) || report.FirmamentV2?.SemanticIntent is not null))
{
var artifacts = SideHoleGoldenPathArtifacts.Write(outDir, report);
report = report with
{
- Milestone = "AIR-REGION-X13",
+ Milestone = report.FirmamentV2?.SemanticIntent is not null ? "AIR-FIRMAMENT-X5" : "AIR-REGION-X13",
Artifacts = artifacts,
- Diagnostics = report.Diagnostics.Append("air-region-x13-golden-path-artifacts-written").Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal).ToArray()
+ Diagnostics = report.Diagnostics.Append(report.FirmamentV2?.SemanticIntent is not null ? "air-firmament-x5-v2-side-hole-artifacts-written" : "air-region-x13-golden-path-artifacts-written").Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal).ToArray()
};
var jsonText = JsonSerializer.Serialize(report, JsonOptions);
var textText = AirTraceTextRenderer.Render(report);
diff --git a/docs/air-firmament-a1-firmament-fixture-corpus.md b/docs/air-firmament-a1-firmament-fixture-corpus.md
index 8089e126..ee4459a4 100644
--- a/docs/air-firmament-a1-firmament-fixture-corpus.md
+++ b/docs/air-firmament-a1-firmament-fixture-corpus.md
@@ -182,3 +182,7 @@ A2.2 expands the `fixtures/FirmamentV2/` metadata-only taxonomy with `RecordDeri
## AIR-FIRMAMENT-X4 fixture promotion
`fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture` is parser-backed for the controlled +X to -X side-hole region and reaches `region-parent-integrated` through the existing AIR Region golden trace path.
+
+## AIR-FIRMAMENT-X5 V2 side-hole artifact status
+
+`fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture` now has a generated-on-demand artifact workflow. Running `aetheris trace --fixture fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture --out-dir artifacts/air-firmament-x5/side-hole-v2` writes `side-hole-v2.step`, `side-hole-v2.trace.json`, `side-hole-v2.trace.txt`, and `manifest.json`. This records parser-backed V2 parity with the controlled AIR-REGION-X13 side-hole path without broad corpus migration or general side-hole support.
diff --git a/docs/air-firmament-x4-v2-side-hole-region.md b/docs/air-firmament-x4-v2-side-hole-region.md
index f77f3653..525411c2 100644
--- a/docs/air-firmament-x4-v2-side-hole-region.md
+++ b/docs/air-firmament-x4-v2-side-hole-region.md
@@ -66,3 +66,15 @@ Validation included CLI build/help/trace commands and focused parser/frontend te
## Next milestone recommendation
The next milestone should either generalize a second controlled side-hole variant with explicit admissibility limits or add a thin adapter object between `SideHoleIntent` and AIR Region construction so future V2 regions avoid direct trace-probe coupling. Do not broaden Boolean admission or arbitrary face/axis support until that adapter exists.
+
+## AIR-FIRMAMENT-X5 artifact workflow
+
+AIR-FIRMAMENT-X5 adds generated-on-demand artifacts for the same parser-backed V2 side-hole fixture. The command is:
+
+```bash
+dotnet run --project Aetheris.CLI -f net10.0 -- trace \
+ --fixture fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture \
+ --out-dir artifacts/air-firmament-x5/side-hole-v2
+```
+
+Expected files are `side-hole-v2.step`, `side-hole-v2.trace.json`, `side-hole-v2.trace.txt`, and `manifest.json` under `artifacts/air-firmament-x5/side-hole-v2/`. The artifact remains generated-on-demand and is parity-checked against the AIR-REGION-X13 controlled side-hole path on stable structural facts, not STEP byte equality.
diff --git a/docs/air-firmament-x5-v2-side-hole-artifacts-parity.md b/docs/air-firmament-x5-v2-side-hole-artifacts-parity.md
new file mode 100644
index 00000000..3fdbbe63
--- /dev/null
+++ b/docs/air-firmament-x5-v2-side-hole-artifacts-parity.md
@@ -0,0 +1,109 @@
+# AIR-FIRMAMENT-X5 — V2 side-hole artifacts and parity lock
+
+## Purpose and scope
+
+AIR-FIRMAMENT-X5 locks the parser-backed Firmament V2 side-hole source path as a generated-on-demand artifact workflow. The scope is exactly the controlled V2 side-hole fixture: STEP artifact, trace JSON artifact, trace text artifact, manifest artifact, and structural parity with the existing AIR-REGION-X13 controlled side-hole path.
+
+This milestone does not add geometry support or broaden region support.
+
+## Relationship to X4
+
+AIR-FIRMAMENT-X4 proved that the parser-backed V2 source can lower to the existing AIR Region golden trace chain:
+
+```text
+stage: region-parent-integrated
+parentIntegration: Integrated
+shellClosure: Closed
+stepSmoke: Succeeded
+```
+
+X5 keeps that real path and adds persistent, reproducible compiler artifacts when `--out-dir` is supplied.
+
+## Relationship to AIR-REGION-X13
+
+AIR-REGION-X13 locked the earlier metadata-controlled side-hole fixture as generated-on-demand artifacts. X5 gives the parser-backed V2 fixture its own clearly labeled artifact names and compares stable semantic facts against the X13 path instead of requiring STEP byte equality.
+
+## V2 fixture path
+
+```text
+fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture
+```
+
+## Artifact generation command
+
+```bash
+dotnet run --project Aetheris.CLI -f net10.0 -- trace \
+ --fixture fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture \
+ --out-dir artifacts/air-firmament-x5/side-hole-v2
+```
+
+## Expected output paths
+
+```text
+artifacts/air-firmament-x5/side-hole-v2/side-hole-v2.step
+artifacts/air-firmament-x5/side-hole-v2/side-hole-v2.trace.json
+artifacts/air-firmament-x5/side-hole-v2/side-hole-v2.trace.txt
+artifacts/air-firmament-x5/side-hole-v2/manifest.json
+```
+
+The V2 names deliberately do not reuse `side-hole.step`, `side-hole.trace.json`, or `side-hole.trace.txt` from the X13 metadata path.
+
+## Generated-on-demand artifact policy
+
+Artifacts are generated on demand and should not be committed as golden blobs. When `--out-dir` is present, the CLI creates the directory, writes stable files, reports artifact paths in trace JSON and trace text, writes `manifest.json`, and leaves the files on disk. Without `--out-dir`, normal trace output remains unchanged and no persistent artifacts are required.
+
+## Parity checks
+
+The parity lock compares stable structural facts shared by the V2 parser-backed path and the X13 controlled side-hole path:
+
+- both reach `region-parent-integrated`;
+- parent integration is `Integrated`;
+- shell closure is `Closed`;
+- STEP smoke is `Succeeded`;
+- entry face is `+X`;
+- exit / through face is `-X`;
+- radius is `1`;
+- tool is `Cylinder`;
+- `CutEntryLoop`, `CutExitLoop`, and `CutWallFace` evidence is present;
+- `RegionIntegrationPatch` is consumed/materialized in the parent integration evidence;
+- blockers are absent;
+- CIR remains analysis-only;
+- Boolean is unused / not generally admitted.
+
+## Deliberately not compared
+
+X5 does not require byte-for-byte STEP equality. The artifact is a stable generated inspection artifact, but parity is locked on normalized compiler facts and STEP smoke success rather than incidental file bytes.
+
+## What the V2 artifact proves
+
+The parser-backed Firmament V2 source for the controlled side-hole can reach the controlled AIR Region golden path and can emit a STEP/text/JSON/manifest artifact set on demand.
+
+## What it does not prove
+
+- No general side-hole support.
+- No arbitrary face/axis support.
+- No generic region support.
+- No Boolean general admission.
+- No CIR topology authority.
+- No shell, fillet, chamfer, surfacing, pattern, material, or FEA implementation.
+- No templates, concepts, PMI, or `where` parser support.
+- No STEP PMI export.
+
+## Tests run
+
+X5 validation should include the focused CLI artifact/parity tests plus the usual trace commands:
+
+```bash
+dotnet build Aetheris.CLI/Aetheris.CLI.csproj -f net10.0
+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/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture
+dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture --json
+dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/FirmamentV2/Region/valid/side-hole-v2.valid.firmfixture --out-dir artifacts/air-firmament-x5/side-hole-v2
+dotnet run --project Aetheris.CLI -f net10.0 -- trace --fixture fixtures/Firmament/Region/valid/side-hole-face-attached-region.valid.firmfixture
+dotnet test Aetheris.CLI.Tests/Aetheris.CLI.Tests.csproj --filter "FirmamentV2SideHoleArtifacts|FirmamentV2Parser|FirmamentV2SideHole|FirmamentV2Region|FirmamentSemanticRefs|FirmamentExpose|FirmamentFatArrow|FirmamentWith|FirmamentRecordDerivation|FirmamentV2|FirmamentFixtureCorpus|FirmFixture|Fixture|Trace|Region|SideHole|Primitive|ParserBacked|NotImplemented|Invalid"
+```
+
+## Next milestone recommendation
+
+Recommended next milestone: add a thin explicit V2 side-hole-to-AIR-region adapter object so future parser-backed region milestones avoid trace-probe coupling. Do not generalize arbitrary faces, axes, Boolean admission, or generic region topology until that adapter has its own narrow tests.
diff --git a/docs/air-region-x13-side-hole-golden-path-artifacts.md b/docs/air-region-x13-side-hole-golden-path-artifacts.md
index e809a558..72acb0eb 100644
--- a/docs/air-region-x13-side-hole-golden-path-artifacts.md
+++ b/docs/air-region-x13-side-hole-golden-path-artifacts.md
@@ -86,3 +86,7 @@ AIR-FIRMAMENT-A1 promotes the controlled side-hole fixture into the language-lev
## Firmament V2 syntax note
AIR-FIRMAMENT-A2 documents a V2 side-hole region syntax as design-level source shape. That snippet is not parser-backed yet and does not expand the controlled X13 golden path into general side-hole support, arbitrary face/axis support, production Boolean fallback, CIR topology authority, STEP exporter/importer behavior changes, or BRep topology behavior changes.
+
+## AIR-FIRMAMENT-X5 V2 parity note
+
+AIR-FIRMAMENT-X5 now gives the parser-backed Firmament V2 side-hole fixture its own generated-on-demand artifact path at `artifacts/air-firmament-x5/side-hole-v2/`. The V2 artifact uses clearly labeled `side-hole-v2.*` filenames and is structurally parity-checked against this X13 controlled side-hole path for stage, parent integration, shell closure, STEP smoke, +X entry, -X exit, radius-1 Cylinder cut evidence, loop/wall/patch materialization evidence, no blocker, CIR analysis-only status, and no Boolean general admission.