cartethyia 2.7.0 → 2.7.1

package/src/transport/dispatch/empty-stream.ts

@@ -1,217 +1,224 @@
-/**
- * Empty-stream replay + pre-start failover.
- *
- * When a provider returns HTTP 200 but the response body decodes to zero
- * meaningful events, the request is replayed byte-identical (same headers,
- * same body) up to `maxEmptyReplays` times with exponential backoff. If all
- * replays on one endpoint fail, the helper advances to the next endpoint in
- * the caller-supplied ordered list.
- *
- * The helper is transport-layer: it owns fetch, watchdog, backoff, and
- * endpoint rotation. The caller owns SSE decoding via the `DrainStream`
- * callback and supplies materialized headers + serialized body so replays
- * are byte-identical.
- *
- * Design: the replay count, backoff, and the ordered endpoint list are the
- * caller's contract; this helper owns fetch, watchdog, and rotation so a
- * provider that answers 200 with no events is retried on the next endpoint
- * rather than surfacing an empty body to the client.
- */
-import { GatewayError } from "../../protocol/gateway-error";
-import {
-  fallbackRetryDelayMs,
-  MIN_RETRY_BUDGET_MS,
-  sleep as abortableSleep,
-} from "../failure-policy";
-
-// ─── Public types ──────────────────────────────────────────────────────────
-
-/** What the caller's drain observed. Counts only dispatched data events:
- *  comments/keepalives, `[DONE]`, and whitespace-only data are excluded. */
-export interface StreamTally {
-  readonly dataEvents: number;
-  readonly meaningful: boolean;
-  readonly thoughtOnly: boolean;
-}
-
-/** Drain one response body to a tally. Provider-supplied; uses decodeSseEvents. */
-export type DrainStream = (response: Response, signal: AbortSignal) => Promise<StreamTally>;
-
-/** Bound fetch for one endpoint. Receives materialized headers + serialized body. */
-export type EmptyStreamFetch = (
-  url: string,
-  init: { headers: Record<string, string>; body: string; signal: AbortSignal },
-) => Promise<Response>;
-
-/**
- * Retry-delay policy.
- *
- * Delays come from `fallbackRetryDelayMs` (capped exponential with full
- * jitter), whose base and cap are operator-tunable. There is deliberately no
- * per-caller base: the local formula this replaced was uncapped and
- * unjittered, so a provider returning 200-with-no-events could drive an
- * unbounded wait, and concurrent clients could resynchronize their retries.
- */
-export interface EmptyStreamPolicy {
-  readonly maxEmptyReplays?: number;
-  readonly firstEventTimeoutMs?: number;
-  readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
-}
-
-export interface EmptyStreamResult {
-  readonly response: Response;
-  readonly tally: StreamTally;
-  readonly endpoint: string;
-  readonly replaysUsed: number;
-}
-
-// ─── Defaults ──────────────────────────────────────────────────────────────
-
-const DEFAULT_MAX_REPLAYS = 2;
-const DEFAULT_FIRST_EVENT_TIMEOUT_MS = 200_000; // 200s, matches CARTETHYIA_STREAM_FIRST_CHUNK_TIMEOUT_MS default
-
-
-// ─── Helpers ───────────────────────────────────────────────────────────────
-
-/** Pure predicate: zero data events, or data events with nothing meaningful. */
-export function isEmptyStream(tally: StreamTally): boolean {
-  return tally.dataEvents === 0 || (!tally.meaningful && !tally.thoughtOnly);
-}
-
-
-
-// ─── Main function ─────────────────────────────────────────────────────────
-
-/**
- * Replays the byte-identical request while responses drain empty,
- * failing over across ordered endpoints pre-start.
- *
- * Throws GatewayError (platform_unavailable, 502, upstream) on exhaustion,
- * GatewayError (transport_closed, 499) on abort.
- */
-export async function fetchWithEmptyStreamRecovery(
-  endpoints: readonly string[],
-  request: { headers: Record<string, string>; body: string },
-  deps: {
-    fetch: EmptyStreamFetch;
-    drain: DrainStream;
-    signal: AbortSignal;
-    deadlineMs: number;
-    policy?: EmptyStreamPolicy;
-  },
-): Promise<EmptyStreamResult> {
-  const maxReplays = deps.policy?.maxEmptyReplays ?? DEFAULT_MAX_REPLAYS;
-  const firstEventTimeout = deps.policy?.firstEventTimeoutMs ?? DEFAULT_FIRST_EVENT_TIMEOUT_MS;
-  const sleep = deps.policy?.sleep ?? abortableSleep;
-
-  if (endpoints.length === 0) {
-    throw new GatewayError("platform_unavailable", 502, "No endpoints available", {}, "upstream");
-  }
-
-  for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
-    const endpoint = endpoints[endpointIndex]!;
-    const isLastEndpoint = endpointIndex === endpoints.length - 1;
-    const replaysAllowed = isLastEndpoint ? maxReplays : maxReplays;
-
-    for (let replay = 0; replay <= replaysAllowed; replay++) {
-      // Check abort before each fetch
-      if (deps.signal.aborted) {
-        throw new GatewayError("transport_closed", 499, "Aborted");
-      }
-
-      // Check deadline floor
-      const now = Date.now();
-      const remaining = deps.deadlineMs - now;
-      if (remaining < MIN_RETRY_BUDGET_MS) {
-        throw new GatewayError(
-          "platform_unavailable",
-          502,
-          "Deadline exhausted before empty-stream replay",
-          {},
-          "upstream",
-        );
-      }
-
-      const fetchTimeout = Math.min(firstEventTimeout, remaining);
-
-      let response: Response;
-      try {
-        response = await fetchWithTimeout(deps.fetch, endpoint, request, deps.signal, fetchTimeout);
-      } catch (error) {
-        if (error instanceof GatewayError) throw error;
-        break; // advance to next endpoint
-      }
-
-      // Drain the response
-      let tally: StreamTally;
-      try {
-        tally = await deps.drain(response, deps.signal);
-      } catch (error) {
-        if (error instanceof GatewayError) throw error;
-        break; // advance to next endpoint
-      }
-
-      // Check if empty
-      if (!isEmptyStream(tally)) {
-        // Success — return the response and tally
-        return {
-          response,
-          tally,
-          endpoint,
-          replaysUsed: replay,
-        };
-      }
-
-      // Empty — replay if we haven't exhausted this endpoint's budget
-      if (replay < replaysAllowed) {
-        const delay = fallbackRetryDelayMs(replay);
-        try {
-          await sleep(delay, deps.signal);
-        } catch (error) {
-          if (error instanceof GatewayError) throw error;
-          throw error;
-        }
-      }
-    }
-  }
-
-  // All endpoints exhausted
-  throw new GatewayError(
-    "platform_unavailable",
-    502,
-    "All endpoints returned empty streams",
-    {},
-    "upstream",
-  );
-}
-
-// ─── Internal helpers ──────────────────────────────────────────────────────
-
-async function fetchWithTimeout(
-  fetch: EmptyStreamFetch,
-  url: string,
-  request: { headers: Record<string, string>; body: string },
-  signal: AbortSignal,
-  timeoutMs: number,
-): Promise<Response> {
-  // Race the fetch against a first-event timeout
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    const timer = setTimeout(() => {
-      reject(new GatewayError("transport_closed", 499, "First event timeout", {}, "upstream"));
-    }, timeoutMs);
-    signal.addEventListener("abort", () => {
-      clearTimeout(timer);
-      reject(new GatewayError("transport_closed", 499, "Aborted"));
-    }, { once: true });
-  });
-
-  try {
-    return await Promise.race([
-      fetch(url, { headers: request.headers, body: request.body, signal }),
-      timeoutPromise,
-    ]);
-  } catch (error) {
-    if (error instanceof GatewayError) throw error;
-    throw error;
-  }
-}
+/**
+ * Empty-stream replay + pre-start failover.
+ *
+ * When a provider returns HTTP 200 but the response body decodes to zero
+ * meaningful events, the request is replayed byte-identical (same headers,
+ * same body) up to `maxEmptyReplays` times with exponential backoff. If all
+ * replays on one endpoint fail, the helper advances to the next endpoint in
+ * the caller-supplied ordered list.
+ *
+ * The helper is transport-layer: it owns fetch, watchdog, backoff, and
+ * endpoint rotation. The caller owns SSE decoding via the `DrainStream`
+ * callback and supplies materialized headers + serialized body so replays
+ * are byte-identical.
+ *
+ * Design: the replay count, backoff, and the ordered endpoint list are the
+ * caller's contract; this helper owns fetch, watchdog, and rotation so a
+ * provider that answers 200 with no events is retried on the next endpoint
+ * rather than surfacing an empty body to the client.
+ */
+import { GatewayError } from "../../protocol/gateway-error";
+import {
+  fallbackRetryDelayMs,
+  MIN_RETRY_BUDGET_MS,
+  sleep as abortableSleep,
+} from "../failure-policy";
+
+// ─── Public types ──────────────────────────────────────────────────────────
+
+/** What the caller's drain observed. Counts only dispatched data events:
+ *  comments/keepalives, `[DONE]`, and whitespace-only data are excluded. */
+export interface StreamTally {
+  readonly dataEvents: number;
+  readonly meaningful: boolean;
+  readonly thoughtOnly: boolean;
+}
+
+/** Drain one response body to a tally. Provider-supplied; uses decodeSseEvents. */
+export type DrainStream = (response: Response, signal: AbortSignal) => Promise<StreamTally>;
+
+/** Bound fetch for one endpoint. Receives materialized headers + serialized body. */
+export type EmptyStreamFetch = (
+  url: string,
+  init: { headers: Record<string, string>; body: string; signal: AbortSignal },
+) => Promise<Response>;
+
+/**
+ * Retry-delay policy.
+ *
+ * Delays come from `fallbackRetryDelayMs` (capped exponential with full
+ * jitter), whose base and cap are operator-tunable. There is deliberately no
+ * per-caller base: the local formula this replaced was uncapped and
+ * unjittered, so a provider returning 200-with-no-events could drive an
+ * unbounded wait, and concurrent clients could resynchronize their retries.
+ */
+export interface EmptyStreamPolicy {
+  readonly maxEmptyReplays?: number;
+  readonly firstEventTimeoutMs?: number;
+  readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+
+export interface EmptyStreamResult {
+  readonly response: Response;
+  readonly tally: StreamTally;
+  readonly endpoint: string;
+  readonly replaysUsed: number;
+}
+
+// ─── Defaults ──────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_REPLAYS = 2;
+const DEFAULT_FIRST_EVENT_TIMEOUT_MS = 200_000; // 200s, matches CARTETHYIA_STREAM_FIRST_CHUNK_TIMEOUT_MS default
+
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+/** Pure predicate: zero data events, or data events with nothing meaningful. */
+export function isEmptyStream(tally: StreamTally): boolean {
+  return tally.dataEvents === 0 || (!tally.meaningful && !tally.thoughtOnly);
+}
+
+
+
+// ─── Main function ─────────────────────────────────────────────────────────
+
+/**
+ * Replays the byte-identical request while responses drain empty,
+ * failing over across ordered endpoints pre-start.
+ *
+ * Throws GatewayError (platform_unavailable, 502, upstream) on exhaustion,
+ * GatewayError (deadline_exceeded, 504, upstream) when a first event never
+ * arrives within the window, and GatewayError (transport_closed, 499) on
+ * client abort.
+ */
+export async function fetchWithEmptyStreamRecovery(
+  endpoints: readonly string[],
+  request: { headers: Record<string, string>; body: string },
+  deps: {
+    fetch: EmptyStreamFetch;
+    drain: DrainStream;
+    signal: AbortSignal;
+    deadlineMs: number;
+    policy?: EmptyStreamPolicy;
+  },
+): Promise<EmptyStreamResult> {
+  const maxReplays = deps.policy?.maxEmptyReplays ?? DEFAULT_MAX_REPLAYS;
+  const firstEventTimeout = deps.policy?.firstEventTimeoutMs ?? DEFAULT_FIRST_EVENT_TIMEOUT_MS;
+  const sleep = deps.policy?.sleep ?? abortableSleep;
+
+  if (endpoints.length === 0) {
+    throw new GatewayError("platform_unavailable", 502, "No endpoints available", {}, "upstream");
+  }
+
+  for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
+    const endpoint = endpoints[endpointIndex]!;
+    const isLastEndpoint = endpointIndex === endpoints.length - 1;
+    const replaysAllowed = isLastEndpoint ? maxReplays : maxReplays;
+
+    for (let replay = 0; replay <= replaysAllowed; replay++) {
+      // Check abort before each fetch
+      if (deps.signal.aborted) {
+        throw new GatewayError("transport_closed", 499, "Aborted");
+      }
+
+      // Check deadline floor
+      const now = Date.now();
+      const remaining = deps.deadlineMs - now;
+      if (remaining < MIN_RETRY_BUDGET_MS) {
+        throw new GatewayError(
+          "platform_unavailable",
+          502,
+          "Deadline exhausted before empty-stream replay",
+          {},
+          "upstream",
+        );
+      }
+
+      const fetchTimeout = Math.min(firstEventTimeout, remaining);
+
+      let response: Response;
+      try {
+        response = await fetchWithTimeout(deps.fetch, endpoint, request, deps.signal, fetchTimeout);
+      } catch (error) {
+        if (error instanceof GatewayError) throw error;
+        break; // advance to next endpoint
+      }
+
+      // Drain the response
+      let tally: StreamTally;
+      try {
+        tally = await deps.drain(response, deps.signal);
+      } catch (error) {
+        if (error instanceof GatewayError) throw error;
+        break; // advance to next endpoint
+      }
+
+      // Check if empty
+      if (!isEmptyStream(tally)) {
+        // Success — return the response and tally
+        return {
+          response,
+          tally,
+          endpoint,
+          replaysUsed: replay,
+        };
+      }
+
+      // Empty — replay if we haven't exhausted this endpoint's budget
+      if (replay < replaysAllowed) {
+        const delay = fallbackRetryDelayMs(replay);
+        try {
+          await sleep(delay, deps.signal);
+        } catch (error) {
+          if (error instanceof GatewayError) throw error;
+          throw error;
+        }
+      }
+    }
+  }
+
+  // All endpoints exhausted
+  throw new GatewayError(
+    "platform_unavailable",
+    502,
+    "All endpoints returned empty streams",
+    {},
+    "upstream",
+  );
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+async function fetchWithTimeout(
+  fetch: EmptyStreamFetch,
+  url: string,
+  request: { headers: Record<string, string>; body: string },
+  signal: AbortSignal,
+  timeoutMs: number,
+): Promise<Response> {
+  // Race the fetch against a first-event timeout
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    const timer = setTimeout(() => {
+      // A first-event timeout is the gateway waiting on a silent upstream (e.g.
+      // a provider that holds the request in a queue), not the client leaving.
+      // It must surface as a deadline failure, never as a `transport_closed`
+      // 499 — that code is reserved for genuine client cancellations and would
+      // otherwise hide a real upstream wait behind "cancelled by client".
+      reject(new GatewayError("deadline_exceeded", 504, "First event timeout", {}, "upstream"));
+    }, timeoutMs);
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new GatewayError("transport_closed", 499, "Aborted"));
+    }, { once: true });
+  });
+
+  try {
+    return await Promise.race([
+      fetch(url, { headers: request.headers, body: request.body, signal }),
+      timeoutPromise,
+    ]);
+  } catch (error) {
+    if (error instanceof GatewayError) throw error;
+    throw error;
+  }
+}

package/src/transport/dispatch/generation.ts

@@ -21,34 +21,16 @@
 import type { ImageGenerationOutcome, ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
 import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
-import type { OAuthTokenRefresher, OAuthRefreshService } from "../../providers/authentication/oauth-refresh-service";
-import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
-import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import type { RouteSnapshotService } from "../routing/route-model";
 import type { ServiceKind } from "../../protocol/canonical-model";
 import { metrics } from "../../observability/metrics";
-import type { NetworkPoolSelector } from "../../network/pool/selector";
-import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
 import type { ProxyRequestState } from "../request/state";
-import { ProxyRequestStateStore } from "../request/state";
-import { ProxyRequestPreparer } from "../request/preparer";
-import { completeAttempt, estimatedUsage } from "./attempt-finalize";
+import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import { captureProviderRateLimit } from "./ratelimit-capture";
 
-export interface GenerationHandlerDeps {
-  readonly db: CartethyiaDatabase;
-  readonly providerAdapters: ReadonlyMap<string, ProviderAdapter>;
-  readonly resolveProviderAdapter?: (providerId: string) => Promise<ProviderAdapter | undefined>;
-  readonly proxyPreparer: ProxyRequestPreparer;
-  readonly stateStore: ProxyRequestStateStore;
-  readonly poolSelector?: NetworkPoolSelector;
-  readonly networkBindingFactory?: ValidatedNetworkBindingFactory;
-  readonly snapshotService?: RouteSnapshotService;
-  readonly telemetryBuffer?: TelemetryBatchBuffer;
-  readonly resolveOAuthRefresher?: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
-  readonly oauthRefreshService?: OAuthRefreshService;
-}
+import type { GatewayHandlerDeps } from "./handler-deps";
+
+export type GenerationHandlerDeps = GatewayHandlerDeps;
 
 /** Which surface a handler serves. Drives candidate filtering and error copy. */
 export type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGeneration">;
@@ -133,22 +115,23 @@ async function passThrough(
   captureProviderRateLimit(args.candidate.provider_id, args.candidate.provider_account_id, upstream.headers);
   await completeAttempt(state, {
     status: "completed",
-    providerId: args.candidate.provider_id,
-    ...(args.candidate.provider_account_id ? { accountId: args.candidate.provider_account_id } : {}),
-    ...(args.candidate.provider_account_label ? { accountLabel: args.candidate.provider_account_label } : {}),
-    ...(args.networkPoolId ? { networkPoolId: args.networkPoolId } : {}),
-    usage,
-    modelId: args.candidate.model_id,
-    lease: args.lease as never,
-    commitUsage: usage,
-    terminal: true,
-    tenantId: args.tenantId,
-    ingressBody: state.ingressBody,
+    ...nativeCompletionBase({
+      providerId: args.candidate.provider_id,
+      ...(args.candidate.provider_account_id ? { accountId: args.candidate.provider_account_id } : {}),
+      ...(args.candidate.provider_account_label ? { accountLabel: args.candidate.provider_account_label } : {}),
+      ...(args.networkPoolId ? { networkPoolId: args.networkPoolId } : {}),
+      usage,
+      modelId: args.candidate.model_id,
+      lease: args.lease as never,
+      commitUsage: usage,
+      tenantId: args.tenantId,
+      ingressBody: state.ingressBody,
+      providerCapture: args.providerCapture as never,
+      db: args.deps.db,
+      ...(args.deps.telemetryBuffer ? { telemetryBuffer: args.deps.telemetryBuffer } : {}),
+      ...(args.deps.snapshotService ? { snapshotService: args.deps.snapshotService } : {}),
+    }),
     responseBody: null,
-    providerCapture: args.providerCapture as never,
-    db: args.deps.db,
-    ...(args.deps.telemetryBuffer ? { telemetryBuffer: args.deps.telemetryBuffer } : {}),
-    ...(args.deps.snapshotService ? { snapshotService: args.deps.snapshotService } : {}),
   });
   metrics.proxy_requests_total.inc(1, { status: "completed" });
   return new Response(upstream.body, {
@@ -251,9 +234,7 @@ export function createNativeSurfaceHandler(
               provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
               credential_kind: "none" as const,
             };
-        const adapter = deps.resolveProviderAdapter
-          ? await deps.resolveProviderAdapter(candidate.provider_id)
-          : deps.providerAdapters.get(candidate.provider_id);
+        const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
           throw new GatewayError(
             "capability_unsupported",
@@ -292,22 +273,23 @@ export function createNativeSurfaceHandler(
           const usage = estimatedUsage(0, 0);
           await completeAttempt(state, {
             status: "completed",
-            providerId: candidate.provider_id,
-            ...(candidate.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
-            ...(candidate.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
-            ...(leases.proxySlot ? { networkPoolId: leases.proxySlot.poolId } : {}),
-            usage,
-            modelId: candidate.model_id,
-            lease: leases.lease,
-            commitUsage: usage,
-            terminal: true,
-            tenantId: prepared.authorization.tenantId,
-            ingressBody: state.ingressBody,
+            ...nativeCompletionBase({
+              providerId: candidate.provider_id,
+              ...(candidate.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
+              ...(candidate.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
+              ...(leases.proxySlot ? { networkPoolId: leases.proxySlot.poolId } : {}),
+              usage,
+              modelId: candidate.model_id,
+              lease: leases.lease,
+              commitUsage: usage,
+              tenantId: prepared.authorization.tenantId,
+              ingressBody: state.ingressBody,
+              providerCapture,
+              db: deps.db,
+              ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
+              ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
+            }),
             responseBody: payload,
-            providerCapture,
-            db: deps.db,
-            ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
-            ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
           });
           metrics.proxy_requests_total.inc(1, { status: "completed" });
           return jsonResponse(payload, 200, state.requestId);

package/src/transport/dispatch/handler-deps.ts

@@ -0,0 +1,32 @@
+/**
+ * The one dependency shape every gateway route handler takes.
+ *
+ * Proxy, generation, responses-compact, system one, web search, and token
+ * count all receive the same wiring. Before this module each handler spelled
+ * its own near-identical interface and `app.ts` spelled the same object five
+ * times — a new handler dep had to be added to five interfaces and five
+ * literals to reach the runtime. One shape means one place to grow.
+ */
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import type { ProviderAdapter } from "../../providers/provider-contracts";
+import type { OAuthRefreshService, OAuthTokenRefresher } from "../../providers/authentication/oauth-refresh-service";
+import type { NetworkPoolSelector } from "../../network/pool/selector";
+import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
+import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
+import type { ProxyRequestPreparer } from "../request/preparer";
+import type { ProxyRequestStateStore } from "../request/state";
+import type { RouteSnapshotService } from "../routing/route-model";
+
+export interface GatewayHandlerDeps {
+  readonly db: CartethyiaDatabase;
+  /** Preferred over a static map: resolves an adapter on demand and caches it. */
+  readonly resolveProviderAdapter?: (providerId: string) => Promise<ProviderAdapter | undefined>;
+  readonly proxyPreparer: ProxyRequestPreparer;
+  readonly stateStore: ProxyRequestStateStore;
+  readonly poolSelector?: NetworkPoolSelector;
+  readonly networkBindingFactory?: ValidatedNetworkBindingFactory;
+  readonly snapshotService?: RouteSnapshotService;
+  readonly telemetryBuffer?: TelemetryBatchBuffer;
+  readonly resolveOAuthRefresher?: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
+  readonly oauthRefreshService?: OAuthRefreshService;
+}

package/src/transport/dispatch/leases.ts

@@ -124,11 +124,16 @@ async function acquirePoolSlot(
     }
   }
   // Round-robin rotation rides the strategy the snapshot attached to the
-  // candidate (the pool-owning tenant scopes the cursor); absent strategy or
-  // `least_loaded` keeps the default weighted least-loaded scan.
+  // candidate (the pool-owning tenant scopes the cursor); `random` scatters
+  // each selection across eligible pools. Absent strategy or `least_loaded`
+  // keeps the default weighted least-loaded scan.
   const rotation: PoolRotation | undefined =
-    routing?.strategy === "round_robin"
-      ? { key: routing.tenantId, rotateCount: routing.rotateCount }
+    routing?.strategy === "round_robin" || routing?.strategy === "random"
+      ? {
+          key: routing.tenantId,
+          rotateCount: routing.rotateCount,
+          strategy: routing.strategy,
+        }
       : undefined;
 
   if (!poolIds?.length || !poolSelector) {