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.csnew file mode 100644index 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.csindex 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 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 +376,12 @@ 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,+ false,+ "oracle-trim: not-integrated"));}}diff --git a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.csindex 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.csnew file mode 100644index 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.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.diff --git a/docs/cir-t81-opposite-surface-routing.md b/docs/cir-t81-opposite-surface-routing.mdnew file mode 100644index 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.