@ultimat3/http 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -23,8 +23,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   from `HttpConfigInput`.
 - **No drain deadline here**: `drain.deadlineMs` is the one budget (core, per role); the deleted
   key and `ServerOptions.drain`: `docs/history/http.md#no-drain-deadline`.
-- **`cors.origins: ['*']` with `credentials: true`, or `'null'` in the list, is `X_CORS_CONFIG_INVALID`.** A refused origin
-  still gets `vary: origin`.
+- **`X_CORS_CONFIG_INVALID`: `cors.origins: ['*']` with `credentials: true`, `'null'`, or any entry
+  but `'*'` whose `URL.origin` is not itself** (fix names the canonical form). A refused origin still gets `vary: origin`.
 - **`DEFAULT_CORS` is what `clientTransport` sends and reads**, off core's constants; `cors.test.ts` observes the transport's real traffic, so a new header fails it. `date` alone stays hidden: this server writes delta-seconds. An app's list replaces the default whole.
 - **A `security.csp.extend` entry must emit only the directive it names**
   (`X_CSP_DIRECTIVE_INVALID`); `buildCsp` builds through a `Map`.
@@ -58,7 +58,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`hooks.authenticate` has one declaration site: `configureAuthenticator()`.** A route may
   REPLACE it with `meta.authenticate` (never run beside it): `bearerMount` sets it so a session
   cookie authenticates nothing on `/v1/*`.
-- **`bearerMount` re-serves existing `Route`s, never re-projects them** (`bearer-mount.ts`): the cut is decided in the `auth` stage, outside the scopes is `X_ROUTE_NOT_FOUND`, the prefix is opaque. The token allowance is spent once, in the authenticator, for every resolved token in scope or not (a 422 or 403 before the handler pays). A declared `rateLimit` REPLACES `default` on the mount's routes (`rateLimitedBy: 'handler'`); a route's own `meta.rateLimit` and the tenant allowance stay. A successor `Link` is rewritten in a `finally` to the mounted path when in the cut under a scope the token holds, else removed (`bearer-mount-wire.test.ts`). Full rule: `docs/history/http.md`.
+- **`bearerMount` re-serves existing `Route`s, never re-projects them** (`bearer-mount.ts`): the cut is decided in the `auth` stage (outside it: `X_ROUTE_NOT_FOUND`); the token allowance is spent once, in the authenticator; a declared `rateLimit` REPLACES `default`, a route's own and the tenant allowance stay; a successor `Link` is rewritten or removed (`bearer-mount-wire.test.ts`). Full rule: `docs/history/http.md`.
 - **`hooks.devNotices` is called only inside the `config.dev && wantsOverlay` branch.**
 - **A dev 4xx asks `hooks.errorPage` first; a 5xx is always the overlay** (#492): the app's file
   when it has one, else the overlay. Production asks for every status (`stages-error-page.test.ts`).
@@ -70,9 +70,11 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `finalize.ts` owns the tail. Imports go `pipeline.ts` → `stages.ts`; a stage reads
   `StageRunnersInput`, never `PipelineDeps`. A new stage is an entry in both `PIPELINE_STAGES` and the
   `Record<StageName, StageRun>` table, with a `why` and a test.
-- **The request span is named by the route PATTERN** (`GET /r/:token`, `routeSpanName`), started
-  as the bare method and renamed after the match; `http.route` is the pattern or `unmatched`. A
-  concrete URL carries tokens and is attacker-chosen — never a span name, attribute or label.
+- **The request span is named by the route PATTERN** (`GET /r/:token`, `routeSpanName`), renamed
+  on match; `http.route` is the pattern or `unmatched`. A concrete URL (tokens,
+  attacker-chosen) is never a span name, attribute or label — no `url.path`. Keys: core's
+  `SEMCONV`; the id is `ultimate.request_id`. **`http.request` is emitted once, in the same
+  `finally`**, after `deadline.clear()` (`pipeline-telemetry.test.ts`).
 - **The CSP `connect-src` is `'self' blob:`** — no bare `ws:`/`wss:`. A cross-origin sync node is
   the boot's `csp.extend` of that origin exactly. `security.hsts` merges key by key.
 - **The two inbound ids are read BEFORE the context and the span** (`correlation.ts`, core's
@@ -94,6 +96,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `hooks.authorize`; `'handler'` stands the `authz` stage down.
 - **A 403's `fix:` names the POLICY** (`route.meta.policy`), degrading to `x routes --json` for a
   composite.
+- **`maxRequestBodyBytes` (128 MiB, ≥ `bodyLimitBytes`) is the transport ceiling**; Bun's is off.
+  A declared length past it (`admit`) or a streamed one (`server.ts`) is `X_BODY_TOO_LARGE` (413).
 - **The body cap is enforced while reading** (`UltimateRequest.#read`'s counting reader, cancelling
   past `bodyLimitBytes`); multipart goes through the same capped bytes. **Bytes with no
   `content-type` are `X_BODY_INVALID`** from `bodyRaw()`, never "no body"; `bodyBytes()` reads them.
@@ -131,7 +135,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `markReady()`, `drain()`, the payloads) — never a private state or in-flight counter.
 - **`stop()` hands its two hooks back ABOVE its early return** (`packages/http/e2e/server.e2e.test.ts`
   reads `shutdownHookCount()`).
-- **`compress` is the last stage and has no option** (`compress.ts`, its counted read `compress-read.ts`). A signed-in answer is coded only when `immutable` (`compressResponse(..., { anonymous })`, declared, never defaulted). The ceiling is 256 KiB, measured. A response that fails the rule is the SAME object with its body unread. `cache-control` with `private`, `no-store`, `no-cache` or `no-transform` is identity (BREACH); `vary: accept-encoding` goes on every answer past the type and cache conditions, coded or not. `content-length` is the bound: `html`, `textResponse`, `jsonResponse` declare it, `stream` never. A read that overruns, fails or passes `ctx.signal`, and a `gzipSync` throw, log `http.compress_failed` and answer identity, whole: never a request failure.
+- **`compress` is the last stage and has no option** (`compress.ts`, `compress-read.ts`). A signed-in answer is coded only when `immutable` (`{ anonymous }`, declared, never defaulted). 1–256 KiB declared is `gzipSync`ed; past 256 KiB, or undeclared once 1 KiB is read, `CompressionStream` with no length. An undeclared NDJSON feed never is. A refused response is the SAME object. `private`, `no-store`, `no-cache` or `no-transform` is identity (BREACH); `vary: accept-encoding` goes on every answer past the type and cache conditions. A counted read that overruns, fails or passes `ctx.signal`, or a `gzipSync` throw, logs `http.compress_failed`: identity, whole.
 
 ## Rules — errors and the problem document
 
@@ -146,16 +150,16 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `registerProblemMeta({ CODE: { publicCause: true } })`). `toProblem(error, { dev })` defaults `dev`
   to false. An unclassified 5xx carries nothing off the throwable. **A hidden cause hides the `fix`
   too**: `callerFix`, else `x errors explain <CODE> --json` — never `facts.fix` outside dev.
-- **The document carries the ISSUE LIST** as a top-level `issues` member: `issuesOf` is total,
-  all-or-nothing, absent (never `[]`) when none, dropped past `MAX_PROBLEM_ISSUES` (100), dropped under
-  the opacity condition; `received` forced to `''`, entries rebuilt member by member.
+- **The document carries the ISSUE LIST** (`issues`): `issuesOf` is total, all-or-nothing,
+  absent when none, past 100 or opaque; `received` is `''`. `issuesTruncated: true` rides only
+  with a carried list and `meta.issuesTruncated === true`. Both are reserved meta keys.
 - **`meta` reaches the document only by declaration** (`registerProblemMeta({ CODE: [keys] })`, app
   codes only; not `issues`, not `__proto__`): `wireMeta` copies declared keys through
   `Object.defineProperty`, bounded by `MAX_PROBLEM_META_BYTES`, dropped when opaque.
 - **A rejected value is a log FIELD, never the message** — the `error-map` line's message is the code alone.
 - **A rejected BODY names only what the framework chose**: `bodyInvalid`'s `issues` are a fixed
   vocabulary; what the caller sent rides in `meta`; the parser's message goes through `renderThrowable`.
-- **A browser failing `auth: 'required'` is redirected; an agent gets the problem document** (`auth-redirect.ts`, in `error-map` before the overlay). Full rule: `docs/history/http.md`.
+- **A browser failing `auth: 'required'` is redirected; an agent gets the problem document** (`auth-redirect.ts`, in `error-map` before the overlay), in the routed locale. Full rule: `docs/history/http.md`.
 - **A pathname in a `fix:` goes through `renderFixShellArg`** (`routeNotFound`). **A `code` is gated by
   core's `FRAMEWORK_CODE`** before `x errors explain <code>`, else `x errors list --json`. **A supplied
   `fix:` is taken only from a branded error** (`isUltimateError`).
@@ -167,24 +171,20 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 
 ## Rules — rate limiting
 
-- **One request spends a LIST of keys**: the caller's and, when `rateLimit.tenantBucket` is declared,
-  `tenant|org:<id>` (not route-scoped); stop at the first refusal; an undeclared name is
-  `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN`. Headers report the bucket closest to refusing.
-- **The memory store is bounded** (`forgetAtMs` sweep, `DEFAULT_MAX_RATE_LIMIT_KEYS`, evicting the
-  entries closest to FULL first — never LRU).
-- **The limiter takes a `Clock`** (`rateLimiter({ clock })`); `deps.limiter` is the one seam.
-- **The scope is DECLARED, with no default**: an enabled limiter without `scope` is
-  `X_RATE_LIMIT_SCOPE_UNSET`; `assertRateLimitScope` (in `httpPipeline`) refuses `'shared'` over a
-  per-process store (`X_RATE_LIMIT_NOT_SHARED`). Install through `httpServer({ rateLimitStore })`.
-- **A failed `auth: 'required'` is metered in the `auth` stage**. Full rule: `docs/history/http.md`.
-- **`postgresRateLimitStore({ executor })` is the shared store**, over `@ultimat3/core`'s structural
-  `PgExecutor` (re-exported here). The
-  refill expression is repeated inside `on conflict do update` on purpose; `spent` is a stored column;
-  `purgeExpired(nowMs)` takes the caller's clock.
-- **A bucket a route names must be registered**: `withRouteBuckets` merges `meta.rateLimitBucket`
-  into the table in `httpServer` and `httpPipeline`; any disagreement is
-  `X_RATE_LIMIT_BUCKET_CONFLICT`. **The installed limiter must hold it too** — `RateLimiter.buckets`
-  is declared and `assertRouteBuckets` refuses, never rebinds.
+Full rules and their reasons: [`docs/history/http-rate-limit.md`](../../docs/history/http-rate-limit.md).
+
+- **An address key is core's `addressNetwork(ip)`** (IPv6 `/64`). **One request spends a LIST of
+  keys** (caller's, then `tenant|org:<id>` when declared); stop at the first refusal.
+- **The memory store is bounded** (`DEFAULT_MAX_RATE_LIMIT_KEYS`, evicts closest-to-FULL first).
+- **The scope is DECLARED, with no default** (`X_RATE_LIMIT_SCOPE_UNSET`); `'shared'` over a
+  per-process store is `X_RATE_LIMIT_NOT_SHARED`, checked in `httpPipeline`.
+- **ONE store slot** (`rate-limit-installed.ts`): routes AND primitives count in
+  `installedRateLimitStore()`; a server reads it PER REQUEST (`liveRateLimitStore`). Installer and
+  reset are on `@ultimat3/http/adapter` only (`adapter.test.ts`); an app names `rateLimitStore` in
+  `apps/<app>/runtime.ts`. `httpServer` takes no store (v31).
+- **A bucket a route names must be registered** (`withRouteBuckets`, `X_RATE_LIMIT_BUCKET_CONFLICT`)
+  and held by the limiter (`assertRouteBuckets`, `X_RATE_LIMIT_BUCKET_UNBOUND`).
+- Shared stores: `postgresRateLimitStore({ executor })`, `redisRateLimitStore({ client })`.
 
 ## Rules — webhooks and tests
 
@@ -197,7 +197,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`verifyWebhookSignature` and `verifyBodyHmac` share ONE secret screen** (`assertWebhookSecrets`)
   and one pair of refusals (`webhookSecretMissing`, `webhookSignatureInvalid`), each naming its caller.
 - Tests must not touch the network — the preload seals `fetch`. Socket tests live in `e2e/` (`bun test
-  packages/http/e2e`), sealed; `start()` calls core's `markListening()`. Never unseal.
+  ./packages/http/e2e/`), sealed; `start()` calls core's `markListening()`. Never unseal.
 
 ## Files
 
@@ -206,12 +206,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `pipeline.ts` | the ORDER the stages run in — the framework's guarantee — and the one loop that drives a request through them |
 | `stages.ts` | what each stage DOES, one entry per `StageName`, plus the stage vocabulary the other two import |
 | `finalize.ts` | the tail of that lifecycle, guarded: a throw after the handler degrades, never rejects |
-| `router.ts` | trie, static > param > wildcard, `path-invalid` for a segment that will not decode. A request segment is decoded ONCE; a static child is looked up raw, then decoded. A wildcard takes an EMPTY rest after the node's own routes (`/docs` → `/docs/*path`, `path: ''`). Segments, decoding and `canonicalPath` are `route-path.ts`'s: `ctx.routePath` is the match's one spelling, `requestAddress(ctx)` what render keys `isr` on |
-| `navigation.ts` | the client router's server half: the gate `context` runs after the match (a prefetch to a route whose `meta.navigation` did not opt in → `204`; a soft GET to anything but a page of the router's `<app>:<surface>` → `204` + `x-ultimate-location`, before auth or app code) and the `response` stage's rewrite of a 3xx to a router request into the same hand-over, cookies kept |
+| `router.ts` | trie, static > param > wildcard; a segment decoded ONCE (static looked up raw, then decoded), `path-invalid` if it will not. A wildcard takes an EMPTY rest (`/docs` → `/docs/*path`). `route-path.ts` owns segments and `canonicalPath`: `ctx.routePath` is the match's one spelling, `requestAddress(ctx)` what render keys `isr` on |
+| `navigation.ts` | the client router's server half: `context`'s gate after the match (an un-opted prefetch, or a soft GET off the router's `<app>:<surface>` → `204` [+ `x-ultimate-location`], before auth) and `response`'s rewrite of a 3xx to that hand-over, cookies kept |
 | `error-map.ts` | the code → status table, closed: COMPOSES the slices and holds no row of its own |
-| `error-map-http.ts`, `error-map-tier-<0-4>.ts` | the rows, one slice per owning tier (this package's own apart). `bun run new-error-code` appends to the slice its `--package` maps to; a code in two slices is refused there and by `error-map.test.ts` |
+| `error-map-http.ts`, `error-map-tier-<0-4>.ts` | the rows, one slice per owning tier. `bun run new-error-code` appends to its `--package`'s slice; a code in two is refused by `error-map.test.ts` |
 | `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document (including the issue list and the opacity rule over it), the three terminal lines |
-| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices`, `errorPage`, `explainMiss` (asked ONLY on a `not-found` match, synchronously, with the request line alone; its error replaces `X_ROUTE_NOT_FOUND`) + the app's `configureAuthenticator()` |
+| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices`, `errorPage`, `explainMiss` (asked ONLY on a `not-found` match, synchronously, with the request line alone; its error replaces `X_ROUTE_NOT_FOUND`) + the app's `configureAuthenticator(fn, { credentialTtlMs })` |
 | `type-pins.ts` | compile-time claims about `AuthzDecision`'s shape — source, because `tsc` never reads a `.test.ts` |
 | `overlay.ts` | the dev error page: the same code/cause/fix as the terminal, plus any notices |
 | `overlay-style.ts` | the overlay's one stylesheet, split out so `security-headers.ts` hashes it |
@@ -222,12 +222,16 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `stored-object-headers.ts` | inline only for raster images, audio, video; else `attachment` + `sandbox` (private) |
 | `auth-redirect.ts` | where an unauthenticated browser goes, and where it comes back to |
 | `cache-policy.ts` | the default `CacheHint` for a route that declared none — route AND actor — and the review of a declared one (`reviewedHint`) |
-| `error-log-level.ts` | the level of the `error-map` stage's one line: `error` for 5xx, `warn` for 401/403/429, `info` for the rest |
+| `error-log-level.ts` | the `error-map` line's level: `error` 5xx, `warn` 401/403/429, `info` the rest and a `routineRefusal` (`unauthenticated()`) |
 | `route-cache.ts` | the screen a `Route.cache` hint gets where it is DECLARED, thrown from `httpRouter`; the response path's `finiteDeltaSeconds` is the total half of the same rule |
-| `rate-limit.ts` | the token-bucket maths, the store interface, the memory driver and `toBucket` |
+| `rate-limit.ts` | the token-bucket maths, the store interface, the memory driver |
+| `adapter.ts` | `@ultimat3/http/adapter`: the store port's interface, the shipped stores' types (also on `.`, beside their factories), the driver error (adapter only), and the boot's installer |
+| `rate-limit-config.ts` | the bucket table, its resolver and `toBucket` |
 | `rate-limit-postgres.ts` | the SHARED store: one table, one `insert … on conflict` per take, over a structural `PgExecutor` |
-| `rate-limit-errors.ts` | every refusal a rate limit produces — the 429 and the six declaration faults. Split off `errors.ts` at the ceiling |
-| `error-titles.ts` | the owned codes, their titles and the two `retry-after` classes, registered at import — the one module `sideEffects` lists, imported bare by the barrel and `errors.ts`. Server realm only: a browser reads an http refusal's title off the body and its delay off `Retry-After` (core's decoders), so no http module rides into an island |
+| `rate-limit-redis.ts` | the other shared store: one Lua token bucket per take |
+| `body-ceiling.ts` | the transport ceiling and `X_BODY_TOO_LARGE` |
+| `rate-limit-errors.ts` | every refusal a rate limit produces — the 429 and the declaration faults |
+| `error-titles.ts` | the owned codes, titles and `retry-after` classes, registered at import — the one `sideEffects` module. Server realm only: a browser reads title and delay off the body and `Retry-After` |
 | `correlation.ts` | the inbound request id and trace, read before the context and the span exist |
 | `forwarded.ts` | one hop-indexed reader for every header a trusted proxy writes |
 | `peer-identity.ts` | Envoy XFCC -> `ctx.peer`, on that same trust rule |
@@ -238,7 +242,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `locale.ts` | WHERE the request's locale and zone are read from — header and cookie NAMES only. It negotiates nothing; the cookie is read by core's `readCookie`, imported, never re-exported |
 | `rate-limit-buckets.ts` | the one point routes and config meet: a route's own bucket, registered or refused |
 | `rate-limit-stage.ts` | what the pipeline spends and when: the `rate-limit` stage's list of keys, and the address-keyed allowance the `auth` stage spends for a failed credential |
-| `health-disclosure.ts` | WHO the web role's `/healthz` and `/readyz` tell the detail to: the `healthDetailPeers` config key, its screen, and the trusted-proxy half. The body rule and the peer match are core's (`health-disclosure.ts` there), shared with the sync node |
+| `health-disclosure.ts` | WHO `/healthz` and `/readyz` tell the detail to: `healthDetailPeers`, its screen, the trusted-proxy half. Body rule and peer match are core's |
 | `bearer-mount.ts` | a second door onto existing routes: `Authorization: Bearer` on a prefix, the scope cut, the per-token allowance |
 | `request-facts.ts` | `RequestFacts`, any token resolver's frozen 2nd arg; address = `ctx.ip` |
 | `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
@@ -249,7 +253,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 ## Commands
 
 ```
-bun test packages/http
+bun test ./packages/http/
 bun run --filter @ultimat3/http typecheck
 ```
 

package/README.md

@@ -31,6 +31,7 @@ configureHttp({ bodyLimitBytes: 8 * 1024 * 1024, requestTimeoutMs: 300_000 });
 | the request deadline and `ctx.signal` | `deadline.ts` |
 | the caller's real address behind a proxy | `forwarded.ts` |
 | the inbound request id and trace, read before the span | `correlation.ts` |
+| the `server` span (OpenTelemetry's stable `http.*`/`url.*`/`server.*` names, `ultimate.request_id`) and `http.request` on core's instrumentation bus, once per request | `pipeline.ts` |
 | dev error overlay | `overlay.ts` |
 
 ## What an app declares: `configureHttp()`
@@ -51,7 +52,10 @@ configureHttp({
 ```
 
 One registration, read once by whatever process starts the web role — the same seam
-`configureAuthenticator()` is. **Breaking, `As of 2026-08-24`**: before it, the only `HttpConfig`
+`configureAuthenticator(authenticate, { credentialTtlMs? })` is. `credentialTtlMs` is what a
+resolved identity is worth on a connection that carries no further request (the `sync` node's
+websocket re-asks after it; omitted, five minutes) — the credential's lifetime is the
+authenticator's fact, so it is declared beside the function, never as a second authenticator. **Breaking, `As of 2026-08-24`**: before it, the only `HttpConfig`
 any shipped process built was a fixed literal inside `@ultimat3/cli`, so none of the four values
 above could be set from an app at all — `cors.origins` was `[]` in every deployment, which refuses
 every cross-origin browser call, permanently. `AppConfig` has never carried an `http` key and does
@@ -101,7 +105,11 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | a repeated form field | a LIST, exactly as a repeated query parameter is. One collector for query, urlencoded and multipart; `Object.fromEntries` kept the last value, so a checkbox group reached the schema as one string |
 | a cross-origin request from an origin the allow-list refuses | no `access-control-allow-origin`, but always `vary: origin`, so a shared cache never answers an allowed origin out of the refusal's slot |
 | `cors.origins: ['*']` with `credentials: true` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, because a browser accepts that pair from nobody |
+| a `cors.origins` entry no browser sends — `'https://app.com/'`, `'https://App.com'`, `'https://app.com:443'`, `'app.com'` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, its `fix` naming the canonical form (`URL.origin`). `As of 2026-11` (v31): the match is byte for byte, so each spelling matched nothing and refused every cross-origin write |
+| a body past `maxRequestBodyBytes` (default 128 MiB, never below `bodyLimitBytes`) — declared or streamed | `X_BODY_TOO_LARGE` (413). `As of 2026-11`: Bun's own `maxRequestBodySize` is off — it answered an empty, uncoded 413 before any framework code, and its 128 MiB default refused every larger signed upload. `configureHttp({ maxRequestBodyBytes })` raises the ceiling |
 | `?next=` carrying anything but a same-origin path | the fallback — including a value whose TAB/CR/LF a browser strips back into `//evil.test`, and any other control character. `nextAfterSignIn` takes the value its caller's parser already decoded and never decodes it again, `As of 2026-10`: `?q=a%26b` lands as `?q=a%26b`, not `?q=a&b`. A code point above U+007F is percent-encoded so a `Location` header can carry it. The answer is the normalised path (`/a/../b` → `/b`), and one whose pathname starts `//` (`/.//evil.test`) is refused; `x-ultimate-location` never carries a same-origin pathname starting `//` either |
+| a browser with no session on a localized URL (`/es/account`) | `303` to the sign-in page in that locale (`/es/login?next=%2Fes%2Faccount`), `As of 2026-11` — it went to the default-locale `signInPath` and switched the visitor's language at the door |
+| `Range: bytes=5-3` (last byte before the first) | ignored, `200` with the whole body (RFC 9110: an invalid range-spec is ignored), `As of 2026-11`; `416` stays for a valid range past the size |
 | HSTS | emitted only when the connection is affirmatively https (`ctx.https`); never by the zero-argument default |
 | `rateLimit.scope: 'shared'` on a per-process store | `X_RATE_LIMIT_NOT_SHARED` at `httpServer`, because N replicas each holding their own counters enforce N × every configured number |
 | a route's own bucket and a configured bucket of that name disagreeing | `X_RATE_LIMIT_BUCKET_CONFLICT` at `httpServer`, because the loser would be a number someone read and nothing applied |
@@ -129,7 +137,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | `buildId: null` | skew detection off, whatever `BUILD_ID` says; `hostname` never defaults from `HOSTNAME` (the container id under Docker) |
 | an `x-forwarded-client-cert` value in quotes | unescaped ONCE, after the pairs are split — `Subject="O=Acme; Inc,CN=svc-one"` is that whole subject, not `O=Acme` |
 | a request past `maxInflight` (1000) | `X_OVERLOADED` (503) + `retry-after`, shed in the `admit` stage before any work |
-| a public text answer, 1 KiB to 256 KiB, with a declared length | gzip on the wire, from the last stage (`compress`), `vary: accept-encoding` and a weak `etag`. A private answer, a signed-in one that is not `immutable`, `no-transform`, a range or an undeclared length stays identity and unread. HEAD carries GET's coded headers. `html`, `textResponse`, `jsonResponse` declare their bytes; `stream` never does. Exported: `isCompressibleType(contentType)`, `COMPRESS_MIN_BYTES`, `COMPRESS_MAX_BYTES` |
+| a public text answer of at least 1 KiB, or with no declared length | gzip on the wire, from the last stage (`compress`), `vary: accept-encoding` and a weak `etag`. Up to 256 KiB with a declared length it is coded whole (`gzipSync`, with its `content-length`); past that, or a stream with no declared length once its first 1 KiB has arrived — CSV, a large JSON export — it is coded as the client pulls (`CompressionStream`, no `content-length`), `As of 2026-11`; an undeclared body that ends under 1 KiB leaves identity with its length, and an undeclared NDJSON feed is never coded (the coder emits nothing until its source closes). A HEAD answered with no body has nothing to measure and stays identity. A private answer, a signed-in one that is not `immutable`, `no-store`, `no-transform` or a range stays identity and unread. HEAD carries GET's coded headers. Exported: `isCompressibleType(contentType)`, `COMPRESS_MIN_BYTES`, `COMPRESS_MAX_BYTES` |
 
 `handle()` resolves to a Response, always — a stage that throws after the handler, or while
 rendering another stage's throw, degrades to `X_PIPELINE_FINALIZE_FAILED` (500, the stage named in
@@ -148,22 +156,19 @@ reads (refill applied, **no write and no row** — a key never taken is full; `r
 `refilledTokens` do the arithmetic) and `reset(key)`. `peek` is required, `As of 2026-10`: the
 `auth` stage asks it on every request to an `auth: 'required'` route.
 
+**One store, one place to choose it, `As of 31.0.0`.** Routes and primitives (an action's or a
+query's declared `rateLimit:`) count in ONE installed store. The boot installs
+`postgresRateLimitStore` over the pool it opened; an app that wants another names it in
+`apps/<app>/runtime.ts`, and nowhere else — `httpServer({ rateLimitStore })` and the barrel's
+`installRateLimitStore` / `adoptRateLimitStore` are gone (Upgrading, 30 → 31). The installer lives
+on `@ultimat3/http/adapter`, which the boot imports; an app never calls it.
+
 ```ts
-import {
-  httpServer,
-  defineHttpConfig,
-  type RateLimitStore,
-  type Route,
-} from '@ultimat3/http';
-
-declare const routes: readonly Route[];
-declare const myStore: RateLimitStore;   // postgresRateLimitStore({ executor }), say
-
-httpServer({
-  routes,
-  config: defineHttpConfig({ rateLimit: { scope: 'shared' } }), // this limit is the fleet's
-  rateLimitStore: myStore,                                      // whose own scope is 'shared'
-});
+// apps/web/runtime.ts
+import type { RateLimitStore } from '@ultimat3/http';
+
+declare const myStore: RateLimitStore;   // its own scope is 'shared'
+export const runtime = { rateLimitStore: myStore };
 ```
 
 | Declared | Store | Result |
@@ -179,8 +184,8 @@ said one replica" the same value while `docker/helm/values.yaml` runs three —
 the one nobody declared. A limiter with `enabled: false` owes no declaration: nothing is enforced,
 so nothing can be wrong.
 
-`rateLimitStore` feeds the `PipelineDeps.limiter` seam rather than sitting beside it: the bucket
-maths stays in `rateLimiter`, so every driver agrees on the numbers.
+The installed store feeds the `PipelineDeps.limiter` seam rather than sitting beside it: the
+bucket maths stays in `rateLimiter`, so every driver agrees on the numbers.
 
 **One request spends a LIST of keys, `As of 2026-08-24`** — the caller's (`actor`, else `org`,
 else `ip`) and, when the app declared `rateLimit.tenantBucket`, that caller's tenant. The key
@@ -201,28 +206,37 @@ and one `insert … on conflict` per take (a peek is one `select`), so N replica
 line over the client the boot already opened; **never `Bun.sql`**, whose `.query` is `undefined`.
 
 ```ts
+// apps/web/runtime.ts — only when the boot's own default is not the one you want
 import { baseClient, dbExecutor } from '@ultimat3/db';
-import {
-  httpServer,
-  defineHttpConfig,
-  type PgExecutor,
-  postgresRateLimitStore,
-  type Route,
-} from '@ultimat3/http';
-
-declare const routes: readonly Route[];
+import { type PgExecutor, postgresRateLimitStore } from '@ultimat3/http';
 
 // The pool this process already opened, never a request's open transaction — the boot builds
 // the same executor when it installs the store for you.
 const executor: PgExecutor = dbExecutor(baseClient);
 
-httpServer({
-  routes,
-  config: defineHttpConfig({ rateLimit: { scope: 'shared' } }),
-  rateLimitStore: postgresRateLimitStore({ executor }),
-});
+export const runtime = { rateLimitStore: postgresRateLimitStore({ executor }) };
 ```
 
+**A Redis store ships too, `As of 2026-11`** — `redisRateLimitStore({ client })`, one Lua token
+bucket per take (`EVALSHA`, falling back to `EVAL` on `NOSCRIPT`), a peek one `HMGET`. A hot key —
+one NAT, a tenant bucket — no longer serialises every request on one Postgres row lock. Each key
+expires once it would be full again, so it needs no purge. Same `scope: 'shared'`, same deadline
+(`deadlineMs`, 250 ms) and the same degrade-to-this-pod's-memory on an outage, `ERR_REDIS_CONNECTION_CLOSED`
+included. Connect the client before the first request, or the first takes are decided in memory.
+
+```ts
+// apps/web/runtime.ts
+import { redisClient } from '@ultimat3/core/redis';
+import { redisRateLimitStore } from '@ultimat3/http';
+
+export const runtime = { rateLimitStore: redisRateLimitStore({ client: redisClient(), prefix: 'app' }) };
+```
+
+**An IPv6 caller is its `/64`, `As of 2026-11` (v31)** — `@ultimat3/core`'s `addressNetwork(ip)` is the address
+every anonymous key and the failed-credential key count by: IPv4 whole (an IPv4-mapped IPv6 is its
+IPv4), any other IPv6 `<first four hextets>::/64`. One subscriber holds a /64, so the full address
+handed each holder a fresh bucket per request.
+
 The table bounds itself only when something asks it to: `store.purgeExpired(ctx.now().getTime())`
 from a `task` drops every bucket that has refilled to capacity, which is the memory store's forget
 rule. `nowMs` is required and must come from the same clock the takes use — measured against the
@@ -265,8 +279,7 @@ the same rule as `RateLimitStore.scope` — and `assertRouteBuckets` compares it
 at construction. A limiter passed to `PipelineDeps.limiter` that cannot enforce a declared bucket
 is refused rather than rebound: a `RateLimiter` is opaque, so rebinding would mean discarding the
 store it carries, and a caller who built their own limiter may have meant their own numbers. Pass
-the **store** — `httpServer({ routes, rateLimitStore })` — and the pipeline builds the limiter
-from the merged table for you.
+no limiter — `httpServer({ routes })` builds one over the installed store from the merged table.
 
 ## Routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "keywords": [
     "ultimate",
@@ -27,7 +27,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts"
   },
   "files": [
     "src",
@@ -45,9 +46,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/i18n": "30.9.0",
-    "@ultimat3/schema": "30.9.0",
-    "@ultimat3/time": "30.9.0"
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/i18n": "31.0.0",
+    "@ultimat3/schema": "31.0.0",
+    "@ultimat3/time": "31.0.0"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,14 @@
+// `@ultimat3/http/adapter` — the rate-limit store port: the interface a driver implements, the
+// errors it throws, and the boot's installer. The installer lives here and never on the `.` barrel
+// so an app has exactly one way to choose a store: `rateLimitStore` in `apps/<app>/runtime.ts`.
+
+export type { Bucket, RateLimitDecision, RateLimitScope, RateLimitStore } from './rate-limit';
+export { rateLimitStoreUnavailable } from './rate-limit-errors';
+export {
+  clearDefaultRateLimitBuckets,
+  installRateLimitStore,
+  resetRateLimitStore,
+  withScratchRateLimitStore,
+} from './rate-limit-installed';
+export type { RateLimitPeek } from './rate-limit-peek';
+export { RATE_LIMIT_STORE_DEADLINE_MS } from './rate-limit-store-deadline';

package/src/auth-redirect.ts

@@ -2,6 +2,7 @@
 // client want `X_UNAUTHENTICATED` as JSON with a fix line; a person following a link wants the
 // sign-in page. One condition, two audiences, decided here so the error stage stays one branch.
 
+import { localizedPath } from '@ultimat3/i18n';
 import type { RequestContext } from './context';
 import { acceptsHtml } from './html-render';
 import type { RedirectIntent } from './response';
@@ -19,12 +20,17 @@ export const NEXT_PARAM = 'next';
  *
  * 303, not 302: the request that failed authz may have been a form POST, and 303 turns the
  * follow-up into the GET the sign-in page actually is. Same reasoning as `setRedirect`.
+ *
+ * The sign-in page is spelled in the locale the URL routed (`ctx.pathLocale`): `/es/account` goes
+ * to `/es/login`, never the default-locale `/login`, which switched a visitor's language at the door.
  */
 export function signInRedirect(input: {
   readonly code: string;
   readonly signInPath: string | null;
   readonly request: Request;
-  readonly ctx: Pick<RequestContext, 'url' | 'method'>;
+  readonly ctx: Pick<RequestContext, 'url' | 'method'> & {
+    readonly pathLocale?: RequestContext['pathLocale'];
+  };
 }): RedirectIntent | undefined {
   const { code, signInPath, request, ctx } = input;
   if (code !== 'X_UNAUTHENTICATED' || signInPath === null) return undefined;
@@ -33,9 +39,11 @@ export function signInRedirect(input: {
   if (!acceptsHtml(request)) return undefined;
   // A sign-in page that declares `auth: 'required'` by mistake would otherwise redirect to
   // itself forever, and a browser reports that as a bare "too many redirects" with no code.
-  if (ctx.url.pathname === signInPath) return undefined;
+  const signIn =
+    ctx.pathLocale === undefined ? signInPath : localizedPath(signInPath, ctx.pathLocale);
+  if (ctx.url.pathname === signInPath || ctx.url.pathname === signIn) return undefined;
   const next = `${ctx.url.pathname}${ctx.url.search}`;
-  return { location: `${signInPath}?${NEXT_PARAM}=${encodeURIComponent(next)}`, status: 303 };
+  return { location: `${signIn}?${NEXT_PARAM}=${encodeURIComponent(next)}`, status: 303 };
 }
 
 /**

package/src/bearer-mount.ts

@@ -11,15 +11,16 @@
 import type { Actor, Clock } from '@ultimat3/core';
 import {
   ACTION_PATH_PREFIX,
+  liveClock,
   QUERY_PATH_PREFIX,
   successorLink,
   successorPathOf,
-  systemClock,
 } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bearerMountInvalid, routeNotFound } from './errors';
 import type { RateLimitDecision, RateLimitStore } from './rate-limit';
-import { memoryRateLimitStore, toBucket } from './rate-limit';
+import { memoryRateLimitStore } from './rate-limit';
+import { toBucket } from './rate-limit-config';
 import { rateLimited } from './rate-limit-errors';
 import { rateLimitHeaders } from './rate-limit-headers';
 import type { UltimateRequest } from './request';
@@ -156,7 +157,8 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
   const bucket =
     input.rateLimit === undefined ? undefined : toBucket(`bearer mount ${prefix}`, input.rateLimit);
   const store = input.rateLimitStore ?? memoryRateLimitStore();
-  const clock = input.clock ?? systemClock;
+  // Read per request, never captured at mount: an unpinned mount follows the `clock` port.
+  const nowMs = (): number => (input.clock ?? liveClock).now().getTime();
   // The caller each request resolved to, keyed by ITS context — never a module-level slot two
   // concurrent requests could share.
   const callers = new WeakMap<RequestContext, { caller: BearerCaller }>();
@@ -201,9 +203,9 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       `${prefix}|token:${key}`,
       bucket,
       1,
-      clock.now().getTime(),
+      nowMs(),
     );
-    for (const [name, value] of Object.entries(rateLimitHeaders(decision, clock.now().getTime()))) {
+    for (const [name, value] of Object.entries(rateLimitHeaders(decision, nowMs()))) {
       ctx.headers.set(name, value);
     }
     // `rateLimited` carries the seconds in `meta`, which the error-map stage turns into

package/src/body-ceiling.ts

@@ -0,0 +1,54 @@
+// The transport ceiling: the most bytes this process reads in one request, for any route. Bun's
+// own `maxRequestBodySize` answered an empty, uncoded 413 before framework code ran, so the
+// framework holds the limit instead — refused by declared length in `admit`, and counted on a
+// streamed body — and Bun's is lifted out of the way.
+
+import { HttpError } from './errors';
+
+/** Bun's former default, so an app that declares nothing reads exactly what it read before. */
+export const DEFAULT_MAX_REQUEST_BODY_BYTES = 134_217_728;
+
+/** What `Bun.serve` is given: no ceiling of its own. The framework's is `maxRequestBodyBytes`. */
+export const BUN_MAX_REQUEST_BODY_SIZE = Number.MAX_SAFE_INTEGER;
+
+export const requestBodyTooLarge = (pathname: string, bytes: number, ceiling: number): HttpError =>
+  new HttpError({
+    code: 'X_BODY_TOO_LARGE',
+    cause: `${pathname} was sent at least ${bytes} bytes and the most this process reads in one request is ${ceiling} (http.maxRequestBodyBytes)`,
+    fix: `configureHttp({ maxRequestBodyBytes: ${bytes} })   # in the app's http.ts — or send it in parts: storage's signPart/completeUpload for an upload`,
+  });
+
+/** The declared `content-length`, refused when it is already over the ceiling. */
+export const assertDeclaredBody = (request: Request, pathname: string, ceiling: number): void => {
+  const header = request.headers.get('content-length');
+  if (header === null) return;
+  const declared = Number.parseInt(header, 10);
+  if (Number.isFinite(declared) && declared > ceiling) {
+    throw requestBodyTooLarge(pathname, declared, ceiling);
+  }
+};
+
+/**
+ * A body with no declared length, counted: past `ceiling` the stream errors with
+ * `X_BODY_TOO_LARGE`, so whoever reads it — the framework's capped reader or a handler's raw
+ * `arrayBuffer()` — never holds more. A declared length needs nothing: HTTP framing ends the body
+ * there, and `admit` already refused it if it was over.
+ */
+export const capStreamedBody = (request: Request, ceiling: number): Request => {
+  if (request.body === null || request.headers.has('content-length')) return request;
+  let total = 0;
+  const pathname = new URL(request.url).pathname;
+  const counted = request.body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        total += chunk.byteLength;
+        if (total > ceiling) {
+          controller.error(requestBodyTooLarge(pathname, total, ceiling));
+          return;
+        }
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  return new Request(request, { body: counted, duplex: 'half' } as RequestInit);
+};

package/src/byte-range.ts

@@ -15,7 +15,8 @@ export const RANGE_UNSATISFIABLE = 'unsatisfiable';
 /**
  * One range or none. A multi-range or malformed header is ignored rather than refused — RFC 9110
  * lets a server answer the whole representation, and `multipart/byteranges` is a body format no
- * caller of these routes asks for. `bytes=-` names no byte and is ignored the same way.
+ * caller of these routes asks for. `bytes=-` names no byte and is ignored the same way, and so is
+ * `bytes=5-3`, whose last byte comes before its first.
  */
 export function parseByteRange(
   header: string | null | undefined,
@@ -37,8 +38,11 @@ export function parseByteRange(
       : { start: Math.max(size - wanted, 0), end: size - 1 };
   }
   const start = Number(from);
+  // RFC 9110 §14.1.1: a last-pos below its first-pos is an INVALID range-spec, ignored like any
+  // other malformed header — 416 is for a valid range this size cannot meet.
+  if (to !== '' && Number(to) < start) return undefined;
   const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);
-  return start >= size || end < start ? RANGE_UNSATISFIABLE : { start, end };
+  return start >= size ? RANGE_UNSATISFIABLE : { start, end };
 }
 
 /**