@ultimat3/http 23.0.0 → 25.0.0

package/src/locale-prefix.ts

@@ -5,6 +5,7 @@
 
 import { type LocaleSources, localeConfig, resolveLocale, splitLocalePrefix } from '@ultimat3/i18n';
 import type { RequestContext } from './context';
+import { normalizePath } from './router';
 
 /** Methods whose redirect may change nothing but the URL. Anything else is a 308, never a 301. */
 const SAFE_METHODS = new Set(['GET', 'HEAD']);
@@ -26,7 +27,10 @@ export function routeLocalePrefix(
   if (prefix === undefined) return pathname;
   if (prefix.isDefault) {
     const mount = basePath === '/' || basePath === '' ? '' : basePath.replace(/\/$/, '');
-    const location = `${mount}${prefix.path}${ctx.url.search}`;
+    // Normalised exactly as the router would match it. The remainder is caller-written, and
+    // `//host/x` in a `Location` is a scheme-relative URL: a permanent, cacheable redirect off
+    // the site, answered before auth. One leading slash, no empty segment.
+    const location = `${mount}${normalizePath(prefix.path)}${ctx.url.search}`;
     // PERMANENT, and so not `redirect()`, whose statuses are an application's (it refuses 301 on
     // purpose: a cached permanent redirect cannot be taken back). This one is the framework's URL
     // scheme, and it IS permanent — the default locale is never prefixed, in any release.

package/src/locale.ts

@@ -32,30 +32,3 @@ export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
   header: TIMEZONE_HEADER,
   cookie: 'x_timezone',
 };
-
-/**
- * The raw value on a malformed escape, never a throw. `Cookie:` is attacker-controlled and
- * `decodeURIComponent('%')` is a bare `URIError` — thrown from the `locale` stage, which runs on
- * every request, so `curl -H 'Cookie: x-locale=%'` answered 500 and paged the on-call. Nothing is
- * loosened: a locale that is not in `supported` still falls back, and a time zone `Intl` cannot
- * format is still refused. `@ultimat3/auth` guards its own cookie reader the same way and for the
- * same reason; the guard is four lines and this package can never import that one (same tier).
- */
-const decodeCookieValue = (raw: string): string => {
-  try {
-    return decodeURIComponent(raw);
-  } catch {
-    return raw;
-  }
-};
-
-export const readCookie = (header: string | null, name: string): string | null => {
-  if (header === null) return null;
-  for (const part of header.split(';')) {
-    const index = part.indexOf('=');
-    if (index === -1) continue;
-    if (part.slice(0, index).trim() !== name) continue;
-    return decodeCookieValue(part.slice(index + 1).trim());
-  }
-  return null;
-};

package/src/navigation.ts

@@ -24,17 +24,42 @@ export function navigationPurpose(request: Request): NavigationPurpose | null {
 
 const SAFE = new Set(['GET', 'HEAD']);
 
+/** The schemes a navigation may be handed over to. Everything else is not a place to go. */
+const WEB_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:']);
+
 /**
  * What `x-ultimate-location` says. A target on THIS origin is its path, query and fragment and
  * nothing else: behind a TLS-terminating proxy the request URL this process sees is
  * `http://internal…`, so an absolute URL built from it named the public site as `http://` (HSTS
  * hid it; it was still wrong). The router resolves a path against the page it runs in, whose origin
  * is the one the visitor typed. A target on ANOTHER origin is kept exactly as the app gave it.
+ *
+ * Only `http:` and `https:` are ever handed over. The router LOADS what this header says, so a
+ * scheme that runs in the page (`javascript:`, `data:`) would be script in the app's own origin
+ * whenever a redirect target is caller-influenced. Such a target — and one that will not parse —
+ * answers the REQUESTED url instead, as a path: a document load of it re-runs the route, and the
+ * browser's own redirect handling refuses what this refused. Total, never a throw: it runs in the
+ * `response` stage, after the handler. A same-origin pathname is never emitted starting `//`
+ * (`hostlessPath`).
  */
 export function locationFor(target: string, base: URL): string {
+  const requested = `${base.pathname}${base.search}${base.hash}`;
+  if (!URL.canParse(target, base)) return requested;
   const resolved = new URL(target, base);
+  if (!WEB_PROTOCOLS.has(resolved.protocol)) return requested;
   if (resolved.origin !== base.origin) return target;
-  return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+  return `${hostlessPath(resolved.pathname)}${resolved.search}${resolved.hash}`;
+}
+
+/**
+ * A pathname that starts `//` — `/.//evil.test`, `/..//evil.test`, a request for `//evil.test` —
+ * is a path on THIS origin only while the URL keeps its host. Emitted alone it is a
+ * scheme-relative reference, and the router resolves it to another host and assigns that to
+ * `window.location`. `/.` in front is how WHATWG URL serialisation keeps a host-less `//` path a
+ * path; it resolves back to the same pathname, so nothing legitimate changes.
+ */
+function hostlessPath(pathname: string): string {
+  return pathname.startsWith('//') ? `/.${pathname}` : pathname;
 }
 
 /** "Load this with a real navigation" — never stored anywhere, it answers one request. */

package/src/overlay.ts

@@ -2,8 +2,10 @@
 // `--json` emits, so a code/cause/fix string can never differ between the three
 // surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
 // error contract, not UI copy, so they are not routed through the i18n catalog.
+
+import { escapeHtml } from '@ultimat3/core';
 import { factsOf, renderErrorLines, toProblem } from './error-facts';
-import { acceptsHtml, escapeHtml } from './html-render';
+import { acceptsHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 

package/src/peer-identity.ts

@@ -1,8 +1,7 @@
 // Who the MESH says is calling. TLS termination is the mesh's job (axiom 7) so the framework's
-// entire contribution is reading a header it has been TOLD to trust: Envoy's
-// `x-forwarded-client-cert`, at the same hop index `x-forwarded-for` is read at. Untrusted, this
-// header is worse than nothing — it authenticates — so an untrusted read answers `null` and
-// there is no second proxy-trust path to get it wrong in.
+// entire contribution is reading a header it has been TOLD to trust (`trustClientCertHeader`):
+// Envoy's `x-forwarded-client-cert`, at the hop index `x-forwarded-for` is read at. Untrusted,
+// this header is worse than nothing — it authenticates — so an untrusted read answers `null`.
 
 import { FORWARDED_CLIENT_CERT, type ForwardedInput, forwardedElement } from './forwarded';
 
@@ -82,11 +81,16 @@ const pairsOf = (element: string): ReadonlyMap<string, readonly string[]> => {
 };
 
 /**
- * The peer identity a TRUSTED proxy asserted, or `null`. `null` is the answer for an untrusted
- * deployment, a missing header and a chain shorter than `trustedProxyHops` alike: a certificate
+ * The peer identity a TRUSTED proxy asserted, or `null`. `null` is the answer for a deployment
+ * that did not declare `trustClientCertHeader`, an untrusted one, a missing header and a chain
+ * shorter than `trustedProxyHops` alike: a certificate
  * identity read from a hop nobody vouched for is a confident name for an attacker's claim.
  */
 export const peerIdentity = (input: ForwardedInput): PeerIdentity | null => {
+  // Its own declaration, never implied by `trustProxy`: that one says the proxy APPENDS to
+  // `x-forwarded-for`, and plenty of ingresses that do pass a client-sent certificate header
+  // straight through — where the caller would be naming its own identity.
+  if (!input.config.trustClientCertHeader) return null;
   const element = forwardedElement(
     input.headers.get(FORWARDED_CLIENT_CERT),
     input.config.trustedProxyHops,

package/src/pipeline.ts

@@ -3,9 +3,9 @@
 // middleware stack, so nothing can skip a stage and `/_x` and `pipeline.test.ts` can both read it.
 // The other two thirds of the lifecycle are siblings: `stages.ts` owns what each stage does, and
 // `finalize.ts` owns the promise that the tail always answers rather than rejecting.
-import { recordRequest, runWithContext, withSpan } from '@ultimat3/core';
+import { beginWork, recordRequest, runWithContext, withSpan } from '@ultimat3/core';
 import { defineHttpConfig, type HttpConfig } from './config';
-import { asCtx, createRequestContext, elapsedMs, type RequestContext } from './context';
+import { asCtx, elapsedMs, type RequestContext, requestContext } from './context';
 import { readCorrelation } from './correlation';
 import { type Deadline, startDeadline } from './deadline';
 import { pipelineNoResponse } from './errors';
@@ -14,8 +14,9 @@ import { clientAddress, clientUsedHttps } from './forwarded';
 import type { ServerHooks } from './hooks';
 import type { Middleware } from './middleware';
 import { peerIdentity } from './peer-identity';
-import { assertRateLimitScope, createRateLimiter, type RateLimiter } from './rate-limit';
+import { assertRateLimitScope, type RateLimiter, rateLimiter } from './rate-limit';
 import { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
+import { assertInstalledRateLimitScope } from './rate-limit-installed';
 import { UltimateRequest } from './request';
 import { problem } from './response';
 import type { RouteTable } from './router';
@@ -56,7 +57,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'auth',
     phase: 'request',
-    why: 'before rate limiting so the limiter keys per actor and per tenant instead of punishing a shared NAT address',
+    why: 'before rate limiting so the limiter keys per actor and per tenant instead of punishing a shared NAT address — and a request that FAILS a required route is refused here, so this stage spends an allowance keyed on the address alone for it: a failed credential is metered, a signed-in caller behind the same address is not',
   },
   {
     name: 'rate-limit',
@@ -66,7 +67,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'csrf',
     phase: 'request',
-    why: 'after auth so it only judges a caller holding an AMBIENT credential — a bearer token and an anonymous call are both exempt — and before body so a forged write never makes the server allocate its payload. CORS cannot cover this: application/x-www-form-urlencoded is a simple content type, so a cross-site form post is sent and executed and only the RESPONSE is withheld',
+    why: 'after auth so it knows who is calling: a bearer token is exempt (not ambient), and an anonymous write is judged like a signed-in one whenever it carries browser evidence, because a forged sign-in is a forged write — and before body so a forged write never makes the server allocate its payload. CORS cannot cover this: application/x-www-form-urlencoded is a simple content type, so a cross-site form post is sent and executed and only the RESPONSE is withheld',
   },
   {
     name: 'body',
@@ -109,7 +110,7 @@ export interface PipelineDeps {
   readonly hooks?: ServerHooks;
   readonly middleware?: readonly Middleware[];
   /**
-   * A limiter built elsewhere — `createServer({ rateLimitStore })` is the one supported way, and
+   * A limiter built elsewhere — `httpServer({ rateLimitStore })` is the one supported way, and
    * it hands over a limiter built from the SAME merged config this constructor would have built.
    * One passed from anywhere else resolves bucket names against the table IT closed over, which
    * is why `assertRouteBuckets` compares that table against the routes' declarations and refuses
@@ -135,16 +136,19 @@ export interface Pipeline {
   handle(request: Request, init: HandleInit): Promise<Response>;
 }
 
-export const createPipeline = (deps: PipelineDeps): Pipeline => {
+export const httpPipeline = (deps: PipelineDeps): Pipeline => {
   // Routes first, config second, and the merge here: `defineHttpConfig` cannot see a route, so a
   // bucket a route declares only becomes real at the construction that holds both. Idempotent, so
-  // a config `createServer` already merged passes through unchanged.
+  // a config `httpServer` already merged passes through unchanged.
   const config = withRouteBuckets(deps.config ?? defineHttpConfig(), deps.table.routes);
-  const limiter = deps.limiter ?? createRateLimiter({ config: config.rateLimit });
-  // Here rather than in `createServer`: this is the one construction path every server, test and
+  const limiter = deps.limiter ?? rateLimiter({ config: config.rateLimit });
+  // Here rather than in `httpServer`: this is the one construction path every server, test and
   // embedder shares, so a limiter that cannot keep the app's declaration is refused exactly once.
   // Two halves of one question — where the counters live, and which buckets the limiter holds.
   assertRateLimitScope(config.rateLimit, limiter);
+  // The third half: where an action's or a query's declared `rateLimit:` is counted. Under a
+  // `'shared'` declaration that store is held to the same promise as this pipeline's own.
+  assertInstalledRateLimitScope(config.rateLimit);
   assertRouteBuckets(limiter, deps.table.routes);
   const run = stageRunners({
     table: deps.table,
@@ -188,8 +192,23 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         // own; this race is the half that answers the SOCKET when it does not. `work` keeps its
         // own handler either way — a rejection arriving after the deadline already won is still
         // a rejection, and an unhandled one takes the process down.
-        void work.catch(() => undefined);
-        await Promise.race([work, deadline.expired]);
+        let settled = false;
+        const settle = (): void => {
+          settled = true;
+        };
+        void work.then(settle, settle);
+        try {
+          await Promise.race([work, deadline.expired]);
+        } finally {
+          // The deadline won and the handler is still running: it holds its pool slot and
+          // whatever it was writing. The caller's own count ends when this response leaves, so
+          // the orphan is counted in its own right until it settles — a drain that saw an idle
+          // process here closed the pool under it.
+          if (!settled) {
+            const done = beginWork();
+            void work.then(done, done);
+          }
+        }
       }
     } catch (error) {
       ctx.error = error;
@@ -228,7 +247,7 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         socketAddress: init.ip ?? null,
         urlProtocol: url.protocol,
       };
-      const ctx = createRequestContext({
+      const ctx = requestContext({
         url,
         method: raw.method,
         role: init.role,

package/src/preferences.ts

@@ -2,10 +2,10 @@
 // and `auth` calls it again once the actor's saved preference is known. WHERE each value is read
 // from is this file's; what a locale or a zone IS stays `@ultimat3/i18n`'s and `@ultimat3/time`'s.
 
+import { readCookie } from '@ultimat3/core';
 import { resolveTimeZone } from '@ultimat3/time';
 import type { HttpConfig } from './config';
 import type { RequestContext } from './context';
-import { readCookie } from './locale';
 import { requestLocale } from './locale-prefix';
 import type { UltimateRequest } from './request';
 

package/src/problem-meta.ts

@@ -12,6 +12,10 @@
 // it was. Measured need: an app's `X_SESSION_CHECKOUT_BUSY` carried `{ sessionId, title, state }`
 // in `meta` and its island recovered the id by running a UUID regex over `cause`.
 
+// The public-cause predicate and both of its tables are `@ultimat3/core`'s (`public-cause.ts`): the
+// MCP error data and the agent `tool_result` ask the question this package's problem document
+// does. This file only WRITES the app half — a reader imports `hasPublicCause` from core.
+import { registerPublicCause, resetPublicCauses } from '@ultimat3/core';
 import { ERROR_STATUS } from './error-map';
 import { problemMetaInvalid } from './errors';
 
@@ -47,20 +51,6 @@ const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
 /** Per app-owned code, the `meta` keys its documents carry. A `Map`, for `APP_ERROR_STATUS`'s reason. */
 const DECLARED = new Map<string, readonly string[]>();
 
-/**
- * The 5xx codes whose `cause` a caller may read. Every other 5xx document carries the code and the
- * request id and a fixed sentence: `X_DB_STATEMENT_FAILED` has a status row, so the old "blank only
- * what nobody classified" rule served the Postgres message and the SQL statement in a production
- * 500. The framework's four are refusals whose cause IS the instruction — back off, retry.
- */
-const FRAMEWORK_PUBLIC_CAUSE: ReadonlySet<string> = new Set([
-  'X_DRAINING',
-  'X_OVERLOADED',
-  'X_FLIGHT_GATE_OVERLOADED',
-  'X_TIMEOUT',
-]);
-const APP_PUBLIC_CAUSE = new Set<string>();
-
 /** Per code: the `meta` keys, a public cause, or both. A bare list is the keys alone. */
 export type ProblemMetaDeclaration =
   | readonly string[]
@@ -98,7 +88,7 @@ export const registerProblemMeta = (
       : ((declaration as { keys?: readonly string[] }).keys ?? []);
     const publicCause = !listed && (declaration as { publicCause?: boolean }).publicCause === true;
     if (!listed && keys.length === 0 && publicCause) {
-      APP_PUBLIC_CAUSE.add(code);
+      registerPublicCause(code);
       continue;
     }
     if (keys.length === 0) {
@@ -122,20 +112,16 @@ export const registerProblemMeta = (
       throw problemMetaInvalid(code, `already declared as [${existing.join(', ')}] by this app`);
     }
     DECLARED.set(code, [...keys]);
-    if (publicCause) APP_PUBLIC_CAUSE.add(code);
+    if (publicCause) registerPublicCause(code);
   }
 };
 
 /** Test seam. Production registers once at boot and never unregisters. */
 export const resetProblemMeta = (): void => {
   DECLARED.clear();
-  APP_PUBLIC_CAUSE.clear();
+  resetPublicCauses();
 };
 
-/** Whether a 5xx document for `code` may carry its authored `cause`. */
-export const hasPublicCause = (code: string): boolean =>
-  FRAMEWORK_PUBLIC_CAUSE.has(code) || APP_PUBLIC_CAUSE.has(code);
-
 /** The keys declared for a code, or `undefined` when nothing was — which is every framework code. */
 export const problemMetaKeysFor = (code: string): readonly string[] | undefined =>
   DECLARED.get(code);

package/src/rate-limit-buckets.ts

@@ -5,7 +5,11 @@
 
 import type { HttpConfig } from './config';
 import type { Bucket, RateLimiter } from './rate-limit';
-import { rateLimitBucketConflict, rateLimitBucketUnbound } from './rate-limit-errors';
+import {
+  rateLimitBucketConflict,
+  rateLimitBucketForPrimitive,
+  rateLimitBucketUnbound,
+} from './rate-limit-errors';
 import type { Route } from './router';
 
 const same = (a: Bucket, b: Bucket): boolean =>
@@ -20,10 +24,30 @@ const same = (a: Bucket, b: Bucket): boolean =>
  * number an author read, an OpenAPI document published and nothing enforced, which is the exact
  * failure this seam closes. Same shape as `@ultimat3/auth`'s `AuthLimiter` policy check.
  *
- * Idempotent, so both construction paths (`createServer`, and `createPipeline` under it) can apply
+ * Idempotent, so both construction paths (`httpServer`, and `httpPipeline` under it) can apply
  * it: a second pass compares each bucket against the copy the first pass registered.
  */
+/**
+ * A configured bucket keyed by a mounted primitive's NAME, which since 25.0.0 limits nothing.
+ * `default`, the tenant bucket and any name a route really selects are live, so they pass.
+ */
+const assertNoPrimitiveBuckets = (config: HttpConfig, routes: readonly Route[]): void => {
+  const selected = new Set<string>(['default']);
+  if (config.rateLimit.tenantBucket !== null) selected.add(config.rateLimit.tenantBucket);
+  for (const route of routes) {
+    if (route.meta.rateLimit !== undefined) selected.add(route.meta.rateLimit);
+  }
+  for (const route of routes) {
+    const primitive = route.meta.primitive;
+    const name = route.meta.name;
+    if (primitive === undefined || selected.has(name)) continue;
+    if (!Object.hasOwn(config.rateLimit.buckets, name)) continue;
+    throw rateLimitBucketForPrimitive({ bucket: name, primitive });
+  }
+};
+
 export const withRouteBuckets = (config: HttpConfig, routes: readonly Route[]): HttpConfig => {
+  assertNoPrimitiveBuckets(config, routes);
   const declared = new Map<string, { readonly bucket: Bucket; readonly route: string }>();
   for (const route of routes) {
     const bucket = route.meta.rateLimitBucket;

package/src/rate-limit-errors.ts

@@ -1,7 +1,7 @@
 // Every refusal a rate limit produces: the 429 a caller is answered with, and the six declaration
 // faults the boot refuses. Split from `errors.ts` at the 500-line ceiling, on the seam it already
-// had. The codes and their TITLES stay there, which is the one registry — `registerErrorCodes`
-// must see them all in a single call.
+// had. The codes, their TITLES and the `retry-after` class are `error-titles.ts`'s, the one
+// registry — `registerErrorCodes` must see them all in a single call.
 import { HttpError } from './errors';
 
 /**
@@ -19,19 +19,24 @@ export const rateLimited = (key: string, retryAfterSeconds: number): HttpError =
   });
 
 /**
- * At `createServer`/`createPipeline`, never on the request. `replicas: 3` behind one config means
+ * At `httpServer`/`httpPipeline`, never on the request. `replicas: 3` behind one config means
  * each process holds its own counters, so every configured number is enforced three times over —
  * a green `x verify` and a limit that is not the limit. The declaration is the app's because the
  * framework cannot see its replica count, and a framework that guessed would guess wrong.
  */
-export const rateLimitNotShared = (found: 'process' | 'disabled'): HttpError =>
+export const rateLimitNotShared = (found: 'process' | 'disabled' | 'installed'): HttpError =>
   new HttpError({
     code: 'X_RATE_LIMIT_NOT_SHARED',
     cause:
       found === 'disabled'
         ? "http.rateLimit.scope is 'shared' but http.rateLimit.enabled is false, so the fleet-wide limit is enforced nowhere"
-        : "http.rateLimit.scope is 'shared' but the installed store keeps its counters in this process, so each replica would enforce the full bucket on its own",
-    fix: "createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }) — or defineHttpConfig({ rateLimit: { scope: 'process' } }) to accept per-replica limits",
+        : found === 'installed'
+          ? "http.rateLimit.scope is 'shared' but the store actions and queries spend their declared rateLimit from keeps its counters in this process, so each replica would enforce every declared limit on its own"
+          : "http.rateLimit.scope is 'shared' but the installed store keeps its counters in this process, so each replica would enforce the full bucket on its own",
+    fix:
+      found === 'installed'
+        ? 'installRateLimitStore(rateLimitStore) at boot, with the same postgresRateLimitStore({ executor }) passed to httpServer({ routes, rateLimitStore })'
+        : "httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }) — or defineHttpConfig({ rateLimit: { scope: 'process' } }) to accept per-replica limits",
   });
 
 /**
@@ -46,7 +51,28 @@ interface BucketNumbers {
 const numbers = (bucket: BucketNumbers): string => `${bucket.capacity} / ${bucket.refillPerSecond}`;
 
 /**
- * Two declarations of one bucket, at `createServer`/`createPipeline`. Neither wins: an app that
+ * `rateLimit.buckets.<name>` where `<name>` is a mounted action's or query's own name. Since
+ * 25.0.0 a primitive's route carries no `meta.rateLimit` — the primitive spends its own declared
+ * limit on every surface — so that bucket limits nothing. Refused rather than kept: a number an
+ * operator reads in `configureHttp()` and nothing enforces is the failure every 12a deletion turns
+ * into a code. `X_CONFIG_INVALID`, borrowed, because it is a config key the framework cannot honour.
+ */
+export const rateLimitBucketForPrimitive = (input: {
+  bucket: string;
+  primitive: 'action' | 'query';
+}): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `rateLimit.buckets.${input.bucket} is named after the mounted ${input.primitive} "${input.bucket}", and since 25.0.0 an ${input.primitive}'s route spends no named bucket — the ${input.primitive} spends its own declared rateLimit on every surface — so this bucket would limit nothing`,
+    fix:
+      input.primitive === 'query'
+        ? `query({ …, rateLimit: { limit, windowMs } })   # rateLimit.buckets.${input.bucket} no longer limits a query since 25.0.0 — delete it from configureHttp() and declare the limit on the query`
+        : `action({ …, rateLimit: { limit, windowMs } })   # rateLimit.buckets.${input.bucket} no longer limits an action since 25.0.0 — delete it from configureHttp() and declare the limit on the action`,
+    meta: { option: `rateLimit.buckets.${input.bucket}`, primitive: input.primitive },
+  });
+
+/**
+ * Two declarations of one bucket, at `httpServer`/`httpPipeline`. Neither wins: an app that
  * configures `rateLimit.buckets.<name>` and a route that declares its own numbers under that name
  * disagree about what is enforced, and whichever a merge picked would leave the other a number
  * someone read and nothing applies — the failure this seam exists to end. The message speaks
@@ -84,7 +110,7 @@ export const rateLimitBucketConflict = (input: {
 
 /**
  * A route declares its own bucket and the INSTALLED limiter cannot enforce it — at
- * `createPipeline`, never on the request. `createRateLimiter` closes over the config it was built
+ * `httpPipeline`, never on the request. `rateLimiter` closes over the config it was built
  * with, so a limiter constructed before the routes existed resolves the route's bucket name
  * through `bucketFor`, misses, and falls through to `default`: measured at 120 burst and 21 of 21
  * requests allowed for a route declaring 5. Silent, and looser than what the author wrote.
@@ -109,7 +135,7 @@ export const rateLimitBucketUnbound = (input: {
         ? 'does not hold that bucket, so the route would run on the default one'
         : `holds ${numbers(input.found)} for it`
     }`,
-    fix: 'pass the STORE and let the pipeline build the limiter — createServer({ routes, rateLimitStore }) — so the bucket table is the one the routes registered',
+    fix: 'pass the STORE and let the pipeline build the limiter — httpServer({ routes, rateLimitStore }) — so the bucket table is the one the routes registered',
   });
 
 /**
@@ -125,7 +151,7 @@ export const rateLimitScopeUnset = (): HttpError =>
     code: 'X_RATE_LIMIT_SCOPE_UNSET',
     cause:
       'http.rateLimit is enabled and the deployment has not declared http.rateLimit.scope, so the numbers below it are per replica rather than per fleet',
-    fix: "defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit — a process booted by x dev or apps/web/server.ts derives it from the store it installed and never declares it",
+    fix: "defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit — a process booted by x dev or apps/web/server.ts derives it from the store it installed and never declares it",
   });
 
 /**

package/src/rate-limit-headers.ts

@@ -0,0 +1,40 @@
+// A rate-limit decision as the three `RateLimit-*` response headers. One rendering, so the
+// pipeline's limiter, a bearer mount's per-token allowance and a primitive's declared bucket can
+// never answer a client in two shapes.
+
+import type { RequestContext } from './context';
+import type { RateLimitDecision } from './rate-limit';
+
+/**
+ * Lowercase names, as every writer sets them on `ctx.headers`. The reset is whole seconds from
+ * `nowMs`, floored at 0: a decision read after its own reset passed is a full bucket, not a
+ * negative wait.
+ */
+export const rateLimitHeaders = (
+  decision: RateLimitDecision,
+  nowMs: number,
+): Record<string, string> => ({
+  'ratelimit-limit': String(decision.limit),
+  'ratelimit-remaining': String(decision.remaining),
+  'ratelimit-reset': String(Math.max(0, Math.ceil((decision.resetAtMs - nowMs) / 1000))),
+});
+
+/**
+ * A handler-spent bucket onto the answer (`RouteMeta.rateLimitedBy: 'handler'`), when it is the
+ * one closest to refusing — the rule the `rate-limit` stage follows across its own buckets:
+ * `remaining: 118` off the tenant's while the primitive's holds 1 tells a client to proceed and
+ * then refuses its next call. A refusal always wins. Set on the CONTEXT before the handler throws,
+ * so the `error-map` stage's 429 carries these headers and reads `Retry-After` off `ctx.rateLimit`.
+ */
+export const publishRateLimit = (
+  ctx: RequestContext,
+  decision: RateLimitDecision,
+  nowMs: number,
+): void => {
+  const prior = ctx.rateLimit;
+  if (decision.allowed && prior !== undefined && prior.remaining < decision.remaining) return;
+  ctx.rateLimit = decision;
+  for (const [name, value] of Object.entries(rateLimitHeaders(decision, nowMs))) {
+    ctx.headers.set(name, value);
+  }
+};

package/src/rate-limit-installed.ts

@@ -0,0 +1,79 @@
+// 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 })`.
+
+import type { 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. */
+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.
+ */
+const frames: { readonly store: RateLimitStore }[] = [];
+
+const current = (): RateLimitStore => frames.at(-1)?.store ?? base;
+const isChosen = (): boolean => baseChosen || frames.length > 0;
+
+/**
+ * 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`.
+ */
+export const installRateLimitStore = (store: RateLimitStore): void => {
+  base = store;
+  baseChosen = true;
+};
+
+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;
+}
+
+/**
+ * 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.
+ */
+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);
+  };
+};
+
+/**
+ * `assertRateLimitScope`'s rule for the primitives' half: a `'shared'` declaration says every
+ * number is the fleet's, and an action or query limit counted in one process' memory is not.
+ */
+export const assertInstalledRateLimitScope = (config: RateLimitConfig): void => {
+  if (config.scope !== 'shared') return;
+  if (current().scope !== 'shared') throw rateLimitNotShared('installed');
+};

package/src/rate-limit-peek.ts

@@ -0,0 +1,32 @@
+// The READ half of a token bucket: what a key holds now, refill applied, with nothing written.
+// Split from `rate-limit.ts` at the size ceiling; every `RateLimitStore.peek` answers through it.
+
+import type { Bucket } from './rate-limit';
+
+/** A read of a bucket: whole tokens left, and how long until one more is there when none is. */
+export interface RateLimitPeek {
+  readonly remaining: number;
+  /** `0` while a whole token is left; otherwise the seconds until one is, at least 1. */
+  readonly retryAfterSeconds: number;
+}
+
+/**
+ * The peek every store answers from the tokens it computed — exported for the reason
+ * `rateLimitDecision` is: two drivers deriving "when may I come back" separately is two answers.
+ * A bucket that never refills is clamped to a day, as a decision's `Retry-After` is.
+ */
+export const rateLimitPeek = (bucket: Bucket, tokens: number): RateLimitPeek => {
+  if (tokens >= 1) return { remaining: Math.floor(tokens), retryAfterSeconds: 0 };
+  const seconds =
+    bucket.refillPerSecond > 0 ? Math.min(86_400, (1 - tokens) / bucket.refillPerSecond) : 86_400;
+  return { remaining: 0, retryAfterSeconds: Math.max(1, Math.ceil(seconds)) };
+};
+
+/** `stored` tokens last written at `lastMs`, refilled to `nowMs` and capped — no mutation. */
+export const refilledTokens = (
+  bucket: Bucket,
+  stored: number,
+  lastMs: number,
+  nowMs: number,
+): number =>
+  Math.min(bucket.capacity, stored + (Math.max(0, nowMs - lastMs) / 1000) * bucket.refillPerSecond);