@ultimat3/http 24.0.0 → 25.1.0

package/src/errors.ts

@@ -1,46 +1,18 @@
 // The HTTP layer's stable error codes. Every throw in this package goes through a
 // factory here so a code, a cause and an exact fix always travel together — the
 // terminal, the dev overlay and `--json` all render the same three strings.
-import {
-  deniedCallerFix,
-  registerErrorCodes,
-  registerErrorRetry,
-  renderFixShellArg,
-  renderThrowable,
-  UltimateError,
-} from '@ultimat3/core';
-
-/** Codes this package declares and owns. */
-export const HTTP_OWNED_ERROR_CODES = [
-  'X_ROUTE_NOT_FOUND',
-  'X_METHOD_NOT_ALLOWED',
-  'X_PATH_INVALID',
-  'X_BODY_INVALID',
-  'X_RATE_LIMITED',
-  'X_BUILD_SKEW',
-  'X_ROUTE_CONFLICT',
-  'X_SERVER_NOT_STARTED',
-  'X_PIPELINE_NO_RESPONSE',
-  'X_PIPELINE_FINALIZE_FAILED',
-  'X_NO_REQUEST',
-  'X_ERROR_STATUS_INVALID',
-  'X_PROBLEM_META_INVALID',
-  'X_CORS_CONFIG_INVALID',
-  'X_CSP_DIRECTIVE_INVALID',
-  'X_RATE_LIMIT_NOT_SHARED',
-  'X_RATE_LIMIT_BUCKET_CONFLICT',
-  'X_RATE_LIMIT_BUCKET_UNBOUND',
-  'X_RATE_LIMIT_SCOPE_UNSET',
-  'X_RATE_LIMIT_INVALID',
-  'X_RATE_LIMIT_STORE_UNAVAILABLE',
-  'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
-  'X_TRUST_PROXY_UNSET',
-  'X_OVERLOADED',
-  'X_CSRF_BLOCKED',
-  'X_WEBHOOK_SIGNATURE_INVALID',
-  'X_WEBHOOK_SIGNATURE_STALE',
-  'X_BEARER_MOUNT_INVALID',
-] as const;
+import { deniedCallerFix, renderFixShellArg, renderThrowable, UltimateError } from '@ultimat3/core';
+// The owned code list, its titles and its retry classes are `error-titles.ts` — the one module
+// `sideEffects` lists, imported bare here and from the barrel — so this module is side-effect-free
+// and a chunk keeps only the classes it constructs. Re-exported: every name still reads from here.
+import './error-titles';
+import { HTTP_OWNED_ERROR_CODES } from './error-titles';
+
+export {
+  HTTP_ERROR_TITLES,
+  HTTP_OWNED_ERROR_CODES,
+  type HttpOwnedErrorCode,
+} from './error-titles';
 
 /**
  * Codes this package throws but does NOT own. `X_FORBIDDEN` belongs to `@ultimat3/policy` and
@@ -71,60 +43,8 @@ export const HTTP_BORROWED_ERROR_CODES = [
 /** Every code http can throw: the ones it owns plus the two it borrows. */
 export const HTTP_ERROR_CODES = [...HTTP_OWNED_ERROR_CODES, ...HTTP_BORROWED_ERROR_CODES] as const;
 
-export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
 export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
 
-/** Human title per owned code. Kept next to the codes so one edit updates every surface. */
-export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
-  X_ROUTE_NOT_FOUND: 'no route matches this request',
-  X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
-  X_PATH_INVALID: 'a path segment is not valid percent-encoding',
-  X_BODY_INVALID: 'request body failed its schema',
-  X_RATE_LIMITED: 'rate limit exhausted for this key',
-  X_BUILD_SKEW: 'client build id does not match the server build id',
-  X_ROUTE_CONFLICT: 'two routes claim the same path',
-  X_SERVER_NOT_STARTED: 'server handle used before start()',
-  X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
-  X_PIPELINE_FINALIZE_FAILED: 'a finalize stage threw instead of finishing the response',
-  X_NO_REQUEST: 'the inbound request is not in scope here',
-  X_ERROR_STATUS_INVALID: 'an error code cannot be mapped to that status',
-  X_PROBLEM_META_INVALID: 'a problem document cannot carry that meta declaration',
-  X_CORS_CONFIG_INVALID: 'the cors config can never produce a working response',
-  X_CSP_DIRECTIVE_INVALID: 'a csp extension would emit something other than the directive it names',
-  X_RATE_LIMIT_NOT_SHARED: 'the rate limit is declared fleet-wide and the store is per-process',
-  X_RATE_LIMIT_BUCKET_CONFLICT: 'a route and the config declare different numbers for one bucket',
-  X_RATE_LIMIT_BUCKET_UNBOUND: 'the installed limiter cannot enforce a bucket a route declares',
-  X_RATE_LIMIT_SCOPE_UNSET: 'the deployment has not said where the rate limiter keeps its counters',
-  X_RATE_LIMIT_INVALID: 'a declared rate limit computes to numbers the limiter cannot run on',
-  X_RATE_LIMIT_STORE_UNAVAILABLE: 'the shared rate-limit store did not answer, so nothing decided',
-  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 'the tenant allowance names a bucket nothing declares',
-  X_TRUST_PROXY_UNSET: 'proxy headers are trusted without saying how many proxies are in front',
-  X_OVERLOADED: 'in-flight requests are at the configured ceiling',
-  X_CSRF_BLOCKED: 'an unsafe request that did not prove same-origin',
-  X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
-  X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
-  X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
-};
-
-// Registered at module load, unconditionally, in one call, so core's registry renders OUR title
-// everywhere. Without this the registry humanises the code (`X_BUILD_SKEW` → "build skew"); with a
-// presence guard, a package that claimed one of these first would silently keep its own title.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(HTTP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
-);
-
-/**
- * The two codes this package throws that a client is SUPPOSED to come back from, and both say
- * when: each carries `retry-after` on the response. Unclassified defaults to `terminal`, which is
- * right for the rest — a 404, a 422 and a wiring bug all fail the same way forever — but wrong for
- * a shed request, whose whole contract is "not now". Only codes this package OWNS are listed:
- * `X_TIMEOUT` and `X_DRAINING` are borrowed, and core classifies its own.
- */
-registerErrorRetry({
-  X_RATE_LIMITED: 'retry-after',
-  X_OVERLOADED: 'retry-after',
-});
-
 // No `docs:` below. `UltimateError` fills it from `describeErrorCode(code).docs`, which is
 // `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
 // `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE
@@ -274,7 +194,7 @@ export const serverNotStarted = (member: string): HttpError =>
   new HttpError({
     code: 'X_SERVER_NOT_STARTED',
     cause: `${member} was read before start() bound a socket`,
-    fix: 'call createServer({ ... }).start() before reading url()',
+    fix: 'call httpServer({ ... }).start() before reading url()',
   });
 
 export const pipelineNoResponse = (stage: string): HttpError =>
@@ -297,7 +217,7 @@ export const finalizeFailed = (stage: string, cause: unknown): HttpError =>
     // runs a `Proxy`'s `getPrototypeOf` trap and `.message` runs a getter, so both reads go
     // through core's total `renderThrowable` — the fast path was the last unguarded one here.
     cause: `the "${stage}" stage threw while finishing the response: ${renderThrowable(cause)}`,
-    fix: 'return a Response built here — json(), text(), html() or redirect() from @ultimat3/http; one whose headers cannot be set, like Response.redirect(), cannot take the final headers',
+    fix: 'return a Response built here — jsonResponse(), textResponse(), html() or redirect() from @ultimat3/http; one whose headers cannot be set, like Response.redirect(), cannot take the final headers',
   });
 
 /**
@@ -379,6 +299,36 @@ export const trustProxyUnset = (): HttpError =>
     fix: 'set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process that is reached directly; an embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }',
   });
 
+/**
+ * `http.drainTimeoutMs`, deleted in 25.0.0. It was a second knob for the budget `drain.deadlineMs`
+ * owns: applied after `lifecycleForRole` on the web role only, so the web role and every other
+ * role could drain on different budgets from one app config. Refused by key PRESENCE — a JS caller
+ * or a spread still handing it over gets the edit, never a silently ignored number.
+ */
+export const drainTimeoutDeleted = (): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'http.drainTimeoutMs was deleted in 25.0.0: drain.deadlineMs is the one drain budget, for every role, and a second key for the web role alone is two answers to how long SIGTERM waits',
+    fix: 'drain: { deadlineMs: 25_000 }   # in app.config.ts: drain.deadlineMs is the one budget every role, web included, drains on — and delete drainTimeoutMs from configureHttp({ … })',
+    meta: { option: 'drainTimeoutMs', replacement: 'drain.deadlineMs' },
+  });
+
+/**
+ * `http.buildIdHeader`, deleted in 25.0.0. The pipeline read the client's build claim from it and
+ * stamped its own back under it, while the typed client, the service worker and `DEFAULT_CORS`
+ * all spelled core's `BUILD_ID_HEADER` — so a renamed header was a server listening for a header
+ * no client of it sent, and skew detection off in silence. Refused by key PRESENCE.
+ */
+export const buildIdHeaderDeleted = (): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'http.buildIdHeader was deleted in 25.0.0: the build-id header is core BUILD_ID_HEADER (x-ultimate-build), which every client sends, and a renamed one is a header no client of this server sends',
+    fix: "import { BUILD_ID_HEADER } from '@ultimat3/core'   # the one build-id header, not configurable — and delete buildIdHeader from configureHttp({ … })",
+    meta: { option: 'buildIdHeader', replacement: 'BUILD_ID_HEADER' },
+  });
+
 /**
  * A numeric knob that is not a count, refused where `app.config.ts` still names it.
  *
@@ -497,3 +447,17 @@ export const webhookSignatureStale = (
     fix: 'sync the sending host clock with NTP, or widen the window with verifyWebhookSignature(request, { secret, toleranceMs: 600_000 }) if the sender queues deliveries for longer than that',
     meta: { skewMs, toleranceMs },
   });
+
+/**
+ * The receiver holds no secret. Not a weak key — NO key: an HMAC under '' is a mac anyone can
+ * compute, so verifying against it accepts every forged delivery. `X_CONFIG_INVALID` because the
+ * repair is the route's configuration and nothing a sender does can fix it. `shape` is `typeof`
+ * or "an empty string" — never the value, which is a credential when it is one.
+ */
+export const webhookSecretMissing = (shape: string): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `verifyWebhookSignature was given ${shape} as its secret, and a mac under an empty key is one anyone can compute — every forged delivery would verify`,
+    fix: "verifyWebhookSignature(request, { secret: process.env.WEBHOOK_SECRET ?? '' }) in the api/ route receiving it, with WEBHOOK_SECRET set in the deployment environment to the signing secret the sender shows for this endpoint — an unset variable is then refused here rather than verified against",
+    meta: { option: 'webhook secret' },
+  });

package/src/forwarded.ts

@@ -43,10 +43,25 @@ export const forwardedElement = (
   return list[index];
 };
 
-/** The plain-list form: `x-forwarded-for`, `x-forwarded-proto`. */
+/** The plain-list form: `x-forwarded-for`. */
 export const forwardedValue = (header: string | null, hops: number): string | undefined =>
   forwardedElement(header, hops);
 
+/**
+ * `x-forwarded-proto`, which proxies OVERWRITE far more often than they append (nginx's `$scheme`,
+ * an ALB, Traefik): behind two hops it holds one value while `x-forwarded-for` holds two. A full
+ * chain is read exactly like an address. A SHORTER one is not a forgery here: an overwrite erased
+ * everything client-ward of it, so every entry left was written by a trusted hop, and the
+ * outermost of them — index 0 — is the one that saw the client's leg. A client value survives only
+ * when no trusted hop writes the header at all, the same exposure `hops: 1` has always had.
+ */
+export const forwardedProto = (header: string | null, hops: number): string | undefined => {
+  if (header === null || hops < 1) return undefined;
+  const list = plainSplit(header, ',');
+  if (list.length === 0) return undefined;
+  return list[Math.max(0, list.length - hops)];
+};
+
 /**
  * `1.2.3.4:5678` and `[::1]:443` are both legal in an `x-forwarded-for` entry; the port is the
  * proxy's bookkeeping and would make every connection its own rate-limit bucket.
@@ -91,12 +106,12 @@ export const clientAddress = (input: ForwardedInput): string | null =>
   forwardedClientAddress(input.headers, input.config) ?? input.socketAddress;
 
 /**
- * Whether the CLIENT's leg of the connection was TLS. Read at the same hop index as the address,
- * because `x-forwarded-proto` is as forgeable as `x-forwarded-for` — and this one decides whether
- * a two-year `includeSubDomains` HSTS policy goes out.
+ * Whether the CLIENT's leg of the connection was TLS. Hop-indexed like the address, because
+ * `x-forwarded-proto` is as forgeable as `x-forwarded-for` — and this one decides whether a
+ * two-year `includeSubDomains` HSTS policy goes out. `forwardedProto` says why a short list counts.
  */
 export const clientUsedHttps = (input: ForwardedInput): boolean => {
-  const forwarded = forwardedValue(
+  const forwarded = forwardedProto(
     input.headers.get(FORWARDED_PROTO),
     input.config.trustedProxyHops,
   );

package/src/health-disclosure.ts

@@ -12,9 +12,6 @@ import type { HttpConfig } from './config';
 import { HttpError } from './errors';
 import { forwardedClientAddress } from './forwarded';
 
-/** Core's, named here for the config that defaults to it — never a second copy of the list. */
-export { DEFAULT_HEALTH_DETAIL_PEERS } from '@ultimat3/core';
-
 /** Every class an entry may name. A `Record` so a class core adds is a build error here. */
 const ADDRESS_CLASSES = Object.freeze<Record<AddressClass, true>>({
   loopback: true,

package/src/hooks.ts

@@ -40,12 +40,13 @@ export interface ServerHooks {
   /**
    * The app's OWN error page for a status, served byte for byte, or `undefined` to render the
    * framework's. A seam and not a config value because the answer lives on a disk this package
-   * cannot see: `@ultimat3/cli` reads `apps/web/site/errors/<status>.html`, per request, so a file
-   * dropped into a running server takes effect without a restart — the rule `/favicon.ico`
-   * already follows for the same class of file.
+   * cannot see: `@ultimat3/cli` reads `apps/web/site/errors/<status>.html` — per request under
+   * `x dev`, so a file dropped into a running server takes effect without a restart (the rule
+   * `/favicon.ico` already follows), and once per status in a container.
    *
-   * Consulted only on the production HTML path: a dev process answers a browser with the overlay,
-   * and an agent gets the problem document in both.
+   * Asked on the HTML path only — an agent gets the problem document in both environments. In
+   * production for every status; in dev for a 4xx alone (the page a visitor will see), with the
+   * overlay when it answers `undefined`. A dev 5xx is always the overlay and never asks.
    */
   readonly errorPage?: (
     status: number,

package/src/index.ts

@@ -1,19 +1,16 @@
 // The public surface of @ultimat3/http. Explicit, never `export *`: what is not
 // listed here is an implementation detail and may change without a major bump.
 
+// Imported bare, and the one module `sideEffects` lists: the codes' titles and the `retry-after`
+// class of a 429 and a 503 are read by `UltimateError`, which never imports this module — so a
+// server realm that reaches the barrel registers them whatever it constructs. `SIDE_EFFECTS_ANCHORS`
+// carries the argument and `bun run side-effects` enforces it.
+import './error-titles';
+
 export type { PgExecutor, RenderMode } from '@ultimat3/core';
-// The wire format is `@ultimat3/core`'s and is RE-EXPORTED, never re-declared: it is one module at
-// the tier both halves can reach, because `@ultimat3/jobs` signs a delivery, this package verifies
-// one, and neither may import the other. Re-exported here so a receiver route needs one import.
-export {
-  escapeHtml,
-  isCanonicalWebhookField,
-  readCookie,
-  WEBHOOK_ID_HEADER,
-  WEBHOOK_SIGNATURE_HEADER,
-  WEBHOOK_SIGNATURE_VERSION,
-  WEBHOOK_TOPIC_HEADER,
-} from '@ultimat3/core';
+// No core VALUE is re-exported here (`X_HELPER_COPY`, `bun run flight-copies`): the webhook wire
+// format (`WEBHOOK_*`, `isCanonicalWebhookField`), `escapeHtml` and `readCookie` are imported from
+// `@ultimat3/core`, their one home, by every caller.
 export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
 export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
@@ -30,8 +27,8 @@ export type { ActorView, RequestContext, RequestContextInit } from './context';
 export {
   actorView,
   asCtx,
-  createRequestContext,
   elapsedMs,
+  requestContext,
   useRequestBodyBytes,
   useRequestContext,
   useRequestCookie,
@@ -44,7 +41,7 @@ export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } fro
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
-export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
+export { resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-facts';
 export {
   factsOf,
@@ -125,7 +122,7 @@ export { OVERLAY_STYLE } from './overlay-style';
 export type { PeerIdentity } from './peer-identity';
 export { peerIdentity } from './peer-identity';
 export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
-export { createPipeline, PIPELINE_STAGES } from './pipeline';
+export { httpPipeline, PIPELINE_STAGES } from './pipeline';
 export type { ProblemMeta, ProblemMetaDeclaration, ProblemMetaValue } from './problem-meta';
 export { MAX_PROBLEM_META_BYTES, registerProblemMeta } from './problem-meta';
 export type {
@@ -142,11 +139,11 @@ export type {
 } from './rate-limit';
 export {
   assertRateLimitScope,
-  createRateLimiter,
   DEFAULT_MAX_RATE_LIMIT_KEYS,
   DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitDecision,
+  rateLimiter,
   rateLimitSpends,
   resolveRateLimitConfig,
   toBucket,
@@ -162,6 +159,15 @@ export {
   rateLimitStoreUnavailable,
   tenantBucketUnknown,
 } from './rate-limit-errors';
+export { publishRateLimit, rateLimitHeaders } from './rate-limit-headers';
+export type { AdoptRateLimitStoreOptions } from './rate-limit-installed';
+export {
+  adoptRateLimitStore,
+  assertInstalledRateLimitScope,
+  installedRateLimitStore,
+  installRateLimitStore,
+  resetRateLimitStore,
+} from './rate-limit-installed';
 export type { RateLimitPeek } from './rate-limit-peek';
 export { rateLimitPeek, refilledTokens } from './rate-limit-peek';
 export type { PostgresRateLimitStore, PostgresRateLimitStoreOptions } from './rate-limit-postgres';
@@ -172,18 +178,20 @@ export {
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
 export { UltimateRequest } from './request';
+export type { RequestFacts, RequestFactsInput } from './request-facts';
+export { requestFacts } from './request-facts';
 export type { CacheHint, RedirectIntent, RedirectStatus } from './response';
 export {
   applyCacheHeaders,
   cacheControl,
   html,
-  json,
+  jsonResponse,
   NO_STORE,
   noContent,
   problem,
   redirect,
   stream,
-  text,
+  textResponse,
   withHeaders,
 } from './response';
 export type {
@@ -198,9 +206,9 @@ export type {
   RouteTable,
 } from './router';
 export {
-  createRouter,
   describeRoutes,
   HTTP_METHODS,
+  httpRouter,
   matchRoute,
 } from './router';
 export type { SecurityConfig } from './security-headers';
@@ -212,12 +220,14 @@ export type {
   UpgradeTarget,
   WebSocketMount,
 } from './server';
-export { createServer } from './server';
+export { httpServer } from './server';
+export type { DeleteCookieOptions } from './set-cookie';
+export { deleteCookie, setCookie } from './set-cookie';
 // The stage vocabulary comes from its declaration site, beside the fourteen implementations it
 // names; `PIPELINE_STAGES` — the ORDER — stays `pipeline.ts`'s.
 export type { Stage, StageDoc, StageName, StagePhase, StageRun } from './stages';
 export type { InferOutput, Schema, ValidationOutcome } from './validate';
-export { formatIssue, validate, validateSync } from './validate';
+export { formatIssue, validateBody, validateSync } from './validate';
 export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify';
 export {
   DEFAULT_WEBHOOK_BODY_LIMIT,

package/src/navigation.ts

@@ -39,7 +39,8 @@ const WEB_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:']);
  * 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.
+ * `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}`;
@@ -47,7 +48,18 @@ export function locationFor(target: string, base: URL): string {
   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/pipeline.ts

@@ -5,7 +5,7 @@
 // `finalize.ts` owns the promise that the tail always answers rather than rejecting.
 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';
@@ -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,
@@ -243,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/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",
   });
 
 /**