cartethyia 2.5.10 → 2.6.0

package/src/providers/quota/quota-contracts.ts

@@ -1,4 +1,5 @@
 import { decodeJwtPayload } from "../authentication/oauth-flow-store";
+import { asCoercedNumber, asRecord as sharedAsRecord } from "../../shared/coerce";
 
 export interface ProviderQuotaWindow {
   readonly kind: string;
@@ -112,9 +113,7 @@ function creditWindowBalance(
 const TIMEOUT_MS = 15_000;
 
 export function record(value: unknown): Record<string, unknown> | null {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
+  return sharedAsRecord(value) ?? null;
 }
 
 export function text(value: unknown): string | null {
@@ -122,10 +121,7 @@ export function text(value: unknown): string | null {
 }
 
 export function number(value: unknown): number | null {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
-    return Number(value);
-  return null;
+  return asCoercedNumber(value) ?? null;
 }
 
 export function isoDate(value: unknown): string | null {

package/src/providers/search/search-provider.ts

@@ -1,3 +1,5 @@
+import { asRecord } from "../../shared/coerce";
+
 /**
  * Declarative web-search provider adapters.
  *
@@ -42,12 +44,6 @@ export interface SearchProviderSpec {
   readonly normalize: (data: unknown) => readonly WebSearchResult[];
 }
 
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
 function stringField(record: Record<string, unknown> | undefined, key: string): string {
   const value = record?.[key];
   return typeof value === "string" ? value : "";

package/src/security/admission/contracts.ts

@@ -44,6 +44,16 @@ export interface AdmissionReserveRequest {
   readonly lifetimeBudget: number | null;
   readonly lifetimeConsumed: number;
   readonly concurrencyLimit: number | null;
+  /**
+   * Hidden allowance added on top of `concurrencyLimit`.
+   *
+   * The configured limit is what an operator tunes and what the error names;
+   * this is deliberate slack so a run that lands a few requests over does not
+   * get refused at the number it was told. Effective max is
+   * `concurrencyLimit + concurrencyTolerance`. Only requests *beyond* that are
+   * refused — never ones already admitted.
+   */
+  readonly concurrencyTolerance?: number | null | undefined;
   readonly tenantId: string;
   readonly tenantConcurrencyLimit: number | null;
   /**

package/src/security/admission/in-memory-store.ts

@@ -20,6 +20,16 @@ interface InMemoryReservation {
   readonly monthlyKey: string;
   readonly tracksLifetime: boolean;
   readonly tracksConcurrency: boolean;
+  /**
+   * The key the concurrency counter was incremented under.
+   *
+   * Not `apiKeyId`: a share child reserves under its own id while the
+   * reservation is recorded against its parent, so charging and refunding
+   * through `apiKeyId` incremented one counter and decremented another. The
+   * child's count then never fell — after `limit` requests it was permanently
+   * full and refused everything, which is the "never invoked again" symptom.
+   */
+  readonly concurrencyKey: string;
   readonly tenantId: string;
   readonly tracksTenantConcurrency: boolean;
   state: "active" | "committed" | "released";
@@ -36,9 +46,57 @@ const TERMINAL_RESERVATION_CAP = 10_000;
 const COUNTER_MAP_CAP = 20_000;
 
 
+/**
+ * Per-key RPM timestamp queue.
+ *
+ * Entries are appended in nondecreasing `now` order (requests are admitted
+ * under the store's exclusive gate, each stamped with its own `now`), so the
+ * window prefix is monotone: pruning advances a head index past every entry
+ * `<= cutoff` without copying the surviving suffix, and the array is compacted
+ * only when the consumed prefix exceeds half of it. Per request this is O(1)
+ * amortized instead of the previous per-request full-array rewrite.
+ *
+ * Exposed surface mirrors what the reserve path needs: `length` (window count
+ * for the limit check), `push` (append on admit), and `prune` (advance the
+ * window). `purge()` drops the whole key from the outer map.
+ */
+class RpmTimestampQueue {
+  private entries: number[] = [];
+  private head = 0;
+
+  get length(): number {
+    return this.entries.length - this.head;
+  }
+
+  push(now: number): void {
+    this.entries.push(now);
+  }
+
+  /**
+   * Drops every entry `<= cutoff`. An entry exactly one window old is expired
+   * (the existing exact-boundary semantics: `cutoff = now - window`, so an
+   * entry at `now - window` equals the cutoff and is dropped).
+   */
+  prune(now: number, windowMs: number): void {
+    const cutoff = now - windowMs;
+    while (this.head < this.entries.length && this.entries[this.head]! <= cutoff) {
+      this.head += 1;
+    }
+    if (this.head > this.entries.length / 2) {
+      this.entries = this.entries.slice(this.head);
+      this.head = 0;
+    }
+  }
+
+  /** True when no live entries remain — the caller deletes the bucket. */
+  isEmpty(): boolean {
+    return this.length === 0;
+  }
+}
+
 /** Atomic single-process admission store used by tests and single-process development. */
 export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
-  private readonly rpmTimestamps = new Map<string, number[]>();
+  private readonly rpmTimestamps = new Map<string, RpmTimestampQueue>();
   private readonly daily = new Map<string, number>();
   private readonly monthly = new Map<string, number>();
   private readonly lifetime = new Map<string, number>();
@@ -145,8 +203,19 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
         lifetime + request.estimatedTokens > request.lifetimeBudget
       )
         throw reasonToGatewayError("lifetime-token-budget", { limit: request.lifetimeBudget });
-      if (request.concurrencyLimit != null && concurrent >= request.concurrencyLimit)
-        throw reasonToGatewayError("concurrency-limit", { limit: request.concurrencyLimit });
+      // The tolerance is slack above the configured limit, so the ceiling is
+      // the sum. It widens admission only: requests already inside are never
+      // revisited, and the refusal still names the configured limit.
+      const concurrencyCeiling =
+        request.concurrencyLimit !== null
+          ? request.concurrencyLimit + Math.max(0, request.concurrencyTolerance ?? 0)
+          : null;
+      if (concurrencyCeiling !== null && concurrent >= concurrencyCeiling)
+        throw reasonToGatewayError("concurrency-limit", {
+          limit: request.concurrencyLimit,
+          tolerance: request.concurrencyTolerance ?? 0,
+          effectiveLimit: concurrencyCeiling,
+        });
       if (
         request.tenantConcurrencyLimit != null &&
         tenantConcurrent >= request.tenantConcurrencyLimit
@@ -182,6 +251,7 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
         monthlyKey,
         tracksLifetime: request.lifetimeBudget != null,
         tracksConcurrency: request.concurrencyLimit != null,
+        concurrencyKey: rpmConcId,
         tenantId: request.tenantId,
         tracksTenantConcurrency: request.tenantConcurrencyLimit != null,
         state: "active",
@@ -205,7 +275,7 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
       this.adjust(this.daily, reservation.dailyKey, delta, reservation.tracksDaily);
       this.adjust(this.monthly, reservation.monthlyKey, delta, reservation.tracksMonthly);
       this.adjust(this.lifetime, apiKeyId, delta, reservation.tracksLifetime);
-      if (reservation.tracksConcurrency) this.decrement(this.concurrent, apiKeyId);
+      if (reservation.tracksConcurrency) this.decrement(this.concurrent, reservation.concurrencyKey);
       if (reservation.tracksTenantConcurrency)
         this.decrement(this.tenantConcurrent, reservation.tenantId);
       reservation.state = "committed";
@@ -276,7 +346,7 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
   }
 
   /** Caps a bucketed counter map; oldest-inserted buckets evicted first. */
-  private evictCounter(store: Map<string, number> | Map<string, number[]>): void {
+  private evictCounter(store: Map<string, number> | Map<string, RpmTimestampQueue>): void {
     if (store.size < COUNTER_MAP_CAP) return;
     let toEvict = store.size - COUNTER_MAP_CAP + 1;
     for (const key of store.keys()) {
@@ -290,7 +360,7 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
     this.adjust(this.daily, reservation.dailyKey, -reservation.reserved, reservation.tracksDaily);
     this.adjust(this.monthly, reservation.monthlyKey, -reservation.reserved, reservation.tracksMonthly);
     this.adjust(this.lifetime, reservation.apiKeyId, -reservation.reserved, reservation.tracksLifetime);
-    if (reservation.tracksConcurrency) this.decrement(this.concurrent, reservation.apiKeyId);
+    if (reservation.tracksConcurrency) this.decrement(this.concurrent, reservation.concurrencyKey);
     if (reservation.tracksTenantConcurrency)
       this.decrement(this.tenantConcurrent, reservation.tenantId);
     reservation.state = "released";
@@ -316,21 +386,26 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
   private value(store: ReadonlyMap<string, number>, key: string): number {
     return store.get(key) ?? 0;
   }
-  private pruneRpm(apiKeyId: string, now: number): number[] {
-    const cutoff = now - (this.options.windowMs ?? 60_000);
+  private pruneRpm(apiKeyId: string, now: number): RpmTimestampQueue {
     const existing = this.rpmTimestamps.get(apiKeyId);
     if (!existing) {
-      const fresh: number[] = [];
+      const fresh = new RpmTimestampQueue();
       this.rpmTimestamps.set(apiKeyId, fresh);
       this.evictCounter(this.rpmTimestamps);
       return fresh;
     }
-    // In-place compaction: `.filter` allocated a new array per request.
-    let write = 0;
-    for (let read = 0; read < existing.length; read += 1) {
-      if (existing[read]! > cutoff) existing[write++] = existing[read]!;
+    // Amortized: advances the head past expired entries; compaction of the
+    // consumed prefix happens only when it exceeds half the array.
+    existing.prune(now, this.options.windowMs ?? 60_000);
+    if (existing.isEmpty()) {
+      // Drop the emptied bucket so the map cannot pin one dead queue per key
+      // the process ever served, then hand the caller a fresh queue — the
+      // caller pushes this request's timestamp into whatever it gets back, and
+      // pushing into the detached object would silently drop the admission.
+      const fresh = new RpmTimestampQueue();
+      this.rpmTimestamps.set(apiKeyId, fresh);
+      return fresh;
     }
-    existing.length = write;
     return existing;
   }
   private requireReservation(

package/src/security/admission/lua.ts

@@ -1,182 +1,191 @@
-import type { AdmissionRejectionReason } from "./contracts";
-import { reasonToGatewayError } from "./reasons";
-import {
-  CONCURRENCY_TTL_SECONDS,
-  DAILY_COUNTER_TTL_SECONDS,
-  LIFETIME_COUNTER_TTL_SECONDS,
-  MONTHLY_COUNTER_TTL_SECONDS,
-  RPM_WINDOW_TTL_SECONDS,
-} from "./ttl";
-
-/**
- * The three atomic scripts every Redis admission operation runs.
- *
- * They live apart from the store that calls them because they are the
- * enforcement itself: a limit check and its counter write must be one
- * indivisible step, which is why the logic is Lua rather than TypeScript.
- * Reading them next to each other is the only way to see that reserve,
- * reconcile, and release agree on the lease hash fields.
- */
-/**
- * RESERVE — the atomic admission algorithm. Runs as one Redis Lua script so
- * every limit is validated and the reservation created in a single atomic
- * step: no read-modify-write race can let two requests through the last
- * remaining slot, and no partially applied reservation can survive (all
- * counter writes + the lease hash commit together or not at all).
- *
- * Idempotency: an existing lease hash in any state short-circuits to `1`
- * (already reserved) so a retried admission cannot double-charge counters.
- *
- * Limit model — rate limits vs concurrency:
- * - RPM (KEYS[1], a ZSET of timestamps): sliding 60s window, pruned with
- *   ZREMRANGEBYSCORE before counting. Admission is count-based, not
- *   token-based.
- * - Daily / monthly / lifetime token budgets (KEYS[2]/[3]/[5]): the
- *   *estimated* token count is pre-credited at reserve time and reconciled
- *   to actual usage later (RECONCILE_SCRIPT), so a request that would exceed
- *   its budget is rejected before dispatch, never after.
- * - Concurrency (KEYS[4], per API key) and tenant concurrency (KEYS[7]) are
- *   classic INCR/DECR slots held for the request duration; the lease hash
- *   (KEYS[6]) records which counters each reservation tracks so release
- *   reverses exactly those.
- *
- * Key naming: `admission:<kind>[:<apiKeyId>|<tenantId>][:<bucket>]` —
- * `admission:rpm:<key>`, `admission:daily:<key>:<YYYY-MM-DD>`,
- * `admission:monthly:<key>:<YYYY-MM>`, `admission:lifetime:<key>`,
- * `admission:concurrent:<key>`, `admission:tenant_concurrent:<tenant>`,
- * `admission:lease:<reservationId>`. All counters carry TTLs (roughly one
- * bucket + slack) so a process death cannot leak counters forever.
- *
- * Return codes: `0` reserved; `1` idempotent replay; `-1..-6` limit
- * rejections (mapped to GatewayErrors by `assertResult`); `-99` corrupt
- * counter state (never bypassed — admission fails closed).
- */
-export const RESERVE_SCRIPT = `
-local state = redis.call('HGET', KEYS[6], 'state')
-if state == 'active' or state == 'committed' or state == 'released' then return 1 end
-redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', tonumber(ARGV[1]) - 60000)
-local rpm = redis.call('ZCARD', KEYS[1])
-local daily = tonumber(redis.call('GET', KEYS[2]) or '0')
-local monthly = tonumber(redis.call('GET', KEYS[3]) or '0')
-local concurrent = tonumber(redis.call('GET', KEYS[4]) or '0')
-local tenantConcurrent = tonumber(redis.call('GET', KEYS[7]) or '0')
-local lifetime = 0
-if tonumber(ARGV[6]) then
-  local rawLifetime = redis.call('GET', KEYS[5])
-  lifetime = rawLifetime and tonumber(rawLifetime) or tonumber(ARGV[9])
-  if not lifetime then return -99 end
-  if not rawLifetime then redis.call('SET', KEYS[5], lifetime, 'EX', ${LIFETIME_COUNTER_TTL_SECONDS}) end
-end
-local estimated = tonumber(ARGV[2])
-if not estimated or estimated < 0 then return -99 end
-if tonumber(ARGV[3]) and rpm >= tonumber(ARGV[3]) then return -1 end
-if tonumber(ARGV[4]) and daily + estimated > tonumber(ARGV[4]) then return -2 end
-if tonumber(ARGV[5]) and monthly + estimated > tonumber(ARGV[5]) then return -3 end
-if tonumber(ARGV[6]) and lifetime + estimated > tonumber(ARGV[6]) then return -4 end
-if tonumber(ARGV[7]) and concurrent >= tonumber(ARGV[7]) then return -5 end
-if tonumber(ARGV[10]) and tenantConcurrent >= tonumber(ARGV[10]) then return -6 end
-redis.call('ZADD', KEYS[1], ARGV[1], ARGV[8])
-redis.call('EXPIRE', KEYS[1], ${RPM_WINDOW_TTL_SECONDS})
-if tonumber(ARGV[4]) then redis.call('INCRBY', KEYS[2], estimated); redis.call('EXPIRE', KEYS[2], ${DAILY_COUNTER_TTL_SECONDS}) end
-if tonumber(ARGV[5]) then redis.call('INCRBY', KEYS[3], estimated); redis.call('EXPIRE', KEYS[3], ${MONTHLY_COUNTER_TTL_SECONDS}) end
-if tonumber(ARGV[6]) then redis.call('INCRBY', KEYS[5], estimated); redis.call('EXPIRE', KEYS[5], ${LIFETIME_COUNTER_TTL_SECONDS}) end
-if tonumber(ARGV[7]) then redis.call('INCR', KEYS[4]); redis.call('EXPIRE', KEYS[4], ${CONCURRENCY_TTL_SECONDS}) end
-if tonumber(ARGV[10]) then redis.call('INCR', KEYS[7]); redis.call('EXPIRE', KEYS[7], ${CONCURRENCY_TTL_SECONDS}) end
-redis.call('HSET', KEYS[6], 'state', 'active', 'reserved', estimated, 'daily', tonumber(ARGV[4]) and KEYS[2] or '', 'monthly', tonumber(ARGV[5]) and KEYS[3] or '', 'lifetime', tonumber(ARGV[6]) and KEYS[5] or '', 'concurrent', tonumber(ARGV[7]) and '1' or '0', 'tenant_concurrent', tonumber(ARGV[10]) and '1' or '0', 'tenant_id', ARGV[11], 'api_key_id', ARGV[12], 'expires_at', tonumber(ARGV[1]) + tonumber(ARGV[13]))
-redis.call('EXPIRE', KEYS[6], tonumber(ARGV[14]))
-return 0
-`;
-
-/**
- * RECONCILE — replaces the reservation's estimated token credit with actual
- * provider usage, atomically. Runs only on an `active` lease; reads which
- * counters the reservation credited from the lease hash, computes
- * `delta = actual - reserved`, validates the resulting counter values (no
- * negative drift), applies them, and decrements the held concurrency slots.
- * `actual` may be less than `reserved` (over-estimate refunded) or more
- * (under-estimate charged). Marks the lease `committed` — a second reconcile
- * or release is an idempotent no-op (`1`).
- */
-export const RECONCILE_SCRIPT = `
-local state = redis.call('HGET', KEYS[1], 'state')
-if state == 'committed' or state == 'released' then return 1 end
-if state ~= 'active' then return -99 end
-local reserved = tonumber(redis.call('HGET', KEYS[1], 'reserved'))
-local actual = tonumber(ARGV[1])
-if not reserved or not actual or reserved < 0 or actual < 0 or reserved ~= math.floor(reserved) or actual ~= math.floor(actual) then return -99 end
-local delta = actual - reserved
-local updates = {}
-for _, field in ipairs({'daily', 'monthly', 'lifetime'}) do
-  local key = redis.call('HGET', KEYS[1], field)
-  if key and key ~= '' then
-    local value = tonumber(redis.call('GET', key))
-    if not value or value < 0 or value + delta < 0 or value + delta ~= math.floor(value + delta) then return -99 end
-    table.insert(updates, key)
-  end
-end
-local concurrentKey = 'admission:concurrent:' .. ARGV[2]
-local hasConcurrency = redis.call('HGET', KEYS[1], 'concurrent') == '1'
-if hasConcurrency then
-  local value = tonumber(redis.call('GET', concurrentKey))
-  if not value or value < 1 or value ~= math.floor(value) then return -99 end
-end
-local tenantKey = ''
-local hasTenantConcurrency = redis.call('HGET', KEYS[1], 'tenant_concurrent') == '1'
-if hasTenantConcurrency then
-  local tenantId = redis.call('HGET', KEYS[1], 'tenant_id')
-  if not tenantId or tenantId == '' then return -99 end
-  tenantKey = 'admission:tenant_concurrent:' .. tenantId
-  local value = tonumber(redis.call('GET', tenantKey))
-  if not value or value < 1 or value ~= math.floor(value) then return -99 end
-end
--- INCRBY, never SET: a plain SET replaces the key and drops its TTL, so the
--- first reconcile after admission would strip the bucket's expiry and the
--- counter would outlive its window forever. INCRBY adjusts the value in place
--- and leaves the TTL intact. (KEEPTTL would also work but is unavailable on
--- the oldest Redis this is documented against.)
-for _, key in ipairs(updates) do redis.call('INCRBY', key, delta) end
-if hasConcurrency then redis.call('DECR', concurrentKey) end
-if hasTenantConcurrency then redis.call('DECR', tenantKey) end
-redis.call('HSET', KEYS[1], 'state', 'committed', 'actual', actual)
-return 0
-`;
-
-/**
- * RELEASE — reverses an uncommitted reservation exactly once: refunds the
- * pre-credited token estimates, decrements the held concurrency and tenant
- * slots, and marks the lease `released` (subsequent release/reconcile
- * returns `1`). Unlike the normal release path, crash-recovery releases
- * (`releaseAdmissionLease` / the sweeper) run this same script keyed only by
- * the lease hash; concurrency keys are rebuilt from `admission:concurrent:`
- * + the lease's `api_key_id` / `tenant_id` fields, so recovery never needs
- * the caller to remember which counters were held.
- */
-export const RELEASE_SCRIPT = `
-local state = redis.call('HGET', KEYS[1], 'state')
-if state == 'released' or state == 'committed' then return 1 end
-if state ~= 'active' then return -99 end
-local reserved = tonumber(redis.call('HGET', KEYS[1], 'reserved'))
-if not reserved or reserved < 0 then return -99 end
-for _, field in ipairs({'daily', 'monthly', 'lifetime'}) do local key = redis.call('HGET', KEYS[1], field); if key and key ~= '' then local value = tonumber(redis.call('GET', key) or '0'); if not value or value < reserved then return -99 end; redis.call('DECRBY', key, reserved) end end
-if redis.call('HGET', KEYS[1], 'concurrent') == '1' then local key = 'admission:concurrent:' .. ARGV[1]; local value = tonumber(redis.call('GET', key) or '0'); if not value or value < 1 then return -99 end; redis.call('DECR', key) end
-if redis.call('HGET', KEYS[1], 'tenant_concurrent') == '1' then local tenantId = redis.call('HGET', KEYS[1], 'tenant_id'); if not tenantId or tenantId == '' then return -99 end; local key = 'admission:tenant_concurrent:' .. tenantId; local value = tonumber(redis.call('GET', key) or '0'); if not value or value < 1 then return -99 end; redis.call('DECR', key) end
-redis.call('HSET', KEYS[1], 'state', 'released')
-return 0
-`;
-const RESULT_REASON: Record<number, AdmissionRejectionReason> = {
-  [-1]: "rpm-exhausted",
-  [-2]: "daily-token-limit",
-  [-3]: "monthly-token-limit",
-  [-4]: "lifetime-token-budget",
-  [-5]: "concurrency-limit",
-  [-6]: "tenant-capacity-exhausted",
-};
-
-export function assertResult(result: number, operation: string): void {
-  if (result === -99) throw new Error(`corrupt admission counter during ${operation}`);
-  const reason = RESULT_REASON[result];
-  if (reason) {
-    throw reasonToGatewayError(reason, { operation });
-  }
-  if (result < 0) throw new Error(`admission rejected during ${operation}: ${result}`);
-}
+import type { AdmissionRejectionReason } from "./contracts";
+import { reasonToGatewayError } from "./reasons";
+import {
+  CONCURRENCY_TTL_SECONDS,
+  DAILY_COUNTER_TTL_SECONDS,
+  LIFETIME_COUNTER_TTL_SECONDS,
+  MONTHLY_COUNTER_TTL_SECONDS,
+  RPM_WINDOW_TTL_SECONDS,
+} from "./ttl";
+
+/**
+ * The three atomic scripts every Redis admission operation runs.
+ *
+ * They live apart from the store that calls them because they are the
+ * enforcement itself: a limit check and its counter write must be one
+ * indivisible step, which is why the logic is Lua rather than TypeScript.
+ * Reading them next to each other is the only way to see that reserve,
+ * reconcile, and release agree on the lease hash fields.
+ */
+/**
+ * RESERVE — the atomic admission algorithm. Runs as one Redis Lua script so
+ * every limit is validated and the reservation created in a single atomic
+ * step: no read-modify-write race can let two requests through the last
+ * remaining slot, and no partially applied reservation can survive (all
+ * counter writes + the lease hash commit together or not at all).
+ *
+ * Idempotency: an existing lease hash in any state short-circuits to `1`
+ * (already reserved) so a retried admission cannot double-charge counters.
+ *
+ * Limit model — rate limits vs concurrency:
+ * - RPM (KEYS[1], a ZSET of timestamps): sliding 60s window, pruned with
+ *   ZREMRANGEBYSCORE before counting. Admission is count-based, not
+ *   token-based.
+ * - Daily / monthly / lifetime token budgets (KEYS[2]/[3]/[5]): the
+ *   *estimated* token count is pre-credited at reserve time and reconciled
+ *   to actual usage later (RECONCILE_SCRIPT), so a request that would exceed
+ *   its budget is rejected before dispatch, never after.
+ * - Concurrency (KEYS[4], per API key) and tenant concurrency (KEYS[7]) are
+ *   classic INCR/DECR slots held for the request duration; the lease hash
+ *   (KEYS[6]) records which counters each reservation tracks so release
+ *   reverses exactly those.
+ *
+ * Key naming: `admission:<kind>[:<apiKeyId>|<tenantId>][:<bucket>]` —
+ * `admission:rpm:<key>`, `admission:daily:<key>:<YYYY-MM-DD>`,
+ * `admission:monthly:<key>:<YYYY-MM>`, `admission:lifetime:<key>`,
+ * `admission:concurrent:<key>`, `admission:tenant_concurrent:<tenant>`,
+ * `admission:lease:<reservationId>`. All counters carry TTLs (roughly one
+ * bucket + slack) so a process death cannot leak counters forever.
+ *
+ * Return codes: `0` reserved; `1` idempotent replay; `-1..-6` limit
+ * rejections (mapped to GatewayErrors by `assertResult`); `-99` corrupt
+ * counter state (never bypassed — admission fails closed).
+ */
+export const RESERVE_SCRIPT = `
+local state = redis.call('HGET', KEYS[6], 'state')
+if state == 'active' or state == 'committed' or state == 'released' then return 1 end
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', tonumber(ARGV[1]) - 60000)
+local rpm = redis.call('ZCARD', KEYS[1])
+local daily = tonumber(redis.call('GET', KEYS[2]) or '0')
+local monthly = tonumber(redis.call('GET', KEYS[3]) or '0')
+local concurrent = tonumber(redis.call('GET', KEYS[4]) or '0')
+local tenantConcurrent = tonumber(redis.call('GET', KEYS[7]) or '0')
+local lifetime = 0
+if tonumber(ARGV[6]) then
+  local rawLifetime = redis.call('GET', KEYS[5])
+  lifetime = rawLifetime and tonumber(rawLifetime) or tonumber(ARGV[9])
+  if not lifetime then return -99 end
+  if not rawLifetime then redis.call('SET', KEYS[5], lifetime, 'EX', ${LIFETIME_COUNTER_TTL_SECONDS}) end
+end
+local estimated = tonumber(ARGV[2])
+if not estimated or estimated < 0 then return -99 end
+if tonumber(ARGV[3]) and rpm >= tonumber(ARGV[3]) then return -1 end
+if tonumber(ARGV[4]) and daily + estimated > tonumber(ARGV[4]) then return -2 end
+if tonumber(ARGV[5]) and monthly + estimated > tonumber(ARGV[5]) then return -3 end
+if tonumber(ARGV[6]) and lifetime + estimated > tonumber(ARGV[6]) then return -4 end
+-- ARGV[15] is the tolerance: slack above the configured limit, so the ceiling
+-- is the sum. It widens admission only; already-admitted requests are never
+-- revisited.
+if tonumber(ARGV[7]) and concurrent >= tonumber(ARGV[7]) + (tonumber(ARGV[15]) or 0) then return -5 end
+if tonumber(ARGV[10]) and tenantConcurrent >= tonumber(ARGV[10]) then return -6 end
+redis.call('ZADD', KEYS[1], ARGV[1], ARGV[8])
+redis.call('EXPIRE', KEYS[1], ${RPM_WINDOW_TTL_SECONDS})
+if tonumber(ARGV[4]) then redis.call('INCRBY', KEYS[2], estimated); redis.call('EXPIRE', KEYS[2], ${DAILY_COUNTER_TTL_SECONDS}) end
+if tonumber(ARGV[5]) then redis.call('INCRBY', KEYS[3], estimated); redis.call('EXPIRE', KEYS[3], ${MONTHLY_COUNTER_TTL_SECONDS}) end
+if tonumber(ARGV[6]) then redis.call('INCRBY', KEYS[5], estimated); redis.call('EXPIRE', KEYS[5], ${LIFETIME_COUNTER_TTL_SECONDS}) end
+if tonumber(ARGV[7]) then redis.call('INCR', KEYS[4]); redis.call('EXPIRE', KEYS[4], ${CONCURRENCY_TTL_SECONDS}) end
+if tonumber(ARGV[10]) then redis.call('INCR', KEYS[7]); redis.call('EXPIRE', KEYS[7], ${CONCURRENCY_TTL_SECONDS}) end
+redis.call('HSET', KEYS[6], 'state', 'active', 'reserved', estimated, 'daily', tonumber(ARGV[4]) and KEYS[2] or '', 'monthly', tonumber(ARGV[5]) and KEYS[3] or '', 'lifetime', tonumber(ARGV[6]) and KEYS[5] or '', 'concurrent', tonumber(ARGV[7]) and '1' or '0', 'concurrent_key', tonumber(ARGV[7]) and KEYS[4] or '', 'tenant_concurrent', tonumber(ARGV[10]) and '1' or '0', 'tenant_id', ARGV[11], 'api_key_id', ARGV[12], 'expires_at', tonumber(ARGV[1]) + tonumber(ARGV[13]))
+redis.call('EXPIRE', KEYS[6], tonumber(ARGV[14]))
+return 0
+`;
+
+/**
+ * RECONCILE — replaces the reservation's estimated token credit with actual
+ * provider usage, atomically. Runs only on an `active` lease; reads which
+ * counters the reservation credited from the lease hash, computes
+ * `delta = actual - reserved`, validates the resulting counter values (no
+ * negative drift), applies them, and decrements the held concurrency slots.
+ * `actual` may be less than `reserved` (over-estimate refunded) or more
+ * (under-estimate charged). Marks the lease `committed` — a second reconcile
+ * or release is an idempotent no-op (`1`).
+ */
+export const RECONCILE_SCRIPT = `
+local state = redis.call('HGET', KEYS[1], 'state')
+if state == 'committed' or state == 'released' then return 1 end
+if state ~= 'active' then return -99 end
+local reserved = tonumber(redis.call('HGET', KEYS[1], 'reserved'))
+local actual = tonumber(ARGV[1])
+if not reserved or not actual or reserved < 0 or actual < 0 or reserved ~= math.floor(reserved) or actual ~= math.floor(actual) then return -99 end
+local delta = actual - reserved
+local updates = {}
+for _, field in ipairs({'daily', 'monthly', 'lifetime'}) do
+  local key = redis.call('HGET', KEYS[1], field)
+  if key and key ~= '' then
+    local value = tonumber(redis.call('GET', key))
+    if not value or value < 0 or value + delta < 0 or value + delta ~= math.floor(value + delta) then return -99 end
+    table.insert(updates, key)
+  end
+end
+-- The key that was CHARGED, not one rebuilt from the caller's identity: a share
+-- child reserves under its own id while the lease is recorded against its
+-- parent, so rebuilding from ARGV incremented one counter and decremented
+-- another. The child's count never fell and the key went permanently over its
+-- limit. Fall back to ARGV only for leases written before this field existed.
+local concurrentKey = redis.call('HGET', KEYS[1], 'concurrent_key')
+if not concurrentKey or concurrentKey == '' then concurrentKey = 'admission:concurrent:' .. ARGV[2] end
+local hasConcurrency = redis.call('HGET', KEYS[1], 'concurrent') == '1'
+if hasConcurrency then
+  local value = tonumber(redis.call('GET', concurrentKey))
+  if not value or value < 1 or value ~= math.floor(value) then return -99 end
+end
+local tenantKey = ''
+local hasTenantConcurrency = redis.call('HGET', KEYS[1], 'tenant_concurrent') == '1'
+if hasTenantConcurrency then
+  local tenantId = redis.call('HGET', KEYS[1], 'tenant_id')
+  if not tenantId or tenantId == '' then return -99 end
+  tenantKey = 'admission:tenant_concurrent:' .. tenantId
+  local value = tonumber(redis.call('GET', tenantKey))
+  if not value or value < 1 or value ~= math.floor(value) then return -99 end
+end
+-- INCRBY, never SET: a plain SET replaces the key and drops its TTL, so the
+-- first reconcile after admission would strip the bucket's expiry and the
+-- counter would outlive its window forever. INCRBY adjusts the value in place
+-- and leaves the TTL intact. (KEEPTTL would also work but is unavailable on
+-- the oldest Redis this is documented against.)
+for _, key in ipairs(updates) do redis.call('INCRBY', key, delta) end
+if hasConcurrency then redis.call('DECR', concurrentKey) end
+if hasTenantConcurrency then redis.call('DECR', tenantKey) end
+redis.call('HSET', KEYS[1], 'state', 'committed', 'actual', actual)
+return 0
+`;
+
+/**
+ * RELEASE — reverses an uncommitted reservation exactly once: refunds the
+ * pre-credited token estimates, decrements the held concurrency and tenant
+ * slots, and marks the lease `released` (subsequent release/reconcile
+ * returns `1`). Unlike the normal release path, crash-recovery releases
+ * (`releaseAdmissionLease` / the sweeper) run this same script keyed only by
+ * the lease hash; concurrency keys are rebuilt from `admission:concurrent:`
+ * + the lease's `api_key_id` / `tenant_id` fields, so recovery never needs
+ * the caller to remember which counters were held.
+ */
+export const RELEASE_SCRIPT = `
+local state = redis.call('HGET', KEYS[1], 'state')
+if state == 'released' or state == 'committed' then return 1 end
+if state ~= 'active' then return -99 end
+local reserved = tonumber(redis.call('HGET', KEYS[1], 'reserved'))
+if not reserved or reserved < 0 then return -99 end
+for _, field in ipairs({'daily', 'monthly', 'lifetime'}) do local key = redis.call('HGET', KEYS[1], field); if key and key ~= '' then local value = tonumber(redis.call('GET', key) or '0'); if not value or value < reserved then return -99 end; redis.call('DECRBY', key, reserved) end end
+if redis.call('HGET', KEYS[1], 'concurrent') == '1' then local key = redis.call('HGET', KEYS[1], 'concurrent_key'); if not key or key == '' then key = 'admission:concurrent:' .. ARGV[1] end; local value = tonumber(redis.call('GET', key) or '0'); if not value or value < 1 then return -99 end; redis.call('DECR', key) end
+if redis.call('HGET', KEYS[1], 'tenant_concurrent') == '1' then local tenantId = redis.call('HGET', KEYS[1], 'tenant_id'); if not tenantId or tenantId == '' then return -99 end; local key = 'admission:tenant_concurrent:' .. tenantId; local value = tonumber(redis.call('GET', key) or '0'); if not value or value < 1 then return -99 end; redis.call('DECR', key) end
+redis.call('HSET', KEYS[1], 'state', 'released')
+return 0
+`;
+const RESULT_REASON: Record<number, AdmissionRejectionReason> = {
+  [-1]: "rpm-exhausted",
+  [-2]: "daily-token-limit",
+  [-3]: "monthly-token-limit",
+  [-4]: "lifetime-token-budget",
+  [-5]: "concurrency-limit",
+  [-6]: "tenant-capacity-exhausted",
+};
+
+export function assertResult(result: number, operation: string): void {
+  if (result === -99) throw new Error(`corrupt admission counter during ${operation}`);
+  const reason = RESULT_REASON[result];
+  if (reason) {
+    throw reasonToGatewayError(reason, { operation });
+  }
+  if (result < 0) throw new Error(`admission rejected during ${operation}: ${result}`);
+}