@tscircuit/fanout-solver 0.0.29 → 0.0.30

package/lib/fanout-solver.ts

@@ -259,7 +259,7 @@ function getBusDepthInRows(bus: PreparedBus): number {
   )
 }
 
-function createPreferredLayerAssignment(params: {
+function createInitialLayerAssignment(params: {
   buses: PreparedBus[]
   escapeLayers: string[]
   escapeLayersByBusId: Readonly<Record<string, readonly string[]>>
@@ -314,16 +314,16 @@ function createPreferredLayerAssignment(params: {
 }
 
 function prioritizeLayerAssignment(params: {
-  preferredAssignment: Readonly<Record<string, string>>
+  initialAssignment: Readonly<Record<string, string>>
   generatedAssignments: Array<Readonly<Record<string, string>>>
   maxAssignments: number
 }): Array<Readonly<Record<string, string>>> {
-  const { preferredAssignment, generatedAssignments, maxAssignments } = params
-  const preferredKey = JSON.stringify(preferredAssignment)
+  const { initialAssignment, generatedAssignments, maxAssignments } = params
+  const initialKey = JSON.stringify(initialAssignment)
   return [
-    preferredAssignment,
+    initialAssignment,
     ...generatedAssignments.filter(
-      (assignment) => JSON.stringify(assignment) !== preferredKey,
+      (assignment) => JSON.stringify(assignment) !== initialKey,
     ),
   ].slice(0, maxAssignments)
 }
@@ -335,7 +335,12 @@ function getCandidateEscapeLayersForBus(params: {
   staticClearanceCache: RouteBusStaticClearanceCache
 }): string[] {
   const { bus, srj, config, staticClearanceCache } = params
-  const individuallyRoutableLayers = config.escapeLayers.filter(
+  const busAllowedLayers = bus.allowedLayers
+  const allowedEscapeLayers =
+    busAllowedLayers === undefined
+      ? config.escapeLayers
+      : config.escapeLayers.filter((layer) => busAllowedLayers.includes(layer))
+  const individuallyRoutableLayers = allowedEscapeLayers.filter(
     (targetLayer) =>
       routeBus({
         srj,
@@ -357,9 +362,11 @@ function getCandidateEscapeLayersForBus(params: {
   // route this bus by itself cannot become viable later in an assignment.
   // Preserve the original candidates when none route so impossible problems
   // still produce the usual failed-solver result instead of throwing here.
-  return individuallyRoutableLayers.length > 0
-    ? individuallyRoutableLayers
-    : config.escapeLayers
+  const candidateLayers =
+    individuallyRoutableLayers.length > 0
+      ? individuallyRoutableLayers
+      : allowedEscapeLayers
+  return candidateLayers
 }
 
 export class FanoutSolver extends BaseSolver {
@@ -400,6 +407,24 @@ export class FanoutSolver extends BaseSolver {
     this.config = resolveConfig(inputSrj, options)
     this.preparedBuses = prepareFanoutBuses(inputSrj, options)
     for (const bus of this.preparedBuses) {
+      for (const allowedLayer of bus.allowedLayers ?? []) {
+        if (!this.config.layerNames.includes(allowedLayer)) {
+          throw new Error(
+            `FanoutSolver: bus "${bus.busId}" allows unavailable layer "${allowedLayer}"`,
+          )
+        }
+      }
+      if (
+        bus.termination.type === "boundary" &&
+        bus.allowedLayers !== undefined &&
+        !bus.allowedLayers.some((layer) =>
+          this.config.escapeLayers.includes(layer),
+        )
+      ) {
+        throw new Error(
+          `FanoutSolver: bus "${bus.busId}" has no allowed layer in escapeLayers`,
+        )
+      }
       if (bus.termination.type !== "plane") continue
       const planeLayer = bus.termination.layer
       if (!this.config.layerNames.includes(planeLayer)) {
@@ -407,6 +432,14 @@ export class FanoutSolver extends BaseSolver {
           `FanoutSolver: plane-terminated bus "${bus.busId}" targets unavailable layer "${planeLayer}"`,
         )
       }
+      if (
+        bus.allowedLayers !== undefined &&
+        !bus.allowedLayers.includes(planeLayer)
+      ) {
+        throw new Error(
+          `FanoutSolver: plane-terminated bus "${bus.busId}" targets disallowed layer "${planeLayer}"`,
+        )
+      }
       if (
         bus.connections.some(
           (connection) => connection.sourceLayer === planeLayer,
@@ -454,7 +487,7 @@ export class FanoutSolver extends BaseSolver {
       ...fixedPlaneAssignments,
     }))
     this.layerAssignments = prioritizeLayerAssignment({
-      preferredAssignment: createPreferredLayerAssignment({
+      initialAssignment: createInitialLayerAssignment({
         buses: this.preparedBuses,
         escapeLayers: this.config.escapeLayers,
         escapeLayersByBusId,

package/lib/prepare-buses.ts

@@ -407,6 +407,26 @@ function resolvePreferredExit(
   return value
 }
 
+function resolveAllowedLayers(
+  busId: string,
+  allowedLayers: readonly string[] | undefined,
+): string[] | undefined {
+  if (allowedLayers === undefined) return undefined
+  if (allowedLayers.length === 0) {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" must allow at least one layer`,
+    )
+  }
+  for (const layer of allowedLayers) {
+    if (typeof layer !== "string" || layer.length === 0) {
+      throw new Error(
+        `FanoutSolver: bus "${busId}" has an invalid allowed layer`,
+      )
+    }
+  }
+  return [...new Set(allowedLayers)]
+}
+
 export function resolveAvailableBoundaryRegions(
   value: readonly FanoutAvailableCornerAndSideInput[] | undefined,
 ): AvailableBoundaryRegion[] | undefined {
@@ -491,6 +511,10 @@ function resolveBusSpecs(
         (requestedBus as FanoutBusSpec).preferredExit ??
         options.defaultPreferredExit,
     )
+    const allowedLayers = resolveAllowedLayers(
+      requestedBus.busId,
+      (requestedBus as FanoutBusSpec).allowedLayers,
+    )
     if (termination.type === "plane" && preferredExit !== undefined) {
       throw new Error(
         `FanoutSolver: plane-terminated bus "${requestedBus.busId}" cannot also specify preferredExit`,
@@ -506,6 +530,7 @@ function resolveBusSpecs(
         (requestedBus as FanoutBusSpec).direction ??
         options.defaultDirection,
       preferredExit,
+      ...(allowedLayers === undefined ? {} : { allowedLayers }),
       termination,
     })
   }
@@ -1020,6 +1045,7 @@ export function prepareFanoutBuses(
       busId: busSpec.busId,
       direction: resolvedExit.direction,
       preferredExit: resolvedExit.preferredExit,
+      allowedLayers: busSpec.allowedLayers,
       termination: busSpec.termination ?? { type: "boundary" },
       connections: preparedConnections,
       componentId: sourceGrid.componentId,

package/lib/types.ts

@@ -76,6 +76,8 @@ export interface FanoutBusSpec extends SimpleRouteBus {
   sourceComponentId?: string
   direction?: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /** Layers to which this bus is allowed to escape. */
+  allowedLayers?: readonly string[]
   /**
    * Preferred downstream routing point for each connection after it leaves the
    * fanout boundary. This is routing guidance only and does not replace the
@@ -244,6 +246,8 @@ export interface PreparedBus {
   busId: string
   direction: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /** Layers to which this bus is allowed to escape. */
+  allowedLayers?: readonly string[]
   termination: FanoutBusTermination
   connections: PreparedConnection[]
   componentId: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/fanout-solver",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "BGA fanout solver with coordinated bus-layer escapes for SimpleRouteJson",
   "module": "lib/index.ts",
   "type": "module",