Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Verify Firmament V2 semantic holes through AP242

Yuechen Lid35b01900664
diff --git a/Aetheris.CLI.Tests/FirmamentV2SemanticHoleStepPipelineTests.cs b/Aetheris.CLI.Tests/FirmamentV2SemanticHoleStepPipelineTests.cs
new file mode 100644
index 00000000..35367581
--- /dev/null
+++ b/Aetheris.CLI.Tests/FirmamentV2SemanticHoleStepPipelineTests.cs
@@ -0,0 +1,67 @@
+using System.Text.RegularExpressions;
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Step242;
+
+namespace Aetheris.CLI.Tests;
+
+public sealed class FirmamentV2SemanticHoleStepPipelineTests
+{
+ public static TheoryData<string, double, int, int> Cases => new()
+ {
+ { "feature-v2-shaft-hole-through-step-verified", 480d - Math.PI * 1d * 1d * 6d, 1, 0 },
+ { "feature-v2-shaft-hole-blind-step-verified", 480d - Math.PI * 1d * 1d * 3d, 1, 0 },
+ { "feature-v2-counterbore-step-verified", 480d - ((Math.PI * 1d * 1d * 6d) + (Math.PI * ((2d * 2d) - (1d * 1d)) * 1d)), 2, 0 },
+ { "feature-v2-countersink-step-verified", 480d - ((Math.PI * 1d * 1d * 6d) + ((Math.PI * 1d / 3d) * ((2d * 2d) + (2d * 1d) + (1d * 1d))) - (Math.PI * 1d * 1d * 1d)), 1, 1 }
+ };
+
+ [Theory]
+ [MemberData(nameof(Cases))]
+ public void STEP_V2_X2_semantic_hole_step_verified_builds_emits_reimports_and_matches_volume(string fixtureId, double expectedVolume, int expectedCylinders, int expectedCones)
+ {
+ var fixturePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, $"../../../../fixtures/FirmamentV2/Hole/valid/{fixtureId}.valid.firmfixture"));
+ var outDir = Path.Combine(Path.GetTempPath(), "aetheris-step-v2-x2", Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(outDir);
+ var stepPath = Path.Combine(outDir, fixtureId + ".step");
+
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exit = Aetheris.CLI.CliRunner.Run(["build", fixturePath, "--out", stepPath, "--json"], stdout, stderr);
+
+ Assert.True(exit == 0, stderr.ToString());
+ Assert.True(File.Exists(stepPath), fixtureId + " reaches real build command");
+
+ var fixtureText = File.ReadAllText(fixturePath);
+ Assert.Contains("expected-stage: step-verified", fixtureText, StringComparison.Ordinal);
+ Assert.Contains("current-stage: step-verified", fixtureText, StringComparison.Ordinal);
+ Assert.Contains("roundtrip-required: true", fixtureText, StringComparison.Ordinal);
+ Assert.Contains("build-command: aetheris build", fixtureText, StringComparison.Ordinal);
+
+ var stepText = File.ReadAllText(stepPath);
+ Assert.Contains("ISO-10303-21", stepText, StringComparison.Ordinal);
+ Assert.True(CountStepEntities(stepText, "ADVANCED_FACE") > 0, fixtureId + " emits real STEP advanced faces");
+ Assert.True(CountStepEntities(stepText, "VERTEX_POINT") > 0, fixtureId + " emits STEP vertex topology marker");
+ Assert.DoesNotContain("controlled fixture only", stepText, StringComparison.OrdinalIgnoreCase);
+ Assert.DoesNotContain("trace", stepText, StringComparison.OrdinalIgnoreCase);
+
+ var import = Step242Importer.ImportBody(stepText);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));
+ var body = import.Value;
+ Assert.True(body.Topology.Faces.Count() > 0);
+ Assert.True(body.Topology.Vertices.Count() > 0);
+
+ var cylinderCount = body.Topology.Faces.Count(f => body.TryGetFaceSurface(f.Id, out var surface) && surface?.Kind == SurfaceGeometryKind.Cylinder);
+ var coneCount = body.Topology.Faces.Count(f => body.TryGetFaceSurface(f.Id, out var surface) && surface?.Kind == SurfaceGeometryKind.Cone);
+ Assert.Equal(expectedCylinders, cylinderCount);
+ Assert.Equal(expectedCones, coneCount);
+
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+ Assert.True(volume.Success, fixtureId + " volume analysis succeeds");
+ Assert.True(volume.Exact, fixtureId + " volume should use exact semantic hole interval analysis.");
+ Assert.Equal("analytic-box-minus-z-hole", volume.Method);
+ Assert.InRange(Math.Abs(volume.Volume - expectedVolume), 0d, 1e-8);
+ }
+
+ private static int CountStepEntities(string stepText, string entityName) =>
+ Regex.Matches(stepText, "=\\s*" + Regex.Escape(entityName) + "\\s*\\(", RegexOptions.CultureInvariant).Count;
+}
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 25804a22..42953bdb 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -132,7 +132,9 @@ internal static class AirTraceReportBuilder
var stepVerifiedDiagnostics = Array.Empty<string>();
if (isFirmamentV2 && string.Equals(fixture.ExpectedStage, "step-verified", StringComparison.Ordinal))
{
- var stepVerified = TryVerifyV2BoxStepFixture(fixture);
+ var stepVerified = string.Equals(fixture.Metadata.GetValueOrDefault("feature-area"), "semantic-hole", StringComparison.Ordinal)
+ ? TryVerifyV2SemanticHoleStepFixture(fixture)
+ : TryVerifyV2BoxStepFixture(fixture);
if (stepVerified.Succeeded)
{
actualStage = "step-verified";
@@ -201,6 +203,71 @@ internal static class AirTraceReportBuilder
+
+ private static (bool Succeeded, string[] Diagnostics) TryVerifyV2SemanticHoleStepFixture(FirmFixture fixture)
+ {
+ var diagnostics = new List<string> { "step-v2-x2-build-command-invoked" };
+ try
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-step-v2-x2-trace", Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(dir);
+ var stepPath = Path.Combine(dir, fixture.CaseName + ".step");
+ var build = FirmamentBuildAndExport.Run(fixture.Path, stepPath);
+ if (!build.IsSuccess)
+ {
+ diagnostics.Add("step-v2-x2-build-failed");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var stepText = File.ReadAllText(stepPath);
+ if (CountStepEntities(stepText, "ADVANCED_FACE") <= 0 || CountStepEntities(stepText, "VERTEX_POINT") <= 0)
+ {
+ diagnostics.Add("step-v2-x2-step-topology-markers-missing");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ if (stepText.Contains("trace", StringComparison.OrdinalIgnoreCase) || stepText.Contains("controlled fixture only", StringComparison.OrdinalIgnoreCase))
+ {
+ diagnostics.Add("step-v2-x2-trace-or-controlled-artifact-detected");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var import = Step242Importer.ImportBody(stepText);
+ if (!import.IsSuccess)
+ {
+ diagnostics.Add("step-v2-x2-step-reimport-failed");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+ var expectedVolume = fixture.CaseName switch
+ {
+ "feature-v2-shaft-hole-through-step-verified" => 480d - Math.PI * 6d,
+ "feature-v2-shaft-hole-blind-step-verified" => 480d - Math.PI * 3d,
+ "feature-v2-counterbore-step-verified" => 480d - ((Math.PI * 6d) + (Math.PI * 3d)),
+ "feature-v2-countersink-step-verified" => 480d - ((Math.PI * 6d) + (Math.PI * 7d / 3d) - Math.PI),
+ _ => double.NaN
+ };
+
+ if (!volume.Success || !volume.Exact || !double.IsFinite(expectedVolume) || Math.Abs(volume.Volume - expectedVolume) > 1e-8)
+ {
+ diagnostics.Add("step-v2-x2-volume-mismatch");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ diagnostics.Add("step-v2-x2-real-ap242-emitted");
+ diagnostics.Add("step-v2-x2-step-roundtrip-succeeded");
+ diagnostics.Add("step-v2-x2-topology-evidence-verified");
+ diagnostics.Add("step-v2-x2-volume-verified");
+ return (true, Stable(diagnostics).ToArray());
+ }
+ catch
+ {
+ diagnostics.Add("step-v2-x2-step-verification-threw");
+ return (false, Stable(diagnostics).ToArray());
+ }
+ }
+
private static (bool Succeeded, string[] Diagnostics) TryVerifyV2BoxStepFixture(FirmFixture fixture)
{
var diagnostics = new List<string> { "step-v2-a1-build-command-invoked" };
diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.cs
index 6fe7228a..c22e55b3 100644
--- a/Aetheris.CLI/StepAnalyzer.cs
+++ b/Aetheris.CLI/StepAnalyzer.cs
@@ -145,6 +145,12 @@ public sealed record VolumeAnalysisResult(
return new VolumeAnalysisResult(stepPath, true, vol, "model-unit", "model-unit^3", new VolumeBoundingBox(bbox.Min, bbox.Max), "analytic-torus", true, false, null, null, null, null, null, null, null, notes);
}
+ if (TryComputeAxisAlignedBoxWithZHoleVolume(body, bbox, out var zHoleVolume, out var zHoleBasis))
+ {
+ notes.Add(zHoleBasis);
+ return new VolumeAnalysisResult(stepPath, true, zHoleVolume, "model-unit", "model-unit^3", new VolumeBoundingBox(bbox.Min, bbox.Max), "analytic-box-minus-z-hole", true, false, null, null, null, null, null, null, null, notes);
+ }
+
var shellVolume = TryComputePlanarClosedShellVolume(body, shells, out var planarVolume, out var planarFailureReason);
if (shellVolume)
{
@@ -155,6 +161,121 @@ public sealed record VolumeAnalysisResult(
throw new InvalidOperationException(planarFailureReason ?? "Volume analysis currently supports canonical sphere, single-lateral-face cylinder, and enclosed planar closed-shell bodies only.");
}
+ private static bool TryComputeAxisAlignedBoxWithZHoleVolume(BrepBody body, BoundingBox3D bbox, out double volume, out string basis)
+ {
+ volume = 0d;
+ basis = string.Empty;
+
+ var cylinders = new List<(double Radius, double ZMin, double ZMax)>();
+ var cones = new List<(double RadiusAtZMin, double RadiusAtZMax, double ZMin, double ZMax)>();
+
+ foreach (var face in body.Topology.Faces)
+ {
+ if (!body.TryGetFaceSurface(face.Id, out var surface) || surface is null)
+ {
+ return false;
+ }
+
+ if (surface.Kind == SurfaceGeometryKind.Cylinder && surface.Cylinder is { } cylinder)
+ {
+ if (!IsZAxis(cylinder.Axis.ToVector())) return false;
+ if (!TryResolveFaceZSpan(body, face.Id, out var zMin, out var zMax)) return false;
+ cylinders.Add((cylinder.Radius, zMin, zMax));
+ continue;
+ }
+
+ if (surface.Kind == SurfaceGeometryKind.Cone && surface.Cone is { } cone)
+ {
+ if (!IsZAxis(cone.Axis.ToVector())) return false;
+ if (!TryResolveFaceZSpan(body, face.Id, out var zMin, out var zMax)) return false;
+ if (!TryResolveConeRadiiAtZSpan(body, face.Id, cone.Axis.ToVector(), new Point3D(cone.PlacementOrigin.X, cone.PlacementOrigin.Y, 0d), zMin, zMax, out var rMin, out var rMax)) return false;
+ cones.Add((rMin, rMax, zMin, zMax));
+ continue;
+ }
+
+ if (surface.Kind != SurfaceGeometryKind.Plane)
+ {
+ return false;
+ }
+ }
+
+ if (cylinders.Count == 0 && cones.Count == 0)
+ {
+ return false;
+ }
+
+ var baseVolume = (bbox.Max.X - bbox.Min.X) * (bbox.Max.Y - bbox.Min.Y) * (bbox.Max.Z - bbox.Min.Z);
+ var breakpoints = cylinders.SelectMany(c => new[] { c.ZMin, c.ZMax }).Distinct().OrderBy(z => z).ToArray();
+ var removed = 0d;
+ for (var i = 0; i + 1 < breakpoints.Length; i++)
+ {
+ var a = breakpoints[i];
+ var b = breakpoints[i + 1];
+ var mid = (a + b) / 2d;
+ var radius = cylinders.Where(c => mid >= c.ZMin - 1e-9 && mid <= c.ZMax + 1e-9).Select(c => c.Radius).DefaultIfEmpty(0d).Max();
+ removed += double.Pi * radius * radius * (b - a);
+ }
+
+ foreach (var cone in cones)
+ {
+ var h = cone.ZMax - cone.ZMin;
+ if (h <= 0d) return false;
+ var frustum = double.Pi * h / 3d * (cone.RadiusAtZMin * cone.RadiusAtZMin + cone.RadiusAtZMin * cone.RadiusAtZMax + cone.RadiusAtZMax * cone.RadiusAtZMax);
+ var overlapRadius = cylinders
+ .Where(c => c.ZMin <= cone.ZMin + 1e-9 && c.ZMax >= cone.ZMax - 1e-9)
+ .Select(c => c.Radius)
+ .DefaultIfEmpty(0d)
+ .Min();
+ removed += frustum - double.Pi * overlapRadius * overlapRadius * h;
+ }
+
+ volume = baseVolume - removed;
+ basis = "Exact analytic volume for an axis-aligned rectangular box with supported +Z semantic cylindrical/counterbore/countersink hole intervals.";
+ return double.IsFinite(volume) && volume > 0d;
+ }
+
+ private static bool TryResolveFaceZSpan(BrepBody body, FaceId faceId, out double zMin, out double zMax)
+ {
+ zMin = double.PositiveInfinity;
+ zMax = double.NegativeInfinity;
+ if (!body.Topology.TryGetFace(faceId, out var face) || face is null) return false;
+ foreach (var loopId in face.LoopIds)
+ {
+ var vertices = TryBuildOrientedLoopVertices(body, loopId, out _);
+ if (vertices is null) return false;
+ foreach (var vertex in vertices)
+ {
+ zMin = double.Min(zMin, vertex.Z);
+ zMax = double.Max(zMax, vertex.Z);
+ }
+ }
+
+ return double.IsFinite(zMin) && double.IsFinite(zMax) && zMax > zMin;
+ }
+
+ private static bool TryResolveConeRadiiAtZSpan(BrepBody body, FaceId faceId, Vector3D axis, Point3D axisPoint, double zMin, double zMax, out double radiusAtZMin, out double radiusAtZMax)
+ {
+ radiusAtZMin = 0d;
+ radiusAtZMax = 0d;
+ if (!body.Topology.TryGetFace(faceId, out var face) || face is null) return false;
+ foreach (var loopId in face.LoopIds)
+ {
+ var vertices = TryBuildOrientedLoopVertices(body, loopId, out _);
+ if (vertices is null) return false;
+ foreach (var vertex in vertices)
+ {
+ var radial = new Vector3D(vertex.X - axisPoint.X, vertex.Y - axisPoint.Y, 0d).Length;
+ if (double.Abs(vertex.Z - zMin) <= 1e-7) radiusAtZMin = double.Max(radiusAtZMin, radial);
+ if (double.Abs(vertex.Z - zMax) <= 1e-7) radiusAtZMax = double.Max(radiusAtZMax, radial);
+ }
+ }
+
+ return radiusAtZMin > 0d && radiusAtZMax > 0d;
+ }
+
+ private static bool IsZAxis(Vector3D axis) =>
+ double.Abs(axis.X) <= 1e-9 && double.Abs(axis.Y) <= 1e-9 && double.Abs(double.Abs(axis.Z) - 1d) <= 1e-9;
+
private static BrepBodyShellRepresentation ResolveShellRepresentationForVolume(BrepBody body)
{
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs
index b63194f1..ac75f5d9 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs
@@ -33,6 +33,8 @@ public sealed class FirmamentV2SemanticHoleTests
Assert.Equal(AirHoleStackKind.Counterbore, feature.Stack.Kind);
Assert.Equal([AirHoleStackComponentKind.Counterbore, AirHoleStackComponentKind.Shaft], feature.Stack.Components.Select(c => c.Kind).ToArray());
Assert.DoesNotContain("ProfileStackExtrudeSpec", feature.Provenance.ConstructionHistoryKind);
+ Assert.DoesNotContain("CylinderCut", feature.Provenance.ConstructionHistoryKind);
+ Assert.DoesNotContain("ConeCut", feature.Provenance.ConstructionHistoryKind);
}
[Theory]
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 90cff7a2..7f85ec22 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -3,6 +3,7 @@ using Aetheris.Kernel.Core.Results;
using Aetheris.Kernel.Core.Step242;
using Aetheris.Kernel.Firmament.Execution;
using Aetheris.Kernel.Firmament.FirmamentV2;
+using Aetheris.Kernel.Firmament.Materializer;
namespace Aetheris.Kernel.Firmament;
@@ -40,6 +41,11 @@ public static class FirmamentBuildAndExport
var v2Parse = FirmamentV2Parser.Parse(sourceText);
if (v2Parse.IsSuccess && v2Parse.Document is not null)
{
+ if (TryExportV2SemanticHoleBody(v2Parse.Document) is { } semanticHoleExport)
+ {
+ return semanticHoleExport;
+ }
+
var lowering = FirmamentV2BuildLowering.LowerPrimitiveBridge(v2Parse.Document);
if (!lowering.IsSuccess)
{
@@ -77,6 +83,53 @@ public static class FirmamentBuildAndExport
return FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
}
+
+ private static KernelResult<FirmamentStepExportResult>? TryExportV2SemanticHoleBody(FirmamentV2Document document)
+ {
+ if (document.ModifyBlocks is not { Count: > 0 })
+ {
+ return null;
+ }
+
+ if (document.Solids.Count != 1 || document.Solid.Primitive is not FirmamentV2BoxRecord box || box.Size.Count != 3)
+ {
+ return null;
+ }
+
+ var semanticHoles = FirmamentV2SemanticHoleLowering.LowerSemanticHoles(document);
+ if (semanticHoles.Count != 1)
+ {
+ return null;
+ }
+
+ var feature = semanticHoles[0];
+ var host = new AirHoleSimpleShaftHost(box.Size[0], box.Size[1], -box.Size[2] / 2d, box.Size[2] / 2d);
+ var materialized = AirHoleSimpleShaftMaterializer.Execute(feature, host);
+ if (!materialized.Succeeded || materialized.Body is null)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(materialized.Diagnostics.Select(d => new Kernel.Core.Diagnostics.KernelDiagnostic(
+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,
+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,
+ d,
+ "FirmamentV2.SemanticHoleBuild")).ToArray());
+ }
+
+ var step = Step242Exporter.ExportBody(materialized.Body);
+ if (!step.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
+ }
+
+ return KernelResult<FirmamentStepExportResult>.Success(
+ new FirmamentStepExportResult(
+ step.Value,
+ feature.FeatureId,
+ 0,
+ nameof(AirHoleSimpleShaftMaterializer),
+ feature.Stack.Kind.ToString(),
+ DatumInspection: [],
+ DimensionInspection: []));
+ }
private static string ResolveDefaultOutputPath(string fullSourcePath)
{
var root = FindRepositoryRoot(Path.GetDirectoryName(fullSourcePath)!);
diff --git a/docs/implementation/step-v2-x2-semantic-holes-ap242.md b/docs/implementation/step-v2-x2-semantic-holes-ap242.md
new file mode 100644
index 00000000..a7fa622d
--- /dev/null
+++ b/docs/implementation/step-v2-x2-semantic-holes-ap242.md
@@ -0,0 +1,65 @@
+# STEP-V2-X2 semantic holes AP242 verification
+
+STEP-V2-X2 promotes the already-supported Firmament V2 semantic hole source forms from feature-air coverage to AP242 `step-verified` fixture coverage. It does not introduce new hole syntax or new hole semantics.
+
+## Fixtures
+
+The MVP fixtures live under `fixtures/FirmamentV2/Hole/valid/`:
+
+- `feature-v2-shaft-hole-through-step-verified.valid.firmfixture`
+- `feature-v2-shaft-hole-blind-step-verified.valid.firmfixture`
+- `feature-v2-counterbore-step-verified.valid.firmfixture`
+- `feature-v2-countersink-step-verified.valid.firmfixture`
+
+Each fixture uses a `10 x 8 x 6 mm` V2 `Box` host and a single real `modify base { hole<...> ... }` declaration from the HOLE-X4 source hook.
+
+## Command path
+
+The integration proof invokes the production CLI build path:
+
+```bash
+aetheris build <fixture> --out <path> --json
+```
+
+In tests this is executed through `Aetheris.CLI.CliRunner.Run(["build", fixture, "--out", stepPath, "--json"], ...)`. The build path lowers the V2 semantic hole to the existing `AirHoleFeature` / profile-stack materialization route, produces a real `BrepBody`, and exports through `Step242Exporter.ExportBody`. The fixtures do not use hardcoded STEP templates and are not trace-only artifacts.
+
+## AP242 verification checks
+
+For every fixture, `FirmamentV2SemanticHoleStepPipelineTests` verifies:
+
+1. the real build command exits successfully;
+2. an AP242 STEP file is emitted on disk;
+3. the file contains `ISO-10303-21`, `ADVANCED_FACE`, and `VERTEX_POINT` topology markers;
+4. trace-only and controlled-fixture sentinel text is absent;
+5. `Step242Importer.ImportBody` reimports the emitted STEP;
+6. imported topology contains faces and vertices;
+7. stable semantic/topological evidence is present via imported analytic surface families;
+8. exact volume analysis matches independent hand formulas.
+
+## Volume formulas
+
+All expected volumes are computed from fixture dimensions, not copied from implementation output:
+
+- shaft through: `480 - pi * 1^2 * 6`
+- shaft blind: `480 - pi * 1^2 * 3`
+- counterbore: `480 - (pi * 1^2 * 6 + pi * (2^2 - 1^2) * 1)`
+- countersink: with shaft radius `1`, entry radius `2`, included angle `90`, derived sink depth `1`: `480 - (pi * 1^2 * 6 + (pi * 1 / 3) * (2^2 + 2 * 1 + 1^2) - pi * 1^2 * 1)`
+
+The CLI volume analyzer now recognizes this bounded class as `analytic-box-minus-z-hole`: an axis-aligned rectangular box with supported +Z semantic cylindrical, counterbore, or countersink intervals.
+
+## Topology and semantic evidence
+
+Exact topology counts are intentionally not part of the AP242 contract for these hole fixtures because STEP import can assign canonical IDs differently as the exporter/importer evolves. The stable evidence is instead:
+
+- all variants: `ADVANCED_FACE > 0`, `VERTEX_POINT > 0`, reimport succeeds;
+- shaft through/blind: one cylindrical wall face;
+- counterbore: two cylindrical wall faces, one for the through shaft and one for the wider entry bore;
+- countersink: one cylindrical shaft wall and one conical entry face.
+
+## Relationship to MVP readiness and HOLE-X1-X4
+
+HOLE-X1 introduced semantic `AirHoleFeature`; HOLE-X2 materialized simple shaft holes; HOLE-X3 added counterbore/countersink stack components; HOLE-X4 added the Firmament V2 source hook. STEP-V2-X2 proves that these existing semantics now travel through the real build/export/reimport path and satisfy the MVP readiness contract for the four bounded top-face hole variants above.
+
+## Deferred
+
+The milestone still defers standards/fit libraries, M-size tables, ISO/ASME semantics, threads/taps, drill tips, hole groups, patterns, `upToFace`, `upToNext`, arbitrary datum placement, non-planar entry faces, multi-body propagation, raw 3D boolean authoring, side-hole reroute, chamfer/fillet/draft, PMI, and DFM enforcement.
diff --git a/docs/mvp/firmament-v2-ap242-mvp-readiness-contract.md b/docs/mvp/firmament-v2-ap242-mvp-readiness-contract.md
index 5151ee5c..6241281b 100644
--- a/docs/mvp/firmament-v2-ap242-mvp-readiness-contract.md
+++ b/docs/mvp/firmament-v2-ap242-mvp-readiness-contract.md
@@ -230,3 +230,7 @@ MVP is pitchable when:
* no MVP claim relies on hardcoded STEP templates, trace-only output, or non-exported AIR.
If it does not emit valid AP242 through the real exporter, it is not MVP-ready.
+
+## Implementation notes
+
+* STEP-V2-X2 semantic hole AP242 fixture hardening is documented in `docs/implementation/step-v2-x2-semantic-holes-ap242.md`.
diff --git a/fixtures/FirmamentV2/Hole/valid/feature-v2-counterbore-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/feature-v2-counterbore-step-verified.valid.firmfixture
new file mode 100644
index 00000000..98d18ec3
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/valid/feature-v2-counterbore-step-verified.valid.firmfixture
@@ -0,0 +1,35 @@
+// fixture-id: feature-v2-counterbore-step-verified
+// case: feature-v2-counterbore-step-verified
+// category: Hole
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(Counterbore)
+// dimensions: base box 10 x 8 x 6; shaft radius 1 through depth 6; counterbore radius 2 depth 1
+// units: mm
+// tier: 2
+// mvp-required: true
+// feature-area: semantic-hole
+// build-command: aetheris build
+// expected-volume: 480 - (pi * 1^2 * 6 + pi * (2^2 - 1^2) * 1)
+// expected-topology: advanced_face>0, vertex_point>0, shaft-cylinder=true, counterbore-cylinder=true
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X2 semantic counterbore fixture; verified through real build/export, Step242Exporter, reimport, topology markers, and analytic volume.
+model FeatureV2CounterboreStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<counterbore> mount {
+ on: face(+Z)
+ center: [0, 0]
+ shaftDiameter: 2
+ counterboreDiameter: 4
+ counterboreDepth: 1
+ end: throughAll
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/Hole/valid/feature-v2-countersink-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/feature-v2-countersink-step-verified.valid.firmfixture
new file mode 100644
index 00000000..610df06d
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/valid/feature-v2-countersink-step-verified.valid.firmfixture
@@ -0,0 +1,35 @@
+// fixture-id: feature-v2-countersink-step-verified
+// case: feature-v2-countersink-step-verified
+// category: Hole
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(Countersink)
+// dimensions: base box 10 x 8 x 6; shaft radius 1 through depth 6; countersink entry radius 2, included angle 90, derived sink depth 1
+// units: mm
+// tier: 2
+// mvp-required: true
+// feature-area: semantic-hole
+// build-command: aetheris build
+// expected-volume: 480 - (pi * 1^2 * 6 + (pi * 1 / 3) * (2^2 + 2 * 1 + 1^2) - pi * 1^2 * 1)
+// expected-topology: advanced_face>0, vertex_point>0, shaft-cylinder=true, countersink-cone=true
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X2 semantic countersink fixture; verified through real build/export, Step242Exporter, reimport, topology markers, and analytic volume.
+model FeatureV2CountersinkStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<countersink> flatHead {
+ on: face(+Z)
+ center: [0, 0]
+ shaftDiameter: 2
+ countersinkDiameter: 4
+ countersinkAngle: 90
+ end: throughAll
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-blind-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-blind-step-verified.valid.firmfixture
new file mode 100644
index 00000000..66af1fc7
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-blind-step-verified.valid.firmfixture
@@ -0,0 +1,33 @@
+// fixture-id: feature-v2-shaft-hole-blind-step-verified
+// case: feature-v2-shaft-hole-blind-step-verified
+// category: Hole
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(SimpleShaft)
+// dimensions: base box 10 x 8 x 6; shaft radius 1; blind depth 3
+// units: mm
+// tier: 2
+// mvp-required: true
+// feature-area: semantic-hole
+// build-command: aetheris build
+// expected-volume: 480 - pi * 1^2 * 3
+// expected-topology: advanced_face>0, vertex_point>0, cylindrical-wall-face=true, blind-bottom-face=true
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X2 semantic blind shaft-hole fixture; verified through real build/export, Step242Exporter, reimport, topology markers, and analytic volume.
+model FeatureV2ShaftHoleBlindStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<shaft> mount {
+ on: face(+Z)
+ center: [0, 0]
+ diameter: 2
+ end: depth 3
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-through-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-through-step-verified.valid.firmfixture
new file mode 100644
index 00000000..05c0e02a
--- /dev/null
+++ b/fixtures/FirmamentV2/Hole/valid/feature-v2-shaft-hole-through-step-verified.valid.firmfixture
@@ -0,0 +1,33 @@
+// fixture-id: feature-v2-shaft-hole-through-step-verified
+// case: feature-v2-shaft-hole-through-step-verified
+// category: Hole
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(SimpleShaft)
+// dimensions: base box 10 x 8 x 6; shaft radius 1; through depth 6
+// units: mm
+// tier: 2
+// mvp-required: true
+// feature-area: semantic-hole
+// build-command: aetheris build
+// expected-volume: 480 - pi * 1^2 * 6
+// expected-topology: advanced_face>0, vertex_point>0, cylindrical-wall-face=true
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X2 semantic shaft through-hole fixture; verified through real build/export, Step242Exporter, reimport, topology markers, and analytic volume.
+model FeatureV2ShaftHoleThroughStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<shaft> mount {
+ on: face(+Z)
+ center: [0, 0]
+ diameter: 2
+ end: throughAll
+ }
+ }
+}