@nifrajs/core 2.13.0 → 3.1.0

package/dist/server/server.js

@@ -7,107 +7,19 @@ 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, markTransportCap, markTrustedBodyFraming, } from "./body.js";
+import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.js";
+import { assertByteLimit, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } 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 { jsonError, pathnameOf, plainError, 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, 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 { RequestContext, readBodyFramed, readBoundedJsonSource } from "./request-context.js";
+import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, toResponse, } from "./respond.js";
+import { CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, isResponseResult, requestOf, status, } from "./runtime-core.js";
 import { normalizeStaticResponseHeaders } from "./static-headers.js";
-const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe";
-const GUARDED_RESPONSE_HEADERS = new WeakSet();
-/**
- * Detect a guarded Web Headers object before invoking user code. Retrying after catching any
- * TypeError is observably wrong: user hooks are allowed to throw TypeError themselves, and a retry
- * runs those hooks twice. The hot path never reaches the probe: every framework-constructed
- * Response stamps its headers as known-mutable at construction (see respond.ts), so only a
- * handler-returned foreign `Response` - the case that can actually be guarded - pays it, once per
- * headers object. The probe uses a valid private header name and restores a pre-existing value, so
- * the fallback is limited to the actual immutable/guarded-header case.
- */
-function hasMutableResponseHeaders(headers) {
-    if (knownMutableHeaders(headers))
-        return true;
-    if (GUARDED_RESPONSE_HEADERS.has(headers))
-        return false;
-    let previous = null;
-    try {
-        previous = headers.get(HEADER_MUTABILITY_PROBE);
-        headers.set(HEADER_MUTABILITY_PROBE, "1");
-        if (previous === null)
-            headers.delete(HEADER_MUTABILITY_PROBE);
-        else
-            headers.set(HEADER_MUTABILITY_PROBE, previous);
-        rememberMutableHeaders(headers);
-        return true;
-    }
-    catch {
-        try {
-            if (previous === null)
-                headers.delete(HEADER_MUTABILITY_PROBE);
-            else
-                headers.set(HEADER_MUTABILITY_PROBE, previous);
-        }
-        catch {
-            // The guarded object rejected the cleanup too; the clone below is authoritative.
-        }
-        GUARDED_RESPONSE_HEADERS.add(headers);
-        return false;
-    }
-}
-/** Adapt a portable {@link ResponseBodyHook} into the Web `onResponse` walk. Only a Response
- * carrying the framework-buffered body tag participates - a raw or streamed Response is skipped by
- * contract, never drained. */
-function webResponseBodyHook(fn, owners) {
-    return (response, req) => {
-        const body = taggedResponseBody(response, owners);
-        if (body === undefined)
-            return response;
-        const out = fn(body, response.headers, webRequestView(req), response.status);
-        if (out instanceof Promise)
-            return out.then((replaced) => withReplacedBody(response, replaced));
-        return withReplacedBody(response, out);
-    };
-}
-/** Minimal request view over a Web `Request` for portable header hooks on the Web serving paths. */
-function webRequestView(req) {
-    return { method: req.method, url: req.url, header: (name) => req.headers.get(name) };
-}
-/**
- * Adapt a portable {@link ResponseHeadersHook} into the Web `onResponse` walk: run it against the
- * response's own `Headers` in place (no clone). A response whose headers are GUARDED (a raw
- * `fetch()`ed Response returned by a handler) throws on the FIRST mutation, so nothing was applied
- * yet - rerun once against a mutable copy. Async hooks should perform their mutations before their
- * first await for the guard fallback to cover them.
- */
-function webResponseHeadersHook(fn) {
-    return (response, req) => {
-        const view = webRequestView(req);
-        if (!hasMutableResponseHeaders(response.headers)) {
-            const clone = new Response(response.body, response);
-            const out = fn(clone.headers, view, clone.status);
-            return out instanceof Promise ? out.then(() => clone) : clone;
-        }
-        const out = fn(response.headers, view, response.status);
-        return out instanceof Promise ? out.then(() => response) : response;
-    };
-}
-/** Adapt a raw-response fallback hook. Tagged framework payloads already ran through the body tier,
- * while untagged Responses include streams, proxied fetches, and framework-generated error responses. */
-function webResponseRawHook(fn, owners) {
-    return (response, req) => {
-        if (taggedResponseBody(response, owners) !== undefined)
-            return response;
-        return fn(response, req);
-    };
-}
-import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_RESPONSE_CONTRACT, INSTALL_SSE, INSTALL_WS, } from "./install.js";
+import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, RESOLVE_NODE_MOUNT, } from "./install.js";
 import { jsonLogger } from "./logger.js";
 const functionToString = Function.prototype.toString;
 const CONTEXTLESS_ARROW = /^(?:async\s*)?\(\s*\)\s*(?::[\s\S]*?)?=>/;
@@ -162,12 +74,18 @@ const STOP_HOOK_TIMEOUT_MS = 5_000;
  * 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. */
 const wsSameOrigin = isSameOriginRequest;
-function validationError(issues) {
+function validationIssues(issues) {
     const serialized = issues.map((issue) => {
         const path = issue.path?.map((seg) => String(typeof seg === "object" ? seg.key : seg));
         return path !== undefined ? { message: issue.message, path } : { message: issue.message };
     });
-    return Response.json({ ok: false, error: "validation", issues: serialized }, { status: 422 });
+    return { ok: false, error: "validation", issues: serialized };
+}
+/** The 422 as plain data - the shape every lane's response wrapper takes, so a rejected body costs
+ * what an accepted one costs: on Node it is written straight to the socket with a `content-length`
+ * instead of being built as a `Response` and drained back out. */
+export function plainValidationError(issues) {
+    return status(422, validationIssues(issues));
 }
 // `jsonError`, `urlPartsOf`, `pathnameOf` moved to `./http.ts` (a dependency-free leaf shared with the
 // opt-in request lanes); re-exported so existing importers keep resolving from here.
@@ -210,6 +128,20 @@ function stripMountPrefix(request, prefix) {
 function responseSet(ctx) {
     return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
 }
+/**
+ * A `derive` that answered with a response rather than a context extension - `status(...)`, or a bare
+ * `Response`. The request ends there, on the same lane a `beforeHandle`'s early return takes.
+ *
+ * `derive` is the one stage that could not exit early: `beforeHandle` says "done" by returning a
+ * value, but a derive's return value IS the extension, so the only way out was `throw`ing a
+ * `Response` - which measured as the single most expensive way to answer (the `Response` object
+ * costs ~40% of the rejection lane; see `PlainRender`). Neither shape had a meaning here before:
+ * `Object.assign(ctx, response)` copies nothing (a `Response`'s properties live on its prototype),
+ * so a derive that returned one silently fell through to the handler it meant to prevent.
+ */
+function isDeriveEarlyExit(extension) {
+    return isResponseResult(extension) || extension instanceof Response;
+}
 function isContextlessNoArgArrow(handler) {
     if (handler.length !== 0)
         return false;
@@ -220,9 +152,92 @@ function isContextlessNoArgArrow(handler) {
         return false;
     }
 }
+/**
+ * The Web lanes' `wrapResponse` input, as a `Response`. A plain-data carrier ({@link plainError},
+ * `status(...)`) is rendered on the ordinary JSON lane rather than through its own `toResponse`, so
+ * it picks up the same prebuilt init a handler's plain return uses. `EMPTY_RESPONSE_CONTROLS` because
+ * these renders happen where no request context exists - before routing, or after it was abandoned.
+ */
+const webResponseOf = (result) => result instanceof Response ? result : toResponse(result, EMPTY_RESPONSE_CONTROLS);
 // Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
-const IDENTITY_RESPONSE = (response) => response;
+const IDENTITY_RESPONSE = (response) => webResponseOf(response);
 const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
+// The unused-order-scoped-hook audit (recorder, seal check, stack capture, message) is a dev-time
+// diagnostic. Every guard below keeps the INLINE literal `process.env.NODE_ENV !== "production"` at the
+// branch - never a shared const holding the folded boolean - because a bundler's `process.env.NODE_ENV`
+// define only dead-code-eliminates the audit when the literal appears at the `if`; Bun does not
+// propagate a module const's value into the branch. Every real production bundler (vite/esbuild/webpack/
+// next, `bun build --production`) injects that define, turning each guard into `hookAuditRuntime &&
+// false`, which folds away - dropping the whole audit and restoring the bare kernel size.
+//
+// `hookAuditRuntime` is the one shared flag: `typeof globalThis.Deno === "undefined"`. Deno ships a
+// node-compat `process`, so `typeof process` does NOT gate it out there, yet reading `process.env`
+// throws `NotCapable` without `--allow-env`. The flag short-circuits before the env read on Deno (audit
+// off) while a production define still folds `<flag> && false` to `false` on every other runtime.
+const hookAuditRuntime = typeof globalThis.Deno === "undefined";
+// This module's own path, captured once from a sentinel stack. Every internal frame of an
+// order-scoped hook push (the public method, its `use()`-bundle dispatcher, the recorder) lives here,
+// so `captureCallerSite` skips anything starting with it and lands on the user's calling frame.
+const SERVER_MODULE_PATH = /* @__PURE__ */ (() => {
+    const frame = new Error().stack?.split("\n")[1];
+    return frame?.match(/\(?([^()\s]+):\d+:\d+\)?\s*$/)?.[1];
+})();
+/** One `file:line:col` frame for the caller of an order-scoped hook method, for the unused-hook
+ * report. Only ever called behind the `unusedScopedHooks !== "off"` guard, so the `Error` (the sole
+ * non-trivial cost) is never constructed when the check is disabled. */
+const captureCallerSite = () => {
+    const stack = new Error().stack;
+    if (stack === undefined)
+        return undefined;
+    for (const line of stack.split("\n").slice(1)) {
+        const frame = line.match(/\(?([^()\s]+:\d+:\d+)\)?\s*$/)?.[1];
+        if (frame === undefined)
+            continue;
+        if (SERVER_MODULE_PATH !== undefined && frame.startsWith(`${SERVER_MODULE_PATH}:`))
+            continue;
+        return frame;
+    }
+    return undefined;
+};
+const hookAudit = /* @__PURE__ */ new WeakMap();
+/** Start tracking one server's order-scoped hook pushes (once, from the constructor). */
+const beginHookAudit = (key, policy, hasCustomLogger) => {
+    hookAudit.set(key, { policy, hasCustomLogger, sites: [], checked: false });
+};
+/** Record one order-scoped hook push: the route count at that moment (so `routesAtPush === total` at
+ * seal means no route was declared after it) and the caller's frame. */
+const recordScopedHook = (key, routesAtPush, kind) => {
+    const state = hookAudit.get(key);
+    if (state === undefined || state.policy === "off")
+        return;
+    state.sites.push({ kind, routesAtPush, site: captureCallerSite() });
+};
+/** Run the deadness check exactly once. A hook whose recorded route count equals the final route count
+ * had no route declared after it - unambiguously dead, since the scoping feature (a hook that covers
+ * only later routes) always leaves at least one such route. Zero-route apps are exempt (different
+ * mistake, and the warning would be noise). */
+const sealHookAudit = (key, total, logger) => {
+    const state = hookAudit.get(key);
+    if (state === undefined || state.checked)
+        return;
+    state.checked = true;
+    if (state.policy === "off" || total === 0)
+        return;
+    const dead = state.sites.filter((hook) => hook.routesAtPush === total);
+    if (dead.length === 0)
+        return;
+    const detail = dead.map((hook) => `  ${hook.kind}()  at ${hook.site ?? "<unknown>"}`).join("\n");
+    const message = `[nifra] ${dead.length} order-scoped hook(s) apply to no route - they were added after the ` +
+        `last route was registered, and register() snapshots the chain into each route as it is ` +
+        `declared:\n${detail}\nMove them before the routes they should cover. App-global hooks ` +
+        `(onRequest/onResponse) are not order-scoped and can be added at any time.`;
+    if (state.policy === "error")
+        throw new FrameworkError("UNUSED_SCOPED_HOOKS", message);
+    if (state.hasCustomLogger)
+        logger.warn(message);
+    else
+        console.warn(message);
+};
 /**
  * The inline server. Routes are chainable and fully type-inferred. `derive`/
  * `decorate` extend the handler context (`Ctx`) for routes defined *after* them,
@@ -380,6 +395,11 @@ export class Server {
         this.defaultOnValidationError = options.onValidationError;
         this.bunServer = undefined;
         this.sealed = false;
+        // Guarded so a production define strips the call, leaving `beginHookAudit`/`hookAudit` unreferenced
+        // for the bundler to eliminate; a non-bundled production run skips it the same way.
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
+            beginHookAudit(this, options.unusedScopedHooks ?? "warn", options.logger !== undefined);
+        }
         this.derives = [];
         this.decorations = {};
         this.beforeHandleHooks = [];
@@ -439,16 +459,34 @@ export class Server {
         this.fetchMounts.sort((a, b) => b.path.length - a.path.length);
         return this;
     }
-    /** Add a per-request, computed context extension for subsequent routes. */
+    /**
+     * Add a per-request, computed context extension. Order-scoped: it is snapshotted into every route
+     * declared *after* this call, and reaches none declared before. One added after the last route
+     * (e.g. on the app returned by a route-registering factory) covers nothing - see
+     * {@link ServerOptions.unusedScopedHooks}.
+     *
+     * Returning a `status(...)` (or a `Response`) instead of an extension ends the request there - the
+     * guard shape, and the cheap one: it renders as plain data on the same lane a handler's return
+     * takes, where `throw new Response(...)` pays ~40% of the rejection lane to build the object. That
+     * branch is control flow, so it does not widen the derived context type.
+     */
     derive(fn) {
         this.assertConfigurable("derive()");
         this.derives.push(fn);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "derive");
         return this;
     }
-    /** Add a static context value for subsequent routes. */
+    /**
+     * Add a static context value. Order-scoped: captured by every route declared *after* this call, and
+     * by none before; one added after the last route reaches nothing
+     * (see {@link ServerOptions.unusedScopedHooks}).
+     */
     decorate(key, value) {
         this.assertConfigurable("decorate()");
         this.decorations[key] = value;
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "decorate");
         return this;
     }
     /**
@@ -462,20 +500,31 @@ export class Server {
         this.nodeRequestHooksComplete = false;
         return this;
     }
-    /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
+    /**
+     * Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped:
+     * it is snapshotted into every route declared *after* this call and covers none declared before, so
+     * one added after the last route reaches nothing (see {@link ServerOptions.unusedScopedHooks}).
+     */
     beforeHandle(fn) {
         this.assertConfigurable("beforeHandle()");
         this.beforeHandleHooks.push(fn);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "beforeHandle");
         return this;
     }
     /**
      * Wrap the matched route lifecycle for subsequent routes. This is intentionally generic over the
      * route output, so wrappers like async context storage do not force Node's direct JSON path through
      * a Web `Response`. The first registered wrapper is outermost.
+     *
+     * Order-scoped: captured by every route declared *after* this call, none before; one added after the
+     * last route reaches nothing (see {@link ServerOptions.unusedScopedHooks}).
      */
     around(fn) {
         this.assertConfigurable("around()");
         this.aroundHooks.push(fn);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "around");
         return this;
     }
     /**
@@ -494,6 +543,8 @@ export class Server {
         }
         // JS timers wrap larger delays to ~1ms, which would unexpectedly deny every effect.
         this.capabilityInterceptors.push(Object.freeze({ interceptor, timeoutMs: Math.min(timeoutMs, 2_147_483_647) }));
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "aroundCapability");
         return this;
     }
     /** Observe token-only admission/execution lifecycle events for subsequent capability routes. */
@@ -505,16 +556,24 @@ export class Server {
         this.capabilityObservers.push(observer);
         return this;
     }
-    /** Transform the handler's result before it is serialized. Order-scoped. */
+    /** Transform the handler's result before it is serialized. Order-scoped: captured by routes declared
+     * *after* this call, none before; one added after the last route reaches nothing (see
+     * {@link ServerOptions.unusedScopedHooks}). */
     afterHandle(fn) {
         this.assertConfigurable("afterHandle()");
         this.afterHandleHooks.push(fn);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "afterHandle");
         return this;
     }
-    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
+    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500).
+     * Order-scoped: captured by routes declared *after* this call, none before; one added after the last
+     * route reaches nothing (see {@link ServerOptions.unusedScopedHooks}). */
     onError(fn) {
         this.assertConfigurable("onError()");
         this.onErrorHooks.push(fn);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordScopedHook(this, this.catalog.size, "onError");
         return this;
     }
     /** Transform every outgoing response - success, error, 404, 405, short-circuit. Global. */
@@ -556,19 +615,33 @@ export class Server {
      * hook owns part of the header state - into a hook that runs in the right order. */
     addStaticResponseHeaders(record) {
         if (this.onResponseHooks.length > 0) {
-            return this.onResponseHeaders((headers) => {
-                for (const name of Object.keys(record)) {
-                    if (!headers.has(name))
-                        headers.set(name, record[name]);
-                }
-            });
+            const observerHeaders = this.onResponseHeaders;
+            if (observerHeaders !== undefined) {
+                observerHeaders.call(this, (headers) => {
+                    for (const name of Object.keys(record)) {
+                        if (!headers.has(name))
+                            headers.set(name, record[name]);
+                    }
+                });
+                return this;
+            }
+            // Route the hook through the same seam the static tier uses. On a framework response (headers
+            // stamped mutable) it applies the defaults in place and returns the SAME object, so the
+            // serialized-body marker survives for later `onResponseBody`/`onResponseRaw` observers and the
+            // Node writer; reconstructing a `Response` here would strip that marker and reclassify the Node
+            // outcome from `json` to a generic `response`. A guarded foreign response takes its clone path.
+            const statics = buildStaticResponseHeaders(record);
+            this.onResponseHooks.push((response) => applyStaticResponseHeaders(response, statics));
+            this.onNodeResponseHooks.push(undefined);
+            this.nodeResponseHooksComplete = false;
+            return this;
         }
         const merged = this.staticResponseHeaders === undefined
             ? record
             : { ...this.staticResponseHeaders.record, ...record };
         this.staticResponseHeaders = buildStaticResponseHeaders(merged);
         const statics = this.staticResponseHeaders;
-        this.wrapWebResponse = (response) => applyStaticResponseHeaders(response, statics);
+        this.wrapWebResponse = (response) => applyStaticResponseHeaders(webResponseOf(response), statics);
         this.webResponseTimeout = () => applyStaticResponseHeaders(RESPONSE_TIMEOUT(), statics);
         return this;
     }
@@ -579,58 +652,14 @@ export class Server {
         }
         return this.responseBodyTag;
     }
-    /**
-     * Register a response transform for raw/streamed Responses. Framework-serialized payloads stay on
-     * the body tier; this hook is only entered for untagged Responses (streams, proxied fetches, and
-     * framework-generated error responses). A no-op native twin keeps buffered JSON on the direct lane.
-     */
-    onResponseRaw(fn) {
-        this.assertConfigurable("onResponseRaw()");
-        this.enableResponseBodyTagging();
-        this.onResponseHooks.push(webResponseRawHook(fn, this.responseBodyOwners));
-        this.onNodeResponseHooks.push(() => undefined);
-        return this;
-    }
-    /**
-     * Register a PORTABLE header-only response hook - one implementation, fast on every runtime.
-     *
-     * The hook receives a mutable case-insensitive header view, a minimal request view, and the
-     * status. On the Web serving paths it runs inside the normal `onResponse` walk against the
-     * response's own `Headers` (mutating in place - no clone). On Node it self-pairs as a native
-     * response hook against the outcome's plain header record, so registering one NEVER forces the
-     * Node adapter off its direct socket writer the way a full `onResponse(res: Response)` hook does.
-     * Prefer this over `onResponse` whenever the middleware only reads/writes headers.
-     */
-    onResponseHeaders(fn) {
-        this.assertConfigurable("onResponseHeaders()");
-        this.onResponseHooks.push(webResponseHeadersHook(fn));
-        this.onNodeResponseHooks.push((response, req) => fn(recordHeadersView(response), req, response.status));
-        return this;
-    }
-    /**
-     * Register a PORTABLE post-serialization body hook - the payload tier. The hook receives the
-     * FINAL framework-serialized bytes (plus the mutable header view and status) and may return
-     * replacement bytes; `undefined` keeps the body. On the Node direct writer the bytes come
-     * straight off the outcome record; on the Web serving paths they ride the framework-built
-     * Response as a tag, so no body stream is ever drained on any runtime. A handler-returned raw
-     * `Response` (proxied fetch, SSE, streamed SSR) is skipped by contract - transforming those is
-     * what the full `onResponse` hook is for.
-     */
-    onResponseBody(fn) {
-        this.assertConfigurable("onResponseBody()");
-        this.enableResponseBodyTagging();
-        this.onResponseHooks.push(webResponseBodyHook(fn, this.responseBodyOwners));
-        this.onNodeResponseHooks.push((response, req) => {
-            const body = response.body;
-            if (body === null)
-                return undefined;
-            const out = fn(body, recordHeadersView(response), req, response.status);
-            if (out instanceof Promise)
-                return out.then((replaced) => applyBodyReplacement(response, replaced));
-            applyBodyReplacement(response, out);
-            return undefined;
-        });
-        return this;
+    responseObserverMethods() {
+        const methods = this;
+        if (typeof methods.onResponseHeaders !== "function" ||
+            typeof methods.onResponseBody !== "function" ||
+            typeof methods.onResponseRaw !== "function") {
+            throw new TypeError("response observation requires `.use(responseObserver())` or an observer-enabled middleware");
+        }
+        return methods;
     }
     /** Observe the terminal response after all transformations. Observers are ordered and fail-open. */
     onResponseFinalized(fn) {
@@ -676,6 +705,15 @@ export class Server {
         }
         this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"));
         this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"));
+        const responseObserver = arg[INSTALL_RESPONSE_OBSERVER];
+        if (responseObserver !== undefined) {
+            if (typeof responseObserver !== "object" ||
+                responseObserver === null ||
+                typeof responseObserver.install !== "function") {
+                throw new TypeError("response observer middleware has an invalid runtime");
+            }
+            this[INSTALL_RESPONSE_OBSERVER](responseObserver);
+        }
         if (arg.onRequest !== undefined) {
             this.assertConfigurable("onRequest()");
             this.onRequestHooks.push(arg.onRequest);
@@ -709,11 +747,11 @@ export class Server {
         if (arg.responseHeaders !== undefined)
             this.responseHeaders(arg.responseHeaders);
         if (arg.onResponseHeaders !== undefined)
-            this.onResponseHeaders(arg.onResponseHeaders);
+            this.responseObserverMethods().onResponseHeaders(arg.onResponseHeaders);
         if (arg.onResponseBody !== undefined)
-            this.onResponseBody(arg.onResponseBody);
+            this.responseObserverMethods().onResponseBody(arg.onResponseBody);
         if (arg.onResponseRaw !== undefined)
-            this.onResponseRaw(arg.onResponseRaw);
+            this.responseObserverMethods().onResponseRaw(arg.onResponseRaw);
         if (arg.onResponseFinalized !== undefined)
             this.onResponseFinalized(arg.onResponseFinalized);
         if (arg.onError !== undefined)
@@ -820,6 +858,9 @@ export class Server {
         // Boot-time guard: the WS runtime is a subpath (`@nifrajs/core/ws`) so no-WebSocket apps don't
         // bundle it. Registration is the loud, early failure point - never the first connection.
         const runtime = requireWsRuntime(this.wsRuntime);
+        if (handler.validateSend === true && handler.sendSchema === undefined) {
+            throw new RouteConfigError("INVALID_WS_SEND_VALIDATION", `route WS ${path}: validateSend requires sendSchema`);
+        }
         this.topics ??= runtime.createTopics();
         // A `messageSchema` wraps `message` with validation once, here - every adapter then dispatches
         // already-validated, typed messages (Bun/Deno/Node/Workers) with no per-adapter code.
@@ -872,6 +913,8 @@ export class Server {
     }
     prepareRoute(method, path, schema, handler) {
         const pattern = compileRoutePattern(path);
+        // Resolved here, once: `undefined` past this point means the route declared `"unlimited"`, NOT
+        // "nothing declared". Readers fall back to UNLIMITED_BODY_BYTES accordingly.
         let bodyLimit = this.maxBodyBytes;
         const invalidBodyLimit = (message) => {
             throw new RouteConfigError("INVALID_BODY_LIMIT", `route ${method} ${path}: ${message}`);
@@ -884,6 +927,12 @@ export class Server {
                 schema.bodyLimitReason.trim().length === 0) {
                 invalidBodyLimit('bodyLimit: "unlimited" requires a non-empty bodyLimitReason');
             }
+            if (schema.body !== undefined) {
+                invalidBodyLimit('bodyLimit: "unlimited" cannot be used with a body schema; use a finite cap');
+            }
+            if (schema.idempotency !== undefined) {
+                invalidBodyLimit('bodyLimit: "unlimited" cannot be used with idempotency');
+            }
             bodyLimit = undefined;
         }
         else if (schema?.bodyLimit !== undefined) {
@@ -981,12 +1030,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, bodyLimit ?? this.maxBodyBytes)
+            ? this.buildFusedBodyRunner(handler, schema.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? UNLIMITED_BODY_BYTES)
             : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
-            ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? this.maxBodyBytes)
+            ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? UNLIMITED_BODY_BYTES)
             : fusedQuery
-                ? this.buildFusedQueryWeb(handler, hasDecorations ? routeDecorations : undefined, schema.query, bodyLimit ?? this.maxBodyBytes)
+                ? this.buildFusedQueryWeb(handler, hasDecorations ? routeDecorations : undefined, schema.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                 : fusedBody
                     ? this.buildFusedBodyWeb(fusedBodyRunner)
                     : undefined;
@@ -1094,7 +1143,18 @@ export class Server {
             });
             routeAssurance.push(Object.freeze(declared));
         }
-        if (schema?.body !== undefined) {
+        // Two ways a route proves its body is bounded, both enforced by the core at read time:
+        // `schema.body` (the validated read is bounded) and an explicit finite `schema.bodyLimit` (the
+        // transport cap shadows every reader, including a raw `c.req.body` stream that a Content-Length
+        // middleware cannot bound).
+        // `bodyLimit: "unlimited"` is rejected above for schema and idempotency routes. The remaining
+        // exemption is schema-less streaming/upload work, so it publishes NOTHING: there is no finite
+        // framework byte ceiling for assurance to attest and the application protocol owns that bound.
+        // The server-wide `maxBodyBytes` default is not evidence either. It applies to every route
+        // whether or not anyone thought about it, so publishing it would make the id pass everywhere and
+        // prove nothing; this evidence marks a bound the route chose.
+        const unlimitedBody = schema?.bodyLimit === "unlimited";
+        if (!unlimitedBody && (schema?.body !== undefined || typeof schema?.bodyLimit === "number")) {
             routeAssurance.push(Object.freeze({
                 id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
                 source: "route-schema",
@@ -1129,6 +1189,29 @@ export class Server {
         this.assertConfigurable("responseContract()");
         this.responseContractRuntime = runtime;
     }
+    /** @internal Symbol-keyed install seam for the response observer plugin. */
+    [INSTALL_RESPONSE_OBSERVER](runtime) {
+        this.assertConfigurable("responseObserver()");
+        const methods = runtime.install({
+            assertConfigurable: (operation) => this.assertConfigurable(operation),
+            addResponseHook: (web, node) => {
+                this.onResponseHooks.push(web);
+                this.onNodeResponseHooks.push(node);
+                if (node === undefined)
+                    this.nodeResponseHooksComplete = false;
+            },
+            enableResponseBodyTagging: () => {
+                if (this.responseBodyTag === undefined) {
+                    this.responseBodyTag = Object.freeze({});
+                    this.responseBodyOwners.add(this.responseBodyTag);
+                }
+                return this.responseBodyTag;
+            },
+            responseBodyOwners: () => this.responseBodyOwners,
+        });
+        Object.assign(this, methods);
+        return methods;
+    }
     /** @internal Symbol-keyed install seam for the `idempotency()` plugin. Off the public typed surface. */
     [INSTALL_IDEMPOTENCY](runtime) {
         this.assertConfigurable("idempotency()");
@@ -1259,13 +1342,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, entry.bodyLimit ?? this.maxBodyBytes)
+            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
             : 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, entry.bodyLimit ?? this.maxBodyBytes)
-                : this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler), entry.bodyLimit ?? this.maxBodyBytes);
+                ? this.buildFusedQueryWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, entry.schema?.query, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+                : this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler), entry.bodyLimit ?? UNLIMITED_BODY_BYTES);
         return {
             ...route,
             entry: {
@@ -1305,6 +1388,10 @@ export class Server {
         return this.fetchSource(req, platform);
     }
     fetchSource(source, platform) {
+        // Seal once on the first request so test servers (no `listen()`) still get the dead-hook check.
+        // After that it is a single boolean read - the per-request cost the option promises to keep at zero.
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            sealHookAudit(this, this.catalog.size, this.logger);
         // Off path (default): straight through - one property check, no closure, no promise.
         if (this.capacityGate === undefined)
             return this.fetchSourceInner(source, platform);
@@ -1379,6 +1466,42 @@ export class Server {
         release();
         return outcome;
     }
+    /**
+     * Select a mounted handler's native Node lane without materializing a Web Request. This is an
+     * adapter seam, not a second lifecycle: any app-wide behavior that the ordinary mount path would
+     * run makes the capability ineligible and the caller falls back to `resolveNodeSource`. Typed
+     * routes keep precedence exactly as `routeAndRun` does, including the existing mount behavior for
+     * a path whose registered route rejects this method.
+     */
+    [RESOLVE_NODE_MOUNT](source) {
+        if (this.onRequestHooks.length > 0 ||
+            this.onResponseHooks.length > 0 ||
+            this.onResponseFinalizedHooks.length > 0 ||
+            this.capacityGate !== undefined ||
+            this.staticResponseHeaders !== undefined ||
+            this.requestTimeoutMs !== 0 ||
+            this.acceptInboundDeadlines ||
+            this.clientIpTrust !== undefined) {
+            return undefined;
+        }
+        const parts = source.urlParts ?? urlPartsOf(source.url);
+        const match = this.catalog.find(source.method, parts.pathname);
+        if (match.found)
+            return undefined;
+        for (const mount of this.fetchMounts) {
+            if (!underMountPrefix(parts.pathname, mount.path))
+                continue;
+            const candidate = mount.handler[NODE_NATIVE_MOUNT];
+            return typeof candidate === "function"
+                ? {
+                    handler: candidate,
+                    path: mount.path,
+                    stripPrefix: mount.stripPrefix,
+                }
+                : undefined;
+        }
+        return undefined;
+    }
     /**
      * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` - the
      * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici
@@ -1391,6 +1514,9 @@ export class Server {
         return this.resolveNodeSource(req, platform);
     }
     resolveNodeSource(source, platform, suppliedRuntime) {
+        // Seal once on the Node-direct lane too - it can bypass `fetchSource` entirely (hookless outcome).
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            sealHookAudit(this, this.catalog.size, this.logger);
         // A paired header-only native hook can preserve the Node-direct JSON/body outcome for successful
         // responses. Arbitrary onResponse transforms need a real Web Response, but a buffered outcome can
         // be materialized with a direct-write marker and return to the socket path when the hook mutates
@@ -1915,15 +2041,18 @@ export class Server {
                     : wrapResponse(mounted);
             }
             if (match.reason === "method-not-allowed") {
-                return wrapResponse(jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }));
+                return wrapResponse(
+                // Lowercase on purpose: a plain render's headers go into the node outcome record verbatim,
+                // and every other name in that record is lowercase (the Web lane normalizes either way).
+                plainError(405, "method_not_allowed", { allow: match.allowed.join(", ") }));
             }
-            return wrapResponse(jsonError(404, "not_found"));
+            return wrapResponse(plainError(404, "not_found"));
         }
         // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
         // already did and made every plain dynamic route pay for unrelated static path bytes.
         const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
         if (params === null) {
-            return wrapResponse(jsonError(400, "malformed_path"));
+            return wrapResponse(plainError(400, "malformed_path"));
         }
         return this.runMatched(source, platform, match.payload, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
@@ -1958,7 +2087,7 @@ export class Server {
         // 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: entry.bodyLimit ?? this.maxBodyBytes,
+                maxBodyBytes: entry.bodyLimit ?? UNLIMITED_BODY_BYTES,
                 runLanes: (buffered, plat, ent, prm, srch) => this.idempotencyRunLanes(buffered, plat, ent, prm, srch),
             });
         }
@@ -1984,7 +2113,7 @@ export class Server {
                 ? undefined
                 : admitDeadline(source.headers, this.deadlineAdmissionOptions);
         if (admission !== undefined && !admission.ok) {
-            return wrapResponse(jsonError(admission.status, admission.reason));
+            return wrapResponse(plainError(admission.status, admission.reason));
         }
         const effectiveTimeoutMs = admission?.timeoutMs ?? 0;
         // Only allocate a controller for a finite budget; the historical no-timeout path remains
@@ -2009,7 +2138,7 @@ export class Server {
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
         if (controller !== undefined && outcome instanceof Promise) {
             const timedOut = admission?.inherited === true
-                ? () => wrapResponse(jsonError(504, "deadline_exceeded"))
+                ? () => wrapResponse(plainError(504, "deadline_exceeded"))
                 : onTimeout;
             return this.withTimeout(outcome, controller, timedOut, Math.max(0, Math.ceil(budget.remaining())));
         }
@@ -2040,9 +2169,13 @@ export class Server {
     contextlessBareError(err, source, params, search, signal, budget, platform, wrapResponse) {
         if (err instanceof Response)
             return wrapResponse(err);
+        // Handed over as the plain data it is: `wrapResponse` renders it on the JSON lane (no `Response`
+        // built on Node). There is no context here by construction, so there is no `c.set` to merge.
+        if (isResponseResult(err))
+            return wrapResponse(err);
         const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes, this.protoPoisoning);
         this.logRequestError(err, ctx);
-        return wrapResponse(jsonError(500, "internal_error"));
+        return wrapResponse(plainError(500, "internal_error"));
     }
     /**
      * The synchronous fast path selected by a route's execution plan: apply static decorations, call the
@@ -2062,11 +2195,11 @@ export class Server {
             result = entry.handler(ctx);
         }
         catch (err) {
-            return this.bareError(err, ctx, wrapResponse);
+            return this.bareError(err, ctx, finalize, wrapResponse);
         }
         if (result instanceof Promise) {
             // Async handler on an otherwise-bare route: finish on a microtask, with the same error handling.
-            return result.then((value) => finalize(value, responseSet(ctx)), (err) => this.bareError(err, ctx, wrapResponse));
+            return result.then((value) => finalize(value, responseSet(ctx)), (err) => this.bareError(err, ctx, finalize, wrapResponse));
         }
         return finalize(result, responseSet(ctx));
     }
@@ -2080,14 +2213,10 @@ export class Server {
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
     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) => {
-            if (err instanceof Response)
-                return this.wrapWebResponse(err);
-            this.logRequestError(err, ctx);
-            return this.wrapWebResponse(jsonError(500, "internal_error"));
-        };
+        // Same thrown-value contract as the generic lane (`bare-error-lane.ts` via `bareError`); the fused
+        // lane only injects its renderer, so a thrown `status(...)` and the flat 500 fold in static headers
+        // through `wrapWebResponse`. One source of truth for the error surface, no per-lane copy to drift.
+        const logError = (err, ctx) => this.bareError(err, ctx, (result, set) => this.wrapWebResponse(toResponse(result, set)), this.wrapWebResponse);
         if (contextless && decorations === undefined) {
             // `() => ...` can't observe the context - skip allocating one entirely (errors still build
             // one for the structured log, exactly like runContextlessBare).
@@ -2133,7 +2262,7 @@ export class Server {
      * 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, maxBodyBytes) {
-        const logError = (err, ctx, wrapResponse) => this.bareError(err, ctx, wrapResponse);
+        const logError = (err, ctx, finalize, wrapResponse) => this.bareError(err, ctx, finalize, wrapResponse);
         const runHandler = (ctx, finalize, wrapResponse) => {
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
@@ -2142,7 +2271,7 @@ export class Server {
                 output = handler(ctx);
             }
             catch (err) {
-                return logError(err, ctx, wrapResponse);
+                return logError(err, ctx, finalize, wrapResponse);
             }
             if (output instanceof Promise) {
                 return output.then((result) => {
@@ -2150,20 +2279,20 @@ export class Server {
                         return finalize(result, responseSet(ctx), ctx);
                     }
                     catch (err) {
-                        return logError(err, ctx, wrapResponse);
+                        return logError(err, ctx, finalize, wrapResponse);
                     }
-                }, (err) => logError(err, ctx, wrapResponse));
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
             }
             try {
                 return finalize(output, responseSet(ctx), ctx);
             }
             catch (err) {
-                return logError(err, ctx, wrapResponse);
+                return logError(err, ctx, finalize, wrapResponse);
             }
         };
         const runValidated = (result, ctx, finalize, wrapResponse) => {
             if (result.issues !== undefined)
-                return wrapResponse(validationError(result.issues));
+                return wrapResponse(plainValidationError(result.issues));
             ctx.body = result.value;
             return runHandler(ctx, finalize, wrapResponse);
         };
@@ -2173,7 +2302,7 @@ export class Server {
                 validation = bodySchema["~standard"].validate(parsed);
             }
             catch (err) {
-                return logError(err, ctx, wrapResponse);
+                return logError(err, ctx, finalize, wrapResponse);
             }
             if (validation instanceof Promise) {
                 return validation.then((settled) => {
@@ -2181,15 +2310,15 @@ export class Server {
                         return runValidated(settled, ctx, finalize, wrapResponse);
                     }
                     catch (err) {
-                        return logError(err, ctx, wrapResponse);
+                        return logError(err, ctx, finalize, wrapResponse);
                     }
-                }, (err) => logError(err, ctx, wrapResponse));
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
             }
             try {
                 return runValidated(validation, ctx, finalize, wrapResponse);
             }
             catch (err) {
-                return logError(err, ctx, wrapResponse);
+                return logError(err, ctx, finalize, wrapResponse);
             }
         };
         return (source, params, search, signal, budget, platform, nativeContext, finalize, wrapResponse) => {
@@ -2197,7 +2326,7 @@ export class Server {
                 ? 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, maxBodyBytes, finish, wrapResponse, (err) => logError(err, ctx, wrapResponse));
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, finish, wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse));
         };
     }
     /** Web adapter wrapper for the shared body runner. Node passes its native finalizer directly through
@@ -2213,14 +2342,10 @@ export class Server {
      * `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, 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) => {
-            if (err instanceof Response)
-                return this.wrapWebResponse(err);
-            this.logRequestError(err, ctx);
-            return this.wrapWebResponse(jsonError(500, "internal_error"));
-        };
+        // Same thrown-value contract as the generic lane (`bare-error-lane.ts` via `bareError`); the fused
+        // lane only injects its renderer, so a thrown `status(...)` and the flat 500 fold in static headers
+        // through `wrapWebResponse`. One source of truth for the error surface, no per-lane copy to drift.
+        const logError = (err, ctx) => this.bareError(err, ctx, (result, set) => this.wrapWebResponse(toResponse(result, set)), this.wrapWebResponse);
         const runHandler = (ctx, value) => {
             ctx.query = value;
             let result;
@@ -2250,19 +2375,19 @@ export class Server {
             }
             if (validation instanceof Promise) {
                 return validation.then((settled) => settled.issues !== undefined
-                    ? this.wrapWebResponse(validationError(settled.issues))
+                    ? this.wrapWebResponse(plainValidationError(settled.issues))
                     : runHandler(ctx, settled.value), (err) => logError(err, ctx));
             }
             if (validation.issues !== undefined)
-                return this.wrapWebResponse(validationError(validation.issues));
+                return this.wrapWebResponse(plainValidationError(validation.issues));
             return runHandler(ctx, validation.value);
         };
     }
-    bareError(err, ctx, wrapResponse) {
-        if (err instanceof Response)
-            return wrapResponse(err);
-        this.logRequestError(err, ctx);
-        return wrapResponse(jsonError(500, "internal_error"));
+    bareError(err, ctx, finalize, wrapResponse) {
+        // The thrown-value contract lives in `bare-error-lane.ts`, one source of truth for both this
+        // lane and the fused body runner. `responseSet` and the logger are injected because they reach
+        // into class state; the closure is allocated only on the throw path, never on the hot lane.
+        return renderBareError(err, ctx, finalize, wrapResponse, responseSet, (e, c) => this.logRequestError(e, c));
     }
     // @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)
@@ -2296,27 +2421,7 @@ export class Server {
     // @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, 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, maxBodyBytes, onParsed, wrapResponse, onError) {
-        const contentType = headerOf(source, "content-type") ?? "";
-        if (contentType !== "application/json" && !contentType.includes("application/json")) {
-            if (isUrlEncodedForm(contentType)) {
-                return readBoundedForm(source, maxBodyBytes).then((form) => (form instanceof Response ? wrapResponse(form) : onParsed(form)), onError);
-            }
-            return Promise.resolve(wrapResponse(jsonError(415, "unsupported_media_type")));
-        }
-        // 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, maxBodyBytes, (parsed) => (parsed instanceof Response ? wrapResponse(parsed) : onParsed(parsed)), onError);
-        }
-        catch (err) {
-            return Promise.resolve(onError(err));
-        }
+        return readBodyFramed(source, entry.bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
     }
     /** Validate + run the handler for the bodyOnly path - shared by the inline fast path and the
      * streaming fallback. A method (not per-request closures) so the hot path allocates nothing
@@ -2371,13 +2476,13 @@ export class Server {
                 if (validation instanceof Promise) {
                     return validation.then((settled) => {
                         if (settled.issues !== undefined)
-                            return wrapResponse(validationError(settled.issues));
+                            return wrapResponse(plainValidationError(settled.issues));
                         ctx.body = settled.value;
                         return this.executeHandler(entry, ctx, finalize);
                     });
                 }
                 if (validation.issues !== undefined)
-                    return wrapResponse(validationError(validation.issues));
+                    return wrapResponse(plainValidationError(validation.issues));
                 ctx.body = validation.value;
                 return this.executeHandler(entry, ctx, finalize);
             }
@@ -2386,18 +2491,18 @@ export class Server {
                 if (validation instanceof Promise) {
                     return validation.then((settled) => {
                         if (settled.issues !== undefined)
-                            return wrapResponse(validationError(settled.issues));
+                            return wrapResponse(plainValidationError(settled.issues));
                         ctx.query = settled.value;
                         return this.executeHandler(entry, ctx, finalize, wrapResponse);
                     }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
                 }
                 if (validation.issues !== undefined)
-                    return wrapResponse(validationError(validation.issues));
+                    return wrapResponse(plainValidationError(validation.issues));
                 ctx.query = validation.value;
                 return this.executeHandler(entry, ctx, finalize, wrapResponse);
             }
         }
-        return wrapResponse(validationError(originalIssues));
+        return wrapResponse(plainValidationError(originalIssues));
     }
     applyBodyValidation(entry, result, ctx, finalize, wrapResponse) {
         if (result.issues !== undefined) {
@@ -2409,7 +2514,7 @@ export class Server {
                 }
                 return this.handleValidationErrorRecovery(entry, recovery, ctx, finalize, wrapResponse, result.issues, "body");
             }
-            return wrapResponse(validationError(result.issues));
+            return wrapResponse(plainValidationError(result.issues));
         }
         ctx.body = result.value;
         return this.executeHandler(entry, ctx, finalize);
@@ -2452,7 +2557,7 @@ export class Server {
                 }
                 return this.handleValidationErrorRecovery(entry, recovery, ctx, finalize, wrapResponse, result.issues, "query");
             }
-            return wrapResponse(validationError(result.issues));
+            return wrapResponse(plainValidationError(result.issues));
         }
         ctx.query = result.value;
         return this.executeHandler(entry, ctx, finalize, wrapResponse);
@@ -2747,6 +2852,8 @@ export class Server {
                 if (extension instanceof Promise) {
                     return this.continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, i, extension);
                 }
+                if (isDeriveEarlyExit(extension))
+                    return finalize(extension, responseSet(ctx));
                 Object.assign(ctx, extension);
             }
             for (let i = 0; i < entry.beforeHandle.length; i++) {
@@ -2774,6 +2881,8 @@ export class Server {
             if (extension instanceof Promise) {
                 return this.continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, 0, extension);
             }
+            if (isDeriveEarlyExit(extension))
+                return finalize(extension, responseSet(ctx));
             Object.assign(ctx, extension);
             const outcome = entry.beforeHandle[0](ctx);
             if (outcome instanceof Promise) {
@@ -2802,10 +2911,16 @@ export class Server {
     }
     async continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, firstIndex, first) {
         try {
-            Object.assign(ctx, await first);
+            const settled = await first;
+            if (isDeriveEarlyExit(settled))
+                return finalize(settled, responseSet(ctx));
+            Object.assign(ctx, settled);
             for (let i = firstIndex + 1; i < entry.derives.length; i++) {
-                const extension = entry.derives[i](ctx);
-                Object.assign(ctx, extension instanceof Promise ? await extension : extension);
+                const raw = entry.derives[i](ctx);
+                const extension = raw instanceof Promise ? await raw : raw;
+                if (isDeriveEarlyExit(extension))
+                    return finalize(extension, responseSet(ctx));
+                Object.assign(ctx, extension);
             }
             return await this.runLifecycleHooksAsync(entry, ctx, finalize, wrapResponse);
         }
@@ -2909,7 +3024,7 @@ export class Server {
                 path: pathnameOf(ctx.req.url),
                 detail: outcome.message,
             });
-            return wrapResponse(jsonError(500, "internal_error"));
+            return wrapResponse(plainError(500, "internal_error"));
         }
         if (outcome.kind === "warn") {
             this.logger.warn("response contract", {
@@ -2920,14 +3035,33 @@ export class Server {
         }
         return finalize(outcome.value, responseSet(ctx));
     }
-    async handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
+    /** Synchronous by design, and `MaybePromise` rather than `Promise` for the same reason: control flow
+     * out of a lifecycle stage must not cost a promise. An `async` method allocates one and defers the
+     * result a microtask even when every branch it takes returns immediately, which is the common case
+     * here - a thrown `status(...)`/`Response`, or a route with no `onError` hook at all. Only the hook
+     * loop, which may await, drops into {@link runErrorHooks}. */
+    handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
         // A *thrown* Response is deliberate control flow, not an error - a guard throws a redirect/401,
         // an action throws an error page. Return it as-is (Remix/SvelteKit semantics); don't run onError
         // or log it as a 500. This is what makes `throw redirect(...)` / `requireSession(...)` work from
         // any handler or loader.
         if (err instanceof Response)
             return wrapResponse(err);
-        // onError hooks may return a custom response; otherwise the default 500 stands.
+        // Same rule for a thrown `status(...)`, but through `finalize` rather than `wrapResponse`: the
+        // value is still plain data, so the ordinary JSON lane renders it and no `Response` is built.
+        if (isResponseResult(err))
+            return finalize(err, responseSet(ctx));
+        if (entry.onError.length === 0) {
+            // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
+            // (redacting) logger. Body-read failures and around-hook failures land here too.
+            this.logRequestError(err, ctx);
+            return wrapResponse(plainError(500, "internal_error"));
+        }
+        return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse);
+    }
+    /** The `onError` chain, split off {@link handleLifecycleError} so its `await` costs only the routes
+     * that registered a hook. A hook may return a custom response; otherwise the default 500 stands. */
+    async runErrorHooks(entry, err, ctx, finalize, wrapResponse) {
         // 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++) {
@@ -2936,49 +3070,33 @@ export class Server {
             if (handled !== undefined)
                 return finalize(handled, responseSet(ctx));
         }
-        // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
-        // (redacting) logger. Body-read failures and around-hook failures land here too.
         this.logRequestError(err, ctx);
-        return wrapResponse(jsonError(500, "internal_error"));
+        return wrapResponse(plainError(500, "internal_error"));
     }
     /** 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),
-            name: err instanceof Error ? err.name : "Error",
-            // `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 === "none" ? {} : { detail: err instanceof Error ? err.message : String(err) }),
-            ...(detail === "full" && err instanceof Error ? { stack: err.stack } : {}),
-        });
+        emitRequestErrorLog(this.logger, this.errorLogDetail, err, ctx);
     }
     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, entry.bodyLimit ?? this.maxBodyBytes);
-            if (json instanceof Response)
+            const json = await this.readBoundedJson(req, entry.bodyLimit ?? UNLIMITED_BODY_BYTES);
+            if (isResponseResult(json))
                 return json;
             parsed = json;
         }
         else if (isUrlEncodedForm(contentType)) {
-            const form = await readBoundedForm(req, entry.bodyLimit ?? this.maxBodyBytes);
-            if (form instanceof Response)
+            const form = await readBoundedForm(req, entry.bodyLimit ?? UNLIMITED_BODY_BYTES);
+            if (isResponseResult(form))
                 return form;
             parsed = form;
         }
         else {
             // multipart/form-data (file uploads) stays 415 on the schema path by design - files don't
             // fit a value schema; use a schema-less route + @nifrajs/uploads helpers for those.
-            return jsonError(415, "unsupported_media_type");
+            return plainError(415, "unsupported_media_type");
         }
         const validation = entry.schema.body["~standard"].validate(parsed);
         const result = validation instanceof Promise ? await validation : validation;
@@ -3003,7 +3121,7 @@ export class Server {
         }
         const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError;
         if (hook === undefined)
-            return validationError(result.issues);
+            return plainValidationError(result.issues);
         const attempted = hook(result.issues, ctx, kind);
         if (attempted instanceof Promise) {
             return attempted.then((recovery) => this.finishLifecycleValidationRecovery(entry, kind, result.issues, recovery, assign));
@@ -3012,7 +3130,7 @@ export class Server {
     }
     finishLifecycleValidationRecovery(entry, kind, issues, recovery, assign) {
         if (recovery === undefined)
-            return validationError(issues);
+            return plainValidationError(issues);
         if (recovery instanceof Response)
             return recovery;
         const schema = kind === "body"
@@ -3026,13 +3144,13 @@ export class Server {
         if (retried instanceof Promise) {
             return retried.then((settled) => {
                 if (settled.issues !== undefined)
-                    return validationError(settled.issues);
+                    return plainValidationError(settled.issues);
                 assign(settled.value);
                 return undefined;
             });
         }
         if (retried.issues !== undefined)
-            return validationError(retried.issues);
+            return plainValidationError(retried.issues);
         assign(retried.value);
         return undefined;
     }
@@ -3192,6 +3310,9 @@ export class Server {
             // defined`. Exercised by the @nifrajs/deno suite (which runs on a non-Bun runtime).
             throw new FrameworkError("BUN_REQUIRED", "listen() uses Bun.serve and runs only on Bun. Serve on Node with @nifrajs/node or on Deno with @nifrajs/deno, or hand app.fetch to any fetch-compatible runtime (Workers, etc.).");
         }
+        // Seal before Bun.serve: in `"error"` mode this throws instead of leaving a bound port behind.
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            sealHookAudit(this, this.catalog.size, this.logger);
         // Bun's `Server` is the concrete handle; we expose the stable `RunningServer`
         // subset so the public types don't depend on the ambient `Bun` global. The cast
         // bridges them - Bun's `.port` is `number | undefined` (undefined only for unix