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.csnew file mode 100644index 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.csnew file mode 100644index 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.csindex 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.mdindex 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.mdindex 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 noteEDGE-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.mdnew file mode 100644index 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.mdindex 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 milestoneThe 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.