@ultimat3/http 11.3.0 → 12.0.0

package/CLAUDE.md

@@ -20,6 +20,27 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 ## Rules
 
 - Route `meta.auth` is required. Never default a route to public.
+- **An app declares its half of `HttpConfig` through `configureHttp()`, and the boot lays its own
+  facts over it** (`As of 2026-08-24`). Until 12.0.0 the entire tuning surface was **unreachable
+  from a shipped app**: `AppConfig` has never had an `http` key, `RuntimeOverrides` carries none,
+  and the only construction any shipped process made was one fixed literal in
+  `packages/cli/src/dev-roles.ts` passing eight boot facts — so `DEFAULT_CORS.origins` was `[]` in
+  every deployment (an SPA on `app.example.com` calling `api.example.com` could not work, ever),
+  `bodyLimitBytes` was 1 MiB for a 4 MB CSV endpoint, `requestTimeoutMs` 30s for a five-minute
+  export, and `rateLimit.buckets` was 120 burst / 2 rps for a bank and a blog alike. Fourteen
+  `fix:` lines told the reader to edit `http.<key>` in `app.config.ts`, which has never held one.
+  It is a registration and not a config key for `configureAuthenticator`'s reason, stated in
+  `hooks.ts`: `@ultimat3/core` is tier 0 and cannot hold this package's types, so an `http` block
+  on `AppConfig` would be a **second declaration** of `HttpConfigInput` in a package that can
+  never check it against this one. `AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>`,
+  **derived, never listed**: a key the boot always overwrites (`port`, `hostname`, `dev`,
+  `buildId`, `signInPath`, `trustProxy`, `trustedProxyHops`, `rateLimit.scope`) is a type error
+  where an app writes it, rather than a value silently discarded at every boot. `mergeHttpConfig`
+  merges one level down — `security.csp.extend` per DIRECTIVE, because the app's CDN source and
+  the boot's inline-script hash are each the whole answer for something, and either alone breaks a
+  page. `type-pins.ts` holds the other half: a key on `HttpConfig` and not on `HttpConfigInput` is
+  a build error, which `scripts/config-readers.ts` cannot see — that ratchet walks `AppConfig` and
+  asks whether a key is READ, and this is the mirror question.
 - **`asCtx` is a WIDENING the compiler checks, never a cast.** `RequestContext extends Ctx`, and
   `asCtx` is the identity function. It used to be `ctx as unknown as Ctx` over an object that set
   none of `clock`, `now`, `logger`, `signal` or `services` — so `ctx.now()` threw
@@ -60,6 +81,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   with `AbortSignal.any`, which is what `context.ts` had documented and nothing wired — a closed
   tab held its handler, its pool slot and its vendor connection for the whole 30s. `expired` stays
   the timer's alone: it answers the SOCKET, and a caller that hung up has no socket to answer.
+  **And it leaves this process on the next hop's headers, `As of 2026-08-24`**:
+  `Deadline.deadlineAt` is published as core's `ctx.deadlineAt`, and `traceHeaders()` (tier 0, the
+  one thing both typed clients spread before the caller's own headers) sends what is LEFT as
+  `x-request-timeout-ms`. Before that the header had exactly one reader — `resolveTimeoutMs`, in
+  this file — and **zero writers anywhere in the tree**, so gateway → A (30s) → B meant a call made
+  at t=29 started B on a FRESH 30s: real work, holding a pool slot and a vendor connection, half a
+  minute after A's socket was answered `X_TIMEOUT`. A spent budget sends no header at all rather
+  than `0`, because `resolveTimeoutMs` ignores anything under 1ms and falls back to its own.
   With `requestTimeoutMs: 0` the caller's signal is handed through as-is rather than the shared
   never-aborted singleton, which every such request used to share — one `abort` listener per
   request, accumulating for the life of the process. Always `deadline.clear()` in the `finally` —
@@ -242,6 +271,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `lastResort` spells its one `type` as a literal because that function calls nothing, and
   `pipeline-finalize.test.ts` pins the literal against `problemTypeFor('X_INTERNAL')` so the two
   cannot drift. Never assert either value as a copied string — import the constant.
+- **`error-map.ts` answers the status; `error-facts.ts` renders the throwable** (`As of
+  2026-08-24`). One file did both and reached 501 lines, over the ceiling. The seam between
+  them is `declaredStatusFor(code)` — `number | undefined`, exported to this package only —
+  because the two questions are genuinely different: `statusFor` always answers a number, while
+  "did ANYBODY classify this code" is what decides whether a 5xx may carry the throwable's own
+  words back to the caller (`isUnclassifiedFailure`). Imports go one way, `error-facts.ts` →
+  `error-map.ts`; a status read from the facts file would be the second table this package
+  spent a release deleting.
 - Statuses live in `error-map.ts` only. No other file writes a status number. The framework's
   table (`ERROR_STATUS`) is closed; an app declares its own codes' statuses with
   `registerErrorStatus()`, which refuses a code the framework already holds. Without that half,
@@ -309,8 +346,24 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `X_INTERNAL`, built with no call that could fail in turn, and the renderer's own failure goes to
   the log as `pipeline.problem_failed` — a last resort sharing a code path with what just broke is
   not one.
+- **One request spends a LIST of rate-limit keys, and the tenant's is the second** (`As of
+  2026-08-24`). `rateLimitKey` picked ONE subject — actor > org > ip, exclusive — and `actorView`
+  answers `null` for anonymous, so `orgId` was consulted only for a caller with an org and no id:
+  **no authenticated request ever touched an org bucket**. A tenant with 8,000 seats whose
+  integration entered a retry loop therefore took 8,000 × the per-actor burst against one shared
+  pool, every bucket inside its own limit, and no number an operator could set would have refused
+  it — while `@ultimat3/jobs` has had `perTenant` since it shipped. `rateLimitSpends` answers the
+  caller's key **and** `tenant|org:<id>` when the app declared `rateLimit.tenantBucket`; the stage
+  spends them in order and stops at the first refusal, so a caller its own bucket already refused
+  costs its tenant nothing. The tenant key is deliberately NOT scoped to the route — a per-route
+  tenant bucket is the same number multiplied by the route table, which is not a cap. `null` is
+  the default because one tenant is a person and the next is five thousand seats (axiom 8), and a
+  name nothing declares is `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` at `defineHttpConfig`, never a
+  silent fall-through to `default`. The headers report the bucket **closest to refusing**: telling
+  a client `remaining: 99` off its own bucket while its tenant's holds 2 is a number that plans a
+  caller into a 429.
 - **The memory rate-limit store is bounded, and the eviction order is part of the guarantee.**
-  The key falls back to the connection address (`rateLimitKey`), so a scan rotating through an
+  The key falls back to the connection address (`rateLimitSpends`), so a scan rotating through an
   IPv6 /64 mints one entry per request — an unbounded map hands the flood the process. Every
   entry carries `forgetAtMs`, the instant a refilled bucket becomes indistinguishable from a
   missing one, and the sweep drops those for free. `DEFAULT_MAX_RATE_LIMIT_KEYS` is the backstop,
@@ -402,7 +455,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 matcher, precedence static > param > wildcard, `path-invalid` for a segment that will not decode |
-| `error-map.ts` | code → status table + `factsOf()` |
+| `error-map.ts` | the code → status table, closed, plus the app's half (`registerErrorStatus`) |
+| `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document, the three terminal lines |
 | `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices` + the app's `configureAuthenticator()` |
 | `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 |
@@ -421,6 +475,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `csrf.ts` | the origin proof an unsafe method from a credentialed browser must carry |
 | `locale.ts` | WHERE the request's locale and zone are read from — header and cookie NAMES only, plus `readCookie`. It negotiates nothing |
 | `rate-limit-buckets.ts` | the one point routes and config meet: a route's own bucket, registered or refused |
+| `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 
 ## Commands
 

package/README.md

@@ -13,8 +13,10 @@ to skip.
 | the ordered request lifecycle | `pipeline.ts` |
 | typed request (params, query, body) | `request.ts` |
 | response constructors + `problem()` | `response.ts` |
-| code → status, `factsOf()` | `error-map.ts` |
+| code → status, closed table | `error-map.ts` |
+| `factsOf()`, the problem document, the terminal lines | `error-facts.ts` |
 | token-bucket limiting, `toBucket` | `rate-limit.ts` |
+| the app's own HTTP declaration, and the boot's facts over it | `app-config.ts` |
 | CORS, CSP/HSTS | `cors.ts`, `security-headers.ts` |
 | CSRF (origin proof for a credentialed write) | `csrf.ts` |
 | the request deadline and `ctx.signal` | `deadline.ts` |
@@ -22,6 +24,37 @@ to skip.
 | the inbound request id and trace, read before the span | `correlation.ts` |
 | dev error overlay | `overlay.ts` |
 
+## What an app declares: `configureHttp()`
+
+```ts
+// apps/web/app/http.ts — module scope, imported by the app like any other module
+import { configureHttp } from '@ultimat3/http';
+
+configureHttp({
+  cors: { origins: ['https://app.example.com'], credentials: true },
+  bodyLimitBytes: 8 * 1024 * 1024,   // this API takes a 4 MB CSV
+  requestTimeoutMs: 300_000,          // and an export that really does take five minutes
+  rateLimit: {
+    tenantBucket: 'tenant',
+    buckets: { tenant: { capacity: 5_000, refillPerSecond: 100 } },
+  },
+});
+```
+
+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`
+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
+not gain one: `@ultimat3/core` is tier 0 and cannot hold this package's types.
+
+`AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>` — `port`, `hostname`, `dev`,
+`buildId`, `signInPath`, `trustProxy`, `trustedProxyHops` and `rateLimit.scope` are the boot's, and
+writing one here is a **type error** rather than a value silently overwritten at the next boot.
+`mergeHttpConfig(configuredHttp(), boot)` is the layering, and it merges `security.csp.extend` per
+directive: the app's CDN source and the boot's inline-script hash are each the whole answer for
+something.
+
 ## The pipeline is the guarantee
 
 ```
@@ -57,6 +90,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | 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 `createServer`, 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 `createServer`, because the loser would be a number someone read and nothing applied |
+| a `rateLimit.tenantBucket` naming a bucket nothing declares | `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` at `defineHttpConfig`, because the name would fall through to `default` and a whole tenant's cap would silently be the 120-burst read bucket |
 | an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `createPipeline`, because the name would fall through to `default` — measured at 120 burst for a route declaring 5 |
 | a config that never declared `rateLimit.scope` | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `'process'` used to be the default, so "nobody asked" and "the app said one replica" were the same value while the chart runs three |
 | `trustProxy: true` with no `trustedProxyHops` | `X_TRUST_PROXY_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `trustProxy` now defaults to `false`, and `x-forwarded-for` is read at `entries.length - hops` — never at `[0]`, which is whatever the client typed |
@@ -102,6 +136,18 @@ so nothing can be wrong.
 `rateLimitStore` feeds the `PipelineDeps.limiter` seam rather than sitting beside it: the bucket
 maths stays in `createRateLimiter`, 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
+builder used to pick exactly ONE subject and consult `orgId` only when there was no actor id,
+which no authenticated request ever satisfies: a tenant with 8,000 seats took 8,000 × the
+per-actor burst against one shared pool, every bucket inside its own limit, and no number an
+operator could set would have refused it. The tenant key is `tenant|org:<id>` and is deliberately
+NOT scoped to the route — a per-route tenant bucket is the same allowance once per route. The
+spend stops at the first refusal, so a caller its own bucket refused costs its tenant nothing, and
+the `ratelimit-*` headers report the bucket closest to refusing. `tenantBucket` defaults to `null`:
+one tenant is a person and the next is five thousand seats, so there is no allowance a framework
+can pick for you.
+
 **A shared store ships, `As of 2026-08`** — `postgresRateLimitStore({ executor })`, one table
 and one `insert … on conflict` per take, so N replicas count against one bucket. Until it landed,
 `scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded
@@ -217,7 +263,7 @@ in a table row and a table row has no anchor. Assert against `problemTypeFor` an
 
 ## Boundaries
 
-Tier 2. Imports `@ultimat3/core` and `@ultimat3/schema` only. Authentication and
-policy evaluation arrive through `ServerHooks`, declared structurally, because
-`@ultimat3/policy` is a sibling tier. There is no plugin API: `Middleware` wraps a
-handler, the pipeline is everything else.
+Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ultimat3/time` —
+tiers 0 and 1, which is the whole rule. Authentication and policy evaluation arrive through
+`ServerHooks`, declared structurally, because `@ultimat3/policy` is a sibling tier. There is no
+plugin API: `Middleware` wraps a handler, the pipeline is everything else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/i18n": "11.3.0",
-    "@ultimat3/schema": "11.3.0",
-    "@ultimat3/time": "11.3.0"
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/i18n": "12.0.0",
+    "@ultimat3/schema": "12.0.0",
+    "@ultimat3/time": "12.0.0"
   }
 }

package/src/app-config.ts

@@ -0,0 +1,146 @@
+// The app's own HTTP declaration, and the layering that keeps a boot fact above it. One
+// registration site, read once by whatever process starts the web role — the same seam
+// `configureAuthenticator()` is, and for the same reason: `@ultimat3/core` is tier 0 and cannot
+// hold this package's types, so an `http` block on `AppConfig` would be a second declaration of
+// `HttpConfigInput` in a package that can never check it against this one.
+
+import type { HttpConfigInput } from './config';
+import type { RateLimitConfig } from './rate-limit';
+
+/**
+ * The keys the BOOT owns, and the reason this type is an `Omit` rather than a hand-written list of
+ * what an app may say. Each of these is a fact about the PROCESS — the port it was told to bind,
+ * the build it serves, whether it is `x dev`, how many proxies the deployment puts in front of it,
+ * `auth.signInPath` from `app.config.ts` — so a value an app wrote for one of them would be
+ * overwritten at every boot: a switch with no wire, which is the defect this whole surface exists
+ * to remove. Refused at the type level, which is the build error that enforces it.
+ */
+export type BootOwnedHttpKey =
+  | 'port'
+  | 'hostname'
+  | 'dev'
+  | 'buildId'
+  | 'signInPath'
+  | 'trustProxy'
+  | 'trustedProxyHops';
+
+/**
+ * What an app declares. `rateLimit.scope` is boot-owned for the same reason as the keys above:
+ * `startWeb` DERIVES it from the store it installed, so a literal here would be a second
+ * declaration quietly contradicting the object beside it — and `assertRateLimitScope` compares
+ * exactly those two halves.
+ */
+export type AppHttpConfig = Omit<HttpConfigInput, BootOwnedHttpKey | 'rateLimit'> & {
+  readonly rateLimit?: Omit<Partial<RateLimitConfig>, 'scope'> | undefined;
+};
+
+/**
+ * The app's declaration, if it made one. A single value and not a list, exactly as
+ * `configuredAuthenticator` is: two answers to "how does this server bind and what does it admit"
+ * is two configurations, and the one that ran first wins.
+ *
+ * Process-global for the reason that one is: the app has exactly one boot, and every host that
+ * starts a server (`x dev`, `apps/web/server.ts`) would otherwise need its own way to be handed
+ * the same values — which is what left the whole tuning surface unreachable, since the only
+ * shipped construction was a fixed literal inside the CLI.
+ */
+let declared: AppHttpConfig | undefined;
+
+export const configureHttp = (config: AppHttpConfig): void => {
+  declared = config;
+};
+
+/** What the boot layers its own facts over. `undefined` means the locked defaults stand. */
+export const configuredHttp = (): AppHttpConfig | undefined => declared;
+
+/** Test seam. Production configures once at module scope and never unconfigures. */
+export const resetHttpConfig = (): void => {
+  declared = undefined;
+};
+
+type SecurityInput = NonNullable<HttpConfigInput['security']>;
+type CspInput = NonNullable<SecurityInput['csp']>;
+type CspExtend = NonNullable<CspInput['extend']>;
+
+/**
+ * Per directive, both lists. The app's `script-src` is a CDN it serves scripts from and the boot's
+ * is the sha256 of the hydration runtime this process emits inline — each is the whole answer for
+ * something, so a merge that let either win breaks a page: the CDN script, or every island.
+ *
+ * Built through a `Map`, never by assigning `out[directive]`: a directive named `__proto__` sets
+ * the PROTOTYPE rather than a key, which is a source silently dropped from the one header this
+ * package locks down hardest.
+ */
+const mergeCspExtend = (
+  app: CspExtend | undefined,
+  boot: CspExtend | undefined,
+): CspExtend | undefined => {
+  if (app === undefined) return boot;
+  if (boot === undefined) return app;
+  const merged = new Map<string, readonly string[]>(Object.entries(app));
+  for (const [directive, sources] of Object.entries(boot)) {
+    merged.set(directive, [...(merged.get(directive) ?? []), ...sources]);
+  }
+  return Object.fromEntries(merged);
+};
+
+const mergeSecurity = (
+  app: SecurityInput | undefined,
+  boot: SecurityInput | undefined,
+): SecurityInput | undefined => {
+  if (app === undefined) return boot;
+  if (boot === undefined) return app;
+  const extend = mergeCspExtend(app.csp?.extend, boot.csp?.extend);
+  const csp: CspInput = {
+    ...app.csp,
+    ...boot.csp,
+    ...(extend === undefined ? {} : { extend }),
+  };
+  return { ...app, ...boot, csp };
+};
+
+/**
+ * The app's declaration with the boot's own facts laid OVER it — the one order that can be right.
+ * `buildId`, the port, the CSP hashes of what this process emits and the scope of the store it
+ * installed are all things the boot measured; an app can only have guessed at them. Everything
+ * else the app said survives, which is the whole point of it having said anything.
+ *
+ * Sections merge one level down rather than being replaced whole: `security: { csp: { extend } }`
+ * from the boot would otherwise delete an app's `hsts`, `frameAncestors` and its own extends, and
+ * `rateLimit: { scope }` would delete every bucket it declared.
+ */
+export const mergeHttpConfig = (
+  app: AppHttpConfig | undefined,
+  boot: HttpConfigInput,
+): HttpConfigInput => {
+  if (app === undefined) return boot;
+  // `rateLimit` is lifted out of the spread rather than overwritten by it: `AppHttpConfig` types
+  // it WITHOUT `scope` and `HttpConfigInput` types it with, so under `exactOptionalPropertyTypes`
+  // the spread of the narrower optional is not assignable to the wider one. The merged value is
+  // computed below and put back.
+  const { rateLimit: appRateLimit, ...appRest } = app;
+  const cors =
+    app.cors === undefined && boot.cors === undefined ? undefined : { ...app.cors, ...boot.cors };
+  const csrf =
+    app.csrf === undefined && boot.csrf === undefined ? undefined : { ...app.csrf, ...boot.csrf };
+  const locale =
+    app.locale === undefined && boot.locale === undefined
+      ? undefined
+      : { ...app.locale, ...boot.locale };
+  const tz = app.tz === undefined && boot.tz === undefined ? undefined : { ...app.tz, ...boot.tz };
+  const rateLimit: Partial<RateLimitConfig> | undefined =
+    appRateLimit === undefined && boot.rateLimit === undefined
+      ? undefined
+      : { ...appRateLimit, ...boot.rateLimit };
+  const security = mergeSecurity(app.security, boot.security);
+  return {
+    ...appRest,
+    ...boot,
+    ...(cors === undefined ? {} : { cors }),
+    ...(csrf === undefined ? {} : { csrf }),
+    ...(locale === undefined ? {} : { locale }),
+    ...(tz === undefined ? {} : { tz }),
+    ...(rateLimit === undefined ? {} : { rateLimit }),
+    ...(security === undefined ? {} : { security }),
+  };
+};

package/src/config.ts

@@ -1,5 +1,8 @@
-// The HTTP slice of `app.config.ts`. One resolver, so a value is either a locked
-// default or an explicit override — never "whatever the first caller passed".
+// The resolver every HTTP config goes through, so a value is either a locked default or an
+// explicit override — never "whatever the first caller passed". It is NOT a slice of
+// `app.config.ts`, which this file claimed for four majors while `AppConfig` has never carried an
+// `http` key: an app declares its half through `configureHttp()` (`app-config.ts`) and the boot
+// lays its own facts over it before calling this.
 import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';

package/src/context.ts

@@ -80,6 +80,11 @@ export interface RequestContext extends Ctx {
   readonly logger: Logger;
   /** Aborted when the caller goes away or the request deadline passes. See `deadline.ts`. */
   readonly signal: AbortSignal;
+  /**
+   * The instant `signal` will fire at, or `null` with `requestTimeoutMs: 0`. Core's field: a
+   * signal can only say "already over", and an outbound hop has to say how much is LEFT.
+   */
+  readonly deadlineAt: number | null;
   readonly services: ServiceBag;
 
   // Mutable slots, each filled by exactly one pipeline stage. Kept mutable (and
@@ -135,6 +140,8 @@ export interface RequestContextInit {
   readonly logger?: Logger;
   /** The deadline/disconnect signal. Absent means a request nothing can cancel. */
   readonly signal?: AbortSignal;
+  /** `Deadline.deadlineAt` — epoch ms. Absent means this request has no budget. */
+  readonly deadlineAt?: number | null;
   readonly services?: ServiceBag;
 }
 
@@ -174,6 +181,7 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
     // context — a callback that outlived the request scope, a logger passed to a driver.
     logger: (init.logger ?? rootLogger).child({ requestId, traceId }),
     signal: init.signal ?? NEVER_ABORTED,
+    deadlineAt: init.deadlineAt ?? null,
     // Frozen and explicit. `defineService` factories are NOT installed here: core does not
     // export the installer, so the honest answer for a service nothing passed is
     // `X_SERVICE_MISSING` from `useService()` — which is what it exists to raise — rather than

package/src/cors.ts

@@ -1,5 +1,5 @@
-// CORS with a locked default: same-origin only. Cross-origin access is a decision
-// the app makes in app.config.ts, never something a route can quietly opt into.
+// CORS with a locked default: same-origin only. Cross-origin access is a decision the app makes
+// once, in `configureHttp({ cors })`, never something a route can quietly opt into.
 
 import { corsConfigInvalid } from './errors';
 

package/src/deadline.ts

@@ -4,18 +4,31 @@
 // until the process died, and SIGTERM then waited out the whole drain budget for work that would
 // never finish.
 
+import { REQUEST_TIMEOUT_HEADER, systemClock } from '@ultimat3/core';
 import type { HttpConfig } from './config';
 import { requestTimedOut } from './errors';
 
 /**
  * A caller may SHORTEN this request's deadline, never lengthen it. Honoured without trusting the
  * proxy, because the only thing it can buy an attacker is a faster 504 for their own request.
+ *
+ * The name is core's, re-exported rather than declared twice: this package READS the header and
+ * `@ultimat3/core`'s typed-client wire path WRITES it, and a second literal is a propagation that
+ * stops working the day one of the two strings is edited. Same shape as `logger.ts` re-exporting
+ * `REDACTED` — one definition, one public path.
  */
-export const REQUEST_TIMEOUT_HEADER = 'x-request-timeout-ms';
+export { REQUEST_TIMEOUT_HEADER };
 
 export interface Deadline {
   /** Aborted when the deadline passes. Handed to the context as `ctx.signal`. */
   readonly signal: AbortSignal;
+  /**
+   * Epoch ms the budget runs out at, or `null` when there is none — `ctx.deadlineAt`, and what an
+   * outbound hop subtracts `now` from. Real monotonic time (`systemClock`), never an injected
+   * clock, for the reason the drain budget is: the timer beside it runs on `setTimeout`, so a
+   * frozen clock would publish an instant the abort will not honour.
+   */
+  readonly deadlineAt: number | null;
   /** Rejects with `X_TIMEOUT` at the deadline; `undefined` when there is no deadline. */
   readonly expired: Promise<never> | undefined;
   readonly timeoutMs: number;
@@ -27,6 +40,7 @@ const NEVER_ABORTED: AbortSignal = new AbortController().signal;
 
 const NO_DEADLINE: Deadline = {
   signal: NEVER_ABORTED,
+  deadlineAt: null,
   expired: undefined,
   timeoutMs: 0,
   clear: () => undefined,
@@ -69,6 +83,8 @@ export const startDeadline = (input: {
   }
 
   const controller = new AbortController();
+  // Read BEFORE the timer is armed, so the published instant is never later than the abort.
+  const deadlineAt = systemClock.now().getTime() + timeoutMs;
   let fire: (() => void) | undefined;
   const expired = new Promise<never>((_resolve, reject) => {
     fire = () => reject(requestTimedOut(input.method, input.pathname, timeoutMs));
@@ -83,6 +99,7 @@ export const startDeadline = (input: {
   }, timeoutMs);
 
   return {
+    deadlineAt,
     // Both halves, or the doc on `ctx.signal` is half true — which it was: nothing in this package
     // read the inbound signal, so a browser closing the tab left the request holding its pool slot
     // and its vendor connection for the whole budget, for a caller that is gone. `expired` stays