@nifrajs/core 3.3.0 → 4.0.0

package/dist/server/server.js

@@ -7,31 +7,38 @@ import { compileRouteOptions } from "../internal/route-compiler.js";
 import { compileRouteExecutionPlan, } from "../internal/route-execution.js";
 import { compileRouteProgram, executeRouteProgram } from "../internal/route-program.js";
 import { isSameOriginRequest } from "../internal/same-origin.js";
-import { decodeRouteParams } from "../router/pattern.js";
-import { EMPTY_PARAMS, Router } from "../router/router.js";
+import { decodeRouteParams, expandOptionalParams } from "../router/pattern.js";
+import { EMPTY_PARAMS, METHODS, Router } from "../router/router.js";
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.js";
 import { assertByteLimit, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } from "./body.js";
-import { resolveClientIp } from "./client-ip.js";
+import { NIFRA_PLATFORM_CLIENT_IP_DERIVED, resolveClientIp, } from "./client-ip.js";
+import "./core-copies.js";
 import { hasLowercaseHeaderKeysMark, headerKeysAllLowercase, markLowercaseHeaderKeys, } from "./header-case.js";
 import { headerObjectOf } from "./headers.js";
-import { jsonError, pathnameOf, plainError, urlPartsOf } from "./http.js";
+import { isRoutableMethod, jsonError, pathnameOf, plainError, urlPartsOf, } from "./http.js";
 import { withStaticNodeHeaders } from "./node-outcome.js";
 import { queryObjectOf, searchOf } from "./query.js";
-import { RequestContext, readBodyFramed } from "./request-context.js";
+import { PLATFORM_PEER, RequestContext, readBodyFramed, } from "./request-context.js";
+import { recordRequestReplacement } from "./request-lineage.js";
+import { hasDotSegment, resolveDotSegments } from "./request-target.js";
 import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, toResponse, } from "./respond.js";
 import { CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, isResponseResult, requestOf, } from "./runtime-core.js";
 import { normalizeStaticResponseHeaders } from "./static-headers.js";
 import { plainValidationError } from "./validation.js";
-import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, RESOLVE_NODE_MOUNT, } from "./install.js";
+import { NIFRA_BACKEND_WS_RUNTIME } from "../mount.js";
+import { GET_WS_RUNTIME, INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_NOT_FOUND, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, RESOLVE_NODE_MOUNT, } from "./install.js";
 import { jsonLogger } from "./logger.js";
+// CORS uses this marker to say its request hook only handles OPTIONS preflight. Bun can keep
+// ordinary registered routes on its native table and send unmatched OPTIONS requests through the
+// normal fetch fallback where the hook still runs.
+const BUN_NATIVE_REQUEST_SAFE = Symbol.for("@nifrajs/core/bun-native-request-safe");
 const functionToString = Function.prototype.toString;
 const CONTEXTLESS_ARROW = /^(?:async\s*)?\(\s*\)\s*(?::[\s\S]*?)?=>/;
-/** The socket peer Bun observed, as a `Platform` for the request lifecycle (`undefined` if unknown).
- * Typed structurally on `requestIP` alone so any Bun `Server` (WS or not) satisfies it. */
+/** The socket peer Bun observed, as a `Platform` for the request lifecycle (`undefined` if unknown). */
 function bunPeerPlatform(server, req) {
-    // Bun's requestIP() is surprisingly expensive (~20 us on the SSR benchmark machine). Keep the
+    // Bun's requestIP() costs ~0.5 us per call, about 7% of a bare GET's server time. Keep the
     // documented raw-peer c.clientIp behavior, but resolve it lazily: most routes never read c.clientIp,
-    // and paying for the socket lookup on every request erased Bun's native HTTP advantage. A getter also
+    // so they should not pay for the socket lookup on every request. A getter also
     // preserves middleware that inspects the platform argument directly and trust-mode routes, which
     // resolve the value in deriveClientIp before the handler runs.
     let resolved = false;
@@ -46,7 +53,38 @@ function bunPeerPlatform(server, req) {
         },
     };
 }
+/**
+ * Whether the portable router gives `other` a request that `route` also matches: the two patterns can
+ * match one path, and `other` is the more specific at the first segment where they differ. `route`
+ * holds static and `:param` segments only; `other` has a wildcard or a part-literal segment.
+ *
+ * It errs toward `true`. A segment that is part literal, part parameter is taken to match whatever
+ * `route` has in that position.
+ */
+function outranks(other, route) {
+    let ahead = false;
+    for (let i = 0; i < route.length; i++) {
+        const theirs = other[i];
+        if (theirs === undefined)
+            return false;
+        if (theirs.kind === "wildcard")
+            return ahead;
+        const ours = route[i];
+        if (ours.kind === "static") {
+            if (theirs.kind === "static" ? theirs.value !== ours.value : !ahead)
+                return false;
+        }
+        else if (theirs.kind !== "param")
+            ahead = true;
+    }
+    return ahead && other.length === route.length;
+}
 const WS_PASS = { kind: "pass" };
+const DEFAULT_WS_UPGRADE_TIMEOUT_MS = 10_000;
+/** Counts `ws()` routes and `mount()`s across every app in this copy of core: the only
+ * changes that can make a mounted app take WebSocket upgrades. An app's answer to that question
+ * (`mountsTakeUpgrades`) is kept until this moves. */
+let wsChanges = 0;
 /** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
 function requireWsRuntime(runtime) {
     if (runtime === undefined) {
@@ -87,13 +125,27 @@ export { plainValidationError } from "./validation.js";
 // Query-string + urlencoded-form parsing now lives in `./query.ts`; re-exported so existing
 // importers keep resolving `searchOf`/`queryObjectOf`/`QueryValue` from here.
 export { queryObjectOf, searchOf };
-function hasReplacementParam(params) {
+/**
+ * A param value Bun's native route table matched but the portable router must decide: an invalid
+ * escape, or a piece of path Bun matched raw while its own parsed URL says otherwise - a `.` / `..`
+ * segment (Bun hands `%2e` over decoded), or a backslash, which the parsed URL reads as `/`.
+ */
+const unroutedParam = (value) => value !== undefined &&
+    (value.includes("\uFFFD") || value.includes("\\") || value === "." || value === "..");
+function hasUnroutedParam(params) {
     for (const key in params) {
-        if (params[key].includes("\uFFFD"))
+        if (unroutedParam(params[key]))
             return true;
     }
     return false;
 }
+/**
+ * Deno is the runtime that hands an app a `Request` whose `url` is the target as the client sent it;
+ * Bun, workerd and every `new Request()` parse it first. Only there does `fetch` read the URL up front.
+ */
+const rawRequestTargets = typeof globalThis.Deno !== "undefined";
+/** `req` as Bun or workerd would have delivered it: the same request, its URL's dot segments resolved. */
+const withResolvedTarget = (req) => new Request(resolveDotSegments(req.url), req);
 function normalizeMountPrefix(path) {
     if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
         throw new TypeError("mountFetch path must be an absolute pathname without a query or hash");
@@ -111,6 +163,17 @@ function normalizeMountPrefix(path) {
 function underMountPrefix(pathname, prefix) {
     return prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`);
 }
+function mountPriorityOf(priority) {
+    if (priority === undefined)
+        return 0;
+    if (!Number.isSafeInteger(priority)) {
+        throw new TypeError("mount priority must be a safe integer");
+    }
+    return priority;
+}
+function compareMounts(a, b) {
+    return b.priority - a.priority || b.path.length - a.path.length || a.order - b.order;
+}
 function stripMountPrefix(request, prefix) {
     if (prefix === "/")
         return request;
@@ -139,6 +202,68 @@ function isContextlessNoArgArrow(handler) {
  * these renders happen where no request context exists - before routing, or after it was abandoned.
  */
 const webResponseOf = (result) => result instanceof Response ? result : toResponse(result, EMPTY_RESPONSE_CONTROLS);
+/** A `group(prefix)` hook's scope: every request whose path is the prefix or lies under it - served,
+ * 404, 405, or preflight alike (Hono's `use("/api/*")` reach). The router matches static segments
+ * byte-exactly and case-sensitively, with the same path scanner used here, so no spelling a group
+ * route answers to can fall outside this test. */
+const underPrefix = (prefix) => {
+    const nested = `${prefix}/`;
+    return (req) => {
+        const path = pathnameOf(req.url);
+        return path === prefix || path.startsWith(nested);
+    };
+};
+/** A merged server's hook scope: exactly the routes MERGED, snapshotted into a dedicated matcher so
+ * the guard never reflects whatever the source's own catalog grows into afterwards. */
+const servedBy = (routes) => {
+    const scope = new RouteCatalog();
+    scope.addBatch(routes);
+    return (req) => scope.find(req.method, pathnameOf(req.url)).found;
+};
+/** Gate adopted hooks to `inScope` (`undefined`: adopt them unchanged). The request is a request
+ * hook's first argument (`reqAt` 0) and every response-side hook's second; out of scope a hook
+ * declines, except a Web response hook, which must hand the response on (`passFirst`). An
+ * `undefined` slot marks an unpaired Node twin, position-aligned with its Web list, and stays
+ * `undefined` - wrapping it would fabricate a twin that never existed. */
+const scopeHooks = (hooks, inScope, reqAt, passFirst) => inScope === undefined
+    ? hooks
+    : hooks.map((hook) => hook === undefined
+        ? hook
+        : ((first, second) => inScope(reqAt === 0 ? first : second)
+            ? hook(first, second)
+            : passFirst && first));
+/** A `group()` prefix: `/`-led segments of RFC 3986 `pchar` minus `%` and `:`, none of them `.` or
+ * `..`. That is text the router compares byte-for-byte as static, so a prefix can never smuggle a
+ * param, a wildcard, or an escape, and never spells a path (dot or empty segment, trailing slash)
+ * that no normalized client URL reaches. Segments are delimited by a `/` the class excludes, so the
+ * match is linear. */
+const GROUP_PREFIX = /^(?:\/(?!\.\.?(?:\/|$))[\w.~!$&'()+,;=@-]+)+$/;
+/** The order-scoped chain a group scope inherits - copied, so what the group adds stays its own. */
+const GROUP_CHAIN = [
+    "derives",
+    "authStages",
+    "beforeHandleHooks",
+    "afterHandleHooks",
+    "onErrorHooks",
+    "aroundHooks",
+    "activeAssurance",
+    // Inherited so a group route computes `authenticated` (idempotency principal scoping) exactly as a
+    // parent route would; only the evidence the group adds is folded at adoption.
+    "globalAssurance",
+    "capabilityInterceptors",
+    "capabilityObservers",
+];
+/** Installed runtimes: a group scope inherits them, and adoption hoists a source's into a server that
+ * has none, so composing servers cannot silently disable a safety lane. */
+const SERVER_RUNTIMES = [
+    "responseContractRuntime",
+    "idempotencyRuntime",
+    "effectLedgerRuntime",
+    "mcpRuntime",
+    "nodeOutcomeRuntime",
+    "sseRuntime",
+    "wsRuntime",
+];
 // Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
 const IDENTITY_RESPONSE = (response) => webResponseOf(response);
 const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
@@ -231,6 +356,10 @@ export class Server {
     /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
     wsRouter;
     wsRouteCount;
+    /** `wsChanges` when `wsMountsLive` was last worked out; -1 until then. */
+    wsMountsCheckedAt = -1;
+    /** Whether an app mounted here takes WebSocket upgrades, as of `wsMountsCheckedAt`. */
+    wsMountsLive = false;
     /** In-process pub/sub backing `ws.subscribe(topic)` + `app.publish(topic, data)` (single-instance).
      * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime - `undefined` until then, so a
      * no-WebSocket app never constructs (or bundles) it. */
@@ -240,7 +369,8 @@ export class Server {
      * rather than delegate to Bun's native `server.publish`. */
     wsHasValidatedSend = false;
     /** Bun's native topic broadcast, bound by `listen()` in native-pubsub mode; `app.publish` uses it
-     * instead of the JS registry. `undefined` off Bun, before `listen()`, or with a validated-send route. */
+     * instead of the JS registry. `undefined` off Bun, before `listen()`, with a validated-send route,
+     * or when a mounted app takes upgrades. */
     nativePublish;
     maxBodyBytes;
     protoPoisoning;
@@ -248,6 +378,7 @@ export class Server {
     trustBodyFraming;
     wsMaxPayloadBytes;
     requestTimeoutMs;
+    wsUpgradeTimeoutMs;
     /** Installed by the `responseContract()` plugin; `undefined` = not installed, which is the default
      * and the state in which a declared `response` schema stays a compile-time contract only. */
     responseContractRuntime;
@@ -259,6 +390,9 @@ export class Server {
     gracefulSignals;
     stopHooks;
     fetchMounts;
+    mountOrder;
+    /** Number of composed mounts that must run before the parent route table. Keeps legacy mounts off the hot path. */
+    preRouteMountCount;
     /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
     capacityGate;
     onCapabilityUse;
@@ -272,6 +406,8 @@ export class Server {
     idempotencyRuntime;
     /** Installed opt-in runtime for `.tool()`/`.resource()`/`.prompt()`; `undefined` until `.use(mcp())`. */
     mcpRuntime;
+    /** Installed answer for a request no route matched; `undefined` (the plain 404) until `.use(notFound())`. */
+    notFoundLane;
     /** Installed Node-direct renderer for direct `resolveNode()` callers; `undefined` until `.use(nodeDirect())`. */
     nodeOutcomeRuntime;
     /** Installed streaming runtime for `.sse()` routes; `undefined` until `.use(streaming())`. */
@@ -286,6 +422,8 @@ export class Server {
     bunServer;
     sealed;
     derives;
+    /** Dedicated authentication stages captured by subsequent routes. */
+    authStages;
     decorations;
     beforeHandleHooks;
     afterHandleHooks;
@@ -295,10 +433,14 @@ export class Server {
     onNodeRequestHooks;
     /** Registration-time eligibility for the Node request twin lane. */
     nodeRequestHooksComplete;
+    /** True when every request hook is safe to skip on a Bun native route. */
+    bunNativeRequestHooksSafe;
     onResponseHooks;
     onNodeResponseHooks;
     /** Registration-time eligibility for the Node response twin lane. */
     nodeResponseHooksComplete;
+    /** True when every response hook only mutates headers and can run after a Bun fused response. */
+    bunNativeResponseHeadersOnly;
     /**
      * True once a bundle registers a RAW `onNodeResponse` twin - one handed the outcome's header
      * record itself rather than the case-normalizing view. Their names are contractually the wire
@@ -327,7 +469,7 @@ export class Server {
     responseSources;
     /** Memoized NodeRequestContext per plain-`Request` source - see {@link nodeRequestContextOf}. */
     nodeContexts;
-    /** Names of plugins/middleware already applied via `use` - for idempotent dedupe. */
+    /** Plugins/middleware already applied via `use`, by name - for idempotent dedupe. */
     appliedPlugins;
     /** Order-scoped evidence captured by routes registered after an assured plugin. */
     activeAssurance;
@@ -336,7 +478,14 @@ export class Server {
     /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
     mcpResourceList;
     mcpPromptList;
+    /** Kept so a {@link group} scope is built with exactly this server's settings: fused lanes read
+     * several of them at request time, so a group route must never run under different ones. */
+    options;
+    /** Static prefix joined onto every route this server registers; non-empty only on a group scope. */
+    routePrefix;
     constructor(options = {}) {
+        this.options = options;
+        this.routePrefix = "";
         this.catalog = new RouteCatalog();
         this.wsRouter = new Router();
         this.wsRouteCount = 0;
@@ -350,6 +499,7 @@ export class Server {
         this.maxBodyBytes = maxBodyBytes;
         this.wsMaxPayloadBytes = wsMaxPayloadBytes;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
+        this.wsUpgradeTimeoutMs = options.wsUpgradeTimeoutMs ?? DEFAULT_WS_UPGRADE_TIMEOUT_MS;
         this.clientIpTrust = options.clientIp;
         this.acceptInboundDeadlines = options.acceptInboundDeadlines ?? false;
         this.maxInboundDeadlineMs = options.maxInboundDeadlineMs ?? 30_000;
@@ -360,12 +510,17 @@ export class Server {
         if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs < 0) {
             throw new RangeError("requestTimeoutMs must be a finite non-negative number");
         }
+        if (!Number.isFinite(this.wsUpgradeTimeoutMs) || this.wsUpgradeTimeoutMs < 0) {
+            throw new RangeError("wsUpgradeTimeoutMs must be a finite non-negative number");
+        }
         if (!Number.isFinite(this.maxInboundDeadlineMs) || this.maxInboundDeadlineMs <= 0) {
             throw new RangeError("maxInboundDeadlineMs must be a finite positive number");
         }
         this.gracefulSignals = options.gracefulSignals ?? false;
         this.stopHooks = [];
         this.fetchMounts = [];
+        this.mountOrder = 0;
+        this.preRouteMountCount = 0;
         this.capacityGate = options.admission;
         this.onCapabilityUse = options.onCapabilityUse;
         this.capabilityInterceptors = [];
@@ -388,6 +543,7 @@ export class Server {
             beginHookAudit(this, options.unusedScopedHooks ?? "warn", options.logger !== undefined);
         }
         this.derives = [];
+        this.authStages = [];
         this.decorations = {};
         this.beforeHandleHooks = [];
         this.afterHandleHooks = [];
@@ -396,9 +552,11 @@ export class Server {
         this.onRequestHooks = [];
         this.onNodeRequestHooks = [];
         this.nodeRequestHooksComplete = true;
+        this.bunNativeRequestHooksSafe = true;
         this.onResponseHooks = [];
         this.onNodeResponseHooks = [];
         this.nodeResponseHooksComplete = true;
+        this.bunNativeResponseHeadersOnly = true;
         this.hasRawNodeResponseHook = false;
         this.onResponseFinalizedHooks = [];
         this.staticResponseHeaders = undefined;
@@ -409,7 +567,7 @@ export class Server {
         this.responseRequests = new WeakMap();
         this.responseSources = new WeakMap();
         this.nodeContexts = new WeakMap();
-        this.appliedPlugins = new Set();
+        this.appliedPlugins = new Map();
         this.activeAssurance = [];
         this.globalAssurance = [];
         this.mcpResourceList = [];
@@ -417,7 +575,7 @@ export class Server {
     }
     assertConfigurable(operation) {
         if (this.sealed) {
-            throw new FrameworkError("SERVER_SEALED", `server configuration is sealed after listen(); call ${operation} before listen()`);
+            throw new FrameworkError("SERVER_SEALED", `server configuration is sealed after listen() (a group once its builder returns); call ${operation} before`);
         }
     }
     /** Register a callback awaited after graceful drain and server stop. Hung callbacks are bounded. */
@@ -441,9 +599,70 @@ export class Server {
             path: normalizeMountPrefix(path),
             handler: handler,
             stripPrefix: options.stripPrefix === true,
+            priority: mountPriorityOf(options.priority),
+            fallbackOn404: options.fallbackOn === 404,
+            beforeRoutes: false,
+            order: this.mountOrder++,
+            opaque: options.opaque,
         };
         this.fetchMounts.push(mount);
-        this.fetchMounts.sort((a, b) => b.path.length - a.path.length);
+        this.fetchMounts.sort(compareMounts);
+        return this;
+    }
+    /**
+     * Compose a child fetch app under a literal path prefix.
+     *
+     * Composed mounts run after the app-global request phase and before the parent's route table. This
+     * makes them safe to use in an SSR shell whose `/*` page route would otherwise swallow an API mount.
+     * If the child exposes `resolveWebSocketUpgrade`, the same mount also participates in adapter-owned
+     * WebSocket upgrades; the serving adapter still upgrades its original socket, while the child sees
+     * the mounted request path (stripped when requested).
+     *
+     * `fallbackOn: 404` is deliberately limited to GET/HEAD/OPTIONS at dispatch time. Those methods are
+     * replayable without buffering an untrusted request body; POST/PUT/PATCH and streaming requests
+     * never get retried after a child has had a chance to consume them.
+     */
+    mount(options) {
+        this.assertConfigurable("mount()");
+        if (options === null || typeof options !== "object") {
+            throw new TypeError("mount() requires { path, app }");
+        }
+        const app = options.app;
+        if (app === null || typeof app !== "object") {
+            throw new TypeError("mount() app must be an object with fetch()");
+        }
+        if (typeof app.fetch !== "function") {
+            throw new TypeError("mount() app.fetch must be a function");
+        }
+        const resolver = typeof app.resolveWebSocketUpgrade === "function"
+            ? app.resolveWebSocketUpgrade.bind(app)
+            : undefined;
+        // Bun needs a websocket callback table in the parent process. A composed Nifra app names the
+        // runtime its upgrades need through this internal seam, which `listen()` asks (see
+        // `[GET_WS_RUNTIME]`); a resolver without it names none. Adapters that wire standard sockets use
+        // the resolver outcome's own `attach`.
+        const getRuntime = app[GET_WS_RUNTIME] ?? app[NIFRA_BACKEND_WS_RUNTIME];
+        const mount = {
+            path: normalizeMountPrefix(options.path),
+            handler: app.fetch.bind(app),
+            ...(resolver === undefined
+                ? {}
+                : {
+                    resolveWebSocketUpgrade: resolver,
+                    wsRuntime: typeof getRuntime === "function" ? getRuntime.bind(app) : () => null,
+                }),
+            stripPrefix: options.stripPrefix === true,
+            priority: mountPriorityOf(options.priority),
+            fallbackOn404: options.fallbackOn === 404,
+            beforeRoutes: true,
+            order: this.mountOrder++,
+            opaque: options.opaque,
+            app,
+        };
+        this.fetchMounts.push(mount);
+        this.fetchMounts.sort(compareMounts);
+        this.preRouteMountCount += 1;
+        wsChanges += 1;
         return this;
     }
     /**
@@ -469,6 +688,30 @@ export class Server {
      * by none before; one added after the last route reaches nothing
      * (see {@link ServerOptions.unusedScopedHooks}).
      */
+    /**
+     * Register a dedicated authentication stage for subsequent routes.
+     *
+     * Unlike `derive`, this stage receives a body-blind authentication capsule and is compiled before
+     * route validation. Keeping it separate prevents an unrelated derive from accidentally becoming a
+     * security gate and lets the route compiler retain a protected fast lane.
+     */
+    authenticate(stage) {
+        this.assertConfigurable("authenticate()");
+        if (stage === null || typeof stage !== "object") {
+            throw new TypeError("authenticate() requires an authentication stage");
+        }
+        if (typeof stage.id !== "string" || stage.id.trim() === "") {
+            throw new TypeError("authenticate() stage id must be a non-empty string");
+        }
+        if (typeof stage.run !== "function") {
+            throw new TypeError("authenticate() stage run must be a function");
+        }
+        if (stage.mode !== undefined && stage.mode !== "sync" && stage.mode !== "async") {
+            throw new TypeError('authenticate() stage mode must be "sync" or "async"');
+        }
+        this.authStages.push(stage);
+        return this;
+    }
     decorate(key, value) {
         this.assertConfigurable("decorate()");
         this.decorations[key] = value;
@@ -485,6 +728,7 @@ export class Server {
         this.onRequestHooks.push(fn);
         this.onNodeRequestHooks.push(undefined);
         this.nodeRequestHooksComplete = false;
+        this.bunNativeRequestHooksSafe = false;
         return this;
     }
     /**
@@ -569,6 +813,7 @@ export class Server {
         this.onResponseHooks.push(fn);
         this.onNodeResponseHooks.push(undefined);
         this.nodeResponseHooksComplete = false;
+        this.bunNativeResponseHeadersOnly = false;
         return this;
     }
     /**
@@ -585,7 +830,8 @@ export class Server {
      *   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
+     * wins, whatever casing it used. In a group, a name the group declares replaces the value its
+     * enclosing scopes declared before the group, on the group's routes. 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.
      *
@@ -617,7 +863,7 @@ export class Server {
             // serialized-body marker survives for later `onResponseBody`/`onResponseRaw` observers and the
             // Node writer; reconstructing a `Response` here would strip that marker and reclassify the Node
             // outcome from `json` to a generic `response`. A guarded foreign response takes its clone path.
-            const statics = buildStaticResponseHeaders(record);
+            const statics = buildStaticResponseHeaders(record, this.inheritedStatics);
             this.onResponseHooks.push((response) => applyStaticResponseHeaders(response, statics));
             this.onNodeResponseHooks.push(undefined);
             this.nodeResponseHooksComplete = false;
@@ -626,7 +872,7 @@ export class Server {
         const merged = this.staticResponseHeaders === undefined
             ? record
             : { ...this.staticResponseHeaders.record, ...record };
-        this.staticResponseHeaders = buildStaticResponseHeaders(merged);
+        this.staticResponseHeaders = buildStaticResponseHeaders(merged, this.inheritedStatics);
         const statics = this.staticResponseHeaders;
         this.wrapWebResponse = (response) => applyStaticResponseHeaders(webResponseOf(response), statics);
         this.webResponseTimeout = () => applyStaticResponseHeaders(RESPONSE_TIMEOUT(), statics);
@@ -654,24 +900,36 @@ export class Server {
         this.onResponseFinalizedHooks.push(fn);
         return this;
     }
-    use(arg) {
+    use(input) {
+        // A method-routes plugin is an ordinary plugin function; only its type is opaque.
+        const arg = input;
         this.assertConfigurable("use()");
-        if (typeof arg === "function") {
-            const name = arg.pluginName;
-            if (name !== undefined) {
-                if (this.appliedPlugins.has(name))
-                    return this; // idempotent: already applied
-                this.appliedPlugins.add(name);
+        const name = typeof arg === "function" ? arg.pluginName : arg.name;
+        if (name !== undefined) {
+            if (this.appliedPlugins.has(name)) {
+                const parent = this.inheritedPlugins?.get(name);
+                // A group's builder passing another instance of a plugin its parent applied would have it
+                // dropped, configuration and all. A plugin's own dependency use() shares the parent's copy.
+                if (parent !== undefined && parent !== arg) {
+                    throw new RouteConfigError("PLUGIN_RECONFIGURED", `use() of ${JSON.stringify(name)} in a group: its parent applied another instance`);
+                }
+                return this; // idempotent: already applied
             }
+            this.appliedPlugins.set(name, arg);
+        }
+        if (typeof arg === "function") {
             const evidence = assuranceDeclarationsOf(arg);
             const pluginOnly = evidence.filter((item) => item.scope === "plugin");
             this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"));
             this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"));
             this.activeAssurance.push(...pluginOnly);
+            const inherited = this.inheritedPlugins;
+            this.inheritedPlugins = undefined;
             try {
                 return arg(this);
             }
             finally {
+                this.inheritedPlugins = inherited;
                 // Remove only this plugin's temporary evidence. Nested assured plugins may deliberately leave
                 // subsequent evidence active, so truncating the whole array would lose real ordering semantics.
                 for (const item of pluginOnly) {
@@ -681,11 +939,6 @@ export class Server {
                 }
             }
         }
-        if (arg.name !== undefined) {
-            if (this.appliedPlugins.has(arg.name))
-                return this;
-            this.appliedPlugins.add(arg.name);
-        }
         const evidence = assuranceDeclarationsOf(arg);
         if (evidence.some((item) => item.scope === "plugin")) {
             throw new Error('route assurance: scope "plugin" may only annotate a plugin function');
@@ -707,6 +960,9 @@ export class Server {
             this.onNodeRequestHooks.push(arg.onNodeRequest);
             if (arg.onNodeRequest === undefined)
                 this.nodeRequestHooksComplete = false;
+            if (!arg[BUN_NATIVE_REQUEST_SAFE]) {
+                this.bunNativeRequestHooksSafe = false;
+            }
         }
         else if (arg.onNodeRequest !== undefined) {
             throw new TypeError("onNodeRequest() requires a paired onRequest() hook");
@@ -725,6 +981,7 @@ export class Server {
                 this.nodeResponseHooksComplete = false;
             else
                 this.hasRawNodeResponseHook = true;
+            this.bunNativeResponseHeadersOnly = false;
         }
         else if (arg.onNodeResponse !== undefined) {
             throw new TypeError("onNodeResponse() requires a paired onResponse() hook");
@@ -733,10 +990,18 @@ export class Server {
         // 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.responseObserverMethods().onResponseHeaders(arg.onResponseHeaders);
-        if (arg.onResponseBody !== undefined)
-            this.responseObserverMethods().onResponseBody(arg.onResponseBody);
+        if (arg.onResponseHeaders !== undefined) {
+            this.responseObserverMethods().onResponseHeaders(arg.onResponseHeaders, arg.onNodeResponseHeaders);
+        }
+        else if (arg.onNodeResponseHeaders !== undefined) {
+            throw new TypeError("onNodeResponseHeaders() requires a paired onResponseHeaders() hook");
+        }
+        if (arg.onResponseBody !== undefined) {
+            this.responseObserverMethods().onResponseBody(arg.onResponseBody, arg.onNodeResponseBody);
+        }
+        else if (arg.onNodeResponseBody !== undefined) {
+            throw new TypeError("onNodeResponseBody() requires a paired onResponseBody() hook");
+        }
         if (arg.onResponseRaw !== undefined)
             this.responseObserverMethods().onResponseRaw(arg.onResponseRaw);
         if (arg.onResponseFinalized !== undefined)
@@ -855,10 +1120,11 @@ export class Server {
         this.topics ??= runtime.createTopics();
         // A `messageSchema` wraps `message` with validation once, here - every adapter then dispatches
         // already-validated, typed messages (Bun/Deno/Node/Workers) with no per-adapter code.
-        this.wsRouter.add("GET", path, {
-            handler: runtime.wrapHandler(handler),
-        });
+        const entry = { handler: runtime.wrapHandler(handler, this.protoPoisoning) };
+        for (const form of expandOptionalParams(path))
+            this.wsRouter.add("GET", form, entry);
         this.wsRouteCount += 1;
+        wsChanges += 1;
         return this;
     }
     /**
@@ -898,16 +1164,37 @@ export class Server {
      * is the "compiled", order-scoped per-route chain.
      */
     register(method, path, schema, handler) {
-        this.assertConfigurable("route registration");
-        this.catalog.add(this.prepareRoute(method, path, schema, handler));
+        this.registerBatch([{ method, path, schema, handler }]);
     }
     /** Register a contract/group route batch atomically. Every route captures the same current chain it
-     * would capture through {@link register}; no route becomes visible unless the full batch validates. */
+     * would capture through {@link register}; no route becomes visible unless the full batch validates.
+     *
+     * A path ending in optional parameters (`/users/:id?`) is one catalog route per concrete pattern,
+     * so reflection, OpenAPI, evidence and the typed client all see ordinary routes. */
     registerBatch(routes) {
         this.assertConfigurable("route registration");
-        const staged = routes.map(({ method, path, schema, handler }) => this.prepareRoute(method, path, schema, handler));
+        const staged = [];
+        for (const { method, path, schema, handler } of routes) {
+            for (const form of expandOptionalParams(this.prefixed(path))) {
+                staged.push(this.prepareRoute(method, form, schema, handler));
+            }
+        }
         this.catalog.addBatch(staged);
     }
+    /** Join a group scope's prefix BEFORE compilation, so the pattern, the reflected descriptor, the
+     * capability guard, the ledger record, and assurance path matching all see the one served path. */
+    prefixed(path) {
+        const prefix = this.routePrefix;
+        if (prefix === "")
+            return path;
+        if (path === "/")
+            return prefix;
+        // Checked here, not left to the pattern compiler: `"/api" + "users"` is a valid-looking path
+        // (`/apiusers`) that would silently escape the group instead of failing.
+        if (path[0] === "/")
+            return prefix + path;
+        throw new RouteConfigError("INVALID_PATH", `group(${JSON.stringify(prefix)}) route path must start with "/": ${JSON.stringify(path)}`);
+    }
     prepareRoute(method, path, schema, handler) {
         const compiled = compileRouteOptions({
             maxBodyBytes: this.maxBodyBytes,
@@ -921,6 +1208,7 @@ export class Server {
             idempotencyRuntime: this.idempotencyRuntime,
             responseContractRuntime: this.responseContractRuntime,
             derives: this.derives,
+            authStages: this.authStages,
             beforeHandleHooks: this.beforeHandleHooks,
             afterHandleHooks: this.afterHandleHooks,
             onErrorHooks: this.onErrorHooks,
@@ -928,16 +1216,30 @@ export class Server {
             defaultOnValidationError: this.defaultOnValidationError,
         }, method, path, schema, handler);
         const { pattern, bodyLimit, capabilities, routeDecorations, hasDecorations, idempotent, ledgered, responseContract, lanes, routeAssurance, } = compiled;
+        if (idempotent !== undefined && this.idempotencyRuntime !== undefined) {
+            handler = this.idempotencyRuntime.wrapHandler(handler);
+        }
         const { bare, fusedQuery, fusedBody } = lanes;
-        const fusedBodyRunner = fusedBody
-            ? this.buildFusedBodyRunner(handler, schema?.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? UNLIMITED_BODY_BYTES)
-            : undefined;
         // Fused lifecycle lanes: derive + before (with or without an after), and body + the same shape.
         // The lane selectors in `selectRouteLanes` are exhaustive about the lifecycleHookLane /
         // body-derive-before-after eligibility, so we only need to check the lane and the hook counts.
         const lifecycleHookLane = lanes.lifecycleHookLane;
         const isFusedLifecycle = lifecycleHookLane !== undefined && this.derives.length === 1;
         const isFusedBodyLifecycle = lanes.fusedLane === "body-derive-before" || lanes.fusedLane === "body-derive-before-after";
+        // The generic runners below are the Node-direct twins of the fused Web lanes built further
+        // down: same single-frame lifecycle, finalizing through the caller's own `finalize` instead of
+        // building a `Response`, so the `!webFast` dispatcher prefers them over the generic program
+        // exactly as it prefers the body-only runner. Only the original body-only lane may feed the Web
+        // wrapper; every other runner here preserves its derive/before/after stages.
+        const fusedBodyRunner = fusedBody
+            ? this.buildFusedBodyRunner(handler, schema?.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? UNLIMITED_BODY_BYTES)
+            : isFusedBodyLifecycle
+                ? this.buildFusedBodyDeriveBeforeAfterRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                : isFusedLifecycle && lifecycleHookLane === "derive-before"
+                    ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], undefined, schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                    : isFusedLifecycle && lifecycleHookLane === "derive-before-after"
+                        ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? UNLIMITED_BODY_BYTES)
             : fusedQuery
@@ -955,6 +1257,7 @@ export class Server {
             schema,
             handler: handler,
             derives: this.derives,
+            authStages: compiled.authStages,
             beforeHandle: this.beforeHandleHooks,
             afterHandle: this.afterHandleHooks,
             onError: this.onErrorHooks,
@@ -982,6 +1285,7 @@ export class Server {
             ledgered,
             responseContract,
             derives: [...this.derives],
+            authStages: [...compiled.authStages],
             decorations: routeDecorations,
             hasDecorations,
             beforeHandle: [...this.beforeHandleHooks],
@@ -996,6 +1300,9 @@ export class Server {
             method,
             path,
             schema,
+            ...(responseContract === undefined
+                ? {}
+                : { responseContract: responseContract.runtime.mode }),
             ...(capabilities.length > 0 ? { capabilities } : {}),
             ...(schema?.family === true ? { family: true } : {}),
         };
@@ -1023,11 +1330,13 @@ export class Server {
         this.assertConfigurable("responseObserver()");
         const methods = runtime.install({
             assertConfigurable: (operation) => this.assertConfigurable(operation),
-            addResponseHook: (web, node) => {
+            addResponseHook: (web, node, headerOnly = false) => {
                 this.onResponseHooks.push(web);
                 this.onNodeResponseHooks.push(node);
                 if (node === undefined)
                     this.nodeResponseHooksComplete = false;
+                if (!headerOnly)
+                    this.bunNativeResponseHeadersOnly = false;
             },
             enableResponseBodyTagging: () => {
                 if (this.responseBodyTag === undefined) {
@@ -1051,6 +1360,11 @@ export class Server {
         this.assertConfigurable("mcp()");
         this.mcpRuntime = runtime;
     }
+    /** @internal Symbol-keyed install seam for the `notFound()` plugin. Off the public typed surface. */
+    [INSTALL_NOT_FOUND](lane) {
+        this.assertConfigurable("notFound()");
+        this.notFoundLane = lane;
+    }
     /** @internal Symbol-keyed install seam for the `nodeDirect()` plugin. Off the public typed surface. */
     [INSTALL_NODE_DIRECT](runtime) {
         this.assertConfigurable("nodeDirect()");
@@ -1066,6 +1380,41 @@ export class Server {
         this.assertConfigurable("websocket()");
         this.wsRuntime = runtime;
     }
+    /**
+     * @internal The runtime Bun serves this app's WebSocket upgrades with, asked by `listen()` and by a
+     * parent that mounts this app: `undefined` while nothing here can take one, `null` when something
+     * can but no runtime is at hand. A mounted Nifra app answers through this same seam, so mounting an
+     * app without a WebSocket route needs no runtime; a resolver without the seam cannot say, so it
+     * counts. `seen` ends a mount cycle (an app mounted under itself to alias a prefix).
+     */
+    [GET_WS_RUNTIME](seen) {
+        return this.wsRouteCount > 0 ? this.wsRuntime : this.mountedWsRuntime(seen);
+    }
+    /** The `[GET_WS_RUNTIME]` answer for the apps mounted here alone, whatever this app's own routes. */
+    mountedWsRuntime(seen = new Set()) {
+        if (seen.has(this))
+            return;
+        seen.add(this);
+        let found;
+        for (const mount of this.fetchMounts) {
+            const runtime = mount.wsRuntime?.(seen);
+            if (runtime === undefined)
+                continue;
+            found = this.wsRuntime ?? runtime;
+            if (found)
+                return found;
+        }
+        return found;
+    }
+    /** Whether an app mounted here takes WebSocket upgrades. Worked out again only after a `ws()` or a
+     * `mount()` somewhere, so the upgrade check on a plain request costs one comparison. */
+    mountsTakeUpgrades() {
+        if (this.wsMountsCheckedAt !== wsChanges) {
+            this.wsMountsLive = this.mountedWsRuntime() !== undefined;
+            this.wsMountsCheckedAt = wsChanges;
+        }
+        return this.wsMountsLive;
+    }
     /**
      * Merge another server's routes into this one - the composition escape hatch for large apps.
      *
@@ -1092,75 +1441,188 @@ export class Server {
      */
     merge(other) {
         this.assertConfigurable("merge()");
+        if (!(other instanceof Server)) {
+            // A server from another copy of this package reaches this copy's private request state through
+            // symbols it does not share, and would fail per request. The boot warning names the copies.
+            throw new TypeError("merge() requires a server() from this copy of @nifrajs/core");
+        }
+        if (this.routePrefix !== "") {
+            // The merged routes were compiled under their own paths; adopting them here would publish them
+            // OUTSIDE the prefix while looking like part of the group.
+            throw new RouteConfigError("INVALID_PATH", "merge() inside a group cannot prefix compiled routes - merge on the parent");
+        }
         const source = other;
         if (source.wsRouteCount > 0) {
             throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes - register .ws() routes on the parent server");
         }
+        this.adopt(source, undefined, 0);
+        return this;
+    }
+    /**
+     * Declare routes under a static path prefix, with the prefix in the typed client, `routes()`,
+     * OpenAPI, capability events, and the effect ledger - the counterpart of Hono's `route()`,
+     * Elysia's `group()`, and Fastify's `register({ prefix })`.
+     *
+     *   app
+     *     .derive(session)
+     *     .group("/admin", (admin) =>
+     *       admin.beforeHandle(requireAdmin).get("/users", listUsers).get("/users/:id", getUser),
+     *     )
+     *     .get("/", home)          // not covered by requireAdmin
+     *
+     * The builder receives a scope that INHERITS this server's route chain as it stands at the call
+     * (`derive`/`decorate`/`authenticate`/`beforeHandle`/`afterHandle`/`onError`/`around`, assurance,
+     * capability interceptors, installed runtimes, applied plugins), exactly as a route declared here
+     * would. A plugin this server already applied is in effect for the group: the group's `use()` of
+     * that same instance does nothing, and its `use()` of another instance under the same name throws a
+     * `RouteConfigError` (`PLUGIN_RECONFIGURED`), because that instance could never replace the parent's.
+     * A plugin the group applies still shares the parent's copy of a dependency it `use()`s itself.
+     * What it adds stays in the group: its chain additions apply only to its own routes, and its
+     * request/response hooks (`onRequest`, `onResponse`, `responseHeaders`, `onResponseFinalized`, and
+     * middleware bundles that use them) run only for requests whose path is the prefix or below it.
+     * Per-route authorization belongs in `authenticate`/`beforeHandle`, which are compiled into each
+     * route; request hooks are path prefilters.
+     *
+     * The prefix is static text - `"/api"`, `"/api/v1"` - validated when declared: no params,
+     * wildcards, empty or dot segments, percent-escapes, or trailing slash. A group's `"/"` route
+     * serves the prefix itself. Groups nest (`"/api"` then `"/v1"` serves `/api/v1/...`).
+     *
+     * Fail closed: the builder must synchronously return the scope it was given; a collision with an
+     * existing route throws `RouteConfigError` and adds none of the group's routes; `.ws()`, mounts,
+     * MCP `.tool()`s, and `merge()` inside a group are refused (register them on the parent). Once the
+     * builder returns, the scope is closed - a leaked reference cannot add routes later.
+     */
+    group(prefix, build) {
+        this.assertConfigurable("group()");
+        if (typeof prefix !== "string" || !GROUP_PREFIX.test(prefix)) {
+            throw new RouteConfigError("INVALID_PATH", `group() prefix must be a static path like "/api/v1": ${JSON.stringify(prefix)}`);
+        }
+        const fullPrefix = this.routePrefix + prefix;
+        const scope = new Server(this.options);
+        scope.routePrefix = fullPrefix;
+        scope.inheritedStatics = { ...this.inheritedStatics, ...this.staticResponseHeaders?.record };
+        for (const key of GROUP_CHAIN)
+            scope[key].push(...this[key]);
+        for (const key of SERVER_RUNTIMES)
+            scope[key] = this[key];
+        Object.assign(scope.decorations, this.decorations);
+        // A plugin already applied here is already in effect for the group (its chain was copied above
+        // and its request hooks are app-wide), so re-applying it would run it twice per request. The
+        // group's own plugins are NOT copied back: they are scoped, and a parent `use()` of the same
+        // plugin must still apply it to the parent's routes. The response observer is the exception: it
+        // installs methods bound to the server it is applied to, so the scope must be free to install its
+        // own (re-applying it registers no hook, so nothing can run twice).
+        for (const [name, plugin] of this.appliedPlugins) {
+            if (name !== "nifra:response-observer")
+                scope.appliedPlugins.set(name, plugin);
+        }
+        scope.inheritedPlugins = new Map(scope.appliedPlugins);
+        let built;
+        try {
+            built = build(scope);
+            // Only `listen()` seals a server, so a scope sealed here was served on its own - without this
+            // server's request hooks - which a group must never be.
+            if (scope.sealed)
+                built = undefined;
+        }
+        finally {
+            // Closed on every exit, including a throw: an async continuation or a leaked reference must
+            // not register routes that nothing will ever adopt.
+            scope.sealed = true;
+        }
+        const label = `group(${JSON.stringify(fullPrefix)})`;
+        if (built !== scope) {
+            throw new TypeError(`${label} builder must return its group synchronously`);
+        }
+        if (scope.wsRouteCount > 0 ||
+            scope.fetchMounts.length > 0 ||
+            scope.catalog.entries().some((route) => route.descriptor.tool !== undefined)) {
+            throw new RouteConfigError("INVALID_PATH", `${label} cannot hold ws(), mount, or MCP tool routes - add them to the parent`);
+        }
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            sealHookAudit(scope, scope.catalog.size, this.logger);
+        this.adopt(scope, fullPrefix, this.globalAssurance.length);
+        return this;
+    }
+    /**
+     * Take over another server's routes and hooks - the shared core of {@link merge} and {@link group}.
+     * `prefix` selects group semantics: hooks are scoped to requests under the prefix (response hooks
+     * included), and the source's global assurance past `inheritedGlobal` (what it copied from this
+     * server) is folded into its routes. Without a prefix, merge semantics: request hooks are scoped to
+     * the source's routes when it has any, response hooks are appended app-wide.
+     */
+    adopt(source, prefix, inheritedGlobal) {
         const sourceRoutes = source.catalog.entries();
         // Hooks and global assurance stay LOCAL to a group that has routes; a route-less group is a
         // middleware bundle whose hooks can only mean app-wide intent, so it keeps the global append.
-        const scoped = sourceRoutes.length > 0;
-        // A group's global assurance rides its (route-scoped) hooks: folded into each merged route's
-        // own evidence rather than the parent's global list, so `routes()` never claims the group's
+        // A prefix group is always local: its hooks mean "under this path", routes or not.
+        const scoped = prefix !== undefined || sourceRoutes.length > 0;
+        const ownGlobal = source.globalAssurance.slice(inheritedGlobal);
+        // A group's global assurance rides its (scoped) hooks: folded into each adopted route's own
+        // evidence rather than the parent's global list, so `routes()` never claims the group's
         // enforcement for parent routes the group's hooks do not see.
-        const foldedAssurance = scoped && source.globalAssurance.length > 0
+        const foldedAssurance = scoped && ownGlobal.length > 0
             ? (route) => ({
                 ...route,
-                assurance: [...route.assurance, ...source.globalAssurance],
+                assurance: [...route.assurance, ...ownGlobal],
             })
             : (route) => route;
         this.catalog.addBatch(sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(route))));
         // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
-        // runtime object supplies the generic execution machinery. Preserve a group's installed runtime
-        // when the parent has none so merging cannot silently disable a safety lane. If the parent already
-        // has a runtime, either implementation can execute every resolved entry because route-specific
-        // options were pinned during registration.
-        this.responseContractRuntime ??= source.responseContractRuntime;
-        this.idempotencyRuntime ??= source.idempotencyRuntime;
-        this.effectLedgerRuntime ??= source.effectLedgerRuntime;
-        this.mcpRuntime ??= source.mcpRuntime;
-        this.nodeOutcomeRuntime ??= source.nodeOutcomeRuntime;
-        this.sseRuntime ??= source.sseRuntime;
-        this.wsRuntime ??= source.wsRuntime;
-        if (scoped && source.onRequestHooks.length > 0) {
-            // Snapshot the group's routes into a dedicated matcher: the guard must reflect what was
-            // MERGED, not whatever the group's own catalog grows into afterwards. One probe against it
-            // gates each group hook to requests the group would serve; everything else passes untouched.
-            const scope = new RouteCatalog();
-            scope.addBatch(sourceRoutes);
-            this.onRequestHooks.push(...source.onRequestHooks.map((hook) => (req, platform) => scope.find(req.method, pathnameOf(req.url)).found ? hook(req, platform) : undefined));
-            // An `undefined` slot marks an unpaired hook (position-aligned with `onRequestHooks`) and
-            // must stay `undefined` - wrapping it would fabricate a Node twin that never existed.
-            this.onNodeRequestHooks.push(...source.onNodeRequestHooks.map((hook) => hook === undefined
-                ? undefined
-                : (req, platform) => scope.find(req.method, pathnameOf(req.url)).found ? hook(req, platform) : undefined));
-        }
-        else {
-            this.onRequestHooks.push(...source.onRequestHooks);
-            this.onNodeRequestHooks.push(...source.onNodeRequestHooks);
-        }
+        // runtime object supplies the generic execution machinery. If the parent already has a runtime,
+        // either implementation can execute every resolved entry because route-specific options were
+        // pinned during registration.
+        const runtimes = this;
+        for (const key of SERVER_RUNTIMES)
+            runtimes[key] ??= source[key];
+        // Which requests a scoped hook sees: under the prefix for a group; for a merged server with
+        // routes, a snapshot of exactly the routes MERGED (not whatever its own catalog grows into later).
+        const inScope = prefix !== undefined
+            ? underPrefix(prefix)
+            : scoped && source.onRequestHooks.length > 0
+                ? servedBy(sourceRoutes)
+                : undefined;
+        this.onRequestHooks.push(...scopeHooks(source.onRequestHooks, inScope, 0));
+        this.onNodeRequestHooks.push(...scopeHooks(source.onNodeRequestHooks, inScope, 0));
         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.bunNativeRequestHooksSafe &&= source.bunNativeRequestHooksSafe;
+        // A merged server's response hooks are app-wide; a group's run only under its prefix.
+        const responseScope = prefix === undefined ? undefined : inScope;
+        const statics = source.staticResponseHeaders;
+        if (statics !== undefined) {
+            if (responseScope === undefined) {
+                // 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).
+                this.addStaticResponseHeaders({ ...statics.record });
+            }
+            else {
+                // The static tier is folded into EVERY response this server builds, so a group's static
+                // headers cannot join it. A hook ahead of the group's own (the sealed scope is discarded
+                // after adoption) keeps their meaning - defaults a value already on the response wins over.
+                source.onResponseHooks.unshift((response) => applyStaticResponseHeaders(response, statics));
+                source.onNodeResponseHooks.unshift(undefined);
+                source.nodeResponseHooksComplete = false;
+            }
+        }
+        this.onResponseHooks.push(...scopeHooks(source.onResponseHooks, responseScope, 1, true));
+        this.onNodeResponseHooks.push(...scopeHooks(source.onNodeResponseHooks, responseScope, 1));
+        this.onResponseFinalizedHooks.push(...scopeHooks(source.onResponseFinalizedHooks, responseScope, 1));
         this.nodeResponseHooksComplete &&= source.nodeResponseHooksComplete;
+        this.bunNativeResponseHeadersOnly &&= source.bunNativeResponseHeadersOnly;
         this.hasRawNodeResponseHook ||= source.hasRawNodeResponseHook;
-        this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks);
         if (source.responseBodyTag !== undefined) {
             const owner = this.enableResponseBodyTagging();
             this.responseBodyOwners.add(source.responseBodyTag);
             source.responseBodyOwners.add(owner);
         }
         if (!scoped)
-            this.globalAssurance.push(...source.globalAssurance);
+            this.globalAssurance.push(...ownGlobal);
+        // Cleanup the source registered (a pool, a queue consumer) belongs to the server that now runs
+        // its routes; dropping it would leak the resource past `stop()`.
+        this.stopHooks.push(...source.stopHooks);
         this.mcpResourceList.push(...source.mcpResourceList);
         this.mcpPromptList.push(...source.mcpPromptList);
-        return this;
     }
     /** A fused renderer closes over runtime services to keep its seven-argument JSC fast path. Merging
      * rebinds that closure once to the executing server; generic plans already receive the runtime. */
@@ -1173,15 +1635,30 @@ export class Server {
         const lane = entry.execution.fusedLane;
         // Type-erase the lane so each `===` branch sees the full union, not the narrowed remainder.
         const laneName = lane;
-        // Body+lifecycle routes have a fused Web renderer, but no body-only Node renderer: the latter
-        // would bypass derive/before/after because the Node-direct dispatcher prefers `fusedBody` over
-        // the generic execution plan. Only the original body-only lane may populate this slot.
-        const fusedBody = laneName === "body"
-            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
-            : undefined;
+        // Body+lifecycle routes have a fused Web renderer, and - unlike before - a generic fused
+        // runner too: it preserves derive/before/after (it IS the lifecycle, single-framed), so the
+        // Node-direct dispatcher's preference for the generic slot over the execution plan stays
+        // semantics-preserving. Only the original body-only lane may feed the Web wrapper below.
         const derive = entry.derives[0];
         const before = entry.beforeHandle[0];
         const after = entry.afterHandle[0];
+        const fusedBody = laneName === "body"
+            ? this.buildFusedBodyRunner(entry.handler, entry.schema?.body, entry.hasDecorations ? entry.decorations : undefined, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+            : laneName === "body-derive-before" && derive !== undefined && before !== undefined
+                ? this.buildFusedBodyDeriveBeforeAfterRunner(entry.handler, derive, before, undefined, entry.schema?.body, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+                : laneName === "body-derive-before-after" &&
+                    derive !== undefined &&
+                    before !== undefined &&
+                    after !== undefined
+                    ? this.buildFusedBodyDeriveBeforeAfterRunner(entry.handler, derive, before, after, entry.schema?.body, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+                    : laneName === "derive-before" && derive !== undefined && before !== undefined
+                        ? this.buildFusedDeriveBeforeRunner(entry.handler, derive, before, undefined, entry.schema?.query, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        : laneName === "derive-before-after" &&
+                            derive !== undefined &&
+                            before !== undefined &&
+                            after !== undefined
+                            ? this.buildFusedDeriveBeforeRunner(entry.handler, derive, before, after, entry.schema?.query, entry.bodyLimit ?? UNLIMITED_BODY_BYTES)
+                            : undefined;
         const fusedWeb = laneName === "body"
             ? this.buildFusedBodyWeb(fusedBody)
             : laneName === "query"
@@ -1231,6 +1708,10 @@ export class Server {
      * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).
      */
     fetch(req, platform) {
+        // Deno's `Request.url` is the target as sent; Bun, workerd and every `new Request()` parse it.
+        // Route what the parsed URL says, so `/users/../admin` is `/admin` on every runtime.
+        if (rawRequestTargets && hasDotSegment(req.url))
+            req = withResolvedTarget(req);
         // An edge deployment whose only ingress is this method declares its requests runtime-framed at
         // construction; everything else stays on the delivered-byte check (see `trustBodyFraming`).
         if (this.trustBodyFraming)
@@ -1266,13 +1747,14 @@ export class Server {
     }
     /** Web response path when Bun already matched the route. The lifecycle and response hooks remain
      * exactly the same as {@link fetchSource}; only portable URL scanning + trie lookup are skipped. */
-    fetchMatched(source, entry, params) {
-        if (this.capacityGate === undefined)
-            return this.fetchMatchedInner(source, entry, params);
-        return this.admitGated(requestOf(source), () => this.fetchMatchedInner(source, entry, params));
+    fetchMatched(source, entry, params, platform) {
+        if (this.capacityGate === undefined) {
+            return this.fetchMatchedInner(source, entry, params, platform);
+        }
+        return this.admitGated(requestOf(source), () => this.fetchMatchedInner(source, entry, params, platform));
     }
-    fetchMatchedInner(source, entry, params) {
-        const outcome = this.runMatched(source, undefined, entry, params, undefined, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, true);
+    fetchMatchedInner(source, entry, params, platform) {
+        const outcome = this.runMatched(source, platform, entry, params, undefined, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, true);
         if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
             return outcome;
         }
@@ -1338,19 +1820,26 @@ export class Server {
         }
         const parts = source.urlParts ?? urlPartsOf(source.url);
         const match = this.catalog.find(source.method, parts.pathname);
-        if (match.found)
+        if (match.found || !isRoutableMethod(source.method))
+            return undefined;
+        // The mount the ordinary path reaches first: every `mount()` runs before any `mountFetch()`,
+        // whatever their prefix lengths. A 404 fallthrough chain stays on the ordinary path.
+        const mount = this.firstMountUnder(parts.pathname, true) ?? this.firstMountUnder(parts.pathname, false);
+        if (mount === undefined || mount.fallbackOn404)
             return undefined;
+        const candidate = mount.handler[NODE_NATIVE_MOUNT];
+        return typeof candidate === "function"
+            ? {
+                handler: candidate,
+                path: mount.path,
+                stripPrefix: mount.stripPrefix,
+            }
+            : undefined;
+    }
+    firstMountUnder(pathname, beforeRoutes) {
         for (const mount of this.fetchMounts) {
-            if (!underMountPrefix(parts.pathname, mount.path))
-                continue;
-            const candidate = mount.handler[NODE_NATIVE_MOUNT];
-            return typeof candidate === "function"
-                ? {
-                    handler: candidate,
-                    path: mount.path,
-                    stripPrefix: mount.stripPrefix,
-                }
-                : undefined;
+            if (mount.beforeRoutes === beforeRoutes && underMountPrefix(pathname, mount.path))
+                return mount;
         }
         return undefined;
     }
@@ -1489,6 +1978,7 @@ export class Server {
         const context = {
             status: outcome.status,
             headers,
+            headersAreLowercase: !this.hasRawNodeResponseHook && lowercaseKeys,
             cookies: outcome.kind === "json" ? outcome.cookies : undefined,
             body: outcome.body,
         };
@@ -1570,76 +2060,210 @@ export class Server {
      * `data`). Runs the route's `upgrade(c)` guard in a real request context. Synchronous unless
      * `upgrade()` is async; a throw rejects with a flat 500 (no detail leaked).
      */
+    runWebSocketRequestHooks(req, platform) {
+        let current = req;
+        for (let i = 0; i < this.onRequestHooks.length; i++) {
+            const hook = this.onRequestHooks[i];
+            if (hook === undefined)
+                return current;
+            const outcome = hook(current, platform);
+            if (outcome instanceof Promise) {
+                return outcome.then((first) => this.continueWebSocketRequestHooks(first, i + 1, current, platform));
+            }
+            if (outcome instanceof Request) {
+                current = outcome;
+                continue;
+            }
+            if (outcome !== undefined)
+                return outcome;
+        }
+        return current;
+    }
+    async continueWebSocketRequestHooks(first, start, current, platform) {
+        let next = current;
+        let outcome = first;
+        for (let i = start;; i++) {
+            if (outcome instanceof Request)
+                next = outcome;
+            else if (outcome !== undefined)
+                return outcome;
+            if (i >= this.onRequestHooks.length)
+                return next;
+            const hook = this.onRequestHooks[i];
+            if (hook === undefined)
+                return next;
+            outcome = await hook(next, platform);
+        }
+    }
     resolveWebSocketUpgrade(req, platform) {
-        if (this.wsRouteCount === 0)
+        // Before any header is read: Deno only materializes a request's headers when asked, and that
+        // costs a plain request measurably.
+        if (this.wsRouteCount === 0 && !this.mountsTakeUpgrades())
             return WS_PASS;
         if (req.headers.get("upgrade")?.toLowerCase() !== "websocket")
             return WS_PASS;
-        const url = urlPartsOf(req.url);
-        const match = this.wsRouter.find("GET", url.pathname);
-        if (!match.found)
-            return WS_PASS; // upgrade header, no WS route here → normal routing decides
-        // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
-        // already did and made every plain dynamic route pay for unrelated static path bytes.
-        const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
-        if (params === null)
-            return { kind: "reject", response: jsonError(400, "malformed_path") };
-        const handler = match.payload.handler;
-        // Non-null: wsRouteCount > 0 ⇒ ws() ran ⇒ `.use(websocket())` installed the runtime + registry.
-        const pubsub = this.topics;
-        const attach = this.wsRuntime.attach;
-        // CSWSH guard, before any per-connection work or the user's upgrade(): reject a disallowed
-        // Origin with 403. Browsers don't CORS-protect WS handshakes but do send cookies, so this
-        // blocks cross-site authenticated sockets when the route opts in via `allowedOrigins`.
-        const origin = req.headers.get("origin");
-        if (handler.allowedOrigins !== undefined) {
-            const allowed = typeof handler.allowedOrigins === "function"
-                ? handler.allowedOrigins(origin)
-                : origin !== null && handler.allowedOrigins.includes(origin);
-            if (!allowed)
+        // A WebSocket handshake is a GET (RFC 6455 section 4.1). Any other method with an Upgrade header
+        // is an ordinary request: its HTTP route answers it, and normal routing refuses an unknown token.
+        if (req.method !== "GET")
+            return WS_PASS;
+        // The handshake routes the path `fetch` would: dot segments resolved (see `fetch`).
+        if (rawRequestTargets && hasDotSegment(req.url))
+            req = withResolvedTarget(req);
+        // The handshake's caller is the one `fetch` derives: hooks and `upgrade()` see the trusted IP.
+        platform = this.trustedPlatform(req, platform);
+        const timeoutMs = this.wsUpgradeTimeoutMs === 0
+            ? 0
+            : this.requestTimeoutMs > 0
+                ? Math.min(this.wsUpgradeTimeoutMs, this.requestTimeoutMs)
+                : this.wsUpgradeTimeoutMs;
+        const controller = timeoutMs > 0 ? new AbortController() : undefined;
+        const signal = controller?.signal ?? getNeverAbortSignal();
+        const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : undefined;
+        const timeoutResponse = jsonError(503, "request_timeout");
+        const onTimeout = () => ({
+            kind: "reject",
+            response: timeoutResponse,
+        });
+        const bounded = (work, onDone) => controller === undefined
+            ? work
+            : this.withTimeout(work, controller, onDone, Math.max(0, deadline - Date.now()));
+        const resolveMatched = (request) => {
+            const url = urlPartsOf(request.url);
+            const match = this.wsRouter.find("GET", url.pathname);
+            if (!match.found)
+                return WS_PASS; // upgrade header, no WS route here → normal routing decides
+            // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
+            // already did and made every plain dynamic route pay for unrelated static path bytes.
+            const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
+            if (params === null)
+                return { kind: "reject", response: jsonError(400, "malformed_path") };
+            const handler = match.payload.handler;
+            // Non-null: wsRouteCount > 0 ⇒ ws() ran ⇒ `.use(websocket())` installed the runtime + registry.
+            const pubsub = this.topics;
+            const attach = this.wsRuntime.attach;
+            // CSWSH guard, before any per-connection work or the user's upgrade(): reject a disallowed
+            // Origin with 403. Browsers don't CORS-protect WS handshakes but do send cookies, so this
+            // blocks cross-site authenticated sockets when the route opts in via `allowedOrigins`.
+            const origin = request.headers.get("origin");
+            if (handler.allowedOrigins !== undefined) {
+                const allowed = typeof handler.allowedOrigins === "function"
+                    ? handler.allowedOrigins(origin)
+                    : origin !== null && handler.allowedOrigins.includes(origin);
+                if (!allowed)
+                    return { kind: "reject", response: jsonError(403, "forbidden_origin") };
+            }
+            else if (origin !== null && !wsSameOrigin(origin, request)) {
+                // Secure default (no explicit `allowedOrigins`): reject a CROSS-ORIGIN browser handshake - the
+                // CSWSH case, since browsers send cookies on WS handshakes and don't apply CORS. Non-browser
+                // clients send no `Origin` and pass; same-origin browsers pass. Set `allowedOrigins` to permit
+                // specific cross-origin clients (or `() => true` for a genuinely public socket).
                 return { kind: "reject", response: jsonError(403, "forbidden_origin") };
-        }
-        else if (origin !== null && !wsSameOrigin(origin, req)) {
-            // Secure default (no explicit `allowedOrigins`): reject a CROSS-ORIGIN browser handshake - the
-            // CSWSH case, since browsers send cookies on WS handshakes and don't apply CORS. Non-browser
-            // clients send no `Origin` and pass; same-origin browsers pass. Set `allowedOrigins` to permit
-            // specific cross-origin clients (or `() => true` for a genuinely public socket).
-            return { kind: "reject", response: jsonError(403, "forbidden_origin") };
-        }
-        if (handler.upgrade === undefined) {
-            return {
-                kind: "upgrade",
-                handler,
-                data: undefined,
-                pubsub,
-                attach,
-                maxPayloadBytes: this.wsMaxPayloadBytes,
-            };
-        }
-        const upgradeSignal = getNeverAbortSignal();
-        const ctx = new RequestContext(req, params, url.search, upgradeSignal, createUnboundedRequestBudget(upgradeSignal), platform, this.maxBodyBytes, this.protoPoisoning);
-        const settle = (value) => value instanceof Response
-            ? { kind: "reject", response: value }
-            : {
-                kind: "upgrade",
-                handler,
-                data: value,
-                pubsub,
-                attach,
-                maxPayloadBytes: this.wsMaxPayloadBytes,
-            };
-        try {
-            const result = handler.upgrade(ctx);
-            return result instanceof Promise
-                ? result.then(settle, () => ({
+            }
+            if (handler.upgrade === undefined) {
+                return {
+                    kind: "upgrade",
+                    handler,
+                    data: undefined,
+                    pubsub,
+                    attach,
+                    maxPayloadBytes: this.wsMaxPayloadBytes,
+                };
+            }
+            const budget = controller === undefined
+                ? createUnboundedRequestBudget(signal)
+                : createRequestBudget({ deadline: deadline, signal });
+            const ctx = new RequestContext(request, params, url.search, signal, budget, platform, this.maxBodyBytes, this.protoPoisoning);
+            const settle = (value) => value instanceof Response
+                ? { kind: "reject", response: value }
+                : {
+                    kind: "upgrade",
+                    handler,
+                    data: value,
+                    pubsub,
+                    attach,
+                    maxPayloadBytes: this.wsMaxPayloadBytes,
+                };
+            try {
+                const result = handler.upgrade(ctx);
+                if (!(result instanceof Promise))
+                    return settle(result);
+                const pending = result.then(settle, () => ({
                     kind: "reject",
                     response: jsonError(500, "internal_error"),
-                }))
-                : settle(result);
+                }));
+                return bounded(pending, onTimeout);
+            }
+            catch {
+                return { kind: "reject", response: jsonError(500, "internal_error") };
+            }
+        };
+        const resolveMounted = (request) => {
+            // Native pub/sub was chosen because no mounted app took upgrades when `listen()` ran. One that
+            // gains a WebSocket route later stays out: its sockets would share this server's Bun topics.
+            if (this.nativePublish !== undefined)
+                return WS_PASS;
+            const pathname = urlPartsOf(request.url).pathname;
+            const dispatch = (start) => {
+                let selected;
+                let selectedIndex = start;
+                for (let i = start; i < this.fetchMounts.length; i++) {
+                    const candidate = this.fetchMounts[i];
+                    if (candidate.resolveWebSocketUpgrade !== undefined &&
+                        underMountPrefix(pathname, candidate.path)) {
+                        selected = candidate;
+                        selectedIndex = i;
+                        break;
+                    }
+                }
+                if (selected === undefined)
+                    return WS_PASS;
+                const childRequest = selected.stripPrefix
+                    ? stripMountPrefix(request, selected.path)
+                    : request;
+                let child;
+                try {
+                    child = selected.resolveWebSocketUpgrade(childRequest, platform);
+                }
+                catch {
+                    return { kind: "reject", response: jsonError(500, "internal_error") };
+                }
+                const settle = (outcome) => outcome.kind === "pass" ||
+                    (outcome.kind === "reject" && outcome.response.status === 404 && selected.fallbackOn404)
+                    ? dispatch(selectedIndex + 1)
+                    : outcome;
+                return child instanceof Promise ? child.then(settle) : settle(child);
+            };
+            return dispatch(0);
+        };
+        const resolveRoutes = (request) => {
+            const local = resolveMatched(request);
+            if (local instanceof Promise) {
+                return local.then((outcome) => outcome.kind === "pass" ? resolveMounted(request) : outcome);
+            }
+            return local.kind === "pass" ? resolveMounted(request) : local;
+        };
+        const resolveWithDeadline = (request) => {
+            const outcome = resolveRoutes(request);
+            return outcome instanceof Promise ? bounded(outcome, onTimeout) : outcome;
+        };
+        if (this.onRequestHooks.length === 0)
+            return resolveWithDeadline(req);
+        let hooked;
+        try {
+            hooked = this.runWebSocketRequestHooks(req, platform);
         }
         catch {
             return { kind: "reject", response: jsonError(500, "internal_error") };
         }
+        if (!(hooked instanceof Promise)) {
+            return hooked instanceof Response
+                ? { kind: "reject", response: hooked }
+                : resolveWithDeadline(hooked);
+        }
+        const pending = hooked.then((result) => result instanceof Response
+            ? { kind: "reject", response: result }
+            : resolveWithDeadline(result), () => ({ kind: "reject", response: jsonError(500, "internal_error") }));
+        return bounded(Promise.resolve(pending).then((result) => result), onTimeout);
     }
     /** Bun `fetch` when WS routes exist: try a WS upgrade first, else run the normal HTTP lifecycle.
      * `undefined` ⇒ Bun owns the upgraded socket; a `Response` ⇒ a normal reply or a rejected upgrade.
@@ -1650,11 +2274,13 @@ export class Server {
                 return this.fetch(req, bunPeerPlatform(server, req));
             if (o.kind === "reject")
                 return o.response;
-            return server.upgrade(req, { data: { handler: o.handler, data: o.data } })
+            return server.upgrade(req, {
+                data: { handler: o.handler, data: o.data, pubsub: o.pubsub },
+            })
                 ? undefined
                 : jsonError(426, "upgrade_required");
         };
-        const outcome = this.resolveWebSocketUpgrade(req);
+        const outcome = this.resolveWebSocketUpgrade(req, bunPeerPlatform(server, req));
         return outcome instanceof Promise ? outcome.then(handle) : handle(outcome);
     }
     /**
@@ -1670,6 +2296,12 @@ export class Server {
         const derived = resolveClientIp(platform?.clientIp, requestOf(source), this.clientIpTrust);
         return { ...platform, clientIp: derived };
     }
+    trustedPlatform(source, platform) {
+        return this.clientIpTrust === undefined ||
+            platform?.[NIFRA_PLATFORM_CLIENT_IP_DERIVED] === true
+            ? platform
+            : this.deriveClientIp(source, platform);
+    }
     dispatch(source, platform, finalize, wrapResponse, onTimeout, 
     // True only from the Web `fetch` path - unlocks each route's fused lane, whose output type IS
     // `Response` (`T = Response` there by construction; the node path always passes false).
@@ -1677,10 +2309,14 @@ export class Server {
         // Resolve the trust declaration into the platform's `clientIp` ONCE, here at the shared funnel, so
         // `c.clientIp` (and every hook/derive downstream) sees the derived caller. No config ⇒ the raw
         // socket peer the adapter supplied passes through untouched (a one-property no-op on the hot path).
-        const resolved = this.clientIpTrust === undefined ? platform : this.deriveClientIp(source, platform);
+        // A platform an enclosing nifra server already resolved (an in-process call from an SSR loader)
+        // keeps its `clientIp`: the synthesized request carries none of the visitor's forwarding headers.
+        const resolved = this.trustedPlatform(source, platform);
         // onRequest hooks may be async, so a hooked app takes the async path; with no hooks (the common
         // case) routing stays synchronous, letting a bare route resolve with no lifecycle promise at all.
-        if (this.onRequestHooks.length === 0) {
+        // A token no route can be registered under skips the hooks as well: it cannot match, so routing
+        // answers it 404 or 405 and no hook reads a method string it would misjudge.
+        if (this.onRequestHooks.length === 0 || !isRoutableMethod(source.method)) {
             return this.routeAndRun(source, resolved, finalize, wrapResponse, onTimeout, webFast);
         }
         if (!webFast && this.canUseNodeRequestHooks()) {
@@ -1736,11 +2372,14 @@ export class Server {
             this.responseSources.set(source, originalRequest);
         let current = source;
         for (let i = 0; i < hooks.length; i++) {
-            const outcome = hooks[i](requestOf(current), platform);
+            const seen = requestOf(current);
+            const outcome = hooks[i](seen, platform);
             if (outcome instanceof Promise) {
                 return outcome.then((early) => this.continueOnRequest(early, i + 1, originalRequest, current, platform, finalize, wrapResponse, onTimeout, webFast));
             }
             if (outcome instanceof Request) {
+                if (outcome !== seen)
+                    recordRequestReplacement(outcome, seen);
                 current = outcome;
                 if (outcome !== originalRequest)
                     this.responseRequests.set(originalRequest, outcome);
@@ -1755,10 +2394,13 @@ export class Server {
      * the remaining hooks (awaiting freely - we're already async here). */
     async continueOnRequest(first, nextIndex, originalRequest, sourceAtAwait, platform, finalize, wrapResponse, onTimeout, webFast) {
         let current = sourceAtAwait;
+        let seen = requestOf(sourceAtAwait);
         let early = first;
         let index = nextIndex;
         for (;;) {
             if (early instanceof Request) {
+                if (early !== seen)
+                    recordRequestReplacement(early, seen);
                 current = early;
                 if (early !== originalRequest)
                     this.responseRequests.set(originalRequest, early);
@@ -1768,7 +2410,8 @@ export class Server {
             }
             if (index >= this.onRequestHooks.length)
                 break;
-            const outcome = this.onRequestHooks[index](requestOf(current), platform);
+            seen = requestOf(current);
+            const outcome = this.onRequestHooks[index](seen, platform);
             early = outcome instanceof Promise ? await outcome : outcome;
             index++;
         }
@@ -1884,9 +2527,20 @@ export class Server {
                 search = searchStart === -1 ? "" : rawUrl.slice(searchStart, searchEnd);
             }
         }
+        // Explicit composed mounts run before the parent's route table. This is what lets an SSR shell
+        // mount an API at `/api` without its catch-all page route swallowing the request. Legacy
+        // `mountFetch()` stays behind typed routes and is checked in the existing branch below.
+        if (this.preRouteMountCount > 0) {
+            const mounted = this.fetchMount(pathname, source, platform, true);
+            if (mounted !== undefined) {
+                return mounted instanceof Promise
+                    ? mounted.then((response) => wrapResponse(response))
+                    : wrapResponse(mounted);
+            }
+        }
         const match = this.catalog.find(source.method, pathname);
         if (!match.found) {
-            const mounted = this.fetchMount(pathname, source, platform);
+            const mounted = this.fetchMount(pathname, source, platform, false);
             if (mounted !== undefined) {
                 return mounted instanceof Promise
                     ? mounted.then((response) => wrapResponse(response))
@@ -1898,7 +2552,10 @@ export class Server {
                 // and every other name in that record is lowercase (the Web lane normalizes either way).
                 plainError(405, "method_not_allowed", { allow: match.allowed.join(", ") }));
             }
-            return wrapResponse(plainError(404, "not_found"));
+            const lane = this.notFoundLane;
+            return lane === undefined
+                ? wrapResponse(plainError(404, "not_found"))
+                : lane(this, source, pathname, platform, wrapResponse, onTimeout);
         }
         // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
         // already did and made every plain dynamic route pay for unrelated static path bytes.
@@ -1908,14 +2565,46 @@ export class Server {
         }
         return this.runMatched(source, platform, match.payload, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
-    fetchMount(pathname, source, platform) {
-        for (const mount of this.fetchMounts) {
-            if (!underMountPrefix(pathname, mount.path))
+    fetchMount(pathname, source, platform, beforeRoutes) {
+        const request = requestOf(source);
+        let first = -1;
+        for (let i = 0; i < this.fetchMounts.length; i++) {
+            const mount = this.fetchMounts[i];
+            if (mount.beforeRoutes !== beforeRoutes || !underMountPrefix(pathname, mount.path))
                 continue;
-            const request = requestOf(source);
-            return mount.handler(mount.stripPrefix ? stripMountPrefix(request, mount.path) : request, platform);
+            first = i;
+            break;
         }
-        return undefined;
+        // A mounted handler is arbitrary code that may read the method loosely, so it is only handed a
+        // token a route could be registered under; anything else is left to the route table to refuse.
+        if (first === -1 || !isRoutableMethod(source.method))
+            return undefined;
+        // A request body is a one-shot stream. Only methods whose request semantics are replayable are
+        // eligible for 404 fallthrough; this intentionally refuses POST/PUT/PATCH even when the body is
+        // empty because an adapter may expose a delayed stream or a protocol-specific side effect.
+        const replayable = source.method === "GET" || source.method === "HEAD" || source.method === "OPTIONS";
+        const dispatch = (index, fallback) => {
+            let mount;
+            for (let i = index; i < this.fetchMounts.length; i++) {
+                const candidate = this.fetchMounts[i];
+                if (candidate.beforeRoutes === beforeRoutes && underMountPrefix(pathname, candidate.path)) {
+                    mount = candidate;
+                    index = i;
+                    break;
+                }
+            }
+            if (mount === undefined)
+                return fallback ?? jsonError(404, "not_found");
+            const childRequest = mount.stripPrefix ? stripMountPrefix(request, mount.path) : request;
+            const outcome = mount.handler(childRequest, platform);
+            if (!replayable || !mount.fallbackOn404)
+                return outcome;
+            if (outcome instanceof Promise) {
+                return outcome.then((response) => response.status === 404 ? dispatch(index + 1, response) : response);
+            }
+            return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome;
+        };
+        return dispatch(first);
     }
     /** 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) {
@@ -1928,8 +2617,10 @@ export class Server {
         // handler can reach `c.req`; that lane already enforces `entry.bodyLimit`. Installing the full
         // direct-reader cap on `c.req` here would allocate bound readers, closures, and a stream wrapper
         // for a body that is already consumed. Keep the lazy transport cap for raw-body routes, where a
-        // user read is the only framework-owned body boundary.
-        if (entry.bodyLimit !== undefined && entry.schema?.body === undefined) {
+        // user read is the only framework-owned body boundary, and for the auth-first lane, whose
+        // derive and beforeHandle hooks reach `c.req` before the body is read.
+        if (entry.bodyLimit !== undefined &&
+            (entry.schema?.body === undefined || entry.program.authBeforeValidation)) {
             const method = source.method;
             if (method !== "GET" && method !== "HEAD")
                 markTransportCap(source, entry.bodyLimit);
@@ -2176,7 +2867,7 @@ export class Server {
                 ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
                 : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes, this.protoPoisoning);
             const finish = (value) => runParsed(value, ctx, finalize, wrapResponse);
-            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, finish, wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse));
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, finish, wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema);
         };
     }
     /** Web adapter wrapper for the shared body runner. Node passes its native finalizer directly through
@@ -2548,14 +3239,294 @@ export class Server {
                 ctx.body = validation.value;
                 return runHandlerValidated();
             };
-            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, onParsed, (response) => this.wrapWebResponse(response), (err) => Promise.resolve(logError(err, ctx)));
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, onParsed, (response) => this.wrapWebResponse(response), (err) => Promise.resolve(logError(err, ctx)), bodySchema);
+        };
+    }
+    /**
+     * Generic (finalize/wrapResponse-parameterized) fused runner for the derive-before(-after) lane:
+     * the Node-direct counterpart of `buildFusedDeriveBefore` / `buildFusedDeriveBeforeAfter`.
+     *
+     * The Web fused builders above return a `Response`, so the Node dispatcher (`webFast === false`)
+     * cannot use them and a derive+before route falls back to the generic route program there - two
+     * staged loops, per-stage dispatch, and the async-continuation machinery - while Bun rides the
+     * single closure. That asymmetry is the realistic-route Node deficit against Fastify: this runner
+     * closes it by running validate → derive → before → handler → (after) in one frame and finalizing
+     * through the caller's own `finalize` (the Node outcome on the direct lane, `toResponse` on Web),
+     * so the same registration feeds both runtimes with no per-lane copy of the lifecycle to drift.
+     *
+     * Semantics mirror the generic program stage-for-stage for the shapes this lane admits (exactly
+     * one derive, one beforeHandle, zero-or-one afterHandle, no onError/around/decorations/contracts/
+     * recovery hooks - enforced by `selectRouteLanes`): thrown `Response`/`status(...)` are control
+     * flow through `wrapResponse`/`finalize`, anything else logs + 500s via the shared `bareError`
+     * lane (identical to `handleLifecycleError` with no `onError` hooks), and a terminal `finalize`
+     * throw (e.g. an unstringifiable handler return on the Node lane) is caught exactly as
+     * `finishLifecycleContract` catches it. Step functions close over registration state only and take
+     * the request state as arguments, so the hot path allocates no per-request closures.
+     */
+    buildFusedDeriveBeforeRunner(handler, derive, before, after, querySchema, maxBodyBytes) {
+        const logError = (err, ctx, finalize, wrapResponse) => this.bareError(err, ctx, finalize, wrapResponse);
+        const runFinish = (result, ctx, finalize, wrapResponse) => {
+            if (after === undefined) {
+                try {
+                    return finalize(result, responseSet(ctx), ctx);
+                }
+                catch (err) {
+                    return logError(err, ctx, finalize, wrapResponse);
+                }
+            }
+            let transformed;
+            try {
+                transformed = after(result, ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (transformed instanceof Promise) {
+                return transformed.then((value) => {
+                    try {
+                        return finalize(value, responseSet(ctx), ctx);
+                    }
+                    catch (err) {
+                        return logError(err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            try {
+                return finalize(transformed, responseSet(ctx), ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+        };
+        const finalizeEarly = (result, ctx, finalize, wrapResponse) => {
+            try {
+                return finalize(result, responseSet(ctx), ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+        };
+        const runHandler = (ctx, finalize, wrapResponse) => {
+            let result;
+            try {
+                result = handler(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (result instanceof Promise) {
+                return result.then((value) => runFinish(value, ctx, finalize, wrapResponse), (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            return runFinish(result, ctx, finalize, wrapResponse);
+        };
+        const runBefore = (ctx, finalize, wrapResponse) => {
+            let early;
+            try {
+                early = before(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (early instanceof Promise) {
+                return early.then((settled) => settled === undefined
+                    ? runHandler(ctx, finalize, wrapResponse)
+                    : finalizeEarly(settled, ctx, finalize, wrapResponse), (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (early === undefined)
+                return runHandler(ctx, finalize, wrapResponse);
+            return finalizeEarly(early, ctx, finalize, wrapResponse);
+        };
+        const runDerive = (ctx, finalize, wrapResponse) => {
+            let derived;
+            try {
+                derived = derive(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (derived instanceof Promise) {
+                return derived.then((settled) => {
+                    if (isResponseResult(settled) || settled instanceof Response) {
+                        return finalizeEarly(settled, ctx, finalize, wrapResponse);
+                    }
+                    Object.assign(ctx, settled);
+                    return runBefore(ctx, finalize, wrapResponse);
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (isResponseResult(derived) || derived instanceof Response) {
+                return finalizeEarly(derived, ctx, finalize, wrapResponse);
+            }
+            Object.assign(ctx, derived);
+            return runBefore(ctx, finalize, wrapResponse);
+        };
+        const runValidated = (validation, ctx, finalize, wrapResponse) => {
+            if (validation instanceof Promise) {
+                return validation.then((settled) => {
+                    if (settled.issues !== undefined)
+                        return wrapResponse(plainValidationError(settled.issues));
+                    ctx.query = settled.value;
+                    return runDerive(ctx, finalize, wrapResponse);
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (validation.issues !== undefined)
+                return wrapResponse(plainValidationError(validation.issues));
+            ctx.query = validation.value;
+            return runDerive(ctx, finalize, wrapResponse);
+        };
+        return (source, params, search, signal, budget, platform, nativeContext, finalize, wrapResponse) => {
+            const ctx = nativeContext
+                ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+                : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes, this.protoPoisoning);
+            if (querySchema === undefined)
+                return runDerive(ctx, finalize, wrapResponse);
+            let validation;
+            try {
+                validation = querySchema["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            return runValidated(validation, ctx, finalize, wrapResponse);
+        };
+    }
+    /**
+     * Generic fused runner for the body+derive-before(-after) lane: the Node-direct counterpart of
+     * `buildFusedBodyDeriveBeforeAfter`. Same contract as `buildFusedDeriveBeforeRunner` above - one
+     * frame running parse → validate → derive → before → handler → (after) through the caller's own
+     * `finalize` - with the body read ahead of validation, exactly as the generic program orders its
+     * body stage before the derive/before stages. `readBodyFramed` keeps the shared bounded-read,
+     * content-type, and prototype-poisoning contracts; the 415/400 renders take `wrapResponse`
+     * directly, which is what the generic lane's wrap-after-identity amounts to.
+     */
+    buildFusedBodyDeriveBeforeAfterRunner(handler, derive, before, after, bodySchema, maxBodyBytes) {
+        const logError = (err, ctx, finalize, wrapResponse) => this.bareError(err, ctx, finalize, wrapResponse);
+        const runFinish = (result, ctx, finalize, wrapResponse) => {
+            if (after === undefined) {
+                try {
+                    return finalize(result, responseSet(ctx), ctx);
+                }
+                catch (err) {
+                    return logError(err, ctx, finalize, wrapResponse);
+                }
+            }
+            let transformed;
+            try {
+                transformed = after(result, ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (transformed instanceof Promise) {
+                return transformed.then((value) => {
+                    try {
+                        return finalize(value, responseSet(ctx), ctx);
+                    }
+                    catch (err) {
+                        return logError(err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            try {
+                return finalize(transformed, responseSet(ctx), ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+        };
+        const finalizeEarly = (result, ctx, finalize, wrapResponse) => {
+            try {
+                return finalize(result, responseSet(ctx), ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+        };
+        const runHandler = (ctx, finalize, wrapResponse) => {
+            let result;
+            try {
+                result = handler(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (result instanceof Promise) {
+                return result.then((value) => runFinish(value, ctx, finalize, wrapResponse), (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            return runFinish(result, ctx, finalize, wrapResponse);
+        };
+        const runBefore = (ctx, finalize, wrapResponse) => {
+            let early;
+            try {
+                early = before(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (early instanceof Promise) {
+                return early.then((settled) => settled === undefined
+                    ? runHandler(ctx, finalize, wrapResponse)
+                    : finalizeEarly(settled, ctx, finalize, wrapResponse), (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (early === undefined)
+                return runHandler(ctx, finalize, wrapResponse);
+            return finalizeEarly(early, ctx, finalize, wrapResponse);
+        };
+        const runDerive = (ctx, finalize, wrapResponse) => {
+            let derived;
+            try {
+                derived = derive(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (derived instanceof Promise) {
+                return derived.then((settled) => {
+                    if (isResponseResult(settled) || settled instanceof Response) {
+                        return finalizeEarly(settled, ctx, finalize, wrapResponse);
+                    }
+                    Object.assign(ctx, settled);
+                    return runBefore(ctx, finalize, wrapResponse);
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (isResponseResult(derived) || derived instanceof Response) {
+                return finalizeEarly(derived, ctx, finalize, wrapResponse);
+            }
+            Object.assign(ctx, derived);
+            return runBefore(ctx, finalize, wrapResponse);
+        };
+        const onParsed = (parsed, ctx, finalize, wrapResponse) => {
+            let validation;
+            try {
+                validation = bodySchema["~standard"].validate(parsed);
+            }
+            catch (err) {
+                return logError(err, ctx, finalize, wrapResponse);
+            }
+            if (validation instanceof Promise) {
+                return validation.then((settled) => {
+                    if (settled.issues !== undefined)
+                        return wrapResponse(plainValidationError(settled.issues));
+                    ctx.body = settled.value;
+                    return runDerive(ctx, finalize, wrapResponse);
+                }, (err) => logError(err, ctx, finalize, wrapResponse));
+            }
+            if (validation.issues !== undefined)
+                return wrapResponse(plainValidationError(validation.issues));
+            ctx.body = validation.value;
+            return runDerive(ctx, finalize, wrapResponse);
+        };
+        return (source, params, search, signal, budget, platform, nativeContext, finalize, wrapResponse) => {
+            const ctx = nativeContext
+                ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
+                : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes, this.protoPoisoning);
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, (parsed) => onParsed(parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema);
         };
     }
     bareError(err, ctx, finalize, wrapResponse) {
         // The thrown-value contract lives in `bare-error-lane.ts`, one source of truth for both this
         // lane and the fused body runner. `responseSet` and the logger are injected because they reach
         // into class state; the closure is allocated only on the throw path, never on the hot lane.
-        return renderBareError(err, ctx, finalize, wrapResponse, responseSet, (e, c) => this.logRequestError(e, c), () => this.internalErrorResponse(wrapResponse));
+        return renderBareError(err, ctx, finalize, responseSet, (e, c) => this.logRequestError(e, c), () => this.internalErrorResponse(wrapResponse));
     }
     /**
      * Keep the ordinary thrown-error response independent from the caught value. Deliberate Response
@@ -2585,15 +3556,13 @@ export class Server {
     /** Bind a compiled validation stage to its stable schema and the existing recovery contract. */
     // @ts-expect-error TS6133 -- invoked structurally by the general route program
     validateProgramStage(entry, stage, source, ctx) {
-        const input = stage.kind === "headers"
-            ? headerObjectOf(source.headers)
-            : stage.kind === "params"
-                ? ctx.params
-                : stage.kind === "query"
-                    ? queryObjectOf(ctx[CONTEXT_SEARCH])
-                    : undefined;
         if (stage.kind === "body")
             return this.readProgramBody(entry, source, ctx);
+        const input = stage.kind === "headers"
+            ? headerObjectOf(source.headers)
+            : stage.kind === "query"
+                ? queryObjectOf(ctx[CONTEXT_SEARCH])
+                : ctx[stage.kind];
         const validation = stage.schema["~standard"].validate(input);
         return validation instanceof Promise
             ? validation.then((result) => this.applyLifecycleValidation(entry, result, ctx, stage.kind))
@@ -2633,7 +3602,7 @@ export class Server {
     }
     // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
     runBodyOnly(entry, source, ctx, finalize, wrapResponse) {
-        return readBodyFramed(source, entry.bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        return readBodyFramed(source, entry.bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse), entry.schema?.body);
     }
     /** Validate + run the handler for the bodyOnly path - shared by the inline fast path and the
      * streaming fallback. A method (not per-request closures) so the hot path allocates nothing
@@ -2881,7 +3850,7 @@ export class Server {
             const contract = entry.responseContract;
             if (contract === undefined)
                 return finalize(result, responseSet(ctx));
-            const checked = contract.runtime.check(contract.schema, result);
+            const checked = contract.runtime.check(contract.definition, result, ctx);
             if (checked instanceof Promise) {
                 return checked.then((outcome) => this.finishContractOutcome(ctx, finalize, wrapResponse, outcome), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
             }
@@ -2916,15 +3885,16 @@ export class Server {
      * loop, which may await, drops into {@link runErrorHooks}. */
     handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
         // A *thrown* Response is deliberate control flow, not an error - a guard throws a redirect/401,
-        // an action throws an error page. Return it as-is (Remix/SvelteKit semantics); don't run onError
-        // or log it as a 500. This is what makes `throw redirect(...)` / `requireSession(...)` work from
-        // any handler or loader.
+        // an action throws an error page. Send it as the same Response returned would be sent (Remix/
+        // SvelteKit semantics): as built, plus the cookies the request queued, so a session set or
+        // cleared before `throw redirect(...)` / `requireSession(...)` ships. Don't run onError or log
+        // it as a 500.
         if (err instanceof Response)
-            return wrapResponse(err);
+            return finalize(err, responseSet(ctx));
         // Same rule for a thrown `status(...)`, but through `finalize` rather than `wrapResponse`: the
         // value is still plain data, so the ordinary JSON lane renders it and no `Response` is built.
         if (isResponseResult(err))
-            return finalize(err, responseSet(ctx));
+            return this.finishLifecycleContract(entry, ctx, finalize, wrapResponse, err);
         if (entry.onError.length === 0) {
             // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
             // (redacting) logger. Body-read failures and around-hook failures land here too.
@@ -2963,20 +3933,14 @@ export class Server {
                 ? validation.then((result) => this.applyLifecycleValidation(entry, result, ctx, "body"))
                 : this.applyLifecycleValidation(entry, validation, ctx, "body");
         };
-        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, (response) => response, (error) => Promise.reject(error));
+        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, (response) => response, (error) => Promise.reject(error), bodySchema);
     }
     /** 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. */
     applyLifecycleValidation(entry, result, ctx, kind) {
         const assign = (value) => {
-            if (kind === "body")
-                ctx.body = value;
-            else if (kind === "query")
-                ctx.query = value;
-            else if (kind === "headers")
-                ctx.headers = value;
-            else
-                ctx.params = value;
+            ;
+            ctx[kind] = value;
         };
         if (result.issues === undefined) {
             assign(result.value);
@@ -2996,14 +3960,7 @@ export class Server {
             return plainValidationError(issues);
         if (recovery instanceof Response)
             return recovery;
-        const schema = kind === "body"
-            ? entry.schema?.body
-            : kind === "query"
-                ? entry.schema?.query
-                : kind === "params"
-                    ? entry.schema?.params
-                    : entry.schema?.headers;
-        const retried = schema["~standard"].validate(recovery);
+        const retried = entry.schema[kind]["~standard"].validate(recovery);
         if (retried instanceof Promise) {
             return retried.then((settled) => {
                 if (settled.issues !== undefined)
@@ -3019,7 +3976,7 @@ export class Server {
     }
     /** Adapt one route's compiled execution plan to Bun's already-matched request shape. Route
      * semantics remain in the plan; this closure only supplies native params and deadline fallback. */
-    compileBunNativeHandler(entry, paramNames, fused, signal, budget) {
+    compileBunNativeHandler(entry, paramNames, fused, signal, budget, peer, fallback) {
         // This callback is reached only from Bun's compiled native route table. Bun has already parsed
         // the HTTP framing, so the JSON lane may retain its native fused `json()` parse without weakening
         // the portable/adapted source contract (those sources are never marked).
@@ -3027,7 +3984,9 @@ export class Server {
         // The fused native lane bypasses `runMatched`, so the route's transport byte cap must be
         // marked here too - otherwise a Bun `listen()` fused route would leave direct `c.req` body
         // reads uncapped. The non-fused branches go through `fetchMatched` -> `runMatched`, which marks.
-        const bodyLimit = entry.schema?.body === undefined ? entry.bodyLimit : undefined;
+        const bodyLimit = entry.schema?.body === undefined || entry.program.authBeforeValidation
+            ? entry.bodyLimit
+            : undefined;
         const inner = fused;
         const capped = inner === undefined || bodyLimit === undefined
             ? inner
@@ -3037,73 +3996,90 @@ export class Server {
                     markTransportCap(source, bodyLimit);
                 return inner(source, params, search, fusedSignal, fusedBudget, platform, nativeContext);
             };
+        const nativeResponseHooks = this.onResponseHooks.length > 0 && this.bunNativeResponseHeadersOnly;
+        const finishNative = (request, response) => {
+            if (!nativeResponseHooks)
+                return response;
+            return this.applyOnResponseAndFinalize(response, request);
+        };
+        const runNative = (request, params) => {
+            const outcome = capped(request, params, undefined, signal, budget, peer, true);
+            return outcome instanceof Promise
+                ? outcome.then((response) => finishNative(request, response))
+                : finishNative(request, outcome);
+        };
         if (paramNames.length === 0) {
             if (capped === undefined) {
                 return (request) => {
                     markFramed(request);
-                    return this.fetchMatched(request, entry, EMPTY_PARAMS);
+                    return this.fetchMatched(request, entry, EMPTY_PARAMS, peer);
                 };
             }
             if (this.acceptInboundDeadlines) {
                 return (request) => {
                     markFramed(request);
                     return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                        ? this.fetchMatched(request, entry, EMPTY_PARAMS)
-                        : capped(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+                        ? this.fetchMatched(request, entry, EMPTY_PARAMS, peer)
+                        : capped(request, EMPTY_PARAMS, undefined, signal, budget, peer, true);
                 };
             }
             return (request) => {
                 markFramed(request);
-                return capped(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+                return runNative(request, EMPTY_PARAMS);
             };
         }
         const malformed = paramNames.length === 1
-            ? (params) => params[paramNames[0]]?.includes("\uFFFD") === true
-            : hasReplacementParam;
+            ? (params) => unroutedParam(params[paramNames[0]])
+            : hasUnroutedParam;
         if (capped === undefined) {
-            return (request) => {
+            return (request, server) => {
                 markFramed(request);
                 const params = request.params ?? EMPTY_PARAMS;
                 if (malformed(params))
-                    return this.fetchSource(request);
-                return this.fetchMatched(request, entry, params);
+                    return fallback(request, server);
+                return this.fetchMatched(request, entry, params, peer);
             };
         }
         if (this.acceptInboundDeadlines) {
-            return (request) => {
+            return (request, server) => {
                 markFramed(request);
                 const params = request.params ?? EMPTY_PARAMS;
                 if (malformed(params))
-                    return this.fetchSource(request);
+                    return fallback(request, server);
                 return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                    ? this.fetchMatched(request, entry, params)
-                    : capped(request, params, undefined, signal, budget, undefined, true);
+                    ? this.fetchMatched(request, entry, params, peer)
+                    : capped(request, params, undefined, signal, budget, peer, true);
             };
         }
-        return (request) => {
+        return (request, server) => {
             markFramed(request);
             const params = request.params ?? EMPTY_PARAMS;
             if (malformed(params))
-                return this.fetchSource(request);
-            return capped(request, params, undefined, signal, budget, undefined, true);
+                return fallback(request, server);
+            return runNative(request, params);
         };
     }
     /** Compile portable route registrations into Bun's native route table. Apps with request-rewrite
      * hooks or WebSockets retain the single portable dispatcher because those features must run before
-     * route selection/upgrade. Named wildcards also stay on the fallback until Bun exposes their raw
-     * capture semantics; static and `:param` routes take the native lane. */
-    buildBunNativeRoutes() {
+     * route selection/upgrade.
+     *
+     * Bun and the portable router agree on which of two static-and-`:param` paths wins a request, so
+     * the table is kept to those paths. Where Bun would otherwise pass a request on to a less specific
+     * path, the more specific one carries `fallback`, the portable dispatcher, under that method.
+     * `peer` is the platform every request served from the table shares. */
+    buildBunNativeRoutes(fallback, peer) {
         // A `clientIp` trust declaration must run the resolver in `dispatch`, which the fused native lane
         // bypasses - so an app that declares trust routes through the fetch lane (where `c.clientIp`
         // resolves) instead of Bun's native table. The allocation-free default keeps native fusion.
-        if (this.onRequestHooks.length > 0 ||
+        if ((this.onRequestHooks.length > 0 && !this.bunNativeRequestHooksSafe) ||
             this.wsRouteCount > 0 ||
+            this.preRouteMountCount > 0 ||
             this.clientIpTrust !== undefined) {
             return undefined;
         }
         const routes = Object.create(null);
         const mayUseFusedNative = this.requestTimeoutMs === 0 &&
-            this.onResponseHooks.length === 0 &&
+            (this.onResponseHooks.length === 0 || this.bunNativeResponseHeadersOnly) &&
             this.onResponseFinalizedHooks.length === 0 &&
             // The capacity gate must wrap every request; the fused lane bypasses fetchMatched, so enabling
             // admission drops fusion (native matching stays) and routes through the gated matched lane.
@@ -3111,18 +4087,65 @@ export class Server {
         const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined;
         const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined;
         let count = 0;
-        for (const { method, path, pattern, entry } of this.catalog.entries()) {
-            if (pattern.segments.some((segment) => segment.kind === "wildcard"))
+        const all = this.catalog.entries();
+        // A path with a wildcard or a part-literal segment cannot go in the table: Bun reads `/:name.json`
+        // as one parameter named `name.json`. These are filed under each run of static segments they
+        // start with, which is where a table path they could outrank looks for them.
+        const under = new Map();
+        const lead = all.map((route) => {
+            const segments = route.pattern.segments;
+            const plain = segments.every((segment) => segment.kind === "static" || segment.kind === "param");
+            let prefix = "";
+            for (const segment of segments) {
+                if (!plain) {
+                    let bucket = under.get(prefix);
+                    if (bucket === undefined) {
+                        bucket = [];
+                        under.set(prefix, bucket);
+                    }
+                    bucket.push(route);
+                }
+                if (segment.kind !== "static")
+                    break;
+                prefix += `/${segment.value}`;
+            }
+            return plain ? prefix : undefined;
+        });
+        // A preflight hook is intentionally handled by the fallback fetch path. Keeping OPTIONS out
+        // of the native lane means Bun dispatches it through CORS's onRequest hook even when the
+        // same path has native GET/POST handlers.
+        const preflightOnFallback = this.onRequestHooks.length > 0 && this.bunNativeRequestHooksSafe;
+        // Where Bun could pass a request down: the methods served natively on a path with a parameter,
+        // as segment count + method. Two table paths match one request only at the same segment count.
+        const below = new Set();
+        const tableAt = (path) => {
+            routes[path] ??= Object.create(null);
+            return routes[path];
+        };
+        for (let i = 0; i < all.length; i++) {
+            const { method, path, pattern, entry } = all[i];
+            const run = lead[i];
+            // The route is served from the table unless its path cannot be there, Bun's table has no slot
+            // for its method, or a path outside the table outranks it: Bun would hand this route a request
+            // the portable router gives to that one. An idempotent route stays off it too: its lanes run on
+            // a buffered copy of the request, and Bun names the peer only of the request it delivered, so
+            // the platform the table shares could not answer `c.clientIp` there.
+            if (run === undefined ||
+                entry.idempotent !== undefined ||
+                !METHODS.includes(method) ||
+                (preflightOnFallback && method === "OPTIONS") ||
+                under.get(run)?.some((other) => outranks(other.pattern.segments, pattern.segments))) {
                 continue;
-            let methods = routes[path];
-            if (methods === undefined) {
-                methods = Object.create(null);
-                routes[path] = methods;
             }
             const paramNames = pattern.paramNames;
             const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined;
-            methods[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget);
+            tableAt(path)[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget, peer, fallback);
             count += 1;
+            if (paramNames.length > 0) {
+                below.add(pattern.segments.length + method);
+                if (method === "GET")
+                    below.add(`${pattern.segments.length}HEAD`);
+            }
         }
         if (count === 0)
             return undefined;
@@ -3135,6 +4158,19 @@ export class Server {
             if (methods.GET !== undefined)
                 methods.HEAD ??= methods.GET;
         }
+        // Bun picks among the paths its table holds for the request's method, so a path with no entry
+        // for the method lets the request through to a less specific one. The portable router stops at
+        // the most specific path and answers 405. Every path the table could hold therefore gets the
+        // portable dispatcher under each method a less specific path might serve.
+        for (let i = 0; i < all.length; i++) {
+            if (lead[i] === undefined)
+                continue;
+            const { path, pattern } = all[i];
+            for (const method of METHODS) {
+                if (below.has(pattern.segments.length + method))
+                    tableAt(path)[method] ??= fallback;
+            }
+        }
         return routes;
     }
     /**
@@ -3158,6 +4194,10 @@ export class Server {
      * connection cut mid-flight regardless of `requestTimeoutMs`. Apps with such endpoints must raise
      * this above their slowest expected response, which is why it is a first-class option and not a
      * reason to drop down to `Bun.serve`. `0` disables the timeout entirely; max 255.
+     *
+     * `tls` serves HTTPS directly: `app.listen(443, { tls: { cert, key } })` with PEM text or bytes.
+     * Requests then arrive with `https:` URLs. Behind a proxy or a platform that terminates TLS, leave
+     * it unset.
      */
     listen(port, options) {
         if (typeof Bun === "undefined") {
@@ -3182,31 +4222,57 @@ export class Server {
         // because wsRouteCount > 0 means ws() ran, and ws() requires the runtime at registration.
         // Native pub/sub when the app has WS routes and none validate outbound frames: `ws.subscribe` and
         // `app.publish` go through Bun's own (uWebSockets) broadcast instead of the JS registry loop.
-        const nativePubsub = this.wsRouteCount > 0 && !this.wsHasValidatedSend;
-        const wsHandlers = this.wsRouteCount === 0
-            ? undefined
-            : this.wsRuntime.bunHandlers(this.topics, nativePubsub);
-        const reusePort = options?.reusePort === true;
-        // Spread rather than pass `hostname: undefined` - Bun treats an explicit undefined as a value
-        // on some option paths, and omitting is what selects its 0.0.0.0 default.
-        const bind = options?.hostname === undefined ? {} : { hostname: options.hostname };
-        // Same reasoning as `bind`: omit rather than pass undefined, so Bun's own default applies.
-        const idle = options?.idleTimeoutSec === undefined ? {} : { idleTimeout: options.idleTimeoutSec };
-        const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes() : undefined;
+        // A mounted app counts only while it has a WebSocket route (see `[GET_WS_RUNTIME]`), so composing
+        // one without any needs no runtime here.
+        const wsRuntime = this[GET_WS_RUNTIME]();
+        if (wsRuntime === null) {
+            throw new FrameworkError("INVALID_WS_RUNTIME", "a Bun server with mounted WebSocket routes needs the websocket() runtime installed on the parent or child app");
+        }
+        // Native pub/sub is safe only when every upgrade belongs to this app. A mounted child that takes
+        // upgrades owns a different TopicRegistry, so force the per-connection JS dispatcher and carry
+        // that registry in the upgrade outcome instead of accidentally broadcasting child sockets through
+        // the parent.
+        const nativePubsub = this.wsRouteCount > 0 && !this.mountsTakeUpgrades() && !this.wsHasValidatedSend;
+        const wsHandlers = wsRuntime?.bunHandlers(this.topics ?? wsRuntime.createTopics(), nativePubsub);
+        // Spread rather than pass `hostname: undefined` (or an undefined idle timeout or TLS) - Bun treats
+        // an explicit undefined as a value on some option paths, and omitting is what selects its own
+        // defaults, 0.0.0.0 among them.
+        const listening = {
+            port,
+            reusePort: options?.reusePort === true,
+            ...(options?.hostname === undefined ? {} : { hostname: options.hostname }),
+            ...(options?.idleTimeoutSec === undefined ? {} : { idleTimeout: options.idleTimeoutSec }),
+            ...(options?.tls === undefined ? {} : { tls: options.tls }),
+            // A hook that throws rejects `fetch`; Bun's own answer to that is a development page carrying
+            // the message, stack and source whenever NODE_ENV is not "production".
+            error: (err) => {
+                emitRequestErrorLog(this.logger, this.errorLogDetail, err, undefined);
+                return jsonError(500, "internal_error");
+            },
+        };
+        const fallback = (req, server) => {
+            // Bun has already framed and bounded this request body in its HTTP parser. Mark the
+            // source before the portable fallback runs so body schemas use Bun's native `json()`
+            // reader instead of the defensive arrayBuffer/decode path reserved for caller-built
+            // Requests. Native route handlers mark themselves in compileBunNativeHandler; this
+            // covers every request the native lane does not serve.
+            markTrustedBodyFraming(req);
+            return this.fetch(req, bunPeerPlatform(server, req));
+        };
+        // Bun names the socket peer of a request when its server is asked. A request served from the
+        // native table carries this one platform, which asks only when a handler reads `c.clientIp`.
+        const peer = {
+            [PLATFORM_PEER]: (request) => running.requestIP(request)?.address,
+        };
+        const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes(fallback, peer) : undefined;
         const running = (wsHandlers === undefined
             ? Bun.serve({
-                port,
-                reusePort,
-                ...bind,
-                ...idle,
+                ...listening,
                 ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
-                fetch: (req, server) => this.fetch(req, bunPeerPlatform(server, req)),
+                fetch: fallback,
             })
             : Bun.serve({
-                port,
-                reusePort,
-                ...bind,
-                ...idle,
+                ...listening,
                 fetch: (req, server) => this.bunFetchWithWebSocket(req, server),
                 // Bun's `ServerWebSocket<BunWsData>` is runtime-compatible with the handlers' structural
                 // `BunSocket` view (kept local so `Bun.*` types never leak into the published .d.ts); the
@@ -3222,7 +4288,9 @@ export class Server {
             }));
         this.bunServer = running;
         // Bind `app.publish` to Bun's native broadcast now that the server handle exists. Guarded on the
-        // method's presence so a runtime whose handle lacks it simply keeps the registry path.
+        // method's presence so a runtime whose handle lacks it simply keeps the registry path. Cleared
+        // first: a mounted app may have gained a WebSocket route since an earlier `listen()`.
+        this.nativePublish = undefined;
         if (nativePubsub && typeof running.publish === "function") {
             const native = running.publish.bind(running);
             this.nativePublish = (topic, data) => {