Skip to content

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.cs
index 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 SurfacePatchDescriptorScaffoldTests
Assert.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.cs
index 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 : ISurfaceFamilyMaterializer
string? 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 : ISurfaceFamilyMaterializer
internal 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.");
}
else
diff --git a/docs/cir-brep-t2-oracle-admissibility-policy.md b/docs/cir-brep-t2-oracle-admissibility-policy.md
new file mode 100644
index 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.