Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.4 subtract retention classification scaffold

Yuechen Li044dadc51cd4
diff --git a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
index 247be933..43cde92b 100644
--- a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
@@ -6,56 +6,67 @@ namespace Aetheris.Kernel.Firmament.Tests;
public sealed class FacePatchCandidateDryRunTests
{
[Fact]
- public void FacePatchDryRun_BoxMinusCylinder_ReportsExactTrimReady()
+ public void Retention_BoxMinusCylinder_ClassifiesBaseAndToolRoles()
{
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.Contains(result.Candidates, c => c.CandidateRole == "base-surface-candidate" && c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool);
+ Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
+ Assert.Contains(result.Candidates, c => c.RetentionStatus == FacePatchRetentionStatus.KnownTrimmedSurface);
Assert.False(result.TopologyAssemblyImplemented);
}
[Fact]
- public void FacePatchDryRun_BoxMinusSphere_ReportsPlanarSphericalCircleExact()
+ public void Retention_BoxMinusSphere_ReportsSphericalToolRetainedInsideBase()
{
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.Candidates, c =>
+ c.SourceSurface.Family == SurfacePatchFamily.Spherical
+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase
+ && c.RetentionStatus == FacePatchRetentionStatus.KnownTrimmedSurface);
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);
+ Assert.DoesNotContain(result.Candidates, c => c.Diagnostics.Any(d => d.Contains("generic unsupported", StringComparison.OrdinalIgnoreCase)));
}
[Fact]
- public void FacePatchDryRun_BoxMinusTorus_ReportsDeferredTrim()
+ public void Retention_BoxMinusTorus_ReportsKnownRoleButTrimDeferred()
{
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, c =>
+ c.SourceSurface.Family == SurfacePatchFamily.Toroidal
+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase
+ && c.Readiness == FacePatchCandidateReadiness.TrimDeferred
+ && c.RetentionStatus == FacePatchRetentionStatus.Deferred);
Assert.Contains(result.Candidates.SelectMany(c => c.Diagnostics), d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase));
}
+ [Fact]
+ public void Retention_NonSubtract_IsDeferredOrNotApplicable()
+ {
+ var root = new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2));
+
+ var result = FacePatchCandidateGenerator.Generate(root);
+
+ Assert.False(result.IsSuccess);
+ Assert.All(result.Candidates, c => Assert.Equal(FacePatchRetentionRole.NotApplicable, c.RetentionRole));
+ Assert.All(result.Candidates, c => Assert.Equal(FacePatchRetentionStatus.Deferred, c.RetentionStatus));
+ }
+
[Fact]
public void FacePatchDryRun_UsesSourceSurfaceExtractor()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
index 5791314e..caa1b4f6 100644
--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
@@ -10,12 +10,34 @@ internal enum FacePatchCandidateReadiness
Unsupported
}
+internal enum FacePatchRetentionRole
+{
+ NotApplicable,
+ BaseBoundaryRetainedOutsideTool,
+ ToolBoundaryRetainedInsideBase,
+ DiscardedInterior,
+ RetentionDeferred,
+ Unsupported
+}
+
+internal enum FacePatchRetentionStatus
+{
+ KnownWholeSurface,
+ KnownTrimmedSurface,
+ Deferred,
+ Unsupported
+}
+
internal sealed record FacePatchCandidate(
SourceSurfaceDescriptor SourceSurface,
FacePatchDescriptor ProposedPatch,
string CandidateRole,
FacePatchCandidateReadiness Readiness,
TrimCapabilityResult? TrimCapability,
+ FacePatchRetentionRole RetentionRole,
+ FacePatchRetentionStatus RetentionStatus,
+ string RetentionReason,
+ IReadOnlyList<SurfacePatchFamily> OppositeFamilies,
IReadOnlyList<string> Diagnostics);
internal sealed record FacePatchCandidateGenerationResult(
@@ -46,7 +68,24 @@ internal static class FacePatchCandidateGenerator
if (root is not CirSubtractNode subtract)
{
- diagnostics.Add("unsupported-node-shape: face patch dry-run currently supports subtract-tree analysis only.");
+ foreach (var source in extraction.Descriptors)
+ {
+ var patch = new FacePatchDescriptor(source, [], [], source.OrientationRole, "non-subtract-candidate", []);
+ candidates.Add(new FacePatchCandidate(
+ source,
+ patch,
+ "non-subtract-candidate",
+ FacePatchCandidateReadiness.RetentionDeferred,
+ null,
+ FacePatchRetentionRole.NotApplicable,
+ FacePatchRetentionStatus.Deferred,
+ "retention-not-applicable: CIR-F8.4 retention classification applies to subtract roots only.",
+ [],
+ ["retention-not-applicable: non-subtract root leaves candidate retention unclassified."]));
+ }
+
+ 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.");
return new(false, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred, diagnostics, TopologyAssemblyImplemented: false);
}
@@ -57,11 +96,14 @@ internal static class FacePatchCandidateGenerator
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 isBase = IsFromNode(source, subtract.Left);
+ var role = isBase ? "base-surface-candidate" : "tool-surface-candidate";
+ var relevantOther = isBase ? right.Descriptors : left.Descriptors;
+ var oppositeFamilies = relevantOther.Select(d => d.Family).Distinct().ToArray();
var trim = EvaluateBestTrim(source, relevantOther);
var readiness = EvaluateReadiness(trim);
+ var (retentionRole, retentionStatus, retentionReason) = EvaluateRetention(isBase, trim, relevantOther.Count);
var candidateDiagnostics = new List<string>();
if (trim is null)
{
@@ -84,23 +126,57 @@ internal static class FacePatchCandidateGenerator
candidateDiagnostics.Add($"trim-capability-special-case: {trim.Reason}");
}
- if (readiness == FacePatchCandidateReadiness.ExactReady)
+ if (retentionStatus == FacePatchRetentionStatus.KnownTrimmedSurface)
{
- candidateDiagnostics.Add("retention-classification-deferred: exact trim capability found, but retained/discarded patch boundaries are not classified in CIR-F8.3.");
+ candidateDiagnostics.Add("retention-region-deferred: retention role is known and trim capability is available, but retained-loop assembly is deferred.");
}
}
- var patch = new FacePatchDescriptor(source, [], [], source.OrientationRole, role, []);
- candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, candidateDiagnostics));
+ candidateDiagnostics.Add($"retention-role: {retentionRole}");
+ candidateDiagnostics.Add($"retention-status: {retentionStatus}");
+ candidateDiagnostics.Add(retentionReason);
+
+ var orientation = isBase ? source.OrientationRole : FacePatchOrientationRole.Reversed;
+ var patchRole = isBase ? "base-boundary-retained-outside-tool" : "tool-boundary-retained-inside-base";
+ var patch = new FacePatchDescriptor(source, [], [], orientation, patchRole, []);
+ candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, retentionRole, retentionStatus, retentionReason, oppositeFamilies, 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.");
+ diagnostics.Add("retention-region-deferred: subtract retention roles are classified, but retained trim loops and topology assembly are deferred in CIR-F8.4.");
var success = extraction.IsSuccess && candidates.Count > 0;
return new(success, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred.Distinct().ToArray(), diagnostics, TopologyAssemblyImplemented: false);
}
+ private static (FacePatchRetentionRole Role, FacePatchRetentionStatus Status, string Reason) EvaluateRetention(bool isBaseSide, TrimCapabilityResult? trim, int oppositeCount)
+ {
+ if (oppositeCount == 0)
+ {
+ return (FacePatchRetentionRole.Unsupported, FacePatchRetentionStatus.Unsupported, "retention-unsupported: subtract side has no opposite source surfaces to classify against.");
+ }
+
+ var role = isBaseSide
+ ? FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool
+ : FacePatchRetentionRole.ToolBoundaryRetainedInsideBase;
+
+ if (trim is null)
+ {
+ return (role, FacePatchRetentionStatus.Deferred, "retention-deferred: subtract retention rule is known, but trim capability against opposite surfaces is unavailable.");
+ }
+
+ return trim.Classification switch
+ {
+ TrimCapabilityClassification.ExactSupported or TrimCapabilityClassification.SpecialCaseOnly
+ => (role, FacePatchRetentionStatus.KnownTrimmedSurface, "retention-known-trimmed: subtract retention role is known and pair trim capability is available; retained region loops are not assembled yet."),
+ TrimCapabilityClassification.Deferred
+ => (role, FacePatchRetentionStatus.Deferred, $"retention-trim-deferred: retention role is known but trim policy is deferred ({trim.Reason})"),
+ TrimCapabilityClassification.Unsupported
+ => (FacePatchRetentionRole.Unsupported, FacePatchRetentionStatus.Unsupported, $"retention-unsupported: subtract retention role cannot be applied due to unsupported trim pairing ({trim.Reason})"),
+ _ => (FacePatchRetentionRole.RetentionDeferred, FacePatchRetentionStatus.Deferred, "retention-deferred: subtract retention classification unresolved.")
+ };
+ }
+
private static IReadOnlyList<TrimCapabilityResult> ComputeUniqueTrimSummaries(IReadOnlyList<SourceSurfaceDescriptor> left, IReadOnlyList<SourceSurfaceDescriptor> right)
{
var summaries = new Dictionary<(SurfacePatchFamily, SurfacePatchFamily), TrimCapabilityResult>();
diff --git a/docs/cir-f84-subtract-retention-classification.md b/docs/cir-f84-subtract-retention-classification.md
new file mode 100644
index 00000000..82227f30
--- /dev/null
+++ b/docs/cir-f84-subtract-retention-classification.md
@@ -0,0 +1,81 @@
+# CIR-F8.4: bounded subtract retention classification for face patch dry-run candidates
+
+## Purpose
+
+CIR-F8.4 adds bounded **retention classification** on top of CIR-F8.3 dry-run candidates for subtract trees.
+
+For `A - B`, candidate classification now models the generic subtract-boundary rule:
+
+1. portions of `A` boundary retained where `B` is outside,
+2. portions of `B` boundary retained where `B` lies inside `A` (tool-cavity side, reversed orientation).
+
+This milestone remains descriptor/diagnostic-only. It does not emit BRep topology.
+
+## Retention model
+
+Each dry-run `FacePatchCandidate` now includes:
+
+- `RetentionRole`
+ - `BaseBoundaryRetainedOutsideTool`
+ - `ToolBoundaryRetainedInsideBase`
+ - `NotApplicable` / `Unsupported` / deferred variants
+- `RetentionStatus`
+ - `KnownTrimmedSurface`
+ - `KnownWholeSurface` (reserved for future conservative proofs)
+ - `Deferred`
+ - `Unsupported`
+- `RetentionReason` string
+- `OppositeFamilies` snapshot (opposite-side source surface families used for trim-capability context)
+
+`FacePatchCandidateReadiness` remains trim-capability readiness (`ExactReady`, `TrimDeferred`, `Unsupported`) and is not replaced by retention semantics.
+
+## Subtract-only behavior
+
+Retention classification applies only to `CirSubtractNode` roots in CIR-F8.4.
+
+- subtract root: base/tool candidates receive explicit subtract retention roles.
+- non-subtract root: candidates are marked `NotApplicable` + deferred retention diagnostic.
+
+## Example outcomes
+
+### subtract(box, cylinder)
+
+- box planar source candidates -> `BaseBoundaryRetainedOutsideTool`
+- tool cylindrical source candidate -> `ToolBoundaryRetainedInsideBase` with reversed patch orientation role
+- planar/cylindrical trim capability remains `SpecialCaseOnly` (exact-ready scaffold), with retained-loop assembly deferred
+
+### subtract(box, sphere)
+
+- spherical tool source candidate -> `ToolBoundaryRetainedInsideBase`
+- planar/spherical trim capability -> `ExactSupported` with circle family
+- diagnostics indicate retention region loops/topology not assembled yet
+
+### subtract(box, torus)
+
+- toroidal tool source candidate -> `ToolBoundaryRetainedInsideBase`
+- planar/toroidal remains deferred
+- readiness -> `TrimDeferred`
+- retention status -> `Deferred` with explicit matrix reason (quartic/algebraic)
+
+## Diagnostics added
+
+CIR-F8.4 distinguishes:
+
+- role known + trim capability available + retained-loop assembly deferred,
+- role known + trim policy deferred,
+- subtract retention not applicable (non-subtract roots),
+- topology assembly not implemented.
+
+This avoids overloading everything into generic unsupported.
+
+## Still deferred (intentional)
+
+- trim loop computation and boundary graphing
+- BRep face/edge/coedge/vertex emission
+- topology assembly
+- pair-specific subtract materializers
+- generated topology naming (SEM-A0 preserved)
+
+## Recommended next step (CIR-F8.5)
+
+Implement bounded retained-region loop scaffolding from trim-capability-ready pairs (starting planar/spherical and constrained planar/cylindrical), while still deferring full BRep emission.