@volter/twin-planetscale 0.1.0

package/src/planetscale-budget.ts

@@ -0,0 +1,347 @@
+// PLANETSCALE'S CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus
+// `guardPlanetscaleClient`, the choke point every live PlanetScale call goes through. The MECHANISM
+// — the durable token-keyed ledger, the rolling window, reserve-under-lock, the `Retry-After`/429
+// cooldown, fail-CLOSED on a corrupt ledger — lives ONCE in the vendor-agnostic kernel
+// (`@volter/world-core` → `rateBudget.ts`). Read that module's header for the full rationale AND for the
+// honest list of what the guard does NOT guarantee. This module is modeled on
+// `notion-budget.ts` / `upstash-budget.ts`, the reference injected-client decorators.
+//
+// ── THE NUMBER, AND WHY IT IS THE KERNEL FALLBACK RATHER THAN A TRANSCRIBED LIMIT ─────────────
+// PlanetScale publishes system limits and this build LIVE-READ them
+// (planetscale.com/docs/reference/planetscale-system-limits, 2026-08-31). Every published figure is
+// a PER-QUERY or PER-SCHEMA bound, not a rate:
+//     • per-query rows returned/updated/deleted: 100k       • per-query result set: 64 MiB
+//     • autocommit timeout: 900s                            • transaction timeout: 20s
+//     • tables per schema: 2048                             • columns per table: 1017
+// There is NO published requests-per-second or requests-per-minute figure for the psdb HTTP API,
+// and this build did not find one. Per ADDING_A_TWIN's rule for exactly that case, the reason says
+// so plainly and the ceiling stays AT the kernel's austere fallback — 60 units / 60s at the default
+// weight of 2 = 30 calls per minute — rather than dressing a guess up as a vendor fact. Nothing
+// here is more permissive than `DEFAULT_RATE_BUDGET`, so no `VENDOR_BURST_ANCHOR` figure is owed.
+//
+// ── WHAT THE RISK ACTUALLY IS ─────────────────────────────────────────────────────────────────
+// PlanetScale meters ROWS READ, not requests. One `SELECT` against a large table is a single call
+// that can read millions of rows, so a request-count ceiling bounds the SHAPE of a runaway loop
+// without bounding its cost. That is a real limitation of a request-count guard against this vendor
+// and it is stated rather than papered over: the connector's own defence is that every pull takes a
+// hard result `limit` (not a storage rows-examined guarantee), and `transaction` is priced at 4x because ONE guarded call fans out into an
+// unbounded number of statements behind it (`Connection.transaction` in dist/index.js runs the
+// caller's whole callback).
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  RateBudgetError,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+import type { PlanetscaleLikeClient } from './planetscale-connector.ts';
+
+const VENDOR = 'planetscale';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const PLANETSCALE_BUDGET_WINDOW_MS = 60_000;
+
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export const PLANETSCALE_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export const PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export const PLANETSCALE_CALL_WEIGHTS = {
+  /** `transaction` — ONE guarded call that runs an unbounded number of statements behind it. */
+  transaction: 8,
+  /** `execute` / `refresh` / anything unclassified. */
+  other: 2,
+} as const;
+
+/**
+ * The client methods this pack PRICES BY NAME. `@planetscale/database`'s `Client` and `Connection`
+ * expose exactly these three (dist/index.d.ts), and the connector calls only `execute`.
+ *
+ * NOT a closed list: a method absent from it is still priced at `defaultWeight` through the
+ * passthrough proxy. An unmodeled call must never be free — free would also make it invisible.
+ */
+export const PLANETSCALE_BUDGETED_METHODS = ['execute', 'transaction', 'refresh'] as const;
+
+/** THE PACK'S DECLARATION — pure data, the only PlanetScale-specific thing in the whole budget. */
+export const PLANETSCALE_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: PLANETSCALE_BUDGET_WINDOW_MS,
+  ceiling: PLANETSCALE_BUDGET_CEILING,
+  defaultWeight: PLANETSCALE_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S,
+  // Ordered: the kernel prices FIRST-MATCH-WINS, so the most expensive tier is listed first.
+  rules: [
+    { match: '(^|\\.)transaction$', weight: PLANETSCALE_CALL_WEIGHTS.transaction },
+  ],
+  reason:
+    'PlanetScale publishes NO requests-per-second or requests-per-minute limit for the psdb HTTP API. Its '
+    + 'system-limits page (https://planetscale.com/docs/reference/planetscale-system-limits, live-read '
+    + '2026-08-31) publishes only PER-QUERY and PER-SCHEMA bounds: 100k rows returned/updated/deleted per '
+    + 'query, a 64 MiB per-query result set, a 900s autocommit timeout, a 20s transaction timeout, 2048 tables '
+    + 'per schema and 1017 columns per table. None of those is a call rate, so — per the ADDING_A_TWIN rule for '
+    + 'a vendor that publishes no scalar rate — this declaration states that plainly and stays AT the kernel '
+    + "fallback (60 units / 60s at weight 2 = 30 calls per minute) instead of inventing a number. It is "
+    + 'therefore never more permissive than DEFAULT_RATE_BUDGET and owes no VENDOR_BURST_ANCHOR figure. The '
+    + 'real cost driver is metered ROWS READ rather than request count, which a request-count ceiling can only '
+    + 'bound crudely; that limitation is disclosed rather than hidden, and the connector answers it separately '
+    + 'by bounding returned pages on every pull; SQL LIMIT does not cap rows examined or billed. `transaction` is priced at 8 because ONE guarded call runs '
+    + "the caller's entire callback — an unbounded number of statements — behind it "
+    + '(@planetscale/database@1.20.1 dist/index.js, `Connection.transaction`).',
+};
+
+// Declared at module load, so merely importing this module (which `planetscale-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, PLANETSCALE_RATE_BUDGET);
+
+/** Price one PlanetScale call by its client method name (`execute`, `transaction`, …). */
+export function planetscaleCallWeight(method: string): number {
+  return rateBudgetWeight(VENDOR, method);
+}
+
+/** Where PlanetScale's ledger lives. Token-keyed and cwd-independent by default (the vendor meters
+ *  per credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function planetscaleBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for PlanetScale's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type PlanetscaleBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * PlanetScale's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof PlanetscaleBudget` means "a budget that accounts
+ * against this vendor's ledger under this vendor's ceiling".
+ */
+export class PlanetscaleBudget extends RateBudget {
+  constructor(opts: PlanetscaleBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export type { RateBudgetErrorKind as PlanetscaleBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as PlanetscaleBudgetError } from '@volter/world-core';
+export type PlanetscaleBudgetReservation = RateBudgetReservation;
+export type PlanetscaleBudgetSnapshot = RateBudgetSnapshot;
+
+/** What every budgeted connector entrypoint accepts. There is deliberately no option that turns the
+ *  guard OFF — only ones that say WHICH ledger and clock to account against. */
+export type PlanetscaleBudgetedOptions = {
+  /** An existing budget to share across calls. Omit and one is constructed. Cannot be null. */
+  budget?: PlanetscaleBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: PlanetscaleBudgetOptions;
+};
+
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export function planetscaleBudgetOf(opts: PlanetscaleBudgetedOptions): PlanetscaleBudgetedOptions {
+  return {
+    ...(opts.budget !== undefined ? { budget: opts.budget } : {}),
+    ...(opts.budgetOptions !== undefined ? { budgetOptions: opts.budgetOptions } : {}),
+  };
+}
+
+// ── the choke point ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Marks a client this module has already wrapped, so guarding twice cannot charge twice.
+ *
+ * A MODULE-PRIVATE `Symbol()`, deliberately not `Symbol.for()`: a global-registry symbol is
+ * reachable BY NAME, so any caller could stamp the brand on a RAW client and the guard would hand it
+ * straight back UNGUARDED — a one-line bypass of the whole budget.
+ */
+const GUARDED: unique symbol = Symbol('@volter/twin-planetscale.budget.guarded');
+
+type Guarded = { [GUARDED]?: unknown };
+
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export function planetscaleClientBudget(client: unknown): RateBudget | undefined {
+  const mark = (client as Guarded | null)?.[GUARDED];
+  return mark instanceof RateBudget ? mark : undefined;
+}
+
+const NEVER_WRAP = new Set(['then', 'catch', 'finally', 'constructor', 'prototype', 'toJSON', 'toString', 'valueOf', 'inspect']);
+
+/** The HTTP status a value carries, if it looks like one (an SDK error, or a raw response). */
+function responseStatus(v: unknown): number | undefined {
+  const s = (v as { status?: unknown } | null)?.status;
+  return typeof s === 'number' && Number.isFinite(s) ? s : undefined;
+}
+
+/**
+ * Response/error headers as a plain lower-cased record, or `undefined` when there are none. Accepts
+ * a `Headers` instance, a `Map`, or a plain object — `DatabaseError`/`UnknownError` carry a
+ * `context.headers` record (dist/index.js), and a raw `Response` carries a `Headers`.
+ */
+function responseHeaders(v: unknown): Record<string, string> | undefined {
+  const direct = (v as { headers?: unknown } | null)?.headers;
+  const nested = (v as { context?: { headers?: unknown } } | null)?.context?.headers;
+  const h = direct ?? nested;
+  if (!h || typeof h !== 'object') return undefined;
+  const out: Record<string, string> = {};
+  if (typeof (h as Headers).forEach === 'function') {
+    (h as Headers).forEach((value: string, key: string) => { out[String(key).toLowerCase()] = String(value); });
+  } else {
+    for (const [k, value] of Object.entries(h as Record<string, unknown>)) out[k.toLowerCase()] = String(value);
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+// Guard ownership stays module-private; known deployment batches can reserve once without
+// exposing an unguarded client to callers or interrupting rollback with a second admission.
+const rawClients = new WeakMap<object, PlanetscaleLikeClient>();
+function settleBudget(budget: RateBudget, weight: number, reservation: RateBudgetReservation, value: unknown): void {
+  if (value instanceof AggregateError) {
+    for (const error of value.errors) settleBudget(budget, weight, reservation, error);
+    return;
+  }
+  budget.recordCall(weight, responseHeaders(value), { status: responseStatus(value), reservation });
+}
+/** Settle once the call RESOLVED: PlanetScale has answered. recordCall arms any cooldown before it
+ *  throws (a back-off beyond the cap), so that refusal is swallowed and the result kept — a write
+ *  that committed is never reported failed and run again on retry. A non-2xx status still throws. */
+function settleAnswered(budget: RateBudget, weight: number, reservation: RateBudgetReservation, value: unknown): void {
+  try {
+    settleBudget(budget, weight, reservation, value);
+  } catch (error) {
+    const status = responseStatus(value);
+    if (!(error instanceof RateBudgetError) || (status !== undefined && (status < 200 || status >= 300))) throw error;
+  }
+}
+async function charged<T>(budget: RateBudget, weight: number, invoke: () => Promise<T>): Promise<T> {
+  const reservation = budget.checkBudget(weight);
+  try {
+    const result = await invoke(); settleAnswered(budget, weight, reservation, result); return result;
+  } catch (error) { settleBudget(budget, weight, reservation, error); throw error; }
+}
+
+/** Reserve every known row call plus session, BEGIN, COMMIT and possible ROLLBACK before IO. */
+export async function runPlanetscaleTransaction<T>(client: PlanetscaleLikeClient, statementCount: number,
+  run: (tx: unknown) => Promise<T>, opts: PlanetscaleBudgetedOptions = {},
+): Promise<T> {
+  if (!Number.isSafeInteger(statementCount) || statementCount < 0) throw new Error('Invalid PlanetScale statement count');
+  const guarded = guardPlanetscaleClient(client, opts);
+  const raw = rawClients.get(guarded)!;
+  if (!raw?.transaction) throw new Error('PlanetScale deployment requires a transactional client');
+  const budget = planetscaleClientBudget(guarded)!;
+  return charged(budget, Math.max(budget.weightFor('transaction'), (statementCount + 4) * budget.weightFor('execute')), () => raw.transaction!(run));
+}
+
+/**
+ * Wrap an INJECTED PlanetScale client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack never constructs the transport itself (the consumer injects
+ * something satisfying `PlanetscaleLikeClient` — a real `Client` or `Connection` is assignable
+ * as-is), so the guard is a DECORATOR rather than a factory, which is exactly why every connector
+ * entrypoint applies it UNCONDITIONALLY instead of trusting the caller.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged.
+ *
+ * A method that THROWS is still inspected: `@planetscale/database` RAISES `DatabaseError` /
+ * `UnknownError` on a non-2xx rather than returning it, and that error's status and headers are
+ * exactly the signal that must become a persisted cooldown. The original error is always re-raised
+ * afterwards — EXCEPT when the back-off is beyond the cap, where the budget's own louder "stop
+ * calling" error takes precedence.
+ */
+export function guardPlanetscaleClient(client: PlanetscaleLikeClient, opts: PlanetscaleBudgetedOptions = {}): PlanetscaleLikeClient {
+  // There is no value a caller can pass to end up with an UNGUARDED client. Validated BEFORE the
+  // already-guarded early return, so `guard(alreadyGuarded, { budget: impostor })` is refused too.
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof PlanetscaleBudget)) {
+    throw new Error('guardPlanetscaleClient: `budget` must be a PlanetscaleBudget — refusing to guard a PlanetScale client with an unverified rate guard');
+  }
+  if (planetscaleClientBudget(client)) return client;
+  const budget = opts.budget instanceof PlanetscaleBudget
+    ? opts.budget
+    : new PlanetscaleBudget({
+      // The default ledger is keyed by a hash of the credential — the vendor meters per credential,
+      // so a cwd-scoped ledger would hand it a fresh allowance per worktree/CI leg.
+      //
+      // HONESTLY: this pack does NOT hold the credential — the consumer's injected client does — so
+      // `PLANETSCALE_DATABASE_URL` is a BEST-EFFORT stand-in, not the real thing. If it names a
+      // different database than the injected client, spend is booked against the wrong ledger; if it
+      // is unset, every unattributed PlanetScale credential on the machine shares one (over-tight,
+      // the safe direction). A caller who knows the credential says so with `budgetOptions: { token }`,
+      // which is spread last and therefore wins.
+      ...(process.env.PLANETSCALE_DATABASE_URL !== undefined ? { token: process.env.PLANETSCALE_DATABASE_URL } : {}),
+      ...(opts.budgetOptions ?? {}),
+    });
+
+  /** Settle a reservation from whatever the call produced. May THROW (a back-off past the cap). */
+  const settle = (weight: number, reservation: RateBudgetReservation, value: unknown): void => settleBudget(budget, weight, reservation, value);
+
+  /**
+   * Charge, call, settle. Refusing REJECTS rather than throwing synchronously, so
+   * `client.execute(...).catch(…)` behaves exactly as it does on an unguarded client.
+   * `checkBudget` RESERVES under lock, so nothing after its line runs when the budget refuses:
+   * the request is never made.
+   */
+  const chargeAsync = (method: string, invoke: (...args: unknown[]) => unknown) =>
+    async (...args: unknown[]): Promise<unknown> => charged(budget, budget.weightFor(method), async () => invoke(...args));
+
+  const guarded: Record<string, unknown> & Guarded = {};
+  for (const name of PLANETSCALE_BUDGETED_METHODS) {
+    const raw = (client as unknown as Record<string, unknown>)[name];
+    if (typeof raw !== 'function') continue;
+    // Resolved at CALL time, not here, so a client whose method is swapped later is still charged.
+    guarded[name] = chargeAsync(name, (...args) => ((client as unknown as Record<string, unknown>)[name] as (...a: unknown[]) => unknown).apply(client, args));
+  }
+  Object.defineProperty(guarded, GUARDED, { value: budget, enumerable: false });
+
+  // A real client has MORE than the three methods above (`connection()`, `config`, …) and a consumer
+  // who needs one must not be forced to keep the RAW client alongside — every call through that
+  // would be unbudgeted. So the guarded object is a Proxy: modeled members come from the map above,
+  // anything else is taken from the real client and PRICED at `defaultWeight`.
+  const proxy = new Proxy(guarded, {
+    get(target, prop, receiver) {
+      if (typeof prop === 'symbol') {
+        const own = Reflect.get(target, prop, receiver);
+        return own !== undefined ? own : (client as unknown as Record<symbol, unknown>)[prop];
+      }
+      const name = String(prop);
+      if (NEVER_WRAP.has(name)) return Reflect.get(target, prop, receiver);
+      const own = Reflect.get(target, prop, receiver);
+      if (own !== undefined) return own;
+      const from = (client as unknown as Record<string, unknown>)[name];
+      // `connection()` returns a NEW Connection whose `execute` would otherwise escape the budget
+      // entirely, so a function member is charged AND its result is re-guarded when it looks like a
+      // client. Anything else passes through.
+      if (typeof from === 'function') {
+        return (...args: unknown[]) => {
+          const weight = budget.weightFor(name);
+          const reservation = budget.checkBudget(weight);
+          let out: unknown;
+          try {
+            out = (from as (...a: unknown[]) => unknown).apply(client, args);
+          } catch (e) {
+            settle(weight, reservation, e);
+            throw e;
+          }
+          if (out !== null && typeof out === 'object' && typeof (out as { then?: unknown }).then === 'function') {
+            return (out as Promise<unknown>).then(
+              (res) => { settleAnswered(budget, weight, reservation, res); return res; },
+              (e: unknown) => { settle(weight, reservation, e); throw e; },
+            );
+          }
+          settle(weight, reservation, undefined);
+          if (out !== null && typeof out === 'object' && typeof (out as { execute?: unknown }).execute === 'function') {
+            return guardPlanetscaleClient(out as PlanetscaleLikeClient, { budget });
+          }
+          return out;
+        };
+      }
+      return from;
+    },
+    has(target, prop) {
+      return Reflect.has(target, prop) || Reflect.has(client as object, prop);
+    },
+  }) as unknown as PlanetscaleLikeClient;
+  rawClients.set(proxy, client);
+  return proxy;
+}