@volter/twin-openai 0.1.0

package/src/openai-budget.ts

@@ -0,0 +1,173 @@
+// OpenAI's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveOpenAIExecute` uses. 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/twin` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN: NO SCALAR IS PUBLISHED ──────────────────────────────────────
+// Unlike Notion or Cal.com, OpenAI publishes NO scalar per-key request limit. From
+// https://developers.openai.com/api/docs/guides/rate-limits (read 2026-07-26): limits are per
+// ORGANIZATION and PROJECT, expressed in RPM/RPD/TPM/TPD/IPM, and they differ PER MODEL and per
+// tier — the actual figures live on the account's own limits page, not in the docs. The docs carry
+// exactly one scalar this pack could be bound by: Vector Store ingestion is 300 requests per minute
+// per vector store ID. The Batch API's limit is a queued-input-TOKEN quota, not an RPM.
+//
+// So this budget deliberately does NOT model the vendor's limit, and the numbers below are NOT
+// derived from one. Because there is no documented figure to justify going higher, the ceiling is
+// pinned at the kernel's own undeclared fallback in every dimension: 60 weighted units per 60s at
+// `defaultWeight` 2 — 30 calls a minute, exactly `DEFAULT_RATE_BUDGET`, with no endpoint priced
+// CHEAPER than the fallback would price it. What this declaration adds over the fallback is
+// therefore not headroom, it is RESOLUTION: the endpoints that cost real money get priced up.
+//
+// It bounds the 60s AVERAGE; it does not pace (the kernel refuses, it never sleeps). The backstop
+// for a sub-second burst is the cooldown: OpenAI's `x-ratelimit-remaining-requests: 0` and its
+// `retry-after` are both read off the response and turn into a persisted refusal.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ───────────────────────────────
+// OpenAI counts requests per endpoint family, so a flat price is the faithful default. Two
+// deliberate exceptions, both judgement calls rather than published costs:
+//   • The token-metered inference paths (`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`,
+//     `/v1/images/*`, `/v1/audio/*`) cost 5. There TPM — not RPM — is the binding limit, so one
+//     request is worth far more of the org's real allowance than a file-list poll. The connector
+//     never calls them, but the executor is generic and a caller could; an unclassified expensive
+//     endpoint is exactly the shape that caused the lockout.
+//   • Vector-store FILE ingestion costs 4, because it is the one endpoint with a documented
+//     per-minute scalar (300/min per store) AND the recursive fan-out shape — one store ingest is a
+//     loop over every file. At weight 4 at most 15 land in a window, a twentieth of that 300.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/twin';
+
+const VENDOR = 'openai';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const OPENAI_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because OpenAI publishes no scalar that would justify
+ * more. See the header.
+ */
+export const OPENAI_BUDGET_CEILING = 60;
+
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const OPENAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const OPENAI_CALL_WEIGHTS = {
+  /** `/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*` —
+   *  token/compute-metered, where TPM rather than RPM is the binding limit. */
+  inference: 5,
+  /** `POST /v1/vector_stores/:id/files` — documented 300 RPM per store, and a per-file fan-out. */
+  ingest: 4,
+  /** Everything else: file/batch/fine-tune/vector-store list, retrieve, create, cancel, delete. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only OpenAI-specific thing in the whole budget. */
+export const OPENAI_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: OPENAI_BUDGET_WINDOW_MS,
+  ceiling: OPENAI_BUDGET_CEILING,
+  defaultWeight: OPENAI_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: OPENAI_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /v1/(chat/completions|responses|embeddings|moderations)$', weight: OPENAI_CALL_WEIGHTS.inference },
+    { match: '^POST /v1/(images|audio|realtime|videos)/', weight: OPENAI_CALL_WEIGHTS.inference },
+    { match: '^POST /v1/vector_stores/[^/]+/files', weight: OPENAI_CALL_WEIGHTS.ingest },
+  ],
+  reason:
+    'OpenAI publishes NO scalar per-key request limit (developers.openai.com/api/docs/guides/' +
+    'rate-limits, read 2026-07-26): limits are per organization and project, in RPM/RPD/TPM/TPD/IPM, ' +
+    "differ per model and tier, and the figures live on the account's own limits page. The one " +
+    'documented scalar that can bind this pack is Vector Store ingestion at 300 requests/minute per ' +
+    'store. Because no published figure justifies going higher, the ceiling is pinned at the kernel ' +
+    "fallback in EVERY dimension — 60 units / 60s at defaultWeight 2 = 30 calls/min, and no endpoint " +
+    'is priced cheaper than the fallback would price it; the declaration buys resolution, not ' +
+    'headroom. Inference paths cost 5 (TPM, not RPM, binds them) and vector-store file ingestion ' +
+    'costs 4 (the documented 300/min scalar, and a per-file fan-out) — judgement calls, not published ' +
+    'costs. The window bounds the 60s AVERAGE and does not pace; the 429/`x-ratelimit-remaining-*: 0` ' +
+    'cooldown is the backstop for a sub-second burst.',
+};
+
+// Declared at module load, so merely importing this module (which `openai-connector.ts` does) is
+// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
+// takes effect the moment it lands, and constructing through the subclass below (which imports this
+// module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, OPENAI_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about OpenAI. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function openaiCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the query.
+ *
+ * NORMALIZED, because the anchored rules are otherwise trivially evaded (§9 finding, 2026-07-26):
+ * `fetch` upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE
+ * that a `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor
+ * while most routers treat it as the same endpoint. Both are input variations, not attacks, and
+ * either one silently voids the "expensive endpoints are priced up" claim the ceiling rests on.
+ */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  // Collapse a trailing slash, but never turn the root path into the empty string.
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where OpenAI's ledger lives. Token-keyed and cwd-independent by default (the limit is per
+ *  organization/project, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh
+ *  allowance in every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function openaiBudgetPath(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 to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for OpenAI's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type OpenAIBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * OpenAI's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof OpenAIBudget` in `liveOpenAIExecute` means "a budget that
+ * accounts against OPENAI's ledger under OPENAI's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class OpenAIBudget extends RateBudget {
+  constructor(opts: OpenAIBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as OpenAIBudgetError } from '@volter/twin';
+export type { RateBudgetErrorKind as OpenAIBudgetErrorKind } from '@volter/twin';
+export type OpenAIBudgetReservation = RateBudgetReservation;
+export type OpenAIBudgetSnapshot = RateBudgetSnapshot;