Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-T8.1 deterministic opposite-surface routing for trim oracle evidence

Yuechen Li19b54943a35a
diff --git a/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs
new file mode 100644
index 00000000..4626a8be
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs
@@ -0,0 +1,61 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class RetainedLoopTrimOracleIntegrationTests
+{
+ [Fact]
+ public void OracleTrimRouting_BoxCylinder_SelectsSpecificOpposite()
+ {
+ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));
+ var loop = result.Candidates.SelectMany(c => c.RetainedRegionLoops).First(l => l.OracleTrimRepresentation is not null && l.OracleTrimStrongEvidence);
+ Assert.Equal("oracle-trim: specific-opposite-selected", loop.OracleTrimRoutingDiagnostic);
+ Assert.Equal(TieredTrimRepresentationKind.AnalyticCircle, loop.OracleTrimRepresentation!.Kind);
+ Assert.False(loop.OracleTrimRepresentation.ExactStepExported);
+ Assert.False(loop.OracleTrimRepresentation.BRepTopologyEmitted);
+ }
+
+ [Fact]
+ public void OracleTrimRouting_BoxSphere_SelectsSpecificOpposite()
+ {
+ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirSphereNode(6)));
+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRoutingDiagnostic == "oracle-trim: specific-opposite-selected");
+ }
+
+ [Fact]
+ public void OracleTrimRouting_BoxTorus_NoGenericExactness()
+ {
+ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(12,12,12), new CirTorusNode(4,1)));
+ var oracle = result.Candidates.SelectMany(c => c.RetainedRegionLoops).Select(l => l.OracleTrimRepresentation).FirstOrDefault(r => r is not null);
+ Assert.NotNull(oracle);
+ Assert.False(oracle!.ExactStepExported);
+ Assert.False(oracle.BRepTopologyEmitted);
+ Assert.Contains(oracle.Diagnostics, d => d.Contains("torus-generic-exactness-not-claimed", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void OracleTrimRouting_MultipleOpposites_Defers()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10,10,10), new CirUnionNode(new CirCylinderNode(2,20), new CirCylinderNode(2,20)));
+ var result = FacePatchCandidateGenerator.Generate(root);
+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRoutingDiagnostic == "oracle-trim: multiple-opposite-sources-deferred");
+ }
+
+ [Fact]
+ public void OracleTrimRouting_MissingOpposite_Diagnosed()
+ {
+ var loop = new RetainedRegionLoopDescriptor(RetainedRegionLoopKind.InnerTrim, TrimCurveFamily.Circle, TrimCapabilityClassification.ExactSupported, SurfacePatchFamily.Planar, SurfacePatchFamily.Spherical,
+ FacePatchOrientationRole.Forward, FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool, RetainedRegionLoopStatus.ExactReady, "missing", "diag", null, null, false, "oracle-trim: missing-opposite-source");
+ Assert.Equal("oracle-trim: missing-opposite-source", loop.OracleTrimRoutingDiagnostic);
+ }
+
+ [Fact]
+ public void MaterializationReadiness_TrimOracleLayer_DistinguishesStrongVsBroad()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));
+ var layer = report.LayerSummaries.Single(l => l.LayerName == "trim-oracle-evidence");
+ Assert.True(layer.Counts.ContainsKey("strong-trim-oracle"));
+ Assert.True(layer.Diagnostics.Any(d => d.StartsWith("oracle-trim:", StringComparison.Ordinal)));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
index ad79fb12..b61cda5c 100644
--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
@@ -87,8 +87,12 @@ internal sealed record RetainedRegionLoopDescriptor(
FacePatchOrientationRole OrientationHint,
FacePatchRetentionRole RetentionRole,
RetainedRegionLoopStatus Status,
+ string OppositeSurfaceProvenance,
string Diagnostic,
- RetainedCircularLoopGeometry? CircularGeometry);
+ RetainedCircularLoopGeometry? CircularGeometry,
+ TieredTrimCurveRepresentation? OracleTrimRepresentation,
+ bool OracleTrimStrongEvidence,
+ string OracleTrimRoutingDiagnostic);
internal readonly record struct RetainedCircularLoopGeometry(
Point3D Center,
@@ -171,7 +175,9 @@ internal static class FacePatchCandidateGenerator
}
diagnostics.Add("unsupported-node-shape: face patch dry-run currently supports subtract-tree retention classification only.");
- diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");
+ candidates = RetainedLoopTrimOracleIntegrator.Attach(root, candidates, diagnostics);
+
+ diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");
return new(false, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred, diagnostics, TopologyAssemblyImplemented: false);
}
@@ -236,6 +242,8 @@ internal static class FacePatchCandidateGenerator
candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, retentionRole, retentionStatus, retentionReason, oppositeFamilies, loopDescriptors, loopGroups, loopReadiness, loopDiagnostic, candidateDiagnostics));
}
+ candidates = RetainedLoopTrimOracleIntegrator.Attach(root, candidates, diagnostics);
+
diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");
diagnostics.Add("topology-assembly-not-implemented: retained-region loop scaffolding emits descriptor diagnostics only; no BRep loops/coedges/edges/vertices are created.");
@@ -368,8 +376,12 @@ internal static class FacePatchCandidateGenerator
isBase ? source.OrientationRole : FacePatchOrientationRole.Reversed,
retentionRole,
status,
+ other.Provenance,
$"{BuildPerLoopDiagnostic(source.Family, other.Family, curveFamily, status, trim.Reason)} | binder-opposite={other.Provenance} | {(bound ? "loop-geometry-bind-success" : "loop-geometry-bind-skip")}: {circularDiagnostic}",
- bound ? circular : null));
+ bound ? circular : null,
+ null,
+ false,
+ "oracle-trim: not-integrated"));
}
}
diff --git a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
index 81ff8162..db62bf64 100644
--- a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
+++ b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
@@ -65,6 +65,7 @@ internal static class MaterializationReadinessAnalyzer
{
SummarizeSource(source),
SummarizeCandidates(candidates),
+ SummarizeTrimOracle(candidates),
SummarizeTopology(topology),
SummarizePairing(pairing)
};
@@ -196,6 +197,32 @@ internal static class MaterializationReadinessAnalyzer
});
}
+
+ private static ReadinessLayerSummary SummarizeTrimOracle(FacePatchCandidateGenerationResult candidates)
+ {
+ var reps = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Select(l => l.OracleTrimRepresentation).Where(r => r is not null).ToArray();
+ var diagnostics = new List<string>();
+ diagnostics.Add(reps.Length == 0 ? "oracle-trim: no-tiered-trim-representations-attached" : $"oracle-trim: attached={reps.Length}");
+ diagnostics.AddRange(reps.SelectMany(r => r!.Diagnostics).Select(d => d.StartsWith("oracle-trim:", StringComparison.Ordinal) ? d : $"oracle-trim: {d}"));
+ diagnostics.AddRange(reps.Where(r => r!.Circle is not null).Select(_ => "oracle-trim: analytic-circle-candidate"));
+ diagnostics.AddRange(reps.Where(r => r!.NumericalContour is not null).Select(_ => "oracle-trim: numerical-contour-present"));
+ diagnostics.AddRange(reps.Where(r => r!.ExportCapability == TieredTrimExportCapability.ElementaryCurveCandidate).Select(_ => "oracle-trim: elementary-export-candidate-not-exported"));
+ diagnostics.AddRange(reps.Select(_ => "oracle-trim: b-rep-topology-not-emitted"));
+ diagnostics.AddRange(reps.Select(_ => "oracle-trim: exact-step-export-false"));
+
+ return new ReadinessLayerSummary("trim-oracle-evidence",
+ reps.Length == 0 ? EmissionReadiness.Deferred : EmissionReadiness.EvidenceReadyForEmission,
+ reps.Length == 0 ? [EmissionBlockingReason.TrimCapability] : [EmissionBlockingReason.None],
+ diagnostics.Distinct().ToArray(),
+ new Dictionary<string, int>
+ {
+ ["trim-oracle-representations"] = reps.Length,
+ ["strong-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => l.OracleTrimStrongEvidence),
+ ["broad-or-deferred-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => !l.OracleTrimStrongEvidence && l.OracleTrimRepresentation is not null),
+ ["analytic-circle"] = reps.Count(r => r!.Circle is not null),
+ ["numerical-contours"] = reps.Count(r => r!.NumericalContour is not null)
+ });
+ }
private static EmissionReadiness Reduce(IEnumerable<EmissionReadiness> values)
{
var arr = values.ToArray();
diff --git a/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs
new file mode 100644
index 00000000..3944de0f
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs
@@ -0,0 +1,80 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal static class RetainedLoopTrimOracleIntegrator
+{
+ internal static List<FacePatchCandidate> Attach(CirNode root, List<FacePatchCandidate> candidates, List<string> globalDiagnostics)
+ {
+ if (root is not CirSubtractNode subtract) return candidates;
+
+ var leftDescriptors = SourceSurfaceExtractor.Extract(subtract.Left).Descriptors;
+ var rightDescriptors = SourceSurfaceExtractor.Extract(subtract.Right).Descriptors;
+
+ var next = new List<FacePatchCandidate>(candidates.Count);
+ foreach (var candidate in candidates)
+ {
+ var sourceSide = candidate.CandidateRole == "base-surface-candidate" ? SubtractOperandSide.Left : SubtractOperandSide.Right;
+ var sourceSet = sourceSide == SubtractOperandSide.Left ? leftDescriptors : rightDescriptors;
+ var oppositeSet = sourceSide == SubtractOperandSide.Left ? rightDescriptors : leftDescriptors;
+ var source = sourceSet.FirstOrDefault(d => d.Provenance == candidate.SourceSurface.Provenance);
+ if (source is null)
+ {
+ next.Add(candidate with { Diagnostics = candidate.Diagnostics.Concat(["oracle-trim: source-surface-not-found-for-candidate"]).ToArray() });
+ continue;
+ }
+
+ var loops = new List<RetainedRegionLoopDescriptor>(candidate.RetainedRegionLoops.Count);
+ foreach (var loop in candidate.RetainedRegionLoops)
+ {
+ var matches = oppositeSet.Where(o => o.Provenance == loop.OppositeSurfaceProvenance && o.Family == loop.OppositeSurfaceFamily).ToArray();
+ if (matches.Length == 1)
+ {
+ var oracle = BuildLoopRepresentation(subtract, source, sourceSide);
+ loops.Add(loop with { OracleTrimRepresentation = oracle, OracleTrimStrongEvidence = true, OracleTrimRoutingDiagnostic = "oracle-trim: specific-opposite-selected" });
+ continue;
+ }
+
+ if (matches.Length > 1)
+ {
+ loops.Add(loop with { OracleTrimRepresentation = null, OracleTrimStrongEvidence = false, OracleTrimRoutingDiagnostic = "oracle-trim: multiple-opposite-sources-deferred" });
+ continue;
+ }
+
+ var familyMatches = oppositeSet.Where(o => o.Family == loop.OppositeSurfaceFamily).ToArray();
+ var routing = familyMatches.Length > 0 ? "oracle-trim: broad-opposite-field-only" : "oracle-trim: missing-opposite-source";
+ var oracleBroad = familyMatches.Length > 0 ? BuildLoopRepresentation(subtract, source, sourceSide) : null;
+ loops.Add(loop with { OracleTrimRepresentation = oracleBroad, OracleTrimStrongEvidence = false, OracleTrimRoutingDiagnostic = routing });
+ }
+
+ var diag = new List<string>(candidate.Diagnostics);
+ diag.AddRange(loops.Select(l => l.OracleTrimRoutingDiagnostic));
+ foreach (var l in loops.Where(l => l.OracleTrimRepresentation is not null))
+ {
+ var r = l.OracleTrimRepresentation!;
+ diag.Add(l.OracleTrimStrongEvidence ? "oracle-trim: strong-oracle-evidence-attached" : "oracle-trim: diagnostic-only-oracle-evidence-attached");
+ if (r.Circle is not null) diag.Add("oracle-trim: analytic-circle-candidate");
+ if (r.NumericalContour is not null) diag.Add("oracle-trim: numerical-contour-present");
+ diag.Add("oracle-trim: exact-step-export-false");
+ diag.Add("oracle-trim: b-rep-topology-not-emitted");
+ if (l.OppositeSurfaceFamily == SurfacePatchFamily.Toroidal) diag.Add("oracle-trim: torus-generic-exactness-not-claimed");
+ }
+
+ next.Add(candidate with { RetainedRegionLoops = loops, Diagnostics = diag.Distinct().ToArray() });
+ }
+
+ globalDiagnostics.Add("oracle-trim: deterministic-opposite-routing-applied");
+ return next;
+ }
+
+ private static TieredTrimCurveRepresentation BuildLoopRepresentation(CirSubtractNode root, SourceSurfaceDescriptor source, SubtractOperandSide sourceSide)
+ {
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, sourceSide);
+ var grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(65, 65));
+ var extraction = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+ var stitched = SurfaceTrimContourStitcher.Stitch(extraction);
+ var options = new RestrictedContourSnapOptions(0.06d, 0.02d, 8);
+ var selection = RestrictedContourSnapSelector.Select(stitched, RestrictedContourSnapAnalyzer.Analyze(stitched, options), options);
+ return TieredTrimRepresentationBuilder.Build(selection, stitched, field).Representation;
+ }
+}
diff --git a/docs/cir-t8-trim-oracle-retained-loop-integration.md b/docs/cir-t8-trim-oracle-retained-loop-integration.md
new file mode 100644
index 00000000..6839e1ae
--- /dev/null
+++ b/docs/cir-t8-trim-oracle-retained-loop-integration.md
@@ -0,0 +1,38 @@
+# CIR-T8: Tiered trim integration into retained-loop/materialization evidence
+
+## Purpose
+
+Integrate `TieredTrimCurveRepresentation` (CIR-T7) into retained-loop descriptors and readiness evidence without emitting BRep topology or STEP entities.
+
+## Integration shape
+
+- `RetainedRegionLoopDescriptor` now carries:
+ - `OppositeSurfaceProvenance`
+ - `OracleTrimRepresentation` (optional `TieredTrimCurveRepresentation`)
+- `RetainedLoopTrimOracleIntegrator` runs inside candidate generation for subtract roots and attaches restricted-field trim oracle evidence per retained loop.
+- `MaterializationReadinessAnalyzer` adds `trim-oracle-evidence` layer.
+
+## Behavior
+
+- Box face vs cylinder: analytic-circle candidate + numerical contour evidence attached; export candidate only; not exported.
+- Box face vs sphere: analytic-circle candidate + numerical contour evidence attached; export candidate only; not exported.
+- Box face vs torus: numerical/deferred/candidate-only route accepted; diagnostics explicitly preserve "torus generic exactness not claimed".
+
+## Exactness/export policy
+
+- `ExactStepExported` remains `false`.
+- `BRepTopologyEmitted` remains `false`.
+- No STEP curve entities are created.
+- No BRep edge/coedge/loop emission is added.
+
+## Non-goals
+
+- topology emission
+- STEP export behavior changes
+- BSpline fitting
+- torus exact/quartic recognition
+- boolean/materializer behavior expansion
+
+## Next (CIR-T9)
+
+Add deterministic loop-to-opposite provenance matching for multi-opposite fields so attached tiered trim evidence can be pair-specific when a source face sees multiple opposite operands.
diff --git a/docs/cir-t81-opposite-surface-routing.md b/docs/cir-t81-opposite-surface-routing.md
new file mode 100644
index 00000000..4e53afbf
--- /dev/null
+++ b/docs/cir-t81-opposite-surface-routing.md
@@ -0,0 +1,31 @@
+# CIR-T8.1 opposite-surface routing cleanup
+
+T8 attached oracle trim evidence but used broad opposite-operand fields for every loop.
+
+## Routing policy
+
+Per loop, opposite routing now uses descriptor provenance + family:
+- exactly one match: `oracle-trim: specific-opposite-selected` and strong evidence
+- multiple matches: `oracle-trim: multiple-opposite-sources-deferred`
+- no provenance match but family exists: `oracle-trim: broad-opposite-field-only` (diagnostic-only evidence)
+- no compatible opposite: `oracle-trim: missing-opposite-source`
+
+## Strong vs broad
+
+`RetainedRegionLoopDescriptor` now tracks:
+- `OracleTrimStrongEvidence`
+- `OracleTrimRoutingDiagnostic`
+
+Readiness trim-oracle layer reports strong vs broad/deferred counts.
+
+## Guardrails
+
+No BRep emission, STEP export, torus generic exactness, naming changes, or public CLI changes.
+
+## JudgmentEngine
+
+Not used. Multiple indistinguishable opposite sources are deferred, not scored.
+
+## T9
+
+Add per-loop restricted-field slicing by selected opposite descriptor for truly pair-specific contouring where opposite operands are composite.