@tokenbuddy/tokenbuddy 1.0.36 → 1.0.38

package/src/credit-tracker.ts

@@ -1,295 +0,0 @@
-import { createModuleLogger } from "@tokenbuddy/logging";
-
-const logger = createModuleLogger("tb-proxyd:credit-tracker");
-
-/**
- * Default window after a successful purchase during which failover is
- * softened (see buyer-driven-fallback-design.md §17.3). 30 seconds is the
- * v1.1 starting point; v1.2 keeps the same value.
- */
-export const DEFAULT_FRESH_PURCHASE_WINDOW_MS = 30_000;
-
-/**
- * Default threshold of "still considered fresh": the current balance must
- * still cover this fraction of the last purchase amount for the entry to
- * be treated as "刚买". 0.5 means "at least half of the purchased credit is
- * still untouched".
- */
-export const DEFAULT_FRESH_PURCHASE_THRESHOLD = 0.5;
-
-/**
- * Maximum number of automatic purchases a single session may trigger per
- * minute. When the budget is exhausted, route-failover must `切` rather than
- * `重买` (see §17.5).
- */
-export const DEFAULT_PURCHASE_BUDGET_PER_MINUTE = 3;
-
-/**
- * `CreditTracker` 构造选项。
- */
-export interface CreditTrackerOptions {
-  /** "新鲜购买" 判定窗口（毫秒），默认 30s */
-  freshPurchaseWindowMs?: number;
-  /** "新鲜购买" 剩余比例阈值，默认 0.5（剩余 ≥ 50% 才算 fresh） */
-  freshPurchaseThreshold?: number;
-  /** 单 session 每分钟自动购买上限，默认 3 */
-  purchaseBudgetPerMinute?: number;
-  /** 时间源，默认 `Date.now`；测试可注入 */
-  now?: () => number;
-}
-
-interface SellerCredit {
-  sellerId: string;
-  lastPurchaseAt: number;
-  lastPurchaseAmountMicros: number;
-  currentBalanceMicros: number;
-  leftoverCreditMicros: number;
-  lastUpdatedAt: number;
-}
-
-/**
- * Tracks per-seller credit state for the buyer-driven-fallback design's
- * "balance protection" rules. The tracker is intentionally agnostic of the
- * actual seller HTTP layer: callers feed in `recordPurchase`,
- * `recordSpend`, and `transferLeftover` events as they observe them, and
- * the tracker answers "is this seller still inside its fresh-purchase
- * window?" / "may I auto-purchase again this minute?".
- *
- * The tracker is process-local: a buyer restart resets the session
- * counters. See §17.11.4 for the rationale.
- */
-/**
- * buyer-driven-fallback 设计的"余额保护"决策器。
- * 跟踪每个 seller 的余额、最近购买时间、累计浪费 micros，回答：
- * - "该 seller 是否还在 fresh-purchase window 内？"
- * - "本 session 是否还能自动购买？"
- *
- * 仅进程内状态（buyer 重启会重置 session 计数器；详见 §17.11.4）。
- */
-export class CreditTracker {
-  private readonly freshPurchaseWindowMs: number;
-  private readonly freshPurchaseThreshold: number;
-  private readonly purchaseBudgetPerMinute: number;
-  private readonly now: () => number;
-
-  private readonly entries = new Map<string, SellerCredit>();
-  private readonly purchaseTimestamps: number[] = [];
-  private totalWastedMicros = 0;
-  private wastedSinceLastDoctorRun = 0;
-
-  constructor(options: CreditTrackerOptions = {}) {
-    this.freshPurchaseWindowMs = options.freshPurchaseWindowMs ?? DEFAULT_FRESH_PURCHASE_WINDOW_MS;
-    this.freshPurchaseThreshold = options.freshPurchaseThreshold ?? DEFAULT_FRESH_PURCHASE_THRESHOLD;
-    this.purchaseBudgetPerMinute = options.purchaseBudgetPerMinute ?? DEFAULT_PURCHASE_BUDGET_PER_MINUTE;
-    this.now = options.now ?? Date.now;
-  }
-
-  /**
-   * Register a successful purchase. Updates the seller's balance, the
-   * session-wide budget window, and the "fresh purchase" timestamps. If
-   * the seller is unknown, an entry is created.
-   */
-  recordPurchase(sellerId: string, amountMicros: number, balanceMicros: number): SellerCredit {
-    if (!Number.isFinite(amountMicros) || amountMicros <= 0) {
-      throw new Error("recordPurchase requires a positive amountMicros");
-    }
-    const ts = this.now();
-    const previous = this.entries.get(sellerId);
-    const entry: SellerCredit = {
-      sellerId,
-      lastPurchaseAt: ts,
-      lastPurchaseAmountMicros: amountMicros,
-      currentBalanceMicros: Math.max(0, balanceMicros),
-      leftoverCreditMicros: previous?.leftoverCreditMicros ?? 0,
-      lastUpdatedAt: ts
-    };
-    this.entries.set(sellerId, entry);
-    this.purchaseTimestamps.push(ts);
-    this.prunePurchaseTimestamps(ts);
-    logger.info("credit.purchase.recorded", "seller credit purchase recorded", {
-      sellerId,
-      amountMicros,
-      balanceMicros: entry.currentBalanceMicros,
-      purchasesInLastMinute: this.purchaseTimestamps.length
-    });
-    return entry;
-  }
-
-  /**
-   * Update the seller's current balance after a successful inference. The
-   * amount spent is implicit (`previous - next`) so the caller does not
-   * have to track it. A non-positive `balanceMicros` is treated as 0.
-   */
-  recordSpend(sellerId: string, balanceMicros: number): SellerCredit | undefined {
-    const previous = this.entries.get(sellerId);
-    if (!previous) {
-      return undefined;
-    }
-    const next: SellerCredit = {
-      ...previous,
-      currentBalanceMicros: Math.max(0, balanceMicros),
-      lastUpdatedAt: this.now()
-    };
-    this.entries.set(sellerId, next);
-    return next;
-  }
-
-  /**
-   * Move the seller's remaining balance to the `leftoverCreditMicros`
-   * bucket. Called when failover triggers while a balance is still
-   * available. The pool's pre-warm / probe logic can later attempt to
-   * consume the leftover credit (see PR-3.1). The wasted amount is also
-   * added to the session-level counters.
-   */
-  transferLeftoverToWasted(sellerId: string, reason: string): number {
-    const previous = this.entries.get(sellerId);
-    if (!previous) {
-      return 0;
-    }
-    const wasted = previous.currentBalanceMicros;
-    if (wasted <= 0) {
-      return 0;
-    }
-    const next: SellerCredit = {
-      ...previous,
-      currentBalanceMicros: 0,
-      leftoverCreditMicros: previous.leftoverCreditMicros + wasted,
-      lastUpdatedAt: this.now()
-    };
-    this.entries.set(sellerId, next);
-    this.totalWastedMicros += wasted;
-    this.wastedSinceLastDoctorRun += wasted;
-    logger.warn("credit.leftover.wasted", "leftover credit logged as wasted on failover", {
-      sellerId,
-      wastedMicros: wasted,
-      reason,
-      totalWastedMicros: this.totalWastedMicros
-    });
-    return wasted;
-  }
-
-  /**
-   * Consume leftover credit when the seller recovers and a probe
-   * successfully burns it down. Returns the amount actually consumed.
-   */
-  consumeLeftover(sellerId: string, amountMicros: number): number {
-    const previous = this.entries.get(sellerId);
-    if (!previous || previous.leftoverCreditMicros <= 0) {
-      return 0;
-    }
-    const consume = Math.max(0, Math.min(amountMicros, previous.leftoverCreditMicros));
-    if (consume <= 0) {
-      return 0;
-    }
-    const next: SellerCredit = {
-      ...previous,
-      leftoverCreditMicros: previous.leftoverCreditMicros - consume,
-      lastUpdatedAt: this.now()
-    };
-    this.entries.set(sellerId, next);
-    logger.info("credit.leftover.consumed", "leftover credit consumed by recovery probe", {
-      sellerId,
-      consumedMicros: consume,
-      remainingMicros: next.leftoverCreditMicros
-    });
-    return consume;
-  }
-
-  /**
-   * Returns `true` when the seller is still inside the fresh-purchase
-   * window: at least `freshPurchaseThreshold` of the most recent
-   * purchase is still unused, and the window has not elapsed. Sellers
-   * with no recorded purchase are never "fresh".
-   */
-  isInFreshPurchaseWindow(sellerId: string, now: number = this.now()): boolean {
-    const entry = this.entries.get(sellerId);
-    if (!entry || entry.lastPurchaseAmountMicros <= 0) {
-      return false;
-    }
-    if (now - entry.lastPurchaseAt > this.freshPurchaseWindowMs) {
-      return false;
-    }
-    const ratio = entry.currentBalanceMicros / entry.lastPurchaseAmountMicros;
-    return ratio >= this.freshPurchaseThreshold;
-  }
-
-  /**
-   * Returns `true` when the per-minute auto-purchase budget is still
-   * available. Used by `route-failover` to refuse auto-repurchase and
-   * force a clean `切` once the session is at risk of over-spending.
-   */
-  canAutoPurchase(now: number = this.now()): boolean {
-    this.prunePurchaseTimestamps(now);
-    return this.purchaseTimestamps.length < this.purchaseBudgetPerMinute;
-  }
-
-  /**
-   * Snapshot for `tb doctor`. Mirrors the design's "Credit Usage" block.
-   */
-  summary(): CreditSummary {
-    return {
-      totalWastedMicros: this.totalWastedMicros,
-      wastedSinceLastDoctorRun: this.wastedSinceLastDoctorRun,
-      purchasesInLastMinute: this.purchaseTimestamps.length,
-      purchaseBudgetPerMinute: this.purchaseBudgetPerMinute,
-      freshPurchaseWindowMs: this.freshPurchaseWindowMs,
-      freshPurchaseThreshold: this.freshPurchaseThreshold,
-      perSeller: Array.from(this.entries.values()).map((entry) => ({
-        sellerId: entry.sellerId,
-        currentBalanceMicros: entry.currentBalanceMicros,
-        lastPurchaseAmountMicros: entry.lastPurchaseAmountMicros,
-        lastPurchaseAt: entry.lastPurchaseAt,
-        leftoverCreditMicros: entry.leftoverCreditMicros
-      }))
-    };
-  }
-
-  getEntry(sellerId: string): SellerCredit | undefined {
-    return this.entries.get(sellerId);
-  }
-
-  resetDoctorRunCounter(): void {
-    this.wastedSinceLastDoctorRun = 0;
-  }
-
-  clear(): void {
-    this.entries.clear();
-    this.purchaseTimestamps.length = 0;
-    this.totalWastedMicros = 0;
-    this.wastedSinceLastDoctorRun = 0;
-  }
-
-  private prunePurchaseTimestamps(now: number): void {
-    const cutoff = now - 60_000;
-    while (this.purchaseTimestamps.length > 0 && this.purchaseTimestamps[0] < cutoff) {
-      this.purchaseTimestamps.shift();
-    }
-  }
-}
-
-/**
- * `CreditTracker.summary()` 的返回结构，对应 design doc 的 "Credit Usage" 块。
- * `tb doctor` 直接消费此结构展示给用户。
- */
-export interface CreditSummary {
-  /** 自 tracker 创建以来累计浪费的 micros（含 failover 触发时的余额残留） */
-  totalWastedMicros: number;
-  /** 上次 `resetDoctorRunCounter()` 之后又新产生的浪费 micros（doctor 显示 delta） */
-  wastedSinceLastDoctorRun: number;
-  /** 过去 60 秒内自动购买次数 */
-  purchasesInLastMinute: number;
-  /** 每分钟自动购买上限 */
-  purchaseBudgetPerMinute: number;
-  /** 当前 fresh-purchase 窗口长度（毫秒） */
-  freshPurchaseWindowMs: number;
-  /** 当前 fresh-purchase 比例阈值 */
-  freshPurchaseThreshold: number;
-  /** 每个 seller 的余额快照 */
-  perSeller: Array<{
-    sellerId: string;
-    currentBalanceMicros: number;
-    lastPurchaseAmountMicros: number;
-    lastPurchaseAt: number;
-    leftoverCreditMicros: number;
-  }>;
-}