Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add gated Firmament AirChamfer opt-in route

Yuechen Li730647c67050
diff --git a/Aetheris.Kernel.Firmament.Tests/AirChamferFirmamentOptInRouteTests.cs b/Aetheris.Kernel.Firmament.Tests/AirChamferFirmamentOptInRouteTests.cs
new file mode 100644
index 00000000..6c6ea3fe
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/AirChamferFirmamentOptInRouteTests.cs
@@ -0,0 +1,201 @@
+using System.Numerics;
+using Aetheris.Firmament.FrictionLab.CIRLab;
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Execution;
+using Aetheris.Kernel.Firmament.Lowering;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class AirChamferFirmamentOptInRouteTests
+{
+ private const string SupportedFixture = "testdata/firmament/fixtures/edge-x13-valid-airchamfer-shadow-box-edge.firmament";
+
+ [Fact]
+ public void FirmamentAirChamferOptInRoute_DisabledByDefault_UsesLegacyResult()
+ {
+ var compiled = CompileFixture(SupportedFixture);
+ var legacy = AssertLegacyChamferRoute(compiled.Compilation.Value.PrimitiveExecutionResult!);
+ var legacyStep = ExportStep(legacy.Body);
+
+ var executed = ExecuteWith(FirmamentAirChamferExperimentalOptions.Disabled, out var diagnostics);
+ var chamfer = AssertLegacyChamferRoute(executed);
+
+ Assert.Equal(legacyStep, ExportStep(chamfer.Body));
+ Assert.DoesNotContain("edge-v4-air-chamfer-candidate-selected", diagnostics);
+ Assert.Contains("edge-v4-air-chamfer-opt-in-disabled", diagnostics);
+ Assert.Contains("edge-v4-legacy-default-route-used", diagnostics);
+ Assert.Contains("edge-v4-production-default-unchanged", diagnostics);
+ Assert.Contains("edge-v4-no-3d-boolean-used", diagnostics);
+ }
+
+ [Fact]
+ public void FirmamentAirChamferOptInRoute_SupportedControlledCase_SelectsAirChamferCandidate()
+ {
+ var executed = ExecuteWith(SupportedOptions(), out var diagnostics);
+ var chamfer = Assert.Single(executed.ExecutedBooleans);
+
+ Assert.Equal(FirmamentLoweredBooleanKind.Chamfer, chamfer.Kind);
+ Assert.Equal("edge_x13_legacy_edge_break", chamfer.FeatureId);
+ Assert.Contains("edge-v4-air-chamfer-opt-in-enabled", diagnostics);
+ Assert.Contains("edge-v4-supported-case-accepted", diagnostics);
+ Assert.Contains("edge-v4-air-chamfer-shadow-route-invoked", diagnostics);
+ Assert.Contains("edge-v4-air-chamfer-candidate-selected", diagnostics);
+ Assert.Contains("edge-v4-no-3d-boolean-used", diagnostics);
+ Assert.Contains("edge-v3-shadow-candidate-step-smoke-succeeded", diagnostics);
+ Assert.Contains("edge-v3-shadow-feature-recognition-parity-succeeded", diagnostics);
+ Assert.DoesNotContain("edge-v4-legacy-fallback-used", diagnostics);
+
+ Assert.NotEmpty(chamfer.Body.Topology.Bodies);
+ Assert.NotEmpty(chamfer.Body.Topology.Faces);
+ var export = Step242Exporter.ExportBody(chamfer.Body);
+ Assert.True(export.IsSuccess);
+ Assert.Contains("MANIFOLD_SOLID_BREP", export.Value);
+ }
+
+ [Theory]
+ [InlineData("non-planar-face-family", "cylindrical", false, false, false, "unsupported-face-family")]
+ [InlineData("edge-chain", "planar", true, false, false, "edge-chain")]
+ [InlineData("corner-chain", "planar", false, true, false, "corner-chain")]
+ [InlineData("legacy-dependent-triangle", "planar", false, false, true, "legacy-dependent-topology")]
+ public void FirmamentAirChamferOptInRoute_UnsupportedCases_FallbackToLegacy(
+ string caseName,
+ string faceFamily,
+ bool edgeChain,
+ bool cornerChain,
+ bool legacyDependency,
+ string expectedReason)
+ {
+ var compiled = CompileFixture(SupportedFixture);
+ var legacyStep = ExportStep(AssertLegacyChamferRoute(compiled.Compilation.Value.PrimitiveExecutionResult!).Body);
+
+ var executed = ExecuteWith(SupportedOptions(caseName, faceFamily == "planar" ? FirmamentAirChamferExperimentalFaceFamily.Planar : FirmamentAirChamferExperimentalFaceFamily.Cylindrical, edgeChain, cornerChain, legacyDependency), out var diagnostics);
+ var chamfer = AssertLegacyChamferRoute(executed);
+
+ Assert.Equal(legacyStep, ExportStep(chamfer.Body));
+ Assert.DoesNotContain("edge-v4-air-chamfer-candidate-selected", diagnostics);
+ Assert.Contains($"edge-v4-supported-case-rejected:{expectedReason}", diagnostics);
+ Assert.Contains("edge-v4-legacy-fallback-used", diagnostics);
+ Assert.Contains("edge-v4-no-3d-boolean-used", diagnostics);
+ }
+
+ [Fact]
+ public void FirmamentAirChamferOptInRoute_CandidateFailure_FallbackToLegacy()
+ {
+ var compiled = CompileFixture(SupportedFixture);
+ var legacyStep = ExportStep(AssertLegacyChamferRoute(compiled.Compilation.Value.PrimitiveExecutionResult!).Body);
+ var options = SupportedOptions() with
+ {
+ CandidateProvider = _ => new FirmamentAirChamferExperimentalCandidateReport(
+ CandidateProduced: false,
+ FirmamentAirChamferExperimentalCandidateStatus.Failed,
+ "injected-failure",
+ CandidateBody: null,
+ TopologyContractSatisfied: false,
+ StepSmokeSucceeded: false,
+ RecognitionContractSatisfied: false,
+ NoThreeDimensionalBooleanUsed: true,
+ Diagnostics: ["edge-v4-test-injected-candidate-failure"])
+ };
+
+ var executed = ExecuteWith(options, out var diagnostics);
+ var chamfer = AssertLegacyChamferRoute(executed);
+
+ Assert.Equal(legacyStep, ExportStep(chamfer.Body));
+ Assert.Contains("edge-v4-test-injected-candidate-failure", diagnostics);
+ Assert.Contains("edge-v4-air-chamfer-candidate-rejected:failed", diagnostics);
+ Assert.Contains("edge-v4-air-chamfer-candidate-failed-fallback", diagnostics);
+ Assert.Contains("edge-v4-legacy-fallback-used", diagnostics);
+ }
+
+ private static FirmamentPrimitiveExecutionResult ExecuteWith(FirmamentAirChamferExperimentalOptions options, out IReadOnlyList<string> diagnostics)
+ {
+ IReadOnlyList<string> capturedDiagnostics = [];
+ options = options with { DiagnosticSink = d => capturedDiagnostics = d };
+ var compiled = CompileFixture(SupportedFixture);
+ Assert.True(compiled.Compilation.IsSuccess);
+ var result = FirmamentPrimitiveExecutor.Execute(compiled.Compilation.Value.PrimitiveLoweringPlan!, options);
+ Assert.True(result.IsSuccess);
+ diagnostics = capturedDiagnostics;
+ Assert.NotEmpty(diagnostics);
+ return result.Value;
+ }
+
+ private static FirmamentAirChamferExperimentalOptions SupportedOptions(
+ string caseName = "edge-v4-firmament-controlled-box-convex-planar-single-edge",
+ FirmamentAirChamferExperimentalFaceFamily faceFamily = FirmamentAirChamferExperimentalFaceFamily.Planar,
+ bool edgeChain = false,
+ bool cornerChain = false,
+ bool legacyDependency = false) =>
+ new(
+ EnableAirChamferExperimentalRoute: true,
+ CaseName: caseName,
+ FaceFamily: faceFamily,
+ IsEdgeChain: edgeChain,
+ IsCornerChain: cornerChain,
+ LegacyDependency: legacyDependency,
+ IncludeStepSmoke: true,
+ CandidateProvider: InvokeShadowRoute);
+
+ private static FirmamentAirChamferExperimentalCandidateReport InvokeShadowRoute(FirmamentAirChamferExperimentalCandidateRequest request)
+ {
+ var route = AirChamferShadowRoute.Evaluate(new AirChamferShadowRouteRequest(
+ request.CaseName,
+ request.SourceBody,
+ new Vector3(5f, 4f, -3f),
+ new Vector3(5f, 4f, 3f),
+ new Vector3(1f, 0f, 0f),
+ new Vector3(0f, 1f, 0f),
+ request.ChamferDistance,
+ request.FaceFamily == FirmamentAirChamferExperimentalFaceFamily.Planar ? AirChamferFaceFamily.Planar : AirChamferFaceFamily.Cylindrical,
+ request.IsEdgeChain,
+ request.IsCornerChain,
+ request.LegacyDependency,
+ AirChamferClassificationExpectation.Convex,
+ IsOrthogonalFacePair: true,
+ ReferenceEnvelope: 10d,
+ IncludeStepSmoke: request.IncludeStepSmoke));
+
+ return new FirmamentAirChamferExperimentalCandidateReport(
+ route.ShadowCandidateProduced,
+ route.ShadowCandidateStatus switch
+ {
+ AirChamferShadowCandidateStatus.Succeeded => FirmamentAirChamferExperimentalCandidateStatus.Succeeded,
+ AirChamferShadowCandidateStatus.Rejected => FirmamentAirChamferExperimentalCandidateStatus.Rejected,
+ AirChamferShadowCandidateStatus.Deferred => FirmamentAirChamferExperimentalCandidateStatus.Deferred,
+ AirChamferShadowCandidateStatus.FallbackLegacy => FirmamentAirChamferExperimentalCandidateStatus.FallbackLegacy,
+ _ => FirmamentAirChamferExperimentalCandidateStatus.Failed
+ },
+ route.AirChamferDecision,
+ route.ShadowCandidateBody,
+ TopologyContractSatisfied: route.TopologySummary is not null,
+ StepSmokeSucceeded: route.StepSmokeSummary?.Succeeded == true,
+ RecognitionContractSatisfied: route.FeatureRecognitionSummary?.RecognitionContractSatisfied == true,
+ NoThreeDimensionalBooleanUsed: route.Diagnostics.Contains("edge-v3-no-3d-boolean-used"),
+ route.Diagnostics);
+ }
+
+ private static FirmamentExecutedBoolean AssertLegacyChamferRoute(FirmamentPrimitiveExecutionResult execution)
+ {
+ var executedBoolean = Assert.Single(execution.ExecutedBooleans);
+ Assert.Equal(FirmamentLoweredBooleanKind.Chamfer, executedBoolean.Kind);
+ Assert.Equal("edge_x13_legacy_edge_break", executedBoolean.FeatureId);
+ Assert.Equal(7, executedBoolean.Body.Topology.Faces.Count());
+ Assert.NotEmpty(executedBoolean.Body.Topology.Bodies);
+ return executedBoolean;
+ }
+
+ private static string ExportStep(BrepBody body)
+ {
+ var export = Step242Exporter.ExportBody(body);
+ Assert.True(export.IsSuccess);
+ return export.Value;
+ }
+
+ private static FirmamentCompileResult CompileFixture(string fixturePath)
+ {
+ var source = FirmamentCorpusHarness.ReadFixtureText(fixturePath);
+ var compiler = new FirmamentCompiler();
+ return compiler.Compile(new FirmamentCompileRequest(new FirmamentSourceDocument(source)));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentAirChamferExperimentalOptions.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentAirChamferExperimentalOptions.cs
new file mode 100644
index 00000000..415e6ec6
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentAirChamferExperimentalOptions.cs
@@ -0,0 +1,42 @@
+using Aetheris.Kernel.Core.Brep;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum FirmamentAirChamferExperimentalFaceFamily { Planar, Cylindrical, Unsupported }
+
+internal enum FirmamentAirChamferExperimentalCandidateStatus { Succeeded, Rejected, Deferred, Failed, FallbackLegacy }
+
+internal sealed record FirmamentAirChamferExperimentalOptions(
+ bool EnableAirChamferExperimentalRoute = false,
+ string CaseName = "edge-v4-firmament-controlled-box-convex-planar-single-edge",
+ FirmamentAirChamferExperimentalFaceFamily FaceFamily = FirmamentAirChamferExperimentalFaceFamily.Planar,
+ bool IsEdgeChain = false,
+ bool IsCornerChain = false,
+ bool LegacyDependency = false,
+ bool IncludeStepSmoke = true,
+ Func<FirmamentAirChamferExperimentalCandidateRequest, FirmamentAirChamferExperimentalCandidateReport>? CandidateProvider = null,
+ Action<IReadOnlyList<string>>? DiagnosticSink = null)
+{
+ public static FirmamentAirChamferExperimentalOptions Disabled { get; } = new();
+}
+
+internal sealed record FirmamentAirChamferExperimentalCandidateRequest(
+ string CaseName,
+ BrepBody SourceBody,
+ double ChamferDistance,
+ FirmamentAirChamferExperimentalFaceFamily FaceFamily,
+ bool IsEdgeChain,
+ bool IsCornerChain,
+ bool LegacyDependency,
+ bool IncludeStepSmoke);
+
+internal sealed record FirmamentAirChamferExperimentalCandidateReport(
+ bool CandidateProduced,
+ FirmamentAirChamferExperimentalCandidateStatus Status,
+ string Decision,
+ BrepBody? CandidateBody,
+ bool TopologyContractSatisfied,
+ bool StepSmokeSucceeded,
+ bool RecognitionContractSatisfied,
+ bool NoThreeDimensionalBooleanUsed,
+ IReadOnlyList<string> Diagnostics);
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index d4583f2c..b7039248 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -22,8 +22,14 @@ namespace Aetheris.Kernel.Firmament.Execution;
internal static class FirmamentPrimitiveExecutor
{
public static KernelResult<FirmamentPrimitiveExecutionResult> Execute(FirmamentPrimitiveLoweringPlan loweringPlan)
+ => Execute(loweringPlan, FirmamentAirChamferExperimentalOptions.Disabled);
+
+ internal static KernelResult<FirmamentPrimitiveExecutionResult> Execute(
+ FirmamentPrimitiveLoweringPlan loweringPlan,
+ FirmamentAirChamferExperimentalOptions airChamferExperimentalOptions)
{
ArgumentNullException.ThrowIfNull(loweringPlan);
+ ArgumentNullException.ThrowIfNull(airChamferExperimentalOptions);
var executedPrimitives = new List<FirmamentExecutedPrimitive>(loweringPlan.Primitives.Count);
var executedBooleans = new List<FirmamentExecutedBoolean>(loweringPlan.Booleans.Count);
@@ -94,7 +100,14 @@ internal static class FirmamentPrimitiveExecutor
]);
}
- var chamferedBody = chamferResult.Value;
+ var selectedChamfer = SelectAirChamferExperimentalRouteOrLegacy(
+ boolean,
+ baseBody,
+ featureGraphStates.TryGetValue(boolean.PrimaryReferenceFeatureId, out var chamferSourceState) ? chamferSourceState : FirmamentSafeSubtractFeatureGraphState.Other,
+ distance: TryReadFiniteChamferDistance(boolean, out var parsedDistance) ? parsedDistance : double.NaN,
+ legacyBody: chamferResult.Value,
+ airChamferExperimentalOptions);
+ var chamferedBody = selectedChamfer.Body;
executedBooleans.Add(new FirmamentExecutedBoolean(boolean.OpIndex, boolean.FeatureId, boolean.Kind, chamferedBody));
publishedBodiesByFeatureId[boolean.FeatureId] = chamferedBody;
booleanExecutionBodiesByFeatureId[boolean.FeatureId] = chamferedBody;
@@ -1137,6 +1150,162 @@ internal static class FirmamentPrimitiveExecutor
]);
}
+
+ private sealed record AirChamferExperimentalSelection(BrepBody Body, IReadOnlyList<string> Diagnostics);
+
+ private static AirChamferExperimentalSelection SelectAirChamferExperimentalRouteOrLegacy(
+ FirmamentLoweredBoolean boolean,
+ BrepBody sourceBody,
+ FirmamentSafeSubtractFeatureGraphState sourceState,
+ double distance,
+ BrepBody legacyBody,
+ FirmamentAirChamferExperimentalOptions options)
+ {
+ var diagnostics = new List<string>
+ {
+ "edge-v4-air-chamfer-opt-in-route-started",
+ "edge-v4-production-default-unchanged",
+ "edge-v4-no-3d-boolean-used"
+ };
+
+ if (!options.EnableAirChamferExperimentalRoute)
+ {
+ diagnostics.Add("edge-v4-air-chamfer-opt-in-disabled");
+ diagnostics.Add("edge-v4-legacy-default-route-used");
+ return Finish(legacyBody, diagnostics, options);
+ }
+
+ diagnostics.Add("edge-v4-air-chamfer-opt-in-enabled");
+
+ var rejection = GetAirChamferExperimentalSupportedCaseRejection(boolean, sourceState, distance, options);
+ if (rejection is not null)
+ {
+ diagnostics.Add($"edge-v4-supported-case-rejected:{rejection}");
+ diagnostics.Add("edge-v4-legacy-fallback-used");
+ return Finish(legacyBody, diagnostics, options);
+ }
+
+ diagnostics.Add("edge-v4-supported-case-accepted");
+
+ if (options.CandidateProvider is null)
+ {
+ diagnostics.Add("edge-v4-air-chamfer-candidate-rejected:missing-candidate-provider");
+ diagnostics.Add("edge-v4-air-chamfer-candidate-failed-fallback");
+ diagnostics.Add("edge-v4-legacy-fallback-used");
+ return Finish(legacyBody, diagnostics, options);
+ }
+
+ FirmamentAirChamferExperimentalCandidateReport candidate;
+ try
+ {
+ candidate = options.CandidateProvider(new FirmamentAirChamferExperimentalCandidateRequest(
+ options.CaseName,
+ sourceBody,
+ distance,
+ options.FaceFamily,
+ options.IsEdgeChain,
+ options.IsCornerChain,
+ options.LegacyDependency,
+ options.IncludeStepSmoke));
+ }
+ catch (Exception ex)
+ {
+ diagnostics.Add($"edge-v4-air-chamfer-candidate-rejected:provider-threw-{ex.GetType().Name}");
+ diagnostics.Add("edge-v4-air-chamfer-candidate-failed-fallback");
+ diagnostics.Add("edge-v4-legacy-fallback-used");
+ return Finish(legacyBody, diagnostics, options);
+ }
+
+ diagnostics.Add("edge-v4-air-chamfer-shadow-route-invoked");
+ diagnostics.AddRange(candidate.Diagnostics);
+
+ var candidateRejection = GetAirChamferExperimentalCandidateRejection(candidate);
+ if (candidateRejection is not null)
+ {
+ diagnostics.Add($"edge-v4-air-chamfer-candidate-rejected:{candidateRejection}");
+ diagnostics.Add("edge-v4-air-chamfer-candidate-failed-fallback");
+ diagnostics.Add("edge-v4-legacy-fallback-used");
+ return Finish(legacyBody, diagnostics, options);
+ }
+
+ diagnostics.Add("edge-v4-air-chamfer-candidate-selected");
+ return Finish(candidate.CandidateBody!, diagnostics, options);
+ }
+
+ private static string? GetAirChamferExperimentalSupportedCaseRejection(
+ FirmamentLoweredBoolean boolean,
+ FirmamentSafeSubtractFeatureGraphState sourceState,
+ double distance,
+ FirmamentAirChamferExperimentalOptions options)
+ {
+ if (boolean.FeatureId != "edge_x13_legacy_edge_break" || boolean.PrimaryReferenceFeatureId != "base")
+ return "unsupported-fixture";
+
+ if (sourceState != FirmamentSafeSubtractFeatureGraphState.BoxRoot)
+ return "unsupported-source-state";
+
+ if (!double.IsFinite(distance) || distance <= 0d)
+ return "invalid-distance";
+
+ if (options.FaceFamily != FirmamentAirChamferExperimentalFaceFamily.Planar)
+ return "unsupported-face-family";
+
+ if (options.IsEdgeChain)
+ return "edge-chain";
+
+ if (options.IsCornerChain)
+ return "corner-chain";
+
+ if (options.LegacyDependency)
+ return "legacy-dependent-topology";
+
+ if (!BrepBoundedEdgeFinishingToolParser.TryParseChamferSelection(boolean.Tool.RawFields, out var edge, out var incidentEdgePair, out var corner, out _))
+ return "invalid-selection";
+
+ if (edge != BrepBoundedChamferEdge.XMaxYMax || incidentEdgePair.HasValue || corner.HasValue)
+ return "unsupported-selection";
+
+ return null;
+ }
+
+ private static string? GetAirChamferExperimentalCandidateRejection(FirmamentAirChamferExperimentalCandidateReport candidate)
+ {
+ if (!candidate.CandidateProduced || candidate.CandidateBody is null)
+ return candidate.Status.ToString().ToLowerInvariant();
+
+ if (candidate.Status != FirmamentAirChamferExperimentalCandidateStatus.Succeeded)
+ return candidate.Status.ToString().ToLowerInvariant();
+
+ if (!candidate.NoThreeDimensionalBooleanUsed)
+ return "3d-boolean-used";
+
+ if (!candidate.TopologyContractSatisfied)
+ return "topology-contract";
+
+ if (!candidate.StepSmokeSucceeded)
+ return "step-smoke";
+
+ if (!candidate.RecognitionContractSatisfied)
+ return "recognition-contract";
+
+ return null;
+ }
+
+ private static AirChamferExperimentalSelection Finish(BrepBody body, IEnumerable<string> diagnostics, FirmamentAirChamferExperimentalOptions options)
+ {
+ var finalDiagnostics = diagnostics.Distinct().OrderBy(x => x, StringComparer.Ordinal).ToArray();
+ options.DiagnosticSink?.Invoke(finalDiagnostics);
+ return new(body, finalDiagnostics);
+ }
+
+ private static bool TryReadFiniteChamferDistance(FirmamentLoweredBoolean boolean, out double distance)
+ {
+ distance = 0d;
+ return boolean.Tool.RawFields.TryGetValue("distance", out var distanceRaw)
+ && double.TryParse(distanceRaw, NumberStyles.Float, CultureInfo.InvariantCulture, out distance)
+ && double.IsFinite(distance);
+ }
+
private static KernelResult<BrepBody> ExecuteBoundedManufacturingFilletOnRecognizedOrthogonalRoot(
FirmamentLoweredBoolean boolean,
BrepBody baseBody,
diff --git a/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md b/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
index 9114cd4b..256601ce 100644
--- a/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
+++ b/docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md
@@ -4,7 +4,7 @@
This document defines what “full chamfer/fillet support” means for Aetheris within its bounded analytic modeling scope. It is a compatibility and readiness matrix, not an implementation plan that changes behavior.
-The current AirChamfer golden path is strong but narrow: controlled convex planar single-edge chamfers now have Judgment-backed policy, topology planning, geometry artifacts, closed witnesses, controlled topology graft evidence, a production-adjacent prototype, feature-recognition parity probes, a non-authoritative shadow route, CLI STEP artifacts/corpus coverage, and gated corpus stability evidence.
+The current AirChamfer golden path is strong but narrow: controlled convex planar single-edge chamfers now have Judgment-backed policy, topology planning, geometry artifacts, closed witnesses, controlled topology graft evidence, a production-adjacent prototype, feature-recognition parity probes, a non-authoritative shadow route, CLI STEP artifacts/corpus coverage, gated corpus stability evidence, and one internal/test-only gated Firmament opt-in route for the controlled CH-03 fixture.
Legacy bounded chamfer/fillet behavior remains authoritative wherever production behavior exists. In particular, `BrepBoundedChamfer` and `BrepBoundedFillet` are still the production routes for the currently supported bounded cases, and AirEdgeSweep/AirChamfer evidence must not be read as route replacement.
@@ -140,7 +140,7 @@ This path is not production-authoritative. It does not support chains, corners,
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CH-01 | concave/additive | plane-plane, orthogonal | single edge | constant chamfer distance | no corner | plane | `production-legacy-supported` where bounded internal concave route applies | `lab-supported`; `policy-supported` | EDGE-X1 inventory; EDGE-X2 concave planar patch proof; EDGE-X2.1 policy scaffold | production Air route, shadow parity, corpus | Legacy production only; Air is lab/policy evidence | Preserve legacy; use as concave AirChamfer baseline |
| CH-02 | concave/additive | plane-plane, non-orthogonal | single edge | constant chamfer distance | no corner | plane | `unknown/no-test` to `production-legacy-supported` only where existing bounded trusted contexts admit it | `lab-supported`; `policy-supported` | EDGE-X2.2 non-orthogonal concave planar policy+patch | production body mutation, feature-recognition parity, corpus | Not production Air-ready | Add parity/shadow fixture after convex route stabilizes |
-| CH-03 | convex/replacement | plane-plane, orthogonal controlled body | single edge | constant chamfer distance | no corner | plane | `production-legacy-supported` for legacy bounded box/simple contexts | `production-adjacent-air-prototype`; `shadow-supported`; `artifact-corpus-supported`; `closed-witness-supported` | EDGE-X3 through EDGE-X13, EDGE-V1/V2/V3, CLI tests, FrictionLab AirChamfer tests, Firmament shadow-diagnostics tests | production authority, arbitrary body mutation, route fallback policy | Best current AirChamfer row, still non-authoritative; EDGE-X13 adds Firmament-facing test-only shadow diagnostics | EDGE-V4 controlled opt-in route only after diagnostics remain stable |
+| CH-03 | convex/replacement | plane-plane, orthogonal controlled body | single edge | constant chamfer distance | no corner | plane | `production-legacy-supported` for legacy bounded box/simple contexts | `production-adjacent-air-prototype`; `shadow-supported`; `artifact-corpus-supported`; `closed-witness-supported`; `gated-opt-in-route-supported` | EDGE-X3 through EDGE-X13, EDGE-V1/V2/V3/V4, CLI tests, FrictionLab AirChamfer tests, Firmament shadow-diagnostics and opt-in route tests | default production authority, arbitrary body mutation beyond controlled fixture | Best current AirChamfer row; EDGE-V4 adds gated internal/test-only controlled route evidence, still not default production-authoritative | EDGE-V5 one additional controlled opt-in fixture or EDGE-V4.1 fallback injection hardening |
| CH-04 | convex/replacement | plane-plane, non-orthogonal controlled body | single edge | constant chamfer distance | no corner | plane | `production-legacy-supported` only for admitted trusted/triangle-like bounded contexts; otherwise `unknown/no-test` | `shadow-supported`; `artifact-corpus-supported`; `production-adjacent-air-prototype` for safe controlled case | EDGE-X11 non-orthogonal corpus row; EDGE-X12 stability; EDGE-V3 shadow route | broader topology mutation, richer feature-recognition parity, production fallback | Non-authoritative controlled evidence only | Harden controlled non-orthogonal shadow diagnostics |
| CH-05 | convex/replacement | plane-plane | single edge on arbitrary production body | constant chamfer distance | no corner or endpoint transition as needed | plane | `production-legacy-supported` only for legacy recognized bounded cases | `deferred`; `blocked-by-body-mutation`; partial `production-adjacent-air-prototype` for controlled body | EDGE-V2/V3 controlled prototype and shadow docs | arbitrary edge selection, grafting, identity, regression corpus | Not production Air-ready | EDGE-X15 convex AirChamfer controlled body mutation hardening |
| CH-06 | convex/replacement | plane-plane | edge chain | constant chamfer distance | chain termination; endpoint transitions | plane sequence plus transition patches | legacy support is bounded/contextual; generic status `unknown/no-test` | `deferred`; `blocked-by-corner-policy`; `blocked-by-body-mutation` | EDGE-V3 deferred edge-chain diagnostics; EDGE-X1 notes | chain policy, termination policy, topology plan, feature-recognition parity | Not ready | EDGE-X16 AirChamfer edge-chain policy lab |
diff --git a/docs/edge-v3-air-chamfer-shadow-route.md b/docs/edge-v3-air-chamfer-shadow-route.md
index 71b7db98..ea8b99cf 100644
--- a/docs/edge-v3-air-chamfer-shadow-route.md
+++ b/docs/edge-v3-air-chamfer-shadow-route.md
@@ -167,3 +167,7 @@ EDGE-A1 now defines the full chamfer/fillet support taxonomy, compatibility rows
## EDGE-X13 Firmament diagnostics note
EDGE-X13 surfaces the existing `AirChamferShadowRoute` through a Firmament-facing, test-only diagnostics probe. The real Firmament fixture still executes legacy `BrepBoundedChamfer` first; the AirChamfer route is invoked afterward as a sidecar using `AirChamferShadowRoute->AirChamferRealBodyPrototype`. The probe records EDGE-X13 diagnostics for legacy authority, unchanged production output, no production route replacement, no 3D Boolean use, feature-recognition capture, and STEP smoke capture. No public API, normal Firmament route, STEP exporter, Boolean core, chamfer/fillet production behavior, arbitrary selection, chain/corner support, or fillet geometry changed.
+
+## EDGE-V4 gated Firmament opt-in consumer
+
+EDGE-V4 adds an internal/test-only Firmament execution consumer for this shadow route. The consumer injects `AirChamferShadowRoute->AirChamferRealBodyPrototype` through an experimental candidate-provider seam, requires topology, STEP-smoke, recognition, and no-3D-Boolean evidence, and falls back to legacy `BrepBoundedChamfer` for every rejected, deferred, failed, unsupported, or default-disabled case. Normal production Firmament chamfer execution remains unchanged and AirChamfer is not a default production route.
diff --git a/docs/edge-v4-gated-opt-in-airchamfer-route.md b/docs/edge-v4-gated-opt-in-airchamfer-route.md
new file mode 100644
index 00000000..497cbaaf
--- /dev/null
+++ b/docs/edge-v4-gated-opt-in-airchamfer-route.md
@@ -0,0 +1,87 @@
+# EDGE-V4 — gated opt-in Firmament AirChamfer route
+
+## Purpose and scope
+
+EDGE-V4 adds a deliberately narrow, internal/test-only Firmament execution seam that can select an AirChamfer candidate **only** for the known controlled CH-03-style convex plane-plane single-edge fixture proven by EDGE-X13. The route is off by default and does not change normal Firmament chamfer execution.
+
+Reference trail:
+
+- EDGE-A1 compatibility matrix: `docs/edge-a1-chamfer-fillet-support-compatibility-matrix.md`
+- EDGE-X13 Firmament shadow diagnostics: `docs/edge-x13-firmament-airchamfer-shadow-diagnostics.md`
+- EDGE-V3 shadow route: `docs/edge-v3-air-chamfer-shadow-route.md`
+- EDGE-V2 real-body prototype evidence: `docs/frictionlab/edge-x8-controlled-local-air-chamfer-topology-graft-lab.md` and subsequent AirChamfer corpus docs
+
+## Opt-in flag and seam
+
+The seam is `FirmamentPrimitiveExecutor.Execute(loweringPlan, FirmamentAirChamferExperimentalOptions)`.
+
+The opt-in switch is `EnableAirChamferExperimentalRoute`. `FirmamentAirChamferExperimentalOptions.Disabled` is the default path used by existing production-facing `FirmamentPrimitiveExecutor.Execute(loweringPlan)` and by `FirmamentCompiler`.
+
+The candidate path is injected through `CandidateProvider`, keeping the production Firmament assembly independent of FrictionLab while allowing tests to invoke `AirChamferShadowRoute->AirChamferRealBodyPrototype` as ground-truth evidence.
+
+## Default behavior guarantee
+
+Default execution records disabled/default diagnostics and returns the legacy `BrepBoundedChamfer` body. AirChamfer cannot become the result unless the internal/test-only options object explicitly enables the experimental route and supplies a successful candidate provider.
+
+## Supported controlled case
+
+The accepted shape guard is intentionally exact:
+
+- fixture feature id `edge_x13_legacy_edge_break` from source feature `base`,
+- source state is `BoxRoot`,
+- chamfer distance is positive and finite,
+- selection is exactly `x_max_y_max`,
+- adjacent face family is planar,
+- no edge chain,
+- no corner chain,
+- no legacy-dependent topology marker,
+- candidate evidence reports topology, STEP smoke, recognition parity, and no 3D Boolean use.
+
+Everything else remains legacy/deferred: normal Firmament chamfers, arbitrary model edge selection, multiple edges, corners/chains, non-planar/cylindrical adjacent faces, fillets, variable distance, triangle migration, sketch solving, clipping, NURBS/freeform, and arbitrary BRep mutation.
+
+## Fallback policy
+
+The route computes the legacy chamfer first. If opt-in is disabled, the guard rejects, the candidate provider is missing, the provider throws, the candidate rejects/defers/fails, topology evidence is missing, STEP smoke fails, recognition parity fails, or 3D Boolean use is reported, execution returns the already-computed legacy body and emits fallback diagnostics.
+
+Legacy `BrepBoundedChamfer` remains default-authoritative. EDGE-V4 is not public stable API and is not a production default route replacement.
+
+## Diagnostics contract
+
+Deterministic EDGE-V4 diagnostics include:
+
+- `edge-v4-air-chamfer-opt-in-route-started`
+- `edge-v4-air-chamfer-opt-in-enabled`
+- `edge-v4-air-chamfer-opt-in-disabled`
+- `edge-v4-supported-case-accepted`
+- `edge-v4-supported-case-rejected:<reason>`
+- `edge-v4-air-chamfer-shadow-route-invoked`
+- `edge-v4-air-chamfer-candidate-selected`
+- `edge-v4-air-chamfer-candidate-rejected:<reason>`
+- `edge-v4-air-chamfer-candidate-failed-fallback`
+- `edge-v4-legacy-fallback-used`
+- `edge-v4-legacy-default-route-used`
+- `edge-v4-production-default-unchanged`
+- `edge-v4-no-3d-boolean-used`
+
+The selected test provider also preserves EDGE-V3 shadow diagnostics such as STEP smoke and recognition parity success.
+
+## Tests and results
+
+Focused tests live in `Aetheris.Kernel.Firmament.Tests/AirChamferFirmamentOptInRouteTests.cs`:
+
+- default disabled route uses the unchanged legacy result and does not select AirChamfer,
+- opt-in supported controlled case invokes the shadow route and selects the AirChamfer candidate,
+- unsupported non-planar face-family, edge-chain, corner-chain, and legacy-dependent triangle-style cases fallback to legacy with deterministic rejection diagnostics,
+- injected candidate failure falls back to legacy.
+
+## No-3D-Boolean guarantee
+
+EDGE-V4 does not call the 3D Boolean core in the AirChamfer candidate path. The executor emits `edge-v4-no-3d-boolean-used`, and the candidate must affirm no 3D Boolean use before selection.
+
+## Non-goals and limitations
+
+EDGE-V4 does not change STEP exporter/importer behavior, Boolean core behavior, fillet geometry, public stable APIs, arbitrary edge selection, edge/corner chains, triangle migration retry, sketch solving, clipping, NURBS, or freeform support. It does not make AirChamfer the default production chamfer route.
+
+## Next recommended milestone
+
+Recommended next work is **EDGE-V4.1 fallback/failure injection hardening** if route isolation needs more negative evidence, or **EDGE-V5** to add exactly one more controlled opt-in fixture after this route remains stable. If the focus shifts to fillets, begin with **EDGE-X14 AirFillet architecture audit**. For broader body mutation, use **EDGE-X15 controlled body mutation hardening** before widening Firmament selection.
diff --git a/docs/edge-x13-firmament-airchamfer-shadow-diagnostics.md b/docs/edge-x13-firmament-airchamfer-shadow-diagnostics.md
index 7989b242..c4517578 100644
--- a/docs/edge-x13-firmament-airchamfer-shadow-diagnostics.md
+++ b/docs/edge-x13-firmament-airchamfer-shadow-diagnostics.md
@@ -134,3 +134,7 @@ EDGE-X13 does not add or change:
## Recommended next milestone
The recommended next milestone is **EDGE-V4 controlled opt-in AirChamfer route** only if EDGE-X13 diagnostics and the EDGE-X12 corpus stability lane remain stable. If future work finds the Firmament seam too awkward for broader diagnostics, use **EDGE-X13.1 diagnostic seam hardening** before any route authorization. If priorities shift to fillets, use **EDGE-A2 / EDGE-FILLET-A0** instead.
+
+## EDGE-V4 follow-up
+
+EDGE-V4 builds on this shadow diagnostic probe by adding a gated internal/test-only Firmament execution seam. The new seam remains off by default, keeps legacy `BrepBoundedChamfer` authoritative for normal execution, and allows the AirChamfer candidate to become the result only for the exact controlled CH-03-style box edge when explicit experimental options and candidate evidence are supplied. Unsupported or failed cases fallback to legacy with deterministic EDGE-V4 diagnostics.