@ultimat3/http 30.8.0 → 31.0.0

package/src/rate-limit-installed.ts

@@ -1,72 +1,62 @@
-// The store a PRIMITIVE's declared `rateLimit:` is counted in — `@ultimat3/action`'s `invoke` and
-// `@ultimat3/query`'s read path both spend from it, on every surface. One slot, here, so the two
-// tier-3 packages (which cannot import each other) count in one place, and the boot fills it with
-// the same instance it hands `httpServer({ rateLimitStore })`.
+// The store a PRIMITIVE's declared `rateLimit:` is counted in — and, since 31.0.0, the one the
+// HTTP pipeline's limiter counts in too. `@ultimat3/action`'s `invoke` and `@ultimat3/query`'s
+// read path both spend from it, on every surface; one slot, here, so the two tier-3 packages
+// (which cannot import each other) and every `httpServer` count in one place.
 
-import type { RateLimitConfig, RateLimitStore } from './rate-limit';
+import { adapterSlot } from '@ultimat3/core/adapter';
+import type { Bucket, RateLimitConfig, RateLimitStore } from './rate-limit';
 import { memoryRateLimitStore } from './rate-limit';
 import { rateLimitNotShared } from './rate-limit-errors';
 
-/** What a process falls back to when nothing chose: one process' memory. */
+/** What a process falls back to when nothing installed one: one process' memory. */
 let base: RateLimitStore = memoryRateLimitStore();
-let baseChosen = false;
 /**
- * Adopted stores, newest last. A STACK of frames, each popped only by its own adopter: two
- * servers started A-then-B and stopped A-then-B used to have A's stop restore what A replaced —
- * reverting the slot under B while B still served. A frame object is its own identity, so the
- * same store adopted twice is two frames.
+ * Installed stores over the base: core's `adapterSlot`, a stack each release pops only its own
+ * frame from — two boots stopped in either order never revert the slot under the one still serving.
  */
-const frames: { readonly store: RateLimitStore }[] = [];
+const slot = /* @__PURE__ */ adapterSlot<RateLimitStore>(() => base);
 
-const current = (): RateLimitStore => frames.at(-1)?.store ?? base;
-const isChosen = (): boolean => baseChosen || frames.length > 0;
+const current = (): RateLimitStore => slot.current();
 
 /**
- * The embedder's one-line install, for a process that builds its own boot: the base everything
- * else stacks over. Left at the default it is one process' memory — right for dev and tests, and
- * N × every declared limit behind N replicas, which `assertInstalledRateLimitScope` refuses under
- * a `'shared'` declaration. A boot that has to give the slot back uses `adoptRateLimitStore`.
+ * The boot's install, and the only one: exported from `@ultimat3/http/adapter`, never from the
+ * package's `.` barrel. An app does not call it — it names its store as `rateLimitStore` in
+ * `apps/<app>/runtime.ts` and the boot installs that, or `postgresRateLimitStore` over the pool it
+ * opened. Answers the undo that removes THIS frame and no other, whatever order installers stop in.
  */
-export const installRateLimitStore = (store: RateLimitStore): void => {
-  base = store;
-  baseChosen = true;
-};
+export const installRateLimitStore = (store: RateLimitStore): (() => void) => slot.install(store);
 
 export const installedRateLimitStore = (): RateLimitStore => current();
 
-/** Test-only. Every frame and the base, back to one process' memory. */
-export const resetRateLimitStore = (): void => {
-  frames.length = 0;
-  base = memoryRateLimitStore();
-  baseChosen = false;
-};
-
-export interface AdoptRateLimitStoreOptions {
-  /**
-   * `httpServer`'s rule: never over a store something already CHOSE. The boot installs its own
-   * before any server exists, and a server handed a different one must not move every action's
-   * counters out from under it — the chosen one stands, and `assertInstalledRateLimitScope` still
-   * holds it to the declaration.
-   */
-  readonly keepChosen?: boolean;
-}
+/**
+ * The slot as a store: every call reads whatever is installed AT THAT CALL. What `httpServer`'s
+ * limiter counts in, so a store installed after the server was built — a test's override seam, a
+ * boot that orders its installs differently — is the one a request spends from. Its `scope` is
+ * read live too; the boot check reads it once, when the pipeline is built.
+ */
+export const liveRateLimitStore: RateLimitStore = Object.freeze({
+  get scope() {
+    return current().scope;
+  },
+  take: (key: string, bucket: Bucket, cost: number, nowMs: number) =>
+    current().take(key, bucket, cost, nowMs),
+  peek: (key: string, bucket: Bucket, nowMs: number) => current().peek(key, bucket, nowMs),
+  reset: (key: string) => current().reset(key),
+});
 
 /**
- * Push `store` as the one primitives spend from, and answer the undo that removes THIS frame and
- * no other — whatever order the adopters stop in. The boot (`startServices`, `startRoles`) and
- * `httpServer` all go through it, so every install has a matching, order-proof release.
+ * The per-test reset: the DEFAULT memory store's buckets emptied, every installed store left where
+ * it is. A suite that installed a shared store once (a live Redis or Postgres run) keeps running on
+ * it; only the fallback a plain unit test counts in forgets what the previous test spent.
  */
-export const adoptRateLimitStore = (
-  store: RateLimitStore,
-  options: AdoptRateLimitStoreOptions = {},
-): (() => void) => {
-  if (options.keepChosen === true && isChosen() && current() !== store) return () => undefined;
-  const frame = { store };
-  frames.push(frame);
-  return () => {
-    const at = frames.indexOf(frame);
-    if (at !== -1) frames.splice(at, 1);
-  };
+export const clearDefaultRateLimitBuckets = (): void => {
+  base = memoryRateLimitStore();
+};
+
+/** Test-only. Every frame and the base, back to one process' memory. */
+export const resetRateLimitStore = (): void => {
+  slot.reset();
+  base = memoryRateLimitStore();
 };
 
 /**
@@ -86,7 +76,7 @@ export const assertInstalledRateLimitScope = (config: RateLimitConfig): void =>
  */
 export async function withScratchRateLimitStore<T>(fn: () => Promise<T>): Promise<T> {
   const scratch = memoryRateLimitStore();
-  const release = adoptRateLimitStore({
+  const release = installRateLimitStore({
     scope: current().scope,
     take: (key, bucket, cost, nowMs) => scratch.take(key, bucket, cost, nowMs),
     peek: (key, bucket, nowMs) => scratch.peek(key, bucket, nowMs),

package/src/rate-limit-postgres.ts

@@ -31,7 +31,10 @@ create table if not exists x_rate_limit (
   updated_at        timestamptz      not null default now()
 );
 
-create index if not exists x_rate_limit_updated_at_idx on x_rate_limit (updated_at);
+-- v31: never scanned (the purge reads last_ms) and paid on every take. Dropped where an earlier
+-- boot created it, idempotent like the rest. Never a semicolon in a comment here: the boot splits
+-- this text on it.
+drop index if exists x_rate_limit_updated_at_idx;
 `;
 
 /**
@@ -140,7 +143,7 @@ export interface PostgresRateLimitStore extends RateLimitStore {
   /**
    * Delete every bucket that has refilled to capacity, and answer how many. The table is the one
    * part of this store that does not bound itself — Postgres forgets nothing on its own, and the
-   * key falls back to the connection address, so a scan rotating through an IPv6 /64 mints a row
+   * key falls back to the connection address, so a scan rotating through IPv6 /64s mints a row
    * per request. An app runs this from a `task` on whatever cadence its traffic deserves.
    *
    * `nowMs` is required and comes from the SAME clock the takes use — `ctx.now().getTime()` in a
@@ -152,19 +155,17 @@ export interface PostgresRateLimitStore extends RateLimitStore {
 }
 
 /**
- * **Install it at boot, beside the config that declares the scope.** The app owes two lines:
+ * **The boot installs it** over the pool it opened (`x dev`, `x serve`); an app names another
+ * store, or this one over another executor, in one place:
  *
  * ```ts
- * // app.config.ts — what this deployment REQUIRES
- * http: { rateLimit: { scope: 'shared' } }
- *
- * // apps/web/server.ts — what PROVIDES it
+ * // apps/web/runtime.ts — what PROVIDES it
  * const client = db();
- * httpServer({
+ * export const runtime = {
  *   rateLimitStore: postgresRateLimitStore({
  *     executor: { query: (text, values) => client.query({ text, values }) },
  *   }),
- * });
+ * };
  * ```
  *
  * `assertRateLimitScope` compares the two once, inside `httpPipeline`, and a `'shared'`

package/src/rate-limit-redis.ts

@@ -0,0 +1,176 @@
+// The shared rate-limit store over Redis: one Lua token bucket per take, so the refill, the spend
+// and the expiry are one atomic step on the server. Beside Postgres, not instead of it: a hot key
+// (one NAT, a tenant bucket) serialises every request on one row lock there, and Redis runs a
+// script per key without one. The bucket expires once refilled, so it bounds itself — no purge.
+
+import type { Scheduler } from '@ultimat3/core';
+import { stringField } from '@ultimat3/core';
+import { httpCountInvalid } from './errors';
+import type { RateLimitDecision, RateLimitScope, RateLimitStore } from './rate-limit';
+import { rateLimitDecision } from './rate-limit';
+import { degradedFallback, isRateLimitStoreUnreachable } from './rate-limit-degrade';
+import { rateLimitStoreUnavailable } from './rate-limit-errors';
+import { rateLimitPeek, refilledTokens } from './rate-limit-peek';
+import { storeDeadline } from './rate-limit-store-deadline';
+
+/** The slice of Bun's `RedisClient` (core's `redisClient()`) this store sends through. */
+export interface RedisRateLimitClient {
+  send(command: string, args: string[]): Promise<unknown>;
+}
+
+/**
+ * `KEYS[1]` the bucket; `ARGV` capacity, refill per second, cost, the caller's `nowMs`. The same
+ * arithmetic as the memory store and `SQL_RATE_LIMIT_TAKE`: refill capped at capacity, elapsed
+ * never negative, `l` only ever moves forward (two replicas share no clock). Tokens go back as a
+ * STRING — Redis truncates a Lua number reply to an integer, and 0.5 left is not 0. The key
+ * expires when it would be full again — the memory store's `forgetAt` — which answers exactly as a
+ * missing one. A week's window is a week's key: capping it would hand back a fresh allowance. A
+ * refill of 0 never reaches the script (`take` refuses it), so no key is held forever.
+ */
+export const REDIS_RATE_LIMIT_TAKE = `
+local cap = tonumber(ARGV[1])
+local rate = tonumber(ARGV[2])
+local cost = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+local held = redis.call('HMGET', KEYS[1], 't', 'l')
+local tokens = cap
+local last = now
+if held[1] then
+  tokens = tonumber(held[1])
+  last = tonumber(held[2])
+end
+tokens = math.min(cap, tokens + math.max(0, now - last) / 1000 * rate)
+local allowed = tokens >= cost
+if allowed then tokens = tokens - cost end
+redis.call('HSET', KEYS[1], 't', string.format('%.17g', tokens), 'l', string.format('%d', math.max(last, now)))
+redis.call('PEXPIRE', KEYS[1], math.max(1, math.ceil((cap - tokens) / rate * 1000)))
+return { string.format('%.17g', tokens), allowed and 1 or 0 }
+`;
+
+const TAKE_SHA = new Bun.CryptoHasher('sha1').update(REDIS_RATE_LIMIT_TAKE).digest('hex');
+
+export interface RedisRateLimitStoreOptions {
+  /** Core's `redisClient()` (`@ultimat3/core/redis`), or anything with its `send`. */
+  readonly client: RedisRateLimitClient;
+  /** Key namespace, so two apps can share one Redis. Default `x`; keys are `<prefix>:rl:<key>`. */
+  readonly prefix?: string | undefined;
+  /** One round trip's budget before the decision degrades to this pod's memory. Default 250 ms. */
+  readonly deadlineMs?: number | undefined;
+  /** Injection seam for that deadline; production passes none. */
+  readonly schedule?: Scheduler | undefined;
+}
+
+/** Bun's code for a command refused for want of a connection — the store is down, not wrong. */
+const CONNECTION_CLOSED = 'ERR_REDIS_CONNECTION_CLOSED';
+
+const unreachable = (error: unknown): boolean =>
+  isRateLimitStoreUnreachable(error) || stringField(error, 'code') === CONNECTION_CLOSED;
+
+/** A reply list's member as a finite number, or `null` for anything else. */
+const numberAt = (reply: unknown, index: number): number | null => {
+  if (!Array.isArray(reply)) return null;
+  const value: unknown = reply[index];
+  if (value === null || value === undefined) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/**
+ * **Name it in `apps/<app>/runtime.ts`**, the one place a store is chosen:
+ *
+ * ```ts
+ * import { redisClient } from '@ultimat3/core/redis';
+ * export const runtime = { rateLimitStore: redisRateLimitStore({ client: redisClient() }) };
+ * ```
+ *
+ * `scope: 'shared'`, so it satisfies `rateLimit: { scope: 'shared' }`. A Redis that is down or
+ * past `deadlineMs` degrades to this pod's memory, logged — the same rule and the same fallback
+ * as `postgresRateLimitStore` (`rate-limit-degrade.ts`); an error REPLY (a script the server
+ * refuses) still throws.
+ */
+export function redisRateLimitStore(options: RedisRateLimitStoreOptions): RedisRateLimitStore {
+  const { client } = options;
+  const prefix = options.prefix ?? 'x';
+  const keyOf = (key: string): string => `${prefix}:rl:${key}`;
+  const deadline = storeDeadline(options.deadlineMs, options.schedule, 'redisRateLimitStore');
+  const fallback = degradedFallback('redisRateLimitStore');
+  const degrade = <T>(error: unknown, nowMs: number, decide: () => Promise<T>): Promise<T> => {
+    if (!unreachable(error)) throw error;
+    fallback.note(error, nowMs);
+    return decide();
+  };
+  // EVALSHA first: the script is sent once per server, not per request. A server that has not
+  // seen it (a restart, a failover) answers NOSCRIPT, and EVAL both runs and caches it.
+  const runTake = async (args: string[]): Promise<unknown> => {
+    try {
+      return await client.send('EVALSHA', [TAKE_SHA, '1', ...args]);
+    } catch (error) {
+      if (!(stringField(error, 'message') ?? '').includes('NOSCRIPT')) throw error;
+      return client.send('EVAL', [REDIS_RATE_LIMIT_TAKE, '1', ...args]);
+    }
+  };
+
+  return {
+    scope: 'shared',
+
+    async take(key, bucket, cost, nowMs): Promise<RateLimitDecision> {
+      // Config resolution refuses it first; this is the store's own guard for a bucket handed in
+      // directly, because a key whose bucket never refills would never expire.
+      if (!Number.isFinite(bucket.refillPerSecond) || bucket.refillPerSecond <= 0) {
+        throw httpCountInvalid(
+          'rateLimit bucket refillPerSecond',
+          bucket.refillPerSecond,
+          'a finite number of tokens per second above 0',
+          'rateLimit: { buckets: { default: { capacity: 120, refillPerSecond: 2 } } }',
+        );
+      }
+      let reply: unknown;
+      try {
+        reply = await deadline.bound(
+          'take',
+          runTake([
+            keyOf(key),
+            String(bucket.capacity),
+            String(bucket.refillPerSecond),
+            String(cost),
+            String(Math.floor(nowMs)),
+          ]),
+        );
+      } catch (error) {
+        return degrade(error, nowMs, () => fallback.store.take(key, bucket, cost, nowMs));
+      }
+      const tokens = numberAt(reply, 0);
+      const allowed = numberAt(reply, 1);
+      // The script always answers both; anything else is not this script running, and inventing
+      // "allowed" would be the limiter silently switched off.
+      if (tokens === null || allowed === null) throw rateLimitStoreUnavailable('take');
+      return rateLimitDecision(bucket, tokens, cost, allowed === 1, nowMs);
+    },
+
+    async peek(key, bucket, nowMs) {
+      let reply: unknown;
+      try {
+        reply = await deadline.bound('peek', client.send('HMGET', [keyOf(key), 't', 'l']));
+      } catch (error) {
+        return degrade(error, nowMs, () => fallback.store.peek(key, bucket, nowMs));
+      }
+      const stored = numberAt(reply, 0);
+      const lastMs = numberAt(reply, 1);
+      const tokens =
+        stored === null || lastMs === null
+          ? bucket.capacity
+          : refilledTokens(bucket, stored, lastMs, Math.floor(nowMs));
+      return rateLimitPeek(bucket, tokens);
+    },
+
+    async reset(key): Promise<void> {
+      // Both places a decision can come from, the fallback first — the Postgres store's order.
+      await fallback.store.reset(key);
+      await client.send('DEL', [keyOf(key)]);
+    },
+  };
+}
+
+export interface RedisRateLimitStore extends RateLimitStore {
+  readonly scope: RateLimitScope;
+}

package/src/rate-limit-stage.ts

@@ -2,6 +2,7 @@
 // has a caller, and the one allowance the `auth` stage spends for a request that failed to have
 // one. Split out of `stages.ts` at the size ceiling; the bucket maths stays in `rate-limit.ts`.
 
+import { addressNetwork } from '@ultimat3/core';
 import { actorView, type RequestContext } from './context';
 import {
   type RateLimitConfig,
@@ -85,9 +86,9 @@ const routeBucketOf = (ctx: RequestContext, config: RateLimitConfig): string | n
   return meta?.rateLimit ?? config.defaultBucket;
 };
 
-/** The one key failed credentials are counted under: the address alone, never the route. */
+/** The one key failed credentials are counted under: the address alone (an IPv6 /64), never the route. */
 const unauthenticatedKey = (ip: string | null): string =>
-  `${UNAUTHENTICATED_SCOPE}|ip:${ip ?? 'unknown'}`;
+  `${UNAUTHENTICATED_SCOPE}|ip:${ip === null ? 'unknown' : addressNetwork(ip)}`;
 
 /**
  * The `auth` stage's GATE, before `authenticate()` on a required route: an address whose failure

package/src/rate-limit-store-deadline.ts

@@ -26,11 +26,24 @@ export interface StoreDeadline {
   bound<T>(statement: 'take' | 'peek', sending: Promise<T>): Promise<T>;
 }
 
-export const rateLimitStoreTimeout = (statement: string, deadlineMs: number): HttpError =>
+/** Which store's factory a refusal names — the one the author raises `deadlineMs` on. */
+export type SharedStoreOwner = 'postgresRateLimitStore' | 'redisRateLimitStore';
+
+/** The command that checks the store a timeout names: no table indexed by a value. */
+const fixFor = (owner: SharedStoreOwner): string =>
+  owner === 'redisRateLimitStore'
+    ? 'redis-cli -u "$REDIS_URL" --latency   # a Redis that is slow rather than gone takes redisRateLimitStore({ client, deadlineMs }) raised in the boot that builds it'
+    : 'x doctor --json   # names the database binding this pod cannot reach; a database that is slow rather than gone takes postgresRateLimitStore({ executor, deadlineMs }) raised in the boot that builds it';
+
+export const rateLimitStoreTimeout = (
+  statement: string,
+  deadlineMs: number,
+  owner: SharedStoreOwner = 'postgresRateLimitStore',
+): HttpError =>
   new HttpError({
     code: 'X_RATE_LIMIT_STORE_TIMEOUT',
     cause: `the shared rate-limit store's ${statement} statement did not answer within ${String(deadlineMs)} ms, so this decision was taken from this pod's memory`,
-    fix: 'x doctor --json   # names the database binding this pod cannot reach; a database that is slow rather than gone takes postgresRateLimitStore({ executor, deadlineMs }) raised in the boot that builds it',
+    fix: fixFor(owner),
     meta: { statement, deadlineMs },
   });
 
@@ -41,18 +54,23 @@ export const rateLimitStoreTimeout = (statement: string, deadlineMs: number): Ht
 export function storeDeadline(
   deadlineMs: number = RATE_LIMIT_STORE_DEADLINE_MS,
   schedule: Scheduler = unrefSchedule,
+  owner: SharedStoreOwner = 'postgresRateLimitStore',
 ): StoreDeadline {
-  finiteCount('postgresRateLimitStore', 'deadlineMs', deadlineMs, 1);
+  finiteCount(owner, 'deadlineMs', deadlineMs, 1);
+  const handle = owner === 'postgresRateLimitStore' ? 'executor' : 'client';
   assert(
     deadlineMs <= MAX_TIMER_MS,
-    `postgresRateLimitStore deadlineMs is ${String(deadlineMs)}, past the longest delay a timer holds, so it would fire at once`,
-    `postgresRateLimitStore({ executor, deadlineMs: ${String(RATE_LIMIT_STORE_DEADLINE_MS)} })   # or any whole number of ms up to ${String(MAX_TIMER_MS)}`,
+    `${owner} deadlineMs is ${String(deadlineMs)}, past the longest delay a timer holds, so it would fire at once`,
+    `${owner}({ ${handle}, deadlineMs: ${String(RATE_LIMIT_STORE_DEADLINE_MS)} })   # or any whole number of ms up to ${String(MAX_TIMER_MS)}`,
   );
   return {
     bound<T>(statement: 'take' | 'peek', sending: Promise<T>): Promise<T> {
       let cancel: () => void = () => undefined;
       const late = new Promise<never>((_, reject) => {
-        cancel = schedule(() => reject(rateLimitStoreTimeout(statement, deadlineMs)), deadlineMs);
+        cancel = schedule(
+          () => reject(rateLimitStoreTimeout(statement, deadlineMs, owner)),
+          deadlineMs,
+        );
       });
       return Promise.race([sending, late]).finally(() => cancel());
     },

package/src/rate-limit.ts

@@ -1,16 +1,11 @@
 // Token-bucket rate limiting. The store is an interface so the same limiter runs in-memory in
-// dev/tests and against a shared tier in a multi-replica deployment — installed through
-// `httpServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
-// declaration; the bucket maths lives here so every driver agrees on the numbers.
-import { type Clock, systemClock } from '@ultimat3/core';
+// dev/tests and against a shared tier in a multi-replica deployment — named as `rateLimitStore` in
+// `apps/<app>/runtime.ts`, and refused at boot when its scope cannot keep the app's declaration;
+// the bucket maths lives here so every driver agrees on the numbers.
+import { addressNetwork, type Clock, liveClock } from '@ultimat3/core';
 import { httpCountInvalid } from './errors';
-import {
-  rateLimited,
-  rateLimitInvalid,
-  rateLimitNotShared,
-  rateLimitScopeUnset,
-  tenantBucketUnknown,
-} from './rate-limit-errors';
+import { DEFAULT_RATE_LIMIT } from './rate-limit-config';
+import { rateLimited, rateLimitNotShared } from './rate-limit-errors';
 import { rateLimitHeaders } from './rate-limit-headers';
 import { type RateLimitPeek, rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
@@ -73,98 +68,6 @@ export interface RateLimitConfig {
   readonly scope: RateLimitScope;
 }
 
-/**
- * Everything the framework can decide on its own. `scope` is NOT here: one process is the only
- * thing a framework can promise without being told, and defaulting to it made "we did not ask"
- * indistinguishable from "the app said one replica" — so the chart's `replicas: 3` enforced every
- * number three times over, silently, and the boot check that exists for this
- * (`assertRateLimitScope`) never fired because it only reads a `'shared'` declaration. The
- * comment that used to sit here was right about the fact and wrong about the conclusion: ask.
- */
-export const DEFAULT_RATE_LIMIT: Omit<RateLimitConfig, 'scope'> = {
-  enabled: true,
-  defaultBucket: 'default',
-  tenantBucket: null,
-  buckets: {
-    default: { capacity: 120, refillPerSecond: 2 },
-    // Login/signup style endpoints: slow, no burst.
-    auth: { capacity: 10, refillPerSecond: 0.2 },
-    mutation: { capacity: 30, refillPerSecond: 1 },
-  },
-};
-
-/**
- * `defineHttpConfig`'s one resolver for this slice, so the refusal happens where an author can
- * act on it rather than at the first request. A limiter that is switched off has nothing to be
- * wrong about, so `enabled: false` needs no declaration — and reads as `'process'`.
- */
-export const resolveRateLimitConfig = (
-  input: Partial<RateLimitConfig> | undefined,
-): RateLimitConfig => {
-  const merged = { ...DEFAULT_RATE_LIMIT, ...input };
-  // Here and not at the first request, for `assertRateLimitScope`'s reason: an unknown name falls
-  // through `bucketFor` to `default`, so a tenant allowance somebody wrote as 5,000 would silently
-  // be the 120-burst read bucket — looser than what the author declared, and invisible.
-  if (merged.tenantBucket !== null && !Object.hasOwn(merged.buckets, merged.tenantBucket)) {
-    throw tenantBucketUnknown(merged.tenantBucket, Object.keys(merged.buckets));
-  }
-  if (input?.scope !== undefined) return { ...merged, scope: input.scope };
-  if (!merged.enabled) return { ...merged, scope: 'process' };
-  throw rateLimitScopeUnset();
-};
-
-/** How a route, an action or a query spells a limit before it becomes a `Bucket`. */
-export interface RateLimitDeclaration {
-  /** The burst a caller may spend at once. */
-  readonly limit: number;
-  /** The window that refills it. */
-  readonly windowMs: number;
-}
-
-/**
- * `{ limit, windowMs }` as the limiter's own vocabulary: `5 / 600_000ms` is five held, one back
- * every two minutes. The only conversion between a declaration and the enforcement, so the
- * numbers an OpenAPI operation publishes and the numbers `withRouteBuckets` registers cannot
- * drift. It lives HERE, beside `Bucket` and the maths, because `@ultimat3/action` and
- * `@ultimat3/query` are the same tier and can never import each other — a copy in one of them is
- * a second answer to "what does this limit mean" for the other.
- *
- * **The COMPUTED rate is validated, not just the two declared halves.** The division is where a
- * pair that reads fine becomes one the limiter cannot run on, in both directions:
- * `{ limit: Number.MAX_VALUE, windowMs: 1 }` computes to `Infinity` — a bucket that never empties,
- * which is the same "declared a limit, enforced nothing" as `windowMs: 0` — and a tiny limit over
- * a huge window underflows to `0`, a bucket that never refills, so the endpoint is closed after
- * its first burst rather than limited.
- */
-export const toBucket = (owner: string, declared: RateLimitDeclaration): Bucket => {
-  const refuse = (reason: string): never => {
-    throw rateLimitInvalid({
-      owner,
-      limit: declared.limit,
-      windowMs: declared.windowMs,
-      reason,
-    });
-  };
-  // A capacity under one token cannot admit a single request, so the endpoint is closed, not
-  // limited — a policy's job, never a rate limit's.
-  if (!Number.isFinite(declared.limit) || declared.limit < 1) {
-    refuse('limit must be a finite number of at least 1 request');
-  }
-  if (!Number.isFinite(declared.windowMs) || declared.windowMs <= 0) {
-    refuse('windowMs must be finite and greater than zero');
-  }
-  const refillPerSecond = declared.limit / (declared.windowMs / 1000);
-  // Kept though the two checks above make it unreachable today: with `limit >= 1` and a finite
-  // window the smallest rate is ~5.6e-306, which is normal, not zero. It is the guard that has to
-  // move first if `limit >= 1` is ever relaxed.
-  if (!Number.isFinite(refillPerSecond) || refillPerSecond <= 0) {
-    refuse(
-      `the refill rate it computes to is ${refillPerSecond} per second, which is a bucket that never empties — nothing would be enforced`,
-    );
-  }
-  return { capacity: declared.limit, refillPerSecond };
-};
-
 interface BucketState {
   tokens: number;
   lastMs: number;
@@ -255,8 +158,9 @@ const assertFiniteKeyCap = (option: string, value: number): number => {
 /**
  * Default driver: correct for one process, which is exactly dev and tests.
  *
- * Bounded, because the key falls back to the connection address: a scan rotating through an
- * IPv6 /64 mints a fresh key per request, and an unbounded map turns that into an OOM. Two
+ * Bounded, because the key falls back to the connection address: a scan rotating through
+ * IPv6 /64s (one key each since v31, core's `addressNetwork`) mints a fresh key per prefix, and an
+ * unbounded map turns that into an OOM. Two
  * rules keep it flat. A refilled bucket is *forgotten*, not evicted — it answers exactly as a
  * missing one, so dropping it costs nothing and a scanner's one-request buckets qualify within
  * a second. Only if that is not enough does the cap evict live state, and then the entries
@@ -378,7 +282,7 @@ export const rateLimitSpends = (
       : parts.orgId !== null
         ? `org:${parts.orgId}`
         : parts.ip !== null
-          ? `ip:${parts.ip}`
+          ? `ip:${addressNetwork(parts.ip)}`
           : (parts.unattributed ?? 'ip:unknown');
   const spends: RateLimitSpend[] =
     buckets.route === null ? [] : [{ key: `${parts.routeName}|${subject}`, bucket: buckets.route }];
@@ -425,8 +329,9 @@ export const rateLimiter = (options: {
   clock?: Clock;
 }): RateLimiter => {
   const store = options.store ?? memoryRateLimitStore();
-  const clock = options.clock ?? systemClock;
-  const now = (): number => clock.now().getTime();
+  // Read at each call, never captured: with no clock passed, the limiter follows the `clock` port
+  // (`runtime.ts`, a test's `installClock`) even when that is installed after it was built.
+  const now = (): number => (options.clock ?? liveClock).now().getTime();
   // `Object.hasOwn`, never `buckets[name]` — the same read `error-map.ts`'s `statusFor` and
   // `naming.ts` already take for a table of this shape. `buckets` is a plain object literal, so it
   // holds every name on `Object.prototype`: `rateLimit: 'constructor'` read `Object` itself out of