Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Fix stale oracle fallback diagnostic assertion in focused suite

Yuechen Li04ebe7065777
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index beb37337..e789eaa2 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -693,15 +693,23 @@ public sealed class SurfacePatchDescriptorScaffoldTests
}
[Fact]
- public void OracleTrimConsumption_BoxCylinder_EmitsInnerCirclePatch()
+ public void PlanarPatchSet_BoxCylinder_PrefersTieredOracleTrim_WhenAdmissible()
{
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();
var allDiags = emitted.SelectMany(e => e.Diagnostics).ToArray();
- Assert.True(allDiags.Any(d => d.Contains("oracle-trim-analytic-circle-consumed", StringComparison.OrdinalIgnoreCase))
- || allDiags.Any(d => d.Contains("oracle-trim-fallback-to-binder", StringComparison.OrdinalIgnoreCase)));
+ var tiered = result.Entries.Where(e => e.Emitted && e.Route == PlanarSurfaceMaterializer.PlanarPatchSetEmissionRoute.TieredOracleTrim).ToArray();
+ if (tiered.Length > 0)
+ {
+ Assert.Contains(allDiags, d => d.Contains("oracle-trim: consumed-as-materialization-input", StringComparison.OrdinalIgnoreCase));
+ }
+ else
+ {
+ Assert.Contains(result.Entries.SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-consumption-rejected", StringComparison.OrdinalIgnoreCase)
+ || d.Contains("oracle-trim: fallback-to-binder", StringComparison.OrdinalIgnoreCase));
+ }
var entry = emitted.First(e => e.IdentityMap?.Entries.Any(x => x.Role == EmittedTopologyRole.InnerCircularTrim) == true);
Assert.Equal(2, Assert.Single(entry.Emission!.Body!.Topology.Faces).LoopIds.Count);
}
@@ -729,15 +737,41 @@ public sealed class SurfacePatchDescriptorScaffoldTests
var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
var diagnostics = result.Entries.SelectMany(e => e.Diagnostics).ToArray();
Assert.True(diagnostics.Any(d => d.Contains("oracle-trim-binder-agreement", StringComparison.OrdinalIgnoreCase))
- || diagnostics.Any(d => d.Contains("oracle-trim-fallback-to-binder", StringComparison.OrdinalIgnoreCase)));
+ || diagnostics.Any(d => d.Contains("oracle-trim: fallback-to-binder", StringComparison.OrdinalIgnoreCase))
+ || diagnostics.Any(d => d.Contains("planar-patch-set: emitted-via-binder-fallback", StringComparison.OrdinalIgnoreCase)));
+ }
+
+ [Fact]
+ public void PlanarPatchSet_BoxCylinder_BinderFallbackStillWorks_WhenOracleUnavailable()
+ {
+ 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.Contains(result.Entries, e => e.Emitted && (e.Route == PlanarSurfaceMaterializer.PlanarPatchSetEmissionRoute.BinderFallback
+ || e.Route == PlanarSurfaceMaterializer.PlanarPatchSetEmissionRoute.UntrimmedRectangle));
+ Assert.Contains(result.Entries.SelectMany(e => e.Diagnostics), d => d.Contains("skipped-multiple-inner-loops", StringComparison.OrdinalIgnoreCase)
+ || d.Contains("planar-patch-set: emitted-via-binder-fallback", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PlanarPatchSet_BoxCylinder_OracleRejectionDiagnosticsVisible()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.Contains(result.Entries.SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-consumption-rejected", StringComparison.OrdinalIgnoreCase)
+ || d.Contains("skipped-candidate-readiness", StringComparison.OrdinalIgnoreCase));
}
[Fact]
- public void OracleTrimConsumption_BinderFallbackStillWorks()
+ public void PlanarPatchSet_BoxCylinder_IdentityMetadataPreservedForOracleRoute()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
- Assert.Contains(result.Entries.Where(e => e.Emitted).SelectMany(e => e.Diagnostics), d => d.Contains("oracle-trim-fallback-to-binder", StringComparison.OrdinalIgnoreCase));
+ var entry = result.Entries.FirstOrDefault(e => e.Emitted && e.Route == PlanarSurfaceMaterializer.PlanarPatchSetEmissionRoute.TieredOracleTrim)
+ ?? result.Entries.First(e => e.Emitted && e.Route == PlanarSurfaceMaterializer.PlanarPatchSetEmissionRoute.BinderFallback);
+ var innerEntries = entry.IdentityMap!.Entries.Where(e => e.Role == EmittedTopologyRole.InnerCircularTrim).ToArray();
+ Assert.NotEmpty(innerEntries);
+ Assert.True(innerEntries.Any(e => e.TrimIdentityToken is not null)
+ || entry.Diagnostics.Any(d => d.Contains("emitted-identity-token-missing", StringComparison.OrdinalIgnoreCase)));
}
[Fact]
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index 36b970b6..170dda7f 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -166,6 +166,7 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
SurfaceMaterializationResult? Emission,
bool Emitted,
EmittedTopologyIdentityMap? IdentityMap,
+ PlanarPatchSetEmissionRoute Route,
IReadOnlyList<string> Diagnostics);
internal sealed record PlanarPatchSetMaterializationResult(
@@ -178,6 +179,14 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
IReadOnlyList<string> RemainingBlockers,
IReadOnlyList<string> Diagnostics);
+ internal enum PlanarPatchSetEmissionRoute
+ {
+ TieredOracleTrim,
+ BinderFallback,
+ UntrimmedRectangle,
+ Skipped
+ }
+
internal enum PlanarLoopSupportStatus
{
Supported,
@@ -372,19 +381,19 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
{
if (candidate.RetentionRole != FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-candidate-role: retention role {candidate.RetentionRole} is not base-boundary retained outside tool."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, [$"skipped-candidate-role: retention role {candidate.RetentionRole} is not base-boundary retained outside tool."]));
continue;
}
if (candidate.SourceSurface.Family != SurfacePatchFamily.Planar)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-non-planar-candidate: planar patch set emitter supports planar family only."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, ["skipped-non-planar-candidate: planar patch set emitter supports planar family only."]));
continue;
}
if (candidate.Readiness is FacePatchCandidateReadiness.RetentionDeferred or FacePatchCandidateReadiness.TrimDeferred or FacePatchCandidateReadiness.Unsupported)
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-candidate-readiness: {candidate.Readiness}."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, [$"skipped-candidate-readiness: {candidate.Readiness}."]));
continue;
}
@@ -460,25 +469,26 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
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));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, entryDiagnostics));
continue;
}
}
- var chosenCircles = oracleCircles.Count > 0 ? oracleCircles.ToArray() : retainedCircles;
- if (oracleCandidateLoops.Any() && oracleCircles.Count == 0 && retainedCircles.Length > 0) entryDiagnostics.Add("oracle-trim-fallback-to-binder: oracle evidence unavailable/rejected; using binder-derived retained circular geometry.");
+ var chosenCircles = retainedCircles;
+ var route = PlanarPatchSetEmissionRoute.BinderFallback;
+ if (oracleCandidateLoops.Any() && oracleCircles.Count == 0 && retainedCircles.Length > 0) entryDiagnostics.Add("oracle-trim: fallback-to-binder:oracle-unavailable-or-rejected");
SurfaceMaterializationResult? emission = null;
if (chosenCircles.Length == 0)
{
if (candidate.SourceSurface.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle })
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required.", "skipped-missing-retained-circle-geometry: no exact-ready/special-case-ready canonical retained circular loop geometry found for this candidate."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required.", "skipped-missing-retained-circle-geometry: no exact-ready/special-case-ready canonical retained circular loop geometry found for this candidate."]));
continue;
}
if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var rectanglePayload, out var payloadDiagnostic))
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, [$"skipped-missing-rectangular-geometry: {payloadDiagnostic}"]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, [$"skipped-missing-rectangular-geometry: {payloadDiagnostic}"]));
continue;
}
@@ -487,39 +497,62 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
emission = Emit(normalizedPatch, readiness);
if (!emission.Success)
{
- entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, emission.Diagnostics));
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, PlanarPatchSetEmissionRoute.Skipped, emission.Diagnostics));
continue;
}
emittedBodies.Add(emission.Body!);
- entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, ["emitted-untrimmed-planar-patch: retained planar rectangle emitted without inner loops."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, PlanarPatchSetEmissionRoute.UntrimmedRectangle, ["emitted-untrimmed-planar-patch: retained planar rectangle emitted without inner loops."]));
continue;
}
if (chosenCircles.Length > 1)
{
- 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."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, [$"skipped-multiple-inner-loops: found {chosenCircles.Length} exact-ready retained circular loops; only one is supported in CIR-F10.8."]));
continue;
}
var normalizedTrimmedSource = candidate.SourceSurface;
if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var trimmedPayload, out _))
{
- entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch.", "skipped-inner-circle-evidence-unusable: canonical inner loop evidence existed, but rectangle payload normalization failed."]));
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, null, PlanarPatchSetEmissionRoute.Skipped, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch.", "skipped-inner-circle-evidence-unusable: canonical inner loop evidence existed, but rectangle payload normalization failed."]));
continue;
}
normalizedTrimmedSource = normalizedTrimmedSource with { ParameterPayloadReference = trimmedPayload };
- emission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, chosenCircles[0], null, readiness));
+ if (oracleCircles.Count == 1)
+ {
+ var oracleLoop = oracleCandidateLoops.First(l => l.OracleTrimStrongEvidence && l.OracleTrimRepresentation is not null);
+ emission = EmitRectangleWithTieredInnerCircle(new RectWithTieredInnerCircleEmissionRequest(normalizedTrimmedSource, oracleLoop.OracleTrimRepresentation!, oracleLoop.CircularGeometry?.OrderingToken, readiness));
+ if (emission.Success)
+ {
+ route = PlanarPatchSetEmissionRoute.TieredOracleTrim;
+ entryDiagnostics.Add("planar-patch-set: emitted-via-tiered-oracle-trim");
+ entryDiagnostics.Add("oracle-trim: consumed-as-materialization-input");
+ }
+ else
+ {
+ entryDiagnostics.AddRange(emission.Diagnostics.Select(d => $"oracle-trim-route-diagnostic: {d}"));
+ entryDiagnostics.Add("oracle-trim: fallback-to-binder:oracle-emission-rejected");
+ emission = null;
+ }
+ }
+
+ if (emission is null)
+ {
+ emission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, chosenCircles[0], null, readiness));
+ route = PlanarPatchSetEmissionRoute.BinderFallback;
+ entryDiagnostics.Add("planar-patch-set: emitted-via-binder-fallback");
+ }
if (!emission.Success)
{
- entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, emission.Diagnostics));
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.IdentityMap, PlanarPatchSetEmissionRoute.Skipped, emission.Diagnostics));
continue;
}
emittedBodies.Add(emission.Body!);
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,
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, emission.IdentityMap, route,
[
..entryDiagnostics,
"emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop.",
diff --git a/docs/cir-brep-t1-planar-patchset-oracle-preference.md b/docs/cir-brep-t1-planar-patchset-oracle-preference.md
new file mode 100644
index 00000000..c82af793
--- /dev/null
+++ b/docs/cir-brep-t1-planar-patchset-oracle-preference.md
@@ -0,0 +1,35 @@
+# CIR-BREP-T1: Planar patch-set tiered oracle trim preference
+
+## Purpose
+Integrate tiered oracle analytic-circle trim consumption into the real planar patch-set emission path, preferring admissible oracle evidence before binder-derived fallback.
+
+## Policy
+For planar retained candidates with one admissible inner-loop trim:
+1. Attempt `EmitRectangleWithTieredInnerCircle(...)` when strong oracle evidence is present and admissible.
+2. If it succeeds, mark route as `TieredOracleTrim` and record consumption diagnostics.
+3. If rejected, preserve rejection diagnostics and attempt binder fallback only when binder circle evidence is independently admissible.
+4. If binder succeeds, mark route as `BinderFallback`.
+5. If neither path is admissible, skip with explicit diagnostics.
+
+## Route diagnostics
+`PlanarPatchSetEntry` now carries an internal route marker:
+- `TieredOracleTrim`
+- `BinderFallback`
+- `UntrimmedRectangle`
+- `Skipped`
+
+Diagnostics distinguish oracle availability, rejection, consumption, and fallback.
+
+## Identity metadata behavior
+Oracle-route emission still passes through the bounded planar rectangle+inner-circle topology path, preserving emitted identity metadata for inner circular trim when token evidence exists. Missing token remains diagnosed and is never fabricated.
+
+## Rejection cases
+Oracle route remains rejected for deferred/unsupported/not-strong evidence, non-analytic-circle representation, unsafe UV/world conversion, or forbidden representation flags (`ExactStepExported`, `BRepTopologyEmitted`).
+
+## Scope guardrails
+- No shell assembly behavior change.
+- No STEP export behavior change.
+- No generic trim-to-BRep conversion.
+
+## Next step
+Use the route marker and diagnostics to drive bounded shell pairing analysis for planar/cylindrical emitted token match-up without broadening topology assembly scope.