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.csindex cc604401..73d74847 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs@@ -692,4 +692,61 @@ public sealed class SurfacePatchDescriptorScaffoldTestsAssert.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.csnew file mode 100644index 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.csindex 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 : ISurfaceFamilyMaterializercontinue;}- 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 : ISurfaceFamilyMaterializervar 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.mdnew file mode 100644index 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.