Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Integrate tiered trim oracle evidence into retained loop/readiness dry-run

Yuechen Li95485cf46bbd
diff --git a/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs
new file mode 100644
index 00000000..ce22591a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs
@@ -0,0 +1,45 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class RetainedLoopTrimOracleIntegrationTests
+{
+ [Fact]
+ public void RetainedLoopOracleTrim_Cylinder_AttachesAnalyticCircleEvidence()
+ {
+ 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);
+ Assert.Equal(TieredTrimRepresentationKind.AnalyticCircle, loop.OracleTrimRepresentation!.Kind);
+ Assert.NotNull(loop.OracleTrimRepresentation.NumericalContour);
+ Assert.False(loop.OracleTrimRepresentation.ExactStepExported);
+ Assert.False(loop.OracleTrimRepresentation.BRepTopologyEmitted);
+ }
+
+ [Fact]
+ public void RetainedLoopOracleTrim_Sphere_AttachesAnalyticCircleEvidence()
+ {
+ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirSphereNode(6)));
+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRepresentation is not null);
+ }
+
+ [Fact]
+ public void RetainedLoopOracleTrim_Torus_RemainsNumericalOrDeferredWithoutGenericExactness()
+ {
+ 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.True(oracle!.Kind is TieredTrimRepresentationKind.NumericalOnly or TieredTrimRepresentationKind.Deferred or TieredTrimRepresentationKind.AnalyticCircle or TieredTrimRepresentationKind.Unsupported);
+ 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 MaterializationReadiness_IncludesTrimOracleDiagnostics()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));
+ Assert.Contains(report.LayerSummaries, l => l.LayerName == "trim-oracle-evidence");
+ Assert.Contains(report.Diagnostics.Concat(report.LayerSummaries.SelectMany(l => l.Diagnostics)), d => d.Contains("trim-oracle:", StringComparison.Ordinal));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
index ad79fb12..e5c80b9a 100644
--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
@@ -87,8 +87,10 @@ internal sealed record RetainedRegionLoopDescriptor(
FacePatchOrientationRole OrientationHint,
FacePatchRetentionRole RetentionRole,
RetainedRegionLoopStatus Status,
+ string OppositeSurfaceProvenance,
string Diagnostic,
- RetainedCircularLoopGeometry? CircularGeometry);
+ RetainedCircularLoopGeometry? CircularGeometry,
+ TieredTrimCurveRepresentation? OracleTrimRepresentation);
internal readonly record struct RetainedCircularLoopGeometry(
Point3D Center,
@@ -171,7 +173,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 +240,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 +374,10 @@ 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));
}
}
diff --git a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
index 81ff8162..b2cc4036 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,30 @@ 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 ? "trim-oracle: no-tiered-trim-representations-attached" : $"trim-oracle: attached={reps.Length}");
+ diagnostics.AddRange(reps.SelectMany(r => r!.Diagnostics).Select(d => $"trim-oracle: {d}"));
+ diagnostics.AddRange(reps.Where(r => r!.Circle is not null).Select(_ => "trim-oracle: analytic-circle-candidate"));
+ diagnostics.AddRange(reps.Where(r => r!.NumericalContour is not null).Select(_ => "trim-oracle: numerical-contour-present"));
+ diagnostics.AddRange(reps.Where(r => r!.ExportCapability == TieredTrimExportCapability.ElementaryCurveCandidate).Select(_ => "trim-oracle: elementary-export-candidate-not-exported"));
+ diagnostics.AddRange(reps.Select(_ => "trim-oracle: b-rep-topology-not-emitted"));
+ diagnostics.AddRange(reps.Select(_ => "trim-oracle: 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,
+ ["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..ede673ea
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs
@@ -0,0 +1,62 @@
+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 next = new List<FacePatchCandidate>(candidates.Count);
+ foreach (var candidate in candidates)
+ {
+ var sourceSide = candidate.CandidateRole == "base-surface-candidate" ? SubtractOperandSide.Left : SubtractOperandSide.Right;
+ var sourceNode = sourceSide == SubtractOperandSide.Left ? subtract.Left : subtract.Right;
+ var source = SourceSurfaceExtractor.Extract(sourceNode).Descriptors.FirstOrDefault(d => d.Provenance == candidate.SourceSurface.Provenance);
+ if (source is null)
+ {
+ next.Add(candidate with { Diagnostics = candidate.Diagnostics.Concat(["trim-oracle: source-surface-not-found-for-candidate"]).ToArray() });
+ continue;
+ }
+
+ var loops = new List<RetainedRegionLoopDescriptor>(candidate.RetainedRegionLoops.Count);
+ foreach (var loop in candidate.RetainedRegionLoops)
+ {
+ var oracle = BuildLoopRepresentation(subtract, source, sourceSide, loop.OppositeSurfaceProvenance, globalDiagnostics);
+ loops.Add(loop with { OracleTrimRepresentation = oracle });
+ }
+
+ var diag = new List<string>(candidate.Diagnostics);
+ foreach (var l in loops.Where(l => l.OracleTrimRepresentation is not null))
+ {
+ var r = l.OracleTrimRepresentation!;
+ diag.Add($"trim-oracle: kind={r.Kind}");
+ diag.Add($"trim-oracle: export-capability={r.ExportCapability}");
+ if (r.Circle is not null) diag.Add("trim-oracle: analytic-circle-candidate");
+ if (r.NumericalContour is not null) diag.Add("trim-oracle: numerical-contour-present");
+ diag.Add("trim-oracle: exact-step-export-false");
+ diag.Add("trim-oracle: b-rep-topology-not-emitted");
+ if (l.OppositeSurfaceFamily == SurfacePatchFamily.Toroidal) diag.Add("trim-oracle: torus-generic-exactness-not-claimed");
+ }
+
+ next.Add(candidate with { RetainedRegionLoops = loops, Diagnostics = diag.Distinct().ToArray() });
+ }
+
+ return next;
+ }
+
+ private static TieredTrimCurveRepresentation? BuildLoopRepresentation(CirSubtractNode root, SourceSurfaceDescriptor source, SubtractOperandSide sourceSide, string oppositeProvenance, List<string> globalDiagnostics)
+ {
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, sourceSide);
+ globalDiagnostics.Add($"trim-oracle: attached-for-opposite-provenance={oppositeProvenance}");
+
+ 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);
+ var rep = TieredTrimRepresentationBuilder.Build(selection, stitched, field).Representation;
+ return rep;
+ }
+}
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.