@ultimat3/http 24.0.0 → 25.1.0

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-postgres.ts

@@ -135,7 +135,7 @@ export interface PostgresRateLimitStore extends RateLimitStore {
    *
    * `nowMs` is required and comes from the SAME clock the takes use — `ctx.now().getTime()` in a
    * task. There is no default, because the only defensible default would be this process' own
-   * `Date.now()`, and a store that reads a clock nobody handed it is the thing `createRateLimiter`
+   * `Date.now()`, and a store that reads a clock nobody handed it is the thing `rateLimiter`
    * took a `Clock` to stop.
    */
   purgeExpired(nowMs: number): Promise<number>;
@@ -150,14 +150,14 @@ export interface PostgresRateLimitStore extends RateLimitStore {
  *
  * // apps/web/server.ts — what PROVIDES it
  * const client = db();
- * createServer({
+ * httpServer({
  *   rateLimitStore: postgresRateLimitStore({
  *     executor: { query: (text, values) => client.query({ text, values }) },
  *   }),
  * });
  * ```
  *
- * `assertRateLimitScope` compares the two once, inside `createPipeline`, and a `'shared'`
+ * `assertRateLimitScope` compares the two once, inside `httpPipeline`, and a `'shared'`
  * declaration over any other store is `X_RATE_LIMIT_NOT_SHARED` before the socket opens.
  */
 export function postgresRateLimitStore(

package/src/rate-limit-stage.ts

@@ -68,14 +68,23 @@ export const spendRequestBuckets = async (
     limiter,
     rateLimitSpends(
       { actorId: actor?.id ?? null, orgId: actor?.orgId ?? null, ip: ctx.ip, routeName },
-      {
-        route: ctx.route?.meta.rateLimit ?? config.defaultBucket,
-        tenant: config.tenantBucket,
-      },
+      { route: routeBucketOf(ctx, config), tenant: config.tenantBucket },
     ),
   );
 };
 
+/**
+ * The ONE place that decides which bucket a route's caller spends here. A route whose handler
+ * spends its own declared limit (`rateLimitedBy: 'handler'` — every action and query route, whose
+ * primitive counts that limit on every surface) spends none: `default` beside it would cap an
+ * action that declared 1,000 at 120, which a declared limit never was.
+ */
+const routeBucketOf = (ctx: RequestContext, config: RateLimitConfig): string | null => {
+  const meta = ctx.route?.meta;
+  if (meta?.rateLimitedBy === 'handler') return null;
+  return meta?.rateLimit ?? config.defaultBucket;
+};
+
 /** The one key failed credentials are counted under: the address alone, never the route. */
 const unauthenticatedKey = (ip: string | null): string =>
   `${UNAUTHENTICATED_SCOPE}|ip:${ip ?? 'unknown'}`;

package/src/rate-limit.ts

@@ -1,6 +1,6 @@
 // Token-bucket rate limiting. The store is an interface so the same limiter runs in-memory in
 // dev/tests and against a shared tier in a multi-replica deployment — installed through
-// `createServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
+// `httpServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
 // declaration; the bucket maths lives here so every driver agrees on the numbers.
 import { type Clock, systemClock } from '@ultimat3/core';
 import { httpCountInvalid } from './errors';
@@ -11,6 +11,7 @@ import {
   rateLimitScopeUnset,
   tenantBucketUnknown,
 } from './rate-limit-errors';
+import { rateLimitHeaders } from './rate-limit-headers';
 import { type RateLimitPeek, rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
 /**
@@ -325,6 +326,13 @@ export interface RateLimitKeyParts {
   readonly orgId: string | null;
   readonly ip: string | null;
   readonly routeName: string;
+  /**
+   * The subject when there is no actor, no org AND no address. Defaults to `ip:unknown` — every
+   * such request shares it, which is what the pipeline has always done. A caller that can name a
+   * narrower population (a job run nobody attributed) passes its own, so it does not share one
+   * bucket with every anonymous request whose address could not be read.
+   */
+  readonly unattributed?: string | undefined;
 }
 
 /**
@@ -360,17 +368,20 @@ export interface RateLimitSpend {
  */
 export const rateLimitSpends = (
   parts: RateLimitKeyParts,
-  buckets: { readonly route: string; readonly tenant: string | null },
+  // `route: null` — the route's own limit is spent by its handler (`RouteMeta.rateLimitedBy`), so
+  // the caller key is not spent here at all; only the tenant allowance is.
+  buckets: { readonly route: string | null; readonly tenant: string | null },
 ): readonly RateLimitSpend[] => {
   const subject =
     parts.actorId !== null
       ? `actor:${parts.actorId}`
       : parts.orgId !== null
         ? `org:${parts.orgId}`
-        : `ip:${parts.ip ?? 'unknown'}`;
-  const spends: RateLimitSpend[] = [
-    { key: `${parts.routeName}|${subject}`, bucket: buckets.route },
-  ];
+        : parts.ip !== null
+          ? `ip:${parts.ip}`
+          : (parts.unattributed ?? 'ip:unknown');
+  const spends: RateLimitSpend[] =
+    buckets.route === null ? [] : [{ key: `${parts.routeName}|${subject}`, bucket: buckets.route }];
   if (buckets.tenant !== null && parts.orgId !== null) {
     spends.push({ key: `${TENANT_SCOPE}|org:${parts.orgId}`, bucket: buckets.tenant });
   }
@@ -383,8 +394,8 @@ export interface RateLimiter {
   /**
    * The table this limiter resolves a bucket NAME against. Declared, never inferred — the same
    * rule as `RateLimitStore.scope` and `@ultimat3/auth`'s `AuthLimiter.policy`, and for the same
-   * reason: `createRateLimiter` closes over its config, so nothing outside can see which buckets
-   * it actually holds. `createPipeline` compares this against the buckets the ROUTES declare, and
+   * reason: `rateLimiter` closes over its config, so nothing outside can see which buckets
+   * it actually holds. `httpPipeline` compares this against the buckets the ROUTES declare, and
    * an unknown name is refused instead of falling through `bucketFor` to `default`.
    *
    * Optional only so an existing external implementation still type-checks; an absent table
@@ -399,7 +410,7 @@ export interface RateLimiter {
   assert(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
 }
 
-export const createRateLimiter = (options: {
+export const rateLimiter = (options: {
   config: RateLimitConfig;
   store?: RateLimitStore;
   /**
@@ -407,7 +418,7 @@ export const createRateLimiter = (options: {
    * BOTH production call sites (`server.ts`, `pipeline.ts`) build their limiter without an
    * override — so the limiter that actually throttles requests could not be frozen by any test,
    * while `@ultimat3/auth`'s credential limiter has taken an injected `Clock` since it shipped.
-   * Defaulted rather than required, the same shape as `createRequestContext`'s `init.clock`;
+   * Defaulted rather than required, the same shape as `requestContext`'s `init.clock`;
    * `PipelineDeps.limiter` stays the one seam for handing the pipeline a limiter of your own,
    * because a second `clock` beside it would be a second way to set one number.
    */
@@ -438,11 +449,7 @@ export const createRateLimiter = (options: {
     buckets: options.config.buckets,
     check,
     peek: (key, bucketName) => store.peek(key, bucketFor(bucketName), now()),
-    headers: (decision) => ({
-      'ratelimit-limit': String(decision.limit),
-      'ratelimit-remaining': String(decision.remaining),
-      'ratelimit-reset': String(Math.ceil((decision.resetAtMs - now()) / 1000)),
-    }),
+    headers: (decision) => rateLimitHeaders(decision, now()),
     async assert(key, bucketName, cost = 1) {
       const decision = await check(key, bucketName, cost);
       if (!decision.allowed) throw rateLimited(key, decision.retryAfterSeconds);

package/src/request-facts.ts

@@ -0,0 +1,44 @@
+// How one request arrived, as the frozen facts a token resolver is handed — never the raw
+// `Headers`. A resolver given the headers would read `x-forwarded-for` itself and trust a hop the
+// host never declared; the address here is the one the pipeline already resolved (`ctx.ip`).
+// One shape for every bearer surface: this mount, and `@ultimat3/mcp`'s `POST /mcp`.
+
+/**
+ * The request, as far as a credential decision may read it. Four facts and no more: a token bound
+ * to a network reads `address`, a resolver refusing browsers reads `origin`. Never the body (it is
+ * unread when the token is decided) and never another header — `Authorization` is the token itself.
+ */
+export interface RequestFacts {
+  /**
+   * The caller's address AS THE HOST RESOLVED IT — `ctx.ip`, a declared proxy's `x-forwarded-for`
+   * honoured per `trustedProxyHops`, else the socket. `null` when the host resolved none: a surface
+   * that cannot tell a trusted hop from a forged one never derives one from a header.
+   */
+  readonly address: string | null;
+  /** `User-Agent`, verbatim — caller-controlled, so a hint for a rule and never an identity. */
+  readonly userAgent: string | null;
+  /**
+   * The `Origin` request header: which web origin a BROWSER says is calling. `null` when absent —
+   * every non-browser client — and the literal string `'null'` for an opaque origin, which is a
+   * different fact (a sandboxed frame or a `file:` page) and must not read as "no browser".
+   */
+  readonly origin: string | null;
+  /** The URL path the request was sent to. No query string. */
+  readonly path: string;
+}
+
+export interface RequestFactsInput {
+  readonly headers: Headers;
+  readonly url: URL | string;
+  /** What the host resolved — `ctx.ip`, or a transport's `seen.address`. Never a header read. */
+  readonly address: string | null | undefined;
+}
+
+export function requestFacts(input: RequestFactsInput): RequestFacts {
+  return Object.freeze({
+    address: input.address ?? null,
+    userAgent: input.headers.get('user-agent'),
+    origin: input.headers.get('origin'),
+    path: (typeof input.url === 'string' ? new URL(input.url) : input.url).pathname,
+  });
+}

package/src/request.ts

@@ -7,7 +7,7 @@ import { readCookie, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bodyInvalid, buildSkew } from './errors';
 import type { Schema } from './validate';
-import { validate, validateSync } from './validate';
+import { validateBody, validateSync } from './validate';
 
 export type QueryValues = Readonly<Record<string, string | readonly string[]>>;
 
@@ -152,7 +152,7 @@ export class UltimateRequest {
   }
 
   async body<Out>(schema: Schema<Out>): Promise<Out> {
-    const outcome = await validate(schema, await this.bodyRaw());
+    const outcome = await validateBody(schema, await this.bodyRaw());
     if (!outcome.ok) throw bodyInvalid(this.pathname, outcome.issues);
     return outcome.value;
   }

package/src/response.ts

@@ -14,13 +14,13 @@ const withDefaults = (init: HeaderSource, defaults: Record<string, string>): Hea
   return headers;
 };
 
-export const json = <T>(body: T, init?: ResponseInit): Response =>
+export const jsonResponse = <T>(body: T, init?: ResponseInit): Response =>
   new Response(JSON.stringify(body), {
     ...init,
     headers: withDefaults(init, { 'content-type': 'application/json; charset=utf-8' }),
   });
 
-export const text = (body: string, init?: ResponseInit): Response =>
+export const textResponse = (body: string, init?: ResponseInit): Response =>
   new Response(body, {
     ...init,
     headers: withDefaults(init, { 'content-type': 'text/plain; charset=utf-8' }),

package/src/route-cache.ts

@@ -31,7 +31,7 @@ const DELTA_SECONDS_FIELDS = [
  * CLI's authorized-object hint all carry `maxAgeSeconds: 0`, so a floor of 1 would refuse the
  * framework at its own boot.
  *
- * Called once per route by `createRouter`, which is the one way a `Route` becomes matchable — so
+ * Called once per route by `httpRouter`, which is the one way a `Route` becomes matchable — so
  * every hint an app can serve has been through here, including the ones `@ultimat3/cli` mints for
  * favicons, dev assets and storage objects.
  */

package/src/router.ts

@@ -76,6 +76,21 @@ export interface RouteMeta {
    * refuses a configured bucket of the same name that says something else.
    */
   readonly rateLimitBucket?: Bucket;
+  /**
+   * `'handler'`: the handler spends this route's own declared limit — an action's `invoke`, a
+   * query's read — because the primitive counts it on every surface (HTTP, MCP, the agent tool, a
+   * job). The `rate-limit` stage then spends no caller bucket for it, only the tenant allowance:
+   * spending `default` too would cap a primitive that declared more than `default` at `default`.
+   * Set, it wins: `rateLimit`/`rateLimitBucket` name a bucket the STAGE spends, and are not read.
+   */
+  readonly rateLimitedBy?: 'handler';
+  /**
+   * The primitive this route projects, written by `@ultimat3/action`'s `toRoute` and
+   * `@ultimat3/query`'s `toQueryRoute`; absent on a plain route. Read by the bucket check
+   * (`rate-limit-buckets.ts`): since 25.0.0 a `rateLimit.buckets.<name>` named after a primitive
+   * limits nothing and is refused, and only an explicit marker can say which routes those are.
+   */
+  readonly primitive?: 'action' | 'query';
   readonly tags?: readonly string[];
   readonly description?: string;
   /**
@@ -159,7 +174,7 @@ const segmentsOf = (path: string): readonly string[] =>
     .split('/')
     .filter((segment) => segment.length > 0);
 
-export const createRouter = (routes: readonly Route[]): RouteTable => {
+export const httpRouter = (routes: readonly Route[]): RouteTable => {
   const root = node();
   for (const route of routes) {
     // Before the trie is touched: a hint that cannot be emitted is refused where it was WRITTEN,

package/src/server.ts

@@ -15,6 +15,7 @@ import {
   markReady,
   onShutdown,
   readyzPayload,
+  systemClock,
 } from '@ultimat3/core';
 import type { Server } from 'bun';
 import { defineHttpConfig, type HttpConfig } from './config';
@@ -22,11 +23,12 @@ import { HttpError, serverNotStarted } from './errors';
 import { disclosesHealthDetail } from './health-disclosure';
 import type { ServerHooks } from './hooks';
 import type { Middleware } from './middleware';
-import { createPipeline, type Pipeline } from './pipeline';
-import { createRateLimiter, type RateLimitStore } from './rate-limit';
+import { httpPipeline, type Pipeline } from './pipeline';
+import { type RateLimitStore, rateLimiter } from './rate-limit';
 import { withRouteBuckets } from './rate-limit-buckets';
-import { json } from './response';
-import { createRouter, describeRoutes, type Route, type RouteDescription } from './router';
+import { adoptRateLimitStore } from './rate-limit-installed';
+import { jsonResponse } from './response';
+import { describeRoutes, httpRouter, type Route, type RouteDescription } from './router';
 
 /**
  * Beside its one caller rather than in `errors.ts`, which is at the 500-line ceiling — the
@@ -35,7 +37,7 @@ import { createRouter, describeRoutes, type Route, type RouteDescription } from
  * A websocket mount and something already answering its path. Same code as two routes claiming
  * one, because it is the same fact: one path, two declarations, and the framework picks — Bun's
  * native route table is matched BEFORE `fetch`, so the route wins and the upgrade never reaches
- * the mount. Refused at `createServer`, not discovered as a socket that will not open.
+ * the mount. Refused at `httpServer`, not discovered as a socket that will not open.
  */
 const websocketPathTaken = (path: string, answered: string): HttpError =>
   new HttpError({
@@ -63,7 +65,7 @@ export interface ServerOptions {
    * Where the rate limiter keeps its counters. Omitted means `memoryRateLimitStore()`, which is
    * one process' worth of state — correct for dev and tests, and N × every configured number for
    * N replicas. An app that runs more than one process declares `rateLimit.scope: 'shared'` and
-   * passes a store that says the same, or `createServer` refuses here.
+   * passes a store that says the same, or `httpServer` refuses here.
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
@@ -142,7 +144,7 @@ export interface ServerHandle {
   url(): string;
   describe(): readonly RouteDescription[];
   start(): ServerHandle;
-  /** Runs core's three-phase drain. The deadline is `config.drainTimeoutMs`. */
+  /** Runs core's three-phase drain, on the deadline `drain.deadlineMs` set (`lifecycleForRole`). */
   stop(): Promise<void>;
   /**
    * Runs one request through the entire lifecycle with no socket. This is the
@@ -151,20 +153,41 @@ export interface ServerHandle {
   fetch(request: Request): Promise<Response>;
 }
 
+/** How often the `inflight` hook re-reads Bun's count of unfinished responses. */
+const BODY_POLL_MS = 5;
+
 const roleFromEnv = (): Role => (Bun.env['ROLE'] ?? 'web') as Role;
 
-export const createServer = (options: ServerOptions): ServerHandle => {
+export const httpServer = (options: ServerOptions): ServerHandle => {
+  // The store this server is handed is also the one actions and queries spend their declared
+  // `rateLimit:` from — adopted BEFORE the pipeline, whose boot check reads it, and never over a
+  // store the boot already chose (`keepChosen`). Given back on `stop()`, or by ANY refusal from
+  // here to the handle — the pipeline's checks, `configureLifecycle`, `assertMountPathFree` — so a
+  // boot that never produced a server leaves nothing behind it.
+  const releaseStore =
+    options.rateLimitStore === undefined
+      ? () => undefined
+      : adoptRateLimitStore(options.rateLimitStore, { keepChosen: true });
+  try {
+    return buildServer(options, releaseStore);
+  } catch (error) {
+    releaseStore();
+    throw error;
+  }
+};
+
+const buildServer = (options: ServerOptions, releaseStore: () => void): ServerHandle => {
   const role = options.role ?? roleFromEnv();
-  const table = createRouter(options.routes);
-  // Merged here as well as in `createPipeline`, and for the store's sake: the limiter below is
+  const table = httpRouter(options.routes);
+  // Merged here as well as in `httpPipeline`, and for the store's sake: the limiter below is
   // built from `config.rateLimit`, so a table without the routes' own buckets would resolve a
   // declared name to `default` — the very hole this closes. `withRouteBuckets` is idempotent, so
   // the pipeline's second pass changes nothing. `handle.config` is the merged one for the same
   // reason: `server.config.rateLimit.buckets` has to be what the limiter runs on.
   const config = withRouteBuckets(options.config ?? defineHttpConfig(), table.routes);
   // The store feeds the limiter seam `PipelineDeps` already had, rather than becoming a second
-  // one: the bucket maths stays in `createRateLimiter`, so every driver agrees on the numbers.
-  const pipeline = createPipeline({
+  // one: the bucket maths stays in `rateLimiter`, so every driver agrees on the numbers.
+  const pipeline = httpPipeline({
     table,
     config,
     ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
@@ -172,17 +195,14 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     ...(options.rateLimitStore === undefined
       ? {}
       : {
-          limiter: createRateLimiter({ config: config.rateLimit, store: options.rateLimitStore }),
+          limiter: rateLimiter({ config: config.rateLimit, store: options.rateLimitStore }),
         }),
   });
 
-  // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget — and only
-  // when this app DECLARED it. Unconditional, with `defineHttpConfig` defaulting the number, this
-  // line reverted `configureLifecycle({ deadlineMs: 600_000 })` — the edit `X_SHUTDOWN_TIMEOUT`'s
-  // own `fix:` prints — back to 15s on every boot that serves web, silently. "Nobody said" and
-  // "the app said 15 seconds" are different claims and `null` is what keeps them apart.
-  if (config.drainTimeoutMs !== null) configureLifecycle({ deadlineMs: config.drainTimeoutMs });
-  // Same rule: only a declared grace is applied. Core waits it out between the readiness flip and
+  // No deadline is set here. `drain.deadlineMs` is the one budget, applied per role by
+  // `lifecycleForRole` before any server exists; `http.drainTimeoutMs` re-set it on the web role
+  // only, after that, and was deleted in 25.0.0 for being a second answer (axiom 1).
+  // Only a declared grace is applied. Core waits it out between the readiness flip and
   // the `accept` hook below, so endpoints stop routing here before the socket closes.
   const readinessGraceMs = options.drain?.readinessGraceMs;
   if (readinessGraceMs !== undefined) configureLifecycle({ readinessGraceMs });
@@ -190,6 +210,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
   const mount = options.websocket;
   let server: BunServer | undefined;
   let unregister: (() => void) | undefined;
+  let unregisterBodies: (() => void) | undefined;
   let unregisterClose: (() => void) | undefined;
   let stopListening: (() => void) | undefined;
 
@@ -202,7 +223,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
    * peer `healthDetailPeers` lists: these two paths answer outside the pipeline, unauthenticated.
    */
   const healthResponse = (payload: HealthPayload, request: Request, socket: BunServer): Response =>
-    json(
+    jsonResponse(
       healthBody(
         payload.body,
         role,
@@ -342,14 +363,40 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       // 'accept' runs first on SIGTERM, but only after core's readiness grace: readyz flips to
       // 503 the moment the drain starts, the socket stays open for `readinessGraceMs`, so the
       // endpoints controller stops routing here before this closes it — not a 502 in between.
+      //
+      // NOT awaited: Bun's `stop(false)` stops the listener at once but resolves only when every
+      // request AND every websocket on it has closed — so one open browser tab held this hook, and
+      // every `accept` hook after it (worker, scheduler), until the drain deadline, leaving the
+      // `close` hooks 0 ms. Handlers are core's to wait for (`beginWork()`), bodies the `inflight`
+      // hook's below, sockets the `close` hook's `stop(true)`. The same shape as
+      // `realtime/src/sync-listen.ts`. A rejection is the close hook's to surface, not this one's.
       unregister = onShutdown(
         `http:${role}`,
-        async () => {
-          await server?.stop(false);
+        () => {
+          server?.stop(false).catch(() => undefined);
         },
         { phase: 'accept' },
       );
-      // 'close' runs after core has waited out the in-flight phase.
+      // The BODIES. `beginWork()` ends when a handler returns its Response, and a streamed body —
+      // a page render, a file, an LLM stream — is still being written after that; awaiting
+      // `stop(false)` above was what used to wait for it, websockets and all. Bun's
+      // `pendingRequests` counts exactly the responses not yet finished (a client that went away
+      // included as finished), never an upgraded socket, so this waits for bodies alone and costs
+      // the request path nothing. Polled, and bounded by the drain's own deadline: a body that
+      // never ends (SSE) is cut by the `close` hook's `stop(true)`, not waited on forever.
+      unregisterBodies = onShutdown(
+        `http:${role}:bodies`,
+        async (reason) => {
+          while (
+            (server?.pendingRequests ?? 0) > 0 &&
+            systemClock.monotonic() < reason.deadlineAt
+          ) {
+            await Bun.sleep(BODY_POLL_MS);
+          }
+        },
+        { phase: 'inflight' },
+      );
+      // 'close' runs after core has waited out the in-flight phase, bodies included.
       unregisterClose = onShutdown(
         `http:${role}:close`,
         async () => {
@@ -371,9 +418,12 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       // core's `shutdownHookCount()` exists to make visible. The shape `worker.ts`'s teardown
       // holds: the unregisters are the closure's, not the drain's.
       const releaseHooks = (): void => {
+        releaseStore();
         unregister?.();
+        unregisterBodies?.();
         unregisterClose?.();
         unregister = undefined;
+        unregisterBodies = undefined;
         unregisterClose = undefined;
       };
       if (server === undefined) {

package/src/set-cookie.ts

@@ -0,0 +1,60 @@
+// How a route handler, a page loader or an action sets a cookie on the response it cannot build:
+// one serialized line, from core's one serializer, appended to the context's response-header bag —
+// the bag the `response` stage APPENDS `set-cookie` from, so two cookies are two lines, never one.
+
+import { CookieInvalidError, type SetCookieOptions, serializeSetCookie } from '@ultimat3/core';
+import { assertInRequest } from './context';
+
+/**
+ * What identifies the cookie being cleared, plus the attributes its prefix or partition requires.
+ * A browser deletes only the cookie whose name, `Path` and `Domain` all match — `Partitioned` too
+ * for a CHIPS cookie — so these must be what `setCookie` was given. No `maxAge`, `expires` or
+ * `priority`: the clearing line decides those itself.
+ */
+export type DeleteCookieOptions = Pick<
+  SetCookieOptions,
+  'path' | 'domain' | 'secure' | 'httpOnly' | 'sameSite' | 'partitioned'
+>;
+
+const DELETE_FIX = 'deleteCookie(name, { path, domain })   # the one way to clear a cookie';
+
+/**
+ * Clearing has ONE spelling, `deleteCookie`, so a reader searching for where a cookie dies finds
+ * every site. `maxAge: 0` and an `expires` already past both clear in a browser, so both are
+ * refused here rather than left as a second, unsearchable way to do the same thing.
+ */
+function refuseClearing(name: string, options: SetCookieOptions, now: Date): void {
+  if (options.maxAge === 0) {
+    throw new CookieInvalidError('maxAge', name, 'is 0, which deletes the cookie', DELETE_FIX);
+  }
+  const { expires } = options;
+  if (expires instanceof Date && expires.getTime() <= now.getTime()) {
+    throw new CookieInvalidError(
+      'expires',
+      name,
+      'is not after now, so it deletes the cookie',
+      DELETE_FIX,
+    );
+  }
+}
+
+/**
+ * Set cookie `name` on the response to the request in scope. Defaults are core's:
+ * `Path=/; HttpOnly; Secure; SameSite=Lax`. Every call APPENDS a line — the same name on two
+ * paths is two cookies — and an invalid cookie is `X_COOKIE_INVALID` before anything is appended.
+ * Outside a request it throws `X_NO_REQUEST`: a cookie nobody will receive is a silent failure.
+ */
+export const setCookie = (name: string, value: string, options: SetCookieOptions = {}): void => {
+  const ctx = assertInRequest('setCookie()');
+  refuseClearing(name, options, ctx.now());
+  ctx.headers.append('set-cookie', serializeSetCookie(name, value, options));
+};
+
+/**
+ * Clear cookie `name`: an empty value and `Max-Age=0`, with the `Path` and `Domain` it was set
+ * with (defaults the same as `setCookie`'s, so a cookie set with none is cleared with none).
+ */
+export const deleteCookie = (name: string, options: DeleteCookieOptions = {}): void => {
+  const ctx = assertInRequest('deleteCookie()');
+  ctx.headers.append('set-cookie', serializeSetCookie(name, '', { ...options, maxAge: 0 }));
+};