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.csindex 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.csindex 5791314e..caa1b4f6 100644--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs@@ -10,12 +10,34 @@ internal enum FacePatchCandidateReadinessUnsupported}+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 FacePatchCandidateGeneratorif (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 FacePatchCandidateGeneratorforeach (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 FacePatchCandidateGeneratorcandidateDiagnostics.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.mdnew file mode 100644index 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.