@volter/twin-cohere 0.1.0

package/src/cohere-budget.ts

@@ -0,0 +1,197 @@
+// Cohere's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveCohereExecute` 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/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 (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 ──────────────────────────────────────────────────────────────
+// Cohere DOES publish scalar per-minute limits, per endpoint AND per key class. Live-read from
+// https://docs.cohere.com/docs/rate-limits on 2026-08-31:
+//   • Chat: TRIAL key 20 req/min across every Command model; PRODUCTION key 500 req/min for
+//     Command A / R+ / R / R7B (the newer A-variants are sales-gated).
+//   • Rerank: TRIAL 10 req/min; production 1,000 req/min.
+//   • EmbedJob: TRIAL 5 req/min; production 50 req/min.
+//   • Audio Transcriptions: TRIAL 5 req/min.
+//   • Tokenize: TRIAL 100 req/min; production 2,000 req/min.
+//   • Embed (text): 2,000 INPUTS/min on both key classes; Embed (images) 5 inputs/min trial.
+//   • Parse and "Default (other)": 500 req/min on both classes.
+//
+// THE TRIAL NUMBERS BIND, and they are LOWER than the kernel's undeclared fallback. That fallback
+// (`DEFAULT_RATE_BUDGET`) is 60 units / 60s at defaultWeight 2 — 30 calls a minute — which already
+// exceeds Cohere's 20/min trial chat limit and is 6x its 5/min EmbedJob limit. A pack must only be
+// MORE PERMISSIVE than the fallback when the live first-party source justifies it; here the source
+// justifies being TIGHTER, so this declaration is tighter.
+//
+// The ceiling is 20 weighted units per 60s. At the default weight of 2 that is 10 calls a minute:
+// half of the tightest limit that applies to a plain call (chat, 20/min trial) and comfortably
+// under the 5/min EmbedJob floor once that endpoint's own weight is applied.
+//
+// The window bounds the 60-second AVERAGE; it does NOT pace (the kernel refuses, it never sleeps).
+// So the honest claim is "bounds the minute and converts the vendor's first 429/`retry-after` into
+// a hard stop", not "refuses before the vendor ever 429s".
+//
+// ── HOW THE WEIGHTS WERE CHOSEN ─────────────────────────────────────────────────────────────
+// Cohere counts REQUESTS per endpoint, and the per-endpoint limits differ by two orders of
+// magnitude, so pricing by endpoint is reproducing the vendor's own scheme rather than proxying
+// it. Each weight below is the fallback weight scaled by how much scarcer that endpoint's trial
+// allowance is than chat's:
+//   • `POST /v1/embed-jobs` costs 8 — a 5/min trial allowance, four times scarcer than chat's 20.
+//   • `POST /v2/rerank` / `POST /v1/rerank` cost 4 — a 10/min trial allowance, twice as scarce.
+//   • `POST /v2/chat` / `POST /v1/chat` cost 2 (the default) — the 20/min anchor.
+//   • `POST /v1/tokenize` costs 1 — a 100/min trial allowance, five times more generous.
+//
+// Everything unclassified costs `defaultWeight`; nothing is ever free. WHICH published row binds an
+// unclassified call is a deliberate choice worth stating, because the arithmetic is otherwise
+// uncheckable against the source it cites (§9 round 1, m5): the endpoints this connector actually
+// drives — `GET /v1/{datasets,connectors,embed-jobs}` and the connector CRUD — fall under Cohere's
+// "Default (other)" row at 500/min, NOT under chat's 20/min. They are nonetheless priced at the
+// CHAT anchor, i.e. 25x tighter than the vendor allows. That is deliberate: the per-endpoint
+// figures for this set are not individually published, and the cost asymmetry is stark — a
+// too-tight default costs a refused call plus a one-line declaration, a too-loose one costs days of
+// lockout.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'cohere';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const COHERE_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 20/60s at the default weight of 2 is 10 calls a
+ * minute — HALF Cohere's tightest broadly-applicable published limit (chat, 20 req/min on a trial
+ * key) and tighter than the kernel's undeclared fallback, because Cohere's trial limits are below
+ * that fallback.
+ */
+export const COHERE_BUDGET_CEILING = 20;
+
+/** Seconds. A `retry-after` above this means the org is throttled hard — fail loudly, don't sleep. */
+export const COHERE_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for the arithmetic. */
+export const COHERE_CALL_WEIGHTS = {
+  /** `POST /v1/embed-jobs` — a 5 req/min trial allowance, the scarcest endpoint this pack drives. */
+  embedJob: 8,
+  /** `POST /v2/rerank`, `POST /v1/rerank` — a 10 req/min trial allowance. */
+  rerank: 4,
+  /** Chat and everything unclassified — the 20 req/min trial anchor. */
+  other: 2,
+  /** `POST /v1/tokenize` — a 100 req/min trial allowance, the most generous endpoint modeled. */
+  tokenize: 1,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Cohere-specific thing in the whole budget. */
+export const COHERE_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: COHERE_BUDGET_WINDOW_MS,
+  ceiling: COHERE_BUDGET_CEILING,
+  defaultWeight: COHERE_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: COHERE_BUDGET_MAX_RETRY_AFTER_S,
+  // Ordered, first match wins. Every pattern is ANCHORED at both ends so a longer path cannot
+  // borrow a cheaper endpoint's price.
+  rules: [
+    { match: '^POST /v1/embed-jobs$', weight: COHERE_CALL_WEIGHTS.embedJob },
+    { match: '^POST /v2/rerank$', weight: COHERE_CALL_WEIGHTS.rerank },
+    { match: '^POST /v1/rerank$', weight: COHERE_CALL_WEIGHTS.rerank },
+    { match: '^POST /v1/tokenize$', weight: COHERE_CALL_WEIGHTS.tokenize },
+  ],
+  reason:
+    'Cohere publishes scalar per-minute limits per endpoint AND per key class ' +
+    '(https://docs.cohere.com/docs/rate-limits, read 2026-08-31): chat 20 req/min on a TRIAL key ' +
+    'and 500 on production; rerank 10 trial / 1,000 production; EmbedJob 5 trial / 50 production; ' +
+    'tokenize 100 trial / 2,000 production; embed metered in inputs (2,000/min); "default (other)" ' +
+    '500. The TRIAL numbers bind, and they are BELOW the kernel fallback (30 calls/min), so this ' +
+    'declaration is deliberately TIGHTER than the fallback rather than more permissive: 20 weighted ' +
+    'units / 60s at defaultWeight 2 is 10 calls a minute, half the 20/min trial chat limit. Weights ' +
+    'reproduce the vendor\'s own per-endpoint scarcity — embed-jobs 8 (5/min), rerank 4 (10/min), ' +
+    'chat/default 2 (20/min), tokenize 1 (100/min). UNCLASSIFIED calls take the chat anchor rather ' +
+    'than the "default (other)" row that actually governs them (the connector\'s own endpoints are ' +
+    'in that 500/min bucket), i.e. 25x tighter than the vendor allows — deliberate, because those ' +
+    'per-endpoint figures are not individually published and a too-tight default costs a refused ' +
+    'call while a too-loose one costs days of lockout. The window bounds the 60s AVERAGE and does ' +
+    'not pace; the 429 / retry-after cooldown is the backstop for a shorter enforcement horizon.',
+};
+
+// Declared at module load, so merely importing this module (which `cohere-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET, which here is strictly LOOSER (30 calls/min vs 10), so the ordering genuinely
+// matters — constructing through the subclass below (which imports this module) is what makes it a
+// non-issue in practice.
+declareRateBudget(VENDOR, COHERE_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 Cohere.
+ * An unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function cohereCallWeight(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: `fetch` upper-cases a
+ * known method before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule
+ * would otherwise 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 "scarce 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);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Cohere's ledger lives. Token-keyed and cwd-independent by default (the limit is per API
+ *  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 cohereBudgetPath(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 Cohere's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type CohereBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Cohere's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof CohereBudget` in `liveCohereExecute` means "a budget that
+ * accounts against COHERE's ledger under COHERE's ceiling": another vendor's `RateBudget` (with
+ * its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class CohereBudget extends RateBudget {
+  constructor(opts: CohereBudgetOptions = {}) {
+    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 CohereBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as CohereBudgetErrorKind } from '@volter/world-core';
+export type CohereBudgetReservation = RateBudgetReservation;
+export type CohereBudgetSnapshot = RateBudgetSnapshot;