@tokenbuddy/tokenbuddy 1.0.9 → 1.0.11

package/src/credit-tracker.test.ts

@@ -0,0 +1,165 @@
+import {
+  CreditTracker,
+  DEFAULT_FRESH_PURCHASE_THRESHOLD,
+  DEFAULT_FRESH_PURCHASE_WINDOW_MS,
+  DEFAULT_PURCHASE_BUDGET_PER_MINUTE
+} from "../src/credit-tracker.js";
+
+describe("CreditTracker", () => {
+  function makeClock(start = 1_000_000): { now: number; advance: (ms: number) => void } {
+    const clock = { now: start, advance: (ms: number) => { clock.now += ms; } };
+    return clock;
+  }
+
+  test("recordPurchase creates an entry with the supplied balance", () => {
+    const clock = makeClock();
+    const tracker = new CreditTracker({ now: () => clock.now });
+    const entry = tracker.recordPurchase("s1", 1_000_000, 1_000_000);
+    expect(entry.sellerId).toBe("s1");
+    expect(entry.lastPurchaseAmountMicros).toBe(1_000_000);
+    expect(entry.currentBalanceMicros).toBe(1_000_000);
+    expect(entry.leftoverCreditMicros).toBe(0);
+    expect(tracker.summary().purchasesInLastMinute).toBe(1);
+  });
+
+  test("recordPurchase rejects non-positive amounts", () => {
+    const tracker = new CreditTracker();
+    expect(() => tracker.recordPurchase("s1", 0, 0)).toThrow();
+    expect(() => tracker.recordPurchase("s1", -1, -1)).toThrow();
+  });
+
+  test("recordSpend clamps to zero and is a no-op for unknown sellers", () => {
+    const tracker = new CreditTracker();
+    expect(tracker.recordSpend("missing", 100)).toBeUndefined();
+    tracker.recordPurchase("s1", 1_000_000, 1_000_000);
+    const updated = tracker.recordSpend("s1", 600_000);
+    expect(updated?.currentBalanceMicros).toBe(600_000);
+    const zeroed = tracker.recordSpend("s1", -10);
+    expect(zeroed?.currentBalanceMicros).toBe(0);
+  });
+
+  test("isInFreshPurchaseWindow is true only when balance ratio and time window are both satisfied", () => {
+    const clock = makeClock();
+    const tracker = new CreditTracker({ now: () => clock.now });
+    tracker.recordPurchase("s1", 1_000_000, 1_000_000);
+
+    // Right after purchase: 100% balance, well within the window.
+    expect(tracker.isInFreshPurchaseWindow("s1")).toBe(true);
+
+    // After 50% spend: ratio = 0.5, still at the default threshold.
+    tracker.recordSpend("s1", 500_000);
+    expect(tracker.isInFreshPurchaseWindow("s1")).toBe(true);
+
+    // After more spend the ratio drops below threshold.
+    tracker.recordSpend("s1", 100_000);
+    expect(tracker.isInFreshPurchaseWindow("s1")).toBe(false);
+
+    // Replenish via a new purchase and verify window restarts.
+    clock.advance(1_000);
+    tracker.recordPurchase("s1", 1_000_000, 1_000_000);
+    expect(tracker.isInFreshPurchaseWindow("s1")).toBe(true);
+
+    // Advance past the window: even a full balance no longer counts.
+    clock.advance(DEFAULT_FRESH_PURCHASE_WINDOW_MS + 1);
+    expect(tracker.isInFreshPurchaseWindow("s1")).toBe(false);
+  });
+
+  test("isInFreshPurchaseWindow returns false for sellers without any purchase", () => {
+    const tracker = new CreditTracker();
+    expect(tracker.isInFreshPurchaseWindow("never-purchased")).toBe(false);
+  });
+
+  test("canAutoPurchase enforces a per-minute budget and prunes old timestamps", () => {
+    const clock = makeClock();
+    const tracker = new CreditTracker({ now: () => clock.now });
+
+    expect(tracker.canAutoPurchase()).toBe(true);
+    tracker.recordPurchase("s1", 100, 100);
+    tracker.recordPurchase("s2", 100, 100);
+    tracker.recordPurchase("s3", 100, 100);
+    expect(tracker.canAutoPurchase()).toBe(false); // budget hit
+
+    // Advance past the 60s window: oldest timestamps fall out.
+    clock.advance(60_001);
+    expect(tracker.canAutoPurchase()).toBe(true);
+  });
+
+  test("transferLeftoverToWasted moves the current balance into the leftover bucket and tracks waste", () => {
+    const clock = makeClock();
+    const tracker = new CreditTracker({ now: () => clock.now });
+    tracker.recordPurchase("s1", 1_000_000, 800_000);
+    const wasted = tracker.transferLeftoverToWasted("s1", "failover");
+    expect(wasted).toBe(800_000);
+    const entry = tracker.getEntry("s1");
+    expect(entry?.currentBalanceMicros).toBe(0);
+    expect(entry?.leftoverCreditMicros).toBe(800_000);
+    const summary = tracker.summary();
+    expect(summary.totalWastedMicros).toBe(800_000);
+    expect(summary.wastedSinceLastDoctorRun).toBe(800_000);
+  });
+
+  test("transferLeftoverToWasted is a no-op for unknown sellers or empty balances", () => {
+    const tracker = new CreditTracker();
+    expect(tracker.transferLeftoverToWasted("missing", "x")).toBe(0);
+    tracker.recordPurchase("s1", 100, 0);
+    expect(tracker.transferLeftoverToWasted("s1", "x")).toBe(0);
+  });
+
+  test("consumeLeftover drains the leftover bucket up to the requested amount", () => {
+    const tracker = new CreditTracker();
+    tracker.recordPurchase("s1", 1_000_000, 500_000);
+    tracker.transferLeftoverToWasted("s1", "failover");
+    expect(tracker.consumeLeftover("s1", 300_000)).toBe(300_000);
+    expect(tracker.getEntry("s1")?.leftoverCreditMicros).toBe(200_000);
+    // Requesting more than available returns only the available amount.
+    expect(tracker.consumeLeftover("s1", 999_999)).toBe(200_000);
+    expect(tracker.getEntry("s1")?.leftoverCreditMicros).toBe(0);
+  });
+
+  test("consumeLeftover is a no-op for sellers without leftover", () => {
+    const tracker = new CreditTracker();
+    expect(tracker.consumeLeftover("missing", 100)).toBe(0);
+  });
+
+  test("summary includes per-seller entries with latest values", () => {
+    const clock = makeClock();
+    const tracker = new CreditTracker({ now: () => clock.now });
+    tracker.recordPurchase("s1", 1_000_000, 1_000_000);
+    clock.advance(1_000);
+    tracker.recordPurchase("s2", 500_000, 500_000);
+    const summary = tracker.summary();
+    expect(summary.perSeller).toHaveLength(2);
+    const s2 = summary.perSeller.find((entry) => entry.sellerId === "s2");
+    expect(s2?.currentBalanceMicros).toBe(500_000);
+    expect(s2?.lastPurchaseAt).toBe(clock.now);
+  });
+
+  test("resetDoctorRunCounter clears the wasted-since-last-doctor counter", () => {
+    const tracker = new CreditTracker();
+    tracker.recordPurchase("s1", 1_000_000, 500_000);
+    tracker.transferLeftoverToWasted("s1", "failover");
+    expect(tracker.summary().wastedSinceLastDoctorRun).toBe(500_000);
+    tracker.resetDoctorRunCounter();
+    expect(tracker.summary().wastedSinceLastDoctorRun).toBe(0);
+    // totalWastedMicros is preserved.
+    expect(tracker.summary().totalWastedMicros).toBe(500_000);
+  });
+
+  test("clear removes all entries and resets all counters", () => {
+    const tracker = new CreditTracker();
+    tracker.recordPurchase("s1", 100, 100);
+    tracker.transferLeftoverToWasted("s1", "failover");
+    tracker.clear();
+    const summary = tracker.summary();
+    expect(summary.totalWastedMicros).toBe(0);
+    expect(summary.wastedSinceLastDoctorRun).toBe(0);
+    expect(summary.purchasesInLastMinute).toBe(0);
+    expect(summary.perSeller).toEqual([]);
+  });
+
+  test("default constants match the v1.1 / v1.2 design", () => {
+    expect(DEFAULT_FRESH_PURCHASE_WINDOW_MS).toBe(30_000);
+    expect(DEFAULT_FRESH_PURCHASE_THRESHOLD).toBe(0.5);
+    expect(DEFAULT_PURCHASE_BUDGET_PER_MINUTE).toBe(3);
+  });
+});

package/src/credit-tracker.ts

@@ -0,0 +1,269 @@
+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;
+
+export interface CreditTrackerOptions {
+  freshPurchaseWindowMs?: number;
+  freshPurchaseThreshold?: number;
+  purchaseBudgetPerMinute?: number;
+  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.
+ */
+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();
+    }
+  }
+}
+
+export interface CreditSummary {
+  totalWastedMicros: number;
+  wastedSinceLastDoctorRun: number;
+  purchasesInLastMinute: number;
+  purchaseBudgetPerMinute: number;
+  freshPurchaseWindowMs: number;
+  freshPurchaseThreshold: number;
+  perSeller: Array<{
+    sellerId: string;
+    currentBalanceMicros: number;
+    lastPurchaseAmountMicros: number;
+    lastPurchaseAt: number;
+    leftoverCreditMicros: number;
+  }>;
+}