Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add STEP V2 multi-hole composition verification

Yuechen Li6dbb9223ad34
diff --git a/Aetheris.CLI.Tests/FirmamentV2SourceCompositionStepPipelineTests.cs b/Aetheris.CLI.Tests/FirmamentV2SourceCompositionStepPipelineTests.cs
index 9f995b0f..5ac65ef8 100644
--- a/Aetheris.CLI.Tests/FirmamentV2SourceCompositionStepPipelineTests.cs
+++ b/Aetheris.CLI.Tests/FirmamentV2SourceCompositionStepPipelineTests.cs
@@ -13,6 +13,60 @@ public sealed class FirmamentV2SourceCompositionStepPipelineTests
{ "RecordDerivation/valid/derivation-v2-with-chained-twice-step-verified.valid.firmfixture", "derivation-v2-with-chained-twice-step-verified", 12d * 8d * 7d }
};
+
+ public static TheoryData<string, string, double> CompositeCases => new()
+ {
+ { "Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture", "composite-v2-two-independent-holes-step-verified", 480d - 2d * Math.PI * 1d * 1d * 6d },
+ { "Composite/valid/composite-v2-adjacent-non-overlapping-holes-step-verified.valid.firmfixture", "composite-v2-adjacent-non-overlapping-holes-step-verified", 480d - 2d * Math.PI * 1d * 1d * 6d }
+ };
+
+ [Theory]
+ [MemberData(nameof(CompositeCases))]
+ public void STEP_V2_X4_composite_multi_hole_fixtures_build_emit_reimport_and_match_evidence(string fixtureRelativePath, string fixtureId, double expectedVolume)
+ {
+ var fixturePath = Fixture(fixtureRelativePath);
+ var stepPath = TempStep(fixtureId);
+
+ var (stepText, fixtureText) = BuildAndReadStep(fixturePath, stepPath, fixtureId);
+ AssertStageHonesty(fixtureText, "multi-feature-composition", 4);
+ Assert.Contains("AirHoleFeature(SimpleShaft) x2", fixtureText, 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");
+ AssertNoTraceOnlyStep(stepText);
+
+ var import = Step242Importer.ImportBody(stepText);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));
+ var body = import.Value;
+ Assert.Equal(2, body.Topology.Faces.Count(f => body.TryGetFaceSurface(f.Id, out var surface) && surface?.Kind == SurfaceGeometryKind.Cylinder));
+
+ var volume = StepAnalyzer.AnalyzeVolume(stepPath);
+ Assert.True(volume.Success, fixtureId + " volume analysis succeeds");
+ Assert.True(volume.Exact, fixtureId + " volume should use exact semantic multi-hole interval analysis");
+ Assert.Equal("analytic-box-minus-z-hole", volume.Method);
+ Assert.InRange(Math.Abs(volume.Volume - expectedVolume), 0d, 1e-8);
+ }
+
+ [Fact]
+ public void STEP_V2_X4_overlapping_composite_holes_reject_with_clear_diagnostic()
+ {
+ const string fixtureId = "composite-v2-overlapping-holes-rejected-with-clear-diagnostic";
+ var fixturePath = Fixture("Composite/invalid/composite-v2-overlapping-holes-rejected-with-clear-diagnostic.invalid.firmfixture");
+ var stepPath = TempStep(fixtureId);
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+
+ var exit = Aetheris.CLI.CliRunner.Run(["build", fixturePath, "--out", stepPath, "--json"], stdout, stderr);
+
+ Assert.NotEqual(0, exit);
+ var combined = stdout.ToString() + stderr.ToString();
+ Assert.Contains("firmament-v2-semantic-hole-overlap", combined, StringComparison.Ordinal);
+ Assert.False(File.Exists(stepPath), "invalid overlapping fixture must not emit success AP242");
+ var fixtureText = File.ReadAllText(fixturePath);
+ Assert.Contains("current-stage: deterministic rejection", fixtureText, StringComparison.Ordinal);
+ Assert.Contains("expected-diagnostic: firmament-v2-semantic-hole-overlap", fixtureText, StringComparison.Ordinal);
+ }
+
[Theory]
[MemberData(nameof(DerivationCases))]
public void STEP_V2_X3_derivation_fixtures_build_emit_reimport_and_match_box_evidence(string fixtureRelativePath, string fixtureId, double expectedVolume)
@@ -21,7 +75,7 @@ public sealed class FirmamentV2SourceCompositionStepPipelineTests
var stepPath = TempStep(fixtureId);
var (stepText, fixtureText) = BuildAndReadStep(fixturePath, stepPath, fixtureId);
- AssertStageHonesty(fixtureText, "derivation");
+ AssertStageHonesty(fixtureText, "derivation", 3);
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");
@@ -47,7 +101,7 @@ public sealed class FirmamentV2SourceCompositionStepPipelineTests
var stepPath = TempStep(fixtureId);
var (stepText, fixtureText) = BuildAndReadStep(fixturePath, stepPath, fixtureId);
- AssertStageHonesty(fixtureText, "semantic-reference");
+ AssertStageHonesty(fixtureText, "semantic-reference", 3);
Assert.Contains("on: top", fixtureText, StringComparison.Ordinal);
Assert.Contains("face(+Z) => top", fixtureText, StringComparison.Ordinal);
@@ -82,9 +136,9 @@ public sealed class FirmamentV2SourceCompositionStepPipelineTests
return (stepText, File.ReadAllText(fixturePath));
}
- private static void AssertStageHonesty(string fixtureText, string featureArea)
+ private static void AssertStageHonesty(string fixtureText, string featureArea, int tier)
{
- Assert.Contains("tier: 3", fixtureText, StringComparison.Ordinal);
+ Assert.Contains($"tier: {tier}", fixtureText, StringComparison.Ordinal);
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);
diff --git a/Aetheris.CLI/AirTrace.cs b/Aetheris.CLI/AirTrace.cs
index 0cbf7a6f..663a07d3 100644
--- a/Aetheris.CLI/AirTrace.cs
+++ b/Aetheris.CLI/AirTrace.cs
@@ -133,7 +133,7 @@ internal static class AirTraceReportBuilder
if (isFirmamentV2 && string.Equals(fixture.ExpectedStage, "step-verified", StringComparison.Ordinal))
{
var featureArea = fixture.Metadata.GetValueOrDefault("feature-area");
- var stepVerified = string.Equals(featureArea, "semantic-hole", StringComparison.Ordinal) || string.Equals(featureArea, "semantic-reference", StringComparison.Ordinal)
+ var stepVerified = string.Equals(featureArea, "semantic-hole", StringComparison.Ordinal) || string.Equals(featureArea, "semantic-reference", StringComparison.Ordinal) || string.Equals(featureArea, "multi-feature-composition", StringComparison.Ordinal)
? TryVerifyV2SemanticHoleStepFixture(fixture)
: TryVerifyV2BoxStepFixture(fixture);
if (stepVerified.Succeeded)
@@ -142,10 +142,19 @@ internal static class AirTraceReportBuilder
}
stepVerifiedDiagnostics = stepVerified.Diagnostics;
}
+ else if (isFirmamentV2 && string.Equals(fixture.ExpectedStage, "deterministic rejection", StringComparison.Ordinal))
+ {
+ var rejection = TryVerifyV2DeterministicBuildRejection(fixture);
+ if (rejection.Succeeded)
+ {
+ actualStage = "deterministic rejection";
+ }
+ stepVerifiedDiagnostics = rejection.Diagnostics;
+ }
var expectedStageSatisfied = string.IsNullOrWhiteSpace(fixture.ExpectedStage) || string.Equals(actualStage, fixture.ExpectedStage, StringComparison.Ordinal);
var expectationSatisfied = fixture.Expectation == "valid"
? frontend.ParseSucceeded && expectedStageSatisfied && (profileEmissionProbe?.Succeeded ?? true)
- : !frontend.ParseSucceeded && expectedStageSatisfied;
+ : ((!frontend.ParseSucceeded) || string.Equals(actualStage, "deterministic rejection", StringComparison.Ordinal)) && expectedStageSatisfied;
var fxDiagnostics = Stable([.. fixture.Diagnostics, .. frontend.Diagnostics, .. profileEmissionProbe?.Diagnostics ?? [], .. stepVerifiedDiagnostics, "air-x8-parser-backed-fixture-trace-created", "air-x11-parser-backed-fixture-loaded", isFirmamentV2 ? "firmament-v2-parser-invoked" : "air-x11-firmament-parser-invoked", frontend.ParseSucceeded ? (isFirmamentV2 ? "firmament-v2-parse-succeeded" : "air-x11-firmament-parse-succeeded") : (isFirmamentV2 ? "firmament-v2-parse-failed" : "air-x11-firmament-parse-failed"), expectationSatisfied ? "air-x11-parser-backed-expectation-satisfied" : "air-x11-profile-emission-expectation-not-satisfied"]).ToArray();
var featureAir = frontend.FeatureAir is null
@@ -205,6 +214,43 @@ internal static class AirTraceReportBuilder
+
+ private static (bool Succeeded, string[] Diagnostics) TryVerifyV2DeterministicBuildRejection(FirmFixture fixture)
+ {
+ var diagnostics = new List<string> { "step-v2-x4-build-command-invoked" };
+ try
+ {
+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-step-v2-x4-reject-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 || File.Exists(stepPath))
+ {
+ diagnostics.Add("step-v2-x4-invalid-build-unexpectedly-succeeded");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ var messages = string.Join("\n", build.Diagnostics.Select(d => d.Message));
+ if (fixture.Metadata.TryGetValue("expected-diagnostic", out var expected) && !messages.Contains(expected, StringComparison.Ordinal))
+ {
+ diagnostics.Add("step-v2-x4-expected-diagnostic-missing");
+ return (false, Stable(diagnostics).ToArray());
+ }
+
+ if (fixture.Metadata.TryGetValue("expected-diagnostic", out var expectedDiagnostic))
+ {
+ diagnostics.Add(expectedDiagnostic);
+ }
+ diagnostics.Add("step-v2-x4-deterministic-rejection-verified");
+ return (true, Stable(diagnostics).ToArray());
+ }
+ catch
+ {
+ diagnostics.Add("step-v2-x4-rejection-verification-threw");
+ return (false, Stable(diagnostics).ToArray());
+ }
+ }
+
private static (bool Succeeded, string[] Diagnostics) TryVerifyV2SemanticHoleStepFixture(FirmFixture fixture)
{
var diagnostics = new List<string> { "step-v2-x2-build-command-invoked" };
diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.cs
index c22e55b3..339104a4 100644
--- a/Aetheris.CLI/StepAnalyzer.cs
+++ b/Aetheris.CLI/StepAnalyzer.cs
@@ -166,7 +166,7 @@ public sealed record VolumeAnalysisResult(
volume = 0d;
basis = string.Empty;
- var cylinders = new List<(double Radius, double ZMin, double ZMax)>();
+ var cylinders = new List<(double CenterX, double CenterY, 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)
@@ -180,7 +180,7 @@ public sealed record VolumeAnalysisResult(
{
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));
+ cylinders.Add((cylinder.Origin.X, cylinder.Origin.Y, cylinder.Radius, zMin, zMax));
continue;
}
@@ -212,8 +212,11 @@ public sealed record VolumeAnalysisResult(
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);
+ var active = cylinders.Where(c => mid >= c.ZMin - 1e-9 && mid <= c.ZMax + 1e-9).ToArray();
+ var removedArea = active
+ .GroupBy(c => (Math.Round(c.CenterX, 9), Math.Round(c.CenterY, 9)))
+ .Sum(g => double.Pi * g.Max(c => c.Radius) * g.Max(c => c.Radius));
+ removed += removedArea * (b - a);
}
foreach (var cone in cones)
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs
index 9c44e231..c03093cb 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2ParserTests.cs
@@ -1,3 +1,4 @@
+using Aetheris.Kernel.Core.Air;
using Aetheris.Kernel.Firmament;
using Aetheris.Kernel.Firmament.FirmamentV2;
@@ -122,6 +123,22 @@ public sealed class FirmamentV2ParserTests
Assert.Equal([12, 8, 7], parse.Document.Solids.Single(s => s.Name == "taller").Box!.Size);
}
+
+ [Fact]
+ public void FirmamentV2Parser_CompositeMultipleHoles_ParseAndLowerAsDistinctAirHoleFeatures()
+ {
+ var result = FirmamentV2Parser.Parse(Source("Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture"));
+ Assert.True(result.IsSuccess, string.Join(", ", result.Diagnostics));
+ var holes = Assert.Single(result.Document!.ModifyBlocks!).SemanticHoles;
+ Assert.Equal(["leftMount", "rightMount"], holes.Select(h => h.Name).ToArray());
+ Assert.All(holes, h => Assert.Equal(FirmamentV2SemanticHoleVariant.Shaft, h.Variant));
+
+ var lowered = FirmamentV2SemanticHoleLowering.LowerSemanticHoles(result.Document);
+ Assert.Equal(2, lowered.Count);
+ Assert.Equal(["base.leftMount", "base.rightMount"], lowered.Select(h => h.FeatureId).ToArray());
+ Assert.All(lowered, h => Assert.Equal(AirHoleStackKind.SimpleShaft, h.Stack.Kind));
+ }
+
[Fact]
public void FirmamentV2Parser_SemanticFaceAlias_ResolvesBeforeHoleLowering()
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 7f85ec22..9a7dcfc2 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -97,24 +97,37 @@ public static class FirmamentBuildAndExport
}
var semanticHoles = FirmamentV2SemanticHoleLowering.LowerSemanticHoles(document);
- if (semanticHoles.Count != 1)
+ if (semanticHoles.Count == 0)
{
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)
+ Aetheris.Kernel.Core.Brep.BrepBody? body;
+ IReadOnlyList<string> diagnostics;
+ if (semanticHoles.Count == 1)
{
- 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 materialized = AirHoleSimpleShaftMaterializer.Execute(feature, host);
+ body = materialized.Body;
+ diagnostics = materialized.Diagnostics;
+ if (!materialized.Succeeded || body is null)
+ {
+ return SemanticHoleFailure(diagnostics);
+ }
+ }
+ else
+ {
+ var materialized = AirHoleCompositeMaterializer.Execute(semanticHoles, host);
+ body = materialized.Body;
+ diagnostics = materialized.Diagnostics;
+ if (!materialized.Succeeded || body is null)
+ {
+ return SemanticHoleFailure(diagnostics);
+ }
}
- var step = Step242Exporter.ExportBody(materialized.Body);
+ var step = Step242Exporter.ExportBody(body);
if (!step.IsSuccess)
{
return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
@@ -125,11 +138,19 @@ public static class FirmamentBuildAndExport
step.Value,
feature.FeatureId,
0,
- nameof(AirHoleSimpleShaftMaterializer),
- feature.Stack.Kind.ToString(),
+ semanticHoles.Count == 1 ? nameof(AirHoleSimpleShaftMaterializer) : nameof(AirHoleCompositeMaterializer),
+ semanticHoles.Count == 1 ? feature.Stack.Kind.ToString() : "CompositeSimpleShaft",
DatumInspection: [],
DimensionInspection: []));
}
+
+ private static KernelResult<FirmamentStepExportResult> SemanticHoleFailure(IEnumerable<string> diagnostics) =>
+ KernelResult<FirmamentStepExportResult>.Failure(diagnostics.Select(d => new Kernel.Core.Diagnostics.KernelDiagnostic(
+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,
+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,
+ d,
+ "FirmamentV2.SemanticHoleBuild")).ToArray());
+
private static string ResolveDefaultOutputPath(string fullSourcePath)
{
var root = FindRepositoryRoot(Path.GetDirectoryName(fullSourcePath)!);
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs
new file mode 100644
index 00000000..1bc70f46
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs
@@ -0,0 +1,84 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+internal sealed record AirHoleCompositeMaterializationResult(
+ bool Succeeded,
+ BrepBody? Body,
+ IReadOnlyList<AirHoleSimpleShaftMaterializationPlan> Plans,
+ IReadOnlyList<string> Diagnostics);
+
+internal static class AirHoleCompositeMaterializer
+{
+ private const double Tolerance = 1e-9;
+
+ public static AirHoleCompositeMaterializationResult Execute(IReadOnlyList<AirHoleFeature> features, AirHoleSimpleShaftHost host)
+ {
+ var diagnostics = new List<string> { "air-hole-x4 composite semantic hole planner started." };
+ if (features.Count == 0)
+ {
+ diagnostics.Add("air-hole-x4 rejected: composite materialization requires at least one semantic AirHoleFeature.");
+ return new(false, null, [], diagnostics);
+ }
+
+ var plans = new List<AirHoleSimpleShaftMaterializationPlan>(features.Count);
+ foreach (var feature in features)
+ {
+ var planResult = AirHoleSimpleShaftMaterializer.TryCreatePlan(feature, host);
+ diagnostics.AddRange(planResult.Diagnostics.Select(d => $"{feature.FeatureId}: {d}"));
+ if (!planResult.Succeeded || planResult.Plan is null)
+ {
+ diagnostics.Add($"air-hole-x4 rejected: semantic feature {feature.FeatureId} cannot enter bounded composite materialization.");
+ return new(false, null, plans, diagnostics);
+ }
+
+ if (planResult.Plan.StackKind != AirHoleStackKind.SimpleShaft)
+ {
+ diagnostics.Add($"air-hole-x4 rejected: composite materialization is limited to circular shaft holes for STEP-V2-X4; feature {feature.FeatureId} is {planResult.Plan.StackKind}.");
+ return new(false, null, plans, diagnostics);
+ }
+
+ plans.Add(planResult.Plan);
+ }
+
+ var zAxis = Direction3D.Create(new Vector3D(0, 0, 1));
+ var xAxis = Direction3D.Create(new Vector3D(1, 0, 0));
+ var extents = new AxisAlignedBoxExtents(-host.Width / 2d, host.Width / 2d, -host.Depth / 2d, host.Depth / 2d, host.ZMin, host.ZMax);
+ var composition = new SafeBooleanComposition(extents, [], SafeBooleanRootDescriptor.FromBox(extents));
+
+ foreach (var plan in plans)
+ {
+ var span = plan.CutZMin <= host.ZMin + Tolerance && plan.CutZMax >= host.ZMax - Tolerance
+ ? SupportedBooleanHoleSpanKind.Through
+ : (Math.Abs(plan.CutZMax - host.ZMax) < Tolerance ? SupportedBooleanHoleSpanKind.BlindFromTop : SupportedBooleanHoleSpanKind.BlindFromBottom);
+ var cylinder = new RecognizedCylinder(new Point3D(plan.CenterU, plan.CenterV, 0), zAxis, plan.Radius, plan.CutZMin, plan.CutZMax);
+ var surface = new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cylinder);
+ if (!BrepBooleanSafeCompositionGraphValidator.TryValidateNextSubtract(composition, surface, ToleranceContext.Default, out var updated, out var diagnostic, plan.SemanticFeatureId))
+ {
+ diagnostics.Add("firmament-v2-semantic-hole-overlap: " + (diagnostic?.Message ?? $"feature {plan.SemanticFeatureId} overlaps or conflicts with a previously accepted semantic hole."));
+ return new(false, null, plans, diagnostics);
+ }
+
+ // Preserve the end-condition span chosen by AirHoleFeature planning while using the graph validator's narrow same-axis interference policy.
+ var last = updated.Holes[^1] with { SpanKind = span, StartZ = plan.CutZMin, EndZ = plan.CutZMax };
+ composition = updated with { Holes = [.. updated.Holes.Take(updated.Holes.Count - 1), last] };
+ diagnostics.Add($"air-hole-x4 accepted semantic feature {plan.SemanticFeatureId} center=({plan.CenterU:0.###},{plan.CenterV:0.###}) radius={plan.Radius:0.###}.");
+ }
+
+ var built = BrepBooleanBoxCylinderHoleBuilder.BuildComposition(composition, ToleranceContext.Default);
+ if (!built.IsSuccess || built.Value is null)
+ {
+ diagnostics.Add("air-hole-x4 composite BRep build failed.");
+ diagnostics.AddRange(built.Diagnostics.Select(d => d.Message));
+ return new(false, null, plans, diagnostics);
+ }
+
+ diagnostics.Add("air-hole-x4 composite materialization succeeded through semantic AirHoleFeature plans and safe boolean AP242 BRep composition.");
+ return new(true, built.Value, plans, diagnostics);
+ }
+}
diff --git a/docs/implementation/step-v2-x4-multi-feature-composition-ap242.md b/docs/implementation/step-v2-x4-multi-feature-composition-ap242.md
new file mode 100644
index 00000000..fd4c5bb5
--- /dev/null
+++ b/docs/implementation/step-v2-x4-multi-feature-composition-ap242.md
@@ -0,0 +1,59 @@
+# STEP-V2-X4 — multi-feature composition AP242 verification
+
+STEP-V2-X4 promotes the first bounded Firmament V2 multi-feature composition cases to AP242 `step-verified` evidence. The production path remains semantic source → `AirHoleFeature` lowering → bounded safe BRep composition → `Step242Exporter`; no hardcoded STEP templates, trace-only output, patterns, hole groups, or new hole semantics are introduced.
+
+## Fixtures
+
+Valid Tier 4 fixtures:
+
+- `fixtures/FirmamentV2/Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture`
+- `fixtures/FirmamentV2/Composite/valid/composite-v2-adjacent-non-overlapping-holes-step-verified.valid.firmfixture`
+
+Invalid Tier 4 fixture:
+
+- `fixtures/FirmamentV2/Composite/invalid/composite-v2-overlapping-holes-rejected-with-clear-diagnostic.invalid.firmfixture`
+
+The optional derived-variant plus hole case remains deferred for this milestone. X4 intentionally proves multi-hole composition on one selected Box first; combining derivation selection and feature composition can be promoted later without broadening this slice.
+
+## Command path and verification
+
+The integration tests execute the real CLI build path:
+
+```bash
+aetheris build <fixture> --out <temp.step> --json
+```
+
+For valid fixtures the emitted AP242 is checked for `ISO-10303-21`, `ADVANCED_FACE`, and `VERTEX_POINT`, reimported with `Step242Importer`, inspected for two cylindrical wall faces, and analyzed with exact volume analysis. This exercises `FirmamentBuildAndExport`, semantic `AirHoleFeature` lowering, `AirHoleCompositeMaterializer`, `BrepBooleanSafeCompositionGraphValidator`, `BrepBooleanBoxCylinderHoleBuilder`, and `Step242Exporter.ExportBody`.
+
+## Volume formulas
+
+Both valid fixtures use a `10 x 8 x 6` Box:
+
+```text
+base volume = 480
+hole radius = 1
+through depth = 6
+expected volume = 480 - 2 * pi * 1^2 * 6 = 442.3008881569225
+```
+
+The adjacent fixture places centers 2.5 model units apart, so the two radius-1 holes are close but non-overlapping.
+
+## Overlap rejection policy
+
+The invalid fixture uses two same-face, same-axis, circular shaft holes whose centers are 1.5 model units apart with radius 1. That is narrower than `r1 + r2`, so the build is rejected before successful AP242 emission. The stable diagnostic prefix is:
+
+```text
+firmament-v2-semantic-hole-overlap
+```
+
+This is deliberately narrow: same planar entry face, same world-Z axis/direction family, same through-all end condition family, circular shaft holes. The implementation does not resolve, merge, or reroute overlaps and does not attempt general Boolean conflict resolution.
+
+## MVP readiness relationship
+
+These fixtures satisfy the MVP readiness contract for this bounded multi-feature area because `current-stage: step-verified` is claimed only where real AP242 is emitted from a real `BrepBody`, reimported, topology/evidence checked, and volume verified. The rejected fixture is marked deterministic rejection and must not produce misleading success AP242.
+
+## Deferred
+
+- General feature conflict resolution.
+- Patterns, hole groups, new hole variants, threads/taps, up-to-face/up-to-next, side-hole reroute, chamfer/fillet/draft, PMI, and DFM enforcement.
+- Derived variant plus hole AP242 verification, until composition on derived selected solids is promoted as its own bounded slice.
diff --git a/fixtures/FirmamentV2/Composite/invalid/composite-v2-overlapping-holes-rejected-with-clear-diagnostic.invalid.firmfixture b/fixtures/FirmamentV2/Composite/invalid/composite-v2-overlapping-holes-rejected-with-clear-diagnostic.invalid.firmfixture
new file mode 100644
index 00000000..1f0888bd
--- /dev/null
+++ b/fixtures/FirmamentV2/Composite/invalid/composite-v2-overlapping-holes-rejected-with-clear-diagnostic.invalid.firmfixture
@@ -0,0 +1,37 @@
+// fixture-id: composite-v2-overlapping-holes-rejected-with-clear-diagnostic
+// case: composite-v2-overlapping-holes-rejected-with-clear-diagnostic
+// category: Composite
+// syntax-version: FirmamentV2
+// validity: invalid
+// implementation: parser-backed
+// expected: invalid
+// expected-stage: deterministic rejection
+// current-stage: deterministic rejection
+// expected-feature-air: AirHoleFeature(SimpleShaft) x2 rejected before BRep success
+// dimensions: base box 10 x 8 x 6; two shaft radii 1; center separation 1.5 overlaps
+// units: mm
+// tier: 4
+// mvp-required: true
+// feature-area: multi-feature-composition
+// expected-diagnostic: firmament-v2-semantic-hole-overlap
+// build-command: aetheris build
+// parser-backed: true
+// notes: STEP-V2-X4 invalid fixture; same-face same-axis circular shaft hole overlap is rejected deterministically and must not emit success AP242.
+model CompositeV2OverlappingHolesRejectedWithClearDiagnostic {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<shaft> leftMount {
+ on: face(+Z)
+ center: [-0.75, 0]
+ diameter: 2
+ end: throughAll
+ }
+ hole<shaft> rightMount {
+ on: face(+Z)
+ center: [0.75, 0]
+ diameter: 2
+ end: throughAll
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/Composite/valid/composite-v2-adjacent-non-overlapping-holes-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Composite/valid/composite-v2-adjacent-non-overlapping-holes-step-verified.valid.firmfixture
new file mode 100644
index 00000000..a8569532
--- /dev/null
+++ b/fixtures/FirmamentV2/Composite/valid/composite-v2-adjacent-non-overlapping-holes-step-verified.valid.firmfixture
@@ -0,0 +1,39 @@
+// fixture-id: composite-v2-adjacent-non-overlapping-holes-step-verified
+// case: composite-v2-adjacent-non-overlapping-holes-step-verified
+// category: Composite
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(SimpleShaft) x2
+// dimensions: base box 10 x 8 x 6; two shaft radii 1; center separation 2.5; through depth 6
+// units: mm
+// tier: 4
+// mvp-required: true
+// feature-area: multi-feature-composition
+// build-command: aetheris build
+// expected-volume: 442.3008881569225
+// expected-topology: advanced_face>0, vertex_point>0, cylindrical-wall-face-count=2
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X4 near-miss fixture; validates adjacent non-overlapping same-face holes without conflict resolution.
+model CompositeV2AdjacentNonOverlappingHolesStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<shaft> leftMount {
+ on: face(+Z)
+ center: [-1.25, 0]
+ diameter: 2
+ end: throughAll
+ }
+ hole<shaft> rightMount {
+ on: face(+Z)
+ center: [1.25, 0]
+ diameter: 2
+ end: throughAll
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture b/fixtures/FirmamentV2/Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture
new file mode 100644
index 00000000..2267da5f
--- /dev/null
+++ b/fixtures/FirmamentV2/Composite/valid/composite-v2-two-independent-holes-step-verified.valid.firmfixture
@@ -0,0 +1,39 @@
+// fixture-id: composite-v2-two-independent-holes-step-verified
+// case: composite-v2-two-independent-holes-step-verified
+// category: Composite
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// expected-feature-air: AirHoleFeature(SimpleShaft) x2
+// dimensions: base box 10 x 8 x 6; two shaft radii 1; through depth 6
+// units: mm
+// tier: 4
+// mvp-required: true
+// feature-area: multi-feature-composition
+// build-command: aetheris build
+// expected-volume: 442.3008881569225
+// expected-topology: advanced_face>0, vertex_point>0, cylindrical-wall-face-count=2
+// roundtrip-required: true
+// parser-backed: true
+// notes: STEP-V2-X4 fixture; real build/export path uses semantic AirHoleFeature plans, SafeBooleanComposition, Step242Exporter, reimport, topology markers, and analytic volume.
+model CompositeV2TwoIndependentHolesStepVerified {
+ units mm
+ solid base: Box { size: [10, 8, 6] }
+ modify base {
+ hole<shaft> leftMount {
+ on: face(+Z)
+ center: [-2, 0]
+ diameter: 2
+ end: throughAll
+ }
+ hole<shaft> rightMount {
+ on: face(+Z)
+ center: [2, 0]
+ diameter: 2
+ end: throughAll
+ }
+ }
+}