perf(cutting): defer alternate hole entries in preferred pass

OpenNest.Engine/CuttingPlanning/JointCuttingPlanSearch.cs

@@ -402,12 +402,18 @@ internal static class JointCuttingPlanSearch
                                 .FirstOrDefault(c => !choices.Any(e => e.ContourOrdinal == c), -1);
                             var target = downstream < 0 ? preference.PerimeterPierce
                                 : preference.Pierces[downstream];
-                            entries = SelectEntries(source, contour, target, node.Position - source.Location);
-                            // Preference only reorders retained candidates. Neither a failed
-                            // preferred entry nor an alternate hole order prunes this branch.
-                            if (preference.Entries.TryGetValue(contour, out var preferred))
-                                entries = entries.OrderBy(e => e.Point.DistanceTo(preferred.Point)
-                                    <= PostVerificationGeometry.Epsilon ? 0 : 1).ToArray();
+                            // The coarse pass already checked one owned, lead-feasible entry
+                            // for this hole. Do not prepare every alternate before trying it.
+                            // The subsequent full pass still enumerates and checks them all.
+                            if (preferredOnly && preference.Entries.TryGetValue(contour, out var first))
+                                entries = [first];
+                            else
+                            {
+                                entries = SelectEntries(source, contour, target, node.Position - source.Location);
+                                if (preference.Entries.TryGetValue(contour, out var preferred))
+                                    entries = entries.OrderBy(e => e.Point.DistanceTo(preferred.Point)
+                                        <= PostVerificationGeometry.Epsilon ? 0 : 1).ToArray();
+                            }
                         }
                     }
                     else

OpenNest.Tests/CuttingPlanning/HoleEndpointBudgetTests.cs

@@ -55,6 +55,12 @@ public class HoleEndpointBudgetTests
         Assert.Contains(checker.Check(snapshot.Placements[1].Execution, execution.DeparturePoint, 2),
             f => f.Kind == PostVerificationKind.RapidCrossing);
 
+        var measured = JointCuttingPlanSearch.Run(snapshot, default);
+        // The untouched baseline spent 63 prechecks in both modes because it evaluated
+        // alternates even in the single-chain pass. The fallback remains available.
+        Assert.Equal(CuttingPlanStatus.Ready, measured.Status);
+        Assert.True(measured.LeadPrechecks < 63,
+            $"Expected fewer prechecks than the baseline's 63; got {measured.LeadPrechecks}.");
         var result = CuttingPlanService.Plan(snapshot);
 
         Assert.True(result.Status == CuttingPlanStatus.Ready,

docs/cutting-planner.md

@@ -97,10 +97,13 @@ revisit an earlier entry when a later part cannot be reached safely. For multi-p
 requests containing regenerated holes, it first tries one ranked hole chain for
 each outside endpoint. This lets a later blocked approach change the previous
 part's departure without first exhausting combinations of its earlier holes.
-This preferred pass uses the same emitted-motion checks, shared expansion budget
-and stall limit as the retained search; on failure the full entry/hole-order
-backtracking pass remains available. Before that full pass, a failed preferred tour
-also gets a directed-contour recovery pass for parts with at most 16 holes. It
+This preferred pass uses the hole centres to propose an order and checks only the
+one previously lead-feasible entry selected for each hole; it does not prepare
+alternative entries until a subsequent recovery/full pass needs them. It still
+checks emitted motions under the shared expansion budget and stall limit, and
+on failure the full entry/hole-order backtracking pass remains available. A failed
+preferred tour first gets a directed-contour recovery pass for parts with at most
+16 holes. It
 tries native outside entries beyond the ranked shortlist, then builds a hole route
 from actual emitted pierces, checking each transition against already released
 contours. This reaches inner edges of interlocking concave parts which can be