@nifrajs/core 1.13.0 → 2.1.0

package/src/reflection.ts

@@ -40,6 +40,8 @@ export interface SchemaReflection {
 export interface ReflectedRouteSchema {
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
+  /** Path-params schema — constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
+  readonly params?: SchemaReflection
   readonly response?: SchemaReflection
   readonly errors?: Readonly<Record<string, SchemaReflection>>
   /** The SSE event-payload schema of a typed streaming route (`app.sse()`). */
@@ -52,6 +54,9 @@ export interface ReflectedRoute {
   readonly schema?: ReflectedRouteSchema
   readonly assurance?: readonly AssuranceEvidence[]
   readonly capabilities?: readonly string[]
+  /** Set when the route is a declared dynamic route family (a runtime-resolved template like
+   * `/api/:slug/:resource`) - so the assurance gate treats it as one classified family, not a single route. */
+  readonly family?: boolean
   /** Field-level response classification plus the highest sensitivity present. */
   readonly classification?: ResponseClassification
   readonly tool?: {
@@ -167,6 +172,7 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
   return {
     ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
     ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
+    ...(schema.params !== undefined ? { params: reflectSchema(schema.params) } : {}),
     ...(schema.response !== undefined ? { response: reflectSchema(schema.response) } : {}),
     ...(Object.keys(reflectedErrors).length > 0 ? { errors: reflectedErrors } : {}),
     ...(schema.sse !== undefined ? { sse: reflectSchema(schema.sse) } : {}),
@@ -218,6 +224,7 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
       ...(schema !== undefined ? { schema } : {}),
       ...(assurance !== undefined ? { assurance } : {}),
       ...(capabilities.length > 0 ? { capabilities } : {}),
+      ...(route.family === true ? { family: true } : {}),
       ...(classification !== undefined ? { classification } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })

package/src/server/client-ip.ts

@@ -0,0 +1,60 @@
+/**
+ * Deriving the caller's IP (`c.clientIp`), correctly and vendor-neutrally.
+ *
+ * The default is the raw socket peer the serving adapter observed - the only value that cannot be
+ * forged by a client, since the client never controls who the TCP connection comes from. Behind a
+ * reverse proxy or CDN the socket peer is the proxy, not the caller, so a `Forwarded`/`X-Forwarded-For`
+ * value must be consulted - but ONLY as far as you actually trust the hops in front of you, because a
+ * directly-reachable app lets any client forge those headers. The trust is therefore an explicit,
+ * opt-in declaration; with none set, `c.clientIp` is the socket peer and no header is ever believed.
+ *
+ * No vendor names live here: a Cloudflare/Fastly/nginx deployment declares its own header or hop count.
+ */
+
+/**
+ * How much of the forwarding chain to trust when deriving `c.clientIp`. Omit for the safe default
+ * (socket peer only, no header believed).
+ *
+ * - `{ trustedHops: n }` - trust `n` reverse-proxy hops in front of the app. The caller is taken from
+ *   `X-Forwarded-For` counted from the right past the `n` trusted hops (the socket peer is hop 0). Use
+ *   this when the app sits behind `n` proxies **you operate**. Fewer entries than trusted hops means
+ *   the header is too short to trust, so `c.clientIp` is `undefined` (fail closed).
+ * - `{ header: name }` - trust a single named header's first value (e.g. a CDN that overwrites it at
+ *   the edge). Only declare this when the app is reachable **exclusively** through that edge; a
+ *   directly-reachable app lets any client forge the header.
+ */
+export type ClientIpTrust = { readonly trustedHops: number } | { readonly header: string }
+
+function firstHeaderValue(req: Request, header: string): string | undefined {
+  const raw = req.headers.get(header)
+  if (raw === null) return undefined
+  const first = raw.split(",", 1)[0]?.trim()
+  return first === undefined || first === "" ? undefined : first
+}
+
+/**
+ * Resolve the caller IP from the raw socket `peer` (adapter-observed), the request's forwarding
+ * headers, and the app's `trust` declaration. Pure and synchronous.
+ */
+export function resolveClientIp(
+  peer: string | undefined,
+  req: Request,
+  trust: ClientIpTrust | undefined,
+): string | undefined {
+  if (trust === undefined) return peer
+  if ("header" in trust) return firstHeaderValue(req, trust.header)
+
+  // trustedHops: walk `X-Forwarded-For` (client-most first) plus the socket peer as the closest hop.
+  const xff = req.headers.get("x-forwarded-for")
+  const forwarded =
+    xff === null
+      ? []
+      : xff
+          .split(",")
+          .map((entry) => entry.trim())
+          .filter((entry) => entry !== "")
+  const chain = peer !== undefined ? [...forwarded, peer] : forwarded
+  // The caller sits just left of the `trustedHops` trusted proxies at the tail of the chain.
+  const index = chain.length - 1 - trust.trustedHops
+  return index >= 0 ? chain[index] : undefined
+}

package/src/server/context.ts

@@ -78,6 +78,34 @@ export interface RouteSchema {
    * and read by downstream policy (e.g. a partner-API surface refusing to expose `pii`/`secret`).
    */
   readonly classification?: DataClassification
+  /**
+   * Inline **route-assurance evidence**: the enforcement posture this route carries, declared adjacent to
+   * the handler (e.g. `[NIFRA_ASSURANCE.AUTHENTICATED]`). Each id becomes route-scoped `declared` evidence
+   * in reflection, so a `nifra.assurance.ts` policy `require:` clause is satisfiable WITHOUT rewriting an
+   * in-handler guard into a `withRouteAssurance`-marked middleware. Ids are lowercase dot/dash segments
+   * (invalid ids throw at registration). Reflected for the assurance gate; never read on the hot path.
+   *
+   * This is an author ASSERTION (recorded as `source: "declared"`), not runtime proof - like every
+   * assurance marker it is trusted by the static gate, which matches on the evidence id, not its source.
+   * Declare an id only on a route whose guard actually enforces it; a false declaration silently satisfies
+   * the policy. (`source` is retained in reflection, so a stricter policy or reviewer can still tell
+   * declared evidence from enforcement-module evidence.)
+   */
+  readonly assurance?: readonly string[]
+  /**
+   * Mark this route a **dynamic route family**: a template (`/api/:slug/:resource`) whose concrete
+   * resources are resolved at runtime (auto-CRUD over tenant-defined tables, a catch-all dispatcher).
+   * Purely declarative - it does not change dispatch. It surfaces in reflection so the assurance gate and
+   * tooling treat the one templated route as a deliberate family whose evidence covers every runtime-
+   * resolved resource, instead of reading it as a single forgotten route.
+   */
+  readonly family?: boolean
+  /** Optional **path-params schema**. Path params arrive as strings (`/users/:id` -> `c.params.id`);
+   * declaring a schema validates them at the boundary (a malformed `:id` is a `422` before the handler,
+   * like `body`/`query`) and can coerce them (use `t.query({ id: t.integer() })` for a numeric param).
+   * The schema must cover every path param; with the strict default an undeclared path param is rejected.
+   * When omitted, `c.params` stays the path-inferred `Record<name, string>`. */
+  readonly params?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it
@@ -117,7 +145,7 @@ export interface RouteSchema {
   readonly onValidationError?: (
     issues: ReadonlyArray<StandardIssue>,
     ctx: Context,
-    kind: "body" | "query",
+    kind: "body" | "query" | "params",
   ) => Response | unknown | Promise<Response | unknown>
 }
 
@@ -131,6 +159,13 @@ type QueryOf<S extends RouteSchema> = S extends { query: infer Q extends Standar
   ? InferOutput<Q>
   : URLSearchParams
 
+/** The validated params type when a params schema is declared, else the path-inferred `Params<Path>`. */
+type ParamsOf<S extends RouteSchema, Path extends string> = S extends {
+  params: infer P extends StandardSchemaV1
+}
+  ? InferOutput<P>
+  : Params<Path>
+
 /** Mutable response controls a handler may write to before returning. */
 export interface ResponseControls {
   status?: number
@@ -159,6 +194,10 @@ export interface Platform<Env = unknown> {
   readonly env?: Env
   /** Extend the response's lifetime for background work (Workers `ctx.waitUntil`). */
   readonly waitUntil?: (promise: Promise<unknown>) => void
+  /** The raw socket peer address the serving adapter observed, if any (`listen()`, `@nifrajs/node`,
+   * `@nifrajs/deno` set it). The server applies the app's `clientIp` trust declaration to this before
+   * exposing {@link Context.clientIp}; read `c.clientIp`, not this. */
+  readonly clientIp?: string | undefined
 }
 
 /**
@@ -174,7 +213,7 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    * everywhere (no more `c.req` vs `ctx.request` mismatch).
    */
   readonly request: Request
-  readonly params: Params<Path>
+  readonly params: ParamsOf<S, Path>
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>
   /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on
@@ -198,6 +237,15 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    * (`c.env: Env`); otherwise `unknown`. Validate at the trust boundary before use either way.
    */
   readonly env: unknown
+  /**
+   * The caller's IP. By default the raw socket peer the serving adapter observed (`listen()`,
+   * `@nifrajs/node`, `@nifrajs/deno`) — the one address a client cannot forge — or `undefined` when the
+   * runtime exposes no socket (Workers) and no trust is declared. Behind a proxy/CDN, set the
+   * `clientIp` server option (`{ trustedHops }` or `{ header }`) to derive the real caller from the
+   * forwarding chain as far as you trust it; unset, no forwarded header is ever believed. Safe to key
+   * rate limits and audit logs on.
+   */
+  readonly clientIp: string | undefined
   /**
    * Schedule background work. On edge runtimes it extends the response lifetime (Workers
    * `ctx.waitUntil`); off-edge it runs the promise fire-and-forget (a rejection is swallowed,

package/src/server/contract.ts

@@ -26,6 +26,8 @@ export interface ResponseDef {
 export interface OperationDef {
   readonly method: Method
   readonly path: string
+  /** Optional path-params schema (validated + coercible at the boundary; see {@link RouteSchema.params}). */
+  readonly params?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
@@ -35,6 +37,10 @@ export interface OperationDef {
   readonly idempotency?: IdempotencyConfig
   /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
   readonly classification?: DataClassification
+  /** Inline route-assurance evidence this operation carries (see {@link RouteSchema.assurance}). */
+  readonly assurance?: readonly string[]
+  /** Mark this operation a dynamic route family (see {@link RouteSchema.family}). */
+  readonly family?: boolean
   /** Short summary (OpenAPI `summary`). */
   readonly summary?: string
   /** Longer description (OpenAPI `description`, CommonMark). */
@@ -68,21 +74,27 @@ type OpResponse<O extends OperationDef> = O extends { response: infer R extends
 
 /** The body types of a contract op's declared **non-2xx** `responses` (schema-bearing ones), keyed by status. */
 type OpErrorBodies<Rs extends Record<string, ResponseDef>> = {
-  [K in keyof Rs as K extends `2${string}` ? never : K]: Rs[K] extends {
+  // Non-2xx statuses, re-keyed from the contract's string keys ("404") to number literals (404) so
+  // the client's failure union discriminates on the numeric `status` it actually receives.
+  [K in keyof Rs as K extends `2${string}`
+    ? never
+    : K extends `${infer N extends number}`
+      ? N
+      : never]: Rs[K] extends {
     schema: infer S extends StandardSchemaV1
   }
     ? InferOutput<S>
     : never
 }
 
-/** The client-visible error union for a contract op — the union of its non-2xx `responses` body schemas,
- * or `unknown` when it declares none (mirrors an inline route with no `errors`). */
+/** The client-visible error bodies for a contract op as a status-keyed record (`{ 404: Body }`), or
+ * `unknown` when it declares none (mirrors an inline route with no `errors`). */
 type OpErrors<O extends OperationDef> = O extends {
   responses: infer Rs extends Record<string, ResponseDef>
 }
-  ? [OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]] extends [never]
+  ? [keyof OpErrorBodies<Rs>] extends [never]
     ? unknown
-    : OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]
+    : OpErrorBodies<Rs>
   : unknown
 
 /**
@@ -116,7 +128,8 @@ export type RegistryFor<C extends ContractShape> = {
 type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends StandardSchemaV1 }
   ? { body: B }
   : Record<never, never>) &
-  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>)
+  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>) &
+  (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 /**
  * The handler context for an op — identical to the inline `Context<Path, S>`, so a
@@ -251,19 +264,25 @@ export function implement<
     // once here at bind time, not per request — it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
+      op.params !== undefined ||
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
-      op.classification !== undefined
+      op.classification !== undefined ||
+      op.assurance !== undefined ||
+      op.family !== undefined
         ? {
+            ...(op.params !== undefined ? { params: op.params } : {}),
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
             ...(op.classification !== undefined ? { classification: op.classification } : {}),
+            ...(op.assurance !== undefined ? { assurance: op.assurance } : {}),
+            ...(op.family !== undefined ? { family: op.family } : {}),
           }
         : undefined
     return {

package/src/server/http.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency-free HTTP helpers shared by the kernel and the opt-in request lanes (idempotency,
+ * effect-ledger). Kept in a leaf module so a lane can reuse them without importing the server, and so
+ * the server can reuse them without pulling a lane's feature code into the base bundle.
+ */
+
+/** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
+export function jsonError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): Response {
+  return Response.json(
+    { ok: false, error },
+    headers !== undefined ? { status, headers } : { status },
+  )
+}
+
+export interface UrlParts {
+  readonly pathname: string
+  readonly search: string
+}
+
+// Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
+// `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
+// the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
+// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
+export function urlPartsOf(url: string): UrlParts {
+  const schemeEnd = url.indexOf("://")
+  const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3)
+  if (start === -1) return { pathname: "/", search: "" }
+
+  let pathEnd = url.length
+  let searchStart = -1
+  let searchEnd = url.length
+  for (let i = start; i < url.length; i++) {
+    const c = url.charCodeAt(i)
+    if (c === 63 /* ? */ && searchStart === -1) {
+      pathEnd = i
+      searchStart = i
+    } else if (c === 35 /* # */) {
+      if (searchStart === -1) pathEnd = i
+      searchEnd = i
+      break
+    }
+  }
+
+  return {
+    pathname: url.slice(start, pathEnd),
+    search: searchStart === -1 ? "" : url.slice(searchStart, searchEnd),
+  }
+}
+
+// Extract the pathname WITHOUT a full WHATWG `new URL(req.url)` parse. Kept as a public-ish helper
+// for tests and callers that only need the path; the request hot path uses `urlPartsOf()` once.
+export function pathnameOf(url: string): string {
+  return urlPartsOf(url).pathname
+}

package/src/server/idempotency-lane.ts

@@ -0,0 +1,321 @@
+/**
+ * The opt-in idempotency request lane. Installed by `.use(idempotency())` and reached only by routes
+ * that declare `schema.idempotency`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the whole dedupe machinery out.
+ *
+ * The kernel resolves a route's declared idempotency at registration (via {@link IdempotencyRuntime.resolve})
+ * and, on the request path, hands a matched idempotent route to {@link IdempotencyRuntime.run}. Everything
+ * server-specific is supplied through {@link IdempotencyHost} so this module depends on no server internals.
+ */
+import { RouteConfigError } from "../errors.ts"
+import {
+  canonicalizeIdempotencyBody,
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  IdempotencyResponseTooLargeError,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+  validIdempotencyNamespace,
+} from "../idempotency.ts"
+import {
+  beginRequestEffectTracking,
+  markEffect,
+  requestEffectEvidence,
+  requestIsSafeToRetry,
+} from "../internal/effect-execution.ts"
+import { readBoundedBytes } from "./body.ts"
+import type { Platform, RouteSchema } from "./context.ts"
+import { jsonError, urlPartsOf } from "./http.ts"
+import { INSTALL_IDEMPOTENCY } from "./install.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
+export interface ResolvedIdempotency {
+  readonly store: IdempotencyStore
+  readonly ttlMs: number
+  readonly headerName: string
+  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
+  readonly maxResponseBytes: number
+}
+
+/**
+ * What the dedupe lane needs from the server to run a fresh key: the app-wide body cap and a way to
+ * run the buffered request through the route's normal lanes to a concrete `Response`.
+ */
+export interface IdempotencyHost {
+  readonly maxBodyBytes: number
+  runLanes(
+    buffered: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+  ): Promise<Response>
+}
+
+/** The injected idempotency implementation the kernel calls through when the plugin is installed. */
+export interface IdempotencyRuntime {
+  readonly trackEffect: (context: object, committed: boolean) => void
+  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+  resolve(
+    schema: RouteSchema | undefined,
+    authenticated: boolean,
+    maxBodyBytes: number,
+  ): ResolvedIdempotency | undefined
+  /** The dedupe lane: read the key, fingerprint the request, consult the store, run/replay/reject. */
+  run<T>(
+    config: ResolvedIdempotency,
+    req: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+    wrapResponse: (response: Response) => T,
+    host: IdempotencyHost,
+  ): Promise<T>
+}
+
+/** The install seam a server exposes so the `idempotency()` plugin can hand it a runtime. */
+interface IdempotencyInstallable {
+  [INSTALL_IDEMPOTENCY](runtime: IdempotencyRuntime): void
+}
+
+/**
+ * Enable request idempotency. Routes that declare `schema.idempotency` get the dedupe lane: a repeat
+ * `Idempotency-Key` replays the stored response instead of re-running the handler. Without this plugin,
+ * declaring `schema.idempotency` is a registration error (the safety gate can never be silently
+ * dropped). `store` is the app-wide default backing routes that do not pin their own; omit it for a
+ * shared in-process store (development/tests only - inject a durable store in production).
+ */
+export interface IdempotencyPluginOptions {
+  readonly store?: IdempotencyStore | undefined
+}
+
+export function idempotency(options?: IdempotencyPluginOptions): IdentityPlugin {
+  const runtime = createIdempotencyRuntime(options)
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as IdempotencyInstallable)[INSTALL_IDEMPOTENCY](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:idempotency" }) as IdentityPlugin
+}
+
+/**
+ * Build an idempotency runtime. `store` is the app-wide default backing routes that declare
+ * `schema.idempotency` without their own `store`; when omitted, a shared in-process
+ * {@link MemoryIdempotencyStore} is created lazily on first idempotent route.
+ */
+export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): IdempotencyRuntime {
+  const configuredStore = options?.store
+  let lazyStore: IdempotencyStore | undefined
+  const defaultStore = (): IdempotencyStore => {
+    if (configuredStore !== undefined) return configuredStore
+    lazyStore ??= new MemoryIdempotencyStore()
+    return lazyStore
+  }
+
+  return {
+    trackEffect(context, committed) {
+      markEffect(context, committed)
+    },
+    resolve(schema, authenticated, maxBodyBytes) {
+      const config = schema?.idempotency
+      if (config === undefined) return undefined
+      if (schema?.sse !== undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "streaming/SSE responses cannot be used on an idempotency route",
+        )
+      }
+      const store = config.store ?? defaultStore()
+      if (config.scope === "durable" && store.durability !== "durable") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          'durable idempotency requires a durable store (store.durability must be "durable")',
+        )
+      }
+      const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS
+      if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency ttlMs must be a finite positive number",
+        )
+      }
+      const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
+      try {
+        new Headers().set(headerName, "probe")
+      } catch {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency header name ${JSON.stringify(headerName)}`,
+        )
+      }
+      const namespace = config.namespace
+      if (namespace === undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency namespace is required; use a principal resolver or an explicit shared scope",
+        )
+      }
+      if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+        )
+      }
+      if (authenticated && typeof namespace !== "function") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "authenticated idempotency routes require a principal namespace resolver",
+        )
+      }
+      const maxResponseBytes = config.maxResponseBytes ?? maxBodyBytes
+      if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency maxResponseBytes must be a positive integer",
+        )
+      }
+      return Object.freeze({
+        store,
+        ttlMs,
+        headerName,
+        namespace,
+        maxResponseBytes,
+      })
+    },
+
+    async run(config, req, platform, entry, params, search, wrapResponse, host) {
+      const key = req.headers.get(config.headerName)
+      if (key === null || !validIdempotencyKey(key)) {
+        return wrapResponse(jsonError(400, "idempotency_key_required"))
+      }
+      const namespace =
+        typeof config.namespace === "function"
+          ? await config.namespace(req.clone(), platform)
+          : config.namespace
+      if (!validIdempotencyNamespace(namespace)) {
+        return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
+      }
+      const read = await readBoundedBytes(req, host.maxBodyBytes)
+      if (!read.ok) {
+        return wrapResponse(
+          jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"),
+        )
+      }
+      const url = urlPartsOf(req.url)
+      const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"))
+      const fingerprint = await computeIdempotencyFingerprint(
+        req.method,
+        `${url.pathname}${url.search}`,
+        canonicalBody,
+        req.headers.get("content-type") ?? "",
+      )
+
+      const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+      if (begin.state === "replay") {
+        return wrapResponse(
+          responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
+        )
+      }
+      if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
+      if (begin.state === "in-flight") {
+        return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
+      }
+      if (begin.state === "capacity") {
+        return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
+      }
+      const reservation = begin.reservation
+
+      // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+      // then run those lanes to a concrete Response.
+      const bufferedInit: RequestInit = {
+        method: req.method,
+        headers: req.headers,
+        signal: req.signal,
+      }
+      if (read.bytes.byteLength > 0)
+        bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+      const buffered = new Request(req.url, bufferedInit)
+      beginRequestEffectTracking(buffered)
+      let response: Response
+      try {
+        response = await host.runLanes(buffered, platform, entry, params, search)
+      } catch (err) {
+        const evidence = requestEffectEvidence(buffered)
+        if (!evidence.began) {
+          // The request-local boundary proves no owned effect started, so this is the one safe case
+          // where releasing the key cannot duplicate an effect.
+          await config.store.abandon({ namespace, key, reservation })
+          throw err
+        }
+        // A committed or ambiguous effect must never be repeated. Persist a payload-free terminal
+        // response even though the normal handler lifecycle escaped without producing one.
+        response = new Response(null, { status: 500 })
+        const completed = await config.store.complete({
+          namespace,
+          key,
+          reservation,
+          response: await serializeResponse(response, { maxBytes: config.maxResponseBytes }),
+        })
+        if (!completed) {
+          return wrapResponse(
+            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+          )
+        }
+        return wrapResponse(response)
+      }
+      if (
+        response.status >= 500 &&
+        requestIsSafeToRetry(buffered) &&
+        !requestEffectEvidence(buffered).began
+      ) {
+        const abandoned = await config.store.abandon({ namespace, key, reservation })
+        if (!abandoned) {
+          return wrapResponse(
+            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+          )
+        }
+        return wrapResponse(response)
+      }
+      // Once the handler ran, every concrete response is terminal for this key. A non-2xx may follow
+      // an already-committed external effect; abandoning it would let a retry duplicate that effect.
+      let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+      try {
+        storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+      } catch (error) {
+        if (!(error instanceof IdempotencyResponseTooLargeError)) throw error
+        // The effect may already have happened, so never abandon and permit a duplicate execution.
+        // Commit a small terminal response under the winning key and return that same response now.
+        response = jsonError(507, "idempotency_response_too_large")
+        try {
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        } catch (terminalError) {
+          if (!(terminalError instanceof IdempotencyResponseTooLargeError)) throw terminalError
+          // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+          // status + replay safety without silently storing more bytes than the route permits.
+          response = new Response(null, { status: 507 })
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        }
+      }
+      const completed = await config.store.complete({
+        namespace,
+        key,
+        reservation,
+        response: storedResponse,
+      })
+      if (!completed) {
+        return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }))
+      }
+      return wrapResponse(response)
+    },
+  }
+}