@tscircuit/fanout-solver 0.0.37 → 0.0.38

package/README.md

@@ -73,6 +73,10 @@ and treats each bus-layer decision atomically.
   visibly continuous pad connections.
 - Chamfers orthogonal routing corners into 45° segments before validating and
   emitting the fanout.
+- Honors a boundary bus `maxLengthSkew` as a hard local-fanout constraint. It
+  adds straight/45° meanders only after the dense component escape, keeps the
+  original endpoints and vias, and atomically rejects an assignment when the
+  requested skew cannot fit inside that bus's shared boundary.
 - Verifies oriented-pad, via, trace, and already-routed fanout clearance on
   every complete candidate, independent of the routing strategy that produced
   it.
@@ -189,6 +193,7 @@ The canonical bus input is the current `SimpleRouteJson` bus structure:
       busId: "ddr",
       connectionNames: ["BUS_DDR_01", "BUS_DDR_02", "BUS_DDR_03"],
       preferredExit: "right",
+      maxLengthSkew: 0.25,
     },
   ],
 }
@@ -201,6 +206,13 @@ routed cleanly, the solver rejects that bus for the current layer assignment and
 tries another combination. `busExitPreferences` provides the same override
 without modifying the input object.
 
+`maxLengthSkew` is measured in millimeters of planar routed copper within this
+fanout phase. It is supported for multi-connection boundary buses. A loose or
+omitted constraint leaves the routed geometry unchanged; an impossible
+constraint fails instead of returning a fanout that violates the declared skew.
+Plane-terminated buses reject `maxLengthSkew` because they do not have a
+boundary tuning corridor.
+
 `availableCornersAndSides` is a solver-wide hard constraint. Its directed
 corner names distinguish the two edges meeting at a corner: `top_left` exits
 through the top edge, while `left_top` exits through the left edge. The complete
@@ -473,5 +485,7 @@ label.
 ## Scope
 
 This package owns the BGA pad-to-breakout prefix. It does not replace the
-board-level autorouter, length-match buses, or route arbitrary obstacles between
-the breakout boundary and the final destination.
+board-level autorouter or route arbitrary obstacles between the breakout
+boundary and the final destination. Its `maxLengthSkew` matching applies to the
+local fanout prefix; end-to-end delay matching across multiple routing phases
+still belongs to a board-level coordinator.

package/lib/fanout-solver.ts

@@ -8,6 +8,7 @@ import {
   completeOriginalEndpoints,
 } from "./complete-original-endpoints"
 import { generateLayerAssignments, getCopperLayerNames } from "./layer-names"
+import { matchBusPlanLengths } from "./match-bus-lengths"
 import {
   prepareFanoutBuses,
   resolveAvailableBoundaryRegions,
@@ -27,6 +28,7 @@ import type {
   FanoutRoutePlan,
   FanoutSolverOptions,
   FanoutSolverOutput,
+  FanoutValidationIssue,
   PreparedBus,
 } from "./types"
 import { validateFanoutSolution } from "./validate-fanout-solution"
@@ -482,6 +484,7 @@ export class FanoutSolver extends BaseSolver {
   private nextAssignmentIndex = 0
   private nextGeneratedAssignmentIndex = 0
   private bestAttempt: AssignmentAttempt | null = null
+  private lengthMatchingFailure: FanoutValidationIssue | null = null
   private endpointCompletion: CompleteOriginalEndpointsResult | null = null
 
   constructor(
@@ -658,6 +661,19 @@ export class FanoutSolver extends BaseSolver {
     })
   }
 
+  private matchCompletePlanLengths(
+    plans: readonly FanoutRoutePlan[],
+  ): ReturnType<typeof matchBusPlanLengths> {
+    return matchBusPlanLengths({
+      plans,
+      preparedBuses: this.preparedBuses,
+      inputSrj: this.inputSrj,
+      sharedBoundary: this.getValidationBoundary(),
+      clearance: this.config.clearance,
+      allowSameNetMerges: this.config.allowSameNetMerges,
+    })
+  }
+
   private evaluateAssignmentWithStrategy(
     assignmentIndex: number,
     busLayerAssignments: Readonly<Record<string, string>>,
@@ -784,6 +800,29 @@ export class FanoutSolver extends BaseSolver {
     }
 
     let validationIssues: FanoutAttemptSummary["validationIssues"]
+    if (plans.length === this.inputSrj.connections.length) {
+      const lengthMatching = this.matchCompletePlanLengths(plans)
+      if (lengthMatching.plans) {
+        plans = lengthMatching.plans
+      } else {
+        const constrainedBus = lengthMatching.failedBus
+        const lengthMatchingIssue: FanoutValidationIssue = {
+          code: "bus-length-skew",
+          message: `Bus ${constrainedBus.busId} could not satisfy its ${constrainedBus.maxLengthSkew!.toFixed(6)}mm routed-length skew within the fanout boundary`,
+          busId: constrainedBus.busId,
+        }
+        validationIssues = [lengthMatchingIssue]
+        this.lengthMatchingFailure ??= lengthMatchingIssue
+        plans = []
+        failedBusIds = [
+          constrainedBus.busId,
+          ...this.preparedBuses
+            .map((bus) => bus.busId)
+            .filter((busId) => busId !== constrainedBus.busId),
+        ]
+        blockingBusCounts.clear()
+      }
+    }
     let outputSrj = buildOutputSimpleRouteJson({
       inputSrj: this.inputSrj,
       plans,
@@ -1088,32 +1127,54 @@ export class FanoutSolver extends BaseSolver {
 
     let bestState: GroupedBeamState | undefined
     let outputSrj: SimpleRouteJson | undefined
+    let bestMatchedScore = Number.POSITIVE_INFINITY
+    let bestAdditionalViaCount = Number.POSITIVE_INFINITY
+    const getCompleteStateScore = (state: GroupedBeamState): number =>
+      state.plans.reduce((total, plan) => total + plan.length, 0) +
+      getPlanViaCount(state.plans) * 0.1 +
+      assignmentLoadPenalty(
+        state.assignment,
+        this.preparedBuses,
+        this.config.balanceLayerLoadByConnectionCount,
+      ) *
+        getLayerLoadPenaltyWeight(this.config)
+    const hasLengthConstraints = this.preparedBuses.some(
+      (bus) => bus.maxLengthSkew !== undefined,
+    )
     for (const state of states) {
       if (state.plans.length !== this.inputSrj.connections.length) continue
+      const lengthMatching = this.matchCompletePlanLengths(state.plans)
+      if (!lengthMatching.plans) continue
+      const lengthMatchedPlans = lengthMatching.plans
       const candidateOutput = buildOutputSimpleRouteJson({
         inputSrj: this.inputSrj,
-        plans: state.plans,
+        plans: lengthMatchedPlans,
         layerNames: this.config.layerNames,
       })
-      if (!this.validateCompletePlans(state.plans, candidateOutput).valid) {
+      if (
+        !this.validateCompletePlans(lengthMatchedPlans, candidateOutput).valid
+      ) {
         continue
       }
-      bestState = state
-      outputSrj = candidateOutput
-      break
+      const candidateState = { ...state, plans: lengthMatchedPlans }
+      const candidateAdditionalViaCount =
+        this.getCoordinatedAdditionalViaCount(lengthMatchedPlans)
+      const candidateScore = getCompleteStateScore(candidateState)
+      if (
+        !bestState ||
+        candidateAdditionalViaCount < bestAdditionalViaCount ||
+        (candidateAdditionalViaCount === bestAdditionalViaCount &&
+          candidateScore < bestMatchedScore)
+      ) {
+        bestState = candidateState
+        outputSrj = candidateOutput
+        bestMatchedScore = candidateScore
+        bestAdditionalViaCount = candidateAdditionalViaCount
+      }
+      if (!hasLengthConstraints) break
     }
     if (!bestState || !outputSrj) return null
-    const score =
-      bestState.plans.length === this.inputSrj.connections.length
-        ? bestState.plans.reduce((total, plan) => total + plan.length, 0) +
-          getPlanViaCount(bestState.plans) * 0.1 +
-          assignmentLoadPenalty(
-            bestState.assignment,
-            this.preparedBuses,
-            this.config.balanceLayerLoadByConnectionCount,
-          ) *
-            getLayerLoadPenaltyWeight(this.config)
-        : Number.POSITIVE_INFINITY
+    const score = bestMatchedScore
     if (!Number.isFinite(score)) return null
 
     const summary: FanoutAttemptSummary = {
@@ -1397,9 +1458,14 @@ export class FanoutSolver extends BaseSolver {
         this.solved = true
       } else {
         this.failed = true
-        this.error = this.bestAttempt
-          ? `FanoutSolver: best layer assignment routed ${this.bestAttempt.summary.routedConnectionCount}/${this.inputSrj.connections.length} connections`
-          : "FanoutSolver: no layer assignment could be evaluated"
+        const validationMessage =
+          this.lengthMatchingFailure?.message ??
+          this.bestAttempt?.summary.validationIssues?.[0]?.message
+        this.error = validationMessage
+          ? `FanoutSolver: ${validationMessage}`
+          : this.bestAttempt
+            ? `FanoutSolver: best layer assignment routed ${this.bestAttempt.summary.routedConnectionCount}/${this.inputSrj.connections.length} connections`
+            : "FanoutSolver: no layer assignment could be evaluated"
       }
       return
     }

package/lib/match-bus-lengths.ts

@@ -0,0 +1,571 @@
+import type {
+  SimpleRouteJson,
+  SimplifiedPcbTrace,
+} from "@tscircuit/capacity-autorouter"
+import {
+  distance,
+  distancePointToSegment,
+  distanceSegmentToSegment,
+  segmentsAreClear,
+} from "./geometry"
+import { fanoutPlansAreClear } from "./route-bus"
+import type {
+  Bounds,
+  FanoutRoutePlan,
+  Point2D,
+  PreparedBus,
+  RoutedSegment,
+  RoutedVia,
+} from "./types"
+
+const EPSILON = 1e-6
+
+function pointsMatch(first: Point2D, second: Point2D): boolean {
+  return distance(first, second) <= EPSILON
+}
+
+function getPlanVias(plan: FanoutRoutePlan): RoutedVia[] {
+  return [plan.via, ...(plan.additionalVias ?? [])].filter(
+    (via): via is RoutedVia => via !== undefined,
+  )
+}
+
+function rebuildTraceRoute(
+  plan: FanoutRoutePlan,
+  segments: readonly RoutedSegment[],
+): SimplifiedPcbTrace["route"] | null {
+  const firstSegment = segments[0]
+  if (!firstSegment) return null
+  const firstOriginalWire = plan.trace.route.find(
+    (point) => point.route_type === "wire",
+  )
+  const lastOriginalWire = plan.trace.route.findLast(
+    (point) => point.route_type === "wire",
+  )
+  const route: SimplifiedPcbTrace["route"] = [
+    {
+      route_type: "wire",
+      ...firstSegment.start,
+      width: firstSegment.width,
+      layer: firstSegment.layer,
+      ...(firstOriginalWire?.route_type === "wire" &&
+      firstOriginalWire.start_pcb_port_id
+        ? { start_pcb_port_id: firstOriginalWire.start_pcb_port_id }
+        : {}),
+    },
+  ]
+  let currentPoint = firstSegment.start
+  let currentLayer = firstSegment.layer
+  const vias = getPlanVias(plan)
+
+  for (const [segmentIndex, segment] of segments.entries()) {
+    if (!pointsMatch(currentPoint, segment.start)) return null
+    if (currentLayer !== segment.layer) {
+      const transitionVia = vias.find(
+        (via) =>
+          pointsMatch(via.center, segment.start) &&
+          via.spanLayers.includes(currentLayer) &&
+          via.spanLayers.includes(segment.layer),
+      )
+      if (!transitionVia) return null
+      route.push({
+        route_type: "via",
+        ...segment.start,
+        from_layer: currentLayer,
+        to_layer: segment.layer,
+        via_diameter: transitionVia.diameter,
+        via_hole_diameter: transitionVia.holeDiameter,
+      })
+      route.push({
+        route_type: "wire",
+        ...segment.start,
+        width: segment.width,
+        layer: segment.layer,
+      })
+      currentLayer = segment.layer
+    }
+    route.push({
+      route_type: "wire",
+      ...segment.end,
+      width: segment.width,
+      layer: segment.layer,
+      ...(segmentIndex === segments.length - 1 &&
+      lastOriginalWire?.route_type === "wire" &&
+      lastOriginalWire.end_pcb_port_id
+        ? { end_pcb_port_id: lastOriginalWire.end_pcb_port_id }
+        : {}),
+    })
+    currentPoint = segment.end
+  }
+  return route
+}
+
+function createPlanWithSegments(
+  plan: FanoutRoutePlan,
+  segments: RoutedSegment[],
+): FanoutRoutePlan | null {
+  const route = rebuildTraceRoute(plan, segments)
+  if (!route) return null
+  const length = [...segments, ...(plan.planeEndpointSegments ?? [])].reduce(
+    (total, segment) => total + distance(segment.start, segment.end),
+    0,
+  )
+  return {
+    ...plan,
+    trace: { ...plan.trace, route },
+    segments,
+    length,
+  }
+}
+
+function pointIsOutsideDenseBounds(
+  point: Point2D,
+  bounds: Bounds,
+  margin: number,
+): boolean {
+  return (
+    point.x < bounds.minX - margin ||
+    point.x > bounds.maxX + margin ||
+    point.y < bounds.minY - margin ||
+    point.y > bounds.maxY + margin
+  )
+}
+
+function getDenseCopperBounds(bus: PreparedBus): Bounds {
+  return bus.componentObstacles.reduce<Bounds>(
+    (bounds, obstacle) => ({
+      minX: Math.min(bounds.minX, obstacle.center.x - obstacle.width / 2),
+      maxX: Math.max(bounds.maxX, obstacle.center.x + obstacle.width / 2),
+      minY: Math.min(bounds.minY, obstacle.center.y - obstacle.height / 2),
+      maxY: Math.max(bounds.maxY, obstacle.center.y + obstacle.height / 2),
+    }),
+    {
+      minX: Number.POSITIVE_INFINITY,
+      maxX: Number.NEGATIVE_INFINITY,
+      minY: Number.POSITIVE_INFINITY,
+      maxY: Number.NEGATIVE_INFINITY,
+    },
+  )
+}
+
+function hasNonAdjacentSelfIntersection(
+  segments: readonly RoutedSegment[],
+): boolean {
+  for (let firstIndex = 0; firstIndex < segments.length; firstIndex++) {
+    const first = segments[firstIndex]!
+    for (
+      let secondIndex = firstIndex + 2;
+      secondIndex < segments.length;
+      secondIndex++
+    ) {
+      const second = segments[secondIndex]!
+      if (first.layer !== second.layer) continue
+      if (
+        secondIndex === firstIndex + 2 &&
+        pointsMatch(first.end, second.start)
+      ) {
+        continue
+      }
+      if (
+        distanceSegmentToSegment(
+          first.start,
+          first.end,
+          second.start,
+          second.end,
+        ) <= EPSILON
+      ) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+function replacementCopperIsSelfClear(params: {
+  plan: FanoutRoutePlan
+  segments: readonly RoutedSegment[]
+  replacementStartIndex: number
+  replacementSegmentCount: number
+  clearance: number
+}): boolean {
+  const {
+    plan,
+    segments,
+    replacementStartIndex,
+    replacementSegmentCount,
+    clearance,
+  } = params
+  const replacementEndIndex =
+    replacementStartIndex + replacementSegmentCount - 1
+  const vias = getPlanVias(plan)
+  const getConnectedPathDistance = (
+    firstIndex: number,
+    secondIndex: number,
+  ): number => {
+    if (firstIndex === secondIndex) return 0
+    const startIndex = Math.min(firstIndex, secondIndex)
+    const endIndex = Math.max(firstIndex, secondIndex)
+    const startSegment = segments[startIndex]!
+    const endSegment = segments[endIndex]!
+    if (startSegment.layer !== endSegment.layer) {
+      return Number.POSITIVE_INFINITY
+    }
+    let currentPoint = startSegment.end
+    let pathDistance = 0
+    for (let index = startIndex + 1; index < endIndex; index++) {
+      const segment = segments[index]!
+      if (
+        segment.layer !== startSegment.layer ||
+        !pointsMatch(currentPoint, segment.start)
+      ) {
+        return Number.POSITIVE_INFINITY
+      }
+      pathDistance += distance(segment.start, segment.end)
+      currentPoint = segment.end
+    }
+    return pointsMatch(currentPoint, segments[endIndex]!.start)
+      ? pathDistance
+      : Number.POSITIVE_INFINITY
+  }
+  for (
+    let replacementIndex = replacementStartIndex;
+    replacementIndex <= replacementEndIndex;
+    replacementIndex++
+  ) {
+    const replacement = segments[replacementIndex]!
+    for (const [otherIndex, other] of segments.entries()) {
+      const requiredCenterlineClearance =
+        replacement.width / 2 + other.width / 2 + clearance
+      if (
+        getConnectedPathDistance(replacementIndex, otherIndex) <=
+        requiredCenterlineClearance + EPSILON
+      ) {
+        continue
+      }
+      if (!segmentsAreClear(replacement, other, clearance)) return false
+    }
+    for (const via of vias) {
+      if (!via.spanLayers.includes(replacement.layer)) continue
+      if (
+        pointsMatch(via.center, replacement.start) ||
+        pointsMatch(via.center, replacement.end)
+      ) {
+        continue
+      }
+      if (
+        distancePointToSegment(via.center, replacement.start, replacement.end) <
+        via.diameter / 2 + replacement.width / 2 + clearance - EPSILON
+      ) {
+        return false
+      }
+    }
+  }
+  return true
+}
+
+function pointIsInsideBounds(point: Point2D, bounds: Bounds): boolean {
+  return (
+    point.x >= bounds.minX - EPSILON &&
+    point.x <= bounds.maxX + EPSILON &&
+    point.y >= bounds.minY - EPSILON &&
+    point.y <= bounds.maxY + EPSILON
+  )
+}
+
+function addScaled(point: Point2D, vector: Point2D, scale: number): Point2D {
+  return {
+    x: point.x + vector.x * scale,
+    y: point.y + vector.y * scale,
+  }
+}
+
+function createMeanderPoints(params: {
+  segment: RoutedSegment
+  toothCount: number
+  targetAddedLength: number
+  pitch: number
+  placementFraction: number
+  normalSign: -1 | 1
+}): Point2D[] | null {
+  const {
+    segment,
+    toothCount,
+    targetAddedLength,
+    pitch,
+    placementFraction,
+    normalSign,
+  } = params
+  const dx = segment.end.x - segment.start.x
+  const dy = segment.end.y - segment.start.y
+  const segmentLength = Math.hypot(dx, dy)
+  if (segmentLength <= EPSILON) return null
+  const isAxisAligned = Math.abs(dx) <= EPSILON || Math.abs(dy) <= EPSILON
+  const isFortyFiveDegree = Math.abs(Math.abs(dx) - Math.abs(dy)) <= EPSILON
+  if (!isAxisAligned && !isFortyFiveDegree) return null
+  const tangent = { x: dx / segmentLength, y: dy / segmentLength }
+  const normal = {
+    x: -tangent.y * normalSign,
+    y: tangent.x * normalSign,
+  }
+  const chamfer = Math.min(
+    pitch / 2,
+    targetAddedLength / (8 * toothCount * (Math.SQRT2 - 1)),
+  )
+  const plateau = pitch
+  const toothSpan = chamfer * 4 + plateau
+  const toothGap = pitch
+  const occupiedLength =
+    toothCount * toothSpan + Math.max(0, toothCount - 1) * toothGap
+  const minimumLead = pitch / 4
+  if (occupiedLength + minimumLead * 2 > segmentLength + EPSILON) {
+    return null
+  }
+  const minimumAddedLengthPerTooth = 4 * chamfer * (Math.SQRT2 - 1)
+  if (targetAddedLength + EPSILON < minimumAddedLengthPerTooth * toothCount) {
+    return null
+  }
+  const verticalRun =
+    (targetAddedLength / toothCount - minimumAddedLengthPerTooth) / 2
+  const movableLead = segmentLength - occupiedLength - minimumLead * 2
+  const leadingLength =
+    minimumLead + Math.max(0, movableLead) * placementFraction
+  let cursor = addScaled(segment.start, tangent, leadingLength)
+  const points: Point2D[] = [{ ...segment.start }, { ...cursor }]
+
+  for (let toothIndex = 0; toothIndex < toothCount; toothIndex++) {
+    cursor = addScaled(addScaled(cursor, tangent, chamfer), normal, chamfer)
+    points.push(cursor)
+    cursor = addScaled(cursor, normal, verticalRun)
+    points.push(cursor)
+    cursor = addScaled(addScaled(cursor, tangent, chamfer), normal, chamfer)
+    points.push(cursor)
+    cursor = addScaled(cursor, tangent, plateau)
+    points.push(cursor)
+    cursor = addScaled(addScaled(cursor, tangent, chamfer), normal, -chamfer)
+    points.push(cursor)
+    cursor = addScaled(cursor, normal, -verticalRun)
+    points.push(cursor)
+    cursor = addScaled(addScaled(cursor, tangent, chamfer), normal, -chamfer)
+    points.push(cursor)
+    if (toothIndex < toothCount - 1) {
+      cursor = addScaled(cursor, tangent, toothGap)
+      points.push(cursor)
+    }
+  }
+  points.push({ ...segment.end })
+  return points.filter(
+    (point, index) => index === 0 || !pointsMatch(point, points[index - 1]!),
+  )
+}
+
+function createTunedPlanCandidates(params: {
+  plan: FanoutRoutePlan
+  bus: PreparedBus
+  targetAddedLength: number
+  clearance: number
+  sharedBoundary: Bounds
+}): FanoutRoutePlan[] {
+  const { plan, bus, targetAddedLength, clearance, sharedBoundary } = params
+  const candidates: FanoutRoutePlan[] = []
+  const denseCopperBounds = getDenseCopperBounds(bus)
+  const denseMargin = plan.segments[0]?.width
+    ? plan.segments[0].width / 2 + clearance
+    : clearance
+  const eligibleSegments = plan.segments
+    .map((segment, segmentIndex) => ({ segment, segmentIndex }))
+    .filter(({ segment }) => segment.layer === plan.targetLayer)
+    .toSorted(
+      (first, second) =>
+        distance(second.segment.start, second.segment.end) -
+        distance(first.segment.start, first.segment.end),
+    )
+
+  for (const { segment, segmentIndex } of eligibleSegments) {
+    const pitch = segment.width + clearance
+    const segmentLength = distance(segment.start, segment.end)
+    const maximumToothCount = Math.min(
+      12,
+      Math.max(0, Math.floor((segmentLength / pitch + 0.5) / 4)),
+    )
+    for (let toothCount = 1; toothCount <= maximumToothCount; toothCount++) {
+      for (const placementFraction of [0.5, 0, 1, 0.25, 0.75]) {
+        for (const normalSign of [1, -1] as const) {
+          const points = createMeanderPoints({
+            segment,
+            toothCount,
+            targetAddedLength,
+            pitch,
+            placementFraction,
+            normalSign,
+          })
+          if (!points) continue
+          if (
+            points.some((point) => !pointIsInsideBounds(point, sharedBoundary))
+          ) {
+            continue
+          }
+          if (
+            points
+              .slice(1, -1)
+              .some(
+                (point) =>
+                  !pointIsOutsideDenseBounds(
+                    point,
+                    denseCopperBounds,
+                    denseMargin,
+                  ),
+              )
+          ) {
+            continue
+          }
+          const replacementSegments = points.slice(1).map((end, index) => ({
+            start: points[index]!,
+            end,
+            width: segment.width,
+            layer: segment.layer,
+          }))
+          const segments = [
+            ...plan.segments.slice(0, segmentIndex),
+            ...replacementSegments,
+            ...plan.segments.slice(segmentIndex + 1),
+          ]
+          if (hasNonAdjacentSelfIntersection(segments)) continue
+          if (
+            !replacementCopperIsSelfClear({
+              plan,
+              segments,
+              replacementStartIndex: segmentIndex,
+              replacementSegmentCount: replacementSegments.length,
+              clearance,
+            })
+          ) {
+            continue
+          }
+          const candidate = createPlanWithSegments(plan, segments)
+          if (candidate) candidates.push(candidate)
+        }
+      }
+    }
+  }
+  return candidates
+}
+
+function getBusSkew(plans: readonly FanoutRoutePlan[]): number {
+  const lengths = plans.map((plan) => plan.length)
+  return Math.max(...lengths) - Math.min(...lengths)
+}
+
+/**
+ * Adds straight/45-degree meanders after the dense component escape. Matching
+ * is atomic: a constrained bus either satisfies its declared skew with the
+ * complete fanout copper still clear, or the complete assignment is rejected.
+ */
+export function matchBusPlanLengths(params: {
+  plans: readonly FanoutRoutePlan[]
+  preparedBuses: readonly PreparedBus[]
+  inputSrj: SimpleRouteJson
+  sharedBoundary: Bounds
+  clearance: number
+  allowSameNetMerges?: boolean
+}):
+  | { plans: FanoutRoutePlan[]; failedBus?: never }
+  | { plans: null; failedBus: PreparedBus } {
+  const {
+    preparedBuses,
+    inputSrj,
+    sharedBoundary,
+    clearance,
+    allowSameNetMerges = false,
+  } = params
+  let matchedPlans = [...params.plans]
+  const constrainedBuses = preparedBuses.filter(
+    (bus) => bus.maxLengthSkew !== undefined && bus.connections.length > 1,
+  )
+  if (constrainedBuses.length === 0) return { plans: matchedPlans }
+
+  for (const bus of constrainedBuses) {
+    if (bus.termination.type !== "boundary") {
+      return { plans: null, failedBus: bus }
+    }
+    const maximumIterations = bus.connections.length * 2
+    for (let iteration = 0; iteration < maximumIterations; iteration++) {
+      const busPlans = matchedPlans.filter((plan) => plan.busId === bus.busId)
+      if (busPlans.length !== bus.connections.length) {
+        return { plans: null, failedBus: bus }
+      }
+      const maxLengthSkew = bus.maxLengthSkew!
+      const skew = getBusSkew(busPlans)
+      if (skew <= maxLengthSkew + EPSILON) break
+      const shortest = busPlans.toSorted(
+        (first, second) =>
+          first.length - second.length ||
+          first.connectionName.localeCompare(second.connectionName),
+      )[0]!
+      const longestLength = Math.max(...busPlans.map((plan) => plan.length))
+      const deficit = longestLength - shortest.length
+      const minimumRequiredAddition = Math.max(
+        EPSILON,
+        deficit - maxLengthSkew + EPSILON,
+      )
+      const targetAddedLengths = [
+        minimumRequiredAddition,
+        minimumRequiredAddition + maxLengthSkew * 0.1,
+        deficit - maxLengthSkew * 0.5,
+        deficit - maxLengthSkew * 0.75,
+        deficit,
+        deficit + maxLengthSkew,
+      ]
+        .filter(
+          (value, index, values) =>
+            value > EPSILON &&
+            values.findIndex(
+              (candidate) => Math.abs(candidate - value) < EPSILON,
+            ) === index,
+        )
+        .toSorted((first, second) => first - second)
+      let acceptedPlans: FanoutRoutePlan[] | null = null
+      for (const targetAddedLength of targetAddedLengths) {
+        const candidates = createTunedPlanCandidates({
+          plan: shortest,
+          bus,
+          targetAddedLength,
+          clearance,
+          sharedBoundary: bus.sharedBoundary,
+        })
+        for (const candidate of candidates) {
+          const nextPlans = matchedPlans.map((plan) =>
+            plan === shortest ? candidate : plan,
+          )
+          const nextBusPlans = nextPlans.filter(
+            (plan) => plan.busId === bus.busId,
+          )
+          const nextSkew = getBusSkew(nextBusPlans)
+          if (nextSkew > skew + EPSILON) continue
+          if (
+            !fanoutPlansAreClear({
+              plans: nextPlans,
+              srj: inputSrj,
+              sharedBoundary,
+              clearance,
+              allowSameNetMerges,
+            })
+          ) {
+            continue
+          }
+          acceptedPlans = nextPlans
+          break
+        }
+        if (acceptedPlans) break
+      }
+      if (!acceptedPlans) return { plans: null, failedBus: bus }
+      matchedPlans = acceptedPlans
+    }
+    const matchedBusPlans = matchedPlans.filter(
+      (plan) => plan.busId === bus.busId,
+    )
+    if (getBusSkew(matchedBusPlans) > bus.maxLengthSkew! + EPSILON) {
+      return { plans: null, failedBus: bus }
+    }
+  }
+  return { plans: matchedPlans }
+}

package/lib/prepare-buses.ts

@@ -580,6 +580,19 @@ function resolveAllowedLayers(
   return [...new Set(allowedLayers)]
 }
 
+function resolveMaxLengthSkew(
+  busId: string,
+  value: number | undefined,
+): number | undefined {
+  if (value === undefined) return undefined
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" maxLengthSkew must be a finite non-negative number`,
+    )
+  }
+  return value
+}
+
 export function resolveAvailableBoundaryRegions(
   value: readonly FanoutAvailableCornerAndSideInput[] | undefined,
 ): AvailableBoundaryRegion[] | undefined {
@@ -667,6 +680,15 @@ function resolveBusSpecs(
       requestedBus.busId,
       (requestedBus as FanoutBusSpec).allowedLayers,
     )
+    const maxLengthSkew = resolveMaxLengthSkew(
+      requestedBus.busId,
+      requestedBus.maxLengthSkew,
+    )
+    if (termination.type === "plane" && maxLengthSkew !== undefined) {
+      throw new Error(
+        `FanoutSolver: plane-terminated bus "${requestedBus.busId}" cannot specify maxLengthSkew`,
+      )
+    }
     if (
       termination.type === "plane" &&
       resolvedExitFields.preferredExit !== undefined
@@ -682,6 +704,7 @@ function resolveBusSpecs(
         options.sourceComponentId,
       ...resolvedExitFields,
       ...(allowedLayers === undefined ? {} : { allowedLayers }),
+      ...(maxLengthSkew === undefined ? {} : { maxLengthSkew }),
       termination,
     })
   }
@@ -1248,6 +1271,9 @@ export function prepareFanoutBuses(
     }
     buses.push({
       busId: busSpec.busId,
+      ...(busSpec.maxLengthSkew === undefined
+        ? {}
+        : { maxLengthSkew: busSpec.maxLengthSkew }),
       direction: resolvedExit.direction,
       preferredExit: resolvedExit.preferredExit,
       ...(busSpec.exitEdge ? { exitEdge: busSpec.exitEdge } : {}),

package/lib/types.ts

@@ -250,6 +250,8 @@ export interface FanoutValidationIssue {
     | "different-net-trace-clearance"
     | "different-net-trace-via-clearance"
     | "different-net-via-clearance"
+    | "plan-length-mismatch"
+    | "bus-length-skew"
   message: string
   connectionName?: string
   otherConnectionName?: string
@@ -291,6 +293,8 @@ export interface PreparedConnection {
 
 export interface PreparedBus {
   busId: string
+  /** Maximum permitted routed copper length difference in millimeters. */
+  maxLengthSkew?: number
   direction: FanoutDirection
   preferredExit?: FanoutBorderTarget
   /** Explicit final boundary edge. Omitted for legacy direction-based exits. */

package/lib/validate-fanout-solution.ts

@@ -360,6 +360,19 @@ function validatePlanStructure(params: {
     }
   }
 
+  const measuredLength = [
+    ...plan.segments,
+    ...(plan.planeEndpointSegments ?? []),
+  ].reduce((total, segment) => total + distance(segment.start, segment.end), 0)
+  if (Math.abs(measuredLength - plan.length) > 1e-6) {
+    addIssue(
+      issues,
+      "plan-length-mismatch",
+      `Plan ${plan.connectionName} declares ${plan.length.toFixed(6)}mm but contains ${measuredLength.toFixed(6)}mm of routed copper`,
+      plan,
+    )
+  }
+
   const traceSegments = extractTraceSegments({
     trace: plan.trace,
     plan,
@@ -921,6 +934,21 @@ export function validateFanoutSolution(params: {
     connectionPlans.push(plan)
     plansByConnection.set(plan.connectionName, connectionPlans)
   }
+  for (const bus of preparedBuses) {
+    if (bus.maxLengthSkew === undefined) continue
+    const busPlans = plans.filter((plan) => plan.busId === bus.busId)
+    if (busPlans.length < 2) continue
+    const lengths = busPlans.map((plan) => plan.length)
+    const skew = Math.max(...lengths) - Math.min(...lengths)
+    if (skew > bus.maxLengthSkew + 1e-6) {
+      addIssue(
+        issues,
+        "bus-length-skew",
+        `Bus ${bus.busId} has ${skew.toFixed(6)}mm routed-length skew; ${bus.maxLengthSkew.toFixed(6)}mm is allowed`,
+        busPlans[0],
+      )
+    }
+  }
 
   for (const connection of inputSrj.connections) {
     const connectionPlans = plansByConnection.get(connection.name) ?? []

package/package.json

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