@nifrajs/core 2.10.0 → 2.12.0

package/dist/server/server.js

@@ -3,69 +3,23 @@ import { FrameworkError, RouteConfigError } from "../errors.js";
 import { CAPABILITY_GUARD, createCapabilityGuard, DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS, normalizeRouteCapabilities, } from "../internal/capability-runtime.js";
 import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, validEvidenceId, } from "../internal/route-assurance.js";
 import { RouteCatalog } from "../internal/route-catalog.js";
+import { compileRouteExecutionPlan, } from "../internal/route-execution.js";
 import { isSameOriginRequest } from "../internal/same-origin.js";
 import { compileRoutePattern, decodeRouteParams } from "../router/pattern.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
-import { assertByteLimit, parseContentLength } from "./body.js";
+import { assertByteLimit, markTransportCap, markTrustedBodyFraming } from "./body.js";
 import { resolveClientIp } from "./client-ip.js";
+import { hasLowercaseHeaderKeysMark, headerKeysAllLowercase, markLowercaseHeaderKeys, } from "./header-case.js";
+import { headerObjectOf } from "./headers.js";
 import { jsonError, pathnameOf, urlPartsOf } from "./http.js";
 import { withStaticNodeHeaders } from "./node-outcome.js";
 import { recordHeadersView, } from "./node-outcome-hook.js";
 import { isUrlEncodedForm, queryObjectOf, readBoundedForm, searchOf, } from "./query.js";
 import { RequestContext, readBoundedJsonSource } from "./request-context.js";
-import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, knownMutableHeaders, markTaggedResponse, rememberMutableHeaders, taggedResponseBody, taggedResponseOwner, toResponse, } from "./respond.js";
+import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, knownMutableHeaders, rememberMutableHeaders, taggedResponseBody, toResponse, } from "./respond.js";
+import { applyBodyReplacement, withReplacedBody } from "./response-hooks.js";
 import { CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, requestOf, } from "./runtime-core.js";
 import { normalizeStaticResponseHeaders } from "./static-headers.js";
-function isBodylessStatus(status) {
-    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, replaced) {
-    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, replaced) {
-    if (replaced === undefined)
-        return response;
-    const originalBody = taggedResponseBody(response);
-    let body;
-    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, {
-        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();
 /**
@@ -199,10 +153,11 @@ function requireMcpRuntime(runtime) {
 }
 // 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 { defineIdentityPlugin, definePlugin, defineRouterPlugin, } from "./plugin.js";
+export { defineContextPlugin, defineIdentityPlugin, definePlugin, defineRouterPlugin, } from "./plugin.js";
 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
  * for the same request, so a browser that could open a socket was told its POST was cross-origin. */
@@ -227,6 +182,31 @@ function hasReplacementParam(params) {
     }
     return false;
 }
+function normalizeMountPrefix(path) {
+    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, prefix) {
+    return prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+function stripMountPrefix(request, prefix) {
+    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);
+}
 function responseSet(ctx) {
     return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
 }
@@ -261,6 +241,9 @@ export class Server {
      * no-WebSocket app never constructs (or bundles) it. */
     topics;
     maxBodyBytes;
+    protoPoisoning;
+    /** `trustBodyFraming`: mark every `app.fetch` request as runtime-framed (see ServerOptions). */
+    trustBodyFraming;
     wsMaxPayloadBytes;
     requestTimeoutMs;
     /** Installed by the `responseContract()` plugin; `undefined` = not installed, which is the default
@@ -272,6 +255,8 @@ export class Server {
     maxInboundDeadlineMs;
     deadlineAdmissionOptions;
     gracefulSignals;
+    stopHooks;
+    fetchMounts;
     /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
     capacityGate;
     onCapabilityUse;
@@ -292,6 +277,8 @@ export class Server {
     /** Installed WebSocket runtime for `.ws()` routes; `undefined` until `.use(websocket())`. */
     wsRuntime;
     logger;
+    /** How much of an unhandled error {@link logRequestError} records. See `ServerOptions.errorLogDetail`. */
+    errorLogDetail;
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     defaultOnValidationError;
     bunServer;
@@ -310,6 +297,13 @@ export class Server {
     onNodeResponseHooks;
     /** Registration-time eligibility for the Node response twin lane. */
     nodeResponseHooksComplete;
+    /**
+     * 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.
+     */
+    hasRawNodeResponseHook;
     onResponseFinalizedHooks;
     /**
      * Statically declared response headers, merged and prebuilt at registration; `undefined` (the
@@ -347,6 +341,8 @@ export class Server {
         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;
@@ -366,6 +362,8 @@ export class Server {
             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 = [];
@@ -378,6 +376,7 @@ export class Server {
         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;
@@ -393,6 +392,7 @@ export class Server {
         this.onResponseHooks = [];
         this.onNodeResponseHooks = [];
         this.nodeResponseHooksComplete = true;
+        this.hasRawNodeResponseHook = false;
         this.onResponseFinalizedHooks = [];
         this.staticResponseHeaders = undefined;
         this.wrapWebResponse = IDENTITY_RESPONSE;
@@ -413,6 +413,32 @@ export class Server {
             throw new FrameworkError("SERVER_SEALED", `server configuration is sealed after listen(); call ${operation} before listen()`);
         }
     }
+    /** Register a callback awaited after graceful drain and server stop. Hung callbacks are bounded. */
+    onStop(fn) {
+        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, handler, options = {}) {
+        this.assertConfigurable("mountFetch()");
+        if (typeof handler !== "function")
+            throw new TypeError("mountFetch handler must be a function");
+        const mount = {
+            path: normalizeMountPrefix(path),
+            handler: handler,
+            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(fn) {
         this.assertConfigurable("derive()");
@@ -672,6 +698,8 @@ export class Server {
             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");
@@ -844,6 +872,29 @@ export class Server {
     }
     prepareRoute(method, path, schema, handler) {
         const pattern = compileRoutePattern(path);
+        let bodyLimit = this.maxBodyBytes;
+        const invalidBodyLimit = (message) => {
+            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);
         const invalidHandlerScope = handlerAssurance.find((declaration) => declaration.scope !== "plugin");
@@ -879,6 +930,7 @@ export class Server {
             ? { runtime, schema: schema.response }
             : undefined;
         const bare = schema?.params === undefined &&
+            schema?.headers === undefined &&
             schema?.body === undefined &&
             schema?.query === undefined &&
             idempotent === undefined &&
@@ -899,6 +951,7 @@ export class Server {
             schema?.query !== undefined &&
             schema.body === undefined &&
             schema.params === undefined &&
+            schema.headers === undefined &&
             schema.onValidationError === undefined &&
             this.defaultOnValidationError === undefined &&
             idempotent === undefined &&
@@ -912,6 +965,7 @@ export class Server {
             schema?.body !== undefined &&
             schema.query === undefined &&
             schema.params === undefined &&
+            schema.headers === undefined &&
             this.derives.length === 0 &&
             this.beforeHandleHooks.length === 0 &&
             this.afterHandleHooks.length === 0 &&
@@ -927,12 +981,12 @@ export class Server {
         // handler continuation once. The runner keeps the bounded parser and all error semantics while
         // avoiding the generic entry/schema/lifecycle dispatch on Bun, Deno, and Node-direct.
         const fusedBodyRunner = fusedBody
-            ? this.buildFusedBodyRunner(handler, schema.body, hasDecorations ? routeDecorations : undefined)
+            ? this.buildFusedBodyRunner(handler, schema.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? this.maxBodyBytes)
             : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
-            ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
+            ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? this.maxBodyBytes)
             : fusedQuery
-                ? this.buildFusedQueryWeb(handler, hasDecorations ? routeDecorations : undefined, schema.query)
+                ? this.buildFusedQueryWeb(handler, hasDecorations ? routeDecorations : undefined, schema.query, bodyLimit ?? this.maxBodyBytes)
                 : fusedBody
                     ? this.buildFusedBodyWeb(fusedBodyRunner)
                     : undefined;
@@ -947,6 +1001,7 @@ export class Server {
                     schema?.body === undefined &&
                     schema?.query !== undefined &&
                     schema.params === undefined &&
+                    schema.headers === undefined &&
                     this.derives.length === 0 &&
                     this.beforeHandleHooks.length === 0 &&
                     this.afterHandleHooks.length === 0 &&
@@ -957,7 +1012,7 @@ export class Server {
         // plus an optional query or body schema. Select their complete validation stage at registration
         // 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
+        const lifecycleLane = lane !== "lifecycle" || schema?.params !== undefined || schema?.headers !== undefined
             ? undefined
             : schema?.body !== undefined
                 ? schema.query !== undefined
@@ -979,12 +1034,22 @@ export class Server {
             this.onErrorHooks.length === 0
             ? "derive-before"
             : undefined;
-        const execution = this.compileExecutionPlan(lane, contextless, this.aroundHooks.length > 0, ledgered !== undefined, lifecycleLane, fusedWeb, fusedBodyRunner, fusedWeb === undefined ? undefined : fusedQuery ? "query" : fusedBody ? "body" : "bare");
+        const execution = compileRouteExecutionPlan({
+            lane,
+            contextless,
+            hasAround: this.aroundHooks.length > 0,
+            hasLedger: ledgered !== undefined,
+            lifecycleLane,
+            fusedWeb,
+            fusedBody: fusedBodyRunner,
+            fusedLane: fusedWeb === undefined ? undefined : fusedQuery ? "query" : fusedBody ? "body" : "bare",
+        });
         const registeredEntry = {
             // (context: never) => unknown -> InternalHandler: the framework invokes it
             // with the concrete RawContext the typed handler expects, so this is sound.
             handler: handler,
             schema,
+            bodyLimit,
             idempotent,
             ledgered,
             responseContract: contracted,
@@ -1006,6 +1071,13 @@ export class Server {
             ...(schema?.family === true ? { family: true } : {}),
         };
         const routeAssurance = [...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).
@@ -1013,7 +1085,14 @@ export class Server {
             if (!validEvidenceId(id)) {
                 throw new Error(`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" };
+            Object.defineProperty(declared, "provenance", {
+                value: "declared",
+                enumerable: false,
+                configurable: false,
+                writable: false,
+            });
+            routeAssurance.push(Object.freeze(declared));
         }
         if (schema?.body !== undefined) {
             routeAssurance.push(Object.freeze({
@@ -1040,67 +1119,6 @@ export class Server {
             assurance: Object.freeze(routeAssurance),
         };
     }
-    /** 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. */
-    compileExecutionPlan(lane, contextless, hasAround, hasLedger, lifecycleLane, fusedWeb, fusedBody, fusedLane) {
-        if (contextless) {
-            const run = (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;
-        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 = hasAround
-            ? (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runWithAround(entry, ctx, () => inner(runtime, entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse)
-            : inner;
-        const run = (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;
-            // 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;
-                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;
-                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). */
     idempotencyRunLanes(buffered, platform, entry, params, search) {
@@ -1148,10 +1166,15 @@ export class Server {
      *
      * 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).
      */
@@ -1161,7 +1184,20 @@ export class Server {
         if (source.wsRouteCount > 0) {
             throw new RouteConfigError("INVALID_PATH", "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) => ({
+                ...route,
+                assurance: [...route.assurance, ...source.globalAssurance],
+            })
+            : (route) => 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
@@ -1174,8 +1210,23 @@ export class Server {
         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) => (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) => 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
@@ -1186,13 +1237,15 @@ export class Server {
         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;
@@ -1206,13 +1259,13 @@ export class Server {
         // Rebuild with the SAME builder that produced the closure - rebinding a query-fused route as
         // bare would silently drop its validation.
         const fusedBody = entry.execution.fusedLane === "body"
-            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined)
+            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined, entry.bodyLimit ?? this.maxBodyBytes)
             : undefined;
         const fusedWeb = entry.execution.fusedLane === "body"
             ? this.buildFusedBodyWeb(fusedBody)
             : entry.execution.fusedLane === "query"
-                ? this.buildFusedQueryWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, entry.schema?.query)
-                : this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler));
+                ? this.buildFusedQueryWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, entry.schema?.query, entry.bodyLimit ?? this.maxBodyBytes)
+                : this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler), entry.bodyLimit ?? this.maxBodyBytes);
         return {
             ...route,
             entry: {
@@ -1243,6 +1296,10 @@ export class Server {
      * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).
      */
     fetch(req, platform) {
+        // 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);
@@ -1365,11 +1422,15 @@ export class Server {
         // 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))
@@ -1410,12 +1471,22 @@ export class Server {
                 : runtime.fromResponse(transformed);
         }
         let headers = outcome.headers;
+        // 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) {
@@ -1430,6 +1501,13 @@ export class Server {
                 }
             }
         }
+        // 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 = {
             status: outcome.status,
             headers,
@@ -1551,13 +1629,27 @@ export class Server {
             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(req, params, url.search, upgradeSignal, createUnboundedRequestBudget(upgradeSignal), platform, this.maxBodyBytes);
+        const ctx = new RequestContext(req, params, url.search, upgradeSignal, createUnboundedRequestBudget(upgradeSignal), platform, this.maxBodyBytes, this.protoPoisoning);
         const settle = (value) => 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);
             return result instanceof Promise
@@ -1816,6 +1908,12 @@ export class Server {
         }
         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(", ") }));
             }
@@ -1829,14 +1927,33 @@ export class Server {
         }
         return this.runMatched(source, platform, match.payload, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
+    fetchMount(pathname, source, platform) {
+        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. */
     runMatched(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
+        // 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.
+        if (entry.bodyLimit !== 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).
         if (entry.idempotent !== undefined && this.idempotencyRuntime !== undefined) {
             return this.idempotencyRuntime.run(entry.idempotent, requestOf(source), platform, entry, params, search, wrapResponse, {
-                maxBodyBytes: this.maxBodyBytes,
+                maxBodyBytes: entry.bodyLimit ?? this.maxBodyBytes,
                 runLanes: (buffered, plat, ent, prm, srch) => this.idempotencyRunLanes(buffered, plat, ent, prm, srch),
             });
         }
@@ -1900,6 +2017,8 @@ export class Server {
     }
     /** 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)
     runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse) {
         let result;
         try {
@@ -1916,7 +2035,7 @@ export class Server {
     contextlessBareError(err, source, params, search, signal, budget, platform, wrapResponse) {
         if (err instanceof Response)
             return wrapResponse(err);
-        const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
+        const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes, this.protoPoisoning);
         this.logRequestError(err, ctx);
         return wrapResponse(jsonError(500, "internal_error"));
     }
@@ -1928,6 +2047,8 @@ export class Server {
      * (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)
     runBare(entry, ctx, finalize, wrapResponse) {
         let result;
         try {
@@ -1953,7 +2074,7 @@ export class Server {
      * decoration order, same error routing (thrown `Response` = control flow; anything else logs and
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
-    buildFusedWeb(handler, decorations, contextless) {
+    buildFusedWeb(handler, decorations, contextless, maxBodyBytes) {
         // 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.
         const logError = (err, ctx) => {
@@ -1973,21 +2094,21 @@ export class Server {
                 }
                 catch (err) {
                     return logError(err, 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 (result instanceof Promise) {
-                    return result.then((value) => fusedRespondNoSet(value, this.responseBodyTag, this.staticResponseHeaders), (err) => logError(err, nativeContext
-                        ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
-                        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)));
+                    return result.then((value) => fusedRespondNoSet(value, this.responseBodyTag, this.staticResponseHeaders, this.onResponseHooks.length === 0), (err) => logError(err, nativeContext
+                        ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+                        : new RequestContext(source, params, search, signal, budget, platform, 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;
@@ -1998,15 +2119,15 @@ export class Server {
                 return logError(err, ctx);
             }
             if (result instanceof Promise) {
-                return result.then((value) => fusedRespond(value, ctx, this.responseBodyTag, this.staticResponseHeaders), (err) => logError(err, ctx));
+                return result.then((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);
         };
     }
     /** Compile the eligible body-only route's parser → validator → handler continuation once. The
      * bounded parser remains shared with the generic lane; only the route-invariant entry lookups and
      * lifecycle dispatch disappear from the common synchronous-validator/synchronous-handler case. */
-    buildFusedBodyRunner(handler, bodySchema, decorations) {
+    buildFusedBodyRunner(handler, bodySchema, decorations, maxBodyBytes) {
         const logError = (err, ctx, wrapResponse) => this.bareError(err, ctx, wrapResponse);
         const runHandler = (ctx, finalize, wrapResponse) => {
             if (decorations !== undefined)
@@ -2068,16 +2189,16 @@ export class Server {
         };
         return (source, params, search, signal, budget, platform, nativeContext, finalize, wrapResponse) => {
             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) => runParsed(value, ctx, finalize, wrapResponse);
-            return this.readBodyInput(source, finish, wrapResponse, (err) => logError(err, ctx, wrapResponse));
+            return this.readBodyInput(source, maxBodyBytes, finish, wrapResponse, (err) => logError(err, ctx, wrapResponse));
         };
     }
     /** Web adapter wrapper for the shared body runner. Node passes its native finalizer directly through
      * the execution plan, while Web needs the live context to preserve lazy `c.set` controls. */
     buildFusedBodyWeb(body) {
-        return (source, params, search, signal, budget, platform, nativeContext) => body(source, params, search, signal, budget, platform, nativeContext, (result, _set, ctx) => fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders), this.wrapWebResponse);
+        return (source, params, search, signal, budget, platform, nativeContext) => body(source, params, search, signal, budget, platform, nativeContext, (result, _set, ctx) => fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders, this.onResponseHooks.length === 0), this.wrapWebResponse);
     }
     /** The fused Web lane for a route whose only lifecycle step is a query schema: parse + validate +
      * handler + respond in one closure, no lifecycle promise when the validator and handler are sync.
@@ -2086,7 +2207,7 @@ export class Server {
      * `validationError(issues)` (recovery hooks disqualify the route from this lane), a thrown
      * `Response` passes through, anything else logs and returns a flat 500, and an async validator
      * falls to a then-chain with the same steps. */
-    buildFusedQueryWeb(handler, decorations, querySchema) {
+    buildFusedQueryWeb(handler, decorations, querySchema, maxBodyBytes) {
         // 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.
         const logError = (err, ctx) => {
@@ -2105,14 +2226,14 @@ export class Server {
                 return logError(err, ctx);
             }
             if (result instanceof Promise) {
-                return result.then((settled) => fusedRespond(settled, ctx, this.responseBodyTag, this.staticResponseHeaders), (err) => logError(err, ctx));
+                return result.then((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;
@@ -2138,6 +2259,8 @@ export class Server {
         this.logRequestError(err, ctx);
         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)
     runWithAround(entry, ctx, run, finalize, wrapResponse) {
         let outcome;
         try {
@@ -2165,36 +2288,26 @@ export class Server {
         };
         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)
     runBodyOnly(entry, source, ctx, finalize, wrapResponse) {
-        return this.readBodyInput(source, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        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));
     }
     /** Shared bounded body framing/parser. Both body lanes use the same trust-boundary checks; only
      * the validation + handler continuation differs. */
-    readBodyInput(source, onParsed, wrapResponse, onError) {
+    readBodyInput(source, maxBodyBytes, onParsed, wrapResponse, onError) {
         const contentType = headerOf(source, "content-type") ?? "";
         if (contentType !== "application/json" && !contentType.includes("application/json")) {
             if (isUrlEncodedForm(contentType)) {
-                return readBoundedForm(source, this.maxBodyBytes).then((form) => (form instanceof Response ? wrapResponse(form) : onParsed(form)), onError);
+                return readBoundedForm(source, maxBodyBytes).then((form) => (form instanceof Response ? wrapResponse(form) : onParsed(form)), onError);
             }
             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((parsed) => (parsed instanceof Response ? wrapResponse(parsed) : onParsed(parsed)), onError);
+            return this.readBoundedJson(source, maxBodyBytes, (parsed) => (parsed instanceof Response ? wrapResponse(parsed) : onParsed(parsed)), onError);
         }
         catch (err) {
             return Promise.resolve(onError(err));
@@ -2296,6 +2409,8 @@ export class Server {
         ctx.body = result.value;
         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)
     runQueryOnly(entry, ctx, finalize, wrapResponse) {
         try {
             // Call the validator directly for the raw StandardResult (read `.issues`/`.value`) - skip
@@ -2446,8 +2561,18 @@ export class Server {
      * 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)
     runLifecycle(entry, source, ctx, finalize, wrapResponse) {
         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);
@@ -2469,6 +2594,35 @@ export class Server {
             return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
         }
     }
+    runLifecycleAfterHeadersResult(entry, source, ctx, finalize, wrapResponse, result) {
+        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);
+        }
+    }
+    runLifecycleAfterHeaders(entry, source, ctx, finalize, wrapResponse) {
+        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. */
     runLifecycleQuery(entry, ctx, finalize, wrapResponse) {
         try {
@@ -2492,12 +2646,16 @@ export class Server {
         }
     }
     /** 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)
     runLifecycleBody(entry, source, ctx, finalize, wrapResponse) {
         return this.readAndValidateBody(source, entry, ctx).then((bodyError) => bodyError === undefined
             ? this.runLifecycleHooks(entry, ctx, finalize, wrapResponse)
             : wrapResponse(bodyError), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
     }
     /** 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)
     runLifecycleBodyQuery(entry, source, ctx, finalize, wrapResponse) {
         return this.readAndValidateBody(source, entry, ctx).then((bodyError) => bodyError === undefined
             ? this.runLifecycleQuery(entry, ctx, finalize, wrapResponse)
@@ -2652,8 +2810,12 @@ export class Server {
     }
     async runLifecycleHooksAsync(entry, ctx, finalize, wrapResponse) {
         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));
@@ -2761,8 +2923,10 @@ export class Server {
         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));
@@ -2775,6 +2939,11 @@ export class Server {
     /** 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. */
     logRequestError(err, ctx) {
+        // 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),
@@ -2782,21 +2951,21 @@ export class Server {
             // `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 } : {}),
         });
     }
     async readAndValidateBody(req, entry, ctx) {
         const contentType = headerOf(req, "content-type") ?? "";
         let parsed;
         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;
@@ -2818,6 +2987,8 @@ export class Server {
                 ctx.body = value;
             else if (kind === "query")
                 ctx.query = value;
+            else if (kind === "headers")
+                ctx.headers = value;
             else
                 ctx.params = value;
         };
@@ -2843,7 +3014,9 @@ export class Server {
             ? 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) => {
@@ -2858,42 +3031,59 @@ export class Server {
         assign(retried.value);
         return undefined;
     }
-    /**
-     * 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.
-     */
-    async readBoundedJson(req) {
-        return readBoundedJsonSource(req, this.maxBodyBytes);
+    readBoundedJson(req, maxBodyBytes = this.maxBodyBytes, onResult, onError) {
+        // 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
      * semantics remain in the plan; this closure only supplies native params and deadline fallback. */
     compileBunNativeHandler(entry, paramNames, fused, signal, budget) {
+        // 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) => 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.bodyLimit;
+        const inner = fused;
+        const capped = 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
-                    ? this.fetchMatched(request, entry, EMPTY_PARAMS)
-                    : fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+                return (request) => {
+                    markFramed(request);
+                    return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                        ? this.fetchMatched(request, entry, EMPTY_PARAMS)
+                        : capped(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+                };
             }
-            return (request) => fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+            return (request) => {
+                markFramed(request);
+                return capped(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+            };
         }
         const malformed = paramNames.length === 1
             ? (params) => params[paramNames[0]]?.includes("\uFFFD") === true
             : hasReplacementParam;
-        if (fused === undefined) {
+        if (capped === undefined) {
             return (request) => {
+                markFramed(request);
                 const params = request.params ?? EMPTY_PARAMS;
                 if (malformed(params))
                     return this.fetchSource(request);
@@ -2902,19 +3092,21 @@ export class Server {
         }
         if (this.acceptInboundDeadlines) {
             return (request) => {
+                markFramed(request);
                 const params = request.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.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);
         };
     }
     /** Compile portable route registrations into Bun's native route table. Apps with request-rewrite
@@ -2980,6 +3172,13 @@ export class Server {
      * `"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, options) {
         if (typeof Bun === "undefined") {
@@ -3006,12 +3205,15 @@ export class Server {
         // 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, server) => this.fetch(req, bunPeerPlatform(server, req)),
             })
@@ -3019,6 +3221,7 @@ export class Server {
                 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
@@ -3059,6 +3262,14 @@ export class Server {
             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((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+        ]);
     }
     installSignalHandlers() {
         // Drain, then let the process exit naturally - the stopped server no longer