Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement CIR-T10 oracle trim consumption scaffold

Yuechen Li29ebce6d8696
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index cc604401..73d74847 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -692,4 +692,61 @@ public sealed class SurfacePatchDescriptorScaffoldTests
Assert.Contains(result.Entries.SelectMany(e => e.Candidate.Diagnostics), d => d.Contains("trim-capability-deferred", StringComparison.OrdinalIgnoreCase));
}
+ [Fact]
+ public void OracleTrimConsumption_BoxCylinder_EmitsInnerCirclePatch()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+
+ var emitted = result.Entries.Where(e => e.Emitted).ToArray();
+ Assert.Contains(emitted.SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-analytic-circle-consumed", StringComparison.OrdinalIgnoreCase));
+ var entry = Assert.Single(emitted.Where(e => e.IdentityMap?.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim) == true));
+ Assert.Equal(2, Assert.Single(entry.Emission!.Body!.Topology.Faces).LoopIds.Count);
+ }
+
+ [Fact]
+ public void OracleTrimConsumption_RequiresStrongEvidence()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirUnionNode(new CirCylinderNode(2, 8), new CirCylinderNode(2, 8)));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.DoesNotContain(result.Entries.SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-analytic-circle-consumed", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void OracleTrimConsumption_RejectsNumericalOnly()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.DoesNotContain(result.Entries.Where(e => e.Emitted).SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-analytic-circle-consumed", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void OracleTrimConsumption_BinderOracleAgreementDiagnosed()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.Contains(result.Entries.SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-binder-agreement", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void OracleTrimConsumption_UvToWorldNonCircularRejected()
+ {
+ 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 ok = OracleTrimLoopGeometryConverter.TryConvertAnalyticCircle(source, rep, "tok", out _, out var diagnostics);
+ Assert.False(ok);
+ Assert.Contains(diagnostics, d => d.Contains("non-uniform uv/world scale", StringComparison.OrdinalIgnoreCase));
+ }
+
}
diff --git a/Aetheris.Kernel.Firmament/Execution/OracleTrimLoopGeometryConverter.cs b/Aetheris.Kernel.Firmament/Execution/OracleTrimLoopGeometryConverter.cs
new file mode 100644
index 00000000..1915da94
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/OracleTrimLoopGeometryConverter.cs
@@ -0,0 +1,69 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal static class OracleTrimLoopGeometryConverter
+{
+ internal static bool TryConvertAnalyticCircle(
+ SourceSurfaceDescriptor planarSource,
+ TieredTrimCurveRepresentation oracleTrim,
+ string? orderingToken,
+ out RetainedCircularLoopGeometry geometry,
+ out IReadOnlyList<string> diagnostics)
+ {
+ var d = new List<string>();
+ geometry = default;
+
+ if (planarSource.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle } rect)
+ {
+ d.Add("oracle-trim-conversion-rejected: source planar patch is not bounded rectangle geometry.");
+ diagnostics = d;
+ return false;
+ }
+
+ if (oracleTrim.Kind != TieredTrimRepresentationKind.AnalyticCircle || oracleTrim.Circle is null)
+ {
+ d.Add("oracle-trim-conversion-rejected: oracle trim is not analytic-circle.");
+ diagnostics = d;
+ return false;
+ }
+
+ var uAxis = rect.Corner10 - rect.Corner00;
+ var vAxis = rect.Corner01 - rect.Corner00;
+ var uLen = uAxis.Length;
+ var vLen = vAxis.Length;
+ if (uLen <= 1e-9 || vLen <= 1e-9)
+ {
+ d.Add("oracle-trim-conversion-rejected: rectangle parameterization axes are degenerate.");
+ diagnostics = d;
+ return false;
+ }
+
+ // T10 policy: require near-uniform UV-to-world scaling to guarantee circular world result.
+ var relScaleDelta = Math.Abs(uLen - vLen) / Math.Max(uLen, vLen);
+ if (relScaleDelta > 1e-6)
+ {
+ d.Add($"oracle-trim-conversion-rejected: non-uniform uv/world scale would yield non-circular world trim (u={uLen:G6}, v={vLen:G6}).");
+ diagnostics = d;
+ return false;
+ }
+
+ var uDir = uAxis / uLen;
+ var vDir = vAxis / vLen;
+ var c = oracleTrim.Circle;
+ var center = rect.Center + (uDir * c.CenterU) + (vDir * c.CenterV);
+ var radius = c.RadiusUV;
+
+ var token = string.IsNullOrWhiteSpace(orderingToken) ? string.Empty : orderingToken!;
+ if (string.IsNullOrWhiteSpace(token))
+ {
+ d.Add("oracle-trim-conversion-warning: internal ordering token unavailable from retained loop evidence.");
+ }
+
+ geometry = new RetainedCircularLoopGeometry(center, rect.Normal, radius, RetainedRegionLoopOrientationPolicy.ReverseForToolCavity, token,
+ "oracle-trim-conversion-success: analytic-circle UV converted to retained world circular geometry.");
+ d.Add("oracle-trim-conversion-success: analytic-circle UV converted to world circular geometry.");
+ diagnostics = d;
+ return true;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index 147fa603..1d8c6b43 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -324,14 +324,83 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
}
var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);
- var retainedCircles = candidate.RetainedRegionLoops
+ var retainedLoops = candidate.RetainedRegionLoops
.Where(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim
- && l.CircularGeometry is not null
&& (l.Status == RetainedRegionLoopStatus.ExactReady || l.Status == RetainedRegionLoopStatus.SpecialCaseReady))
- .Select(l => l.CircularGeometry!.Value)
.ToArray();
+ var retainedCircles = retainedLoops.Where(l => l.CircularGeometry is not null).Select(l => l.CircularGeometry!.Value).ToArray();
+ var entryDiagnostics = new List<string>();
+ var oracleCircles = new List<RetainedCircularLoopGeometry>();
+ foreach (var loop in retainedLoops)
+ {
+ if (!loop.OracleTrimStrongEvidence)
+ {
+ if (loop.OracleTrimRepresentation is not null)
+ {
+ entryDiagnostics.Add("oracle-trim-consumption-rejected: broad/deferred oracle evidence is not materialization-grade.");
+ }
+
+ continue;
+ }
+
+ if (loop.OracleTrimRoutingDiagnostic != "oracle-trim: selected-opposite-field-used")
+ {
+ entryDiagnostics.Add("oracle-trim-consumption-rejected: selected-opposite-field routing confirmation missing.");
+ continue;
+ }
+
+ var oracle = loop.OracleTrimRepresentation;
+ if (oracle is null)
+ {
+ 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)
+ {
+ entryDiagnostics.Add("oracle-trim-consumption-rejected: strong oracle flags do not satisfy materialization constraints.");
+ continue;
+ }
+
+ if (OracleTrimLoopGeometryConverter.TryConvertAnalyticCircle(candidate.SourceSurface, oracle, loop.CircularGeometry?.OrderingToken, out var converted, out var convertedDiagnostics))
+ {
+ oracleCircles.Add(converted);
+ entryDiagnostics.AddRange(convertedDiagnostics);
+ entryDiagnostics.Add("oracle-trim-analytic-circle-consumed: converted analytic-circle evidence was admitted for inner-loop emission.");
+ }
+ else
+ {
+ entryDiagnostics.AddRange(convertedDiagnostics);
+ entryDiagnostics.Add("oracle-trim-consumption-rejected: uv-to-world conversion unsafe.");
+ }
+ }
+
+ if (retainedCircles.Length == 1 && oracleCircles.Count == 1)
+ {
+ var binder = retainedCircles[0];
+ var oracle = oracleCircles[0];
+ var centerDelta = (binder.Center - oracle.Center).Length;
+ var radiusDelta = Math.Abs(binder.Radius - oracle.Radius);
+ if (centerDelta <= 1e-4 && radiusDelta <= 1e-4)
+ {
+ entryDiagnostics.Add("oracle-trim-binder-agreement: binder and oracle circles agree within tolerance.");
+ }
+ else
+ {
+ entryDiagnostics.Add($"oracle-trim-binder-mismatch: centerDelta={centerDelta:G6} radiusDelta={radiusDelta:G6}; conservative skip applied.");
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, entryDiagnostics));
+ continue;
+ }
+ }
+
+ var chosenCircles = oracleCircles.Count > 0 ? oracleCircles.ToArray() : retainedCircles;
SurfaceMaterializationResult? emission = null;
- if (retainedCircles.Length == 0)
+ if (chosenCircles.Length == 0)
{
if (candidate.SourceSurface.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle })
{
@@ -359,9 +428,9 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
continue;
}
- if (retainedCircles.Length > 1)
+ if (chosenCircles.Length > 1)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-multiple-inner-loops: found {retainedCircles.Length} exact-ready retained circular loops; only one is supported in CIR-F10.8."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-multiple-inner-loops: found {chosenCircles.Length} exact-ready retained circular loops; only one is supported in CIR-F10.8."]));
continue;
}
@@ -373,7 +442,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
}
normalizedTrimmedSource = normalizedTrimmedSource with { ParameterPayloadReference = trimmedPayload };
- emission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, retainedCircles[0], null, readiness));
+ emission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, chosenCircles[0], null, readiness));
if (!emission.Success)
{
entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, emission.Diagnostics));
@@ -384,6 +453,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
var innerTokenPresent = emission.IdentityMap?.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim && x.TrimIdentityToken is not null) == true;
entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap,
[
+ ..entryDiagnostics,
"emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop.",
innerTokenPresent
? "emitted-identity-token-attached: inner circular trim token attached on emitted planar topology."
diff --git a/docs/cir-t10-oracle-trim-consumption.md b/docs/cir-t10-oracle-trim-consumption.md
new file mode 100644
index 00000000..538e19a1
--- /dev/null
+++ b/docs/cir-t10-oracle-trim-consumption.md
@@ -0,0 +1,46 @@
+# CIR-T10 — consume oracle-derived analytic circle trims in planar materializer path
+
+## Purpose
+CIR-T10 wires strong selected-field trim-oracle evidence into planar retained patch-set emission for `Subtract(Box, Cylinder)` base-side planar retained patches.
+
+## Strong evidence requirements
+Oracle trim is consumed only when all gates hold:
+- `OracleTrimStrongEvidence == true`
+- routing diagnostic is `oracle-trim: selected-opposite-field-used`
+- representation kind is `AnalyticCircle`
+- `AcceptedInternalAnalyticCandidate == true`
+- `ExactStepExported == false`
+- `BRepTopologyEmitted == false`
+- source bounded planar geometry is a rectangle
+
+Broad/deferred evidence remains diagnostic-only and is explicitly rejected as non-materialization grade.
+
+## UV→world conversion policy
+`OracleTrimLoopGeometryConverter.TryConvertAnalyticCircle(...)` converts analytic circle UV data into retained circular loop geometry using planar rectangle parameterization axes.
+
+T10 policy is conservative:
+- reject degenerate rectangle parameterization,
+- reject non-uniform U/V world scaling (would create world ellipse from UV circle),
+- emit precise diagnostics on rejection.
+
+## Binder/oracle comparison policy
+If both binder-derived and oracle-derived circles exist:
+- compare center/radius with tight tolerance,
+- if agreement: diagnose agreement and continue,
+- if mismatch: conservative skip/defer with mismatch diagnostic.
+
+## Rejected cases
+- broad-only oracle routes,
+- numerical-only/deferred/unsupported representations,
+- sphere/torus non-analytic-circle routes,
+- multiple inner loops,
+- unsafe UV→world conversions.
+
+## Out-of-scope guarantees
+- no shell assembly,
+- no STEP export behavior changes,
+- no boolean behavior changes,
+- no generated topology naming changes.
+
+## Next step
+Generalize conversion provenance/tolerance contracts so additional exact analytic retained-loop routes can be consumed without weakening SEM-A0 guardrails.