@nifrajs/core 1.13.0 → 2.0.0

package/dist/server/server.js

@@ -1,41 +1,20 @@
 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");
-}
-/** 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(() => { });
-};
 /**
  * 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
@@ -87,94 +66,38 @@ class RouteCatalog {
         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 };
+}
 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). */
@@ -193,135 +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;
-}
+// `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"))
@@ -329,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;
 }
@@ -371,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,
@@ -687,6 +165,8 @@ export class Server {
     maxBodyBytes;
     wsMaxPayloadBytes;
     requestTimeoutMs;
+    /** Opt-in caller-IP trust declaration; `undefined` = socket peer only, no forwarded header believed. */
+    clientIpTrust;
     acceptInboundDeadlines;
     maxInboundDeadlineMs;
     deadlineAdmissionOptions;
@@ -694,11 +174,20 @@ 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;
@@ -731,6 +220,7 @@ export class Server {
         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({
@@ -746,26 +236,12 @@ 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;
@@ -916,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)
@@ -930,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) {
@@ -946,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.catalog.lastDescriptor();
         if (lastRoute) {
             ;
-            lastRoute.tool = {
-                name,
-                description: config.description,
-                ...(config.annotations !== undefined ? { annotations: config.annotations } : {}),
-            };
+            lastRoute.tool = plan.descriptor;
         }
         return this;
     }
@@ -975,13 +442,7 @@ export class Server {
      */
     resource(uri, config, read) {
         this.assertConfigurable("resource()");
-        this.mcpResourceList.push({
-            uri,
-            name: config.name,
-            ...(config.description !== undefined ? { description: config.description } : {}),
-            ...(config.mimeType !== undefined ? { mimeType: config.mimeType } : {}),
-            read,
-        });
+        this.mcpResourceList.push(requireMcpRuntime(this.mcpRuntime).resource(uri, config, read));
         return this;
     }
     /**
@@ -990,12 +451,7 @@ export class Server {
      */
     prompt(name, config, handler) {
         this.assertConfigurable("prompt()");
-        this.mcpPromptList.push({
-            name,
-            description: config.description,
-            ...(config.arguments !== undefined ? { arguments: config.arguments } : {}),
-            handler,
-        });
+        this.mcpPromptList.push(requireMcpRuntime(this.mcpRuntime).prompt(name, config, handler));
         return this;
     }
     /** The MCP resources declared via {@link resource} — enumerated by `nifra mcp`. */
@@ -1013,13 +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.
@@ -1086,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 &&
@@ -1110,6 +576,7 @@ export class Server {
             ? "bare"
             : schema?.body !== undefined &&
                 schema.query === undefined &&
+                schema.params === undefined &&
                 this.derives.length === 0 &&
                 this.beforeHandleHooks.length === 0 &&
                 this.afterHandleHooks.length === 0 &&
@@ -1117,6 +584,7 @@ export class Server {
                 ? "body"
                 : schema?.body === undefined &&
                     schema?.query !== undefined &&
+                    schema.params === undefined &&
                     this.derives.length === 0 &&
                     this.beforeHandleHooks.length === 0 &&
                     this.afterHandleHooks.length === 0 &&
@@ -1145,8 +613,18 @@ export class Server {
             path,
             schema,
             ...(capabilities.length > 0 ? { capabilities } : {}),
+            ...(schema?.family === true ? { family: true } : {}),
         };
         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,
@@ -1199,78 +677,52 @@ export class Server {
         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;
-            if (hasLedger) {
+            // 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 = createRequestLedger({
-                    method: resolved.method,
-                    path: resolved.path,
-                    declared: resolved.declared,
-                    maxEntries: resolved.maxEntries,
-                    chain: resolved.chain,
-                });
-                attachEffectLedger(ctx, ledger);
+                ledger = ledgerRuntime.create(resolved);
+                ledgerRuntime.attach(ctx, ledger);
             }
             let outcome = execute(runtime, entry, source, ctx, finalize, wrapResponse);
-            if (ledger !== undefined) {
+            if (ledger !== undefined && ledgerRuntime !== undefined) {
                 const active = ledger;
                 const resolved = entry.ledgered;
-                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => runtime.settleEffectLedger(active, resolved, value));
+                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 });
     }
-    /** 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 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;
     }
-    /** 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;
+    /** @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.
@@ -1298,6 +750,17 @@ export class Server {
             throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes — register .ws() routes on the parent server");
         }
         this.catalog.addBatch(source.catalog.entries().map((route) => this.bindFusedRuntime(route)));
+        // 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);
@@ -1434,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 ||
@@ -1448,7 +911,11 @@ export class Server {
         // 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
@@ -1473,8 +940,9 @@ export class Server {
         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`.
@@ -1494,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
@@ -1520,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 } })
@@ -1537,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
@@ -1632,113 +1110,14 @@ 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);
     }
     /** Supply request-specific deadline state to the route's precompiled execution plan. */
     runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
@@ -1788,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. */
@@ -2239,6 +1598,16 @@ 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, ctx);
                 if (bodyError !== undefined)
@@ -2349,11 +1718,16 @@ export class Server {
     /** Apply validation and its recovery hook on the generic lifecycle lane. Recovery is completed
      * before derives/beforeHandle run, matching the body-only and query-only execution lanes. */
     async applyLifecycleValidation(entry, result, ctx, kind) {
-        if (result.issues === undefined) {
+        const assign = (value) => {
             if (kind === "body")
-                ctx.body = result.value;
+                ctx.body = value;
+            else if (kind === "query")
+                ctx.query = value;
             else
-                ctx.query = result.value;
+                ctx.params = value;
+        };
+        if (result.issues === undefined) {
+            assign(result.value);
             return undefined;
         }
         const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError;
@@ -2365,15 +1739,16 @@ export class Server {
             return validationError(result.issues);
         if (recovery instanceof Response)
             return recovery;
-        const schema = kind === "body" ? entry.schema?.body : entry.schema?.query;
+        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);
-        if (kind === "body")
-            ctx.body = settled.value;
-        else
-            ctx.query = settled.value;
+        assign(settled.value);
         return undefined;
     }
     /**
@@ -2440,8 +1815,14 @@ export class Server {
      * 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 &&
@@ -2498,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.
@@ -2514,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,
@@ -2613,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,
                     });