decision-gate 0.1.0

package/lib/cache.mjs

@@ -0,0 +1,95 @@
+import { closeSync, fsyncSync, linkSync, openSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createHmac, randomBytes, randomUUID } from "node:crypto";
+import { appendRecords, clock, locked, privateDir, replaceFile } from "./state.mjs";
+
+export const TTL = 30 * 86400000;
+const MAX_BYTES = 50 * 1024 * 1024;
+
+function hashKey(stateDir) {
+  privateDir(stateDir);
+  const file = path.join(stateDir, "cache-key");
+  try {
+    const key = readFileSync(file);
+    if (key.length !== 32 || (statSync(file).mode & 0o777) !== 0o600) throw new Error("invalid cache key");
+    return key;
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  const temp = `${file}.${randomUUID()}`;
+  const fd = openSync(temp, "wx", 0o600);
+  try { writeFileSync(fd, randomBytes(32)); fsyncSync(fd); }
+  finally { closeSync(fd); }
+  try { linkSync(temp, file); }
+  catch (error) { if (error.code !== "EEXIST") throw error; }
+  finally { rmSync(temp, { force: true }); }
+  return hashKey(stateDir);
+}
+
+function liveRows(text, now, ttl) {
+  const rows = new Map();
+  let lines = 0;
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    lines++;
+    try {
+      const row = JSON.parse(line);
+      if (/^[a-f0-9]{64}$/.test(row.h) && Number.isFinite(row.p) && row.p >= 0 && row.p <= 1 && Number.isFinite(row.t) && row.t <= now && row.t > now - ttl) rows.set(row.h, row);
+    } catch { /* A partial or corrupt entry is a miss, never an answer */ }
+  }
+  return { rows, stale: lines - rows.size };
+}
+
+export function answerCache({ stateDir, cacheDir, scope, ttl = TTL, enabled = true, notice = () => {}, time = clock }) {
+  let key, file;
+  const warn = () => { notice("answer cache unavailable; continuing without caching"); enabled = false; };
+  const hash = (value) => createHmac("sha256", key).update(value).digest("hex");
+  if (enabled) {
+    try {
+      key = hashKey(stateDir);
+      privateDir(cacheDir);
+      file = path.join(cacheDir, `${hash(JSON.stringify(scope))}.jsonl`);
+    } catch { warn(); }
+  }
+  let entries = new Map(), stale = 0;
+  if (enabled) {
+    try { ({ rows: entries, stale } = liveRows(readFileSync(file, "utf8"), time.now(), ttl)); }
+    catch (error) { if (error.code !== "ENOENT") warn(); }
+  }
+  return {
+    get(name) { return enabled ? entries.get(hash(name))?.p : undefined; },
+    // One locked write per batch of [key, probability] pairs
+    async put(pairs) {
+      // Only a key's keyed hash and a number are stored, so nothing else is accepted
+      if (!Array.isArray(pairs) || pairs.some((pair) => typeof pair?.[0] !== "string" || !Number.isFinite(pair[1]) || pair[1] < 0 || pair[1] > 1)) throw new TypeError("cache entries must be [string key, probability] pairs");
+      if (!enabled || !pairs.length) return;
+      try {
+        const now = time.now();
+        const rows = pairs.map(([name, p]) => ({ h: hash(name), p, t: now }));
+        await locked(path.join(cacheDir, "maintenance"), () => {
+          // Expired and superseded rows would otherwise keep a busy query's file growing forever
+          if (stale > Math.max(256, entries.size)) {
+            let text = "";
+            try { text = readFileSync(file, "utf8"); }
+            catch (error) { if (error.code !== "ENOENT") throw error; }
+            const current = liveRows(text, now, ttl).rows;
+            replaceFile(file, [...current.values()].map((row) => `${JSON.stringify(row)}\n`).join(""));
+            entries = current;
+            stale = 0;
+          }
+          let total = 0;
+          const files = readdirSync(cacheDir).filter((name) => /^[a-f0-9]{64}\.jsonl$/.test(name)).map((name) => {
+            const full = path.join(cacheDir, name), stat = statSync(full);
+            total += stat.size;
+            return { full, stat };
+          }).sort((a, b) => a.stat.mtimeMs - b.stat.mtimeMs);
+          const bytes = rows.reduce((sum, row) => sum + Buffer.byteLength(JSON.stringify(row)) + 1, 0);
+          for (const entry of files) {
+            if (total + bytes <= MAX_BYTES && entry.stat.mtimeMs > now - TTL) continue;
+            rmSync(entry.full); total -= entry.stat.size;
+          }
+          appendRecords(file, rows);
+        }, { time });
+        for (const row of rows) entries.set(row.h, row);
+      } catch { warn(); }
+    }
+  };
+}

package/lib/config.mjs

@@ -0,0 +1,113 @@
+import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { ConfigError } from "./errors.mjs";
+import { DEFAULT_PROVIDER, providers } from "./providers/index.mjs";
+
+const NAME = "decision-gate";
+export const expandHome = (value) => value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+
+export function amount(value, name, { positive = false } = {}) {
+  if (typeof value !== "number" || !Number.isFinite(value) || (positive ? value <= 0 : value < 0)) throw new ConfigError(`${name} must be a ${positive ? "positive" : "nonnegative"} number`);
+  return value;
+}
+
+export function loadConfig(env = process.env) {
+  const file = env.DECISION_GATE_CONFIG || path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), NAME, "config.json");
+  let user = {};
+  try { user = JSON.parse(readFileSync(file, "utf8")); }
+  catch (error) {
+    if (error.code !== "ENOENT" || env.DECISION_GATE_CONFIG) throw new ConfigError("cannot read config as JSON");
+  }
+  const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+  if (!object(user) || (user.spend !== undefined && !object(user.spend)) || (user.limits !== undefined && !object(user.limits))) throw new ConfigError("config, spend and limits must be objects");
+  // The provider is only ever chosen by name, never from whichever key variable happens to be set,
+  // since other tools export those keys for their own use
+  const provider = env.DECISION_GATE_PROVIDER ?? user.provider ?? DEFAULT_PROVIDER;
+  if (!Object.hasOwn(providers, provider)) throw new ConfigError(`provider must be one of ${Object.keys(providers).join(", ")}`);
+  const nested = Object.entries(user.limits ?? {}).filter(([, value]) => object(value));
+  if (nested.some(([name]) => !Object.hasOwn(providers, name))) throw new ConfigError("limits may nest only a known provider's own limits");
+  // Unsectioned limits describe a TypeSafe account, so another provider keeps its own defaults
+  // unless its own section overrides them
+  const shared = Object.fromEntries(Object.entries(user.limits ?? {}).filter(([, value]) => !object(value)));
+  const limits = { ...(provider === DEFAULT_PROVIDER ? shared : {}), ...user.limits?.[provider] };
+  // A key belongs to one provider: the top-level key_file is TypeSafe's, and any other provider's
+  // lives in a section named after it
+  const own = Object.keys(providers).filter((name) => name !== DEFAULT_PROVIDER && user[name] !== undefined);
+  if (own.some((name) => !object(user[name]) || Object.keys(user[name]).some((field) => field !== "key_file"))) throw new ConfigError("a provider's config section holds only its key_file");
+  const keyFile = provider === DEFAULT_PROVIDER ? user.key_file : user[provider]?.key_file;
+  const defaults = providers[provider].limits;
+  const number = (name, fallback, label, positive = false) => amount(env[name] !== undefined ? (env[name].trim() ? Number(env[name]) : NaN) : fallback, label, { positive });
+  const location = (value, fromEnv, label) => {
+    if (value === null) return null;
+    if (typeof value !== "string" || !value.trim()) throw new ConfigError(`${label} must be a path`);
+    return path.resolve(fromEnv ? process.cwd() : path.dirname(file), expandHome(value));
+  };
+  const share = amount(limits.share ?? 0.8, "limits.share", { positive: true });
+  if (share > 1) throw new ConfigError("limits.share must not exceed 1");
+  const whole = (value, label) => {
+    if (!Number.isInteger(value)) throw new ConfigError(`${label} must be a positive whole number`);
+    return value;
+  };
+  return {
+    provider,
+    key_file: location(keyFile ?? null, false, "key_file"),
+    never_send_file: location(env.DECISION_GATE_NEVER_SEND_FILE || user.never_send_file || null, !!env.DECISION_GATE_NEVER_SEND_FILE, "never_send_file"),
+    spend: {
+      perRunUsd: number("DECISION_GATE_PER_RUN_USD", user.spend?.per_run_usd ?? 0.02, "per-run ceiling"),
+      perDayUsd: number("DECISION_GATE_PER_DAY_USD", user.spend?.per_day_usd ?? 0.2, "daily ceiling")
+    },
+    limits: {
+      requestsPerMinute: number("DECISION_GATE_RPM", limits.requests_per_minute ?? defaults.requestsPerMinute, "requests per minute", true),
+      tokensPerSecond: number("DECISION_GATE_TPS", limits.tokens_per_second ?? defaults.tokensPerSecond, "tokens per second", true),
+      share,
+      // Measured on one account: requests of about 6,100 tokens finished fastest at two to four in
+      // flight, while at about 50,000 tokens one at a time was as fast as two or four
+      inFlight: whole(number("DECISION_GATE_IN_FLIGHT", limits.in_flight ?? defaults.inFlight, "limits.in_flight", true), "limits.in_flight"),
+      largeInFlight: 1,
+      largeRequestTokens: 32000
+    },
+    stateDir: location(path.join(env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), NAME), true, "state directory"),
+    cacheDir: location(path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), NAME, "answers"), true, "cache directory")
+  };
+}
+
+function privateFile(file) {
+  const stat = statSync(file);
+  if (!stat.isFile() || (stat.mode & 0o777) !== 0o600) throw new ConfigError("key file must be a private regular file (chmod 600)");
+  if (!stat.size) throw new ConfigError("key file must contain one nonempty line");
+}
+
+// A caller's key names the provider it belongs to, and is used only when that provider is selected,
+// so a key never goes to another provider's endpoint
+export function keySource(explicit, config, env, provider) {
+  const kinds = explicit && typeof explicit === "object" ? Object.keys(explicit).filter((name) => name !== "provider") : [];
+  if (explicit != null && (!Object.hasOwn(providers, explicit.provider) || kinds.length !== 1 || !["file", "env", "value"].includes(kinds[0]) || typeof explicit[kinds[0]] !== "string")) throw new ConfigError("key needs its provider and exactly one file, env or value source");
+  const own = explicit?.provider === provider.name ? { [kinds[0]]: explicit[kinds[0]] } : null;
+  const source = own ?? (env[provider.keyEnv]?.trim() ? { env: provider.keyEnv } : config.key_file ? { file: config.key_file } : null);
+  const where = provider.name === DEFAULT_PROVIDER ? "key_file" : `key_file in the config's ${provider.name} section`;
+  const status = () => {
+    try {
+      if (!source) return { ok: false, missing: true, label: provider.label, keyEnv: provider.keyEnv, reason: `a ${provider.label} API key is needed: export ${provider.keyEnv} or set ${where}; nothing was sent` };
+      if (source.file !== undefined) privateFile(expandHome(source.file));
+      else if (!(source.value ?? env[source.env])?.trim()) throw new ConfigError("configured key source is empty");
+      return { ok: true };
+    } catch (error) { return { ok: false, reason: error instanceof ConfigError ? error.message : "cannot read the configured key file" }; }
+  };
+  return Object.freeze({
+    status,
+    read() {
+      const state = status();
+      if (!state.ok) throw new ConfigError(state.reason);
+      let value;
+      try { value = (source.file !== undefined ? readFileSync(expandHome(source.file), "utf8") : source.value ?? env[source.env]).trim(); }
+      catch { throw new ConfigError("cannot read the configured key source"); }
+      if (!value || /[\s\x00-\x1f\x7f]/.test(value)) throw new ConfigError("configured key must contain one nonempty token");
+      return Object.freeze(Object.defineProperties({}, {
+        authorization: { value: `Bearer ${value}` },
+        fingerprint: { value: createHash("sha256").update(value).digest("hex").slice(0, 16), enumerable: true }
+      }));
+    }
+  });
+}

package/lib/errors.mjs

@@ -0,0 +1,27 @@
+// describeError passes these messages through, so none may ever carry a key, request text or a
+// provider response body
+export class ConfigError extends Error {}
+export class StateError extends Error {}
+export class RedactionError extends Error {}
+
+export class SpendCapError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SpendCapError";
+  }
+}
+
+export class ServiceError extends Error {
+  constructor(message, { status } = {}) {
+    super(message);
+    this.name = "ServiceError";
+    this.status = status;
+  }
+}
+
+export class RequestSizeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RequestSizeError";
+  }
+}

package/lib/index.mjs

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { amount, loadConfig, keySource } from "./config.mjs";
+import { createSpendBudget } from "./budget.mjs";
+import { TTL, answerCache } from "./cache.mjs";
+import { ConfigError, RedactionError, RequestSizeError, ServiceError, SpendCapError, StateError } from "./errors.mjs";
+import { createLedger } from "./ledger.mjs";
+import { createLimiter } from "./limits.mjs";
+import { providers } from "./providers/index.mjs";
+import { createRedactor, loadRedactor } from "./redaction.mjs";
+import { clock } from "./state.mjs";
+
+export { ConfigError, RedactionError, RequestSizeError, ServiceError, SpendCapError, StateError };
+export { privateKeyLines } from "./redaction.mjs";
+export { PINNED_MODEL, MAX_INPUT_TOKENS, MAX_STATE_QUESTION_TOKENS, usdFor, estimateUsd } from "./providers/typesafe.mjs";
+
+export function openJev(options = {}) {
+  const { env = process.env, notice = () => {}, time = clock, tool } = options;
+  if (typeof tool !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(tool)) throw new ConfigError("tool must be a short identifier");
+  const config = loadConfig(env);
+  const provider = providers[config.provider];
+  const toolPerDayUsd = options.spend?.perDayUsd === undefined ? Infinity : amount(options.spend.perDayUsd, "daily ceiling");
+  const spend = {
+    perRunUsd: amount(options.spend?.perRunUsd ?? config.spend.perRunUsd, "per-run ceiling"),
+    perDayUsd: Math.min(toolPerDayUsd, config.spend.perDayUsd)
+  };
+  const source = keySource(options.key, config, env, provider);
+  const neverSend = options.neverSend ?? config.never_send_file;
+  const redactor = Object.freeze(neverSend ? loadRedactor(neverSend) : createRedactor());
+  const endpoint = provider.endpoint(env);
+  const limiter = createLimiter({ dir: path.join(config.stateDir, "limits", provider.name), limits: config.limits, notice, time });
+  let identity;
+  const credentials = () => {
+    if (!identity) {
+      const key = source.read();
+      identity = {
+        key,
+        ledger: createLedger({ dir: path.join(config.stateDir, "spend", provider.name), fingerprint: key.fingerprint, tool, perDayUsd: config.spend.perDayUsd, toolPerDayUsd, time })
+      };
+    }
+    return identity;
+  };
+  const jev = Object.freeze({
+    status: source.status,
+    config: Object.freeze({ ...config, spend, provider: provider.name, model: provider.model, pinned: provider.pinned, endpoint }),
+    redactor,
+    notice,
+    time,
+    remaining: () => credentials().ledger.remaining(),
+    // Answers are filed per provider, model, endpoint and never-send list as well as the caller's
+    // scope, so a change to any of them starts a fresh file instead of reusing stale answers
+    // A floating model can change behind its id, so its answers expire within a day
+    cache({ scope, enabled = true, notice: warn = notice } = {}) {
+      return answerCache({
+        ttl: provider.pinned ? TTL : 86400000,
+        stateDir: config.stateDir,
+        cacheDir: config.cacheDir,
+        scope: { provider: provider.name, model: provider.model, endpoint, neverSend: redactor.fingerprint, caller: scope ?? null },
+        enabled,
+        notice: warn,
+        time
+      });
+    },
+    run({ capUsd = spend.perRunUsd } = {}) {
+      amount(capUsd, "run ceiling");
+      const budgetCap = Math.min(capUsd, spend.perRunUsd);
+      let budget, lease, responder, ready, closing;
+      const pending = new Set();
+      const initialize = () => ready ??= (async () => {
+        const { key, ledger } = credentials();
+        lease = await ledger.open(budgetCap);
+        budget = createSpendBudget({ capUsd: lease.capUsd, price: provider.price });
+        // The ledger reads the committed total inside its lock, so concurrent attempts never
+        // persist an older total over a newer one
+        const book = () => lease.book(() => budget.committedUsd());
+        responder = provider.respond({ key, budget, limiter, book, assertSafe: (body) => redactor.check(body), endpoint, fetchImpl: options.fetch, maxRetries: options.maxRetries, timeoutMs: options.timeoutMs });
+      })().catch((error) => { ready = undefined; throw error; });
+      return Object.freeze({
+        ask(request, { signal } = {}) {
+          if (closing) return Promise.reject(new StateError("run is closed"));
+          // Own the serialized snapshot before async work can observe caller mutations
+          let snapshot;
+          try {
+            snapshot = JSON.stringify(request);
+            redactor.check(snapshot);
+            provider.checkSize(JSON.parse(snapshot));
+          } catch (error) { return Promise.reject(error); }
+          const job = (async () => {
+            signal?.throwIfAborted();
+            await initialize();
+            return responder(JSON.parse(snapshot), { signal });
+          })();
+          pending.add(job);
+          job.then(() => pending.delete(job), () => pending.delete(job));
+          return job;
+        },
+        // Which ceiling bounds this run: its own, or what is left of today's once the run has opened
+        summary: () => ({ ...(budget?.summary() ?? { cap_usd: budgetCap, committed_usd: 0, billed_input_tokens: 0, attempts_booked_at_reservation: 0 }), ceiling: lease && lease.capUsd < budgetCap ? "day" : "run" }),
+        close() {
+          // Closing waits for asks already made, so the ledger records their final cost
+          closing ??= (async () => {
+            await Promise.allSettled([...pending]);
+            if (lease) await lease.close(budget.committedUsd());
+          })();
+          return closing;
+        }
+      });
+    }
+  });
+  return jev;
+}
+
+export function describeError(error) {
+  const safe = [ConfigError, ServiceError, SpendCapError, RedactionError, RequestSizeError, StateError].some((Type) => error instanceof Type);
+  return safe ? error.message.replace(/[\r\x1b]/g, " ") : "request failed; check file access and network connectivity (no input or key logged)";
+}

package/lib/ledger.mjs

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { SpendCapError, StateError } from "./errors.mjs";
+import { appendRecord, clock, locked, replaceFile } from "./state.mjs";
+
+const HOLD_MS = 10 * 60000;
+const day = (now) => new Date(now).toISOString().slice(0, 10);
+
+function records(file, now) {
+  let text;
+  try { text = readFileSync(file, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return new Map(); throw error; }
+  const latest = new Map();
+  const lines = text.split("\n").filter(Boolean);
+  try {
+    for (const line of lines) {
+      const row = JSON.parse(line);
+      if (typeof row.id !== "string" || typeof row.tool !== "string" || typeof row.day !== "string" || !Number.isFinite(row.at) || !Number.isFinite(row.usd) || row.usd < 0 || !Number.isFinite(row.hold) || row.hold < row.usd || typeof row.closed !== "boolean") throw new Error();
+      latest.set(row.id, row);
+    }
+  } catch { throw new StateError("invalid spend ledger; refusing to spend"); }
+  // Only today's rows count and only yesterday's runs may still close, so compact the rest away
+  // rather than re-reading every past run under the lock
+  const live = new Set([day(now), day(now - 86400000)]);
+  const kept = [...latest.values()].filter((row) => live.has(row.day));
+  if (lines.length - kept.length > Math.max(256, kept.length)) {
+    replaceFile(file, kept.map((row) => `${JSON.stringify(row)}\n`).join(""));
+    return new Map(kept.map((row) => [row.id, row]));
+  }
+  return latest;
+}
+
+function used(rows, today, now, except, tool) {
+  return [...rows.values()].filter((r) => (tool === undefined || r.tool === tool) && r.day === today && r.id !== except).reduce((sum, r) => sum + (!r.closed && now - r.at < HOLD_MS ? r.hold : r.usd), 0);
+}
+
+// The key's ceiling counts every tool on the key; a tool's own ceiling can only lower it
+export function createLedger({ dir, fingerprint, tool, perDayUsd, toolPerDayUsd = Infinity, time = clock }) {
+  const file = path.join(dir, `${fingerprint}.jsonl`);
+  const available = (rows, today, now, except) => Math.min(perDayUsd - used(rows, today, now, except), toolPerDayUsd - used(rows, today, now, except, tool));
+  return {
+    remaining() {
+      return locked(file, () => {
+        const now = time.now();
+        return Math.max(0, available(records(file, now), day(now), now));
+      }, { time });
+    },
+    async open(capUsd, signal) {
+      let row;
+      await locked(file, () => {
+        const now = time.now();
+        row = { id: randomUUID(), tool, day: day(now), at: now, usd: 0, hold: Math.min(capUsd, Math.max(0, available(records(file, now), day(now), now))), closed: false };
+        appendRecord(file, row);
+      }, { signal, time });
+      const update = (total, closed = false) => locked(file, () => {
+        const usd = typeof total === "function" ? total() : total;
+        const now = time.now();
+        const rows = records(file, now);
+        if (row.closed) throw new StateError("run is closed");
+        // A renewed lease or midnight boundary must re-check other processes' holds
+        if (!closed && (day(now) !== row.day || now - row.at >= HOLD_MS)) {
+          if (day(now) !== row.day) throw new SpendCapError("UTC day changed; start a new run");
+          row.hold = Math.min(row.hold, Math.max(row.usd, available(rows, row.day, now, row.id)));
+        }
+        if (!closed && usd > row.hold + 1e-12) throw new SpendCapError("daily spend ceiling reached");
+        row = { ...row, at: now, usd, hold: closed ? usd : Math.max(usd, row.hold), closed };
+        appendRecord(file, row);
+      }, { time });
+      return { capUsd: row.hold, book: (usd) => update(usd), close: (usd) => update(usd, true) };
+    }
+  };
+}

package/lib/limits.mjs

@@ -0,0 +1,101 @@
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { StateError } from "./errors.mjs";
+import { clock, dead, locked, readJson, writeJson } from "./state.mjs";
+
+// A slot is held across the SDK's retries and refreshed at each attempt; an attempt lasts at most
+// 30 seconds and the SDK waits at most a minute before the next, so a slot left this long belongs
+// to a process that stopped without releasing it
+const SLOT_MS = 120000;
+// Another process frees a slot without telling this one, so a waiter looks again this often
+const POLL_MS = 50;
+
+const localWindows = new Map();
+const mine = new Set();
+
+const valid = (state) => Array.isArray(state.starts) && Number.isFinite(state.pausedUntil) && Array.isArray(state.inFlight)
+  && state.starts.every((e) => Number.isFinite(e.at) && Number.isFinite(e.tokens) && e.tokens >= 0)
+  && state.inFlight.every((e) => Number.isFinite(e.at) && typeof e.token === "string" && typeof e.host === "string" && Number.isInteger(e.pid));
+
+// The service counts rate limits per account, not per key, and a key does not reveal its account,
+// so every key on this machine shares one window, one pause and one set of in-flight slots
+export function createLimiter({ dir, limits, notice = () => {}, time = clock }) {
+  const file = path.join(dir, "accounts", "default.json");
+  const rpm = Math.floor(limits.requestsPerMinute * limits.share);
+  const tps = Math.floor(limits.tokensPerSecond * limits.share);
+  let local = false;
+  const transaction = async (job, signal) => {
+    if (!local) {
+      try {
+        return await locked(file, () => {
+          const state = readJson(file, { starts: [], pausedUntil: 0, inFlight: [] });
+          if (!valid(state)) throw new StateError("invalid rate-limit state");
+          const result = job(state);
+          writeJson(file, state);
+          return result;
+        }, { signal, time });
+      } catch (error) {
+        if (!["EACCES", "EPERM", "EROFS", "ENOSPC", "ENOTDIR"].includes(error.code)) throw error;
+        local = true;
+        notice("shared rate-limit state is unwritable; using in-process limits (spend ceilings still apply)");
+      }
+    }
+    if (!localWindows.has(file)) localWindows.set(file, { starts: [], pausedUntil: 0, inFlight: [] });
+    return job(localWindows.get(file));
+  };
+  // Waits for the account's window, then starts one attempt of `tokens` counted tokens. Without
+  // `held`, it also waits for an in-flight slot and takes it
+  const admit = async (tokens, { held, large = false, signal } = {}) => {
+    if (rpm < 1 || tokens > tps) throw new StateError("configured rate limits cannot fit one reserved request; increase DECISION_GATE_RPM or DECISION_GATE_TPS");
+    const slot = held ?? { token: randomUUID(), host: os.hostname(), pid: process.pid, large };
+    for (;;) {
+      signal?.throwIfAborted();
+      const wait = await transaction((state) => {
+        const now = time.now();
+        state.starts = state.starts.filter((e) => e.at > now - 60000);
+        state.inFlight = state.inFlight.filter((e) => e.at > now - SLOT_MS && !dead(e, mine));
+        if (state.pausedUntil > now) return state.pausedUntil - now;
+        let until = now;
+        if (state.starts.length >= rpm) until = Math.max(until, state.starts[state.starts.length - rpm].at + 60000);
+        const recent = state.starts.filter((e) => e.at > now - 1000);
+        let total = recent.reduce((sum, e) => sum + e.tokens, tokens);
+        for (const entry of recent) {
+          if (total <= tps) break;
+          total -= entry.tokens;
+          until = Math.max(until, entry.at + 1000);
+        }
+        if (until > now) return until - now;
+        if (!held && (state.inFlight.length >= limits.inFlight || (large && state.inFlight.filter((e) => e.large).length >= limits.largeInFlight))) return POLL_MS;
+        state.starts.push({ at: now, tokens });
+        state.inFlight = [...state.inFlight.filter((e) => e.token !== slot.token), { ...slot, at: now }];
+        mine.add(slot.token);
+        return 0;
+      }, signal);
+      if (!wait) return slot;
+      await time.sleep(wait, signal);
+    }
+  };
+  return {
+    // Takes an in-flight slot and starts the first attempt of `tokens` counted tokens; `estimated`
+    // is its likely real size, which decides whether it is a large request. The slot is held
+    // until `release`, and `again` starts each retry on it without waiting for a slot
+    async take(tokens, { estimated = tokens, signal } = {}) {
+      const slot = await admit(tokens, { large: estimated >= limits.largeRequestTokens, signal });
+      let released;
+      return {
+        again: (retryTokens, { signal: retrySignal } = {}) => admit(retryTokens, { held: slot, signal: retrySignal }),
+        release() {
+          released ??= transaction((state) => { state.inFlight = state.inFlight.filter((e) => e.token !== slot.token); })
+            // A slot that cannot be released expires on its own, so the answer is not lost to it
+            .catch(() => {})
+            .finally(() => mine.delete(slot.token));
+          return released;
+        }
+      };
+    },
+    async pause(ms) {
+      await transaction((state) => { state.pausedUntil = Math.max(state.pausedUntil, time.now() + ms); });
+    }
+  };
+}

package/lib/providers/index.mjs

@@ -0,0 +1,8 @@
+import { typesafe } from "./typesafe.mjs";
+import { vercelAiGateway } from "./vercel-ai-gateway.mjs";
+
+// A provider must have a known price and typed probabilities before it can own requests, since
+// the ceilings and callers' thresholds depend on both; state is filed under its name so adding
+// one needs no migration
+export const providers = Object.freeze({ [typesafe.name]: typesafe, [vercelAiGateway.name]: vercelAiGateway });
+export const DEFAULT_PROVIDER = typesafe.name;