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.csnew file mode 100644index 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.csindex 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 FacePatchCandidateGeneratorcandidates.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 FacePatchCandidateGeneratorisBase ? 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.csindex 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.