@nifrajs/core 1.12.0 → 2.0.0

package/dist/server/server.js

@@ -1,128 +1,103 @@
 import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA_DEADLINE_HEADER, } from "../budget.js";
 import { FrameworkError, RouteConfigError } from "../errors.js";
-import { canonicalizeIdempotencyBody, computeIdempotencyFingerprint, DEFAULT_IDEMPOTENCY_HEADER, DEFAULT_IDEMPOTENCY_TTL_MS, IdempotencyResponseTooLargeError, MemoryIdempotencyStore, responseFromStored, serializeResponse, validIdempotencyKey, validIdempotencyNamespace, } from "../idempotency.js";
 import { CAPABILITY_GUARD, createCapabilityGuard, normalizeRouteCapabilities, } from "../internal/capability-runtime.js";
-import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } from "../internal/route-assurance.js";
-import { attachEffectLedger, createRequestLedger, DEFAULT_MAX_ENTRIES, } from "../ledger.js";
+import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, validEvidenceId, } from "../internal/route-assurance.js";
+import { compileRoutePattern, decodeRouteParams, } from "../router/pattern.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
-import { drainCapped, parseContentLength, readBoundedBytes } from "./body.js";
-import { parseCookies, serializeCookie } from "./cookies.js";
+import { parseContentLength } from "./body.js";
+import { resolveClientIp } from "./client-ip.js";
+import { jsonError, pathnameOf, urlPartsOf } from "./http.js";
+import { isUrlEncodedForm, queryObjectOf, readBoundedForm, searchOf, } from "./query.js";
+import { RequestContext, readBoundedJsonSource } from "./request-context.js";
+import { fusedRespond, fusedRespondNoSet, toResponse } from "./respond.js";
+import { CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, requestOf, } from "./runtime-core.js";
+import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_SSE, INSTALL_WS, } from "./install.js";
 import { jsonLogger } from "./logger.js";
-import { sse, typedSSEStream } from "./sse.js";
-import { getWsRuntime } from "./ws-hook.js";
-/** The concrete `Request` for a source — itself when a real `Request` was passed (the Web path), or the
- * lazily-built one (the Node adapter). A real `Request` IS a `RequestSource`, so no wrapper is allocated
- * on the Web hot path. */
-function requestOf(source) {
-    return source.request ?? source;
-}
-function headerOf(source, name) {
-    return source.header?.(name) ?? source.headers.get(name);
-}
-const RESPONSE_RESULT = Symbol.for("nifra.response.result");
-const CONTEXT_SET = Symbol("nifra.context.set");
-const CONTEXT_SEARCH = Symbol("nifra.context.search");
 const functionToString = Function.prototype.toString;
 const CONTEXTLESS_ARROW = /^(?:async\s*)?\(\s*\)\s*(?::[\s\S]*?)?=>/;
-function isResponseResult(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value[RESPONSE_RESULT] === true &&
-        typeof value.toResponse === "function");
+/**
+ * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
+ * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
+ * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
+ * reflection unchanged.
+ */
+class RouteCatalog {
+    matcher = new Router();
+    records = [];
+    /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
+    descriptors = [];
+    assurancePresent = false;
+    add(route) {
+        this.matcher.add(route.method, route.pattern, route.entry);
+        this.records.push(route);
+        this.descriptors.push(route.descriptor);
+        if (route.assurance.length > 0)
+            this.assurancePresent = true;
+    }
+    addBatch(routes) {
+        if (routes.length === 0)
+            return;
+        const nextRecords = this.records.concat(routes);
+        const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor));
+        const nextAssurancePresent = this.assurancePresent || routes.some((route) => route.assurance.length > 0);
+        const staged = new Router();
+        for (const route of this.records)
+            staged.add(route.method, route.pattern, route.entry);
+        for (const route of routes)
+            staged.add(route.method, route.pattern, route.entry);
+        this.matcher = staged;
+        this.records = nextRecords;
+        this.descriptors = nextDescriptors;
+        this.assurancePresent = nextAssurancePresent;
+    }
+    find(method, path) {
+        return this.matcher.find(method, path);
+    }
+    entries() {
+        return this.records;
+    }
+    routeDescriptors() {
+        return this.descriptors;
+    }
+    lastDescriptor() {
+        return this.records[this.records.length - 1]?.descriptor;
+    }
+    hasAssurance() {
+        return this.assurancePresent;
+    }
+}
+/** The socket peer Bun observed, as a `Platform` for the request lifecycle (`undefined` if unknown).
+ * Typed structurally on `requestIP` alone so any Bun `Server` (WS or not) satisfies it. */
+function bunPeerPlatform(server, req) {
+    const address = server.requestIP(req)?.address;
+    return address === undefined ? undefined : { clientIp: address };
 }
-/** Off-edge `waitUntil`: run the background work fire-and-forget, never leaking an unhandled
- * rejection. Edge runtimes pass their own (Workers `ctx.waitUntil`) via the platform arg. */
-const fallbackWaitUntil = (promise) => {
-    void promise.catch(() => { });
-};
 const WS_PASS = { kind: "pass" };
 /** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
-function requireWsRuntime() {
-    const runtime = getWsRuntime();
+function requireWsRuntime(runtime) {
     if (runtime === undefined) {
-        throw new FrameworkError("WS_RUNTIME_MISSING", 'app.ws() needs the WebSocket runtime, which ships as a subpath so no-WebSocket apps stay lean. Add `import "@nifrajs/core/ws"` at your server entry.');
+        throw new FrameworkError("WS_RUNTIME_MISSING", "app.ws() needs the WebSocket runtime, which ships as an opt-in plugin so no-WebSocket apps stay lean. Add `.use(websocket())` from `@nifrajs/core/ws` before declaring WS routes.");
     }
     return runtime;
 }
-/**
- * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
- * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
- * other without double-registering hooks.
- *
- * ```ts
- * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
- * app.use(requestId)   // downstream handlers see c.requestId
- * ```
- *
- * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
- * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
- * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
- * and your whole typed client silently collapses to `any` — no type error, no runtime error.
- */
-export function definePlugin(name, apply) {
-    return Object.assign(apply, { pluginName: name });
+function requireSseRuntime(runtime) {
+    if (runtime === undefined) {
+        throw new FrameworkError("SSE_RUNTIME_MISSING", "app.sse() needs the streaming runtime, which ships as a subpath so non-SSE apps stay lean. Add `.use(streaming())` (from `@nifrajs/core/sse`) at your server setup.");
+    }
+    return runtime;
 }
-/**
- * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
- * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
- * add context types — e.g. one mounting an auth handler. It threads the caller's *concrete* server type
- * through `use`, so routes declared after `app.use(plugin)` keep their types.
- *
- * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
- * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
- * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
- *
- * ```ts
- * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
- * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
- * ```
- */
-export function defineIdentityPlugin(name, apply) {
-    return Object.assign(apply, { pluginName: name });
+function requireMcpRuntime(runtime) {
+    if (runtime === undefined) {
+        throw new FrameworkError("MCP_RUNTIME_MISSING", "MCP declarations ship as an opt-in runtime so ordinary HTTP apps stay lean. Add `.use(mcp())` (from `@nifrajs/core/mcp`) at your server setup.");
+    }
+    return runtime;
 }
-/**
- * Alias of {@link defineIdentityPlugin} with a name that says what it's FOR: a plugin that **mounts
- * routes/hooks but adds no context type** (an auth router, an audit logger). Use this — not
- * {@link definePlugin} — for any such plugin, or the typed client silently collapses to `any`. The
- * "identity" in {@link defineIdentityPlugin} refers to the type-identity it preserves; `defineRouterPlugin`
- * is the same thing under a clearer name.
- *
- * Mount routes as a **side effect**, then return the app unchanged (registering via `.get`/`.post` would
- * change the type away from the identity `S`; the mounted routes run but aren't in the caller's typed
- * registry — that's the trade that keeps everything else typed):
- *
- * ```ts
- * export const scim = defineRouterPlugin("scim", (app) => {
- *   app.get("/scim/v2/Users", listUsers) // side effect: mounted at runtime
- *   return app                           // return S unchanged → routes added after .use(scim) stay typed
- * })
- * const api = server().get("/a", h).use(scim).get("/b", h) // /a AND /b stay typed
- * ```
- */
-export const defineRouterPlugin = defineIdentityPlugin;
+// Plugin definers + their types now live in `./plugin.ts`; re-exported here so `.use()` callers and
+// existing importers keep resolving them from the server module.
+export { defineIdentityPlugin, definePlugin, defineRouterPlugin, } from "./plugin.js";
 const DEFAULT_MAX_BODY_BYTES = 1_000_000;
 const DEFAULT_DRAIN_MS = 10_000;
 const DRAIN_POLL_MS = 10;
-const TEXT_DECODER = new TextDecoder();
-/**
- * Shared never-aborting signal for `ctx.signal` when no timeout is armed — created lazily and
- * cached. NOT a module-scope `new AbortController()`: edge runtimes (Cloudflare workerd) forbid
- * constructing one in global scope; the first request builds it inside the handler, then it's
- * reused at zero per-request cost.
- */
-let neverAbortSignal;
-let unboundedRequestBudget;
-const getNeverAbortSignal = () => {
-    neverAbortSignal ??= new AbortController().signal;
-    return neverAbortSignal;
-};
-const getUnboundedRequestBudget = () => {
-    unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal());
-    return unboundedRequestBudget;
-};
-function jsonError(status, error, headers) {
-    return Response.json({ ok: false, error }, headers !== undefined ? { status, headers } : { status });
-}
 /** Same-origin check for a WebSocket handshake (CSWSH default): the `Origin`'s host[:port] must equal the
  * request's own host (from `req.url`, which the runtime builds from the `Host` header). Scheme differs
  * (ws↔http), so compare host only. An unparseable Origin is treated as NOT same-origin (rejected). */
@@ -141,156 +116,12 @@ function validationError(issues) {
     });
     return Response.json({ ok: false, error: "validation", issues: serialized }, { status: 422 });
 }
-// Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
-// `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
-// the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
-// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
-export function urlPartsOf(url) {
-    const schemeEnd = url.indexOf("://");
-    const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3);
-    if (start === -1)
-        return { pathname: "/", search: "" };
-    let pathEnd = url.length;
-    let searchStart = -1;
-    let searchEnd = url.length;
-    for (let i = start; i < url.length; i++) {
-        const c = url.charCodeAt(i);
-        if (c === 63 /* ? */ && searchStart === -1) {
-            pathEnd = i;
-            searchStart = i;
-        }
-        else if (c === 35 /* # */) {
-            if (searchStart === -1)
-                pathEnd = i;
-            searchEnd = i;
-            break;
-        }
-    }
-    return {
-        pathname: url.slice(start, pathEnd),
-        search: searchStart === -1 ? "" : url.slice(searchStart, searchEnd),
-    };
-}
-// Extract the pathname WITHOUT a full WHATWG `new URL(req.url)` parse. Kept as a public-ish helper
-// for tests and callers that only need the path; the request hot path uses `urlPartsOf()` once.
-export function pathnameOf(url) {
-    return urlPartsOf(url).pathname;
-}
-// The query string ("?a=1", or "" when absent) — for lazily building `c.query` only when read.
-// The fragment (after the first `#`) bounds the search: a `?` that appears only inside the fragment
-// is NOT a query (matches WHATWG). Fragments never reach the server in `req.url`, so this is purely
-// for provable equivalence with `new URL(req.url).search`.
-export function searchOf(url) {
-    return urlPartsOf(url).search;
-}
-/** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
- * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key — the
- * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
- * case (direct assignment on a null-proto object creates an own property). */
-function setQueryValue(out, key, value) {
-    const existing = out[key];
-    if (existing === undefined) {
-        out[key] = value;
-    }
-    else if (typeof existing === "string") {
-        out[key] = [existing, value];
-    }
-    else {
-        existing.push(value);
-    }
-}
-function queryObjectFallback(search) {
-    // Manual iteration instead of Object.fromEntries: repeated keys must promote to arrays
-    // (fromEntries is last-wins), and __proto__ needs the same own-property guard.
-    const out = Object.create(null);
-    for (const [key, value] of new URLSearchParams(search)) {
-        setQueryValue(out, key, value);
-    }
-    return out;
-}
-/**
- * Build the plain object passed to query schemas. Plain ASCII-ish queries avoid
- * `URLSearchParams` + iterator allocations; encoded queries fall back to the Web API so `+`,
- * percent-decoding, malformed escapes, and empty-key behavior stay exact. Repeated keys promote
- * to `string[]` on BOTH paths (see {@link setQueryValue}).
- */
-// Shared empty result for no-query requests: frozen + null-prototype (same shape contract as the
-// populated path), allocated once instead of per request.
-const EMPTY_QUERY = Object.freeze(Object.create(null));
-export function queryObjectOf(search) {
-    const start = search.charCodeAt(0) === 63 /* ? */ ? 1 : 0;
-    if (start >= search.length)
-        return EMPTY_QUERY;
-    for (let i = start; i < search.length; i++) {
-        const c = search.charCodeAt(i);
-        if (c === 37 /* % */ || c === 43 /* + */)
-            return queryObjectFallback(search);
-    }
-    const out = Object.create(null);
-    let pos = start;
-    while (pos <= search.length) {
-        const amp = search.indexOf("&", pos);
-        const end = amp === -1 ? search.length : amp;
-        if (end > pos) {
-            const eq = search.indexOf("=", pos);
-            const split = eq !== -1 && eq < end ? eq : end;
-            const key = search.slice(pos, split);
-            const value = split === end ? "" : search.slice(split + 1, end);
-            setQueryValue(out, key, value);
-        }
-        if (amp === -1)
-            break;
-        pos = amp + 1;
-    }
-    return out;
-}
-/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
-function isUrlEncodedForm(contentType) {
-    return (contentType === "application/x-www-form-urlencoded" ||
-        contentType.startsWith("application/x-www-form-urlencoded;"));
-}
-const FORM_DECODER = new TextDecoder();
-/**
- * Read an HTML-form body (urlencoded) into the plain object a body schema validates — same byte
- * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
- * repeated-key → `string[]` promotion as query parsing, same `__proto__` guard.
- */
-async function readBoundedForm(req, maxBytes) {
-    const read = await readBoundedBytes(req, maxBytes);
-    if (!read.ok) {
-        return read.status === 413
-            ? jsonError(413, "payload_too_large")
-            : jsonError(400, "invalid_content_length");
-    }
-    const out = Object.create(null);
-    // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);
-    // it never throws on junk input, so no try/catch is needed here.
-    for (const [key, value] of new URLSearchParams(FORM_DECODER.decode(read.bytes))) {
-        setQueryValue(out, key, value);
-    }
-    return out;
-}
-function decodeParams(raw) {
-    let out;
-    for (const key in raw) {
-        const value = raw[key];
-        // `decodeURIComponent` only changes strings containing `%`; for the common
-        // unencoded param (`/users/123`) skip the call and its throw-check entirely —
-        // semantically identical (no `%` ⇒ no escapes to decode), ~3× cheaper on that path. If every
-        // param is already plain, return the router's per-request object directly and skip a clone.
-        if (!value.includes("%")) {
-            continue;
-        }
-        try {
-            out ??= { ...raw };
-            out[key] = decodeURIComponent(value);
-        }
-        catch {
-            return null;
-        }
-    }
-    return out ?? raw;
-}
+// `jsonError`, `urlPartsOf`, `pathnameOf` moved to `./http.ts` (a dependency-free leaf shared with the
+// opt-in request lanes); re-exported so existing importers keep resolving from here.
+export { pathnameOf, urlPartsOf } from "./http.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) {
     for (const key in params) {
         if (params[key].includes("\uFFFD"))
@@ -298,35 +129,6 @@ function hasReplacementParam(params) {
     }
     return false;
 }
-class LazyResponseControls {
-    status;
-    _headers;
-    _cookies;
-    get headers() {
-        this._headers ??= {};
-        return this._headers;
-    }
-    cookie(name, value, options) {
-        // Secure-by-default: HttpOnly + Secure + SameSite=Lax + Path=/, overridable per call.
-        const merged = {
-            httpOnly: true,
-            secure: true,
-            sameSite: "lax",
-            path: "/",
-            ...options,
-        };
-        this._cookies ??= [];
-        this._cookies.push(serializeCookie(name, value, merged));
-    }
-    deleteCookie(name, options) {
-        // Expire immediately; default Path=/, and match the original path/domain or the browser keeps it.
-        this._cookies ??= [];
-        this._cookies.push(serializeCookie(name, "", { path: "/", ...options, maxAge: 0, expires: EPOCH }));
-    }
-}
-// Finalization only reads `status`, `_headers`, and `_cookies`. The user-visible mutator methods
-// live on `LazyResponseControls`, created by the `c.set` getter only when user code touches it.
-const EMPTY_RESPONSE_CONTROLS = Object.freeze({});
 function responseSet(ctx) {
     return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
 }
@@ -340,302 +142,9 @@ function isContextlessNoArgArrow(handler) {
         return false;
     }
 }
-/** Coerce `c.json`/`c.text`'s second arg — a status number (the common case) or a full `ResponseInit`. */
-function statusInit(init) {
-    return typeof init === "number" ? { status: init } : init;
-}
-class RequestContext {
-    constructor(source, params, searchOrMaxBodyBytes, signal, budget, platform, maxBodyBytes) {
-        this.source = source;
-        this.params = params;
-        if (typeof searchOrMaxBodyBytes === "number") {
-            this.maxBodyBytes = searchOrMaxBodyBytes;
-            return;
-        }
-        if (searchOrMaxBodyBytes !== undefined)
-            this.searchValue = searchOrMaxBodyBytes;
-        this.signalValue = signal;
-        this.budgetValue = budget;
-        if (platform !== undefined)
-            this.platformValue = platform;
-        this.maxBodyBytes = maxBodyBytes;
-    }
-    static native(source, params, maxBodyBytes) {
-        return new RequestContext(source, params, maxBodyBytes);
-    }
-    [CONTEXT_SET]() {
-        return this.setValue;
-    }
-    get [CONTEXT_SEARCH]() {
-        this.searchValue ??= searchOf(this.source.url);
-        return this.searchValue;
-    }
-    get set() {
-        this.setValue ??= new LazyResponseControls();
-        return this.setValue;
-    }
-    get signal() {
-        return this.signalValue ?? getNeverAbortSignal();
-    }
-    get budget() {
-        return this.budgetValue ?? getUnboundedRequestBudget();
-    }
-    get env() {
-        return this.platformValue?.env;
-    }
-    get waitUntil() {
-        return this.platformValue?.waitUntil ?? fallbackWaitUntil;
-    }
-    get req() {
-        return requestOf(this.source);
-    }
-    get request() {
-        return requestOf(this.source);
-    }
-    json(body, init) {
-        return Response.json(body, statusInit(init));
-    }
-    text(body, init) {
-        const i = statusInit(init);
-        // Default to text/plain; if the caller passes their own headers, they own the content-type.
-        if (i?.headers !== undefined)
-            return new Response(body, i);
-        return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } });
-    }
-    get query() {
-        if (!this.queryReady) {
-            this.queryValue = new URLSearchParams(this[CONTEXT_SEARCH]);
-            this.queryReady = true;
-        }
-        return this.queryValue;
-    }
-    set query(v) {
-        this.queryValue = v;
-        this.queryReady = true;
-    }
-    get cookies() {
-        this.cookiesValue ??= parseCookies(headerOf(this.source, "cookie"));
-        return this.cookiesValue;
-    }
-    boundedBody(maxBytes) {
-        return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes);
-    }
-    boundedJson(maxBytes) {
-        return readBoundedJsonBodyOrThrow(this.source, this.maxBodyBytes, maxBytes);
-    }
-}
-/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 `Response` (caught by
- * `runLifecycle` as control flow, like `throw redirect(...)`), so a handler can't ignore the cap.
- * The byte-cap itself lives in `./body.ts` (shared with the schema path and `verifyWebhook`). */
-async function readBoundedBodyOrThrow(req, maxBodyBytes, maxBytes) {
-    const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes);
-    if (r.ok)
-        return r.bytes;
-    throw r.status === 413
-        ? jsonError(413, "payload_too_large")
-        : jsonError(400, "invalid_content_length");
-}
-/** Backs `c.boundedJson`: `readBoundedBodyOrThrow` + `JSON.parse`, throwing a flat 400 on bad JSON. */
-async function readBoundedJsonBodyOrThrow(req, maxBodyBytes, maxBytes) {
-    const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes);
-    if (parsed instanceof Response)
-        throw parsed;
-    return parsed;
-}
-/**
- * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`.
- * Non-chunked, framed requests with an in-cap `Content-Length` use the runtime-native `req.json()`;
- * chunked or length-less requests fall back to the streaming byte-cap guard.
- */
-async function readBoundedJsonSource(req, maxBytes) {
-    const declared = headerOf(req, "content-length");
-    if (declared !== null) {
-        // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
-        // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
-        // "abc"→NaN, "-5", "1.5", "1e3", "0x10") is malformed → 400, rather than silently falling
-        // through to the streaming guard — which is an UPPER-bound cap only, so a lying SMALLER length
-        // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
-        // hardens hand-built Requests (tests, the in-process client) and crafted input.
-        const length = parseContentLength(declared);
-        if (length === undefined)
-            return jsonError(400, "invalid_content_length");
-        if (length > maxBytes)
-            return jsonError(413, "payload_too_large");
-        const chunked = headerOf(req, "transfer-encoding") !== null;
-        if (!chunked) {
-            try {
-                return await req.json();
-            }
-            catch {
-                return jsonError(400, "invalid_json");
-            }
-        }
-    }
-    const body = req.body;
-    if (body === null)
-        return jsonError(400, "invalid_json");
-    const drained = await drainCapped(body, maxBytes);
-    if (!drained.ok)
-        return jsonError(413, "payload_too_large");
-    try {
-        return JSON.parse(TEXT_DECODER.decode(drained.bytes));
-    }
-    catch {
-        return jsonError(400, "invalid_json");
-    }
-}
-/** A fixed past instant for cookie deletion (`Expires`). A literal epoch — deterministic, unlike an
- * argless `new Date()`. */
-const EPOCH = new Date(0);
-/** Build the response headers init. The common path (no `c.set`) returns `undefined` so `Response`
- * gets no `headers` at all. Cookies force a `Headers` object — multiple `Set-Cookie`s can't live in a
- * `Record<string,string>` (the 2nd would overwrite the 1st), so they're `append`ed individually. */
-function headersInit(set) {
-    const cookies = set._cookies;
-    if (cookies === undefined || cookies.length === 0)
-        return set._headers;
-    const headers = new Headers(set._headers);
-    for (const cookie of cookies)
-        headers.append("set-cookie", cookie);
-    return headers;
-}
-// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
-// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
-// across responses: the Response constructor copies `init.headers` into its own list.
-const JSON_CT_HEADERS = new Headers({
-    "content-type": "application/json;charset=utf-8",
-});
-const JSON_INIT_200 = { status: 200, headers: JSON_CT_HEADERS };
-/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
- * older hand-inlined stringify + Response construction on this lane while preserving the exact
- * body/content-type contract; keep the generic fallback for non-JSON values. */
-function fusedRespondNoSet(result) {
-    if (result !== undefined &&
-        !(result instanceof Response) &&
-        typeof result === "object" &&
-        result !== null &&
-        !isResponseResult(result)) {
-        return Response.json(result);
-    }
-    return toResponse(result, EMPTY_RESPONSE_CONTROLS);
-}
-/** Fused-lane respond with a context: read `c.set` once; untouched (the common case) → the fast
- * JSON respond; touched → the generic `toResponse` with those controls (statuses, headers, cookies). */
-function fusedRespond(result, ctx) {
-    const set = ctx[CONTEXT_SET]();
-    if (set === undefined)
-        return fusedRespondNoSet(result);
-    return toResponse(result, set);
-}
-function toResponse(result, set) {
-    if (isResponseResult(result)) {
-        return appendCookiesToResponse(result.toResponse(), set);
-    }
-    if (result instanceof Response) {
-        return appendCookiesToResponse(result, set);
-    }
-    const headers = headersInit(set);
-    const status = set.status ?? (result === undefined ? 204 : 200);
-    if (headers === undefined && result !== undefined) {
-        // Fast respond (profiled ≈ −50 ns/req on every plain-JSON return): `JSON.stringify` + a
-        // prebuilt init beats `Response.json`'s internal init handling. Output is byte-identical —
-        // same body bytes, same probed content-type. `undefined` from stringify (a function/symbol
-        // result) delegates to Response.json so its TypeError contract stays the single source.
-        const body = JSON.stringify(result);
-        if (body !== undefined) {
-            return new Response(body, status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS });
-        }
-    }
-    const init = headers === undefined ? { status } : { status, headers };
-    return result === undefined ? new Response(null, init) : Response.json(result, init);
-}
-function appendCookiesToResponse(response, set) {
-    // A handler may queue cookies (`c.set.cookie` — e.g. a session cookie) AND return its own Response
-    // (e.g. `redirect("/")` after login). Cookies accumulate additively, so append them to the
-    // returned Response — otherwise the canonical set-session-then-redirect pattern would silently drop
-    // the cookie. (Other `c.set` fields stay the returned Response's own concern.)
-    const cookies = set._cookies;
-    if (cookies !== undefined && cookies.length > 0) {
-        for (const cookie of cookies)
-            response.headers.append("set-cookie", cookie);
-    }
-    return response;
-}
-/**
- * `finalize` for the node-direct path — mirror of {@link toResponse} that skips the `Response` build:
- * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
- * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
- * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
- * works on Node).
- */
-function toNodeOutcome(result, set) {
-    if (isResponseResult(result)) {
-        const body = result.toNodeBody?.();
-        if (body !== undefined) {
-            return {
-                kind: "body",
-                status: body.status,
-                headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
-                body: body.body,
-            };
-        }
-        return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set));
-    }
-    if (result instanceof Response) {
-        return nodeOutcomeFromResponse(appendCookiesToResponse(result, set));
-    }
-    const status = set.status ?? (result === undefined ? 204 : 200);
-    return {
-        kind: "json",
-        status,
-        headers: set._headers,
-        cookies: set._cookies,
-        body: result === undefined ? null : JSON.stringify(result),
-    };
-}
 // Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
 const IDENTITY_RESPONSE = (response) => response;
 const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
-const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
-const NODE_FROM_RESPONSE = (response) => nodeOutcomeFromResponse(response);
-const NODE_TIMEOUT = () => ({
-    kind: "response",
-    response: jsonError(503, "request_timeout"),
-});
-function nodeOutcomeFromResponse(response) {
-    const body = nodeResponseBody(response);
-    return body === undefined
-        ? { kind: "response", response }
-        : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body };
-}
-function nodeResponseBody(response) {
-    if (response.bodyUsed)
-        return undefined;
-    const body = response[NODE_RESPONSE_BODY];
-    return typeof body === "string" || body instanceof Uint8Array ? body : undefined;
-}
-function responseHeadersForNode(response) {
-    let headers;
-    response.headers.forEach((value, key) => {
-        headers ??= {};
-        headers[key] = value;
-    });
-    const setCookies = response.headers.getSetCookie?.();
-    if (setCookies !== undefined && setCookies.length > 0) {
-        headers ??= {};
-        headers["set-cookie"] = setCookies;
-    }
-    return headers;
-}
-function appendCookiesToNodeHeaders(headers, cookies) {
-    if (cookies === undefined || cookies.length === 0)
-        return headers;
-    const out = headers === undefined ? {} : { ...headers };
-    const existing = out["set-cookie"];
-    const setCookies = existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing];
-    out["set-cookie"] = [...setCookies, ...cookies];
-    return out;
-}
 /**
  * The inline server. Routes are chainable and fully type-inferred. `derive`/
  * `decorate` extend the handler context (`Ctx`) for routes defined *after* them,
@@ -645,7 +154,7 @@ function appendCookiesToNodeHeaders(headers, cookies) {
  *      .get("/me", (c) => c.user)            // c.user + c.db are typed
  */
 export class Server {
-    router;
+    catalog;
     /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
     wsRouter;
     wsRouteCount;
@@ -653,10 +162,11 @@ export class Server {
      * 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. */
     topics;
-    routeList;
     maxBodyBytes;
     wsMaxPayloadBytes;
     requestTimeoutMs;
+    /** Opt-in caller-IP trust declaration; `undefined` = socket peer only, no forwarded header believed. */
+    clientIpTrust;
     acceptInboundDeadlines;
     maxInboundDeadlineMs;
     deadlineAdmissionOptions;
@@ -664,15 +174,25 @@ export class Server {
     /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
     capacityGate;
     onCapabilityUse;
-    /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
-    effectLedger;
-    /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
-    configuredIdempotencyStore;
-    lazyIdempotencyStore;
+    /** The installed effect-ledger runtime (owns the sink + per-route resolution + settle), or
+     * `undefined` when the effect-ledger plugin is not installed. */
+    effectLedgerRuntime;
+    /** The installed idempotency runtime (owns the app-wide default store + the dedupe lane), or
+     * `undefined` when the idempotency plugin is not installed. */
+    idempotencyRuntime;
+    /** Installed opt-in runtime for `.tool()`/`.resource()`/`.prompt()`; `undefined` until `.use(mcp())`. */
+    mcpRuntime;
+    /** Installed Node-direct renderer for direct `resolveNode()` callers; `undefined` until `.use(nodeDirect())`. */
+    nodeOutcomeRuntime;
+    /** Installed streaming runtime for `.sse()` routes; `undefined` until `.use(streaming())`. */
+    sseRuntime;
+    /** Installed WebSocket runtime for `.ws()` routes; `undefined` until `.use(websocket())`. */
+    wsRuntime;
     logger;
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     defaultOnValidationError;
     bunServer;
+    sealed;
     derives;
     decorations;
     beforeHandleHooks;
@@ -692,22 +212,15 @@ export class Server {
     /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
     mcpResourceList;
     mcpPromptList;
-    /**
-     * Every registered route's raw router entry + descriptor, in order — the replay source for
-     * {@link merge}. The entry already carries the chains captured at registration (derives,
-     * decorations, before/after/around/onError), so a merged route behaves exactly as it did on
-     * the server that defined it.
-     */
-    rawEntries;
     constructor(options = {}) {
-        this.router = new Router();
+        this.catalog = new RouteCatalog();
         this.wsRouter = new Router();
         this.wsRouteCount = 0;
         this.topics = undefined;
-        this.routeList = [];
         this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
         this.wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? this.maxBodyBytes;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
+        this.clientIpTrust = options.clientIp;
         this.acceptInboundDeadlines = options.acceptInboundDeadlines ?? false;
         this.maxInboundDeadlineMs = options.maxInboundDeadlineMs ?? 30_000;
         this.deadlineAdmissionOptions = Object.freeze({
@@ -723,29 +236,16 @@ export class Server {
         this.gracefulSignals = options.gracefulSignals ?? false;
         this.capacityGate = options.admission;
         this.onCapabilityUse = options.onCapabilityUse;
-        if (options.effectLedger !== undefined) {
-            const ledger = options.effectLedger;
-            if (typeof ledger.sink !== "function") {
-                throw new TypeError("effectLedger.sink must be a function");
-            }
-            const maxEntries = ledger.maxEntries ?? DEFAULT_MAX_ENTRIES;
-            if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
-                throw new RangeError("effectLedger.maxEntries must be a positive safe integer");
-            }
-            this.effectLedger = Object.freeze({
-                sink: ledger.sink,
-                maxEntries,
-                chain: ledger.chain ?? false,
-            });
-        }
-        else {
-            this.effectLedger = undefined;
-        }
-        this.configuredIdempotencyStore = options.idempotencyStore;
-        this.lazyIdempotencyStore = undefined;
+        // The effect-ledger runtime is installed by `.use(effectLedger())`; a bare app never imports it, so
+        // the ledger machinery tree-shakes out. Capability-declaring routes simply carry no ledger without it.
+        this.effectLedgerRuntime = undefined;
+        // The idempotency runtime is installed by `.use(idempotency())`; a bare app never imports it, so the
+        // dedupe machinery tree-shakes out. A route that declares idempotency without it is a build error.
+        this.idempotencyRuntime = undefined;
         this.logger = options.logger ?? jsonLogger();
         this.defaultOnValidationError = options.onValidationError;
         this.bunServer = undefined;
+        this.sealed = false;
         this.derives = [];
         this.decorations = {};
         this.beforeHandleHooks = [];
@@ -761,15 +261,21 @@ export class Server {
         this.globalAssurance = [];
         this.mcpResourceList = [];
         this.mcpPromptList = [];
-        this.rawEntries = [];
+    }
+    assertConfigurable(operation) {
+        if (this.sealed) {
+            throw new FrameworkError("SERVER_SEALED", `server configuration is sealed after listen(); call ${operation} before listen()`);
+        }
     }
     /** Add a per-request, computed context extension for subsequent routes. */
     derive(fn) {
+        this.assertConfigurable("derive()");
         this.derives.push(fn);
         return this;
     }
     /** Add a static context value for subsequent routes. */
     decorate(key, value) {
+        this.assertConfigurable("decorate()");
         this.decorations[key] = value;
         return this;
     }
@@ -778,11 +284,13 @@ export class Server {
      * `Request` to continue routing with a rewritten method/URL/headers. Global.
      */
     onRequest(fn) {
+        this.assertConfigurable("onRequest()");
         this.onRequestHooks.push(fn);
         return this;
     }
     /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
     beforeHandle(fn) {
+        this.assertConfigurable("beforeHandle()");
         this.beforeHandleHooks.push(fn);
         return this;
     }
@@ -792,30 +300,36 @@ export class Server {
      * a Web `Response`. The first registered wrapper is outermost.
      */
     around(fn) {
+        this.assertConfigurable("around()");
         this.aroundHooks.push(fn);
         return this;
     }
     /** Transform the handler's result before it is serialized. Order-scoped. */
     afterHandle(fn) {
+        this.assertConfigurable("afterHandle()");
         this.afterHandleHooks.push(fn);
         return this;
     }
     /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
     onError(fn) {
+        this.assertConfigurable("onError()");
         this.onErrorHooks.push(fn);
         return this;
     }
     /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */
     onResponse(fn) {
+        this.assertConfigurable("onResponse()");
         this.onResponseHooks.push(fn);
         return this;
     }
     /** Observe the terminal response after all transformations. Observers are ordered and fail-open. */
     onResponseFinalized(fn) {
+        this.assertConfigurable("onResponseFinalized()");
         this.onResponseFinalizedHooks.push(fn);
         return this;
     }
     use(arg) {
+        this.assertConfigurable("use()");
         if (typeof arg === "function") {
             const name = arg.pluginName;
             if (name !== undefined) {
@@ -878,7 +392,8 @@ export class Server {
      * JSON-serialized into the SSE `data:` field. The typed client sees the marker and grows a
      * `.subscribe(onEvent)` for the route with the same payload type — end-to-end typed streaming.
      *
-     *   const app = server().sse("/feed", { sse: t.object({ id: t.integer(), title: t.string() }) },
+     *   import { streaming } from "@nifrajs/core/sse"   // .use(streaming()) enables .sse()
+     *   const app = server().use(streaming()).sse("/feed", { sse: t.object({ id: t.integer(), title: t.string() }) },
      *     async (c, stream) => {
      *       stream.send({ id: 1, title: "hello" })          // typed
      *       await waitForDisconnect(stream.signal)
@@ -892,7 +407,7 @@ export class Server {
      * (`stream.signal`). Query/body schemas validate exactly as on any other route.
      */
     sse(path, schema, run, init) {
-        const handler = (context) => sse(context, (stream) => run(context, typedSSEStream(stream)), init);
+        const handler = (context) => requireSseRuntime(this.sseRuntime).response(context, (stream) => run(context, stream), init);
         return this.route("GET", path, schema, handler);
     }
     post(path, schemaOrHandler, handler) {
@@ -908,24 +423,14 @@ export class Server {
         return this.route("DELETE", path, schemaOrHandler, handler);
     }
     tool(name, config, handler) {
-        const path = `/_nifra/tool/${name}`;
-        const routeSchema = config.output !== undefined
-            ? { body: config.input, response: config.output }
-            : { body: config.input };
-        // register's handler is the erased `(context: never) => unknown`; the tool's typed input/ctx come from
-        // the overload above, so bridge with a single cast rather than `any`.
-        const run = (c) => handler(c.body, c);
-        this.register("POST", path, routeSchema, run);
+        const plan = requireMcpRuntime(this.mcpRuntime).tool(name, config, handler);
+        this.register("POST", plan.path, plan.schema, plan.run);
         // Tag the just-registered descriptor as an MCP tool. `tool` is readonly on RouteDescriptor (an
         // introspection field), so write it through a narrow mutable view — not `any`.
-        const lastRoute = this.routeList[this.routeList.length - 1];
+        const lastRoute = this.catalog.lastDescriptor();
         if (lastRoute) {
             ;
-            lastRoute.tool = {
-                name,
-                description: config.description,
-                ...(config.annotations !== undefined ? { annotations: config.annotations } : {}),
-            };
+            lastRoute.tool = plan.descriptor;
         }
         return this;
     }
@@ -936,13 +441,8 @@ export class Server {
      * for the resource half of MCP.
      */
     resource(uri, config, read) {
-        this.mcpResourceList.push({
-            uri,
-            name: config.name,
-            ...(config.description !== undefined ? { description: config.description } : {}),
-            ...(config.mimeType !== undefined ? { mimeType: config.mimeType } : {}),
-            read,
-        });
+        this.assertConfigurable("resource()");
+        this.mcpResourceList.push(requireMcpRuntime(this.mcpRuntime).resource(uri, config, read));
         return this;
     }
     /**
@@ -950,12 +450,8 @@ export class Server {
      * `handler` receives the caller's arguments and returns the rendered messages.
      */
     prompt(name, config, handler) {
-        this.mcpPromptList.push({
-            name,
-            description: config.description,
-            ...(config.arguments !== undefined ? { arguments: config.arguments } : {}),
-            handler,
-        });
+        this.assertConfigurable("prompt()");
+        this.mcpPromptList.push(requireMcpRuntime(this.mcpRuntime).prompt(name, config, handler));
         return this;
     }
     /** The MCP resources declared via {@link resource} — enumerated by `nifra mcp`. */
@@ -973,12 +469,19 @@ export class Server {
      * adapter (`listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler`) — not by bare `app.fetch`, which
      * has no socket (a WS path through `app.fetch` is a normal HTTP response).
      *
+     * The route also enters the type-level registry (under the pseudo-method `"WS"`), so the typed
+     * client grows a `.ws()` handle for it: `messageSchema` types what the client may `send`,
+     * `sendSchema` types the frames it receives. Passing explicit type arguments (`ws<MyData>(…)`)
+     * defeats path-literal inference and skips the registry entry - the route still serves, it is just
+     * invisible to `client<App>`; prefer typing `data` via `upgrade()`'s return.
+     *
      *   app.ws("/chat", { open: (ws) => ws.send("hi"), message: (ws, data) => ws.send(data) })
      */
     ws(path, handler) {
+        this.assertConfigurable("ws()");
         // Boot-time guard: the WS runtime is a subpath (`@nifrajs/core/ws`) so no-WebSocket apps don't
         // bundle it. Registration is the loud, early failure point — never the first connection.
-        const runtime = requireWsRuntime();
+        const runtime = requireWsRuntime(this.wsRuntime);
         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.
@@ -1019,6 +522,18 @@ 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));
+    }
+    /** 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. */
+    registerBatch(routes) {
+        this.assertConfigurable("route registration");
+        const staged = routes.map(({ method, path, schema, handler }) => this.prepareRoute(method, path, schema, handler));
+        this.catalog.addBatch(staged);
+    }
+    prepareRoute(method, path, schema, handler) {
+        const pattern = compileRoutePattern(path);
         const capabilities = normalizeRouteCapabilities(schema?.capabilities);
         const handlerAssurance = assuranceDeclarationsOf(handler);
         const invalidHandlerScope = handlerAssurance.find((declaration) => declaration.scope !== "plugin");
@@ -1033,15 +548,19 @@ export class Server {
         const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0;
         // An idempotency route runs a dedupe lane that must buffer the body and capture the response, so it
         // never takes the fused/native fast path — force it onto the portable matched lane (which routes
-        // through `fetchMatched`, where the dedupe wrapper lives).
-        const idempotent = this.resolveIdempotency(schema, authenticated);
-        // A ledgered route (capabilities declared + `server({ effectLedger })`) needs a per-request
+        // through `fetchMatched`, where the dedupe wrapper lives). Fail closed: a route may not declare
+        // idempotency unless the idempotency runtime is installed, so the safety gate can never be silently
+        // dropped by a missing plugin.
+        if (schema?.idempotency !== undefined && this.idempotencyRuntime === undefined) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "route declares idempotency but the idempotency plugin is not installed; add .use(idempotency())");
+        }
+        const idempotent = this.idempotencyRuntime?.resolve(schema, authenticated, this.maxBodyBytes);
+        // A ledgered route (capabilities declared + `.use(effectLedger())`) needs a per-request
         // context to carry the ledger and a settle step to seal + sink it, so it too leaves the
         // fused/contextless fast path. Resolved per route, at registration — like the capability guard.
-        const ledgered = capabilities.length > 0 && this.effectLedger !== undefined
-            ? Object.freeze({ ...this.effectLedger, method, path, declared: capabilities })
-            : undefined;
-        const bare = schema?.body === undefined &&
+        const ledgered = this.effectLedgerRuntime?.resolve(capabilities, method, path);
+        const bare = schema?.params === undefined &&
+            schema?.body === undefined &&
             schema?.query === undefined &&
             idempotent === undefined &&
             ledgered === undefined &&
@@ -1052,6 +571,27 @@ export class Server {
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
             : undefined;
+        const contextless = bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler);
+        const lane = bare
+            ? "bare"
+            : schema?.body !== undefined &&
+                schema.query === undefined &&
+                schema.params === undefined &&
+                this.derives.length === 0 &&
+                this.beforeHandleHooks.length === 0 &&
+                this.afterHandleHooks.length === 0 &&
+                this.onErrorHooks.length === 0
+                ? "body"
+                : schema?.body === undefined &&
+                    schema?.query !== undefined &&
+                    schema.params === undefined &&
+                    this.derives.length === 0 &&
+                    this.beforeHandleHooks.length === 0 &&
+                    this.afterHandleHooks.length === 0 &&
+                    this.onErrorHooks.length === 0
+                    ? "query"
+                    : "lifecycle";
+        const execution = this.compileExecutionPlan(lane, contextless, this.aroundHooks.length > 0, ledgered !== undefined, fusedWeb);
         const entry = {
             // (context: never) => unknown -> InternalHandler: the framework invokes it
             // with the concrete RawContext the typed handler expects, so this is sound.
@@ -1059,7 +599,6 @@ export class Server {
             schema,
             idempotent,
             ledgered,
-            fusedWeb,
             derives: [...this.derives],
             decorations: routeDecorations,
             hasDecorations,
@@ -1067,34 +606,25 @@ export class Server {
             afterHandle: [...this.afterHandleHooks],
             onError: [...this.onErrorHooks],
             around: [...this.aroundHooks],
-            // Sync-fast-path eligibility (see RouteEntry.bare). Validation + every hook kind must be absent;
-            // decorations and generic around wrappers are fine: around wraps the inner bare route in
-            // `routeAndRun`, while the inner validation/derive/before/after/onError lifecycle remains empty.
-            // Most GET/no-schema routes qualify.
-            bare,
-            contextlessBare: bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler),
-            bodyOnly: schema?.body !== undefined &&
-                schema.query === undefined &&
-                this.derives.length === 0 &&
-                this.beforeHandleHooks.length === 0 &&
-                this.afterHandleHooks.length === 0 &&
-                this.onErrorHooks.length === 0,
-            queryOnly: schema?.body === undefined &&
-                schema?.query !== undefined &&
-                this.derives.length === 0 &&
-                this.beforeHandleHooks.length === 0 &&
-                this.afterHandleHooks.length === 0 &&
-                this.onErrorHooks.length === 0,
+            execution,
         };
-        this.router.add(method, path, entry);
         const descriptor = {
             method,
             path,
             schema,
             ...(capabilities.length > 0 ? { capabilities } : {}),
+            ...(schema?.family === true ? { family: true } : {}),
         };
-        this.routeList.push(descriptor);
         const routeAssurance = [...this.activeAssurance, ...handlerAssurance];
+        // Inline `schema.assurance`: the route DECLARES its enforcement evidence adjacent to the handler, so an
+        // in-handler-guarded route satisfies a policy `require:` clause without a `withRouteAssurance` middleware
+        // rewrite. Each id becomes route-scoped `declared` evidence (invalid ids fail closed at registration).
+        for (const id of schema?.assurance ?? []) {
+            if (!validEvidenceId(id)) {
+                throw new Error(`route assurance: invalid evidence id ${JSON.stringify(id)} on ${method} ${path} (use lowercase dot/dash segments)`);
+            }
+            routeAssurance.push(Object.freeze({ id, source: "declared", scope: "plugin" }));
+        }
         if (schema?.body !== undefined) {
             routeAssurance.push(Object.freeze({
                 id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
@@ -1111,65 +641,88 @@ export class Server {
                 scope: "plugin",
             }));
         }
-        this.rawEntries.push({
+        return {
             method,
             path,
+            pattern,
             entry,
             descriptor,
             assurance: Object.freeze(routeAssurance),
-        });
-    }
-    /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
-    resolveIdempotency(schema, authenticated) {
-        const config = schema?.idempotency;
-        if (config === undefined)
-            return undefined;
-        if (schema?.sse !== undefined) {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", "streaming/SSE responses cannot be used on an idempotency route");
-        }
-        const store = config.store ?? this.defaultIdempotencyStore();
-        if (config.scope === "durable" && store.durability !== "durable") {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", 'durable idempotency requires a durable store (store.durability must be "durable")');
-        }
-        const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
-        if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency ttlMs must be a finite positive number");
-        }
-        const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase();
-        try {
-            new Headers().set(headerName, "probe");
-        }
-        catch {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", `invalid idempotency header name ${JSON.stringify(headerName)}`);
-        }
-        const namespace = config.namespace;
-        if (namespace === undefined) {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency namespace is required; use a principal resolver or an explicit shared scope");
-        }
-        if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", `invalid idempotency namespace ${JSON.stringify(namespace)}`);
-        }
-        if (authenticated && typeof namespace !== "function") {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", "authenticated idempotency routes require a principal namespace resolver");
-        }
-        const maxResponseBytes = config.maxResponseBytes ?? this.maxBodyBytes;
-        if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
-            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency maxResponseBytes must be a positive integer");
-        }
-        return Object.freeze({
-            store,
-            ttlMs,
-            headerName,
-            namespace,
-            maxResponseBytes,
-        });
+        };
     }
-    /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
-    defaultIdempotencyStore() {
-        if (this.configuredIdempotencyStore !== undefined)
-            return this.configuredIdempotencyStore;
-        this.lazyIdempotencyStore ??= new MemoryIdempotencyStore();
-        return this.lazyIdempotencyStore;
+    /** Collapse route-invariant lifecycle decisions into one runner at registration. The request path
+     * performs no eligibility ladder: it supplies request state to this already-selected plan. */
+    compileExecutionPlan(lane, contextless, hasAround, hasLedger, fusedWeb) {
+        if (contextless) {
+            const run = (runtime, entry, source, params, search, signal, budget, platform, finalize, wrapResponse) => runtime.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
+            return Object.freeze({ run, fusedWeb });
+        }
+        let inner;
+        switch (lane) {
+            case "bare":
+                inner = (runtime, entry, _source, ctx, finalize, wrapResponse) => runtime.runBare(entry, ctx, finalize, wrapResponse);
+                break;
+            case "body":
+                inner = (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runBodyOnly(entry, source, ctx, finalize, wrapResponse);
+                break;
+            case "query":
+                inner = (runtime, entry, _source, ctx, finalize, wrapResponse) => runtime.runQueryOnly(entry, ctx, finalize, wrapResponse);
+                break;
+            default:
+                inner = (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runLifecycle(entry, source, ctx, finalize, wrapResponse);
+        }
+        const execute = hasAround
+            ? (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runWithAround(entry, ctx, () => inner(runtime, entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse)
+            : inner;
+        const run = (runtime, entry, source, params, search, signal, budget, platform, finalize, wrapResponse) => {
+            const ctx = new RequestContext(source, params, search, signal, budget, platform, runtime.maxBodyBytes);
+            let ledger;
+            // The runtime is always present when a route resolved a ledger (enforced at registration).
+            const ledgerRuntime = runtime.effectLedgerRuntime;
+            if (hasLedger && ledgerRuntime !== undefined) {
+                const resolved = entry.ledgered;
+                ledger = ledgerRuntime.create(resolved);
+                ledgerRuntime.attach(ctx, ledger);
+            }
+            let outcome = execute(runtime, entry, source, ctx, finalize, wrapResponse);
+            if (ledger !== undefined && ledgerRuntime !== undefined) {
+                const active = ledger;
+                const resolved = entry.ledgered;
+                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => ledgerRuntime.settle(active, resolved, value, (fields) => runtime.logger.error("effect ledger sink failed", fields)));
+            }
+            return outcome;
+        };
+        return Object.freeze({ run, fusedWeb });
+    }
+    /** The idempotency lane's bridge back into the normal matched lanes, resolved to a concrete Response
+     * (the lane buffers the body, then replays it through the route's real validation + handler). */
+    idempotencyRunLanes(buffered, platform, entry, params, search) {
+        return Promise.resolve(this.runMatchedLanes(buffered, platform, entry, params, search, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, false));
+    }
+    /** @internal Symbol-keyed install seam for the `idempotency()` plugin. Off the public typed surface. */
+    [INSTALL_IDEMPOTENCY](runtime) {
+        this.assertConfigurable("idempotency()");
+        this.idempotencyRuntime = runtime;
+    }
+    /** @internal Symbol-keyed install seam for the `mcp()` plugin. Off the public typed surface. */
+    [INSTALL_MCP](runtime) {
+        this.assertConfigurable("mcp()");
+        this.mcpRuntime = runtime;
+    }
+    /** @internal Symbol-keyed install seam for the `nodeDirect()` plugin. Off the public typed surface. */
+    [INSTALL_NODE_DIRECT](runtime) {
+        this.assertConfigurable("nodeDirect()");
+        this.nodeOutcomeRuntime = runtime;
+    }
+    /** @internal Symbol-keyed install seam for the `streaming()` plugin. Off the public typed surface. */
+    [INSTALL_SSE](runtime) {
+        this.assertConfigurable("streaming()");
+        this.sseRuntime = runtime;
+    }
+    /** @internal Symbol-keyed install seam for the `websocket()` plugin. Off the public typed surface. */
+    [INSTALL_WS](runtime) {
+        this.assertConfigurable("websocket()");
+        this.wsRuntime = runtime;
     }
     /**
      * Merge another server's routes into this one — the composition escape hatch for large apps.
@@ -1191,15 +744,23 @@ export class Server {
      * those on the parent).
      */
     merge(other) {
+        this.assertConfigurable("merge()");
         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");
         }
-        for (const { method, path, entry, descriptor, assurance } of source.rawEntries) {
-            this.router.add(method, path, entry); // throws RouteConfigError on a duplicate — fail closed
-            this.routeList.push(descriptor); // shared ref on purpose: carries later .tool() tagging
-            this.rawEntries.push({ method, path, entry, descriptor, assurance });
-        }
+        this.catalog.addBatch(source.catalog.entries().map((route) => this.bindFusedRuntime(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.idempotencyRuntime ??= source.idempotencyRuntime;
+        this.effectLedgerRuntime ??= source.effectLedgerRuntime;
+        this.mcpRuntime ??= source.mcpRuntime;
+        this.nodeOutcomeRuntime ??= source.nodeOutcomeRuntime;
+        this.sseRuntime ??= source.sseRuntime;
+        this.wsRuntime ??= source.wsRuntime;
         this.onRequestHooks.push(...source.onRequestHooks);
         this.onResponseHooks.push(...source.onResponseHooks);
         this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks);
@@ -1208,6 +769,21 @@ export class Server {
         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. */
+    bindFusedRuntime(route) {
+        const { entry } = route;
+        if (entry.execution.fusedWeb === undefined)
+            return route;
+        const fusedWeb = this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler));
+        return {
+            ...route,
+            entry: {
+                ...entry,
+                execution: Object.freeze({ ...entry.execution, fusedWeb }),
+            },
+        };
+    }
     /**
      * Enumerate the registered routes (method, path, input schemas), in registration
      * order. Powers `toOpenAPI` and other introspection; the router trie itself no
@@ -1215,11 +791,11 @@ export class Server {
      */
     routes() {
         if (this.activeAssurance.length === 0 && this.globalAssurance.length === 0) {
-            const anyRouteEvidence = this.rawEntries.some((entry) => entry.assurance.length > 0);
-            if (!anyRouteEvidence)
-                return this.routeList;
+            if (!this.catalog.hasAssurance()) {
+                return this.catalog.routeDescriptors();
+            }
         }
-        return this.rawEntries.map(({ method, path, descriptor, assurance }) => {
+        return this.catalog.entries().map(({ method, path, descriptor, assurance }) => {
             const effective = assuranceEvidenceFor([...assurance, ...this.globalAssurance], method, path);
             return effective.length > 0 ? { ...descriptor, assurance: effective } : descriptor;
         });
@@ -1242,7 +818,7 @@ export class Server {
     }
     fetchSourceInner(source, platform) {
         // Non-`async` on purpose: `dispatch` may return a `Response` *synchronously* (the bare-route fast
-        // path, see RouteEntry.bare), and an `async fetch` would wrap every such result in a redundant
+        // path, selected by the compiled execution plan), and an `async fetch` would wrap every such result in a redundant
         // promise + microtask. Returning `Response | Promise<Response>` matches Web/edge handlers, while
         // `await app.fetch(...)` continues to work exactly as before.
         const outcome = this.dispatch(source, platform, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
@@ -1321,7 +897,7 @@ export class Server {
     resolveNode(req, platform) {
         return this.resolveNodeSource(req, platform);
     }
-    resolveNodeSource(source, platform) {
+    resolveNodeSource(source, platform, suppliedRuntime) {
         // onResponse hooks transform a Response, and the capacity gate wraps the Web response path — both
         // force the Web path here (the gated `fetchSource` admits/sheds/releases); wrap its result.
         if (this.onResponseHooks.length > 0 ||
@@ -1332,10 +908,14 @@ export class Server {
                 ? response.then((settled) => ({ kind: "response", response: settled }))
                 : { kind: "response", response };
         }
-        // May resolve **synchronously** for a bare route + sync handler (RouteEntry.bare) — the `@nifrajs/node`
+        // May resolve **synchronously** for a compiled bare route + sync handler - the `@nifrajs/node`
         // adapter `await`s the result, so it transparently handles either; the sync case allocates no promise
         // at all on the Node hot path.
-        return this.dispatch(source, platform, toNodeOutcome, NODE_FROM_RESPONSE, NODE_TIMEOUT, false);
+        const runtime = suppliedRuntime ?? this.nodeOutcomeRuntime;
+        if (runtime === undefined) {
+            throw new FrameworkError("NODE_DIRECT_RUNTIME_MISSING", "resolveNode() needs the Node-direct renderer. Normal @nifrajs/node serving installs it automatically; direct callers should add `.use(nodeDirect())` (from `@nifrajs/core/node-direct`).");
+        }
+        return this.dispatch(source, platform, runtime.toOutcome, runtime.fromResponse, runtime.timeout, false);
     }
     /**
      * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS
@@ -1356,12 +936,13 @@ export class Server {
             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 : decodeParams(match.params);
+        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 ⇒ the runtime created the registry.
+        // 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`.
@@ -1381,13 +962,13 @@ export class Server {
             return { kind: "reject", response: jsonError(403, "forbidden_origin") };
         }
         if (handler.upgrade === undefined) {
-            return { kind: "upgrade", handler, data: undefined, pubsub };
+            return { kind: "upgrade", handler, data: undefined, pubsub, attach };
         }
         const upgradeSignal = getNeverAbortSignal();
         const ctx = new RequestContext(req, params, url.search, upgradeSignal, createUnboundedRequestBudget(upgradeSignal), platform, this.maxBodyBytes);
         const settle = (value) => value instanceof Response
             ? { kind: "reject", response: value }
-            : { kind: "upgrade", handler, data: value, pubsub };
+            : { kind: "upgrade", handler, data: value, pubsub, attach };
         try {
             const result = handler.upgrade(ctx);
             return result instanceof Promise
@@ -1407,7 +988,7 @@ export class Server {
     bunFetchWithWebSocket(req, server) {
         const handle = (o) => {
             if (o.kind === "pass")
-                return this.fetch(req);
+                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 } })
@@ -1424,16 +1005,26 @@ export class Server {
      * produces the 503. The Web `fetch` and `resolveNode` are thin callers over this one routing +
      * context + lifecycle implementation — no duplication across the trust boundary.
      */
+    /** Apply the `clientIp` trust declaration to the adapter's raw socket peer, returning a platform
+     * whose `clientIp` is the derived caller. Only called when a trust declaration is configured. */
+    deriveClientIp(source, platform) {
+        const derived = resolveClientIp(platform?.clientIp, requestOf(source), this.clientIpTrust);
+        return { ...platform, clientIp: derived };
+    }
     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).
     webFast) {
+        // 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);
         // 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) {
-            return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast);
+            return this.routeAndRun(source, resolved, finalize, wrapResponse, onTimeout, webFast);
         }
-        return this.runWithOnRequest(source, platform, finalize, wrapResponse, onTimeout, webFast);
+        return this.runWithOnRequest(source, resolved, finalize, wrapResponse, onTimeout, webFast);
     }
     /**
      * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the
@@ -1495,12 +1086,12 @@ export class Server {
     }
     /**
      * Route → build context → run. Synchronous through to the handler for a **bare** route
-     * ({@link RouteEntry.bare}), so a sync handler produces its result with zero promise allocations;
+     * (selected by its compiled plan), so a sync handler produces its result with zero promise allocations;
      * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.
      */
     routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast) {
         const url = urlPartsOf(source.url);
-        const match = this.router.find(source.method, url.pathname);
+        const match = this.catalog.find(source.method, url.pathname);
         if (!match.found) {
             if (match.reason === "method-not-allowed") {
                 return wrapResponse(jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }));
@@ -1509,7 +1100,7 @@ export class Server {
         }
         // 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 : decodeParams(match.params);
+        const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
         if (params === null) {
             return wrapResponse(jsonError(400, "malformed_path"));
         }
@@ -1519,115 +1110,16 @@ export class Server {
     runMatched(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
         // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
         // (with the body buffered). All non-idempotent routes skip straight to the lanes — no added cost.
-        if (entry.idempotent !== undefined) {
-            return this.runIdempotent(source, platform, entry, params, search, wrapResponse);
-        }
-        return this.runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast);
-    }
-    /**
-     * Idempotency dedupe lane. Reads the `Idempotency-Key`, fingerprints the request, and consults the
-     * store: a fresh key runs the handler (via {@link runMatchedLanes} with the body buffered) and stores
-     * the response; a repeat key replays it without re-running; a key reused with a different body or an
-     * in-flight duplicate is rejected. Every branch materializes a `Response`, then adapts to `T` via the
-     * caller's `wrapResponse`, so it works on the Web fetch path and the Node-native outcome path alike.
-     */
-    async runIdempotent(source, platform, entry, params, search, wrapResponse) {
-        const config = entry.idempotent;
-        const req = requestOf(source);
-        const key = req.headers.get(config.headerName);
-        if (key === null || !validIdempotencyKey(key)) {
-            return wrapResponse(jsonError(400, "idempotency_key_required"));
-        }
-        const namespace = typeof config.namespace === "function"
-            ? await config.namespace(req.clone(), platform)
-            : config.namespace;
-        if (!validIdempotencyNamespace(namespace)) {
-            return wrapResponse(jsonError(500, "idempotency_namespace_invalid"));
-        }
-        const read = await readBoundedBytes(req, this.maxBodyBytes);
-        if (!read.ok) {
-            return wrapResponse(jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"));
-        }
-        const url = urlPartsOf(req.url);
-        const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"));
-        const fingerprint = await computeIdempotencyFingerprint(req.method, `${url.pathname}${url.search}`, canonicalBody, req.headers.get("content-type") ?? "");
-        const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs });
-        if (begin.state === "replay") {
-            return wrapResponse(responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }));
-        }
-        if (begin.state === "mismatch")
-            return wrapResponse(jsonError(409, "idempotency_key_reused"));
-        if (begin.state === "in-flight") {
-            return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }));
-        }
-        if (begin.state === "capacity") {
-            return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }));
-        }
-        const reservation = begin.reservation;
-        // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
-        // then run those lanes to a concrete Response.
-        const bufferedInit = {
-            method: req.method,
-            headers: req.headers,
-            signal: req.signal,
-        };
-        if (read.bytes.byteLength > 0)
-            bufferedInit.body = read.bytes;
-        const buffered = new Request(req.url, bufferedInit);
-        let response;
-        try {
-            response = await this.runMatchedLanes(buffered, platform, entry, params, search, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, false);
-        }
-        catch (err) {
-            // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
-            // reservation so a retry isn't wedged, then re-throw.
-            await config.store.abandon({ namespace, key, reservation });
-            throw err;
-        }
-        // Cache only successful responses; release the key on any error so the client can retry.
-        if (response.status >= 200 && response.status < 300) {
-            let storedResponse;
-            try {
-                storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes });
-            }
-            catch (error) {
-                if (!(error instanceof IdempotencyResponseTooLargeError))
-                    throw error;
-                // The effect may already have happened, so never abandon and permit a duplicate execution.
-                // Commit a small terminal response under the winning key and return that same response now.
-                response = jsonError(507, "idempotency_response_too_large");
-                try {
-                    storedResponse = await serializeResponse(response, {
-                        maxBytes: config.maxResponseBytes,
-                    });
-                }
-                catch (terminalError) {
-                    if (!(terminalError instanceof IdempotencyResponseTooLargeError))
-                        throw terminalError;
-                    // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
-                    // status + replay safety without silently storing more bytes than the route permits.
-                    response = new Response(null, { status: 507 });
-                    storedResponse = await serializeResponse(response, {
-                        maxBytes: config.maxResponseBytes,
-                    });
-                }
-            }
-            const completed = await config.store.complete({
-                namespace,
-                key,
-                reservation,
-                response: storedResponse,
+        // The runtime is always present when a route resolved idempotency (enforced at registration).
+        if (entry.idempotent !== undefined && this.idempotencyRuntime !== undefined) {
+            return this.idempotencyRuntime.run(entry.idempotent, requestOf(source), platform, entry, params, search, wrapResponse, {
+                maxBodyBytes: this.maxBodyBytes,
+                runLanes: (buffered, plat, ent, prm, srch) => this.idempotencyRunLanes(buffered, plat, ent, prm, srch),
             });
-            if (!completed) {
-                return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }));
-            }
-        }
-        else {
-            await config.store.abandon({ namespace, key, reservation });
         }
-        return wrapResponse(response);
+        return this.runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
-    /** Run a matched route through its selected execution lane (fused/bare/bodyOnly/queryOnly/lifecycle). */
+    /** Supply request-specific deadline state to the route's precompiled execution plan. */
     runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
         // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
         // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
@@ -1661,62 +1153,10 @@ export class Server {
         const budget = controller === undefined
             ? getUnboundedRequestBudget()
             : createRequestBudget({ deadline: admission.deadline, signal });
-        // A bare route runs synchronously (no schema/derives/hooks); everything else keeps the full async
-        // lifecycle. `runBare` returns a value directly for a sync handler — no promise.
-        let outcome;
-        if (webFast && entry.fusedWeb !== undefined) {
-            // Fused Web lane (bare route, no around): one closure end to end. Sound cast — webFast is
-            // passed only by the `fetch` path, where T = Response by construction.
-            outcome = entry.fusedWeb(source, params, search, signal, budget, platform, false);
-        }
-        else if (entry.contextlessBare) {
-            outcome = this.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
-        }
-        else {
-            // Build the context up front so `onError` always has it. Query, cookies, headers, and body helpers
-            // stay lazy, but their accessors live on the prototype instead of allocating per-request closures.
-            const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
-            // Ledgered routes (capabilities + effectLedger) carry a bounded per-request ledger; the
-            // `useCapability` beacon appends to it, and the settle step below seals + sinks it. The route
-            // was forced off the fused/contextless lanes at registration, so this branch always runs.
-            let ledger;
-            if (entry.ledgered !== undefined) {
-                ledger = createRequestLedger({
-                    method: entry.ledgered.method,
-                    path: entry.ledgered.path,
-                    declared: entry.ledgered.declared,
-                    maxEntries: entry.ledgered.maxEntries,
-                    chain: entry.ledgered.chain,
-                });
-                attachEffectLedger(ctx, ledger);
-            }
-            if (entry.around.length === 0) {
-                outcome = entry.bare
-                    ? this.runBare(entry, ctx, finalize, wrapResponse)
-                    : entry.bodyOnly
-                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
-                        : entry.queryOnly
-                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
-                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse);
-            }
-            else {
-                outcome = this.runWithAround(entry, ctx, () => entry.bare
-                    ? this.runBare(entry, ctx, finalize, wrapResponse)
-                    : entry.bodyOnly
-                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
-                        : entry.queryOnly
-                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
-                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse);
-            }
-            // Settle step: seal the ledger and hand it to the sink BEFORE the response is released, on
-            // success and error responses alike (partial work is exactly what an audit must capture). The
-            // lanes above resolve handler errors to responses, so a plain resolve arm is sufficient.
-            if (ledger !== undefined) {
-                const resolved = entry.ledgered;
-                const active = ledger;
-                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => this.settleEffectLedger(active, resolved, value));
-            }
-        }
+        const plan = entry.execution;
+        const outcome = webFast && plan.fusedWeb !== undefined
+            ? plan.fusedWeb(source, params, search, signal, budget, platform, false)
+            : plan.run(this, entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
         // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
         if (controller !== undefined && outcome instanceof Promise) {
@@ -1727,30 +1167,10 @@ export class Server {
         }
         return outcome;
     }
-    /**
-     * Seal a ledgered request and deliver the sealed ledger to the sink. An empty ledger (declared
-     * capabilities, none exercised) is not delivered — there is nothing to audit. This post-effect
-     * ledger is observational: transactional/durable audit belongs in
-     * the owned effect transaction, so a sink outage must not turn a successful effect into a retryable
-     * 500 that can duplicate it.
-     */
-    async settleEffectLedger(ledger, resolved, value) {
-        const sealed = await ledger.seal();
-        if (sealed.entries.length === 0)
-            return value;
-        try {
-            await resolved.sink(sealed);
-        }
-        catch (err) {
-            // Token-only logging: the route pattern and the failure name — never entry payloads (there are
-            // none) and never the request.
-            this.logger.error("effect ledger sink failed", {
-                method: resolved.method,
-                path: resolved.path,
-                name: err instanceof Error ? err.name : "Error",
-            });
-        }
-        return value;
+    /** @internal Symbol-keyed install seam for the `effectLedger()` plugin. Off the public typed surface. */
+    [INSTALL_EFFECT_LEDGER](runtime) {
+        this.assertConfigurable("effectLedger()");
+        this.effectLedgerRuntime = runtime;
     }
     /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
      * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
@@ -1775,7 +1195,7 @@ export class Server {
         return wrapResponse(jsonError(500, "internal_error"));
     }
     /**
-     * The synchronous fast path for a {@link RouteEntry.bare} route: apply static decorations, call the
+     * The synchronous fast path selected by a route's execution plan: apply static decorations, call the
      * handler, render the result — **no `await`** unless the handler itself returns a promise. It mirrors
      * the bare slice of {@link runLifecycle} (which a bare route would otherwise no-op through) and shares
      * {@link logRequestError}; a bare route has no `onError` hooks, so error handling is fully synchronous
@@ -1801,14 +1221,13 @@ export class Server {
     /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError
      * loop: a thrown `Response` is returned as deliberate control flow; anything else is logged + 500. */
     /**
-     * Build a route's fused Web lane (see {@link RouteEntry.fusedWeb}). Composition happens once at
+     * Build a route's fused Web renderer. Composition happens once at
      * registration; the returned closure is what every request to the route runs. Behavior is
      * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair — same
      * decoration order, same error routing (thrown `Response` = control flow; anything else logs and
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
     buildFusedWeb(handler, decorations, contextless) {
-        const maxBodyBytes = this.maxBodyBytes;
         const logError = (err, ctx) => {
             if (err instanceof Response)
                 return err;
@@ -1826,21 +1245,21 @@ export class Server {
                 }
                 catch (err) {
                     return logError(err, nativeContext
-                        ? RequestContext.native(source, params, maxBodyBytes)
-                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes));
+                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes));
                 }
                 if (result instanceof Promise) {
                     return result.then(fusedRespondNoSet, (err) => logError(err, nativeContext
-                        ? RequestContext.native(source, params, maxBodyBytes)
-                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes)));
+                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)));
                 }
                 return fusedRespondNoSet(result);
             };
         }
         return (source, params, search, signal, budget, platform, nativeContext) => {
             const ctx = nativeContext
-                ? RequestContext.native(source, params, maxBodyBytes)
-                : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes);
+                ? RequestContext.native(source, params, this.maxBodyBytes)
+                : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
             let result;
@@ -2179,8 +1598,18 @@ export class Server {
      */
     async runLifecycle(entry, source, ctx, finalize, wrapResponse) {
         try {
+            if (entry.schema?.params !== undefined) {
+                // Path params arrive as strings from routing; validate (and coerce) them at the boundary, before
+                // the body/query, so a malformed `:id` is a 422 before any work runs. Raw `.validate` (no wrapper
+                // alloc), same recovery-hook path as body/query.
+                const validation = entry.schema.params["~standard"].validate(ctx.params);
+                const result = validation instanceof Promise ? await validation : validation;
+                const paramsError = await this.applyLifecycleValidation(entry, result, ctx, "params");
+                if (paramsError !== undefined)
+                    return wrapResponse(paramsError);
+            }
             if (entry.schema?.body !== undefined) {
-                const bodyError = await this.readAndValidateBody(source, entry.schema.body, ctx);
+                const bodyError = await this.readAndValidateBody(source, entry, ctx);
                 if (bodyError !== undefined)
                     return wrapResponse(bodyError);
             }
@@ -2190,9 +1619,9 @@ export class Server {
                 // validateStandard wrapper alloc.
                 const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
                 const result = validation instanceof Promise ? await validation : validation;
-                if (result.issues !== undefined)
-                    return wrapResponse(validationError(result.issues));
-                ctx.query = result.value;
+                const queryError = await this.applyLifecycleValidation(entry, result, ctx, "query");
+                if (queryError !== undefined)
+                    return wrapResponse(queryError);
             }
             // Context extensions: static decorations, then per-request derives.
             // Each hook below only awaits when it actually returns a Promise — a sync hook
@@ -2262,7 +1691,7 @@ export class Server {
             stack: err instanceof Error ? err.stack : undefined,
         });
     }
-    async readAndValidateBody(req, schema, ctx) {
+    async readAndValidateBody(req, entry, ctx) {
         const contentType = headerOf(req, "content-type") ?? "";
         let parsed;
         if (contentType === "application/json" || contentType.includes("application/json")) {
@@ -2282,11 +1711,44 @@ export class Server {
             // fit a value schema; use a schema-less route + @nifrajs/uploads helpers for those.
             return jsonError(415, "unsupported_media_type");
         }
-        const validation = schema["~standard"].validate(parsed);
+        const validation = entry.schema.body["~standard"].validate(parsed);
         const result = validation instanceof Promise ? await validation : validation;
-        if (result.issues !== undefined)
+        return this.applyLifecycleValidation(entry, result, ctx, "body");
+    }
+    /** Apply validation and its recovery hook on the generic lifecycle lane. Recovery is completed
+     * before derives/beforeHandle run, matching the body-only and query-only execution lanes. */
+    async applyLifecycleValidation(entry, result, ctx, kind) {
+        const assign = (value) => {
+            if (kind === "body")
+                ctx.body = value;
+            else if (kind === "query")
+                ctx.query = value;
+            else
+                ctx.params = value;
+        };
+        if (result.issues === undefined) {
+            assign(result.value);
+            return undefined;
+        }
+        const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError;
+        if (hook === undefined)
             return validationError(result.issues);
-        ctx.body = result.value;
+        const attempted = hook(result.issues, ctx, kind);
+        const recovery = attempted instanceof Promise ? await attempted : attempted;
+        if (recovery === undefined)
+            return validationError(result.issues);
+        if (recovery instanceof Response)
+            return recovery;
+        const schema = kind === "body"
+            ? entry.schema?.body
+            : kind === "query"
+                ? entry.schema?.query
+                : entry.schema?.params;
+        const retried = schema["~standard"].validate(recovery);
+        const settled = retried instanceof Promise ? await retried : retried;
+        if (settled.issues !== undefined)
+            return validationError(settled.issues);
+        assign(settled.value);
         return undefined;
     }
     /**
@@ -2306,13 +1768,61 @@ export class Server {
     async readBoundedJson(req) {
         return readBoundedJsonSource(req, this.maxBodyBytes);
     }
+    /** 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) {
+        if (paramNames.length === 0) {
+            if (fused === undefined) {
+                return (request) => this.fetchMatched(request, entry, EMPTY_PARAMS);
+            }
+            if (this.acceptInboundDeadlines) {
+                return (request) => request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                    ? this.fetchMatched(request, entry, EMPTY_PARAMS)
+                    : fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+            }
+            return (request) => fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+        }
+        const malformed = paramNames.length === 1
+            ? (params) => params[paramNames[0]]?.includes("\uFFFD") === true
+            : hasReplacementParam;
+        if (fused === undefined) {
+            return (request) => {
+                const params = request.params ?? EMPTY_PARAMS;
+                if (malformed(params))
+                    return this.fetchSource(request);
+                return this.fetchMatched(request, entry, params);
+            };
+        }
+        if (this.acceptInboundDeadlines) {
+            return (request) => {
+                const params = request.params ?? EMPTY_PARAMS;
+                if (malformed(params))
+                    return this.fetchSource(request);
+                return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                    ? this.fetchMatched(request, entry, params)
+                    : fused(request, params, undefined, signal, budget, undefined, true);
+            };
+        }
+        return (request) => {
+            const params = request.params ?? EMPTY_PARAMS;
+            if (malformed(params))
+                return this.fetchSource(request);
+            return fused(request, params, undefined, signal, budget, undefined, true);
+        };
+    }
     /** 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() {
-        if (this.onRequestHooks.length > 0 || this.wsRouteCount > 0)
+        // 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 ||
+            this.wsRouteCount > 0 ||
+            this.clientIpTrust !== undefined) {
             return undefined;
+        }
         const routes = Object.create(null);
         const mayUseFusedNative = this.requestTimeoutMs === 0 &&
             this.onResponseHooks.length === 0 &&
@@ -2323,119 +1833,17 @@ export class Server {
         const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined;
         const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined;
         let count = 0;
-        for (const { method, path, entry } of this.rawEntries) {
-            if (path.includes("*"))
+        for (const { method, path, pattern, entry } of this.catalog.entries()) {
+            if (pattern.segments.some((segment) => segment.kind === "wildcard"))
                 continue;
             let methods = routes[path];
             if (methods === undefined) {
                 methods = Object.create(null);
                 routes[path] = methods;
             }
-            const paramNames = path
-                .split("/")
-                .filter((segment) => segment.charCodeAt(0) === 58 /* : */)
-                .map((segment) => segment.slice(1));
-            const fused = mayUseFusedNative ? entry.fusedWeb : undefined;
-            if (fused !== undefined) {
-                // Deliberately choose deadline-aware vs zero-admission closures HERE instead of branching on
-                // `acceptInboundDeadlines` per request. JSC can then flatten the default closure through the
-                // handler + Response.json; retaining that route-invariant branch cost ~7% on a dynamic GET.
-                if (paramNames.length === 0) {
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                            ? this.fetchMatched(request, entry, EMPTY_PARAMS)
-                            : fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true)
-                        : (request) => fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                }
-                else if (paramNames.length === 1) {
-                    const paramName = paramNames[0];
-                    const handler = entry.handler;
-                    const decorations = entry.hasDecorations ? entry.decorations : undefined;
-                    const fail = (error, ctx) => {
-                        if (error instanceof Response)
-                            return error;
-                        this.logRequestError(error, ctx);
-                        return jsonError(500, "internal_error");
-                    };
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (params[paramName]?.includes("\uFFFD") === true)
-                                return this.fetchSource(request);
-                            if (request.headers.get(NIFRA_DEADLINE_HEADER) !== null) {
-                                return this.fetchMatched(request, entry, params);
-                            }
-                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
-                            if (decorations !== undefined)
-                                Object.assign(ctx, decorations);
-                            let result;
-                            try {
-                                result = handler(ctx);
-                            }
-                            catch (error) {
-                                return fail(error, ctx);
-                            }
-                            return result instanceof Promise
-                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
-                                : fusedRespond(result, ctx);
-                        }
-                        : (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (params[paramName]?.includes("\uFFFD") === true)
-                                return this.fetchSource(request);
-                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
-                            if (decorations !== undefined)
-                                Object.assign(ctx, decorations);
-                            let result;
-                            try {
-                                result = handler(ctx);
-                            }
-                            catch (error) {
-                                return fail(error, ctx);
-                            }
-                            return result instanceof Promise
-                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
-                                : fusedRespond(result, ctx);
-                        };
-                }
-                else {
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (hasReplacementParam(params))
-                                return this.fetchSource(request);
-                            return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                                ? this.fetchMatched(request, entry, params)
-                                : fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                        }
-                        : (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (hasReplacementParam(params))
-                                return this.fetchSource(request);
-                            return fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                        };
-                }
-            }
-            else if (paramNames.length === 0) {
-                methods[method] = (request) => this.fetchMatched(request, entry, EMPTY_PARAMS);
-            }
-            else if (paramNames.length === 1) {
-                const paramName = paramNames[0];
-                methods[method] = (request) => {
-                    const params = request.params ?? EMPTY_PARAMS;
-                    if (params[paramName]?.includes("\uFFFD") === true)
-                        return this.fetchSource(request);
-                    return this.fetchMatched(request, entry, params);
-                };
-            }
-            else {
-                methods[method] = (request) => {
-                    const params = request.params ?? EMPTY_PARAMS;
-                    if (hasReplacementParam(params))
-                        return this.fetchSource(request);
-                    return this.fetchMatched(request, entry, params);
-                };
-            }
+            const paramNames = pattern.paramNames;
+            const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined;
+            methods[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget);
             count += 1;
         }
         return count === 0 ? undefined : routes;
@@ -2471,11 +1879,11 @@ export class Server {
         // `server` 2nd arg is how Bun exposes `upgrade`); otherwise the lean request-only fetch. The
         // `websocket` handlers are one shared dispatcher — each connection's `ws.data.handler` is the
         // matched route's handler, set by `server.upgrade`.
-        // With WS routes, the dispatcher comes from the `@nifrajs/core/ws` runtime — non-null because
-        // wsRouteCount > 0 means ws() ran, and ws() requires the runtime at registration.
+        // With WS routes, the dispatcher comes from the installed `.use(websocket())` runtime — non-null
+        // because wsRouteCount > 0 means ws() ran, and ws() requires the runtime at registration.
         const wsHandlers = this.wsRouteCount === 0
             ? undefined
-            : getWsRuntime().bunHandlers(this.topics);
+            : this.wsRuntime.bunHandlers(this.topics);
         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.
@@ -2487,7 +1895,7 @@ export class Server {
                 reusePort,
                 ...bind,
                 ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
-                fetch: (req) => this.fetch(req),
+                fetch: (req, server) => this.fetch(req, bunPeerPlatform(server, req)),
             })
             : Bun.serve({
                 port,
@@ -2507,6 +1915,7 @@ export class Server {
                 },
             }));
         this.bunServer = running;
+        this.sealed = true;
         if (this.gracefulSignals)
             this.installSignalHandlers();
         return running;
@@ -2585,7 +1994,9 @@ export function toFetchHandler(app, options) {
                     const pair = new Pair();
                     const server = pair[1];
                     server.accept();
-                    getWsRuntime().attach(server, outcome.handler, outcome.data, {
+                    // The outcome carries the installed runtime's `attach`, so `toFetchHandler` (a standalone
+                    // function, no access to the app's private runtime) wires the socket without a static WS import.
+                    outcome.attach(server, outcome.handler, outcome.data, {
                         openNow: true,
                         pubsub: outcome.pubsub,
                     });