Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.