@tokenbuddy/tokenbuddy 1.0.8 → 1.0.11

package/src/prewarm-cache.test.ts

@@ -0,0 +1,281 @@
+import {
+  DEFAULT_PREWARM_TTL_MS,
+  PrewarmCache,
+  prewarmKey
+} from "../src/prewarm-cache.js";
+
+describe("PrewarmCache", () => {
+  function makeCandidate(overrides: { sellerId: string; healthScore?: number; url?: string }) {
+    return {
+      sellerId: overrides.sellerId,
+      url: overrides.url ?? `https://${overrides.sellerId}.example.com`,
+      healthScore: overrides.healthScore ?? 80
+    };
+  }
+
+  test("key encoding is collision-free and case-insensitive", () => {
+    const a = prewarmKey("gpt-4o", "chat_completions", "clawtip");
+    const b = prewarmKey("GPT-4O", "Chat_Completions", "ClawTip");
+    expect(a).toBe(b);
+  });
+
+  test("get returns undefined for unknown keys; freshness reports empty", () => {
+    const cache = new PrewarmCache();
+    expect(cache.get("m1", "chat_completions", "clawtip")).toBeUndefined();
+    const f = cache.freshness("m1", "chat_completions", "clawtip");
+    expect(f.present).toBe(false);
+    expect(f.expired).toBe(true);
+    expect(f.expiringSoon).toBe(true);
+    expect(f.state).toBe("empty");
+  });
+
+  test("beginWarming creates a new warming entry without mutating any prior candidates", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+
+    const begin = cache.beginWarming("gpt-4o", "chat_completions", "clawtip");
+    expect(begin.hadPrevious).toBe(true);
+    expect(begin.entry.state).toBe("warming");
+    // Prior warm candidates are preserved while a new probe is in flight;
+    // a re-probe that finds nothing must not silently wipe the cache.
+    expect(begin.entry.candidates).toHaveLength(1);
+    expect(begin.entry.candidates[0].sellerId).toBe("s1");
+  });
+
+  test("commitWarm resets warmedAt and replaces candidates", () => {
+    const fakeNow = (() => {
+      let t = 1_000_000;
+      return () => t;
+    })();
+    const cache = new PrewarmCache({ now: fakeNow });
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    expect(cache.get("gpt-4o", "chat_completions", "clawtip")?.warmedAt).toBe(1_000_000);
+
+    fakeNow();
+    fakeNow();
+    const advanced = 1_000_000 + 9 * 60 * 1000; // 9 minutes later, still warm
+    const secondNow = (() => {
+      let t = advanced;
+      return () => t;
+    })();
+    const cache2 = new PrewarmCache({ now: secondNow });
+    cache2.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    cache2.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s2" }), makeCandidate({ sellerId: "s3" })]
+    });
+    const entry = cache2.get("gpt-4o", "chat_completions", "clawtip");
+    expect(entry?.warmedAt).toBe(advanced);
+    expect(entry?.state).toBe("warm");
+    expect(entry?.candidates.map((c) => c.sellerId).sort()).toEqual(["s2", "s3"]);
+  });
+
+  test("commitWarm with zero candidates marks the entry as empty", () => {
+    const cache = new PrewarmCache();
+    const result = cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: []
+    });
+    expect(result.entry.state).toBe("empty");
+    expect(result.entry.candidates).toEqual([]);
+  });
+
+  test("freshness reports expiringSoon when within the last 10% of TTL", () => {
+    // Use a controllable `now` so we can advance time deterministically.
+    let now = 0;
+    const cache = new PrewarmCache({ now: () => now, defaultTtlMs: 1000 });
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+
+    // At t=0: warmedAt=0, age=0, far from expiry.
+    const fresh = cache.freshness("gpt-4o", "chat_completions", "clawtip");
+    expect(fresh.expired).toBe(false);
+    expect(fresh.expiringSoon).toBe(false);
+    expect(fresh.remainingMs).toBe(1000);
+
+    // At t=850: 150ms left, not in the last 10%.
+    now = 850;
+    const midLife = cache.freshness("gpt-4o", "chat_completions", "clawtip");
+    expect(midLife.expired).toBe(false);
+    expect(midLife.expiringSoon).toBe(false);
+    expect(midLife.remainingMs).toBe(150);
+
+    // At t=950: 50ms left, in the last 10%.
+    now = 950;
+    const nearEnd = cache.freshness("gpt-4o", "chat_completions", "clawtip");
+    expect(nearEnd.expired).toBe(false);
+    expect(nearEnd.expiringSoon).toBe(true);
+    expect(nearEnd.remainingMs).toBe(50);
+
+    // At t=1100: past TTL, expired.
+    now = 1100;
+    const past = cache.freshness("gpt-4o", "chat_completions", "clawtip");
+    expect(past.expired).toBe(true);
+    expect(past.state).toBe("stale");
+  });
+
+  test("recordFailure increments consecutive failures and marks entry stale", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    const first = cache.recordFailure("gpt-4o", "chat_completions", "clawtip", "503");
+    expect(first?.consecutiveWarmingFailures).toBe(1);
+    expect(first?.state).toBe("stale");
+    const second = cache.recordFailure("gpt-4o", "chat_completions", "clawtip");
+    expect(second?.consecutiveWarmingFailures).toBe(2);
+  });
+
+  test("recordFailure is a no-op when the key is unknown", () => {
+    const cache = new PrewarmCache();
+    expect(cache.recordFailure("missing", "chat_completions", "clawtip")).toBeUndefined();
+  });
+
+  test("invalidateSeller drops the seller from every entry", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" }), makeCandidate({ sellerId: "s2" })]
+    });
+    cache.commitWarm({
+      modelId: "claude-sonnet-4-5",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s2" })]
+    });
+
+    const affected = cache.invalidateSeller("s2");
+    expect(affected).toBe(2);
+    const gpt = cache.get("gpt-4o", "chat_completions", "clawtip");
+    expect(gpt?.candidates.map((c) => c.sellerId)).toEqual(["s1"]);
+    const claude = cache.get("claude-sonnet-4-5", "chat_completions", "clawtip");
+    expect(claude?.state).toBe("empty");
+    expect(claude?.candidates).toEqual([]);
+  });
+
+  test("invalidateKey removes a single entry entirely", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    expect(cache.invalidateKey("gpt-4o", "chat_completions", "clawtip")).toBe(true);
+    expect(cache.invalidateKey("gpt-4o", "chat_completions", "clawtip")).toBe(false);
+    expect(cache.size()).toBe(0);
+  });
+
+  test("evictExpired removes only entries past their TTL", () => {
+    // Use a single controllable clock so commit and evict see consistent time.
+    let now = 0;
+    const cache = new PrewarmCache({ now: () => now, defaultTtlMs: 1000 });
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    cache.commitWarm({
+      modelId: "claude-sonnet-4-5",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s2" })]
+    });
+    // Clock at 0; both fresh.
+    expect(cache.evictExpired()).toBe(0);
+
+    // Advance to t=500; still fresh.
+    now = 500;
+    expect(cache.evictExpired()).toBe(0);
+
+    // Advance to t=1500; both entries now older than TTL=1000.
+    now = 1500;
+    expect(cache.evictExpired()).toBe(2);
+    expect(cache.size()).toBe(0);
+  });
+
+  test("isExpiringSoon returns true only inside the expiry window", () => {
+    const cache = new PrewarmCache({ now: () => 0, defaultTtlMs: 1000 });
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    // At t=0: warmedAt==0, age==0, not expiring.
+    expect(cache.isExpiringSoon("gpt-4o", "chat_completions", "clawtip", 100, 200)).toBe(false);
+    // At t=850 (150ms left, within 100ms window? no).
+    expect(cache.isExpiringSoon("gpt-4o", "chat_completions", "clawtip", 100, 850)).toBe(false);
+    // At t=950 (50ms left, within 100ms window).
+    expect(cache.isExpiringSoon("gpt-4o", "chat_completions", "clawtip", 100, 950)).toBe(true);
+    // At t=1000 (expired; not in the "soon" window anymore).
+    expect(cache.isExpiringSoon("gpt-4o", "chat_completions", "clawtip", 100, 1000)).toBe(false);
+  });
+
+  test("snapshot returns deep copies that do not mutate cache state", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    const snap = cache.snapshot();
+    snap[0].candidates[0].healthScore = -1;
+    expect(cache.get("gpt-4o", "chat_completions", "clawtip")?.candidates[0].healthScore).not.toBe(-1);
+  });
+
+  test("keys() decodes the cache key back into the model/protocol/payment triple", () => {
+    const cache = new PrewarmCache();
+    cache.commitWarm({
+      modelId: "gpt-4o",
+      protocol: "chat_completions",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s1" })]
+    });
+    cache.commitWarm({
+      modelId: "claude-sonnet-4-5",
+      protocol: "messages",
+      paymentMethod: "clawtip",
+      candidates: [makeCandidate({ sellerId: "s2" })]
+    });
+    const keys = cache.keys().sort((a, b) => a.modelId.localeCompare(b.modelId));
+    expect(keys).toEqual([
+      { modelId: "claude-sonnet-4-5", protocol: "messages", paymentMethod: "clawtip" },
+      { modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" }
+    ]);
+  });
+
+  test("default TTL is 10 minutes", () => {
+    expect(DEFAULT_PREWARM_TTL_MS).toBe(600_000);
+  });
+});

package/src/prewarm-cache.ts

@@ -0,0 +1,373 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+
+const logger = createModuleLogger("tb-proxyd:prewarm-cache");
+
+/**
+ * Default TTL for a successfully warmed entry. 10 minutes is the v1.2 starting
+ * point; see buyer-driven-fallback-design.md §18.13 for the trade-off. The
+ * cache constructor accepts an override so tests and the future PR-E config
+ * loader can change this without re-architecting.
+ */
+export const DEFAULT_PREWARM_TTL_MS = 10 * 60 * 1000;
+
+export type PrewarmState = "warming" | "warm" | "stale" | "empty";
+
+export interface PrewarmCandidate {
+  sellerId: string;
+  url: string;
+  healthScore: number;          // 0-100
+  lastSuccessAt: number;
+  lastFailAt: number;
+  avgLatencyMs: number;
+}
+
+export interface PrewarmEntry {
+  modelId: string;
+  protocol: string;
+  paymentMethod: string;
+  state: PrewarmState;
+  candidates: PrewarmCandidate[];
+  warmedAt: number;
+  ttlMs: number;
+  consecutiveWarmingFailures: number;
+  lastInFlightAt?: number;
+}
+
+export interface PrewarmCandidateInput {
+  sellerId: string;
+  url: string;
+  healthScore?: number;
+  lastSuccessAt?: number;
+  lastFailAt?: number;
+  avgLatencyMs?: number;
+}
+
+/**
+ * Build the cache key for a (model, protocol, payment) triple. The colon
+ * separator is reserved at the model-id level because `RegistrySeller.models`
+ * entries are trimmed but not colon-escaped. v1.2 forbids `:` inside model
+ * ids so this format is collision-free.
+ */
+export function prewarmKey(modelId: string, protocol: string, paymentMethod: string): string {
+  return `${modelId.trim().toLowerCase()}\u0001${protocol.trim().toLowerCase()}\u0001${paymentMethod.trim().toLowerCase()}`;
+}
+
+function parseKey(key: string): { modelId: string; protocol: string; paymentMethod: string } | undefined {
+  const parts = key.split("\u0001");
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  const [modelId, protocol, paymentMethod] = parts;
+  if (!modelId || !protocol || !paymentMethod) {
+    return undefined;
+  }
+  return { modelId, protocol, paymentMethod };
+}
+
+interface PrewarmCacheOptions {
+  defaultTtlMs?: number;
+  now?: () => number;
+}
+
+export class PrewarmCache {
+  private readonly entries = new Map<string, PrewarmEntry>();
+  private readonly defaultTtlMs: number;
+  private readonly now: () => number;
+
+  constructor(options: PrewarmCacheOptions = {}) {
+    this.defaultTtlMs = options.defaultTtlMs ?? DEFAULT_PREWARM_TTL_MS;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Read an entry without mutating state. Returns `undefined` when the key is
+   * unknown; the caller decides whether "absent" should be treated as a miss
+   * (i.e. trigger a fresh prewarm) or as a known empty model.
+   */
+  get(modelId: string, protocol: string, paymentMethod: string): PrewarmEntry | undefined {
+    return this.entries.get(prewarmKey(modelId, protocol, paymentMethod));
+  }
+
+  /**
+   * Look up an entry and return a `Freshness` descriptor. This is the cheap
+   * path used on every inference request to decide whether a prewarm is
+   * still authoritative, expiring soon, or already stale.
+   */
+  freshness(modelId: string, protocol: string, paymentMethod: string): PrewarmFreshness {
+    const entry = this.get(modelId, protocol, paymentMethod);
+    if (!entry) {
+      return { present: false, expired: true, expiringSoon: true, state: "empty" };
+    }
+    const now = this.now();
+    const ageMs = now - entry.warmedAt;
+    const expired = ageMs >= entry.ttlMs;
+    const remainingMs = Math.max(0, entry.ttlMs - ageMs);
+    return {
+      present: true,
+      expired,
+      expiringSoon: !expired && remainingMs <= entry.ttlMs * 0.1,
+      remainingMs,
+      state: expired ? "stale" : entry.state,
+      entry
+    };
+  }
+
+  /**
+   * Mark a (model, protocol, payment) triple as currently being warmed. If an
+   * existing warm entry is present it is kept untouched (the new probe
+   * supersedes it on commit) and the previous state is reported to the
+   * caller via the returned descriptor.
+   */
+  beginWarming(modelId: string, protocol: string, paymentMethod: string, ttlMs?: number): PrewarmBeginResult {
+    const key = prewarmKey(modelId, protocol, paymentMethod);
+    const previous = this.entries.get(key);
+    const now = this.now();
+    const entry: PrewarmEntry = {
+      modelId,
+      protocol,
+      paymentMethod,
+      state: "warming",
+      candidates: previous?.candidates ?? [],
+      warmedAt: previous?.warmedAt ?? now,
+      ttlMs: ttlMs ?? previous?.ttlMs ?? this.defaultTtlMs,
+      consecutiveWarmingFailures: previous?.consecutiveWarmingFailures ?? 0,
+      lastInFlightAt: now
+    };
+    this.entries.set(key, entry);
+    logger.debug("prewarm.cache.warming_started", "prewarm probe in flight", {
+      modelId,
+      protocol,
+      paymentMethod,
+      ttlMs: entry.ttlMs,
+      previousState: previous?.state
+    });
+    return { key, entry, hadPrevious: Boolean(previous) };
+  }
+
+  /**
+   * Commit a successful warm. The entry's `warmedAt` is reset to the current
+   * time so the TTL window starts fresh, and any prior stale candidates are
+   * replaced with the new probe results. The previous candidate set is
+   * returned for caller-side telemetry (e.g. detecting churn).
+   */
+  commitWarm(input: {
+    modelId: string;
+    protocol: string;
+    paymentMethod: string;
+    candidates: PrewarmCandidateInput[];
+    ttlMs?: number;
+  }): PrewarmCommitResult {
+    const key = prewarmKey(input.modelId, input.protocol, input.paymentMethod);
+    const previous = this.entries.get(key);
+    const now = this.now();
+    const next: PrewarmEntry = {
+      modelId: input.modelId,
+      protocol: input.protocol,
+      paymentMethod: input.paymentMethod,
+      state: input.candidates.length > 0 ? "warm" : "empty",
+      candidates: input.candidates.map(toCandidate),
+      warmedAt: now,
+      ttlMs: input.ttlMs ?? previous?.ttlMs ?? this.defaultTtlMs,
+      consecutiveWarmingFailures: 0,
+      lastInFlightAt: now
+    };
+    this.entries.set(key, next);
+
+    if (input.candidates.length === 0) {
+      logger.warn("prewarm.cache.commit_empty", "prewarm commit returned no candidates", {
+        modelId: input.modelId,
+        protocol: input.protocol,
+        paymentMethod: input.paymentMethod
+      });
+    } else {
+      logger.info("prewarm.cache.committed", "prewarm commit updated candidates", {
+        modelId: input.modelId,
+        protocol: input.protocol,
+        paymentMethod: input.paymentMethod,
+        candidateCount: next.candidates.length,
+        ttlMs: next.ttlMs
+      });
+    }
+
+    return {
+      key,
+      entry: next,
+      replacedSellers: previous?.candidates.map((c) => c.sellerId) ?? []
+    };
+  }
+
+  /**
+   * Mark a warm as failed. Consecutive failures are tracked so the scheduler
+   * can apply exponential backoff and so `tb doctor` can surface persistently
+   * broken models.
+   */
+  recordFailure(modelId: string, protocol: string, paymentMethod: string, errorMessage?: string): PrewarmEntry | undefined {
+    const key = prewarmKey(modelId, protocol, paymentMethod);
+    const previous = this.entries.get(key);
+    if (!previous) {
+      return undefined;
+    }
+    const next: PrewarmEntry = {
+      ...previous,
+      state: "stale",
+      consecutiveWarmingFailures: previous.consecutiveWarmingFailures + 1,
+      lastInFlightAt: this.now()
+    };
+    this.entries.set(key, next);
+    logger.warn("prewarm.cache.failure_recorded", "prewarm commit failed; entry marked stale", {
+      modelId,
+      protocol,
+      paymentMethod,
+      consecutiveFailures: next.consecutiveWarmingFailures,
+      errorMessage
+    });
+    return next;
+  }
+
+  /**
+   * Invalidate every entry that references the given seller. Used when the
+   * registry signals a seller is gone (grace period expires) or when a hard
+   * failure (e.g. 5xx storm) should drop the seller from the cache
+   * immediately.
+   */
+  invalidateSeller(sellerId: string): number {
+    let removed = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      const filtered = entry.candidates.filter((candidate) => candidate.sellerId !== sellerId);
+      if (filtered.length !== entry.candidates.length) {
+        removed += 1;
+        this.entries.set(key, {
+          ...entry,
+          candidates: filtered,
+          state: filtered.length > 0 ? entry.state : "empty"
+        });
+      }
+    }
+    if (removed > 0) {
+      logger.info("prewarm.cache.seller_invalidated", "seller dropped from all prewarm entries", {
+        sellerId,
+        entriesAffected: removed
+      });
+    }
+    return removed;
+  }
+
+  /**
+   * Invalidate a specific cache key. Used by `tb doctor --refresh <model>`
+   * and by the registry loop when a model is removed from the focus set.
+   */
+  invalidateKey(modelId: string, protocol: string, paymentMethod: string): boolean {
+    return this.entries.delete(prewarmKey(modelId, protocol, paymentMethod));
+  }
+
+  /**
+   * Drop every entry whose TTL has expired. Returns the number of removed
+   * entries so the caller can log it.
+   */
+  evictExpired(now: number = this.now()): number {
+    let removed = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      if (now - entry.warmedAt >= entry.ttlMs) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    if (removed > 0) {
+      logger.info("prewarm.cache.evicted", "expired prewarm entries evicted", { removed });
+    }
+    return removed;
+  }
+
+  /**
+   * Returns `true` when the entry's TTL is within `withinMs` of expiring. The
+   * scheduler uses this to schedule idle-cycle prewarms just-in-time rather
+   * than at fixed wall-clock intervals.
+   */
+  isExpiringSoon(modelId: string, protocol: string, paymentMethod: string, withinMs: number, now: number = this.now()): boolean {
+    const entry = this.get(modelId, protocol, paymentMethod);
+    if (!entry) {
+      return false;
+    }
+    const age = now - entry.warmedAt;
+    return age >= entry.ttlMs - withinMs && age < entry.ttlMs;
+  }
+
+  /**
+   * Snapshot all entries for diagnostics. Returns a deep-copy of the values
+   * so callers can serialize without risking mutation of cache state.
+   */
+  snapshot(): PrewarmEntry[] {
+    return Array.from(this.entries.values()).map((entry) => ({
+      ...entry,
+      candidates: entry.candidates.map((candidate) => ({ ...candidate }))
+    }));
+  }
+
+  /**
+   * List every cached key, decoded back into its (model, protocol, payment)
+   * triple. Used by `tb doctor` to render the prewarm table.
+   */
+  keys(): Array<{ modelId: string; protocol: string; paymentMethod: string }> {
+    const out: Array<{ modelId: string; protocol: string; paymentMethod: string }> = [];
+    for (const key of this.entries.keys()) {
+      const parsed = parseKey(key);
+      if (parsed) {
+        out.push(parsed);
+      }
+    }
+    return out;
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+export interface PrewarmFreshness {
+  present: boolean;
+  expired: boolean;
+  expiringSoon: boolean;
+  remainingMs?: number;
+  state: PrewarmState;
+  entry?: PrewarmEntry;
+}
+
+export interface PrewarmBeginResult {
+  key: string;
+  entry: PrewarmEntry;
+  hadPrevious: boolean;
+}
+
+export interface PrewarmCommitResult {
+  key: string;
+  entry: PrewarmEntry;
+  replacedSellers: string[];
+}
+
+function toCandidate(input: PrewarmCandidateInput): PrewarmCandidate {
+  return {
+    sellerId: input.sellerId,
+    url: input.url,
+    healthScore: clampScore(input.healthScore ?? 50),
+    lastSuccessAt: input.lastSuccessAt ?? 0,
+    lastFailAt: input.lastFailAt ?? 0,
+    avgLatencyMs: Math.max(0, input.avgLatencyMs ?? 0)
+  };
+}
+
+function clampScore(score: number): number {
+  if (!Number.isFinite(score)) {
+    return 50;
+  }
+  if (score < 0) {
+    return 0;
+  }
+  if (score > 100) {
+    return 100;
+  }
+  return score;
+}