@nifrajs/core 2.11.0 → 2.12.1

package/src/server/server.ts

@@ -8,6 +8,8 @@ import {
 } from "../budget.ts"
 import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
+// Type-only (erased at build): the package root re-exports this module, so a value import would cycle.
+import type { Version } from "../index.ts"
 import {
   type AroundCapabilityOptions,
   CAPABILITY_GUARD,
@@ -26,22 +28,19 @@ import {
   validEvidenceId,
 } from "../internal/route-assurance.ts"
 import { type CatalogRoute, RouteCatalog } from "../internal/route-catalog.ts"
-import type {
-  ContextRouteRunner,
-  FusedBodyRunner,
-  FusedWebRunner,
-  InternalHandler,
-  RawAfterHandle,
-  RawAround,
-  RawBeforeHandle,
-  RawDerive,
-  RawErrorHandler,
-  RouteEntry,
-  RouteExecutionPlan,
-  RouteExecutionRunner,
+import {
+  compileRouteExecutionPlan,
+  type FusedBodyRunner,
+  type FusedWebRunner,
+  type InternalHandler,
+  type RawAfterHandle,
+  type RawAround,
+  type RawBeforeHandle,
+  type RawDerive,
+  type RawErrorHandler,
+  type RouteEntry,
 } from "../internal/route-execution.ts"
 import { isSameOriginRequest } from "../internal/same-origin.ts"
-import type { RequestLedger } from "../ledger.ts"
 import { compileRoutePattern, decodeRouteParams } from "../router/pattern.ts"
 import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
 import type {
@@ -50,9 +49,15 @@ import type {
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import { assertByteLimit, parseContentLength } from "./body.ts"
+import { assertByteLimit, markTransportCap, markTrustedBodyFraming } from "./body.ts"
 import { type ClientIpTrust, resolveClientIp } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
+import {
+  hasLowercaseHeaderKeysMark,
+  headerKeysAllLowercase,
+  markLowercaseHeaderKeys,
+} from "./header-case.ts"
+import { headerObjectOf } from "./headers.ts"
 import { jsonError, pathnameOf, type UrlParts, urlPartsOf } from "./http.ts"
 import { type NodeServeOutcome, withStaticNodeHeaders } from "./node-outcome.ts"
 import {
@@ -81,15 +86,14 @@ import {
   fusedRespond,
   fusedRespondNoSet,
   knownMutableHeaders,
-  markTaggedResponse,
   rememberMutableHeaders,
   taggedResponseBody,
-  taggedResponseOwner,
   toResponse,
 } from "./respond.ts"
 // Type-only: erased, so the kernel never pulls the lane's implementation into a bundle that does not
 // install the plugin. The value side arrives through the symbol-keyed install seam.
 import type { ResponseContractRuntime } from "./response-contract-lane.ts"
+import { applyBodyReplacement, withReplacedBody } from "./response-hooks.ts"
 import {
   CONTEXT_SEARCH,
   CONTEXT_SET,
@@ -116,56 +120,6 @@ export type {
   ResponseHeadersView,
 }
 
-function isBodylessStatus(status: number): boolean {
-  return status === 204 || status === 205 || status === 304
-}
-
-/** Apply a body hook's return to the native response context (bytes, or a structured replacement). */
-function applyBodyReplacement(
-  response: NodeResponseContext,
-  replaced: string | Uint8Array | ResponseBodyReplacement | undefined,
-): void {
-  if (replaced === undefined) return
-  if (typeof replaced === "string" || replaced instanceof Uint8Array) {
-    response.body = isBodylessStatus(response.status) ? null : replaced
-    return
-  }
-  if (replaced.body !== undefined) response.body = replaced.body
-  if (replaced.status !== undefined) response.status = replaced.status
-  if (isBodylessStatus(response.status)) response.body = null
-}
-
-/** Swap a tagged Response's body for a hook's replacement, re-tagging so later body hooks (and the
- * Node fallback's direct writer) see the new bytes; explicit lengths are dropped so framing is
- * re-derived from what actually ships. */
-function withReplacedBody(
-  response: Response,
-  replaced: string | Uint8Array | ResponseBodyReplacement | undefined,
-): Response {
-  if (replaced === undefined) return response
-  const originalBody = taggedResponseBody(response)
-  let body: string | Uint8Array | null
-  let status = response.status
-  if (typeof replaced === "string" || replaced instanceof Uint8Array) {
-    body = replaced
-  } else {
-    body = replaced.body !== undefined ? replaced.body : (originalBody ?? null)
-    if (replaced.status !== undefined) status = replaced.status
-    if (body === (originalBody ?? null) && status === response.status) {
-      return response
-    }
-  }
-  if (isBodylessStatus(status)) body = null
-  const headers = new Headers(response.headers)
-  headers.delete("content-length")
-  const next = new Response(body as ConstructorParameters<typeof Response>[0], {
-    status,
-    headers,
-  })
-  if (body !== null) markTaggedResponse(next, body, taggedResponseOwner(response))
-  return next
-}
-
 const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
 const GUARDED_RESPONSE_HEADERS = new WeakSet<Headers>()
 
@@ -269,7 +223,7 @@ import {
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "./ledger-lane.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
 import type { McpRuntime } from "./mcp-hook.ts"
-import type { IdentityPlugin } from "./plugin.ts"
+import type { ContextPlugin, IdentityPlugin } from "./plugin.ts"
 import type {
   AddRoute,
   EmptyRegistry,
@@ -281,15 +235,18 @@ import type {
 import type {
   AdmissionController,
   AdmissionDecision,
+  FetchHandler,
   McpPromptDescriptor,
   McpResourceDescriptor,
   Middleware,
+  MountFetchOptions,
   PromptArgument,
   PromptMessage,
   ResponseFinalization,
   RouteDescriptor,
   RunningServer,
   ServerOptions,
+  StopHook,
   ToolAnnotations,
 } from "./server-types.ts"
 import type { SSEInit, TypedSSEStream } from "./sse.ts"
@@ -323,6 +280,8 @@ export interface RequestSource {
   readonly body: ReadableStream<Uint8Array> | null
   arrayBuffer(): Promise<ArrayBuffer>
   json(): Promise<unknown>
+  /** Optional runtime-native exact-byte reader (Bun's Request.bytes, when available). */
+  bytes?(): Promise<Uint8Array>
   /** Present only when materializing a `Request` is non-trivial (the Node lazy source); for a real
    * `Request` passed as the source it's absent and {@link requestOf} returns the source itself. */
   readonly request?: Request
@@ -352,6 +311,7 @@ export interface RawContext {
   // Writable: the lifecycle replaces it with the validated/coerced value when a `params` schema is
   // declared (handlers still see it `readonly` via the public `Context` interface).
   params: Record<string, string>
+  headers: Record<string, string>
   query: unknown
   readonly cookies: Readonly<Record<string, string>>
   body: unknown
@@ -386,6 +346,14 @@ interface BunUpgradeServer {
   requestIP(request: Request): { readonly address: string } | null
 }
 
+type MountedFetchHandler = (request: Request, platform?: Platform) => MaybePromise<Response>
+
+interface FetchMount {
+  readonly path: string
+  readonly handler: MountedFetchHandler
+  readonly stripPrefix: boolean
+}
+
 /** The socket peer Bun observed, as a `Platform` for the request lifecycle (`undefined` if unknown).
  * Typed structurally on `requestIP` alone so any Bun `Server` (WS or not) satisfies it. */
 function bunPeerPlatform(
@@ -470,15 +438,18 @@ export type Handler<
 export type {
   AdmissionController,
   AdmissionDecision,
+  FetchHandler,
   McpPromptDescriptor,
   McpResourceDescriptor,
   Middleware,
+  MountFetchOptions,
   PromptArgument,
   PromptMessage,
   ResponseFinalization,
   RouteDescriptor,
   RunningServer,
   ServerOptions,
+  StopHook,
   ToolAnnotations,
 }
 
@@ -490,16 +461,21 @@ export type AnyServer = Server<any, any>
 // Plugin definers + their types now live in `./plugin.ts`; re-exported here so `.use()` callers and
 // existing importers keep resolving them from the server module.
 export {
+  type ContextPlugin,
+  type DefinePluginResult,
+  defineContextPlugin,
   defineIdentityPlugin,
   definePlugin,
   defineRouterPlugin,
   type NifraPlugin,
+  type PluginTypeCollapsed,
 } from "./plugin.ts"
 export type { IdentityPlugin }
 
 const DEFAULT_MAX_BODY_BYTES = 1_000_000
 const DEFAULT_DRAIN_MS = 10_000
 const DRAIN_POLL_MS = 10
+const STOP_HOOK_TIMEOUT_MS = 5_000
 
 /** Same-origin check for a WebSocket handshake (CSWSH default). {@link isSameOriginRequest} is the one
  * owner, shared with the server-function mount in `@nifrajs/web` - the two used to answer differently
@@ -528,6 +504,32 @@ function hasReplacementParam(params: Record<string, string>): boolean {
   return false
 }
 
+function normalizeMountPrefix(path: string): string {
+  if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+    throw new TypeError("mountFetch path must be an absolute pathname without a query or hash")
+  }
+  const withoutWildcard = path.endsWith("/*") ? path.slice(0, -2) : path
+  if (withoutWildcard.includes("*") || withoutWildcard.includes(":")) {
+    throw new TypeError("mountFetch path must be a literal prefix, optionally ending in /*")
+  }
+  if (withoutWildcard.length === 0) return "/"
+  return withoutWildcard.length > 1 && withoutWildcard.endsWith("/")
+    ? withoutWildcard.slice(0, -1)
+    : withoutWildcard
+}
+
+function underMountPrefix(pathname: string, prefix: string): boolean {
+  return prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`)
+}
+
+function stripMountPrefix(request: Request, prefix: string): Request {
+  if (prefix === "/") return request
+  const url = new URL(request.url)
+  const rest = url.pathname.slice(prefix.length)
+  url.pathname = rest === "" ? "/" : rest
+  return new Request(url.href, request)
+}
+
 /** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
  * anything when no handler touched `c.set.*`. Server-internal. */
 export type CtxSet = ResponseControls & {
@@ -549,6 +551,17 @@ function isContextlessNoArgArrow(handler: (context: never) => unknown): boolean
   }
 }
 
+/** `major.minor` of a full version literal - patch releases never change the typed surface. */
+type FeatureVersionOf<V extends string> = V extends `${infer Major}.${infer Minor}.${string}`
+  ? `${Major}.${Minor}`
+  : V
+
+/**
+ * The feature version of the `@nifrajs/core` copy that declared these types, derived from the single
+ * `VERSION` literal (type-only import - erased, so no runtime cycle with the package root).
+ */
+export type NifraFeatureVersion = FeatureVersionOf<Version>
+
 // Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
 const IDENTITY_RESPONSE = (response: Response): Response => response
 const RESPONSE_TIMEOUT = (): Response => jsonError(503, "request_timeout")
@@ -562,6 +575,16 @@ const RESPONSE_TIMEOUT = (): Response => jsonError(503, "request_timeout")
  *      .get("/me", (c) => c.user)            // c.user + c.db are typed
  */
 export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
+  /**
+   * Which copy of `@nifrajs/core` declared this type. Two copies in one build (a linked sibling repo,
+   * a hoisting split) produce two unrelated `Server` types whose assignment error is a wall of
+   * missing internals; the brand puts the feature version in the type itself, so `typeof app` on
+   * hover - and `NifraFeatureVersion` in an assertion - says which core an app is talking to.
+   * `nifra doctor` is the diagnosis that names both install paths.
+   *
+   * `declare` = type-only: no field is emitted, nothing is allocated per server.
+   */
+  declare readonly __nifraCoreVersion: NifraFeatureVersion
   private readonly catalog: RouteCatalog
   /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
   private readonly wsRouter: Router<WsEntry>
@@ -571,6 +594,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * no-WebSocket app never constructs (or bundles) it. */
   private topics: TopicRegistry | undefined
   private readonly maxBodyBytes: number
+  private readonly protoPoisoning: "reject" | "strip" | "ignore"
+  /** `trustBodyFraming`: mark every `app.fetch` request as runtime-framed (see ServerOptions). */
+  private readonly trustBodyFraming: boolean
   private readonly wsMaxPayloadBytes: number
   private readonly requestTimeoutMs: number
   /** Installed by the `responseContract()` plugin; `undefined` = not installed, which is the default
@@ -582,6 +608,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly maxInboundDeadlineMs: number
   private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
   private readonly gracefulSignals: boolean
+  private readonly stopHooks: StopHook[]
+  private readonly fetchMounts: FetchMount[]
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
   private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
@@ -602,6 +630,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Installed WebSocket runtime for `.ws()` routes; `undefined` until `.use(websocket())`. */
   private wsRuntime: WsRuntime | undefined
   private readonly logger: Logger
+  /** How much of an unhandled error {@link logRequestError} records. See `ServerOptions.errorLogDetail`. */
+  private readonly errorLogDetail: "full" | "message" | "none"
   /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
   private readonly defaultOnValidationError?: RouteSchema["onValidationError"]
   private bunServer: RunningServer | undefined
@@ -620,6 +650,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly onNodeResponseHooks: Array<NodeResponseHook | undefined>
   /** Registration-time eligibility for the Node response twin lane. */
   private nodeResponseHooksComplete: boolean
+  /**
+   * True once a bundle registers a RAW `onNodeResponse` twin - one handed the outcome's header
+   * record itself rather than the case-normalizing view. Their names are contractually the wire
+   * spelling, but registration cannot PROVE it, so such an app forgoes the all-lowercase mark and
+   * every reader re-derives the answer, exactly as before the mark existed.
+   */
+  private hasRawNodeResponseHook: boolean
   private readonly onResponseFinalizedHooks: RawOnResponseFinalized[]
   /**
    * Statically declared response headers, merged and prebuilt at registration; `undefined` (the
@@ -658,6 +695,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.topics = undefined
     const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
     assertByteLimit(maxBodyBytes, "maxBodyBytes")
+    this.protoPoisoning = options.protoPoisoning ?? "reject"
+    this.trustBodyFraming = options.trustBodyFraming ?? false
     const wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? maxBodyBytes
     assertByteLimit(wsMaxPayloadBytes, "wsMaxPayloadBytes")
     this.maxBodyBytes = maxBodyBytes
@@ -677,6 +716,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       throw new RangeError("maxInboundDeadlineMs must be a finite positive number")
     }
     this.gracefulSignals = options.gracefulSignals ?? false
+    this.stopHooks = []
+    this.fetchMounts = []
     this.capacityGate = options.admission
     this.onCapabilityUse = options.onCapabilityUse
     this.capabilityInterceptors = []
@@ -689,6 +730,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.responseContractRuntime = undefined
     this.idempotencyRuntime = undefined
     this.logger = options.logger ?? jsonLogger()
+    this.errorLogDetail = options.errorLogDetail ?? "full"
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
     this.sealed = false
@@ -704,6 +746,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.onResponseHooks = []
     this.onNodeResponseHooks = []
     this.nodeResponseHooksComplete = true
+    this.hasRawNodeResponseHook = false
     this.onResponseFinalizedHooks = []
     this.staticResponseHeaders = undefined
     this.wrapWebResponse = IDENTITY_RESPONSE
@@ -729,6 +772,36 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
   }
 
+  /** Register a callback awaited after graceful drain and server stop. Hung callbacks are bounded. */
+  onStop(fn: StopHook): this {
+    this.assertConfigurable("onStop()")
+    if (typeof fn !== "function") throw new TypeError("onStop callback must be a function")
+    this.stopHooks.push(fn)
+    return this
+  }
+
+  /**
+   * Mount a legacy fetch handler under a literal path prefix. Mounted handlers sit behind typed
+   * routes, so routes can move one at a time while the remaining legacy surface stays live.
+   * Mounted responses are outside Nifra's typed route and response-contract checks.
+   */
+  mountFetch(
+    path: string,
+    handler: FetchHandler<EnvOf<Ctx>>,
+    options: MountFetchOptions = {},
+  ): this {
+    this.assertConfigurable("mountFetch()")
+    if (typeof handler !== "function") throw new TypeError("mountFetch handler must be a function")
+    const mount: FetchMount = {
+      path: normalizeMountPrefix(path),
+      handler: handler as MountedFetchHandler,
+      stripPrefix: options.stripPrefix === true,
+    }
+    this.fetchMounts.push(mount)
+    this.fetchMounts.sort((a, b) => b.path.length - a.path.length)
+    return this
+  }
+
   /** Add a per-request, computed context extension for subsequent routes. */
   derive<D extends object>(fn: (context: Context & Ctx) => MaybePromise<D>): Server<R, Ctx & D> {
     this.assertConfigurable("derive()")
@@ -963,6 +1036,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * defeat the generic inference of the transforming overload below and collapse the result to `any`.
    */
   use(plugin: IdentityPlugin): this
+  /**
+   * Apply a **context** plugin ({@link ContextPlugin}, from {@link defineContextPlugin}) - it adds `D`
+   * to the handler context and changes nothing else, so the route registry `R` and the existing context
+   * `Ctx` thread through untouched. Like the identity overload above, this exists because the generic
+   * `(app: this) => Out` overload below cannot infer through a *generic* plugin signature: it erases the
+   * plugin's own type parameters to their constraints, which silently widens `R` to `Registry`.
+   */
+  use<D extends object>(plugin: ContextPlugin<D>): Server<R, Ctx & D>
   /**
    * Apply a **plugin function** - `(app) => app`, typically built with {@link definePlugin}. It's
    * called with `this` and its result is returned, so an inline plugin's `derive`/`decorate` thread
@@ -1027,6 +1108,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       this.onResponseHooks.push(arg.onResponse)
       this.onNodeResponseHooks.push(arg.onNodeResponse)
       if (arg.onNodeResponse === undefined) this.nodeResponseHooksComplete = false
+      else this.hasRawNodeResponseHook = true
     } else if (arg.onNodeResponse !== undefined) {
       throw new TypeError("onNodeResponse() requires a paired onResponse() hook")
     }
@@ -1383,6 +1465,29 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     handler: (context: never) => unknown,
   ): CatalogRoute {
     const pattern = compileRoutePattern(path)
+    let bodyLimit: number | undefined = this.maxBodyBytes
+    const invalidBodyLimit = (message: string): never => {
+      throw new RouteConfigError("INVALID_BODY_LIMIT", `route ${method} ${path}: ${message}`)
+    }
+    if (schema?.bodyLimitReason !== undefined && schema.bodyLimit !== "unlimited") {
+      invalidBodyLimit('bodyLimitReason is only valid with bodyLimit: "unlimited"')
+    }
+    if (schema?.bodyLimit === "unlimited") {
+      if (
+        typeof schema.bodyLimitReason !== "string" ||
+        schema.bodyLimitReason.trim().length === 0
+      ) {
+        invalidBodyLimit('bodyLimit: "unlimited" requires a non-empty bodyLimitReason')
+      }
+      bodyLimit = undefined
+    } else if (schema?.bodyLimit !== undefined) {
+      try {
+        assertByteLimit(schema.bodyLimit, "route bodyLimit")
+      } catch {
+        invalidBodyLimit('bodyLimit must be a non-negative safe integer or "unlimited"')
+      }
+      bodyLimit = schema.bodyLimit
+    }
     const capabilities = normalizeRouteCapabilities(schema?.capabilities)
     const handlerAssurance = assuranceDeclarationsOf(handler as unknown as object)
     const invalidHandlerScope = handlerAssurance.find(
@@ -1444,6 +1549,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         : undefined
     const bare =
       schema?.params === undefined &&
+      schema?.headers === undefined &&
       schema?.body === undefined &&
       schema?.query === undefined &&
       idempotent === undefined &&
@@ -1465,6 +1571,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       schema?.query !== undefined &&
       schema.body === undefined &&
       schema.params === undefined &&
+      schema.headers === undefined &&
       schema.onValidationError === undefined &&
       this.defaultOnValidationError === undefined &&
       idempotent === undefined &&
@@ -1479,6 +1586,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       schema?.body !== undefined &&
       schema.query === undefined &&
       schema.params === undefined &&
+      schema.headers === undefined &&
       this.derives.length === 0 &&
       this.beforeHandleHooks.length === 0 &&
       this.afterHandleHooks.length === 0 &&
@@ -1499,6 +1607,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           handler as unknown as InternalHandler,
           schema.body as StandardSchemaV1,
           hasDecorations ? routeDecorations : undefined,
+          bodyLimit ?? this.maxBodyBytes,
         )
       : undefined
     const fusedWeb =
@@ -1507,12 +1616,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             handler as unknown as InternalHandler,
             hasDecorations ? routeDecorations : undefined,
             isContextlessNoArgArrow(handler),
+            bodyLimit ?? this.maxBodyBytes,
           )
         : fusedQuery
           ? this.buildFusedQueryWeb(
               handler as unknown as InternalHandler,
               hasDecorations ? routeDecorations : undefined,
               schema.query as StandardSchemaV1,
+              bodyLimit ?? this.maxBodyBytes,
             )
           : fusedBody
             ? this.buildFusedBodyWeb(fusedBodyRunner as FusedBodyRunner)
@@ -1528,6 +1639,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             schema?.body === undefined &&
             schema?.query !== undefined &&
             schema.params === undefined &&
+            schema.headers === undefined &&
             this.derives.length === 0 &&
             this.beforeHandleHooks.length === 0 &&
             this.afterHandleHooks.length === 0 &&
@@ -1539,7 +1651,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // so the request path never re-checks params/body presence. Parameter-schema routes retain the
     // generic lifecycle runner until their more involved recovery matrix is selected explicitly.
     const lifecycleLane =
-      lane !== "lifecycle" || schema?.params !== undefined
+      lane !== "lifecycle" || schema?.params !== undefined || schema?.headers !== undefined
         ? undefined
         : schema?.body !== undefined
           ? schema.query !== undefined
@@ -1562,21 +1674,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       this.onErrorHooks.length === 0
         ? "derive-before"
         : undefined
-    const execution = this.compileExecutionPlan(
+    const execution = compileRouteExecutionPlan({
       lane,
       contextless,
-      this.aroundHooks.length > 0,
-      ledgered !== undefined,
+      hasAround: this.aroundHooks.length > 0,
+      hasLedger: ledgered !== undefined,
       lifecycleLane,
       fusedWeb,
-      fusedBodyRunner,
-      fusedWeb === undefined ? undefined : fusedQuery ? "query" : fusedBody ? "body" : "bare",
-    )
+      fusedBody: fusedBodyRunner,
+      fusedLane:
+        fusedWeb === undefined ? undefined : fusedQuery ? "query" : fusedBody ? "body" : "bare",
+    })
     const registeredEntry: RouteEntry = {
       // (context: never) => unknown -> InternalHandler: the framework invokes it
       // with the concrete RawContext the typed handler expects, so this is sound.
       handler: handler as unknown as InternalHandler,
       schema,
+      bodyLimit,
       idempotent,
       ledgered,
       responseContract: contracted,
@@ -1598,6 +1712,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       ...(schema?.family === true ? { family: true } : {}),
     }
     const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance, ...handlerAssurance]
+    if (contracted?.runtime.mode === "enforce" && schema?.response !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
+          source: "response-contract",
+          scope: "plugin",
+        }),
+      )
+    }
     // Inline `schema.assurance`: the route DECLARES its enforcement evidence adjacent to the handler, so an
     // in-handler-guarded route satisfies a policy `require:` clause without a `withRouteAssurance` middleware
     // rewrite. Each id becomes route-scoped `declared` evidence (invalid ids fail closed at registration).
@@ -1607,7 +1730,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           `route assurance: invalid evidence id ${JSON.stringify(id)} on ${method} ${path} (use lowercase dot/dash segments)`,
         )
       }
-      routeAssurance.push(Object.freeze({ id, source: "declared", scope: "plugin" }))
+      const declared = { id, source: "declared", scope: "plugin" } as AssuranceDeclaration
+      Object.defineProperty(declared, "provenance", {
+        value: "declared",
+        enumerable: false,
+        configurable: false,
+        writable: false,
+      })
+      routeAssurance.push(Object.freeze(declared))
     }
     if (schema?.body !== undefined) {
       routeAssurance.push(
@@ -1639,132 +1769,6 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
   }
 
-  /** Collapse route-invariant lifecycle decisions into one runner at registration. The request path
-   * performs no eligibility ladder: it supplies request state to this already-selected plan. */
-  private compileExecutionPlan(
-    lane: "bare" | "body" | "query" | "lifecycle",
-    contextless: boolean,
-    hasAround: boolean,
-    hasLedger: boolean,
-    lifecycleLane: "hooks" | "query" | "body" | "body-query" | undefined,
-    fusedWeb: FusedWebRunner | undefined,
-    fusedBody: FusedBodyRunner | undefined,
-    fusedLane: "bare" | "body" | "query" | undefined,
-  ): RouteExecutionPlan {
-    if (contextless) {
-      const run: RouteExecutionRunner = (
-        runtime,
-        entry,
-        source,
-        params,
-        search,
-        signal,
-        budget,
-        platform,
-        _nativeContext,
-        finalize,
-        wrapResponse,
-      ) =>
-        runtime.runContextlessBare(
-          entry,
-          source,
-          params,
-          search,
-          signal,
-          budget,
-          platform,
-          finalize,
-          wrapResponse,
-        )
-      return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
-    }
-
-    let inner: ContextRouteRunner
-    switch (lane) {
-      case "bare":
-        inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-          runtime.runBare(entry, ctx, finalize, wrapResponse)
-        break
-      case "body":
-        inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-          runtime.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
-        break
-      case "query":
-        inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-          runtime.runQueryOnly(entry, ctx, finalize, wrapResponse)
-        break
-      default:
-        switch (lifecycleLane) {
-          case "hooks":
-            inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-              runtime.runLifecycleHooks(entry, ctx, finalize, wrapResponse)
-            break
-          case "query":
-            inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-              runtime.runLifecycleQuery(entry, ctx, finalize, wrapResponse)
-            break
-          case "body":
-            inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-              runtime.runLifecycleBody(entry, source, ctx, finalize, wrapResponse)
-            break
-          case "body-query":
-            inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-              runtime.runLifecycleBodyQuery(entry, source, ctx, finalize, wrapResponse)
-            break
-          default:
-            inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-              runtime.runLifecycle(entry, source, ctx, finalize, wrapResponse)
-        }
-    }
-    const execute: ContextRouteRunner = hasAround
-      ? (runtime, entry, source, ctx, finalize, wrapResponse) =>
-          runtime.runWithAround(
-            entry,
-            ctx,
-            () => inner(runtime, entry, source, ctx, finalize, wrapResponse),
-            finalize,
-            wrapResponse,
-          )
-      : inner
-    const run: RouteExecutionRunner = (
-      runtime,
-      entry,
-      source,
-      params,
-      search,
-      signal,
-      budget,
-      platform,
-      nativeContext,
-      finalize,
-      wrapResponse,
-    ) => {
-      const ctx = nativeContext
-        ? RequestContext.native(source, params, search, runtime.maxBodyBytes, platform)
-        : new RequestContext(source, params, search, signal, budget, platform, runtime.maxBodyBytes)
-      let ledger: RequestLedger | undefined
-      // The runtime is always present when a route resolved a ledger (enforced at registration).
-      const ledgerRuntime = runtime.effectLedgerRuntime
-      if (hasLedger && ledgerRuntime !== undefined) {
-        const resolved = entry.ledgered as ResolvedEffectLedger
-        ledger = ledgerRuntime.create(resolved)
-        ledgerRuntime.attach(ctx, ledger)
-      }
-      let outcome = execute(runtime, entry, source, ctx, finalize, wrapResponse)
-      if (ledger !== undefined && ledgerRuntime !== undefined) {
-        const active = ledger
-        const resolved = entry.ledgered as ResolvedEffectLedger
-        outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) =>
-          ledgerRuntime.settle(active, resolved, value, (fields) =>
-            runtime.logger.error("effect ledger sink failed", fields),
-          ),
-        )
-      }
-      return outcome
-    }
-    return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
-  }
-
   /** The idempotency lane's bridge back into the normal matched lanes, resolved to a concrete Response
    * (the lane buffers the body, then replays it through the route's real validation + handler). */
   private idempotencyRunLanes(
@@ -1837,10 +1841,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    *
    * Semantics: merged routes keep the chains captured where they were DEFINED - the group's
    * `derive`/`decorate`/`beforeHandle`/`afterHandle`/`onError`/`around` apply to its routes
-   * exactly as they did standalone, so a group wires its own plugins. The group's request-level
-   * hooks (`onRequest`/`onResponse`/`onResponseFinalized`) are appended to this server's. This
-   * server's route-scoped chains do NOT retroactively wrap merged routes (order-scoped, like
-   * routes registered before a `derive`). Fail closed: a path+method collision throws
+   * exactly as they did standalone, so a group wires its own plugins. The same locality rule
+   * covers the group's `onRequest` hooks: they run only for requests that route to the GROUP's
+   * routes (a `bodyLimit()` mounted on an uploads group must not start gating the whole app
+   * because the app composed it in), and the group's global assurance follows its hooks onto
+   * exactly those routes. A group with hooks but NO routes is a middleware bundle - its hooks
+   * can only mean app-wide intent, so they are appended globally, unchanged. Response-side hooks
+   * (`onResponse`/`onResponseFinalized`) are appended to this server's. This server's
+   * route-scoped chains do NOT retroactively wrap merged routes (order-scoped, like routes
+   * registered before a `derive`). Fail closed: a path+method collision throws
    * `RouteConfigError` at merge time, and a group with WebSocket routes is refused (register
    * those on the parent).
    */
@@ -1853,7 +1862,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         "merge() does not carry WebSocket routes - register .ws() routes on the parent server",
       )
     }
-    this.catalog.addBatch(source.catalog.entries().map((route) => this.bindFusedRuntime(route)))
+    const sourceRoutes = source.catalog.entries()
+    // Hooks and global assurance stay LOCAL to a group that has routes; a route-less group is a
+    // middleware bundle whose hooks can only mean app-wide intent, so it keeps the global append.
+    const scoped = sourceRoutes.length > 0
+    // A group's global assurance rides its (route-scoped) hooks: folded into each merged route's
+    // own evidence rather than the parent's global list, so `routes()` never claims the group's
+    // enforcement for parent routes the group's hooks do not see.
+    const foldedAssurance =
+      scoped && source.globalAssurance.length > 0
+        ? (route: CatalogRoute): CatalogRoute => ({
+            ...route,
+            assurance: [...route.assurance, ...source.globalAssurance],
+          })
+        : (route: CatalogRoute): CatalogRoute => route
+    this.catalog.addBatch(
+      sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(route))),
+    )
     // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
     // runtime object supplies the generic execution machinery. Preserve a group's installed runtime
     // when the parent has none so merging cannot silently disable a safety lane. If the parent already
@@ -1866,8 +1891,33 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.nodeOutcomeRuntime ??= source.nodeOutcomeRuntime
     this.sseRuntime ??= source.sseRuntime
     this.wsRuntime ??= source.wsRuntime
-    this.onRequestHooks.push(...source.onRequestHooks)
-    this.onNodeRequestHooks.push(...source.onNodeRequestHooks)
+    if (scoped && source.onRequestHooks.length > 0) {
+      // Snapshot the group's routes into a dedicated matcher: the guard must reflect what was
+      // MERGED, not whatever the group's own catalog grows into afterwards. One probe against it
+      // gates each group hook to requests the group would serve; everything else passes untouched.
+      const scope = new RouteCatalog()
+      scope.addBatch(sourceRoutes)
+      this.onRequestHooks.push(
+        ...source.onRequestHooks.map(
+          (hook): RawOnRequest =>
+            (req, platform) =>
+              scope.find(req.method, pathnameOf(req.url)).found ? hook(req, platform) : undefined,
+        ),
+      )
+      // An `undefined` slot marks an unpaired hook (position-aligned with `onRequestHooks`) and
+      // must stay `undefined` - wrapping it would fabricate a Node twin that never existed.
+      this.onNodeRequestHooks.push(
+        ...source.onNodeRequestHooks.map((hook): NodeRequestHook | undefined =>
+          hook === undefined
+            ? undefined
+            : (req, platform) =>
+                scope.find(req.method, pathnameOf(req.url)).found ? hook(req, platform) : undefined,
+        ),
+      )
+    } else {
+      this.onRequestHooks.push(...source.onRequestHooks)
+      this.onNodeRequestHooks.push(...source.onNodeRequestHooks)
+    }
     this.nodeRequestHooksComplete &&= source.nodeRequestHooksComplete
     // The group's static declarations came before its own response hooks, so they are folded in
     // first - and fold themselves into a hook here if this server already has one (same ordering
@@ -1878,13 +1928,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.onResponseHooks.push(...source.onResponseHooks)
     this.onNodeResponseHooks.push(...source.onNodeResponseHooks)
     this.nodeResponseHooksComplete &&= source.nodeResponseHooksComplete
+    this.hasRawNodeResponseHook ||= source.hasRawNodeResponseHook
     this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks)
     if (source.responseBodyTag !== undefined) {
       const owner = this.enableResponseBodyTagging()
       this.responseBodyOwners.add(source.responseBodyTag)
       source.responseBodyOwners.add(owner)
     }
-    this.globalAssurance.push(...source.globalAssurance)
+    if (!scoped) this.globalAssurance.push(...source.globalAssurance)
     this.mcpResourceList.push(...source.mcpResourceList)
     this.mcpPromptList.push(...source.mcpPromptList)
     return this as unknown as Server<R & R2, Ctx>
@@ -1903,6 +1954,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             entry.handler,
             entry.schema?.body as StandardSchemaV1,
             entry.hasDecorations ? entry.decorations : undefined,
+            entry.bodyLimit ?? this.maxBodyBytes,
           )
         : undefined
     const fusedWeb =
@@ -1913,11 +1965,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
               entry.handler,
               entry.hasDecorations ? entry.decorations : undefined,
               entry.schema?.query as StandardSchemaV1,
+              entry.bodyLimit ?? this.maxBodyBytes,
             )
           : this.buildFusedWeb(
               entry.handler,
               entry.hasDecorations ? entry.decorations : undefined,
               isContextlessNoArgArrow(entry.handler),
+              entry.bodyLimit ?? this.maxBodyBytes,
             )
     return {
       ...route,
@@ -1951,6 +2005,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).
    */
   fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response> {
+    // An edge deployment whose only ingress is this method declares its requests runtime-framed at
+    // construction; everything else stays on the delivered-byte check (see `trustBodyFraming`).
+    if (this.trustBodyFraming) markTrustedBodyFraming(req)
     // A real `Request` satisfies `RequestSource`, so it's passed straight through - no per-request
     // wrapper allocation on the Web/Bun hot path.
     return this.fetchSource(req, platform)
@@ -2126,12 +2183,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // header or body hook reads them through its view), and on the no-hook path too (which returns
     // the outcome straight to the writer without the finish step below).
     const statics = this.staticResponseHeaders
+    // The fold also publishes the all-lowercase proof, which is why it is worth doing here rather
+    // than in the finish step: it is the only stage the HOOKLESS lane passes through, and that lane
+    // returns straight to the writer below without ever reaching `finishNodeResponse`.
+    const markLowercase = !this.hasRawNodeResponseHook
     const outcome =
       statics === undefined
         ? resolved
         : resolved instanceof Promise
-          ? resolved.then((settled) => withStaticNodeHeaders(settled, statics))
-          : withStaticNodeHeaders(resolved, statics)
+          ? resolved.then((settled) => withStaticNodeHeaders(settled, statics, markLowercase))
+          : withStaticNodeHeaders(resolved, statics, markLowercase)
     if (webResponseHooks) {
       return outcome instanceof Promise
         ? outcome.then((settled) => this.finishNodeWebResponse(settled, source, runtime))
@@ -2182,13 +2243,24 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
 
     let headers = outcome.headers as Record<string, string | readonly string[]> | undefined
+    // ONE pass over the names, here, before any twin runs. The same question is asked three times per
+    // request downstream - the Content-Type lookup just below, the header view's alias index, and the
+    // `@nifrajs/node` writer's normalization gate - and each used to walk the record itself. An app
+    // declaring static headers has already had it answered by the fold in `resolveNode`, for free, so
+    // the pass runs only for the records nothing looked at yet.
+    const lowercaseKeys =
+      headers === undefined ||
+      hasLowercaseHeaderKeysMark(headers) ||
+      headerKeysAllLowercase(headers)
     if (outcome.kind === "json" && outcome.body !== null) {
       // The json render adds its Content-Type at WRITE time, so a body hook checking content types
       // would see nothing. Materialize the writer's own value into the hook-visible record - same
       // string the writer would emit, so the wire is unchanged.
       const hasType =
         headers !== undefined &&
-        Object.keys(headers).some((key) => key.toLowerCase() === "content-type")
+        (lowercaseKeys
+          ? headers["content-type"] !== undefined
+          : Object.keys(headers).some((key) => key.toLowerCase() === "content-type"))
       if (!hasType) {
         const defaultContentType = runtime.jsonContentType ?? "application/json;charset=utf-8"
         if (headers === undefined) {
@@ -2202,6 +2274,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         }
       }
     }
+    // Publish the proof for the view and the direct writer - but only for an app whose every twin
+    // normalizes case. A raw `onNodeResponse` twin writes the record straight, past the view, so a
+    // mark set before it ran could be made to lie, and a lying mark would ship a mixed-case name that
+    // `Headers` lowercases on every other runtime. Those apps keep the per-reader scans.
+    if (lowercaseKeys && headers !== undefined && !this.hasRawNodeResponseHook) {
+      markLowercaseHeaderKeys(headers)
+    }
     const context: NodeResponseContext = {
       status: outcome.status,
       headers,
@@ -2336,7 +2415,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       return { kind: "reject", response: jsonError(403, "forbidden_origin") }
     }
     if (handler.upgrade === undefined) {
-      return { kind: "upgrade", handler, data: undefined, pubsub, attach }
+      return {
+        kind: "upgrade",
+        handler,
+        data: undefined,
+        pubsub,
+        attach,
+        maxPayloadBytes: this.wsMaxPayloadBytes,
+      }
     }
     const upgradeSignal = getNeverAbortSignal()
     const ctx = new RequestContext(
@@ -2347,11 +2433,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       createUnboundedRequestBudget(upgradeSignal),
       platform,
       this.maxBodyBytes,
+      this.protoPoisoning,
     )
     const settle = (value: unknown): WebSocketUpgradeOutcome =>
       value instanceof Response
         ? { kind: "reject", response: value }
-        : { kind: "upgrade", handler, data: value, pubsub, attach }
+        : {
+            kind: "upgrade",
+            handler,
+            data: value,
+            pubsub,
+            attach,
+            maxPayloadBytes: this.wsMaxPayloadBytes,
+          }
     try {
       const result = handler.upgrade(ctx as unknown as WebSocketContext<EnvOf<Ctx>>)
       return result instanceof Promise
@@ -2680,6 +2774,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
     const match = this.catalog.find(source.method, pathname)
     if (!match.found) {
+      const mounted = this.fetchMount(pathname, source, platform)
+      if (mounted !== undefined) {
+        return mounted instanceof Promise
+          ? mounted.then((response) => wrapResponse(response))
+          : wrapResponse(mounted)
+      }
       if (match.reason === "method-not-allowed") {
         return wrapResponse(
           jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }),
@@ -2708,6 +2808,22 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     )
   }
 
+  private fetchMount(
+    pathname: string,
+    source: RequestSource,
+    platform: Platform | undefined,
+  ): MaybePromise<Response> | undefined {
+    for (const mount of this.fetchMounts) {
+      if (!underMountPrefix(pathname, mount.path)) continue
+      const request = requestOf(source)
+      return mount.handler(
+        mount.stripPrefix ? stripMountPrefix(request, mount.path) : request,
+        platform,
+      )
+    }
+    return undefined
+  }
+
   /** Run a route that has already been matched by the runtime or Nifra's portable router. */
   private runMatched<T>(
     source: RequestSource,
@@ -2720,6 +2836,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     onTimeout: () => T,
     webFast: boolean,
   ): MaybePromise<T> {
+    // The route's transport byte cap: one property write here; the capped shadowing of direct
+    // `c.req` body readers happens lazily at `c.req` access (`applyTransportCap`), so a route that
+    // never direct-reads pays nothing. Framework readers bypass the shadow (`rawBodySourceOf`) and
+    // keep their own caps, so `c.boundedBody(explicit)` still overrides upward.
+    // `bodyLimit: "unlimited"` (undefined here) skips the cap entirely.
+    // A schema route consumes and validates the body through `readBodyInput` before any derive or
+    // handler can reach `c.req`; that lane already enforces `entry.bodyLimit`. Installing the full
+    // direct-reader cap on `c.req` here would allocate bound readers, closures, and a stream wrapper
+    // for a body that is already consumed. Keep the lazy transport cap for raw-body routes, where a
+    // user read is the only framework-owned body boundary.
+    if (entry.bodyLimit !== undefined && entry.schema?.body === undefined) {
+      const method = source.method
+      if (method !== "GET" && method !== "HEAD") markTransportCap(source, entry.bodyLimit)
+    }
     // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
     // (with the body buffered). All non-idempotent routes skip straight to the lanes - no added cost.
     // The runtime is always present when a route resolved idempotency (enforced at registration).
@@ -2733,7 +2863,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         search,
         wrapResponse,
         {
-          maxBodyBytes: this.maxBodyBytes,
+          maxBodyBytes: entry.bodyLimit ?? this.maxBodyBytes,
           runLanes: (buffered, plat, ent, prm, srch) =>
             this.idempotencyRunLanes(buffered, plat, ent as RouteEntry, prm, srch),
         },
@@ -2861,6 +2991,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
 
   /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
    * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runContextlessBare<T>(
     entry: RouteEntry,
     source: RequestSource,
@@ -2925,6 +3057,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       budget,
       platform,
       this.maxBodyBytes,
+      this.protoPoisoning,
     )
     this.logRequestError(err, ctx)
     return wrapResponse(jsonError(500, "internal_error"))
@@ -2938,6 +3071,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * (a thrown `Response` is control flow; anything else is a logged flat 500). This is where nifra skips
    * the per-request async-frame tax - the same win codegen routers get, but without `eval`.
    */
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runBare<T>(
     entry: RouteEntry,
     ctx: RawContext,
@@ -2974,6 +3109,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     handler: InternalHandler,
     decorations: Record<PropertyKey, unknown> | undefined,
     contextless: boolean,
+    maxBodyBytes: number,
   ): FusedWebRunner {
     // The fused lanes return to the runtime directly, so the framework's own error renders fold in
     // static headers here rather than through the shared `wrapResponse` seam.
@@ -2994,7 +3130,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           return logError(
             err,
             nativeContext
-              ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
+              ? RequestContext.native(
+                  source,
+                  params,
+                  search,
+                  maxBodyBytes,
+                  platform,
+                  this.protoPoisoning,
+                )
               : new RequestContext(
                   source,
                   params,
@@ -3002,18 +3145,32 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
                   signal,
                   budget,
                   platform,
-                  this.maxBodyBytes,
+                  maxBodyBytes,
+                  this.protoPoisoning,
                 ),
           )
         }
         if (result instanceof Promise) {
           return result.then(
-            (value) => fusedRespondNoSet(value, this.responseBodyTag, this.staticResponseHeaders),
+            (value) =>
+              fusedRespondNoSet(
+                value,
+                this.responseBodyTag,
+                this.staticResponseHeaders,
+                this.onResponseHooks.length === 0,
+              ),
             (err) =>
               logError(
                 err,
                 nativeContext
-                  ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
+                  ? RequestContext.native(
+                      source,
+                      params,
+                      search,
+                      maxBodyBytes,
+                      platform,
+                      this.protoPoisoning,
+                    )
                   : new RequestContext(
                       source,
                       params,
@@ -3021,18 +3178,33 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
                       signal,
                       budget,
                       platform,
-                      this.maxBodyBytes,
+                      maxBodyBytes,
+                      this.protoPoisoning,
                     ),
               ),
           )
         }
-        return fusedRespondNoSet(result, this.responseBodyTag, this.staticResponseHeaders)
+        return fusedRespondNoSet(
+          result,
+          this.responseBodyTag,
+          this.staticResponseHeaders,
+          this.onResponseHooks.length === 0,
+        )
       }
     }
     return (source, params, search, signal, budget, platform, nativeContext) => {
       const ctx = nativeContext
-        ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
-        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)
+        ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+        : new RequestContext(
+            source,
+            params,
+            search,
+            signal,
+            budget,
+            platform,
+            maxBodyBytes,
+            this.protoPoisoning,
+          )
       if (decorations !== undefined) Object.assign(ctx, decorations)
       let result: unknown
       try {
@@ -3042,11 +3214,24 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       }
       if (result instanceof Promise) {
         return result.then(
-          (value) => fusedRespond(value, ctx, this.responseBodyTag, this.staticResponseHeaders),
+          (value) =>
+            fusedRespond(
+              value,
+              ctx,
+              this.responseBodyTag,
+              this.staticResponseHeaders,
+              this.onResponseHooks.length === 0,
+            ),
           (err) => logError(err, ctx),
         )
       }
-      return fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders)
+      return fusedRespond(
+        result,
+        ctx,
+        this.responseBodyTag,
+        this.staticResponseHeaders,
+        this.onResponseHooks.length === 0,
+      )
     }
   }
 
@@ -3057,6 +3242,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     handler: InternalHandler,
     bodySchema: StandardSchemaV1,
     decorations: Record<PropertyKey, unknown> | undefined,
+    maxBodyBytes: number,
   ): FusedBodyRunner {
     const logError = <T>(
       err: unknown,
@@ -3149,11 +3335,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       wrapResponse: (response: Response) => T,
     ): MaybePromise<T> => {
       const ctx = nativeContext
-        ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
-        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)
+        ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+        : new RequestContext(
+            source,
+            params,
+            search,
+            signal,
+            budget,
+            platform,
+            maxBodyBytes,
+            this.protoPoisoning,
+          )
       const finish = (value: unknown): MaybePromise<T> =>
         runParsed(value, ctx, finalize, wrapResponse)
-      return this.readBodyInput(source, finish, wrapResponse, (err) =>
+      return this.readBodyInput(source, maxBodyBytes, finish, wrapResponse, (err) =>
         logError(err, ctx, wrapResponse),
       )
     }
@@ -3172,7 +3367,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         platform,
         nativeContext,
         (result, _set, ctx) =>
-          fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders),
+          fusedRespond(
+            result,
+            ctx,
+            this.responseBodyTag,
+            this.staticResponseHeaders,
+            this.onResponseHooks.length === 0,
+          ),
         this.wrapWebResponse,
       ) as MaybePromise<Response>
   }
@@ -3188,6 +3389,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     handler: InternalHandler,
     decorations: Record<PropertyKey, unknown> | undefined,
     querySchema: StandardSchemaV1,
+    maxBodyBytes: number,
   ): FusedWebRunner {
     // The fused lanes return to the runtime directly, so the framework's own error renders fold in
     // static headers here rather than through the shared `wrapResponse` seam.
@@ -3206,16 +3408,38 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       }
       if (result instanceof Promise) {
         return result.then(
-          (settled) => fusedRespond(settled, ctx, this.responseBodyTag, this.staticResponseHeaders),
+          (settled) =>
+            fusedRespond(
+              settled,
+              ctx,
+              this.responseBodyTag,
+              this.staticResponseHeaders,
+              this.onResponseHooks.length === 0,
+            ),
           (err) => logError(err, ctx),
         )
       }
-      return fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders)
+      return fusedRespond(
+        result,
+        ctx,
+        this.responseBodyTag,
+        this.staticResponseHeaders,
+        this.onResponseHooks.length === 0,
+      )
     }
     return (source, params, search, signal, budget, platform, nativeContext) => {
       const ctx = nativeContext
-        ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
-        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)
+        ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+        : new RequestContext(
+            source,
+            params,
+            search,
+            signal,
+            budget,
+            platform,
+            maxBodyBytes,
+            this.protoPoisoning,
+          )
       if (decorations !== undefined) Object.assign(ctx, decorations)
       let validation: MaybePromise<StandardResult<unknown>>
       try {
@@ -3244,6 +3468,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return wrapResponse(jsonError(500, "internal_error"))
   }
 
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runWithAround<T>(
     entry: RouteEntry,
     ctx: RawContext,
@@ -3280,6 +3506,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return dispatch(0)
   }
 
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runBodyOnly<T>(
     entry: RouteEntry,
     source: RequestSource,
@@ -3289,6 +3517,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   ): Promise<T> {
     return this.readBodyInput(
       source,
+      entry.bodyLimit ?? this.maxBodyBytes,
       (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse),
       wrapResponse,
       (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse),
@@ -3299,6 +3528,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * the validation + handler continuation differs. */
   private readBodyInput<T>(
     source: RequestSource,
+    maxBodyBytes: number,
     onParsed: (parsed: unknown) => MaybePromise<T>,
     wrapResponse: (response: Response) => T,
     onError: (err: unknown) => MaybePromise<T>,
@@ -3306,7 +3536,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const contentType = headerOf(source, "content-type") ?? ""
     if (contentType !== "application/json" && !contentType.includes("application/json")) {
       if (isUrlEncodedForm(contentType)) {
-        return readBoundedForm(source, this.maxBodyBytes).then(
+        return readBoundedForm(source, maxBodyBytes).then(
           (form) => (form instanceof Response ? wrapResponse(form) : onParsed(form)),
           onError,
         ) as Promise<T>
@@ -3314,24 +3544,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       return Promise.resolve(wrapResponse(jsonError(415, "unsupported_media_type")))
     }
 
-    // A framed, in-cap, non-chunked body can use native json() directly. Chunked or length-less
-    // bodies use readBoundedJson, which enforces the streaming cap before parsing.
-    const declared = headerOf(source, "content-length")
-    if (declared !== null) {
-      const length = parseContentLength(declared)
-      if (length === undefined) {
-        return Promise.resolve(wrapResponse(jsonError(400, "invalid_content_length")))
-      }
-      if (length > this.maxBodyBytes) {
-        return Promise.resolve(wrapResponse(jsonError(413, "payload_too_large")))
-      }
-      if (headerOf(source, "transfer-encoding") === null) {
-        return source.json().then(onParsed, () => wrapResponse(jsonError(400, "invalid_json")))
-      }
-    }
-
+    // All JSON bodies go through readBoundedJson - the single enforcement point for the framed
+    // fast path (post-read byte re-check), the streaming cap, and the prototype-poisoning guard.
+    // A separate inlined native-json() fast path here would fork the trust boundary in two.
     try {
-      return this.readBoundedJson(source).then(
+      return this.readBoundedJson(
+        source,
+        maxBodyBytes,
         (parsed) => (parsed instanceof Response ? wrapResponse(parsed) : onParsed(parsed)),
         onError,
       )
@@ -3487,6 +3706,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this.executeHandler(entry, ctx, finalize)
   }
 
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runQueryOnly<T>(
     entry: RouteEntry,
     ctx: RawContext,
@@ -3693,6 +3914,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * node-direct primitives); an early/error `Response` (validation, thrown, 500) through `wrapResponse`.
    */
   /** Synchronous until a validator, lifecycle hook, handler, or contract check actually returns a Promise. */
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runLifecycle<T>(
     entry: RouteEntry,
     source: RequestSource,
@@ -3701,6 +3924,32 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     wrapResponse: (response: Response) => T,
   ): MaybePromise<T> {
     try {
+      const headersSchema = entry.schema?.headers
+      if (headersSchema !== undefined) {
+        const validation = headersSchema["~standard"].validate(headerObjectOf(source.headers))
+        if (validation instanceof Promise) {
+          return validation.then(
+            (result) =>
+              this.runLifecycleAfterHeadersResult(
+                entry,
+                source,
+                ctx,
+                finalize,
+                wrapResponse,
+                result,
+              ),
+            (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse),
+          )
+        }
+        return this.runLifecycleAfterHeadersResult(
+          entry,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+          validation,
+        )
+      }
       const paramsSchema = entry.schema?.params
       if (paramsSchema !== undefined) {
         const validation = paramsSchema["~standard"].validate(ctx.params)
@@ -3740,6 +3989,64 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
   }
 
+  private runLifecycleAfterHeadersResult<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+    result: StandardResult<unknown>,
+  ): MaybePromise<T> {
+    try {
+      const headersError = this.applyLifecycleValidation(entry, result, ctx, "headers")
+      if (headersError instanceof Promise) {
+        return headersError.then(
+          (error) =>
+            error === undefined
+              ? this.runLifecycleAfterHeaders(entry, source, ctx, finalize, wrapResponse)
+              : wrapResponse(error),
+          (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse),
+        )
+      }
+      return headersError === undefined
+        ? this.runLifecycleAfterHeaders(entry, source, ctx, finalize, wrapResponse)
+        : wrapResponse(headersError)
+    } catch (err) {
+      return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse)
+    }
+  }
+
+  private runLifecycleAfterHeaders<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T> {
+    const paramsSchema = entry.schema?.params
+    if (paramsSchema === undefined) {
+      if (entry.schema?.body === undefined)
+        return this.runQueryAndLifecycle(entry, ctx, finalize, wrapResponse)
+      return this.runLifecycleAfterParams(entry, source, ctx, finalize, wrapResponse, undefined)
+    }
+    const validation = paramsSchema["~standard"].validate(ctx.params)
+    if (validation instanceof Promise) {
+      return validation.then(
+        (result) =>
+          this.runLifecycleAfterParamsResult(entry, source, ctx, finalize, wrapResponse, result),
+        (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse),
+      )
+    }
+    return this.runLifecycleAfterParamsResult(
+      entry,
+      source,
+      ctx,
+      finalize,
+      wrapResponse,
+      validation,
+    )
+  }
+
   /** Registration-specialized query lifecycle: query validation (including recovery) → hooks. */
   private runLifecycleQuery<T>(
     entry: RouteEntry,
@@ -3772,6 +4079,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   }
 
   /** Registration-specialized body lifecycle: bounded body validation (including recovery) → hooks. */
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runLifecycleBody<T>(
     entry: RouteEntry,
     source: RequestSource,
@@ -3789,6 +4098,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   }
 
   /** Registration-specialized body + query lifecycle: bounded body validation → query validation → hooks. */
+  // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: invoked structurally by compiled plans (internal/route-execution.ts)
   private runLifecycleBodyQuery<T>(
     entry: RouteEntry,
     source: RequestSource,
@@ -4070,8 +4381,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     wrapResponse: (response: Response) => T,
   ): Promise<T> {
     try {
-      for (const hook of entry.beforeHandle) {
-        const outcome = hook(ctx)
+      // Indexed, not `for...of`. An array iterator declared inside an async function stays live
+      // across the `await` below, so neither engine can sink it - unlike the sync lanes above,
+      // where V8 elides it. Measured cost of the iterator form: 43ns per hook on Bun, ~9ns on
+      // Node, on a chain whose hooks return synchronously (the common shape).
+      for (let i = 0; i < entry.beforeHandle.length; i++) {
+        const outcome = entry.beforeHandle[i]!(ctx)
         const early = outcome instanceof Promise ? await outcome : outcome
         if (early !== undefined) return finalize(early, responseSet(ctx))
       }
@@ -4231,8 +4546,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // any handler or loader.
     if (err instanceof Response) return wrapResponse(err)
     // onError hooks may return a custom response; otherwise the default 500 stands.
-    for (const hook of entry.onError) {
-      const outcome = hook(err, ctx)
+    // Indexed for the same reason as the `beforeHandle` chain above: the iterator would outlive
+    // the `await` and stay heap-allocated on both engines.
+    for (let i = 0; i < entry.onError.length; i++) {
+      const outcome = entry.onError[i]!(err, ctx)
       const handled = outcome instanceof Promise ? await outcome : outcome
       if (handled !== undefined) return finalize(handled, responseSet(ctx))
     }
@@ -4245,6 +4562,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Log an unhandled request error to the (redacting) logger - shared by {@link runLifecycle} and the
    * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */
   private logRequestError(err: unknown, ctx: RawContext): void {
+    // An error's own text can quote the input that produced it, so how much of it reaches the sink is
+    // the app's call (`errorLogDetail`). The default keeps it: a 500 with no message and no stack is
+    // an incident nobody can diagnose, and the framework already ships the narrower instrument for
+    // the leak - a redacting logger with `valuePatterns`. `"none"` is there for an untrusted sink.
+    const detail = this.errorLogDetail
     this.logger.error("unhandled request error", {
       method: ctx.req.method,
       path: pathnameOf(ctx.req.url),
@@ -4252,8 +4574,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       // `detail`, not `message`: the logger uses `message` for its own first argument, so a field of
       // that name is silently overwritten and the thrown error's own text never reaches the sink. It
       // survived only incidentally inside `stack`, and was lost outright for a non-Error throw.
-      detail: err instanceof Error ? err.message : String(err),
-      stack: err instanceof Error ? err.stack : undefined,
+      ...(detail === "none" ? {} : { detail: err instanceof Error ? err.message : String(err) }),
+      ...(detail === "full" && err instanceof Error ? { stack: err.stack } : {}),
     })
   }
 
@@ -4265,11 +4587,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const contentType = headerOf(req, "content-type") ?? ""
     let parsed: unknown
     if (contentType === "application/json" || contentType.includes("application/json")) {
-      const json = await this.readBoundedJson(req)
+      const json = await this.readBoundedJson(req, entry.bodyLimit ?? this.maxBodyBytes)
       if (json instanceof Response) return json
       parsed = json
     } else if (isUrlEncodedForm(contentType)) {
-      const form = await readBoundedForm(req, this.maxBodyBytes)
+      const form = await readBoundedForm(req, entry.bodyLimit ?? this.maxBodyBytes)
       if (form instanceof Response) return form
       parsed = form
     } else {
@@ -4288,11 +4610,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     entry: RouteEntry,
     result: StandardResult<unknown>,
     ctx: RawContext,
-    kind: "body" | "query" | "params",
+    kind: "body" | "query" | "params" | "headers",
   ): MaybePromise<Response | undefined> {
     const assign = (value: unknown): void => {
       if (kind === "body") ctx.body = value
       else if (kind === "query") ctx.query = value
+      else if (kind === "headers") ctx.headers = value as Record<string, string>
       else ctx.params = value as Record<string, string>
     }
     if (result.issues === undefined) {
@@ -4312,7 +4635,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
 
   private finishLifecycleValidationRecovery(
     entry: RouteEntry,
-    kind: "body" | "query" | "params",
+    kind: "body" | "query" | "params" | "headers",
     issues: ReadonlyArray<StandardIssue>,
     recovery: unknown,
     assign: (value: unknown) => void,
@@ -4324,7 +4647,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         ? entry.schema?.body
         : kind === "query"
           ? entry.schema?.query
-          : entry.schema?.params
+          : kind === "params"
+            ? entry.schema?.params
+            : entry.schema?.headers
     const retried = schema!["~standard"].validate(recovery)
     if (retried instanceof Promise) {
       return retried.then((settled) => {
@@ -4339,21 +4664,30 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   }
 
   /**
-   * Read the body as text, capped at `maxBodyBytes`. Rejects (`null`) on a
-   * `Content-Length` over the cap *before* buffering, and aborts mid-stream once the
-   * running byte count exceeds it - so a lying or absent length can't force us to
-   * buffer an oversized payload.
-   *
-   * Fast path: when a non-chunked request carries a `Content-Length` within the cap,
-   * a native `req.json()` is already bounded - under HTTP/1.1 + HTTP/2 framing the
-   * runtime delivers at most `Content-Length` bytes - so we skip the manual stream
-   * loop and a separate text decode. It trusts the wire
-   * *framing*, not the header value: nifra only ever receives framed Requests from the
-   * runtime's HTTP server, never a hand-built one with a mismatched length. Chunked or
-   * length-less bodies fall through to the streaming byte-cap guard below.
+   * Read + parse the JSON body, capped at `maxBodyBytes` and screened by the server's
+   * `protoPoisoning` policy. Rejects a `Content-Length` over the cap *before* buffering,
+   * re-checks what was actually delivered after the read, and aborts a chunked or
+   * length-less body mid-stream once the running byte count exceeds the cap - so a lying
+   * or absent length can't force us to buffer an oversized payload.
    */
-  private async readBoundedJson(req: RequestSource): Promise<unknown | Response> {
-    return readBoundedJsonSource(req, this.maxBodyBytes)
+  private readBoundedJson(req: RequestSource, maxBodyBytes?: number): Promise<unknown | Response>
+  private readBoundedJson<T>(
+    req: RequestSource,
+    maxBodyBytes: number,
+    onResult: (parsed: unknown | Response) => T | Promise<T>,
+    onError: (error: unknown) => T | Promise<T>,
+  ): Promise<T>
+  private readBoundedJson<T>(
+    req: RequestSource,
+    maxBodyBytes = this.maxBodyBytes,
+    onResult?: (parsed: unknown | Response) => T | Promise<T>,
+    onError?: (error: unknown) => T | Promise<T>,
+  ): Promise<unknown | Response | T> {
+    // Not `async`: this is a pass-through, and wrapping the lane's own promise in a coroutine
+    // frame costs an extra microtask hop on every JSON body.
+    return onResult === undefined
+      ? readBoundedJsonSource(req, maxBodyBytes, this.protoPoisoning)
+      : readBoundedJsonSource(req, maxBodyBytes, this.protoPoisoning, onResult, onError!)
   }
 
   /** Adapt one route's compiled execution plan to Bun's already-matched request shape. Route
@@ -4365,25 +4699,51 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     signal: AbortSignal | undefined,
     budget: RequestBudget | undefined,
   ): BunNativeHandler {
+    // This callback is reached only from Bun's compiled native route table. Bun has already parsed
+    // the HTTP framing, so the JSON lane may retain its native fused `json()` parse without weakening
+    // the portable/adapted source contract (those sources are never marked).
+    const markFramed = (request: Request): void => markTrustedBodyFraming(request)
+    // The fused native lane bypasses `runMatched`, so the route's transport byte cap must be
+    // marked here too - otherwise a Bun `listen()` fused route would leave direct `c.req` body
+    // reads uncapped. The non-fused branches go through `fetchMatched` -> `runMatched`, which marks.
+    const bodyLimit = entry.schema?.body === undefined ? entry.bodyLimit : undefined
+    const inner = fused
+    const capped: FusedWebRunner | undefined =
+      inner === undefined || bodyLimit === undefined
+        ? inner
+        : (source, params, search, fusedSignal, fusedBudget, platform, nativeContext) => {
+            const method = source.method
+            if (method !== "GET" && method !== "HEAD") markTransportCap(source, bodyLimit)
+            return inner(source, params, search, fusedSignal, fusedBudget, platform, nativeContext)
+          }
     if (paramNames.length === 0) {
-      if (fused === undefined) {
-        return (request) => this.fetchMatched(request, entry, EMPTY_PARAMS)
+      if (capped === undefined) {
+        return (request) => {
+          markFramed(request)
+          return this.fetchMatched(request, entry, EMPTY_PARAMS)
+        }
       }
       if (this.acceptInboundDeadlines) {
-        return (request) =>
-          request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+        return (request) => {
+          markFramed(request)
+          return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
             ? this.fetchMatched(request, entry, EMPTY_PARAMS)
-            : fused(request, EMPTY_PARAMS, undefined, signal!, budget!, undefined, true)
+            : capped(request, EMPTY_PARAMS, undefined, signal!, budget!, undefined, true)
+        }
+      }
+      return (request) => {
+        markFramed(request)
+        return capped(request, EMPTY_PARAMS, undefined, signal!, budget!, undefined, true)
       }
-      return (request) => fused(request, EMPTY_PARAMS, undefined, signal!, budget!, undefined, true)
     }
 
     const malformed =
       paramNames.length === 1
         ? (params: Record<string, string>) => params[paramNames[0]!]?.includes("\uFFFD") === true
         : hasReplacementParam
-    if (fused === undefined) {
+    if (capped === undefined) {
       return (request) => {
+        markFramed(request)
         const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
         if (malformed(params)) return this.fetchSource(request)
         return this.fetchMatched(request, entry, params)
@@ -4391,17 +4751,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
     if (this.acceptInboundDeadlines) {
       return (request) => {
+        markFramed(request)
         const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
         if (malformed(params)) return this.fetchSource(request)
         return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
           ? this.fetchMatched(request, entry, params)
-          : fused(request, params, undefined, signal!, budget!, undefined, true)
+          : capped(request, params, undefined, signal!, budget!, undefined, true)
       }
     }
     return (request) => {
+      markFramed(request)
       const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
       if (malformed(params)) return this.fetchSource(request)
-      return fused(request, params, undefined, signal!, budget!, undefined, true)
+      return capped(request, params, undefined, signal!, budget!, undefined, true)
     }
   }
 
@@ -4476,10 +4838,21 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * `"127.0.0.1"` to bind loopback only - an admin surface, a sidecar, or anything that must not be
    * reachable off the box. Omitting it when you meant to restrict is a real exposure, so it is a
    * first-class option rather than something a caller has to drop down to `Bun.serve` for.
+   *
+   * `idleTimeoutSec` is how long Bun tolerates a connection with no bytes moving before it closes
+   * the socket. Bun's default is **10 seconds**, and a request whose handler is still working sends
+   * nothing - so any endpoint slower than 10s (a render, an export, a long upstream call) has its
+   * connection cut mid-flight regardless of `requestTimeoutMs`. Apps with such endpoints must raise
+   * this above their slowest expected response, which is why it is a first-class option and not a
+   * reason to drop down to `Bun.serve`. `0` disables the timeout entirely; max 255.
    */
   listen(
     port: number,
-    options?: { readonly reusePort?: boolean; readonly hostname?: string },
+    options?: {
+      readonly reusePort?: boolean
+      readonly hostname?: string
+      readonly idleTimeoutSec?: number
+    },
   ): RunningServer {
     if (typeof Bun === "undefined") {
       // listen() is the one Bun-specific seam. Off Bun, fail loud + actionable rather
@@ -4509,12 +4882,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // Spread rather than pass `hostname: undefined` - Bun treats an explicit undefined as a value
     // on some option paths, and omitting is what selects its 0.0.0.0 default.
     const bind = options?.hostname === undefined ? {} : { hostname: options.hostname }
+    // Same reasoning as `bind`: omit rather than pass undefined, so Bun's own default applies.
+    const idle =
+      options?.idleTimeoutSec === undefined ? {} : { idleTimeout: options.idleTimeoutSec }
     const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes() : undefined
     const running = (wsHandlers === undefined
       ? Bun.serve({
           port,
           reusePort,
           ...bind,
+          ...idle,
           ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
           fetch: (req: Request, server) =>
             this.fetch(req, bunPeerPlatform(server, req) as Platform<EnvOf<Ctx>>),
@@ -4523,6 +4900,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           port,
           reusePort,
           ...bind,
+          ...idle,
           fetch: (req, server) => this.bunFetchWithWebSocket(req, server),
           // Bun's `ServerWebSocket<BunWsData>` is runtime-compatible with the handlers' structural
           // `BunSocket` view (kept local so `Bun.*` types never leak into the published .d.ts); the
@@ -4562,6 +4940,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       await Bun.sleep(DRAIN_POLL_MS)
     }
     server.stop(server.pendingRequests > 0) // force-close iff stragglers remain past the deadline
+    if (this.stopHooks.length === 0) return
+    const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook))
+    const settled = Promise.allSettled(callbacks)
+    await Promise.race([
+      settled,
+      new Promise<void>((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+    ])
   }
 
   private installSignalHandlers(): void {