Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add oracle trim admissibility model for planar patch-set routing
Yuechen Li0a682fe0a4cc
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.csindex e789eaa2..9893cdf1 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs@@ -774,6 +774,34 @@ public sealed class SurfacePatchDescriptorScaffoldTests|| entry.Diagnostics.Any(d => d.Contains("emitted-identity-token-missing", StringComparison.OrdinalIgnoreCase)));}+ [Fact]+ public void OracleAdmissibility_BoxCylinder_ExplainsCurrentPolicy()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var candidate = FacePatchCandidateGenerator.Generate(root).Candidates+ .First(c => c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool && c.SourceSurface.Family == SurfacePatchFamily.Planar);+ var loop = candidate.RetainedRegionLoops.First(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.OracleTrimRepresentation is not null);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);++ var result = PlanarSurfaceMaterializer.OracleTrimMaterializationAdmissibility.Evaluate(candidate.SourceSurface, loop.OracleTrimRepresentation!, readiness, loop.CircularGeometry?.OrderingToken);+ Assert.True(result.Admissible || result.Blocker != PlanarSurfaceMaterializer.OracleTrimMaterializationBlocker.None);+ }++ [Fact]+ public void OracleAdmissibility_RejectsNumericalOnly()+ {+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "top",+ BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(-3,-3,0), new Point3D(3,-3,0), new Point3D(3,3,0), new Point3D(-3,3,0), new Vector3D(0,0,1)),+ null, Transform3D.Identity, "synthetic", nameof(CirBoxNode), null, FacePatchOrientationRole.Forward);+ var num = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.NumericalOnly, TieredTrimExportCapability.NumericalOnlyNotExportable,+ null, null, new NumericalTrimContourData(1, [], true, SurfaceTrimContourChainStatus.ClosedLoop, []),+ new TrimSurfaceIntersectionProvenance(null, null, null, null, [], 1, RestrictedContourSnapRouteKind.NumericalOnly, []), false, false, false, []);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);+ var result = PlanarSurfaceMaterializer.OracleTrimMaterializationAdmissibility.Evaluate(source, num, readiness, "tok");+ Assert.False(result.Admissible);+ Assert.Equal(PlanarSurfaceMaterializer.OracleTrimMaterializationBlocker.NumericalOnly, result.Blocker);+ }+[Fact]public void PlanarSurfaceMaterializer_TieredAnalyticCircle_EmitsInnerLoop(){@@ -871,4 +899,37 @@ public sealed class SurfacePatchDescriptorScaffoldTestsAssert.Contains(diagnostics, d => d.Contains("non-uniform uv/world scale", StringComparison.OrdinalIgnoreCase));}+ [Fact]+ public void OracleAdmissibility_RejectsNonUniformUvWorldScale()+ {+ var source = new SourceSurfaceDescriptor(+ SurfacePatchFamily.Planar,+ "top",+ BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(0,0,0), new Point3D(4,0,0), new Point3D(4,1,0), new Point3D(0,1,0), new Vector3D(0,0,1)),+ null, Transform3D.Identity, "synthetic", nameof(CirBoxNode), null, FacePatchOrientationRole.Forward);+ var rep = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.AnalyticCircle, TieredTrimExportCapability.ElementaryCurveCandidate,+ new AnalyticCircleTrimData(2, 0.5, 0.25, 0, 0, 16), null, null,+ new TrimSurfaceIntersectionProvenance(null, null, null, null, [], null, RestrictedContourSnapRouteKind.AnalyticCircle, []), true, false, false, []);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);+ var emission = new PlanarSurfaceMaterializer().EmitRectangleWithTieredInnerCircle(new(source, rep, "tok", readiness));+ Assert.False(emission.Success);+ Assert.Contains(emission.Diagnostics, d => d.Contains("non-uniform", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void OracleAdmissibility_RejectsMissingIdentityIfRequired()+ {+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "top",+ BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(-3,-3,0), new Point3D(3,-3,0), new Point3D(3,3,0), new Point3D(-3,3,0), new Vector3D(0,0,1)),+ null, Transform3D.Identity, "synthetic", nameof(CirBoxNode), null, FacePatchOrientationRole.Forward);+ var rep = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.AnalyticCircle, TieredTrimExportCapability.ElementaryCurveCandidate,+ new AnalyticCircleTrimData(0, 0, 1, 0, 0, 8), null, null,+ new TrimSurfaceIntersectionProvenance(null, null, null, null, [], null, RestrictedContourSnapRouteKind.AnalyticCircle, []), true, false, false, []);+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);+ var result = PlanarSurfaceMaterializer.OracleTrimMaterializationAdmissibility.Evaluate(source, rep, readiness, null);+ Assert.True(result.Admissible);+ Assert.False(result.IdentityTokenSatisfied);+ Assert.Contains(result.Diagnostics, d => d.Contains("identity-token-missing", StringComparison.OrdinalIgnoreCase));+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.csindex 170dda7f..e049dc3c 100644--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs@@ -233,6 +233,52 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializerstring? OrderingToken,MaterializationReadinessReport Readiness);+ internal enum OracleTrimMaterializationBlocker+ {+ None,+ ReadinessBlocked,+ MissingPlanarRectangle,+ WrongKind,+ NotAcceptedAnalyticCandidate,+ NumericalOnly,+ ExactStepAlreadyExportedUnexpected,+ BRepAlreadyEmittedUnexpected,+ MissingIdentityToken,+ Unknown+ }++ internal sealed record OracleTrimMaterializationAdmissibilityResult(+ bool Admissible,+ PlanarPatchSetEmissionRoute Route,+ OracleTrimMaterializationBlocker Blocker,+ string ExactnessTier,+ bool ConversionSafetyRequired,+ bool IdentityTokenSatisfied,+ IReadOnlyList<string> Diagnostics);++ internal static class OracleTrimMaterializationAdmissibility+ {+ internal static OracleTrimMaterializationAdmissibilityResult Evaluate(SourceSurfaceDescriptor planarSource, TieredTrimCurveRepresentation trim, MaterializationReadinessReport readiness, string? orderingToken)+ {+ var diagnostics = new List<string>();+ if (readiness.OverallReadiness is EmissionReadiness.NotApplicable or EmissionReadiness.Deferred or EmissionReadiness.Unsupported)+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, OracleTrimMaterializationBlocker.ReadinessBlocked, "none", true, orderingToken is not null, ["tiered-trim-consumption-rejected: readiness is not evidence-ready for BRep planar inner-loop emission."]);+ if (planarSource.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle })+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, OracleTrimMaterializationBlocker.MissingPlanarRectangle, "none", true, orderingToken is not null, ["tiered-trim-consumption-rejected: bounded rectangular planar geometry is required."]);+ if (trim.Kind != TieredTrimRepresentationKind.AnalyticCircle)+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, trim.Kind is TieredTrimRepresentationKind.NumericalOnly or TieredTrimRepresentationKind.Deferred or TieredTrimRepresentationKind.Unsupported ? OracleTrimMaterializationBlocker.NumericalOnly : OracleTrimMaterializationBlocker.WrongKind, "numerical-or-non-circle", true, orderingToken is not null, ["tiered-trim-consumption-rejected: wrong representation kind; analytic-circle is required for bounded planar inner-loop emission."]);+ if (!trim.AcceptedInternalAnalyticCandidate || trim.Circle is null)+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, OracleTrimMaterializationBlocker.NotAcceptedAnalyticCandidate, "analytic-candidate-only", true, orderingToken is not null, ["tiered-trim-consumption-rejected: analytic candidate was not accepted internally."]);+ if (trim.ExactStepExported)+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, OracleTrimMaterializationBlocker.ExactStepAlreadyExportedUnexpected, "analytic-circle", true, orderingToken is not null, ["tiered-trim-consumption-rejected: representation flags violate bounded intake contract (step already exported)."]);+ if (trim.BRepTopologyEmitted)+ return new(false, PlanarPatchSetEmissionRoute.BinderFallback, OracleTrimMaterializationBlocker.BRepAlreadyEmittedUnexpected, "analytic-circle", true, orderingToken is not null, ["tiered-trim-consumption-rejected: representation flags violate bounded intake contract (topology already emitted)."]);+ if (orderingToken is null) diagnostics.Add("tiered-trim-identity-token-missing: oracle route allowed but emitted identity token may be unavailable.");+ diagnostics.Add("tiered-trim-analytic-circle-admitted: admissibility constraints satisfied for bounded planar inner-loop emission.");+ return new(true, PlanarPatchSetEmissionRoute.TieredOracleTrim, OracleTrimMaterializationBlocker.None, "analytic-circle", true, orderingToken is not null, diagnostics);+ }+ }+public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch){if (patch.SourceSurface.Family != SurfacePatchFamily.Planar) return new(false, "Source surface family mismatch.", 0d);@@ -314,41 +360,12 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializerinternal SurfaceMaterializationResult EmitRectangleWithTieredInnerCircle(RectWithTieredInnerCircleEmissionRequest request){var diagnostics = new List<string>();+ var admissibility = OracleTrimMaterializationAdmissibility.Evaluate(request.Source, request.InnerTrim, request.Readiness, request.OrderingToken);+ if (!admissibility.Admissible)+ return new(false, null, SurfacePatchFamily.Planar, false, admissibility.Diagnostics.ToArray());+ diagnostics.AddRange(admissibility.Diagnostics);- if (request.Readiness.OverallReadiness is EmissionReadiness.NotApplicable or EmissionReadiness.Deferred or EmissionReadiness.Unsupported)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["readiness-gate-rejected: no readiness, no emission.", "tiered-trim-consumption-rejected: readiness is not evidence-ready for BRep planar inner-loop emission."]);- }-- var trim = request.InnerTrim;- if (trim.Kind != TieredTrimRepresentationKind.AnalyticCircle)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["tiered-trim-consumption-rejected: wrong representation kind; analytic-circle is required for bounded planar inner-loop emission."]);- }-- if (!trim.AcceptedInternalAnalyticCandidate)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["tiered-trim-consumption-rejected: analytic candidate was not accepted internally."]);- }-- if (trim.Circle is null)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["tiered-trim-consumption-rejected: analytic-circle payload missing."]);- }-- if (trim.ExactStepExported || trim.BRepTopologyEmitted)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["tiered-trim-consumption-rejected: representation flags violate bounded intake contract (step/topology already emitted)."]);- }-- if (trim.Kind is TieredTrimRepresentationKind.NumericalOnly or TieredTrimRepresentationKind.Deferred or TieredTrimRepresentationKind.Unsupported)- {- return new(false, null, SurfacePatchFamily.Planar, false, ["tiered-trim-consumption-rejected: numerical-only/deferred/unsupported tiered trim is not materialization-grade for this path."]);- }-- diagnostics.Add("tiered-trim-analytic-circle-admitted: admissibility constraints satisfied for bounded planar inner-loop emission.");-- if (!OracleTrimLoopGeometryConverter.TryConvertAnalyticCircle(request.Source, trim, request.OrderingToken, out var converted, out var conversionDiagnostics))+ if (!OracleTrimLoopGeometryConverter.TryConvertAnalyticCircle(request.Source, request.InnerTrim, request.OrderingToken, out var converted, out var conversionDiagnostics)){diagnostics.AddRange(conversionDiagnostics);if (conversionDiagnostics.Any(d => d.Contains("non-uniform uv/world scale", StringComparison.OrdinalIgnoreCase)))@@ -430,16 +447,11 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer{continue;}-- if (oracle.Kind != TieredTrimRepresentationKind.AnalyticCircle)- {- entryDiagnostics.Add("oracle-trim-consumption-rejected: numerical-only/deferred oracle representation is not consumable.");- continue;- }-- if (!oracle.AcceptedInternalAnalyticCandidate || oracle.ExactStepExported || oracle.BRepTopologyEmitted)+ var admissibility = OracleTrimMaterializationAdmissibility.Evaluate(candidate.SourceSurface, oracle, readiness, loop.CircularGeometry?.OrderingToken);+ if (!admissibility.Admissible){- entryDiagnostics.Add("oracle-trim-consumption-rejected: strong oracle flags do not satisfy materialization constraints.");+ entryDiagnostics.AddRange(admissibility.Diagnostics.Select(d => $"oracle-trim-route-diagnostic: {d}"));+ entryDiagnostics.Add($"oracle-trim-admissibility-blocker: {admissibility.Blocker}");continue;}@@ -447,6 +459,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer{oracleCircles.Add(converted);entryDiagnostics.AddRange(convertedDiagnostics);+ entryDiagnostics.AddRange(admissibility.Diagnostics);entryDiagnostics.Add("oracle-trim-analytic-circle-consumed: converted analytic-circle evidence was admitted for inner-loop emission.");}elsediff --git a/docs/cir-brep-t2-oracle-admissibility-policy.md b/docs/cir-brep-t2-oracle-admissibility-policy.mdnew file mode 100644index 00000000..2e836d44--- /dev/null+++ b/docs/cir-brep-t2-oracle-admissibility-policy.md@@ -0,0 +1,52 @@+# CIR-BREP-T2 Oracle Admissibility Policy++## Outcome++CIR-BREP-T2 lands a generalized oracle trim admissibility gate for planar patch-set inner-loop materialization.++## Gap classification++Current blocker class is primarily **B (Exactness/materialization-grade contract)** with a secondary **D (identity diagnostics completeness)** concern.++- Tiered oracle evidence may be present but is not materialization-grade unless analytic-circle + accepted-internal + bounded intake flags are satisfied.+- Numerical/deferred/unsupported tiers remain diagnostic-only.+- Identity token is currently treated as a diagnosable quality signal (not a hard blocker) for planar patch-set promotion.++## Generalized admissibility model++`PlanarSurfaceMaterializer.OracleTrimMaterializationAdmissibility.Evaluate(...)` centralizes route eligibility checks and emits:++- admissible yes/no,+- fallback route target,+- blocker enum,+- exactness tier label,+- conversion safety requirement flag,+- identity token status,+- deterministic diagnostics.++## Policy decision++**Policy A — oracle materialization-grade allowed when admissibility passes.**++For real `Subtract(Box,Cylinder)` planar patch-set candidates:++- try oracle route first when strong selected-opposite evidence exists,+- reject with explicit blocker diagnostics when inadmissible,+- preserve binder fallback as safe route.++## Safety constraints retained++- No numerical-only promotion.+- No deferred/unsupported promotion.+- No promotion when readiness or bounded planar rectangle prerequisites fail.+- UV→world conversion remains a hard post-admissibility gate; non-uniform scale rejects.+- Binder fallback remains available and explicit.++## Non-goals (unchanged)++- shell assembly,+- topology stitching,+- STEP behavior changes,+- BSpline fitting,+- torus recognition expansion,+- boolean scope expansion.