Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-F8.5 retained-region loop scaffolding
Yuechen Li06c81eb1eae7
diff --git a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.csindex 43cde92b..4daeb7f7 100644--- a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs@@ -6,7 +6,7 @@ namespace Aetheris.Kernel.Firmament.Tests;public sealed class FacePatchCandidateDryRunTests{[Fact]- public void Retention_BoxMinusCylinder_ClassifiesBaseAndToolRoles()+ public void LoopScaffold_BoxMinusCylinder_ProducesTrimLoopDescriptors(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));@@ -16,11 +16,15 @@ public sealed class FacePatchCandidateDryRunTestsAssert.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.Contains(result.Candidates, c => c.CandidateRole == "base-surface-candidate" && c.RetainedRegionLoops.Any(l => l.SourceSurfaceFamily == SurfacePatchFamily.Planar));+ Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetainedRegionLoops.Any(l => l.OppositeSurfaceFamily == SurfacePatchFamily.Planar));+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.TrimCurveFamily is TrimCurveFamily.Line or TrimCurveFamily.Circle or TrimCurveFamily.Ellipse);+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.Status is RetainedRegionLoopStatus.ExactReady or RetainedRegionLoopStatus.SpecialCaseReady);Assert.False(result.TopologyAssemblyImplemented);}[Fact]- public void Retention_BoxMinusSphere_ReportsSphericalToolRetainedInsideBase()+ public void LoopScaffold_BoxMinusSphere_ProducesCircularTrimLoopDescriptors(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3));@@ -36,11 +40,12 @@ public sealed class FacePatchCandidateDryRunTests|| (t.FamilyA == SurfacePatchFamily.Spherical && t.FamilyB == SurfacePatchFamily.Planar))&& t.Classification == TrimCapabilityClassification.ExactSupported&& t.CurveFamilies.Contains(TrimCurveFamily.Circle));+ Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Spherical && c.RetainedRegionLoops.Any(l => l.TrimCurveFamily == TrimCurveFamily.Circle && l.Status == RetainedRegionLoopStatus.ExactReady));Assert.DoesNotContain(result.Candidates, c => c.Diagnostics.Any(d => d.Contains("generic unsupported", StringComparison.OrdinalIgnoreCase)));}[Fact]- public void Retention_BoxMinusTorus_ReportsKnownRoleButTrimDeferred()+ public void LoopScaffold_BoxMinusTorus_ProducesDeferredLoopDiagnostics(){var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1));@@ -53,10 +58,13 @@ public sealed class FacePatchCandidateDryRunTests&& c.Readiness == FacePatchCandidateReadiness.TrimDeferred&& c.RetentionStatus == FacePatchRetentionStatus.Deferred);Assert.Contains(result.Candidates.SelectMany(c => c.Diagnostics), d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Candidates, c =>+ c.SourceSurface.Family == SurfacePatchFamily.Toroidal+ && c.RetainedRegionLoops.Any(l => l.Status == RetainedRegionLoopStatus.Deferred));}[Fact]- public void Retention_NonSubtract_IsDeferredOrNotApplicable()+ public void LoopScaffold_NonSubtract_DoesNotInventLoops(){var root = new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2));@@ -65,6 +73,7 @@ public sealed class FacePatchCandidateDryRunTestsAssert.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));+ Assert.All(result.Candidates, c => Assert.Empty(c.RetainedRegionLoops));}[Fact]diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.csindex caa1b4f6..645a2566 100644--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs@@ -28,6 +28,36 @@ internal enum FacePatchRetentionStatusUnsupported}+internal enum RetainedRegionLoopKind+{+ OuterBoundary,+ InnerTrim,+ MouthTrim,+ CapTrim,+ SeamTrim,+ Deferred,+ Unsupported+}++internal enum RetainedRegionLoopStatus+{+ ExactReady,+ SpecialCaseReady,+ Deferred,+ Unsupported+}++internal sealed record RetainedRegionLoopDescriptor(+ RetainedRegionLoopKind LoopKind,+ TrimCurveFamily TrimCurveFamily,+ TrimCapabilityClassification TrimCapability,+ SurfacePatchFamily SourceSurfaceFamily,+ SurfacePatchFamily OppositeSurfaceFamily,+ FacePatchOrientationRole OrientationHint,+ FacePatchRetentionRole RetentionRole,+ RetainedRegionLoopStatus Status,+ string Diagnostic);+internal sealed record FacePatchCandidate(SourceSurfaceDescriptor SourceSurface,FacePatchDescriptor ProposedPatch,@@ -38,6 +68,9 @@ internal sealed record FacePatchCandidate(FacePatchRetentionStatus RetentionStatus,string RetentionReason,IReadOnlyList<SurfacePatchFamily> OppositeFamilies,+ IReadOnlyList<RetainedRegionLoopDescriptor> RetainedRegionLoops,+ RetainedRegionLoopStatus LoopReadiness,+ string LoopDiagnostic,IReadOnlyList<string> Diagnostics);internal sealed record FacePatchCandidateGenerationResult(@@ -81,6 +114,9 @@ internal static class FacePatchCandidateGeneratorFacePatchRetentionStatus.Deferred,"retention-not-applicable: CIR-F8.4 retention classification applies to subtract roots only.",[],+ [],+ RetainedRegionLoopStatus.Deferred,+ "loop-retention-not-applicable: retained-region loop scaffolding applies to subtract roots with classified retention only.",["retention-not-applicable: non-subtract root leaves candidate retention unclassified."]));}@@ -104,6 +140,9 @@ internal static class FacePatchCandidateGeneratorvar readiness = EvaluateReadiness(trim);var (retentionRole, retentionStatus, retentionReason) = EvaluateRetention(isBase, trim, relevantOther.Count);+ var loopDescriptors = BuildRetainedRegionLoops(source, relevantOther, retentionRole, retentionStatus, isBase);+ var loopReadiness = EvaluateLoopReadiness(loopDescriptors);+ var loopDiagnostic = BuildLoopDiagnostic(loopDescriptors, retentionStatus);var candidateDiagnostics = new List<string>();if (trim is null){@@ -135,15 +174,18 @@ internal static class FacePatchCandidateGeneratorcandidateDiagnostics.Add($"retention-role: {retentionRole}");candidateDiagnostics.Add($"retention-status: {retentionStatus}");candidateDiagnostics.Add(retentionReason);+ candidateDiagnostics.Add($"loop-readiness: {loopReadiness}");+ candidateDiagnostics.Add(loopDiagnostic);+ candidateDiagnostics.AddRange(loopDescriptors.Select(l => l.Diagnostic));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));+ candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, retentionRole, retentionStatus, retentionReason, oppositeFamilies, loopDescriptors, loopReadiness, loopDiagnostic, candidateDiagnostics));}diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");- diagnostics.Add("retention-region-deferred: subtract retention roles are classified, but retained trim loops and topology assembly are deferred in CIR-F8.4.");+ diagnostics.Add("topology-assembly-not-implemented: retained-region loop scaffolding emits descriptor diagnostics only; no BRep loops/coedges/edges/vertices are created.");var success = extraction.IsSuccess && candidates.Count > 0;return new(success, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred.Distinct().ToArray(), diagnostics, TopologyAssemblyImplemented: false);@@ -230,4 +272,103 @@ internal static class FacePatchCandidateGeneratorprivate static (SurfacePatchFamily, SurfacePatchFamily) Normalize(SurfacePatchFamily a, SurfacePatchFamily b)=> a <= b ? (a, b) : (b, a);++ private static IReadOnlyList<RetainedRegionLoopDescriptor> BuildRetainedRegionLoops(+ SourceSurfaceDescriptor source,+ IReadOnlyList<SourceSurfaceDescriptor> opposite,+ FacePatchRetentionRole retentionRole,+ FacePatchRetentionStatus retentionStatus,+ bool isBase)+ {+ if (retentionRole is FacePatchRetentionRole.NotApplicable or FacePatchRetentionRole.RetentionDeferred)+ {+ return [];+ }++ if (retentionStatus != FacePatchRetentionStatus.KnownTrimmedSurface && retentionStatus != FacePatchRetentionStatus.Deferred)+ {+ return [];+ }++ var loops = new List<RetainedRegionLoopDescriptor>();+ foreach (var other in opposite)+ {+ var trim = TrimCapabilityMatrix.Evaluate(source.Family, other.Family);+ var loopKind = DetermineLoopKind(source.Family, isBase, trim.Classification);+ var status = trim.Classification switch+ {+ TrimCapabilityClassification.ExactSupported => RetainedRegionLoopStatus.ExactReady,+ TrimCapabilityClassification.SpecialCaseOnly => RetainedRegionLoopStatus.SpecialCaseReady,+ TrimCapabilityClassification.Deferred => RetainedRegionLoopStatus.Deferred,+ _ => RetainedRegionLoopStatus.Unsupported+ };++ var families = trim.CurveFamilies.Count == 0 ? [TrimCurveFamily.Unsupported] : trim.CurveFamilies;+ foreach (var curveFamily in families)+ {+ loops.Add(new RetainedRegionLoopDescriptor(+ loopKind,+ curveFamily,+ trim.Classification,+ source.Family,+ other.Family,+ isBase ? source.OrientationRole : FacePatchOrientationRole.Reversed,+ retentionRole,+ status,+ BuildPerLoopDiagnostic(source.Family, other.Family, curveFamily, status, trim.Reason)));+ }+ }++ return loops;+ }++ private static RetainedRegionLoopKind DetermineLoopKind(SurfacePatchFamily sourceFamily, bool isBase, TrimCapabilityClassification classification)+ {+ if (classification == TrimCapabilityClassification.Deferred) return RetainedRegionLoopKind.Deferred;+ if (classification == TrimCapabilityClassification.Unsupported) return RetainedRegionLoopKind.Unsupported;+ if (isBase) return RetainedRegionLoopKind.InnerTrim;+ return sourceFamily == SurfacePatchFamily.Cylindrical || sourceFamily == SurfacePatchFamily.Spherical+ ? RetainedRegionLoopKind.MouthTrim+ : RetainedRegionLoopKind.InnerTrim;+ }++ private static RetainedRegionLoopStatus EvaluateLoopReadiness(IReadOnlyList<RetainedRegionLoopDescriptor> loops)+ {+ if (loops.Count == 0) return RetainedRegionLoopStatus.Deferred;+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.ExactReady)) return RetainedRegionLoopStatus.ExactReady;+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.SpecialCaseReady)) return RetainedRegionLoopStatus.SpecialCaseReady;+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.Deferred)) return RetainedRegionLoopStatus.Deferred;+ return RetainedRegionLoopStatus.Unsupported;+ }++ private static string BuildLoopDiagnostic(IReadOnlyList<RetainedRegionLoopDescriptor> loops, FacePatchRetentionStatus retentionStatus)+ {+ if (loops.Count == 0)+ {+ return retentionStatus == FacePatchRetentionStatus.Deferred+ ? "loop-scaffold-deferred: retention is deferred, so retained-region loop descriptors are not emitted."+ : "loop-scaffold-empty: no retained-region loops were generated for this candidate.";+ }++ if (loops.All(l => l.Status == RetainedRegionLoopStatus.Deferred))+ {+ return "loop-scaffold-deferred: trim matrix marks all retained-region loops deferred.";+ }++ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.SpecialCaseReady) && !loops.Any(l => l.Status == RetainedRegionLoopStatus.ExactReady))+ {+ return "loop-scaffold-special-case-ready: retained-region loop types are known with special-case restrictions; exact parameter solving remains deferred.";+ }++ return "loop-scaffold-ready: retained-region loop types are known; exact curve parameters and topology assembly remain deferred.";+ }++ private static string BuildPerLoopDiagnostic(SurfacePatchFamily source, SurfacePatchFamily opposite, TrimCurveFamily family, RetainedRegionLoopStatus status, string reason)+ => status switch+ {+ RetainedRegionLoopStatus.ExactReady => $"loop-exact-ready: {source}/{opposite} uses {family} trim family; parameters deferred ({reason})",+ RetainedRegionLoopStatus.SpecialCaseReady => $"loop-special-case-ready: {source}/{opposite} uses {family} trim family with restrictions ({reason})",+ RetainedRegionLoopStatus.Deferred => $"loop-deferred: {source}/{opposite} trim loop remains deferred ({reason})",+ _ => $"loop-unsupported: {source}/{opposite} trim loop unsupported ({reason})"+ };}diff --git a/docs/cir-f85-retained-region-loop-scaffolding.md b/docs/cir-f85-retained-region-loop-scaffolding.mdnew file mode 100644index 00000000..fc701613--- /dev/null+++ b/docs/cir-f85-retained-region-loop-scaffolding.md@@ -0,0 +1,82 @@+# CIR-F8.5: retained-region loop scaffolding for trim-ready face patch candidates++## Purpose++CIR-F8.5 adds a dry-run-only descriptor layer between CIR-F8.4 retention classification and future topology assembly.++For subtract candidates whose retention role is known, the generator now emits **retained-region loop descriptors** that state what loop families would be required to bound retained patches.++No BRep topology is created.++## Descriptor model++Each `FacePatchCandidate` now carries:++- `RetainedRegionLoops` (`RetainedRegionLoopDescriptor[]`)+- `LoopReadiness` (`ExactReady`, `SpecialCaseReady`, `Deferred`, `Unsupported`)+- `LoopDiagnostic` (candidate-level summary)++`RetainedRegionLoopDescriptor` contains:++- `LoopKind`+- `TrimCurveFamily`+- `TrimCapability`+- `SourceSurfaceFamily`+- `OppositeSurfaceFamily`+- `OrientationHint`+- `RetentionRole`+- `Status`+- `Diagnostic`++## Loop kinds and statuses++Loop kinds are bounded to scaffold vocabulary:++- `OuterBoundary`+- `InnerTrim`+- `MouthTrim`+- `CapTrim`+- `SeamTrim`+- `Deferred`+- `Unsupported`++Status reflects trim capability policy:++- `ExactReady` for `ExactSupported`+- `SpecialCaseReady` for `SpecialCaseOnly`+- `Deferred` for matrix-deferred entries+- `Unsupported` for unsupported entries++## Behavior by scenario++### subtract(box, cylinder)++- Base planar retained candidates emit `InnerTrim` loop descriptors against planar/cylindrical pairings.+- Cylindrical tool retained candidates emit `MouthTrim` loop descriptors against base planar families.+- Status surfaces as `SpecialCaseReady` (planar/cylindrical matrix policy) and can include exact-ready descriptors for planar/planar pairings.++### subtract(box, sphere)++- Base planar retained candidates emit circular loop descriptors from planar/spherical exact trim capability.+- Spherical tool retained candidates emit circular `MouthTrim` loop descriptors with `ExactReady` status.++### subtract(box, torus)++- Toroidal candidates emit deferred loop descriptors with matrix reason.+- Diagnostics preserve explicit quartic/algebraic deferred reason from planar/toroidal policy.++## Non-subtract behavior++For non-subtract roots, retention remains `NotApplicable`; loop descriptors are intentionally empty and diagnostics explain the bounded scope.++## Still deferred (intentional)++- Any BRep loop/coedge/edge/vertex emission+- Exact trim curve parameter solving+- Topology assembly and adjacency graphing+- Pair-specific subtract materializers+- Generated topology naming (SEM-A0 preserved)++## Recommended next step (CIR-F8.6)++Introduce bounded retained-loop grouping and canonical ordering per retained candidate (outer vs inner grouping and orientation contracts) while still avoiding BRep emission; use this to define a stable handoff contract for future topology assembly.