@ultimat3/http 1.2.0 → 3.0.0

package/src/pipeline.ts

@@ -1,78 +1,47 @@
-// THE request lifecycle. An explicit, ordered array — not a middleware stack — because
-// this order IS the framework's guarantee: context before user code, identity before
-// rate limiting, validation before authz, authz before the handler. Nothing can skip a
-// stage, and the array is exported so `/_x` renders it and pipeline.test.ts asserts it.
-import {
-  anonymousActor,
-  isAnonymous,
-  logger,
-  recordRequest,
-  runWithContext,
-  withSpan,
-} from '@ultimat3/core';
-import { defineHttpConfig, type HttpConfig, stripBasePath } from './config';
-import { actorView, asCtx, createRequestContext, elapsedMs, type RequestContext } from './context';
-import { corsHeaders, preflight } from './cors';
-import { factsOf } from './error-map';
-import {
-  bodyInvalid,
-  forbidden,
-  methodNotAllowed,
-  pipelineNoResponse,
-  rateLimited,
-  routeNotFound,
-  unauthenticated,
-} from './errors';
+// THE request lifecycle: which stages exist, in what ORDER, why — and the one loop that drives a
+// request through them. The order IS the framework's guarantee, an explicit array and not a
+// 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 { defineHttpConfig, type HttpConfig } from './config';
+import { asCtx, createRequestContext, elapsedMs, type RequestContext } from './context';
+import { readCorrelation } from './correlation';
+import { type Deadline, startDeadline } from './deadline';
+import { pipelineNoResponse } from './errors';
+import { recoverWith, runFinalize } from './finalize';
+import { clientAddress, clientUsedHttps } from './forwarded';
 import type { ServerHooks } from './hooks';
-import { negotiateLocale, readCookie, resolveTimeZone } from './locale';
-import { compose, type Middleware } from './middleware';
-import { overlayResponse, wantsOverlay } from './overlay';
-import { createRateLimiter, type RateLimiter, rateLimitKey } from './rate-limit';
+import type { Middleware } from './middleware';
+import { peerIdentity } from './peer-identity';
+import { assertRateLimitScope, createRateLimiter, type RateLimiter } from './rate-limit';
+import { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
 import { UltimateRequest } from './request';
-import { applyCacheHeaders, type CacheHint, problem } from './response';
-import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
-import { securityHeaders } from './security-headers';
-import { validate } from './validate';
-
-export type StageName =
-  | 'request-id'
-  | 'trace'
-  | 'context'
-  | 'locale'
-  | 'auth'
-  | 'rate-limit'
-  | 'body'
-  | 'authz'
-  | 'handler'
-  | 'cache-headers'
-  | 'error-map'
-  | 'response';
-
-/**
- * `request`  may short-circuit by returning a Response.
- * `terminal` runs the route handler.
- * `recover`  runs only when something above threw.
- * `finalize` always runs, on success and on failure.
- */
-export type StagePhase = 'request' | 'terminal' | 'recover' | 'finalize';
-
-export interface StageDoc {
-  readonly name: StageName;
-  readonly phase: StagePhase;
-  /** Why the stage sits at this index. Rendered verbatim by the dev dashboard. */
-  readonly why: string;
-}
+import { problem } from './response';
+import type { RouteTable } from './router';
+import {
+  type Stage,
+  type StageDoc,
+  type StagePhase,
+  stageRunners,
+  UNMATCHED_ROUTE,
+} from './stages';
 
 export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'request-id',
     phase: 'request',
-    why: 'first: every log line, span, error body and problem document quotes it, so it must exist before anything can fail',
+    why: 'first: every log line, span, error body and problem document quotes it, so it must be on the response before anything can fail',
+  },
+  {
+    name: 'admit',
+    phase: 'request',
+    why: 'second, and before every other stage does any work: a draining process answers 503 here rather than accepting work it will abandon, and past maxInflight a request is shed with Retry-After before it can queue behind the pool that is already the bottleneck',
   },
   {
     name: 'trace',
     phase: 'request',
-    why: 'before any I/O: a span started later would silently exclude auth and DB latency from the trace',
+    why: 'publishes the trace id the root span already carries — the span is started before stage 1, from the inbound traceparent, because one started here would exclude every stage above it and could not adopt the caller as its parent',
   },
   {
     name: 'context',
@@ -94,6 +63,11 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
     phase: 'request',
     why: 'before the body is read: a limited request must never make the server allocate its payload',
   },
+  {
+    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',
+  },
   {
     name: 'body',
     phase: 'request',
@@ -122,223 +96,22 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   },
 ];
 
-export type StageRun = (
-  request: UltimateRequest,
-  ctx: RequestContext,
-) => Response | undefined | Promise<Response | undefined>;
-
-export interface Stage extends StageDoc {
-  readonly run: StageRun;
-}
-
 export interface PipelineDeps {
   readonly table: RouteTable;
   readonly config?: HttpConfig;
   readonly hooks?: ServerHooks;
   readonly middleware?: readonly Middleware[];
+  /**
+   * A limiter built elsewhere — `createServer({ 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
+   * a limiter that cannot enforce one (`X_RATE_LIMIT_BUCKET_UNBOUND`) rather than letting the
+   * name fall through to `default`.
+   */
   readonly limiter?: RateLimiter;
 }
 
-const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
-const REQUEST_ID = /^[\w.:-]{8,128}$/;
-
-/**
- * The one label a request with no matched route may carry. Every 404 and every scan of `/wp-admin`
- * would otherwise be its own rate-limit bucket and its own metric series — an attacker choosing
- * the server's cardinality is how a Prometheus dies.
- */
-const UNMATCHED_ROUTE = 'unmatched';
-
-/** Authenticated routes are never shared-cacheable; that default is not overridable. */
-const defaultCache = (route: Route | undefined): CacheHint =>
-  route === undefined || route.meta.auth === 'required'
-    ? { mode: 'no-store' }
-    : { mode: 'public', maxAgeSeconds: 0, sMaxAgeSeconds: 60, staleWhileRevalidateSeconds: 600 };
-
-const runners = (deps: PipelineDeps, config: HttpConfig, limiter: RateLimiter) => {
-  const hooks = deps.hooks ?? {};
-  const wrapped = new Map<Route, RouteHandler>();
-  const wrap = compose(deps.middleware ?? []);
-  for (const route of deps.table.routes) wrapped.set(route, wrap(route.handler));
-
-  const table: Record<StageName, StageRun> = {
-    'request-id': (request, ctx) => {
-      const inbound = config.trustProxy ? request.header('x-request-id') : null;
-      if (inbound !== null && REQUEST_ID.test(inbound)) ctx.requestId = inbound;
-      ctx.headers.set('x-request-id', ctx.requestId);
-      return undefined;
-    },
-
-    trace: (request, ctx) => {
-      const inbound = request.header('traceparent');
-      const parsed = inbound === null ? null : TRACEPARENT.exec(inbound);
-      if (parsed !== null) {
-        ctx.traceId = parsed[1] ?? ctx.traceId;
-        ctx.parentSpanId = parsed[2] ?? null;
-      }
-      ctx.headers.set('x-trace-id', ctx.traceId);
-      return undefined;
-    },
-
-    context: (request, ctx) => {
-      // A preflight carries no credentials, so answering it after `auth` would 401
-      // every legitimate cross-origin call.
-      const answered = preflight(request.raw, config.cors);
-      if (answered !== undefined) return answered;
-
-      ctx.buildId = request.header(config.buildIdHeader);
-      request.assertBuild();
-
-      const pathname = stripBasePath(ctx.url.pathname, config.basePath);
-      const match = matchRoute(deps.table, ctx.method, pathname);
-      if (!match.ok) {
-        if (match.reason === 'not-found') throw routeNotFound(ctx.method, pathname);
-        ctx.headers.set('allow', match.allow.join(', '));
-        throw methodNotAllowed(ctx.method, pathname, match.allow);
-      }
-      ctx.route = match.route;
-      ctx.params = match.params;
-      return undefined;
-    },
-
-    locale: (request, ctx) => {
-      const cookies = request.header('cookie');
-      ctx.locale = negotiateLocale(
-        request.header('accept-language'),
-        config.locale,
-        readCookie(cookies, config.locale.cookie),
-      );
-      ctx.tz = resolveTimeZone(
-        request.header(config.tz.header) ?? readCookie(cookies, config.tz.cookie),
-        config.tz,
-      );
-      ctx.headers.set('content-language', ctx.locale);
-      return undefined;
-    },
-
-    auth: async (request, ctx) => {
-      if (hooks.authenticate !== undefined) {
-        // The hook says "anonymous" with null; the context says it with core's anonymous actor,
-        // because `asCtx` publishes this object as a `Ctx` and `Ctx.actor` is never null.
-        ctx.actor = (await hooks.authenticate(request, ctx)) ?? anonymousActor();
-      }
-      if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
-        throw unauthenticated(ctx.url.pathname);
-      }
-      return undefined;
-    },
-
-    'rate-limit': async (_request, ctx) => {
-      if (!config.rateLimit.enabled) return undefined;
-      const actor = actorView(ctx.actor);
-      const key = rateLimitKey({
-        actorId: actor?.id ?? null,
-        orgId: actor?.orgId ?? null,
-        ip: ctx.ip,
-        routeName: ctx.route?.meta.name ?? UNMATCHED_ROUTE,
-      });
-      const decision = await limiter.check(
-        key,
-        ctx.route?.meta.rateLimit ?? config.rateLimit.defaultBucket,
-      );
-      // Recorded before the throw so the 429 can carry Retry-After and the
-      // RateLimit-* headers rather than making the client guess.
-      ctx.rateLimit = decision;
-      for (const [name, value] of Object.entries(limiter.headers(decision))) {
-        ctx.headers.set(name, value);
-      }
-      if (!decision.allowed) throw rateLimited(key, decision.retryAfterSeconds);
-      return undefined;
-    },
-
-    body: async (request, ctx) => {
-      const schema = ctx.route?.meta.input;
-      if (schema === undefined) return undefined;
-      const outcome = await validate(schema, await request.bodyRaw());
-      if (!outcome.ok) throw bodyInvalid(ctx.url.pathname, outcome.issues);
-      ctx.input = outcome.value;
-      return undefined;
-    },
-
-    authz: async (request, ctx) => {
-      const route = ctx.route;
-      if (route === undefined || route.meta.policy === undefined) return undefined;
-      // The handler owns this route's single evaluation (`RouteMeta.enforcedBy`). Deciding
-      // here as well would be a second authz system holding strictly less than the first —
-      // no row — and it is the one that answers first, so it is the one that would win.
-      if (route.meta.enforcedBy === 'handler') return undefined;
-      if (hooks.authorize === undefined) {
-        // A declared policy with no evaluator is a wiring bug, and failing open
-        // here is exactly how a framework ends up with two authz systems.
-        throw forbidden(ctx.url.pathname, `no authorizer wired for policy ${route.meta.policy}`);
-      }
-      const decision = await hooks.authorize(route, request, ctx);
-      ctx.authz = decision;
-      if (!decision.allowed) throw forbidden(ctx.url.pathname, decision.reason);
-      return undefined;
-    },
-
-    handler: async (request, ctx) => {
-      const route = ctx.route;
-      if (route === undefined) throw routeNotFound(ctx.method, ctx.url.pathname);
-      const handler = wrapped.get(route) ?? route.handler;
-      return await handler(request, ctx);
-    },
-
-    'cache-headers': (_request, ctx) => {
-      const response = ctx.response;
-      if (response === undefined) return undefined;
-      if (!response.headers.has('cache-control')) {
-        applyCacheHeaders(response, ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route));
-      }
-      return undefined;
-    },
-
-    'error-map': (request, ctx) => {
-      const error = ctx.error;
-      const facts = factsOf(error);
-      hooks.onError?.(error, ctx);
-      logger.error(`${facts.code}: ${facts.cause} [${ctx.requestId}]`);
-      if (config.dev && wantsOverlay(request.raw)) {
-        return overlayResponse(error, {
-          requestId: ctx.requestId,
-          method: ctx.method,
-          path: ctx.url.pathname,
-          buildId: config.buildId,
-        });
-      }
-      const retryAfter =
-        facts.code === 'X_RATE_LIMITED' && ctx.rateLimit !== undefined
-          ? { 'retry-after': String(ctx.rateLimit.retryAfterSeconds) }
-          : {};
-      return problem(error, {
-        instance: ctx.url.pathname,
-        requestId: ctx.requestId,
-        headers: retryAfter,
-      });
-    },
-
-    response: (request, ctx) => {
-      const response = ctx.response;
-      if (response === undefined) return undefined;
-      for (const [name, value] of ctx.headers) response.headers.set(name, value);
-      for (const [name, value] of Object.entries(
-        corsHeaders(config.cors, request.header('origin')),
-      )) {
-        response.headers.set(name, value);
-      }
-      for (const [name, value] of Object.entries(
-        securityHeaders(config.security, { https: ctx.https }),
-      )) {
-        response.headers.set(name, value);
-      }
-      response.headers.set('server-timing', `total;dur=${elapsedMs(ctx)}`);
-      return undefined;
-    },
-  };
-  return table;
-};
-
 export interface HandleInit {
   readonly role: RequestContext['role'];
   readonly ip?: string | null;
@@ -347,14 +120,32 @@ export interface HandleInit {
 export interface Pipeline {
   readonly stages: readonly Stage[];
   readonly config: HttpConfig;
-  /** Runs the full lifecycle for one request and always resolves to a Response. */
+  /**
+   * Runs the full lifecycle for one request and always resolves to a Response — a stage that
+   * throws after the handler, or while rendering another stage's throw, degrades to the coded
+   * 500 (`X_PIPELINE_FINALIZE_FAILED`) rather than rejecting. A caller has a socket open.
+   */
   handle(request: Request, init: HandleInit): Promise<Response>;
 }
 
 export const createPipeline = (deps: PipelineDeps): Pipeline => {
-  const config = deps.config ?? defineHttpConfig();
+  // 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.
+  const config = withRouteBuckets(deps.config ?? defineHttpConfig(), deps.table.routes);
   const limiter = deps.limiter ?? createRateLimiter({ config: config.rateLimit });
-  const run = runners(deps, config, limiter);
+  // Here rather than in `createServer`: 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);
+  assertRouteBuckets(limiter, deps.table.routes);
+  const run = stageRunners({
+    table: deps.table,
+    config,
+    limiter,
+    hooks: deps.hooks ?? {},
+    middleware: deps.middleware ?? [],
+  });
   const stages: readonly Stage[] = PIPELINE_STAGES.map((doc) => ({ ...doc, run: run[doc.name] }));
 
   const byPhase = (phase: StagePhase): readonly Stage[] =>
@@ -362,30 +153,45 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
   const requestStages = byPhase('request');
   const finalizeStages = byPhase('finalize');
   const terminal = stages.find((stage) => stage.phase === 'terminal');
-  const recover = stages.find((stage) => stage.phase === 'recover');
+  const recovered = recoverWith(stages.find((stage) => stage.phase === 'recover'));
 
-  const execute = async (request: UltimateRequest, ctx: RequestContext): Promise<Response> => {
-    try {
-      for (const stage of requestStages) {
-        const short = await stage.run(request, ctx);
-        if (short !== undefined) {
-          ctx.response = short;
-          break;
-        }
+  const runStages = async (request: UltimateRequest, ctx: RequestContext): Promise<void> => {
+    for (const stage of requestStages) {
+      const short = await stage.run(request, ctx);
+      if (short !== undefined) {
+        ctx.response = short;
+        return;
       }
-      if (ctx.response === undefined && terminal !== undefined) {
-        ctx.response = (await terminal.run(request, ctx)) ?? new Response(null, { status: 204 });
+    }
+    if (ctx.response === undefined && terminal !== undefined) {
+      ctx.response = (await terminal.run(request, ctx)) ?? new Response(null, { status: 204 });
+    }
+  };
+
+  const execute = async (
+    request: UltimateRequest,
+    ctx: RequestContext,
+    deadline: Deadline,
+  ): Promise<Response> => {
+    try {
+      const work = runStages(request, ctx);
+      if (deadline.expired === undefined) await work;
+      else {
+        // The abort is the cooperative half and app code that reads `ctx.signal` unwinds on its
+        // 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]);
       }
     } catch (error) {
       ctx.error = error;
-      ctx.response =
-        (recover === undefined ? undefined : await recover.run(request, ctx)) ??
-        problem(error, { instance: ctx.url.pathname, requestId: ctx.requestId });
-    }
-    for (const stage of finalizeStages) {
-      const replaced = await stage.run(request, ctx);
-      if (replaced !== undefined) ctx.response = replaced;
+      ctx.response = await recovered(request, ctx);
     }
+    // `finalize.ts`, not a loop here: these two stages run after the request is already answered
+    // or already failed, so a throw of their own has nothing left to catch it — and `handle`
+    // promises a Response.
+    await runFinalize(finalizeStages, request, ctx, recovered);
     return ctx.response ?? problem(pipelineNoResponse('response'));
   };
 
@@ -394,12 +200,43 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
     config,
     async handle(raw, init) {
       const url = new URL(raw.url);
+      // Before the context and before the span, in this order on purpose. `startSpan` resolves
+      // its parent from `currentSpanContext()`, which reads `ctx.traceId` — so a `traceparent`
+      // parsed by a stage arrived one frame too late, every time: the caller's trace was
+      // discarded and the root span kept an id the logs beside it never mentioned.
+      const correlation = readCorrelation(raw.headers, config);
+      const deadline = startDeadline({
+        headers: raw.headers,
+        config,
+        method: raw.method.toUpperCase(),
+        pathname: url.pathname,
+      });
+      const forwarded = {
+        headers: raw.headers,
+        config,
+        socketAddress: init.ip ?? null,
+        urlProtocol: url.protocol,
+      };
       const ctx = createRequestContext({
         url,
         method: raw.method,
         role: init.role,
         config,
-        ip: init.ip ?? null,
+        requestId: correlation.requestId,
+        traceId: correlation.traceId,
+        parentSpanId: correlation.parentSpanId,
+        // Resolved here, not in `server.ts`: `pipeline.fetch()` is the supported way to test a
+        // route and it must take the identical path a socket does.
+        ip: clientAddress(forwarded),
+        https: clientUsedHttps(forwarded),
+        // The mesh's assertion about the caller's certificate, read at the SAME hop index as the
+        // address — an identity from an untrusted hop authenticates, which is worse than none.
+        peer: peerIdentity(forwarded),
+        signal: deadline.signal,
+        // The context is what app code reaches through core's ALS; without the inbound headers
+        // on it, a cookie the server itself set could never be read back on the next request,
+        // and `ctx.session` had no way to exist.
+        requestHeaders: raw.headers,
       });
       const request = new UltimateRequest(raw, ctx);
       // The ALS scope is entered here, before stage 1, so every stage — and everything
@@ -409,13 +246,13 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
           `${ctx.method} ${url.pathname}`,
           async (span) => {
             // This package's ONE metrics call site. `finally`, not the happy line: `execute`
-            // absorbs app throws into a problem response, but a finalize stage can still throw on
-            // its own (immutable headers on a `Response.redirect`), and a counter that skips the
-            // requests the server handled worst is the one an autoscaler must not have. 500 is the
-            // status such a request gets from the caller either way.
+            // answers every stage's throw with a problem response, but a counter that skipped the
+            // requests the server handled worst is the one an autoscaler must not have — so a
+            // rejection nothing here predicted still counts, at the 500 such a request gets from
+            // the caller either way.
             let status = 500;
             try {
-              const response = await execute(request, ctx);
+              const response = await execute(request, ctx, deadline);
               status = response.status;
               // The root span of every request carried no attributes at all, so an exporter got a
               // name and a duration and nothing to correlate: which request, which outcome. These
@@ -439,9 +276,19 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
                 status,
                 durationMs: elapsedMs(ctx),
               });
+              // A live timer keeps the event loop from going idle, so a process that answered
+              // every request would still refuse to exit for the length of one timeout.
+              deadline.clear();
             }
           },
-          { kind: 'server' },
+          {
+            kind: 'server',
+            // Explicit, and the whole point of parsing `traceparent` up here: without it
+            // `startSpan` falls back to `currentSpanContext()` — the context's own traceId, with
+            // an empty spanId — which produces a root span with no parent and a trace the caller
+            // never heard of.
+            ...(correlation.parent === undefined ? {} : { parent: correlation.parent }),
+          },
         ),
       );
     },

package/src/rate-limit-buckets.ts

@@ -0,0 +1,86 @@
+// Registration: a route that declares its own bucket puts it in the limiter's table. The bucket
+// maths and the store stay in `rate-limit.ts`; this file is the one point where routes and config
+// meet — `defineHttpConfig` runs before any route exists, so the table it builds cannot hold them,
+// and a bucket name with nothing behind it falls through `bucketFor` to `default`.
+
+import type { HttpConfig } from './config';
+import { rateLimitBucketConflict, rateLimitBucketUnbound } from './errors';
+import type { Bucket, RateLimiter } from './rate-limit';
+import type { Route } from './router';
+
+const same = (a: Bucket, b: Bucket): boolean =>
+  a.capacity === b.capacity && a.refillPerSecond === b.refillPerSecond;
+
+/**
+ * The config with every route-declared bucket registered under the name that route selects.
+ *
+ * Precedence is refusal, never a winner: an equal restatement passes, and any disagreement — with
+ * a configured bucket, or with another route claiming the same name — is
+ * `X_RATE_LIMIT_BUCKET_CONFLICT` before the socket opens. Picking one would leave the other a
+ * 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
+ * it: a second pass compares each bucket against the copy the first pass registered.
+ */
+export const withRouteBuckets = (config: HttpConfig, routes: readonly Route[]): HttpConfig => {
+  const declared = new Map<string, { readonly bucket: Bucket; readonly route: string }>();
+  for (const route of routes) {
+    const bucket = route.meta.rateLimitBucket;
+    const name = route.meta.rateLimit;
+    // Numbers with no name to file them under enforce nothing; `toRoute` always sets both.
+    if (bucket === undefined || name === undefined) continue;
+    const prior = declared.get(name);
+    const configured = config.rateLimit.buckets[name];
+    if (prior !== undefined && !same(prior.bucket, bucket)) {
+      throw rateLimitBucketConflict({
+        bucket: name,
+        otherRoute: prior.route,
+        route: route.meta.name,
+        other: prior.bucket,
+        declared: bucket,
+      });
+    }
+    if (prior === undefined && configured !== undefined && !same(configured, bucket)) {
+      throw rateLimitBucketConflict({
+        bucket: name,
+        otherRoute: null,
+        route: route.meta.name,
+        other: configured,
+        declared: bucket,
+      });
+    }
+    declared.set(name, { bucket, route: route.meta.name });
+  }
+  if (declared.size === 0) return config;
+  const buckets: Record<string, Bucket> = { ...config.rateLimit.buckets };
+  for (const [name, entry] of declared) buckets[name] = entry.bucket;
+  return { ...config, rateLimit: { ...config.rateLimit, buckets } };
+};
+
+/**
+ * The other half of registration: the limiter actually installed must hold what the routes
+ * declared. `withRouteBuckets` puts the numbers in the CONFIG, which is enough only when the
+ * pipeline builds the limiter from that config. A limiter handed in through `PipelineDeps.limiter`
+ * closed over a table of its own, and a name it does not hold falls through `bucketFor` to
+ * `default` — silently, and looser than the declaration. So the two tables are compared once, at
+ * construction, exactly as `assertRateLimitScope` compares the two scopes.
+ *
+ * A limiter that declares no table at all is refused for the same reason a per-process store under
+ * a `'shared'` declaration is: what cannot be shown to hold is not assumed to hold.
+ */
+export const assertRouteBuckets = (limiter: RateLimiter, routes: readonly Route[]): void => {
+  for (const route of routes) {
+    const bucket = route.meta.rateLimitBucket;
+    const name = route.meta.rateLimit;
+    if (bucket === undefined || name === undefined) continue;
+    const found = limiter.buckets?.[name];
+    if (found !== undefined && same(found, bucket)) continue;
+    throw rateLimitBucketUnbound({
+      bucket: name,
+      route: route.meta.name,
+      declared: bucket,
+      found: found ?? null,
+    });
+  }
+};