@tokenbuddy/tokenbuddy 1.0.35 → 1.0.37

package/src/seller-metadata-cache.ts

@@ -1,91 +0,0 @@
-import type { RegistrySeller } from "./seller-catalog.js";
-import { fetchSellerManifest } from "./seller-catalog.js";
-import type { SellerRouteMetadata } from "./seller-route-planner.js";
-
-/**
- * `SellerMetadataCache` 构造选项。
- */
-export interface SellerMetadataCacheOptions {
-  /** 缓存条目有效期（毫秒），默认 10 分钟 */
-  ttlMs?: number;
-  /** 时间源，默认 `Date.now`；测试可注入受控时间 */
-  now?: () => number;
-}
-
-export const DEFAULT_SELLER_METADATA_TTL_MS = 10 * 60 * 1000;
-
-/**
- * seller 路由元数据缓存（`/manifest` 拉取结果）。
- * 内部按 seller id 索引、按 TTL 过期；并发刷新合并到同一 `inFlight` Promise，避免重复打 seller。
- */
-export class SellerMetadataCache {
-  private readonly ttlMs: number;
-  private readonly now: () => number;
-  private readonly entries = new Map<string, SellerRouteMetadata>();
-  private readonly inFlight = new Map<string, Promise<void>>();
-
-  constructor(options: SellerMetadataCacheOptions = {}) {
-    this.ttlMs = options.ttlMs ?? DEFAULT_SELLER_METADATA_TTL_MS;
-    this.now = options.now ?? Date.now;
-  }
-
-  snapshot(): SellerRouteMetadata[] {
-    return Array.from(this.entries.values());
-  }
-
-  refreshIfStale(sellers: RegistrySeller[]): Promise<void> {
-    const refreshes = sellers
-      .filter((seller) => this.shouldRefresh(seller.id))
-      .map((seller) => this.refreshSeller(seller));
-    return Promise.all(refreshes).then(() => undefined);
-  }
-
-  private shouldRefresh(sellerId: string): boolean {
-    const existing = this.entries.get(sellerId);
-    if (!existing) {
-      return true;
-    }
-    return this.now() - (existing.lastRefreshAt ?? 0) >= this.ttlMs;
-  }
-
-  private refreshSeller(seller: RegistrySeller): Promise<void> {
-    const existing = this.inFlight.get(seller.id);
-    if (existing) {
-      return existing;
-    }
-    const refresh = this.fetchAndStore(seller).finally(() => {
-      this.inFlight.delete(seller.id);
-    });
-    this.inFlight.set(seller.id, refresh);
-    return refresh;
-  }
-
-  private async fetchAndStore(seller: RegistrySeller): Promise<void> {
-    const refreshedAt = this.now();
-    try {
-      const manifest = await fetchSellerManifest(seller);
-      this.entries.set(seller.id, {
-        sellerId: seller.id,
-        discountRatio: finiteNumber(manifest.selection?.discountRatio ?? manifest.selection?.discount_ratio),
-        manifestVersion: stringField(manifest.manifestVersion ?? manifest.manifest_version),
-        lastRefreshAt: refreshedAt,
-        source: "manifest_selection"
-      });
-    } catch (err) {
-      this.entries.set(seller.id, {
-        sellerId: seller.id,
-        lastRefreshAt: refreshedAt,
-        source: "manifest_selection",
-        errorMessage: err instanceof Error ? err.message : String(err)
-      });
-    }
-  }
-}
-
-function finiteNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
-function stringField(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}

package/src/seller-pool.ts

@@ -1,557 +0,0 @@
-import { createModuleLogger } from "@tokenbuddy/logging";
-import type { RegistrySeller } from "./seller-catalog.js";
-import type { ModelIndex } from "./model-index.js";
-import type { PrewarmCache, PrewarmCandidate, PrewarmEntry } from "./prewarm-cache.js";
-import type { CreditTracker } from "./credit-tracker.js";
-
-const logger = createModuleLogger("tb-proxyd:seller-pool");
-
-/**
- * seller 级熔断器状态。
- * - `closed`：正常挑选
- * - `open`：被踢出候选，等待 `openStateMs` 后降级到 `half_open`
- * - `half_open`：放行一次试探，成功则回 `closed`
- */
-export type CircuitState = "closed" | "half_open" | "open";
-
-/**
- * 路由失败归一化后的错误分类。控制器据此决定切流 / 重试 / 计入 wasted。
- * 与 `SellerPool.recordFailure` 的入参对齐。
- */
-export type FailureKind =
-  | "hard_4xx"           // 400/404/422 — the seller is wrong for this request
-  | "auth_invalid"       // 401/403 token invalid
-  | "insufficient_funds" // 402
-  | "busy_capacity"      // 429 busy_capacity — seller is temporarily full
-  | "purchase_failed"    // purchase/create or purchase/complete failed
-  | "soft_5xx"           // 429/5xx/timeout/network
-  | "deadline"           // buyer deadline exceeded
-  | "stream_aborted"     // upstream stream broken after first chunk
-  | "no_compatible";     // pool had no candidates for the request
-
-/**
- * 池里每个 seller 的运行时视图：registry 描述 + 熔断状态 + 健康画像。
- * 由 `SellerPool.sync()` 从 prewarm cache 重建；写路径（recordSuccess/recordFailure）会原地更新。
- */
-export interface PoolEntry {
-  /** seller 全局 ID */
-  sellerId: string;
-  /** seller URL（去尾部斜杠） */
-  url: string;
-  /** registry 原始描述（用于 planSellerRouteSet 等下游） */
-  registrySeller: RegistrySeller;
-  /** 当前熔断状态 */
-  circuit: CircuitState;
-  /** 连续失败次数（达到 `failureThreshold` 立即 open） */
-  consecutiveFailures: number;
-  /** 滑动窗口内失败时间戳（毫秒），长度受 `windowMs` 约束 */
-  recentFailures: number[];   // timestamps (ms) for sliding window
-  /** 最近一次成功的 unix 毫秒时间戳；0 表示尚无成功 */
-  lastSuccessAt: number;
-  /** 最近一次失败的 unix 毫秒时间戳；0 表示尚无失败 */
-  lastFailAt: number;
-  /** 最近一次被 probe 的 unix 毫秒时间戳（即 cache.warmedAt） */
-  lastProbeAt: number;
-  // Source-of-truth prewarm state; the pool keeps a copy so the hot path
-  // can answer health questions without touching the cache map on every
-  // request.
-  /** 综合健康分 0-100，热路径排序的主键 */
-  healthScore: number;
-  /** 平均延迟（毫秒） */
-  avgLatencyMs: number;
-  /** health probe 延迟（毫秒），可选 */
-  healthProbeLatencyMs?: number;
-  /** TTFT（毫秒），可选 */
-  ttftMs?: number;
-  /** 平均推理延迟（毫秒），可选 */
-  avgInferenceMs?: number;
-  /** 最近 10 分钟窗口内的平均输出吞吐（tokens/s），可选 */
-  avgTokensPerSecond?: number;
-  /** 最近一次 runtime speed 指标观测时间；用于避免旧 prewarm 覆盖 live inference 指标 */
-  runtimeMetricsObservedAt?: number;
-  /** 上游状态，可选 */
-  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
-  /** 上游错误类名，可选 */
-  upstreamErrorClass?: string;
-  /** 临时容量避让截止时间；大于当前时间时不参与路由 */
-  capacityBlockedUntil?: number;
-}
-
-export interface SellerRuntimeMetricsUpdate {
-  /** TTFT（毫秒），可选 */
-  ttftMs?: number;
-  /** 平均推理延迟（毫秒），可选 */
-  avgInferenceMs?: number;
-  /** 输出吞吐（tokens/s），可选 */
-  avgTokensPerSecond?: number;
-}
-
-/**
- * `SellerPool.pick()` 的入参：标识一次路由请求 + 可选的时间/数量约束。
- */
-export interface PickOptions {
-  /** 目标模型 ID（已归一化或未归一化都可，pool 内部会归一化） */
-  modelId: string;
-  /** 目标协议 */
-  protocol: string;
-  /** 目标支付方式 */
-  paymentMethod: string;
-  /** 最多返回几个候选，默认 4 */
-  limit?: number;
-  /** 覆盖时钟（测试用） */
-  now?: number;
-}
-
-/**
- * `SellerPool.pick()` 的返回：候选列表 + 决策原因 + 底层 model index 解析结果。
- * `reason` 用于日志和 doctor 区分"无缓存""有缓存但全 open""正常"等情况。
- */
-export interface PickResult {
-  /** 已按 healthScore 排序的候选（不含 open 电路的 seller） */
-  candidates: Array<{ entry: PoolEntry; registrySeller: RegistrySeller }>;
-  /** 决策原因，例：`prewarm_cache`、`prewarm_cache_empty`、`no_prewarm_candidates` */
-  reason: string;
-  /** 底层 `ModelIndex.resolve()` 的结果（保留给上游做诊断） */
-  resolved: ModelIndexResolution;
-}
-
-/**
- * `SellerPool` 视角的 model-index 解析快照，与 `model-index.ts` 里的同名类型语义一致；
- * 在 pick 路径上做轻量拷贝，避免循环依赖和暴露 `sellers` vs `candidates` 命名差异。
- */
-export interface ModelIndexResolution {
-  /** 解析时使用的模型 ID（可能未归一化） */
-  modelId: string;
-  /** 索引里是否至少有一个 seller 命中 */
-  matched: boolean;
-  /** 命中的 seller 列表（按 default + 声明顺序） */
-  candidates: RegistrySeller[];
-  /** 当前索引里 `models` 字段缺失的 seller 数（诊断用） */
-  missingModelsFlag: number;
-}
-
-/**
- * 构造 `SellerPool` 所需的依赖与可调参数。默认值见 `DEFAULTS`：
- * 失败 3 次 open、滑动窗口 60s、失败率阈值 0.5、open 态 30s。
- */
-export interface SellerPoolOptions {
-  /** 共享的 model index */
-  modelIndex: ModelIndex;
-  /** 共享的 prewarm cache（pool 的真相源） */
-  cache: PrewarmCache;
-  /** 共享的 credit tracker，wasted / auto-purchase 决策都依赖 */
-  creditTracker: CreditTracker;
-  // Circuit breaker thresholds (v1.2 §13).
-  /** 连续失败次数阈值，到达后立即 open，默认 3 */
-  failureThreshold?: number;     // default 3
-  /** 滑动窗口长度（毫秒），默认 60000 */
-  windowMs?: number;              // default 60_000 (1m sliding window)
-  /** 滑动窗口内失败率阈值（次/秒），默认 0.5 */
-  windowFailureRate?: number;     // default 0.5
-  /** open 态保持时间（毫秒），过期后降级 half_open，默认 30000 */
-  openStateMs?: number;           // default 30_000
-  /** `busy_capacity` 的短期避让时间，默认 2000ms */
-  capacityBlockMs?: number;
-  /** 注入时钟（测试用），默认 `Date.now` */
-  now?: () => number;
-  // PoolEntry -> CircuitState transition hooks for tests.
-  /** 测试钩子：在 sync 后对 entry 列表做额外处理 */
-  applyRegistry?: (entries: PoolEntry[], registry: RegistrySeller[]) => PoolEntry[];
-}
-
-const DEFAULTS = {
-  failureThreshold: 3,
-  windowMs: 60_000,
-  windowFailureRate: 0.5,
-  openStateMs: 30_000,
-  capacityBlockMs: 2_000
-};
-
-/**
- * v2 SellerPool: combines `ModelIndex` (registry index), `PrewarmCache`
- * (probe results), and `CreditTracker` (balance protection) into a single
- * source of truth used by the route-failover controller. The pool is
- * process-local and rebuilds its entry list from the cache whenever the
- * cache mutates; entries not yet present in the cache are not in the pool.
- */
-export class SellerPool {
-  private readonly modelIndex: ModelIndex;
-  private readonly cache: PrewarmCache;
-  private readonly creditTracker: CreditTracker;
-  private readonly failureThreshold: number;
-  private readonly windowMs: number;
-  private readonly windowFailureRate: number;
-  private readonly openStateMs: number;
-  private readonly capacityBlockMs: number;
-  private readonly now: () => number;
-
-  private entries = new Map<string, PoolEntry>();
-
-  constructor(options: SellerPoolOptions) {
-    this.modelIndex = options.modelIndex;
-    this.cache = options.cache;
-    this.creditTracker = options.creditTracker;
-    this.failureThreshold = options.failureThreshold ?? DEFAULTS.failureThreshold;
-    this.windowMs = options.windowMs ?? DEFAULTS.windowMs;
-    this.windowFailureRate = options.windowFailureRate ?? DEFAULTS.windowFailureRate;
-    this.openStateMs = options.openStateMs ?? DEFAULTS.openStateMs;
-    this.capacityBlockMs = options.capacityBlockMs ?? DEFAULTS.capacityBlockMs;
-    this.now = options.now ?? Date.now;
-  }
-
-  /**
-   * Rebuild entries from the current prewarm cache. Called by
-   * `route-failover` whenever the cache is mutated (commit, invalidate,
-   * etc.) so the pool always reflects the latest probe results.
-   */
-  sync(): number {
-    const fresh = new Map<string, PoolEntry>(this.entries);
-    for (const entry of this.cache.snapshot()) {
-      for (const candidate of entry.candidates) {
-        const registry = this.modelIndex.getSeller(candidate.sellerId);
-        if (!registry) {
-          // Seller disappeared from the registry since the probe; skip.
-          continue;
-        }
-        const previous = this.entries.get(candidate.sellerId);
-        fresh.set(candidate.sellerId, {
-          sellerId: candidate.sellerId,
-          url: candidate.url,
-          registrySeller: registry,
-          circuit: previous?.circuit ?? "closed",
-          consecutiveFailures: previous?.consecutiveFailures ?? 0,
-          recentFailures: previous?.recentFailures ?? [],
-          lastSuccessAt: candidate.lastSuccessAt || previous?.lastSuccessAt || 0,
-          lastFailAt: candidate.lastFailAt || previous?.lastFailAt || 0,
-          lastProbeAt: entry.warmedAt,
-          healthScore: candidate.healthScore,
-          avgLatencyMs: candidate.avgLatencyMs,
-          healthProbeLatencyMs: candidate.healthProbeLatencyMs,
-          ttftMs: preferRuntimeMetric(candidate.ttftMs, candidate.lastSuccessAt, previous?.ttftMs, previous?.runtimeMetricsObservedAt),
-          avgInferenceMs: preferRuntimeMetric(candidate.avgInferenceMs, candidate.lastSuccessAt, previous?.avgInferenceMs, previous?.runtimeMetricsObservedAt),
-          avgTokensPerSecond: preferRuntimeMetric(candidate.avgTokensPerSecond, candidate.lastSuccessAt, previous?.avgTokensPerSecond, previous?.runtimeMetricsObservedAt),
-          runtimeMetricsObservedAt: Math.max(previous?.runtimeMetricsObservedAt ?? 0, candidate.lastSuccessAt || 0) || undefined,
-          upstreamStatus: candidate.upstreamStatus,
-          upstreamErrorClass: candidate.upstreamErrorClass,
-          capacityBlockedUntil: candidate.capacityBlockedUntil ?? previous?.capacityBlockedUntil
-        });
-      }
-    }
-    for (const sellerId of fresh.keys()) {
-      if (!this.modelIndex.getSeller(sellerId)) {
-        fresh.delete(sellerId);
-      }
-    }
-    this.entries = fresh;
-    return this.entries.size;
-  }
-
-  /**
-   * Ensure registry-fallback candidates also have runtime state. A seller
-   * may be selected before prewarm has produced a cache entry; failures
-   * from that first live request still need to affect the next route plan.
-   */
-  ensureRegistrySellers(sellers: RegistrySeller[], now: number = this.now()): void {
-    for (const seller of sellers) {
-      const previous = this.entries.get(seller.id);
-      if (previous) {
-        this.entries.set(seller.id, {
-          ...previous,
-          registrySeller: seller,
-          url: seller.url.replace(/\/+$/, "")
-        });
-        continue;
-      }
-      this.entries.set(seller.id, {
-        sellerId: seller.id,
-        url: seller.url.replace(/\/+$/, ""),
-        registrySeller: seller,
-        circuit: "closed",
-        consecutiveFailures: 0,
-        recentFailures: [],
-        lastSuccessAt: 0,
-        lastFailAt: 0,
-        lastProbeAt: now,
-        healthScore: 60,
-        avgLatencyMs: 0
-      });
-    }
-  }
-
-  /**
-   * Pick up to `limit` candidates for a (model, protocol, payment) triple.
-   * Sellers in the `open` circuit are skipped unless their open state has
-   * expired (they are flipped to `half_open` and included). Candidates are
-   * sorted by health score (descending) so the strongest seller goes first.
-   */
-  pick(options: PickOptions): PickResult {
-    const now = options.now ?? this.now();
-    const limit = options.limit ?? 4;
-    const freshness = this.cache.freshness(options.modelId, options.protocol, options.paymentMethod);
-    const resolved = this.modelIndex.resolve(options.modelId, {
-      protocol: options.protocol,
-      paymentMethod: options.paymentMethod
-    });
-
-    if (freshness.entry && freshness.entry.candidates.length === 0) {
-      return {
-        candidates: [],
-        reason: "prewarm_cache_empty",
-        resolved: asResolution(resolved)
-      };
-    }
-
-    const candidates = (freshness.entry?.candidates ?? [])
-      .map((candidate) => {
-        const entry = this.entries.get(candidate.sellerId);
-        if (!entry) {
-          return null;
-        }
-        return { entry, registrySeller: entry.registrySeller, candidate };
-      })
-      .filter((row): row is { entry: PoolEntry; registrySeller: RegistrySeller; candidate: PrewarmCandidate } => row !== null)
-      .map((row) => {
-        const entry = this.maybeRecycleFromOpen(row.entry, now);
-        return { entry, registrySeller: row.registrySeller };
-      })
-      .filter((row) => row.entry.circuit !== "open")
-      .filter((row) => !isCapacityBlocked(row.entry, now))
-      .sort((a, b) => b.entry.healthScore - a.entry.healthScore)
-      .slice(0, limit);
-
-    return {
-      candidates,
-      reason: candidates.length > 0 ? "prewarm_cache" : "no_prewarm_candidates",
-      resolved: asResolution(resolved)
-    };
-  }
-
-  /**
-   * Record a successful inference against `sellerId`. The circuit closes
-   * (if it was half-open) and the credit tracker observes the latest
-   * balance via `recordSpend`.
-   */
-  recordSuccess(sellerId: string, balanceMicros: number, now: number = this.now()): PoolEntry | undefined {
-    const entry = this.entries.get(sellerId);
-    if (!entry) {
-      return undefined;
-    }
-    const next: PoolEntry = {
-      ...entry,
-      circuit: "closed",
-      consecutiveFailures: 0,
-      recentFailures: [],
-      lastSuccessAt: now,
-      healthScore: Math.min(100, Math.max(entry.healthScore, 60)),
-      capacityBlockedUntil: undefined
-    };
-    this.entries.set(sellerId, next);
-    this.creditTracker.recordSpend(sellerId, balanceMicros);
-    logger.info("pool.success.recorded", "seller pool entry marked successful", {
-      sellerId,
-      balanceMicros,
-      healthScore: next.healthScore
-    });
-    return next;
-  }
-
-  recordRuntimeMetrics(
-    sellerId: string,
-    metrics: SellerRuntimeMetricsUpdate,
-    now: number = this.now()
-  ): PoolEntry | undefined {
-    const entry = this.entries.get(sellerId);
-    if (!entry) {
-      return undefined;
-    }
-    const ttftMs = finiteNonNegative(metrics.ttftMs);
-    const avgInferenceMs = finiteNonNegative(metrics.avgInferenceMs);
-    const avgTokensPerSecond = finiteNonNegative(metrics.avgTokensPerSecond);
-    const next: PoolEntry = {
-      ...entry,
-      lastSuccessAt: now,
-      healthScore: Math.min(100, Math.max(entry.healthScore, 60)),
-      avgLatencyMs: avgInferenceMs ?? entry.avgLatencyMs,
-      ttftMs: ttftMs ?? entry.ttftMs,
-      avgInferenceMs: avgInferenceMs ?? entry.avgInferenceMs,
-      avgTokensPerSecond: avgTokensPerSecond ?? entry.avgTokensPerSecond,
-      runtimeMetricsObservedAt: Math.max(entry.runtimeMetricsObservedAt ?? 0, now)
-    };
-    this.entries.set(sellerId, next);
-    logger.info("pool.runtime_metrics.recorded", "seller pool runtime metrics updated", {
-      sellerId,
-      ttftMs: next.ttftMs,
-      avgInferenceMs: next.avgInferenceMs,
-      avgTokensPerSecond: next.avgTokensPerSecond
-    });
-    return next;
-  }
-
-  /**
-   * Record a failure against `sellerId`. Returns the new PoolEntry. The
-   * caller (route-failover) uses the returned `entry.circuit` and the
-   * entry's `lastFailAt` to decide whether to fail over, retry, or stop.
-   * On a non-recoverable failure (`hard_4xx`, `auth_invalid`,
-   * `insufficient_funds`) the credit is also transferred to the wasted
-   * bucket so the wasted-micros counter stays accurate.
-   */
-  recordFailure(
-    sellerId: string,
-    kind: FailureKind,
-    options: { transferLeftover?: boolean; reason?: string; now?: number } = {}
-  ): PoolEntry | undefined {
-    const entry = this.entries.get(sellerId);
-    if (!entry) {
-      return undefined;
-    }
-    const now = options.now ?? this.now();
-    const isBusyCapacity = kind === "busy_capacity";
-    const recentFailures = (
-      isBusyCapacity ? entry.recentFailures : [...entry.recentFailures, now]
-    ).filter((ts) => ts >= now - this.windowMs);
-    const consecutiveFailures = isBusyCapacity ? entry.consecutiveFailures : entry.consecutiveFailures + 1;
-    const failureRate = recentFailures.length / Math.max(1, this.windowMs / 1000);
-    const overThreshold = consecutiveFailures >= this.failureThreshold;
-    const overRate = failureRate >= this.windowFailureRate;
-    const isHard = kind === "hard_4xx" || kind === "auth_invalid" || kind === "no_compatible";
-    const circuit: CircuitState = isHard || overThreshold || overRate ? "open" : entry.circuit;
-    const next: PoolEntry = {
-      ...entry,
-      circuit,
-      consecutiveFailures,
-      recentFailures,
-      lastFailAt: now,
-      capacityBlockedUntil: isBusyCapacity ? now + this.capacityBlockMs : entry.capacityBlockedUntil
-    };
-    this.entries.set(sellerId, next);
-    if (options.transferLeftover || isHard) {
-      this.creditTracker.transferLeftoverToWasted(sellerId, options.reason ?? kind);
-    }
-    if (circuit === "open") {
-      logger.warn("pool.circuit_opened", "seller pool entry transitioned to circuit_open", {
-        sellerId,
-        kind,
-        consecutiveFailures,
-        recentFailureRate: failureRate,
-        threshold: this.failureThreshold
-      });
-    } else if (isBusyCapacity) {
-      logger.warn("pool.capacity_blocked", "seller pool entry temporarily blocked by busy capacity", {
-        sellerId,
-        capacityBlockMs: this.capacityBlockMs,
-        blockedUntil: next.capacityBlockedUntil
-      });
-    }
-    return next;
-  }
-
-  /**
-   * Expose a per-seller credit / circuit snapshot to the route-failover.
-   * Used to decide whether a soft failure should retry on the same seller
-   * (刚买窗口保护) or fail over immediately.
-   */
-  inspect(sellerId: string): { entry?: PoolEntry; freshPurchase: boolean; autoPurchaseAvailable: boolean } {
-    const entry = this.entries.get(sellerId);
-    const freshPurchase = this.creditTracker.isInFreshPurchaseWindow(sellerId, this.now());
-    const autoPurchaseAvailable = this.creditTracker.canAutoPurchase(this.now());
-    return { entry, freshPurchase, autoPurchaseAvailable };
-  }
-
-  /**
-   * Recycle expired open circuits before route planning paths that consume
-   * `snapshot()` directly. This keeps the `open -> half_open` recovery path
-   * active even when the newer route planner is used instead of `pick()`.
-   */
-  recycleOpenCircuits(now: number = this.now()): number {
-    let recycled = 0;
-    for (const entry of this.entries.values()) {
-      if (entry.circuit !== "open") {
-        continue;
-      }
-      const next = this.maybeRecycleFromOpen(entry, now);
-      if (next.circuit === "half_open") {
-        recycled += 1;
-      }
-    }
-    return recycled;
-  }
-
-  /**
-   * Manually mark an entry as `open`. Used by the registry loop when a
-   * seller is removed from the registry: the entry lingers for a grace
-   * period but is unreachable, so opening the circuit prevents any
-   * further selection.
-   */
-  markOpen(sellerId: string, reason: string, now: number = this.now()): void {
-    const entry = this.entries.get(sellerId);
-    if (!entry) {
-      return;
-    }
-    this.entries.set(sellerId, { ...entry, circuit: "open", lastFailAt: now });
-    logger.warn("pool.circuit_force_opened", "seller pool entry forced to circuit_open", {
-      sellerId,
-      reason
-    });
-  }
-
-  /**
-   * List all known pool entries. Used by `tb doctor` and tests.
-   */
-  snapshot(): PoolEntry[] {
-    return Array.from(this.entries.values()).map((entry) => ({ ...entry, recentFailures: [...entry.recentFailures] }));
-  }
-
-  size(): number {
-    return this.entries.size;
-  }
-
-  private maybeRecycleFromOpen(entry: PoolEntry, now: number): PoolEntry {
-    if (entry.circuit !== "open") {
-      return entry;
-    }
-    if (now - entry.lastFailAt < this.openStateMs) {
-      return entry;
-    }
-    const recycled: PoolEntry = { ...entry, circuit: "half_open" };
-    this.entries.set(entry.sellerId, recycled);
-    logger.info("pool.circuit_half_opened", "seller pool entry recycled to half_open", {
-      sellerId: entry.sellerId,
-      openStateMs: this.openStateMs
-    });
-    return recycled;
-  }
-}
-
-function finiteNonNegative(value: number | undefined): number | undefined {
-  return Number.isFinite(value) ? Math.max(0, value as number) : undefined;
-}
-
-function preferRuntimeMetric(
-  prewarmValue: number | undefined,
-  prewarmObservedAt: number | undefined,
-  previousValue: number | undefined,
-  previousObservedAt: number | undefined
-): number | undefined {
-  if (prewarmValue === undefined) {
-    return previousValue;
-  }
-  if (previousValue !== undefined && (previousObservedAt ?? 0) > (prewarmObservedAt ?? 0)) {
-    return previousValue;
-  }
-  return prewarmValue;
-}
-
-function isCapacityBlocked(entry: PoolEntry, now: number): boolean {
-  return Number.isFinite(entry.capacityBlockedUntil) && (entry.capacityBlockedUntil as number) > now;
-}
-
-function asResolution(resolved: { modelId: string; matched: boolean; sellers: RegistrySeller[]; missingModelsFlag: number }): ModelIndexResolution {
-  return {
-    modelId: resolved.modelId,
-    matched: resolved.matched,
-    candidates: resolved.sellers,
-    missingModelsFlag: resolved.missingModelsFlag
-  };
-}
-
-export type { PrewarmEntry };