Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-F8.3 face patch dry-run candidate generator
Yuechen Lieac4c4294e8f
diff --git a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.csnew file mode 100644index 00000000..247be933--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs@@ -0,0 +1,80 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class FacePatchCandidateDryRunTests+{+ [Fact]+ public void FacePatchDryRun_BoxMinusCylinder_ReportsExactTrimReady()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));++ var result = FacePatchCandidateGenerator.Generate(root);++ Assert.True(result.IsSuccess);+ Assert.Contains(result.SourceSurfaces, d => d.Family == SurfacePatchFamily.Planar);+ Assert.Contains(result.SourceSurfaces, d => d.Family == SurfacePatchFamily.Cylindrical);+ Assert.Contains(result.TrimCapabilitySummaries, t =>+ (t.FamilyA == SurfacePatchFamily.Planar && t.FamilyB == SurfacePatchFamily.Cylindrical)+ || (t.FamilyA == SurfacePatchFamily.Cylindrical && t.FamilyB == SurfacePatchFamily.Planar));+ Assert.Contains(result.Candidates, c => c.Readiness == FacePatchCandidateReadiness.ExactReady);+ Assert.False(result.TopologyAssemblyImplemented);+ }++ [Fact]+ public void FacePatchDryRun_BoxMinusSphere_ReportsPlanarSphericalCircleExact()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3));++ var result = FacePatchCandidateGenerator.Generate(root);++ Assert.True(result.IsSuccess);+ Assert.Contains(result.SourceSurfaces, d => d.Family == SurfacePatchFamily.Spherical);+ Assert.Contains(result.TrimCapabilitySummaries, t =>+ ((t.FamilyA == SurfacePatchFamily.Planar && t.FamilyB == SurfacePatchFamily.Spherical)+ || (t.FamilyA == SurfacePatchFamily.Spherical && t.FamilyB == SurfacePatchFamily.Planar))+ && t.Classification == TrimCapabilityClassification.ExactSupported+ && t.CurveFamilies.Contains(TrimCurveFamily.Circle));+ Assert.DoesNotContain(result.Candidates, c => c.Readiness == FacePatchCandidateReadiness.Unsupported);+ }++ [Fact]+ public void FacePatchDryRun_BoxMinusTorus_ReportsDeferredTrim()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1));++ var result = FacePatchCandidateGenerator.Generate(root);++ Assert.True(result.IsSuccess);+ Assert.Contains(result.SourceSurfaces, d => d.Family == SurfacePatchFamily.Toroidal);+ Assert.Contains(result.TrimCapabilitySummaries, t =>+ ((t.FamilyA == SurfacePatchFamily.Planar && t.FamilyB == SurfacePatchFamily.Toroidal)+ || (t.FamilyA == SurfacePatchFamily.Toroidal && t.FamilyB == SurfacePatchFamily.Planar))+ && t.Classification == TrimCapabilityClassification.Deferred);+ Assert.Contains(result.Candidates, c => c.Readiness == FacePatchCandidateReadiness.TrimDeferred);+ Assert.Contains(result.Candidates.SelectMany(c => c.Diagnostics), d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void FacePatchDryRun_UsesSourceSurfaceExtractor()+ {+ var root = new CirBoxNode(3, 4, 5);+ var extracted = SourceSurfaceExtractor.Extract(root);++ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(root, new CirSphereNode(1)));++ Assert.Equal(extracted.Descriptors.Count, result.SourceSurfaces.Count(d => d.OwningCirNodeKind == nameof(CirBoxNode)));+ }++ [Fact]+ public void FacePatchDryRun_DoesNotClaimTopologyAssembly()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));++ var result = FacePatchCandidateGenerator.Generate(root);++ Assert.False(result.TopologyAssemblyImplemented);+ Assert.Contains(result.Diagnostics, d => d.Contains("topology-assembly-not-implemented", StringComparison.Ordinal));+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.csnew file mode 100644index 00000000..5791314e--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs@@ -0,0 +1,157 @@+using Aetheris.Kernel.Core.Cir;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum FacePatchCandidateReadiness+{+ ExactReady,+ RetentionDeferred,+ TrimDeferred,+ Unsupported+}++internal sealed record FacePatchCandidate(+ SourceSurfaceDescriptor SourceSurface,+ FacePatchDescriptor ProposedPatch,+ string CandidateRole,+ FacePatchCandidateReadiness Readiness,+ TrimCapabilityResult? TrimCapability,+ IReadOnlyList<string> Diagnostics);++internal sealed record FacePatchCandidateGenerationResult(+ bool IsSuccess,+ IReadOnlyList<FacePatchCandidate> Candidates,+ IReadOnlyList<SourceSurfaceDescriptor> SourceSurfaces,+ IReadOnlyList<TrimCapabilityResult> TrimCapabilitySummaries,+ IReadOnlyList<SourceSurfaceExtractionDiagnostic> ExtractionDiagnostics,+ IReadOnlyList<string> DeferredReasons,+ IReadOnlyList<string> Diagnostics,+ bool TopologyAssemblyImplemented);++internal static class FacePatchCandidateGenerator+{+ internal static FacePatchCandidateGenerationResult Generate(CirNode root, NativeGeometryReplayLog? replayLog = null)+ {+ var extraction = SourceSurfaceExtractor.Extract(root, replayLog);+ var candidates = new List<FacePatchCandidate>();+ var trimSummaries = new List<TrimCapabilityResult>();+ var deferred = new List<string>();+ var diagnostics = new List<string>();++ if (!extraction.IsSuccess)+ {+ diagnostics.Add("source-surface-extraction-unsupported: one or more CIR nodes cannot be inventoried into source surfaces.");+ diagnostics.AddRange(extraction.UnsupportedNodeReasons.Select(r => $"source-surface-extraction-unsupported: {r}"));+ }++ if (root is not CirSubtractNode subtract)+ {+ diagnostics.Add("unsupported-node-shape: face patch dry-run currently supports subtract-tree analysis only.");+ return new(false, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred, diagnostics, TopologyAssemblyImplemented: false);+ }++ var left = SourceSurfaceExtractor.Extract(subtract.Left, replayLog);+ var right = SourceSurfaceExtractor.Extract(subtract.Right, replayLog);++ trimSummaries.AddRange(ComputeUniqueTrimSummaries(left.Descriptors, right.Descriptors));++ foreach (var source in extraction.Descriptors)+ {+ var role = IsFromNode(source, subtract.Left) ? "base-surface-candidate" : "tool-surface-candidate";+ var relevantOther = role == "base-surface-candidate" ? right.Descriptors : left.Descriptors;+ var trim = EvaluateBestTrim(source, relevantOther);++ var readiness = EvaluateReadiness(trim);+ var candidateDiagnostics = new List<string>();+ if (trim is null)+ {+ readiness = FacePatchCandidateReadiness.Unsupported;+ candidateDiagnostics.Add("no-relevant-trim-capability: no opposite-side source surfaces available for trim matrix evaluation.");+ }+ else+ {+ if (trim.Classification == TrimCapabilityClassification.Deferred)+ {+ candidateDiagnostics.Add($"trim-capability-deferred: {trim.Reason}");+ deferred.Add($"{source.Provenance}: {trim.Reason}");+ }+ else if (trim.Classification == TrimCapabilityClassification.Unsupported)+ {+ candidateDiagnostics.Add($"trim-capability-unsupported: {trim.Reason}");+ }+ else if (trim.Classification == TrimCapabilityClassification.SpecialCaseOnly)+ {+ candidateDiagnostics.Add($"trim-capability-special-case: {trim.Reason}");+ }++ if (readiness == FacePatchCandidateReadiness.ExactReady)+ {+ candidateDiagnostics.Add("retention-classification-deferred: exact trim capability found, but retained/discarded patch boundaries are not classified in CIR-F8.3.");+ }+ }++ var patch = new FacePatchDescriptor(source, [], [], source.OrientationRole, role, []);+ candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, candidateDiagnostics));+ }++ diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");+ diagnostics.Add("retention-classification-deferred: boolean retention mapping is intentionally deferred in CIR-F8.3.");++ var success = extraction.IsSuccess && candidates.Count > 0;+ return new(success, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred.Distinct().ToArray(), diagnostics, TopologyAssemblyImplemented: false);+ }++ private static IReadOnlyList<TrimCapabilityResult> ComputeUniqueTrimSummaries(IReadOnlyList<SourceSurfaceDescriptor> left, IReadOnlyList<SourceSurfaceDescriptor> right)+ {+ var summaries = new Dictionary<(SurfacePatchFamily, SurfacePatchFamily), TrimCapabilityResult>();+ foreach (var l in left)+ foreach (var r in right)+ {+ var result = TrimCapabilityMatrix.Evaluate(l.Family, r.Family);+ var key = Normalize(l.Family, r.Family);+ summaries.TryAdd(key, result);+ }++ return summaries.Values.ToArray();+ }++ private static TrimCapabilityResult? EvaluateBestTrim(SourceSurfaceDescriptor source, IReadOnlyList<SourceSurfaceDescriptor> others)+ {+ TrimCapabilityResult? best = null;+ foreach (var other in others)+ {+ var result = TrimCapabilityMatrix.Evaluate(source.Family, other.Family);+ if (best is null || Score(result.Classification) > Score(best.Classification))+ {+ best = result;+ }+ }++ return best;+ }++ private static FacePatchCandidateReadiness EvaluateReadiness(TrimCapabilityResult? trim)+ => trim?.Classification switch+ {+ TrimCapabilityClassification.ExactSupported => FacePatchCandidateReadiness.ExactReady,+ TrimCapabilityClassification.SpecialCaseOnly => FacePatchCandidateReadiness.ExactReady,+ TrimCapabilityClassification.Deferred => FacePatchCandidateReadiness.TrimDeferred,+ TrimCapabilityClassification.Unsupported => FacePatchCandidateReadiness.Unsupported,+ _ => FacePatchCandidateReadiness.Unsupported+ };++ private static bool IsFromNode(SourceSurfaceDescriptor source, CirNode node)+ => source.OwningCirNodeKind == node.GetType().Name;++ private static int Score(TrimCapabilityClassification c)+ => c switch+ {+ TrimCapabilityClassification.ExactSupported => 4,+ TrimCapabilityClassification.SpecialCaseOnly => 3,+ TrimCapabilityClassification.Deferred => 2,+ _ => 1+ };++ private static (SurfacePatchFamily, SurfacePatchFamily) Normalize(SurfacePatchFamily a, SurfacePatchFamily b)+ => a <= b ? (a, b) : (b, a);+}diff --git a/docs/cir-f83-face-patch-dry-run.md b/docs/cir-f83-face-patch-dry-run.mdnew file mode 100644index 00000000..529cd6b7--- /dev/null+++ b/docs/cir-f83-face-patch-dry-run.md@@ -0,0 +1,67 @@+# CIR-F8.3: Face patch dry-run candidates from source surfaces + trim capabilities++## Purpose++CIR-F8.3 introduces a **diagnostic-only dry-run layer** that bridges:++- `SourceSurfaceExtractor` inventory, and+- `TrimCapabilityMatrix` policy facts,++into early `FacePatchDescriptor` candidate generation.++This milestone intentionally **does not emit BRep topology**.++## New dry-run artifact++`FacePatchCandidateGenerator.Generate(CirNode root, NativeGeometryReplayLog? replayLog = null)` returns a `FacePatchCandidateGenerationResult` containing:++- extracted source surfaces,+- dry-run face patch candidates,+- trim capability summaries derived from source-family pairings,+- readiness classification and deferred reasons,+- explicit topology-assembly-not-implemented diagnostics.++## Candidate readiness states++- `ExactReady`: trim capability is `ExactSupported` or `SpecialCaseOnly`; retention classification remains deferred.+- `TrimDeferred`: trim capability is recognized but deferred by matrix policy.+- `Unsupported`: no matrix capability / unsupported source pair for current dry-run.++`RetentionDeferred` is represented by explicit diagnostics while readiness remains trim-focused.++## What is exact-ready vs deferred++### subtract(box, cylinder)++- Source inventory includes planar and cylindrical surfaces.+- Planar/cylindrical capabilities are surfaced as `SpecialCaseOnly` from matrix policy.+- Candidate readiness can be `ExactReady` with retention still deferred.++### subtract(box, sphere)++- Source inventory includes spherical surfaces.+- Planar/spherical capability is `ExactSupported` with circle trims.+- Candidates surface exact trim readiness with retention deferred.++### subtract(box, torus)++- Source inventory includes toroidal surfaces.+- Planar/toroidal and toroidal pairings are surfaced as `Deferred`.+- Candidates are flagged as `TrimDeferred` with matrix reason (quartic/algebraic intersections).++## Why this is not BRep emission++The generator creates descriptor-level candidates only:++- no face/edge/coedge/vertex creation,+- no topology assembly,+- no STEP export behavior changes,+- no pair-specific subtract materializer expansion.++## SEM-A0 guardrails++No topology naming generation is introduced. Provenance remains descriptor-level.++## Next milestone (CIR-F8.4)++Add bounded retention classification for subtract trees (base/tool/trimmed-retained candidate subsets) while still avoiding full topology assembly until classification and boundary contracts are explicit.