@tscircuit/fanout-solver 0.0.54 → 0.0.56

package/README.md

@@ -306,6 +306,19 @@ To capture the inputs without solving, use `bun run generate:dataset31`.
 The optional `--dataset dataset31` flag is accepted for explicit CI invocation;
 other dataset selections are rejected.
 
+To isolate a failure without changing pads or clearance rules, reduce a captured
+input by bus or connection count. This is a diagnostic, not a benchmark score:
+
+```sh
+bun scripts/debug-dataset31.ts --input benchmark-results/inputs/10-left-bottom-offset.json --buses DDR_ADDR_CTRL --connection-limit 7 --output /tmp/address-seven
+bun scripts/debug-dataset31.ts --input benchmark-results/inputs/10-left-bottom-offset.json --buses DDR_ADDR_CTRL --output /tmp/address-eight
+```
+
+Each run has a hard process deadline and saves JSON progress and an SVG preview.
+Use `--dump-input <path> --capture-only` to save the exact reduced solver input
+as a regression fixture. Retained buses keep their original targets and timing
+limits; only removed connections and their differential-pair metadata are pruned.
+
 Each sample runs in an isolated process, with up to four concurrent processes
 locally and a **120-second hard timeout** by default. A synchronous solver hang,
 exception, or unsolved case does not prevent later samples from running.

package/lib/fanout-solver.ts

@@ -1,6 +1,8 @@
 import type { SimpleRouteJson } from "@tscircuit/capacity-autorouter"
 import { BaseSolver } from "@tscircuit/solver-utils"
-import { shortenBusPlans } from "./shorten-bus-plans"
+import { selectCompatibleCandidates } from "./select-compatible-candidates"
+import { refineAdaptivePlaneReservationCore } from "./refine-adaptive-plane-reservations"
+import { shouldUseAdaptiveDensePlaneRouting } from "./should-use-adaptive-dense-plane-routing"
 import { type GraphicsObject, mergeGraphics } from "graphics-debug"
 import { addViaLayerMetadataToSrj } from "./add-via-layer-metadata"
 import { getCornerBandSide, getExitEdgeForDirection } from "./boundary-exit"
@@ -34,6 +36,8 @@ import {
 } from "./route-bus"
 import { routeSingleLayerWithAdaptiveExitsSteps } from "./route-single-layer-adaptive-exits"
 import { routeSingleLayerWithPushAndShove } from "./route-single-layer-push-shove"
+import { getRuntimeProcess } from "./runtime-process"
+import { shortenBusPlans } from "./shorten-bus-plans"
 import type {
   AssignmentAttempt,
   Bounds,
@@ -49,6 +53,11 @@ import type {
 import { validateFanoutSolution } from "./validate-fanout-solution"
 import { visualizeSimpleRouteJson } from "./visualize-simple-route-json"
 
+// Browser Web Workers do not expose Node's `process` global. Keep a local,
+// browser-safe adapter so the optional debug environment flags still work in
+// Node and Bun without crashing browser-based routing.
+const process = getRuntimeProcess(globalThis)
+
 interface ResolvedFanoutConfig {
   traceWidth: number
   viaDiameter: number
@@ -1035,7 +1044,11 @@ export class FanoutSolver extends BaseSolver {
           escapeLayersByBusId: this.escapeLayersByBusId,
           preferOrderedCoordinatedWindingLayers:
             this.config.densePlaneReservationBusIds.length > 0 ||
-            this.config.denseUnrestrictedPlaneRoutingBusIds.length > 0,
+            this.config.denseUnrestrictedPlaneRoutingBusIds.length > 0 ||
+            shouldUseAdaptiveDensePlaneRouting(
+              this.preparedBuses,
+              this.config.allowBlindAndBuriedVias,
+            ),
         }),
         generatedAssignments,
         maxAssignments: this.config.maxLayerCombinations,
@@ -1383,6 +1396,8 @@ export class FanoutSolver extends BaseSolver {
     busesInRoutingOrder: readonly PreparedBus[]
     denseRoutingStrategy?: "pad-aligned" | "boundary-aligned"
     lengthMatchingStage?: "before-planes" | "after-planes"
+    promotedPlaneReservationBusIds?: readonly string[]
+    planeReservationRetryCount?: number
   }): Generator<FanoutWorkYield, MixedTerminationState | null, unknown> {
     if (this.config.allowBlindAndBuriedVias) return null
     const usePadAlignedDenseRouting =
@@ -1398,6 +1413,8 @@ export class FanoutSolver extends BaseSolver {
             "plane-match:incremental-failed",
             "plane-route:alternate-candidate-counts",
             "plane-route:alternate-search",
+            "plane-route:csp",
+            "plane-reservation-core",
             "plane-route:promote-failed",
             "plane-route:alternate-choice",
             "plane-route:promote-zero-candidates",
@@ -1416,9 +1433,20 @@ export class FanoutSolver extends BaseSolver {
     const unsortedBoundaryBuses = params.busesInRoutingOrder.filter(
       (bus) => bus.termination.type === "boundary",
     )
-    const useConfiguredDensePlaneRouting =
+    const configuredDensePlaneRouting =
       this.config.densePlaneReservationBusIds.length > 0 ||
       this.config.denseUnrestrictedPlaneRoutingBusIds.length > 0
+    const useAdaptiveDensePlaneRouting =
+      !configuredDensePlaneRouting &&
+      shouldUseAdaptiveDensePlaneRouting(
+        this.preparedBuses,
+        this.config.allowBlindAndBuriedVias,
+      )
+    const useConfiguredDensePlaneRouting =
+      configuredDensePlaneRouting || useAdaptiveDensePlaneRouting
+    const useAdaptiveJointPlaneSelection =
+      useAdaptiveDensePlaneRouting &&
+      (params.planeReservationRetryCount ?? 0) === 0
     const matchLengthsAfterPlanes =
       useConfiguredDensePlaneRouting &&
       params.lengthMatchingStage !== "before-planes"
@@ -1657,6 +1685,17 @@ export class FanoutSolver extends BaseSolver {
                   : 8,
               )
             : planeBuses
+    if (params.promotedPlaneReservationBusIds) {
+      activeBoundaryReservationPlaneBuses = [
+        ...new Set([
+          ...activeBoundaryReservationPlaneBuses,
+          ...planeBuses.filter((bus) =>
+            params.promotedPlaneReservationBusIds!.includes(bus.busId),
+          ),
+        ]),
+      ]
+    }
+    const unroutablePlaneBusIds = new Set<string>()
     debugDense(
       "start",
       boundaryBuses.map((bus) => `${bus.busId}:${bus.connections.length}`),
@@ -1713,7 +1752,7 @@ export class FanoutSolver extends BaseSolver {
                 getCornerBandSide(bus.exitEdge, bus.preferredExit)
               ? getDenseSingletonBoundaryGeometry(bus).targetProjection > 0
               : getExitEdgeForDirection(bus.direction) !== bus.exitEdge
-          : bus.exitEdge === "top" && bus.connections.length >= 8
+          : hasThreeWideBoundaryBuses && bus.connections.length >= 8
             ? false
             : getExitEdgeForDirection(bus.direction) !== bus.exitEdge,
       ]),
@@ -2108,6 +2147,16 @@ export class FanoutSolver extends BaseSolver {
             return [
               {
                 connectionName: connection.connection.name,
+                sourceEscapeSegment: matchedPlans.some(
+                  (plan) => plan.connectionIndex === connection.connectionIndex,
+                )
+                  ? undefined
+                  : {
+                      start: connection.sourcePoint,
+                      end: center,
+                      layer: connection.sourceLayer,
+                      width: this.config.traceWidth,
+                    },
                 via: {
                   center,
                   diameter: this.config.viaDiameter,
@@ -2169,7 +2218,7 @@ export class FanoutSolver extends BaseSolver {
           fixedViaPointsByConnectionIndex,
           reservedVias: getReservedVias(bus),
           viaMinimalOnly: process.env.FANOUT_DEBUG_ALLOW_EXTRA_VIAS !== "1",
-          allowBoundarySideViaFallback: true,
+          allowBoundarySideViaFallback: bus.connections.length === 1,
           preferCornerBoundaryVia: useConfiguredDensePlaneRouting,
           adaptiveWindingRouteOrder,
           alignWindingGridToPads:
@@ -2310,7 +2359,21 @@ export class FanoutSolver extends BaseSolver {
             ))[0]
             if (busPlans) break
           }
-          if (!busPlans) fixedViaPointsByConnectionIndex = originalPoints
+          if (!busPlans) {
+            fixedViaPointsByConnectionIndex = originalPoints
+            if (bus.connections.length === 2) {
+              busPlans = (yield* routeAlternatives(
+                {
+                  ...routeParams,
+                  fixedViaPointsByConnectionIndex: originalPoints,
+                  reservedVias: getReservedVias(bus),
+                  allowBoundarySideViaFallback: true,
+                  fixedViaFallbackRouteOrderAttempts: 1,
+                },
+                1,
+              ))[0]
+            }
+          }
         }
         if (busPlans && bus.maxLengthSkew !== undefined) {
           const lengths = busPlans.map((plan) => plan.length)
@@ -3068,6 +3131,79 @@ export class FanoutSolver extends BaseSolver {
                     })),
                   }),
                 )
+                if (useAdaptiveJointPlaneSelection) {
+                  const acceptedPlans = [
+                    ...candidatePlans,
+                    ...feasibleAlternatePlanePlans,
+                  ]
+                  for (const planeBus of planeBuses) {
+                    if (
+                      matchedPlaneBuses.includes(planeBus) ||
+                      candidateSets.some((set) => set.planeBus === planeBus)
+                    )
+                      continue
+                    const candidates: IndependentPlaneRouteCandidate[] = []
+                    const sites = getComponentDogboneViaSiteCandidates(
+                      [planeBus],
+                      {
+                        viaDiameter: this.config.viaDiameter,
+                        viaHoleDiameter: this.config.viaHoleDiameter,
+                        traceWidth: this.config.traceWidth,
+                        clearance: this.config.clearance,
+                        blockingSegments: acceptedPlans.flatMap((plan) =>
+                          plan.segments.map((segment) => ({
+                            connectionIndex: plan.connectionIndex,
+                            segment,
+                          })),
+                        ),
+                        blockingVias: acceptedPlans.flatMap((plan) =>
+                          [
+                            plan.via,
+                            ...(plan.additionalVias ?? []),
+                            plan.planeEndpointVia,
+                          ]
+                            .filter((via) => via !== undefined)
+                            .map((via) => ({
+                              connectionIndex: plan.connectionIndex,
+                              center: via!.center,
+                              diameter: via!.diameter,
+                              spanLayers: via!.spanLayers,
+                            })),
+                        ),
+                        additionalObstacles: this.routingSrj.obstacles,
+                        preferPlaneCheckerboardSites: true,
+                        canShareCopper,
+                      },
+                    )
+                    for (const site of sites) {
+                      const plans = routeBus({
+                        srj: this.routingSrj,
+                        bus: planeBus,
+                        targetLayer:
+                          params.busLayerAssignments[planeBus.busId]!,
+                        acceptedPlans,
+                        layerNames: this.config.layerNames,
+                        traceWidth: this.config.traceWidth,
+                        viaDiameter: this.config.viaDiameter,
+                        viaHoleDiameter: this.config.viaHoleDiameter,
+                        clearance: this.config.clearance,
+                        compactBusTracks: this.config.compactBusTracks,
+                        allowBlindAndBuriedVias: false,
+                        allowSameNetMerges: this.config.allowSameNetMerges,
+                        fixedViaPointsByConnectionIndex: new Map([
+                          [site.connectionIndex, site.point],
+                        ]),
+                      })
+                      if (plans)
+                        candidates.push({
+                          key: `${planeBus.busId}:local:${candidates.length}`,
+                          planeBus,
+                          plans,
+                        })
+                    }
+                    candidateSets.push({ planeBus, candidates })
+                  }
+                }
                 debugDense(
                   "plane-route:alternate-candidate-counts",
                   candidateSets.map((candidateSet) => [
@@ -3075,6 +3211,10 @@ export class FanoutSolver extends BaseSolver {
                     candidateSet.candidates.length,
                   ]),
                 )
+                for (const candidateSet of candidateSets) {
+                  if (candidateSet.candidates.length === 0)
+                    unroutablePlaneBusIds.add(candidateSet.planeBus.busId)
+                }
                 const compatibilityByCandidatePair = new Map<string, boolean>()
                 const candidatesAreCompatible = (
                   first: IndependentPlaneRouteCandidate,
@@ -3201,10 +3341,82 @@ export class FanoutSolver extends BaseSolver {
                   )
                   return null
                 }
-                const selectedCandidates = selectCompatiblePlaneRoutes(
-                  candidateSets,
-                  [],
-                )
+                let selectedCandidates: IndependentPlaneRouteCandidate[] | null
+                if (useAdaptiveDensePlaneRouting) {
+                  const getUniqueDomains = (sets: typeof candidateSets) =>
+                    sets.map((set) => [
+                      ...new Map(
+                        set.candidates.map((candidate) => [
+                          JSON.stringify(
+                            candidate.plans.map((plan) => [
+                              plan.segments,
+                              plan.via,
+                              plan.additionalVias,
+                              plan.planeEndpointSegments,
+                              plan.planeEndpointVia,
+                            ]),
+                          ),
+                          candidate,
+                        ]),
+                      ).values(),
+                    ])
+                  const runCandidateSelection = (
+                    sets: typeof candidateSets,
+                    maximumSearchStates = maximumAlternatePlaneSearchStates,
+                  ) =>
+                    selectCompatibleCandidates({
+                      candidateSets: getUniqueDomains(sets),
+                      maximumSearchStates,
+                      areCompatible: (first, second) =>
+                        fanoutPlansAreMutuallyClear({
+                          plans: [...first.plans, ...second.plans],
+                          srj: this.routingSrj,
+                          clearance: this.config.clearance,
+                          allowSameNetMerges: this.config.allowSameNetMerges,
+                        }),
+                    })
+                  const result = runCandidateSelection(candidateSets)
+                  debugDense(
+                    "plane-route:csp",
+                    result.selection ? "complete" : "failed",
+                    result.searchStates,
+                    result.emptyDomainIndices.map(
+                      (index) => candidateSets[index]!.planeBus.busId,
+                    ),
+                  )
+                  selectedCandidates = result.selection
+                  alternatePlaneSearchStates = result.searchStates
+                  if (!result.selection && useAdaptiveDensePlaneRouting) {
+                    const expanded = result.emptyDomainIndices
+                      .map((index) => candidateSets[index]!.planeBus.busId)
+                      .filter(
+                        (id) =>
+                          !orderedAlternatePlaneBuses.some(
+                            (bus) => bus.busId === id,
+                          ),
+                      )
+                    if (expanded.length > 0) {
+                      debugDense("plane-route:expand-domains", expanded)
+                      return matchViaPointsAroundPlans(
+                        candidatePlans,
+                        new Set([...promotedAlternatePlaneBusIds, ...expanded]),
+                      )
+                    }
+                  }
+                  if (!result.selection)
+                    for (const index of (params.planeReservationRetryCount ??
+                      0) === 0
+                      ? result.conflictDomainIndices
+                      : result.emptyDomainIndices.slice(0, 1))
+                      unroutablePlaneBusIds.add(
+                        candidateSets[index]!.planeBus.busId,
+                      )
+                } else {
+                  selectedCandidates = selectCompatiblePlaneRoutes(
+                    candidateSets,
+                    [],
+                  )
+                }
                 alternatePlanePlans = selectedCandidates
                   ? [
                       ...feasibleAlternatePlanePlans,
@@ -3230,6 +3442,18 @@ export class FanoutSolver extends BaseSolver {
               )
               if (!alternatePlanePlans) return null
               feasibleAlternatePlanePlans = alternatePlanePlans
+              if (useAdaptiveJointPlaneSelection) {
+                matchedPlaneBusesInRoutingOrder = []
+                return new Map([
+                  ...fixedBoundaryViaPoints,
+                  ...alternatePlanePlans
+                    .filter((plan) => plan.via)
+                    .map(
+                      (plan) =>
+                        [plan.connectionIndex, plan.via!.center] as const,
+                    ),
+                ])
+              }
             }
             let planeBusIdsRoutedWithoutDogbones = new Set<string>()
             let allBlockingSegments = [...blockingSegments]
@@ -3679,6 +3903,39 @@ export class FanoutSolver extends BaseSolver {
       }
     }
 
+    if (
+      useAdaptiveDensePlaneRouting &&
+      unroutablePlaneBusIds.size > 0 &&
+      (params.planeReservationRetryCount ?? 0) < 5
+    ) {
+      const newlyPromoted = [...unroutablePlaneBusIds].filter(
+        (id) =>
+          !activeBoundaryReservationPlaneBuses.some((bus) => bus.busId === id),
+      )
+      const refinedPromotions =
+        (params.planeReservationRetryCount ?? 0) === 0
+          ? refineAdaptivePlaneReservationCore({
+              candidateBusIds: newlyPromoted,
+              activeBusIds: new Set(
+                activeBoundaryReservationPlaneBuses.map((bus) => bus.busId),
+              ),
+              planeBuses,
+            })
+          : newlyPromoted
+      if (refinedPromotions.length > 0) {
+        debugDense("plane-reservation-core", refinedPromotions)
+        debugDense("promote-reservations", refinedPromotions)
+        return yield* this.routeDenseThroughAllMixedTerminationSteps({
+          ...params,
+          promotedPlaneReservationBusIds: [
+            ...(params.promotedPlaneReservationBusIds ?? []),
+            ...refinedPromotions,
+          ],
+          planeReservationRetryCount:
+            (params.planeReservationRetryCount ?? 0) + 1,
+        })
+      }
+    }
     if (matchLengthsAfterPlanes) {
       return yield* this.routeDenseThroughAllMixedTerminationSteps({
         ...params,

package/lib/get-dogbone-side-variants.ts

@@ -0,0 +1,26 @@
+import type { FanoutDirection, Point2D } from "./types"
+
+/** A bounded fallback for channels trapped by uniform outward dogbones. */
+export function getDogboneSideVariants(
+  connections: readonly { connectionIndex: number; sourcePoint: Point2D }[],
+  direction: FanoutDirection,
+): number[][] {
+  const axis = direction === "up" || direction === "down" ? "y" : "x"
+  const variants = connections
+    .slice(0, 32)
+    .map(({ connectionIndex }) => [connectionIndex])
+  // Two pads in the same escape row can jointly close a winding corridor.
+  // Move both to the other half-pitch row, keeping every other site unchanged.
+  // Do not enumerate the exponential Cartesian product of all via sites.
+  for (let first = 0; first < connections.length; first++) {
+    for (let second = first + 1; second < connections.length; second++) {
+      if (variants.length >= 32) return variants
+      const a = connections[first]!
+      const b = connections[second]!
+      if (Math.abs(a.sourcePoint[axis] - b.sourcePoint[axis]) <= 1e-9) {
+        variants.push([a.connectionIndex, b.connectionIndex])
+      }
+    }
+  }
+  return variants
+}

package/lib/refine-adaptive-plane-reservations.ts

@@ -0,0 +1,94 @@
+import type { PreparedBus } from "./types"
+
+const EPSILON = 1e-9
+
+/**
+ * A failed arc-consistency chain ends with the domain that removed the last
+ * supported candidate. When that plane pad has an adjacent peer farther into
+ * the component, reserving the peer keeps the outer pad available for a
+ * displaced route while protecting the same local dogbone corridor.
+ */
+export function refineAdaptivePlaneReservationCore(params: {
+  candidateBusIds: readonly string[]
+  activeBusIds: ReadonlySet<string>
+  planeBuses: readonly PreparedBus[]
+}): string[] {
+  const core = params.candidateBusIds.filter(
+    (busId) => !params.activeBusIds.has(busId),
+  )
+  if (core.length < 2) return core
+
+  const terminalIndex = core.length - 1
+  const terminal = params.planeBuses.find(
+    (bus) => bus.busId === core[terminalIndex],
+  )
+  const source = terminal?.connections[0]?.sourcePoint
+  if (
+    !terminal ||
+    !source ||
+    terminal.connections.length !== 1 ||
+    terminal.termination.type !== "plane"
+  )
+    return core
+  const terminalLayer = terminal.termination.layer
+
+  const perpendicularAxis =
+    terminal.direction === "up" || terminal.direction === "down" ? "x" : "y"
+  const parallelAxis = perpendicularAxis === "x" ? "y" : "x"
+  const componentCoordinates =
+    perpendicularAxis === "x" ? terminal.xCoordinates : terminal.yCoordinates
+  const pitch = perpendicularAxis === "x" ? terminal.pitchX : terminal.pitchY
+  if (
+    componentCoordinates.length === 0 ||
+    !Number.isFinite(pitch) ||
+    pitch <= EPSILON
+  ) {
+    return core
+  }
+
+  const componentCenter =
+    (Math.min(...componentCoordinates) + Math.max(...componentCoordinates)) / 2
+  const inwardSign = Math.sign(componentCenter - source[perpendicularAxis])
+  if (inwardSign === 0) return core
+
+  const coreIds = new Set(core)
+  const replacement = params.planeBuses
+    .filter((bus) => {
+      const candidateSource = bus.connections[0]?.sourcePoint
+      if (
+        bus === terminal ||
+        bus.componentId !== terminal.componentId ||
+        bus.termination.type !== "plane" ||
+        bus.termination.layer !== terminalLayer ||
+        bus.direction !== terminal.direction ||
+        bus.connections.length !== 1 ||
+        !candidateSource ||
+        params.activeBusIds.has(bus.busId) ||
+        coreIds.has(bus.busId) ||
+        Math.abs(candidateSource[parallelAxis] - source[parallelAxis]) > EPSILON
+      ) {
+        return false
+      }
+      const inwardDistance =
+        (candidateSource[perpendicularAxis] - source[perpendicularAxis]) *
+        inwardSign
+      return inwardDistance > EPSILON && inwardDistance <= pitch + EPSILON
+    })
+    .toSorted((first, second) => {
+      const firstSource = first.connections[0]!.sourcePoint
+      const secondSource = second.connections[0]!.sourcePoint
+      return (
+        Math.abs(firstSource[perpendicularAxis] - source[perpendicularAxis]) -
+          Math.abs(
+            secondSource[perpendicularAxis] - source[perpendicularAxis],
+          ) ||
+        first.connections[0]!.connectionIndex -
+          second.connections[0]!.connectionIndex
+      )
+    })[0]
+
+  if (!replacement) return core
+  return core.map((busId, index) =>
+    index === terminalIndex ? replacement.busId : busId,
+  )
+}