@nifrajs/core 2.8.2 → 2.9.1

package/dist/server/server.js

@@ -9,10 +9,150 @@ import { EMPTY_PARAMS, Router } from "../router/router.js";
 import { assertByteLimit, parseContentLength } from "./body.js";
 import { resolveClientIp } from "./client-ip.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 { fusedRespond, fusedRespondNoSet, toResponse } from "./respond.js";
+import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, knownMutableHeaders, markTaggedResponse, rememberMutableHeaders, taggedResponseBody, taggedResponseOwner, toResponse, } from "./respond.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();
+/**
+ * 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 { jsonLogger } from "./logger.js";
 const functionToString = Function.prototype.toString;
@@ -163,9 +303,34 @@ export class Server {
     onErrorHooks;
     aroundHooks;
     onRequestHooks;
+    onNodeRequestHooks;
+    /** Registration-time eligibility for the Node request twin lane. */
+    nodeRequestHooksComplete;
     onResponseHooks;
+    onNodeResponseHooks;
+    /** Registration-time eligibility for the Node response twin lane. */
+    nodeResponseHooksComplete;
     onResponseFinalizedHooks;
+    /**
+     * Statically declared response headers, merged and prebuilt at registration; `undefined` (the
+     * default) leaves every render path in its original shape. These are NOT response hooks - they are
+     * folded into response construction - so declaring them keeps the fused native lanes an
+     * `onResponse` hook would have disabled.
+     */
+    staticResponseHeaders;
+    /** `wrapResponse` for the Web lanes: identity until static headers exist to fold into the
+     * framework's own error/404/timeout renders, which are built outside the header init. */
+    wrapWebResponse;
+    webResponseTimeout;
+    /** Body/raw response hooks need a framework-payload marker; keep that decision per app. */
+    responseBodyTag;
+    responseBodyOwners;
+    finalizeResponse = (result, set) => toResponse(result, set, this.responseBodyTag, this.staticResponseHeaders);
     responseRequests;
+    /** Original source → request observed by generic request hooks, including in-place mutations. */
+    responseSources;
+    /** Memoized NodeRequestContext per plain-`Request` source - see {@link nodeRequestContextOf}. */
+    nodeContexts;
     /** Names of plugins/middleware already applied via `use` - for idempotent dedupe. */
     appliedPlugins;
     /** Order-scoped evidence captured by routes registered after an assured plugin. */
@@ -223,9 +388,20 @@ export class Server {
         this.onErrorHooks = [];
         this.aroundHooks = [];
         this.onRequestHooks = [];
+        this.onNodeRequestHooks = [];
+        this.nodeRequestHooksComplete = true;
         this.onResponseHooks = [];
+        this.onNodeResponseHooks = [];
+        this.nodeResponseHooksComplete = true;
         this.onResponseFinalizedHooks = [];
+        this.staticResponseHeaders = undefined;
+        this.wrapWebResponse = IDENTITY_RESPONSE;
+        this.webResponseTimeout = RESPONSE_TIMEOUT;
+        this.responseBodyTag = undefined;
+        this.responseBodyOwners = new Set();
         this.responseRequests = new WeakMap();
+        this.responseSources = new WeakMap();
+        this.nodeContexts = new WeakMap();
         this.appliedPlugins = new Set();
         this.activeAssurance = [];
         this.globalAssurance = [];
@@ -256,6 +432,8 @@ export class Server {
     onRequest(fn) {
         this.assertConfigurable("onRequest()");
         this.onRequestHooks.push(fn);
+        this.onNodeRequestHooks.push(undefined);
+        this.nodeRequestHooksComplete = false;
         return this;
     }
     /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
@@ -317,6 +495,115 @@ export class Server {
     onResponse(fn) {
         this.assertConfigurable("onResponse()");
         this.onResponseHooks.push(fn);
+        this.onNodeResponseHooks.push(undefined);
+        this.nodeResponseHooksComplete = false;
+        return this;
+    }
+    /**
+     * Declare response headers with NO per-request decision behind them - and pay nothing for them on
+     * the request path.
+     *
+     * These are not a hook. Because the values are known at wire-up, they are folded into response
+     * construction (one prebuilt init for JSON renders, one record merge where the request set its own
+     * headers), so an app whose only response middleware is static keeps every fused and native lane -
+     * `onResponse`/`onResponseHeaders` disable Bun's fused native routes and, for a full `onResponse`,
+     * the Node direct writer. They apply to EVERY response, exactly as a response hook would: success,
+     * error, 404/405, timeout, and short-circuit alike.
+     *
+     *   app.responseHeaders({ "x-frame-options": "DENY", "referrer-policy": "no-referrer" })
+     *
+     * They are DEFAULTS: a value the request itself produced (`c.set.headers`, or a response hook)
+     * wins, whatever casing it used. Names are lowercased once here; a non-string value, an invalid
+     * name, `__proto__`, or a name the render owns (`content-type`, `content-length`,
+     * `transfer-encoding`, `set-cookie`) throws a `TypeError` at wire-up.
+     *
+     * ORDERING: declarations made before any response hook fold into one static record. One made AFTER
+     * a response hook cannot - the hook may already have written that name and must keep winning - so
+     * it registers as an ordinary `onResponseHeaders` hook instead, preserving registration order at
+     * the cost of the static tier's speed. Declare static headers first.
+     */
+    responseHeaders(record) {
+        this.assertConfigurable("responseHeaders()");
+        return this.addStaticResponseHeaders(normalizeStaticResponseHeaders(record));
+    }
+    /** Wire an already-validated lowercase record into the static tier, or - once a dynamic response
+     * 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 merged = this.staticResponseHeaders === undefined
+            ? record
+            : { ...this.staticResponseHeaders.record, ...record };
+        this.staticResponseHeaders = buildStaticResponseHeaders(merged);
+        const statics = this.staticResponseHeaders;
+        this.wrapWebResponse = (response) => applyStaticResponseHeaders(response, statics);
+        this.webResponseTimeout = () => applyStaticResponseHeaders(RESPONSE_TIMEOUT(), statics);
+        return this;
+    }
+    enableResponseBodyTagging() {
+        if (this.responseBodyTag === undefined) {
+            this.responseBodyTag = Object.freeze({});
+            this.responseBodyOwners.add(this.responseBodyTag);
+        }
+        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;
     }
     /** Observe the terminal response after all transformations. Observers are ordered and fail-open. */
@@ -363,16 +650,42 @@ export class Server {
         }
         this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"));
         this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"));
-        if (arg.onRequest !== undefined)
-            this.onRequest(arg.onRequest);
+        if (arg.onRequest !== undefined) {
+            this.assertConfigurable("onRequest()");
+            this.onRequestHooks.push(arg.onRequest);
+            this.onNodeRequestHooks.push(arg.onNodeRequest);
+            if (arg.onNodeRequest === undefined)
+                this.nodeRequestHooksComplete = false;
+        }
+        else if (arg.onNodeRequest !== undefined) {
+            throw new TypeError("onNodeRequest() requires a paired onRequest() hook");
+        }
         if (arg.around !== undefined)
             this.around(arg.around);
         if (arg.beforeHandle !== undefined)
             this.beforeHandle(arg.beforeHandle);
         if (arg.afterHandle !== undefined)
             this.afterHandle(arg.afterHandle);
-        if (arg.onResponse !== undefined)
-            this.onResponse(arg.onResponse);
+        if (arg.onResponse !== undefined) {
+            this.assertConfigurable("onResponse()");
+            this.onResponseHooks.push(arg.onResponse);
+            this.onNodeResponseHooks.push(arg.onNodeResponse);
+            if (arg.onNodeResponse === undefined)
+                this.nodeResponseHooksComplete = false;
+        }
+        else if (arg.onNodeResponse !== undefined) {
+            throw new TypeError("onNodeResponse() requires a paired onResponse() hook");
+        }
+        // Before the bundle's own hooks: a bundle declaring both means its static values are the
+        // defaults its hook may then override, which is the order a single bundle reads in.
+        if (arg.responseHeaders !== undefined)
+            this.responseHeaders(arg.responseHeaders);
+        if (arg.onResponseHeaders !== undefined)
+            this.onResponseHeaders(arg.onResponseHeaders);
+        if (arg.onResponseBody !== undefined)
+            this.onResponseBody(arg.onResponseBody);
+        if (arg.onResponseRaw !== undefined)
+            this.onResponseRaw(arg.onResponseRaw);
         if (arg.onResponseFinalized !== undefined)
             this.onResponseFinalized(arg.onResponseFinalized);
         if (arg.onError !== undefined)
@@ -558,7 +871,9 @@ export class Server {
         const ledgered = this.effectLedgerRuntime?.resolve(capabilities, method, path);
         // A checked response schema needs the handler's VALUE before it becomes bytes, and the fused and
         // native lanes exist precisely to skip that step. So a contracted route leaves them - the same
-        // trade an idempotent route makes above, and the reason this is opt-in per server.
+        // structural trade an idempotent route makes above. The check itself is not the cost: a compiled
+        // validator measures ~100ns/response, within benchmark noise on any route these lanes already
+        // exclude (middleware, derives, lifecycle hooks).
         const runtime = this.responseContractRuntime;
         const contracted = runtime !== undefined && schema?.response !== undefined
             ? { runtime, schema: schema.response }
@@ -593,24 +908,40 @@ export class Server {
             this.afterHandleHooks.length === 0 &&
             this.onErrorHooks.length === 0 &&
             this.aroundHooks.length === 0;
+        const bodyOnly = contracted === undefined &&
+            schema?.body !== undefined &&
+            schema.query === undefined &&
+            schema.params === undefined &&
+            this.derives.length === 0 &&
+            this.beforeHandleHooks.length === 0 &&
+            this.afterHandleHooks.length === 0 &&
+            this.onErrorHooks.length === 0;
+        const fusedBody = !bare &&
+            bodyOnly &&
+            schema.onValidationError === undefined &&
+            this.defaultOnValidationError === undefined &&
+            idempotent === undefined &&
+            ledgered === undefined &&
+            this.aroundHooks.length === 0;
+        // Body-only routes still need an async body read, but eligible routes can compile the validation +
+        // 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)
+            : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
             : fusedQuery
                 ? this.buildFusedQueryWeb(handler, hasDecorations ? routeDecorations : undefined, schema.query)
-                : undefined;
+                : fusedBody
+                    ? this.buildFusedBodyWeb(fusedBodyRunner)
+                    : undefined;
         const contextless = bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler);
         // The body and query lanes finalize the handler's result themselves, so a contracted route takes
         // the general lifecycle lane instead - one place owns the check rather than three.
         const lane = bare
             ? "bare"
-            : contracted === undefined &&
-                schema?.body !== undefined &&
-                schema.query === undefined &&
-                schema.params === undefined &&
-                this.derives.length === 0 &&
-                this.beforeHandleHooks.length === 0 &&
-                this.afterHandleHooks.length === 0 &&
-                this.onErrorHooks.length === 0
+            : bodyOnly
                 ? "body"
                 : contracted === undefined &&
                     schema?.body === undefined &&
@@ -622,8 +953,34 @@ export class Server {
                     this.onErrorHooks.length === 0
                     ? "query"
                     : "lifecycle";
-        const execution = this.compileExecutionPlan(lane, contextless, this.aroundHooks.length > 0, ledgered !== undefined, fusedWeb, fusedWeb === undefined ? undefined : fusedQuery ? "query" : "bare");
-        const entry = {
+        // Lifecycle routes with no params schema are the common middleware shape: a derive/before hook
+        // 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
+            ? undefined
+            : schema?.body !== undefined
+                ? schema.query !== undefined
+                    ? "body-query"
+                    : "body"
+                : schema?.query !== undefined
+                    ? "query"
+                    : "hooks";
+        // The realistic middleware shape is commonly exactly one synchronous-or-async derive followed
+        // by one before hook. Keep the generic runner for every route that can observe decorations,
+        // after hooks, error hooks, or response contracts; this lane only removes the two per-request
+        // hook-loop dispatches and preserves the same async continuations and error handling.
+        const lifecycleHookLane = lane === "lifecycle" &&
+            contracted === undefined &&
+            !hasDecorations &&
+            this.derives.length === 1 &&
+            this.beforeHandleHooks.length === 1 &&
+            this.afterHandleHooks.length === 0 &&
+            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 registeredEntry = {
             // (context: never) => unknown -> InternalHandler: the framework invokes it
             // with the concrete RawContext the typed handler expects, so this is sound.
             handler: handler,
@@ -637,6 +994,7 @@ export class Server {
             beforeHandle: [...this.beforeHandleHooks],
             afterHandle: [...this.afterHandleHooks],
             onError: [...this.onErrorHooks],
+            lifecycleHookLane,
             around: [...this.aroundHooks],
             execution,
         };
@@ -677,17 +1035,17 @@ export class Server {
             method,
             path,
             pattern,
-            entry,
+            entry: registeredEntry,
             descriptor,
             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, fusedWeb, fusedLane) {
+    compileExecutionPlan(lane, contextless, hasAround, hasLedger, lifecycleLane, fusedWeb, fusedBody, fusedLane) {
         if (contextless) {
-            const run = (runtime, entry, source, params, search, signal, budget, platform, finalize, wrapResponse) => runtime.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
-            return Object.freeze({ run, fusedWeb, fusedLane });
+            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) {
@@ -701,13 +1059,30 @@ export class Server {
                 inner = (runtime, entry, _source, ctx, finalize, wrapResponse) => runtime.runQueryOnly(entry, ctx, finalize, wrapResponse);
                 break;
             default:
-                inner = (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runLifecycle(entry, source, ctx, finalize, wrapResponse);
+                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, finalize, wrapResponse) => {
-            const ctx = new RequestContext(source, params, search, signal, budget, platform, runtime.maxBodyBytes);
+        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;
@@ -724,12 +1099,12 @@ export class Server {
             }
             return outcome;
         };
-        return Object.freeze({ run, fusedWeb, fusedLane });
+        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) {
-        return Promise.resolve(this.runMatchedLanes(buffered, platform, entry, params, search, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, false));
+        return Promise.resolve(this.runMatchedLanes(buffered, platform, entry, params, search, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, false));
     }
     /** @internal Symbol-keyed install seam for the `responseContract()` plugin. Off the public typed surface. */
     [INSTALL_RESPONSE_CONTRACT](runtime) {
@@ -800,8 +1175,23 @@ export class Server {
         this.sseRuntime ??= source.sseRuntime;
         this.wsRuntime ??= source.wsRuntime;
         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
+        // rule as a direct `responseHeaders()` call).
+        if (source.staticResponseHeaders !== undefined) {
+            this.addStaticResponseHeaders({ ...source.staticResponseHeaders.record });
+        }
         this.onResponseHooks.push(...source.onResponseHooks);
+        this.onNodeResponseHooks.push(...source.onNodeResponseHooks);
+        this.nodeResponseHooksComplete &&= source.nodeResponseHooksComplete;
         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);
         this.mcpResourceList.push(...source.mcpResourceList);
         this.mcpPromptList.push(...source.mcpPromptList);
@@ -815,14 +1205,19 @@ export class Server {
             return route;
         // Rebuild with the SAME builder that produced the closure - rebinding a query-fused route as
         // bare would silently drop its validation.
-        const fusedWeb = 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));
+        const fusedBody = entry.execution.fusedLane === "body"
+            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined)
+            : 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));
         return {
             ...route,
             entry: {
                 ...entry,
-                execution: Object.freeze({ ...entry.execution, fusedWeb }),
+                execution: Object.freeze({ ...entry.execution, fusedWeb, fusedBody }),
             },
         };
     }
@@ -863,7 +1258,7 @@ export class Server {
         // path, selected by the compiled execution plan), and an `async fetch` would wrap every such result in a redundant
         // promise + microtask. Returning `Response | Promise<Response>` matches Web/edge handlers, while
         // `await app.fetch(...)` continues to work exactly as before.
-        const outcome = this.dispatch(source, platform, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
+        const outcome = this.dispatch(source, platform, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, true);
         if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
             return outcome;
         }
@@ -881,7 +1276,7 @@ export class Server {
         return this.admitGated(requestOf(source), () => this.fetchMatchedInner(source, entry, params));
     }
     fetchMatchedInner(source, entry, params) {
-        const outcome = this.runMatched(source, undefined, entry, params, undefined, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
+        const outcome = this.runMatched(source, undefined, entry, params, undefined, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, true);
         if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
             return outcome;
         }
@@ -931,20 +1326,28 @@ export class Server {
      * 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
      * `Response` build + body drain (the bulk of the Node bridge cost, measured ≈4µs/req). A handler that
-     * returns a `Response`, an error/short-circuit, or any registered `onResponse` hook falls back to the
-     * full Web path (`{ kind: "response" }`), so behavior is identical - only the common JSON-data case is
-     * faster. Same lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final
-     * render differs.
+     * returns a `Response`, an error/short-circuit, or a response hook that replaces/consumes the buffered
+     * body stays on the full Web path; an in-place response hook can still use the direct writer. Same
+     * lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final render differs.
      */
     resolveNode(req, platform) {
         return this.resolveNodeSource(req, platform);
     }
     resolveNodeSource(source, platform, suppliedRuntime) {
-        // onResponse hooks transform a Response, and the capacity gate wraps the Web response path - both
-        // force the Web path here (the gated `fetchSource` admits/sheds/releases); wrap its result.
-        if (this.onResponseHooks.length > 0 ||
-            this.onResponseFinalizedHooks.length > 0 ||
-            this.capacityGate !== undefined) {
+        // 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
+        // it in place. Finalization observers and the capacity gate still wrap the complete Web path.
+        // The native response lane engages only when the REQUEST side is native too (or there are no
+        // request hooks at all). This is what makes the NodeRequestContext identity contract hold: a
+        // web request-hook walk can rewrite the request, so its response-side view is a synthetic
+        // wrapper - a different object - and any middleware carrying per-request state from its request
+        // twin to its response twin through a WeakMap would silently miss. Coupling the gates means a
+        // response twin always sees the exact object its request twin saw.
+        const nativeResponseHooks = this.canUseNodeResponseHooks() &&
+            (this.onRequestHooks.length === 0 || this.canUseNodeRequestHooks());
+        const webResponseHooks = this.onResponseHooks.length > 0 && !nativeResponseHooks;
+        if (this.onResponseFinalizedHooks.length > 0 || this.capacityGate !== undefined) {
             const response = this.fetchSource(source, platform);
             return response instanceof Promise
                 ? response.then((settled) => ({ kind: "response", response: settled }))
@@ -957,7 +1360,151 @@ export class Server {
         if (runtime === undefined) {
             throw new FrameworkError("NODE_DIRECT_RUNTIME_MISSING", "resolveNode() needs the Node-direct renderer. Normal @nifrajs/node serving installs it automatically; direct callers should add `.use(nodeDirect())` (from `@nifrajs/core/node-direct`).");
         }
-        return this.dispatch(source, platform, runtime.toOutcome, runtime.fromResponse, runtime.timeout, false);
+        const resolved = this.dispatch(source, platform, runtime.toOutcome, runtime.fromResponse, runtime.timeout, false);
+        // Fold declared static headers into the record ONCE, here: before any native twin runs (so a
+        // 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;
+        const outcome = statics === undefined
+            ? resolved
+            : resolved instanceof Promise
+                ? resolved.then((settled) => withStaticNodeHeaders(settled, statics))
+                : withStaticNodeHeaders(resolved, statics);
+        if (webResponseHooks) {
+            return outcome instanceof Promise
+                ? outcome.then((settled) => this.finishNodeWebResponse(settled, source, runtime))
+                : this.finishNodeWebResponse(outcome, source, runtime);
+        }
+        if (!nativeResponseHooks)
+            return outcome;
+        try {
+            return outcome instanceof Promise
+                ? outcome.then((settled) => this.finishNodeResponse(settled, source, runtime))
+                : this.finishNodeResponse(outcome, source, runtime);
+        }
+        catch (error) {
+            // Keep resolveNode's failure shape promise-based, matching app.fetch and the adapter bridge.
+            return Promise.reject(error);
+        }
+    }
+    /** Run generic Web response middleware while retaining direct writes for untouched buffered bodies. */
+    finishNodeWebResponse(outcome, source, runtime) {
+        const req = this.takeResponseRequest(source);
+        const response = runtime.toResponse(outcome);
+        const transformed = this.applyOnResponseAndFinalize(response, req);
+        return transformed instanceof Promise
+            ? transformed.then(runtime.fromResponse)
+            : runtime.fromResponse(transformed);
+    }
+    /** True only when every transforming Web response hook has a header-only Node equivalent. */
+    canUseNodeResponseHooks() {
+        return this.onResponseHooks.length > 0 && this.nodeResponseHooksComplete;
+    }
+    /** Apply paired native hooks to data outcomes; preserve the complete Web hook pipeline for Response outcomes. */
+    finishNodeResponse(outcome, source, runtime) {
+        if (outcome.kind === "response") {
+            const req = this.takeResponseRequest(source);
+            const transformed = this.applyOnResponseAndFinalize(outcome.response, req);
+            return transformed instanceof Promise
+                ? transformed.then(runtime.fromResponse)
+                : runtime.fromResponse(transformed);
+        }
+        let headers = outcome.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");
+            if (!hasType) {
+                const defaultContentType = runtime.jsonContentType ?? "application/json;charset=utf-8";
+                if (headers === undefined) {
+                    headers = { "content-type": defaultContentType };
+                }
+                else {
+                    // The record belongs to this outcome. Add the implicit JSON type in place so the native
+                    // header walk does not clone every c.set.headers record before it can run. A hook that
+                    // replaces or deletes the type still takes the existing withNodeResponseHeaders path;
+                    // the writer's final defaulting behavior remains unchanged.
+                    headers["content-type"] = defaultContentType;
+                }
+            }
+        }
+        const context = {
+            status: outcome.status,
+            headers,
+            cookies: outcome.kind === "json" ? outcome.cookies : undefined,
+            body: outcome.body,
+        };
+        const applied = this.applyNodeResponseHooks(context, this.takeNodeResponseRequest(source));
+        if (applied instanceof Promise) {
+            return applied.then(() => this.withNodeResponseHeaders(outcome, context));
+        }
+        return this.withNodeResponseHeaders(outcome, context);
+    }
+    withNodeResponseHeaders(outcome, context) {
+        const outcomeCookies = outcome.kind === "json" ? outcome.cookies : undefined;
+        const bodyChanged = context.body !== outcome.body;
+        const statusChanged = context.status !== outcome.status;
+        if (context.headers === outcome.headers &&
+            context.cookies === outcomeCookies &&
+            !bodyChanged &&
+            !statusChanged) {
+            return outcome;
+        }
+        let headers = context.headers;
+        if (bodyChanged && headers !== undefined) {
+            // A replaced body invalidates any explicitly carried length; the writers re-derive framing
+            // from the final bytes.
+            const stale = Object.keys(headers).find((key) => key.toLowerCase() === "content-length");
+            if (stale !== undefined) {
+                headers = { ...headers };
+                delete headers[stale];
+            }
+        }
+        if (outcome.kind === "json") {
+            if (bodyChanged && context.body !== null && typeof context.body !== "string") {
+                // A binary replacement can't ride the json render - switch to the buffered-body render,
+                // folding queued cookies into explicit set-cookie lines so nothing is dropped.
+                const record = Object.create(null);
+                if (headers !== undefined)
+                    Object.assign(record, headers);
+                if (context.cookies !== undefined && context.cookies.length > 0) {
+                    record["set-cookie"] = [...context.cookies];
+                }
+                return { kind: "body", status: context.status, headers: record, body: context.body };
+            }
+            return {
+                ...outcome,
+                status: context.status,
+                headers,
+                cookies: context.cookies,
+                body: bodyChanged ? context.body : outcome.body,
+            };
+        }
+        return {
+            ...outcome,
+            status: context.status,
+            headers,
+            body: bodyChanged
+                ? (context.body ?? new Uint8Array(0))
+                : outcome.body,
+        };
+    }
+    /** Synchronous until a native response hook actually returns a Promise. */
+    applyNodeResponseHooks(response, req) {
+        for (let i = 0; i < this.onNodeResponseHooks.length; i++) {
+            const hook = this.onNodeResponseHooks[i];
+            const result = hook(response, req);
+            if (result instanceof Promise)
+                return result.then(() => this.continueNodeResponseHooks(i + 1, response, req));
+        }
+    }
+    async continueNodeResponseHooks(start, response, req) {
+        for (let i = start; i < this.onNodeResponseHooks.length; i++) {
+            const hook = this.onNodeResponseHooks[i];
+            await hook(response, req);
+        }
     }
     /**
      * Resolve a WebSocket upgrade - the seam every serving adapter uses. Returns `pass` (not a WS
@@ -1066,8 +1613,42 @@ export class Server {
         if (this.onRequestHooks.length === 0) {
             return this.routeAndRun(source, resolved, finalize, wrapResponse, onTimeout, webFast);
         }
+        if (!webFast && this.canUseNodeRequestHooks()) {
+            return this.runWithNodeRequest(source, resolved, finalize, wrapResponse, onTimeout);
+        }
         return this.runWithOnRequest(source, resolved, finalize, wrapResponse, onTimeout, webFast);
     }
+    /** Node-native request hook walk. A header-only hook can inspect the lazy source without forcing a
+     * Web `Request`; arbitrary request rewrites and full Web hooks use {@link runWithOnRequest}. */
+    runWithNodeRequest(source, platform, finalize, wrapResponse, onTimeout) {
+        const hooks = this.onNodeRequestHooks;
+        const request = this.nodeRequestContextOf(source);
+        for (let i = 0; i < hooks.length; i++) {
+            const hook = hooks[i];
+            const outcome = hook(request, platform);
+            if (outcome instanceof Promise) {
+                return outcome.then((early) => this.continueNodeRequest(early, i + 1, request, source, platform, finalize, wrapResponse, onTimeout));
+            }
+            if (outcome !== undefined)
+                return wrapResponse(outcome);
+        }
+        return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, false);
+    }
+    async continueNodeRequest(first, nextIndex, request, source, platform, finalize, wrapResponse, onTimeout) {
+        if (first !== undefined)
+            return wrapResponse(first);
+        for (let i = nextIndex; i < this.onNodeRequestHooks.length; i++) {
+            const hook = this.onNodeRequestHooks[i];
+            const outcome = hook(request, platform);
+            const early = outcome instanceof Promise ? await outcome : outcome;
+            if (early !== undefined)
+                return wrapResponse(early);
+        }
+        return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, false);
+    }
+    canUseNodeRequestHooks() {
+        return this.onRequestHooks.length > 0 && this.nodeRequestHooksComplete;
+    }
     /**
      * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the
      * common case - e.g. CORS returning `undefined` for a non-preflight request): an `async` version
@@ -1078,6 +1659,7 @@ export class Server {
     runWithOnRequest(source, platform, finalize, wrapResponse, onTimeout, webFast) {
         const hooks = this.onRequestHooks;
         const originalRequest = requestOf(source);
+        this.responseSources.set(source, originalRequest);
         let current = source;
         for (let i = 0; i < hooks.length; i++) {
             const outcome = hooks[i](requestOf(current), platform);
@@ -1119,6 +1701,16 @@ export class Server {
         return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
     }
     takeResponseRequest(source) {
+        const tracked = this.responseSources.get(source);
+        if (tracked !== undefined) {
+            this.responseSources.delete(source);
+            const rewritten = this.responseRequests.get(tracked);
+            if (rewritten !== undefined) {
+                this.responseRequests.delete(tracked);
+                return rewritten;
+            }
+            return tracked;
+        }
         const request = requestOf(source);
         const rewritten = this.responseRequests.get(request);
         if (rewritten === undefined)
@@ -1126,14 +1718,99 @@ export class Server {
         this.responseRequests.delete(request);
         return rewritten;
     }
+    /**
+     * The NodeRequestContext for a source, MEMOIZED per source so the request twins and the response
+     * twins receive the exact same object within one request - that identity is the documented
+     * contract stateful twins key their WeakMaps on. An adapter source (which already speaks the
+     * interface) is returned as-is; a plain `Request` source (a direct `resolveNode` caller) gets one
+     * cached wrapper.
+     */
+    nodeRequestContextOf(source) {
+        if (source.header !== undefined)
+            return source;
+        let context = this.nodeContexts.get(source);
+        if (context === undefined) {
+            const request = requestOf(source);
+            context = {
+                method: request.method,
+                url: request.url,
+                header: (name) => request.headers.get(name),
+            };
+            this.nodeContexts.set(source, context);
+        }
+        return context;
+    }
+    /** Preserve the request visible to generic onRequest hooks for paired native response hooks. */
+    takeNodeResponseRequest(source) {
+        const tracked = this.responseSources.get(source);
+        if (tracked !== undefined) {
+            this.responseSources.delete(source);
+            const rewritten = this.responseRequests.get(tracked);
+            if (rewritten !== undefined) {
+                this.responseRequests.delete(tracked);
+                return {
+                    method: rewritten.method,
+                    url: rewritten.url,
+                    header: (name) => rewritten.headers.get(name),
+                };
+            }
+            return {
+                method: tracked.method,
+                url: tracked.url,
+                header: (name) => tracked.headers.get(name),
+            };
+        }
+        return this.nodeRequestContextOf(source);
+    }
     /**
      * Route → build context → run. Synchronous through to the handler for a **bare** route
      * (selected by its compiled plan), so a sync handler produces its result with zero promise allocations;
      * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.
      */
     routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast) {
-        const url = source.urlParts ?? urlPartsOf(source.url);
-        const match = this.catalog.find(source.method, url.pathname);
+        // Routing only needs the pathname. Scan the URL once but keep the two slices in locals instead
+        // of allocating the `{ pathname, search }` pair returned by the public helper on every request.
+        let pathname;
+        let search;
+        // Read the source's split ONCE. `urlParts` is an accessor on the Node request sources that
+        // rescans the target and allocates a fresh pair every time it is touched, so testing it and then
+        // reading each half through the accessor scanned the URL three times per request and threw two
+        // of the three pairs away immediately.
+        const parts = source.urlParts;
+        if (parts !== undefined) {
+            pathname = parts.pathname;
+            search = parts.search;
+        }
+        else {
+            const rawUrl = source.url;
+            const schemeEnd = rawUrl.indexOf("://");
+            const start = schemeEnd === -1 ? rawUrl.indexOf("/") : rawUrl.indexOf("/", schemeEnd + 3);
+            if (start === -1) {
+                pathname = "/";
+                search = "";
+            }
+            else {
+                let pathEnd = rawUrl.length;
+                let searchStart = -1;
+                let searchEnd = rawUrl.length;
+                for (let i = start; i < rawUrl.length; i++) {
+                    const c = rawUrl.charCodeAt(i);
+                    if (c === 63 /* ? */ && searchStart === -1) {
+                        pathEnd = i;
+                        searchStart = i;
+                    }
+                    else if (c === 35 /* # */) {
+                        if (searchStart === -1)
+                            pathEnd = i;
+                        searchEnd = i;
+                        break;
+                    }
+                }
+                pathname = rawUrl.slice(start, pathEnd);
+                search = searchStart === -1 ? "" : rawUrl.slice(searchStart, searchEnd);
+            }
+        }
+        const match = this.catalog.find(source.method, pathname);
         if (!match.found) {
             if (match.reason === "method-not-allowed") {
                 return wrapResponse(jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }));
@@ -1146,7 +1823,7 @@ export class Server {
         if (params === null) {
             return wrapResponse(jsonError(400, "malformed_path"));
         }
-        return this.runMatched(source, platform, match.payload, params, url.search, finalize, wrapResponse, onTimeout, webFast);
+        return this.runMatched(source, platform, match.payload, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
     /** 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) {
@@ -1196,9 +1873,12 @@ export class Server {
             ? getUnboundedRequestBudget()
             : createRequestBudget({ deadline: admission.deadline, signal });
         const plan = entry.execution;
+        const nativeContext = controller === undefined;
         const outcome = webFast && plan.fusedWeb !== undefined
-            ? plan.fusedWeb(source, params, search, signal, budget, platform, false)
-            : plan.run(this, entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
+            ? plan.fusedWeb(source, params, search, signal, budget, platform, nativeContext)
+            : !webFast && plan.fusedBody !== undefined
+                ? plan.fusedBody(source, params, search, signal, budget, platform, false, finalize, wrapResponse)
+                : plan.run(this, entry, source, params, search, signal, budget, platform, nativeContext, finalize, wrapResponse);
         // The request timeout only bounds work that is actually pending - a synchronous (bare) result is
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
         if (controller !== undefined && outcome instanceof Promise) {
@@ -1270,11 +1950,13 @@ export class Server {
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
     buildFusedWeb(handler, decorations, contextless) {
+        // 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 err;
+                return this.wrapWebResponse(err);
             this.logRequestError(err, ctx);
-            return jsonError(500, "internal_error");
+            return this.wrapWebResponse(jsonError(500, "internal_error"));
         };
         if (contextless && decorations === undefined) {
             // `() => ...` can't observe the context - skip allocating one entirely (errors still build
@@ -1287,20 +1969,20 @@ export class Server {
                 }
                 catch (err) {
                     return logError(err, nativeContext
-                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                        ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
                         : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes));
                 }
                 if (result instanceof Promise) {
-                    return result.then(fusedRespondNoSet, (err) => logError(err, nativeContext
-                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                    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 fusedRespondNoSet(result);
+                return fusedRespondNoSet(result, this.responseBodyTag, this.staticResponseHeaders);
             };
         }
         return (source, params, search, signal, budget, platform, nativeContext) => {
             const ctx = nativeContext
-                ? RequestContext.native(source, params, this.maxBodyBytes)
+                ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
                 : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
@@ -1312,11 +1994,87 @@ export class Server {
                 return logError(err, ctx);
             }
             if (result instanceof Promise) {
-                return result.then((value) => fusedRespond(value, ctx), (err) => logError(err, ctx));
+                return result.then((value) => fusedRespond(value, ctx, this.responseBodyTag, this.staticResponseHeaders), (err) => logError(err, ctx));
             }
-            return fusedRespond(result, ctx);
+            return fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders);
         };
     }
+    /** 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) {
+        const logError = (err, ctx, wrapResponse) => this.bareError(err, ctx, wrapResponse);
+        const runHandler = (ctx, finalize, wrapResponse) => {
+            if (decorations !== undefined)
+                Object.assign(ctx, decorations);
+            let output;
+            try {
+                output = handler(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, wrapResponse);
+            }
+            if (output instanceof Promise) {
+                return output.then((result) => {
+                    try {
+                        return finalize(result, responseSet(ctx), ctx);
+                    }
+                    catch (err) {
+                        return logError(err, ctx, wrapResponse);
+                    }
+                }, (err) => logError(err, ctx, wrapResponse));
+            }
+            try {
+                return finalize(output, responseSet(ctx), ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, wrapResponse);
+            }
+        };
+        const runValidated = (result, ctx, finalize, wrapResponse) => {
+            if (result.issues !== undefined)
+                return wrapResponse(validationError(result.issues));
+            ctx.body = result.value;
+            return runHandler(ctx, finalize, wrapResponse);
+        };
+        const runParsed = (parsed, ctx, finalize, wrapResponse) => {
+            let validation;
+            try {
+                validation = bodySchema["~standard"].validate(parsed);
+            }
+            catch (err) {
+                return logError(err, ctx, wrapResponse);
+            }
+            if (validation instanceof Promise) {
+                return validation.then((settled) => {
+                    try {
+                        return runValidated(settled, ctx, finalize, wrapResponse);
+                    }
+                    catch (err) {
+                        return logError(err, ctx, wrapResponse);
+                    }
+                }, (err) => logError(err, ctx, wrapResponse));
+            }
+            try {
+                return runValidated(validation, ctx, finalize, wrapResponse);
+            }
+            catch (err) {
+                return logError(err, ctx, wrapResponse);
+            }
+        };
+        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);
+            const finish = (value) => runParsed(value, ctx, finalize, wrapResponse);
+            return this.readBodyInput(source, 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);
+    }
     /** 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.
      * Eligibility is decided at registration (see `fusedQuery` in {@link register}); the semantics here
@@ -1325,11 +2083,13 @@ 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) {
+        // 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 err;
+                return this.wrapWebResponse(err);
             this.logRequestError(err, ctx);
-            return jsonError(500, "internal_error");
+            return this.wrapWebResponse(jsonError(500, "internal_error"));
         };
         const runHandler = (ctx, value) => {
             ctx.query = value;
@@ -1341,13 +2101,13 @@ export class Server {
                 return logError(err, ctx);
             }
             if (result instanceof Promise) {
-                return result.then((settled) => fusedRespond(settled, ctx), (err) => logError(err, ctx));
+                return result.then((settled) => fusedRespond(settled, ctx, this.responseBodyTag, this.staticResponseHeaders), (err) => logError(err, ctx));
             }
-            return fusedRespond(result, ctx);
+            return fusedRespond(result, ctx, this.responseBodyTag, this.staticResponseHeaders);
         };
         return (source, params, search, signal, budget, platform, nativeContext) => {
             const ctx = nativeContext
-                ? RequestContext.native(source, params, this.maxBodyBytes)
+                ? RequestContext.native(source, params, search, this.maxBodyBytes, platform)
                 : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
@@ -1360,11 +2120,11 @@ export class Server {
             }
             if (validation instanceof Promise) {
                 return validation.then((settled) => settled.issues !== undefined
-                    ? validationError(settled.issues)
+                    ? this.wrapWebResponse(validationError(settled.issues))
                     : runHandler(ctx, settled.value), (err) => logError(err, ctx));
             }
             if (validation.issues !== undefined)
-                return validationError(validation.issues);
+                return this.wrapWebResponse(validationError(validation.issues));
             return runHandler(ctx, validation.value);
         };
     }
@@ -1402,25 +2162,20 @@ export class Server {
         return dispatch(0);
     }
     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));
+    }
+    /** 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) {
         const contentType = headerOf(source, "content-type") ?? "";
         if (contentType !== "application/json" && !contentType.includes("application/json")) {
             if (isUrlEncodedForm(contentType)) {
-                // HTML form posts validate through the same schema as JSON (parity with Elysia/Hono).
-                // Off the JSON inline lane on purpose: forms are a fraction of API traffic, and the
-                // bounded form reader shares the streaming guard. JSON requests are untouched.
-                return readBoundedForm(source, this.maxBodyBytes).then((form) => {
-                    if (form instanceof Response)
-                        return wrapResponse(form);
-                    return this.finishBodyOnly(entry, form, ctx, finalize, wrapResponse);
-                });
+                return readBoundedForm(source, this.maxBodyBytes).then((form) => (form instanceof Response ? wrapResponse(form) : onParsed(form)), onError);
             }
             return Promise.resolve(wrapResponse(jsonError(415, "unsupported_media_type")));
         }
-        // Inline fast path (profiled): a framed, in-cap, non-chunked body parses with the native
-        // `req.json()` directly - one promise, one `.then` closure per request. The generic
-        // `readBoundedJson` (an extra async-fn frame + per-request `finish`/`applyValidation`
-        // closures) is kept for the chunked / length-less / oversized cases it exists for.
-        // Semantics are identical to readBoundedJsonSource - same checks, same error codes.
+        // 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);
@@ -1431,21 +2186,14 @@ export class Server {
                 return Promise.resolve(wrapResponse(jsonError(413, "payload_too_large")));
             }
             if (headerOf(source, "transfer-encoding") === null) {
-                return source.json().then((parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), 
-                // Native json() rejection = malformed JSON; anything past parse goes through
-                // finishBodyOnly's own error handling.
-                () => wrapResponse(jsonError(400, "invalid_json")));
+                return source.json().then(onParsed, () => wrapResponse(jsonError(400, "invalid_json")));
             }
         }
         try {
-            return this.readBoundedJson(source).then((parsed) => {
-                if (parsed instanceof Response)
-                    return wrapResponse(parsed);
-                return this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse);
-            }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            return this.readBoundedJson(source).then((parsed) => (parsed instanceof Response ? wrapResponse(parsed) : onParsed(parsed)), onError);
         }
         catch (err) {
-            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+            return Promise.resolve(onError(err));
         }
     }
     /** Validate + run the handler for the bodyOnly path - shared by the inline fast path and the
@@ -1626,7 +2374,11 @@ export class Server {
                 throw error;
             });
         }
-        throw error;
+        // A hook failure must surface as a REJECTION even when every prior step ran synchronously:
+        // `fetch()` may now resolve without a promise, but its failure contract stays promise-shaped -
+        // a synchronous throw here would escape `Promise.resolve(app.fetch(...))` bridges and
+        // `.then()`-style callers entirely instead of reaching their rejection handling.
+        return Promise.reject(error);
     }
     /** Notify terminal observers in order while isolating both sync and async failures. */
     notifyResponseFinalized(outcome, req) {
@@ -1689,100 +2441,314 @@ export class Server {
      * Generic over the render: a success value goes through `finalize(result, set)` (a Web `Response`, or
      * node-direct primitives); an early/error `Response` (validation, thrown, 500) through `wrapResponse`.
      */
-    async runLifecycle(entry, source, ctx, finalize, wrapResponse) {
+    /** Synchronous until a validator, lifecycle hook, handler, or contract check actually returns a Promise. */
+    runLifecycle(entry, source, ctx, finalize, wrapResponse) {
+        try {
+            const paramsSchema = entry.schema?.params;
+            if (paramsSchema !== 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 already knows whether this route has body/params/query validation. Most real
+            // read routes have no body or params schema, so skip the generic stage ladder and go straight to
+            // query validation + lifecycle hooks. The fallback below remains the complete path for routes
+            // with body/params combinations and validation recovery.
+            if (entry.schema?.body === undefined) {
+                return this.runQueryAndLifecycle(entry, ctx, finalize, wrapResponse);
+            }
+            return this.runLifecycleAfterParams(entry, source, ctx, finalize, wrapResponse, undefined);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Registration-specialized query lifecycle: query validation (including recovery) → hooks. */
+    runLifecycleQuery(entry, ctx, finalize, wrapResponse) {
+        try {
+            // The execution plan only selects this runner when the route has a query schema. Keeping the
+            // non-null access here removes the per-request schema-presence branch from realistic GETs.
+            const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
+            if (validation instanceof Promise) {
+                return validation.then((result) => {
+                    try {
+                        return this.runQueryAndLifecycleResult(entry, ctx, finalize, wrapResponse, result);
+                    }
+                    catch (err) {
+                        return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            return this.runQueryAndLifecycleResult(entry, ctx, finalize, wrapResponse, validation);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Registration-specialized body lifecycle: bounded body validation (including recovery) → hooks. */
+    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. */
+    runLifecycleBodyQuery(entry, source, ctx, finalize, wrapResponse) {
+        return this.readAndValidateBody(source, entry, ctx).then((bodyError) => bodyError === undefined
+            ? this.runLifecycleQuery(entry, ctx, finalize, wrapResponse)
+            : wrapResponse(bodyError), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+    }
+    /** Registration-specialized no-body lifecycle: query validation (if present) → derives/hooks. */
+    runQueryAndLifecycle(entry, ctx, finalize, wrapResponse) {
+        const querySchema = entry.schema?.query;
+        return querySchema === undefined
+            ? this.runLifecycleHooks(entry, ctx, finalize, wrapResponse)
+            : this.runLifecycleQuery(entry, ctx, finalize, wrapResponse);
+    }
+    runQueryAndLifecycleResult(entry, ctx, finalize, wrapResponse, result) {
+        const queryError = this.applyLifecycleValidation(entry, result, ctx, "query");
+        if (queryError instanceof Promise) {
+            return queryError.then((error) => error === undefined
+                ? this.runLifecycleHooks(entry, ctx, finalize, wrapResponse)
+                : wrapResponse(error), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        }
+        if (queryError !== undefined)
+            return wrapResponse(queryError);
+        return this.runLifecycleHooks(entry, ctx, finalize, wrapResponse);
+    }
+    runLifecycleAfterParamsResult(entry, source, ctx, finalize, wrapResponse, result) {
+        try {
+            return this.runLifecycleAfterParams(entry, source, ctx, finalize, wrapResponse, this.applyLifecycleValidation(entry, result, ctx, "params"));
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    runLifecycleAfterParams(entry, source, ctx, finalize, wrapResponse, paramsError) {
+        if (paramsError instanceof Promise) {
+            return paramsError.then((error) => this.runLifecycleAfterParamsSettled(entry, source, ctx, finalize, wrapResponse, error), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        }
+        return this.runLifecycleAfterParamsSettled(entry, source, ctx, finalize, wrapResponse, paramsError);
+    }
+    runLifecycleAfterParamsSettled(entry, source, ctx, finalize, wrapResponse, paramsError) {
+        if (paramsError !== undefined)
+            return wrapResponse(paramsError);
+        if (entry.schema?.body !== undefined) {
+            return this.readAndValidateBody(source, entry, ctx).then((bodyError) => this.runLifecycleAfterBody(entry, ctx, finalize, wrapResponse, bodyError), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        }
+        return this.runLifecycleAfterBody(entry, ctx, finalize, wrapResponse, undefined);
+    }
+    runLifecycleAfterBody(entry, ctx, finalize, wrapResponse, bodyError) {
+        if (bodyError !== undefined)
+            return wrapResponse(bodyError);
+        const querySchema = entry.schema?.query;
+        if (querySchema === undefined)
+            return this.runLifecycleHooks(entry, ctx, finalize, wrapResponse);
+        const validation = querySchema["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
+        if (validation instanceof Promise) {
+            return validation.then((result) => this.runLifecycleAfterQueryResult(entry, ctx, finalize, wrapResponse, result), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        }
+        return this.runLifecycleAfterQueryResult(entry, ctx, finalize, wrapResponse, validation);
+    }
+    runLifecycleAfterQueryResult(entry, ctx, finalize, wrapResponse, result) {
+        try {
+            const queryError = this.applyLifecycleValidation(entry, result, ctx, "query");
+            if (queryError instanceof Promise) {
+                return queryError.then((error) => this.runLifecycleAfterQuery(entry, ctx, finalize, wrapResponse, error), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            return this.runLifecycleAfterQuery(entry, ctx, finalize, wrapResponse, queryError);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    runLifecycleAfterQuery(entry, ctx, finalize, wrapResponse, queryError) {
+        if (queryError !== undefined)
+            return wrapResponse(queryError);
+        return this.runLifecycleHooks(entry, ctx, finalize, wrapResponse);
+    }
+    runLifecycleHooks(entry, ctx, finalize, wrapResponse) {
+        if (entry.lifecycleHookLane === "derive-before") {
+            return this.runLifecycleDeriveBefore(entry, ctx, finalize, wrapResponse);
+        }
         try {
-            if (entry.schema?.params !== undefined) {
-                // Path params arrive as strings from routing; validate (and coerce) them at the boundary, before
-                // the body/query, so a malformed `:id` is a 422 before any work runs. Raw `.validate` (no wrapper
-                // alloc), same recovery-hook path as body/query.
-                const validation = entry.schema.params["~standard"].validate(ctx.params);
-                const result = validation instanceof Promise ? await validation : validation;
-                const paramsError = await this.applyLifecycleValidation(entry, result, ctx, "params");
-                if (paramsError !== undefined)
-                    return wrapResponse(paramsError);
-            }
-            if (entry.schema?.body !== undefined) {
-                const bodyError = await this.readAndValidateBody(source, entry, ctx);
-                if (bodyError !== undefined)
-                    return wrapResponse(bodyError);
-            }
-            if (entry.schema?.query !== undefined) {
-                // Repeated query keys promote to `string[]` (so an array schema validates `?a=1&a=2`); a
-                // single occurrence stays a string. Raw `.validate` (read `.issues`/`.value`) skips the
-                // validateStandard wrapper alloc.
-                const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
-                const result = validation instanceof Promise ? await validation : validation;
-                const queryError = await this.applyLifecycleValidation(entry, result, ctx, "query");
-                if (queryError !== undefined)
-                    return wrapResponse(queryError);
-            }
-            // Context extensions: static decorations, then per-request derives.
-            // Each hook below only awaits when it actually returns a Promise - a sync hook
-            // skips the microtask tick (a fast-path; ~64 ns/hook).
             if (entry.hasDecorations)
-                Object.assign(ctx, entry.decorations); // skip the no-op on bare routes
-            // The `.length` guards skip iterator setup for the common no-hook route (most
-            // routes have neither derives nor before/after hooks); a hooked route pays only
-            // the length check.
-            if (entry.derives.length > 0) {
-                for (const derive of entry.derives) {
-                    const extension = derive(ctx);
-                    Object.assign(ctx, extension instanceof Promise ? await extension : extension);
+                Object.assign(ctx, entry.decorations);
+            for (let i = 0; i < entry.derives.length; i++) {
+                const extension = entry.derives[i](ctx);
+                if (extension instanceof Promise) {
+                    return this.continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, i, extension);
                 }
+                Object.assign(ctx, extension);
             }
-            // beforeHandle: a non-undefined return short-circuits, skipping the handler.
-            if (entry.beforeHandle.length > 0) {
-                for (const hook of entry.beforeHandle) {
-                    const outcome = hook(ctx);
-                    const early = outcome instanceof Promise ? await outcome : outcome;
-                    if (early !== undefined)
-                        return finalize(early, responseSet(ctx));
+            for (let i = 0; i < entry.beforeHandle.length; i++) {
+                const outcome = entry.beforeHandle[i](ctx);
+                if (outcome instanceof Promise) {
+                    return this.continueLifecycleAfterBefore(entry, ctx, finalize, wrapResponse, i, outcome);
                 }
+                if (outcome !== undefined)
+                    return finalize(outcome, responseSet(ctx));
+            }
+            const result = entry.handler(ctx);
+            if (result instanceof Promise) {
+                return result.then((value) => this.finishLifecycleResult(entry, ctx, finalize, wrapResponse, value), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            return this.finishLifecycleResult(entry, ctx, finalize, wrapResponse, result);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Registration-specialized derive → before → handler lifecycle. */
+    runLifecycleDeriveBefore(entry, ctx, finalize, wrapResponse) {
+        try {
+            const extension = entry.derives[0](ctx);
+            if (extension instanceof Promise) {
+                return this.continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, 0, extension);
+            }
+            Object.assign(ctx, extension);
+            const outcome = entry.beforeHandle[0](ctx);
+            if (outcome instanceof Promise) {
+                return this.continueLifecycleAfterBefore(entry, ctx, finalize, wrapResponse, 0, outcome);
             }
-            const handlerOutput = entry.handler(ctx);
-            let result = handlerOutput instanceof Promise ? await handlerOutput : handlerOutput;
-            // afterHandle: transform the result before serialization.
-            if (entry.afterHandle.length > 0) {
-                for (const hook of entry.afterHandle) {
-                    const transformed = hook(result, ctx);
-                    result = transformed instanceof Promise ? await transformed : transformed;
+            if (outcome !== undefined)
+                return this.finishSimpleLifecycleResult(entry, ctx, finalize, wrapResponse, outcome);
+            const result = entry.handler(ctx);
+            if (result instanceof Promise) {
+                return result.then((value) => this.finishSimpleLifecycleResult(entry, ctx, finalize, wrapResponse, value), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            return this.finishSimpleLifecycleResult(entry, ctx, finalize, wrapResponse, result);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Finalize the specialized lane without rechecking its registration-proven invariants. */
+    finishSimpleLifecycleResult(entry, ctx, finalize, wrapResponse, result) {
+        try {
+            return finalize(result, responseSet(ctx));
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async continueLifecycleAfterDerive(entry, ctx, finalize, wrapResponse, firstIndex, first) {
+        try {
+            Object.assign(ctx, await first);
+            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);
+            }
+            return await this.runLifecycleHooksAsync(entry, ctx, finalize, wrapResponse);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async runLifecycleHooksAsync(entry, ctx, finalize, wrapResponse) {
+        try {
+            for (const hook of entry.beforeHandle) {
+                const outcome = hook(ctx);
+                const early = outcome instanceof Promise ? await outcome : outcome;
+                if (early !== undefined)
+                    return finalize(early, responseSet(ctx));
+            }
+            return await this.runLifecycleHandlerAsync(entry, ctx, finalize, wrapResponse);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async continueLifecycleAfterBefore(entry, ctx, finalize, wrapResponse, firstIndex, first) {
+        try {
+            const firstOutcome = await first;
+            if (firstOutcome !== undefined)
+                return finalize(firstOutcome, responseSet(ctx));
+            for (let i = firstIndex + 1; 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));
+            }
+            return await this.runLifecycleHandlerAsync(entry, ctx, finalize, wrapResponse);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async runLifecycleHandlerAsync(entry, ctx, finalize, wrapResponse) {
+        try {
+            const output = entry.handler(ctx);
+            const result = output instanceof Promise ? await output : output;
+            return await this.finishLifecycleResult(entry, ctx, finalize, wrapResponse, result);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    finishLifecycleResult(entry, ctx, finalize, wrapResponse, initial) {
+        try {
+            let result = initial;
+            for (let i = 0; i < entry.afterHandle.length; i++) {
+                const transformed = entry.afterHandle[i](result, ctx);
+                if (transformed instanceof Promise) {
+                    return this.continueLifecycleAfterHandle(entry, ctx, finalize, wrapResponse, i, transformed);
                 }
+                result = transformed;
             }
-            // The response contract is checked LAST, after afterHandle, so it holds what actually ships
-            // rather than what the handler happened to return. Only reached by a contracted route: the
-            // registration decision above kept those off the fused/native lanes for exactly this step.
+            return this.finishLifecycleContract(entry, ctx, finalize, wrapResponse, result);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async continueLifecycleAfterHandle(entry, ctx, finalize, wrapResponse, firstIndex, first) {
+        try {
+            let result = await first;
+            for (let i = firstIndex + 1; i < entry.afterHandle.length; i++) {
+                const transformed = entry.afterHandle[i](result, ctx);
+                result = transformed instanceof Promise ? await transformed : transformed;
+            }
+            return await this.finishLifecycleContract(entry, ctx, finalize, wrapResponse, result);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    finishLifecycleContract(entry, ctx, finalize, wrapResponse, result) {
+        try {
             const contract = entry.responseContract;
-            if (contract !== undefined) {
-                const checked = contract.runtime.check(contract.schema, result);
-                const outcome = checked instanceof Promise ? await checked : checked;
-                if (outcome.kind === "violation") {
-                    // The handler broke a contract it declared itself, so this is a server fault, not the
-                    // caller's. Fail closed: the undeclared payload is never sent, and the detail goes to the
-                    // (redacting) logger rather than to the client.
-                    this.logger.error("response contract violation", {
-                        method: ctx.req.method,
-                        path: pathnameOf(ctx.req.url),
-                        // `detail`, not `message`: the logger uses `message` for its own first argument, so a
-                        // field of that name is silently overwritten and the diagnosis disappears.
-                        detail: outcome.message,
-                    });
-                    return wrapResponse(jsonError(500, "internal_error"));
-                }
-                if (outcome.kind === "warn") {
-                    this.logger.warn("response contract", {
-                        method: ctx.req.method,
-                        path: pathnameOf(ctx.req.url),
-                        detail: outcome.message,
-                    });
-                }
-                result = outcome.value;
+            if (contract === undefined)
+                return finalize(result, responseSet(ctx));
+            const checked = contract.runtime.check(contract.schema, result);
+            if (checked instanceof Promise) {
+                return checked.then((outcome) => this.finishContractOutcome(ctx, finalize, wrapResponse, outcome), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
             }
-            return finalize(result, responseSet(ctx));
+            return this.finishContractOutcome(ctx, finalize, wrapResponse, checked);
         }
         catch (err) {
             return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
         }
     }
+    finishContractOutcome(ctx, finalize, wrapResponse, outcome) {
+        if (outcome.kind === "violation") {
+            this.logger.error("response contract violation", {
+                method: ctx.req.method,
+                path: pathnameOf(ctx.req.url),
+                detail: outcome.message,
+            });
+            return wrapResponse(jsonError(500, "internal_error"));
+        }
+        if (outcome.kind === "warn") {
+            this.logger.warn("response contract", {
+                method: ctx.req.method,
+                path: pathnameOf(ctx.req.url),
+                detail: outcome.message,
+            });
+        }
+        return finalize(outcome.value, responseSet(ctx));
+    }
     async 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
@@ -1842,7 +2808,7 @@ export class Server {
     }
     /** Apply validation and its recovery hook on the generic lifecycle lane. Recovery is completed
      * before derives/beforeHandle run, matching the body-only and query-only execution lanes. */
-    async applyLifecycleValidation(entry, result, ctx, kind) {
+    applyLifecycleValidation(entry, result, ctx, kind) {
         const assign = (value) => {
             if (kind === "body")
                 ctx.body = value;
@@ -1859,9 +2825,14 @@ export class Server {
         if (hook === undefined)
             return validationError(result.issues);
         const attempted = hook(result.issues, ctx, kind);
-        const recovery = attempted instanceof Promise ? await attempted : attempted;
+        if (attempted instanceof Promise) {
+            return attempted.then((recovery) => this.finishLifecycleValidationRecovery(entry, kind, result.issues, recovery, assign));
+        }
+        return this.finishLifecycleValidationRecovery(entry, kind, result.issues, attempted, assign);
+    }
+    finishLifecycleValidationRecovery(entry, kind, issues, recovery, assign) {
         if (recovery === undefined)
-            return validationError(result.issues);
+            return validationError(issues);
         if (recovery instanceof Response)
             return recovery;
         const schema = kind === "body"
@@ -1870,10 +2841,17 @@ export class Server {
                 ? entry.schema?.query
                 : entry.schema?.params;
         const retried = schema["~standard"].validate(recovery);
-        const settled = retried instanceof Promise ? await retried : retried;
-        if (settled.issues !== undefined)
-            return validationError(settled.issues);
-        assign(settled.value);
+        if (retried instanceof Promise) {
+            return retried.then((settled) => {
+                if (settled.issues !== undefined)
+                    return validationError(settled.issues);
+                assign(settled.value);
+                return undefined;
+            });
+        }
+        if (retried.issues !== undefined)
+            return validationError(retried.issues);
+        assign(retried.value);
         return undefined;
     }
     /**
@@ -1971,7 +2949,18 @@ export class Server {
             methods[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget);
             count += 1;
         }
-        return count === 0 ? undefined : routes;
+        if (count === 0)
+            return undefined;
+        // RFC 9110 §9.3.2: a GET route answers HEAD with identical status + headers (Bun strips the
+        // body on the wire). Alias the compiled GET handler under HEAD so HEAD stays on the native
+        // lane instead of falling through to the portable dispatcher; the router applies the same
+        // fallback there, so both lanes agree. An explicit HEAD registration wins via the ??=.
+        for (const path of Object.keys(routes)) {
+            const methods = routes[path];
+            if (methods.GET !== undefined)
+                methods.HEAD ??= methods.GET;
+        }
+        return routes;
     }
     /**
      * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).