@nifrajs/core 1.12.0 → 2.0.0

package/src/server/server.ts

@@ -7,19 +7,6 @@ import {
   type RequestBudget,
 } from "../budget.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
-import {
-  canonicalizeIdempotencyBody,
-  computeIdempotencyFingerprint,
-  DEFAULT_IDEMPOTENCY_HEADER,
-  DEFAULT_IDEMPOTENCY_TTL_MS,
-  IdempotencyResponseTooLargeError,
-  type IdempotencyStore,
-  MemoryIdempotencyStore,
-  responseFromStored,
-  serializeResponse,
-  validIdempotencyKey,
-  validIdempotencyNamespace,
-} from "../idempotency.ts"
 import {
   CAPABILITY_GUARD,
   type CapabilityUseEvent,
@@ -28,31 +15,91 @@ import {
 } from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
-  type AssuranceEvidence,
   assuranceDeclarationsOf,
   assuranceEvidenceFor,
   NIFRA_ASSURANCE_IDS,
+  validEvidenceId,
 } from "../internal/route-assurance.ts"
+import type { RequestLedger } from "../ledger.ts"
 import {
-  attachEffectLedger,
-  createRequestLedger,
-  DEFAULT_MAX_ENTRIES,
-  type EffectLedgerOptions,
-  type RequestLedger,
-} from "../ledger.ts"
-import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
+  type CompiledRoutePattern,
+  compileRoutePattern,
+  decodeRouteParams,
+} from "../router/pattern.ts"
+import { EMPTY_PARAMS, type Method, Router, type RouterMatch } from "../router/router.ts"
 import type {
   InferOutput,
   StandardIssue,
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import { drainCapped, parseContentLength, readBoundedBytes } from "./body.ts"
+import { parseContentLength } from "./body.ts"
+import { type ClientIpTrust, resolveClientIp } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
-import { type CookieOptions, parseCookies, serializeCookie } from "./cookies.ts"
+import { jsonError, pathnameOf, urlPartsOf } from "./http.ts"
+import type { NodeServeOutcome } from "./node-outcome.ts"
+import type { NodeOutcomeRuntime } from "./node-outcome-hook.ts"
+import {
+  isUrlEncodedForm,
+  type QueryValue,
+  queryObjectOf,
+  readBoundedForm,
+  searchOf,
+} from "./query.ts"
+import { RequestContext, readBoundedJsonSource } from "./request-context.ts"
+import { fusedRespond, fusedRespondNoSet, toResponse } from "./respond.ts"
+import {
+  CONTEXT_SEARCH,
+  CONTEXT_SET,
+  EMPTY_RESPONSE_CONTROLS,
+  getNeverAbortSignal,
+  getUnboundedRequestBudget,
+  type HandlerResult,
+  headerOf,
+  requestOf,
+} from "./runtime-core.ts"
+
+// NodeServeOutcome (the nifra<->node bridge render form) now lives in `./node-outcome.ts`; re-exported
+// so existing importers keep resolving it from the server module.
+export type { NodeServeOutcome }
+
+import type { IdempotencyRuntime, ResolvedIdempotency } from "./idempotency-lane.ts"
+import {
+  INSTALL_EFFECT_LEDGER,
+  INSTALL_IDEMPOTENCY,
+  INSTALL_MCP,
+  INSTALL_NODE_DIRECT,
+  INSTALL_SSE,
+  INSTALL_WS,
+} from "./install.ts"
+import type { EffectLedgerRuntime, ResolvedEffectLedger } from "./ledger-lane.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
-import type { AddRoute, EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.ts"
-import { type SSEInit, sse, type TypedSSEStream, typedSSEStream } from "./sse.ts"
+import type { McpRuntime } from "./mcp-hook.ts"
+import type { IdentityPlugin } from "./plugin.ts"
+import type {
+  AddRoute,
+  EmptyRegistry,
+  OutputOf,
+  Registry,
+  RouteInfoFor,
+  WsRouteInfoFor,
+} from "./registry.ts"
+import type {
+  AdmissionController,
+  AdmissionDecision,
+  McpPromptDescriptor,
+  McpResourceDescriptor,
+  Middleware,
+  PromptArgument,
+  PromptMessage,
+  ResponseFinalization,
+  RouteDescriptor,
+  RunningServer,
+  ServerOptions,
+  ToolAnnotations,
+} from "./server-types.ts"
+import type { SSEInit, TypedSSEStream } from "./sse.ts"
+import type { SseRuntime } from "./sse-hook.ts"
 import type {
   StandardWebSocket,
   TopicRegistry,
@@ -61,9 +108,9 @@ import type {
   WebSocketUpgradeOutcome,
 } from "./websocket.ts"
 import type { BunWsData } from "./ws-bun.ts"
-import { getWsRuntime, type WsRuntime } from "./ws-hook.ts"
+import type { WsRuntime } from "./ws-hook.ts"
 
-type MaybePromise<T> = T | Promise<T>
+export type MaybePromise<T> = T | Promise<T>
 
 /**
  * Internal request view. A real Web `Request` already satisfies this shape, so Web/edge runtimes pass
@@ -85,17 +132,6 @@ export interface RequestSource {
   readonly request?: Request
 }
 
-/** 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: RequestSource): Request {
-  return source.request ?? (source as unknown as Request)
-}
-
-function headerOf(source: RequestSource, name: string): string | null {
-  return source.header?.(name) ?? source.headers.get(name)
-}
-
 /** The empty context extension. `NonNullable<unknown>` is `{}` without tripping noBannedTypes. */
 type EmptyContext = NonNullable<unknown>
 
@@ -106,42 +142,20 @@ type EmptyContext = NonNullable<unknown>
  */
 type EnvOf<Ctx> = Ctx extends { readonly env: infer E } ? E : unknown
 
-/** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
-type HandlerResult = Response | unknown
 type ContextlessHandler = () => MaybePromise<HandlerResult>
 
-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]*?)?=>/
 
-interface ResponseResult {
-  readonly [RESPONSE_RESULT]: true
-  toResponse(): Response
-  toNodeBody?(): {
-    readonly status: number
-    readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
-    readonly body: string | Uint8Array
-  }
-}
-
-function isResponseResult(value: unknown): value is ResponseResult {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as { readonly [RESPONSE_RESULT]?: unknown })[RESPONSE_RESULT] === true &&
-    typeof (value as { readonly toResponse?: unknown }).toResponse === "function"
-  )
-}
-
 /** Internal, path-erased runtime context. The typed `Context<Path, S>` is a structural view of this. */
-interface RawContext {
+export interface RawContext {
   readonly req: Request
   readonly request: Request
   readonly json: (body: unknown, init?: ResponseInit | number) => Response
   readonly text: (body: string, init?: ResponseInit | number) => Response
-  readonly params: Record<string, string>
+  // Writable: the lifecycle replaces it with the validated/coerced value when a `params` schema is
+  // declared (handlers still see it `readonly` via the public `Context` interface).
+  params: Record<string, string>
   query: unknown
   readonly cookies: Readonly<Record<string, string>>
   body: unknown
@@ -151,17 +165,12 @@ interface RawContext {
   readonly signal: AbortSignal
   readonly budget: RequestBudget
   readonly env: unknown
+  readonly clientIp: string | undefined
   readonly waitUntil: (promise: Promise<unknown>) => void
   readonly boundedBody: (maxBytes?: number) => Promise<Uint8Array>
   readonly boundedJson: <T = unknown>(maxBytes?: number) => Promise<T>
 }
 
-/** 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: Promise<unknown>): void => {
-  void promise.catch(() => {})
-}
-
 type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
 
 /** Broad shape so the implementation signature is compatible with both typed overloads. */
@@ -178,25 +187,33 @@ type RawOnRequest = (req: Request, platform?: Platform) => MaybePromise<OnReques
 type RawOnResponse = (response: Response, req: Request) => MaybePromise<Response>
 type RawOnResponseFinalized = (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
 
-/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
-interface ResolvedIdempotency {
-  readonly store: IdempotencyStore
-  readonly ttlMs: number
-  readonly headerName: string
-  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
-  readonly maxResponseBytes: number
-}
+type RouteExecutionRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  params: Record<string, string>,
+  search: string | undefined,
+  signal: AbortSignal,
+  budget: RequestBudget,
+  platform: Platform | undefined,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
 
-/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
-interface ResolvedEffectLedger {
-  readonly sink: EffectLedgerOptions["sink"]
-  readonly maxEntries: number
-  readonly chain: boolean
-  /** The registered route pattern — what the sealed ledger names (never the concrete URL). */
-  readonly method: string
-  readonly path: string
-  /** The route's declared capability tokens, surfaced on the sealed ledger. */
-  readonly declared: readonly string[]
+type ContextRouteRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
+
+/** Registration-compiled route behavior. Every adapter invokes the same runner; the optional fused
+ * renderer is only a response-format specialization of that same selected route semantics. */
+interface RouteExecutionPlan {
+  readonly run: RouteExecutionRunner
+  readonly fusedWeb: FusedWebRunner | undefined
 }
 
 interface RouteEntry {
@@ -219,33 +236,75 @@ interface RouteEntry {
   readonly onError: ReadonlyArray<RawErrorHandler>
   /** Wraps the matched route lifecycle. Empty for the common no-around path. */
   readonly around: ReadonlyArray<RawAround>
-  /**
-   * Precomputed: the route has no body/query schema and no derive/beforeHandle/afterHandle/onError
-   * hooks — so its lifecycle reduces to `finalize(handler(ctx), set)` with simple error handling, no
-   * `await` unless the handler itself is async. Such routes take the **synchronous fast path**
-   * ({@link Server.runBare}), which skips the `async` machinery of the full {@link Server.runLifecycle}
-   * (≈2 promise frames/req — the per-request tax codegen routers avoid; nifra avoids it here without
-   * `eval`, so it stays edge-safe). Static decorations are still applied (they're a sync `Object.assign`).
-   */
-  readonly bare: boolean
-  /**
-   * A narrower bare-route path for syntactic zero-parameter arrow handlers (`() => ...`). Unlike
-   * `handler.length === 0`, this intentionally excludes `function () { arguments }`, rest params,
-   * default params, bound/native functions, and anything else that can observe the passed context.
-   */
-  readonly contextlessBare: boolean
-  /** Precomputed body-schema-only path: JSON body validation + handler, no other lifecycle hooks. */
-  readonly bodyOnly: boolean
-  /** Precomputed query-schema-only path: query validation + handler, no other lifecycle hooks. */
-  readonly queryOnly: boolean
-  /**
-   * Registration-time-fused Web lane for a {@link bare} route with no `around` hooks: context (when
-   * the handler can observe one), handler, and the JSON respond collapsed into ONE monomorphic
-   * closure — no per-request branch ladder, no `responseSet` lookup, no codegen (`new Function`
-   * measured equivalent to closures on JSC). Only the Web finalizer
-   * (`fetch`) uses it — the node-direct path keeps the generic lifecycle.
-   */
-  readonly fusedWeb: FusedWebRunner | undefined
+  /** The single immutable execution decision consumed by portable, Node-direct, and Bun-native paths. */
+  readonly execution: RouteExecutionPlan
+}
+
+/** One canonical runtime route fact. The catalog owns matching, reflection, assurance, tool metadata,
+ * replay, and native compilation input so batch registration has one commit point. */
+interface CatalogRoute {
+  readonly method: Method
+  readonly path: string
+  readonly pattern: CompiledRoutePattern
+  readonly entry: RouteEntry
+  readonly descriptor: RouteDescriptor
+  readonly assurance: readonly AssuranceDeclaration[]
+}
+
+/**
+ * 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 {
+  private matcher = new Router<RouteEntry>()
+  private records: CatalogRoute[] = []
+  /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
+  private descriptors: RouteDescriptor[] = []
+  private assurancePresent = false
+
+  add(route: CatalogRoute): void {
+    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: readonly CatalogRoute[]): void {
+    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<RouteEntry>()
+    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: string, path: string): RouterMatch<RouteEntry> {
+    return this.matcher.find(method, path)
+  }
+
+  entries(): readonly CatalogRoute[] {
+    return this.records
+  }
+
+  routeDescriptors(): ReadonlyArray<RouteDescriptor> {
+    return this.descriptors
+  }
+
+  lastDescriptor(): RouteDescriptor | undefined {
+    return this.records[this.records.length - 1]?.descriptor
+  }
+
+  hasAssurance(): boolean {
+    return this.assurancePresent
+  }
 }
 
 /** The fused Web lane: same inputs `routeAndRun` would hand the generic path, a `Response` out. */
@@ -264,9 +323,20 @@ interface WsEntry {
   readonly handler: WebSocketHandler
 }
 
-/** Structural view of the Bun `Server` `upgrade` the `fetch` 2nd arg exposes. */
+/** Structural view of the Bun `Server` the `fetch` 2nd arg exposes (`upgrade` + the socket peer). */
 interface BunUpgradeServer {
   upgrade(request: Request, options?: { data?: BunWsData }): boolean
+  requestIP(request: Request): { readonly address: string } | null
+}
+
+/** 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: { requestIP(request: Request): { readonly address: string } | null },
+  req: Request,
+): Platform | undefined {
+  const address = server.requestIP(req)?.address
+  return address === undefined ? undefined : { clientIp: address }
 }
 
 type BunNativeHandler = (request: Request) => MaybePromise<Response>
@@ -277,12 +347,31 @@ type BunRequestWithParams = Request & { readonly params?: Record<string, string>
 const WS_PASS: WebSocketUpgradeOutcome = { kind: "pass" }
 
 /** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
-function requireWsRuntime(): WsRuntime {
-  const runtime = getWsRuntime()
+function requireWsRuntime(runtime: WsRuntime | undefined): WsRuntime {
   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.',
+      "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
+}
+
+function requireSseRuntime(runtime: SseRuntime | undefined): SseRuntime {
+  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
+}
+
+function requireMcpRuntime(runtime: McpRuntime | undefined): McpRuntime {
+  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
@@ -305,202 +394,21 @@ export type Handler<
   Ctx = EmptyContext,
 > = (ctx: Context<Path, S> & Ctx) => MaybePromise<ResponseOf<S>>
 
-/**
- * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
- * exactly once when the response is finalized; a shed request carries a ready `429` Response.
- */
-export type AdmissionDecision =
-  | { readonly admitted: true; release(): void }
-  | { readonly admitted: false; readonly response: Response }
-
-/**
- * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now —
- * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
- * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
- *
- * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
- * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
- * is untouched.
- */
-export interface AdmissionController {
-  admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>
-}
-
-export interface ServerOptions {
-  /**
-   * Max request body size (bytes), enforced **only when a route declares a body schema** — the cap
-   * lives in the schema-validated read path. Default 1_000_000.
-   *
-   * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly
-   * is not auto-bounded — use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which
-   * apply this same cap (override per route by passing `maxBytes` — larger for an upload endpoint,
-   * smaller to tighten one).
-   */
-  readonly maxBodyBytes?: number
-  /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun — frames over this are rejected
-   * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
-   * Default: `maxBodyBytes` (1 MB). */
-  readonly wsMaxPayloadBytes?: number
-  /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
-  readonly requestTimeoutMs?: number
-  /**
-   * Admit the public `x-nifra-deadline` header and let it shorten local work. Disabled by default:
-   * services that participate in trusted cross-service deadline propagation opt in explicitly,
-   * while ordinary/public HTTP routes pay no header-admission tax and ignore hostile client values.
-   */
-  readonly acceptInboundDeadlines?: boolean
-  /**
-   * Maximum time accepted from an inbound `x-nifra-deadline`, in milliseconds. An incoming absolute
-   * deadline may shorten this cap (and `requestTimeoutMs`, when configured), never extend it.
-   * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
-   */
-  readonly maxInboundDeadlineMs?: number
-  /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
-  readonly gracefulSignals?: boolean
-  /**
-   * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
-   * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
-   * Off by default. Enabling it disables the fused native-route fast path (requests route through the
-   * shared matched lane where the gate runs); when unset, the request path pays nothing.
-   */
-  readonly admission?: AdmissionController
-  /**
-   * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
-   * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
-   */
-  readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
-  /**
-   * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a
-   * bounded, token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink
-   * receives the sealed ledger when the response settles (only when it recorded entries). Token-only
-   * by construction — capability ids, phases, counters, digests; never payloads, values, or the
-   * concrete URL (the route *pattern* is recorded). Enabling it moves capability-declaring routes off
-   * the fused fast path (they need a per-request context + a settle step); all other routes are
-   * unaffected, and when unset the request path pays nothing.
-   */
-  readonly effectLedger?: EffectLedgerOptions
-  /**
-   * Default store backing routes that declare `schema.idempotency` without their own `store`. Defaults
-   * to a shared in-process {@link MemoryIdempotencyStore} (created lazily on first idempotent route).
-   * Inject a durable store here to make request-scoped dedupe survive restarts app-wide.
-   */
-  readonly idempotencyStore?: IdempotencyStore
-  /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
-  readonly logger?: Logger
-  /**
-   * App-wide fallback fired when a route **without its own `onValidationError`** fails body/query
-   * validation. Same contract as the per-route hook (`(issues, ctx, kind) => Response | repaired-value |
-   * undefined`): a route's own hook takes precedence, and a route can fall through to the plain `422` by
-   * returning `undefined`. Use it for one app-wide error envelope (like tRPC's `errorFormatter` /
-   * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
-   */
-  readonly onValidationError?: RouteSchema["onValidationError"]
-}
-
-/**
- * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is — so it
- * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors
- * the MCP spec's tool `annotations`.
- */
-export interface ToolAnnotations {
-  /** Human-readable display title for the tool, distinct from the machine `name`. */
-  readonly title?: string
-  /** The tool does not modify its environment (a pure read). */
-  readonly readOnlyHint?: boolean
-  /** The tool may perform destructive updates — only meaningful when `readOnlyHint` is not `true`. */
-  readonly destructiveHint?: boolean
-  /** Repeated calls with the same arguments have no additional effect beyond the first. */
-  readonly idempotentHint?: boolean
-  /** The tool interacts with external entities (an "open world" beyond this server). */
-  readonly openWorldHint?: boolean
-}
-
-/**
- * A registered route's public descriptor — method, path, and input schemas. The
- * router trie discards the original patterns, so this flat list is what lets tools
- * (e.g. `toOpenAPI`) enumerate routes after registration.
- */
-export interface RouteDescriptor {
-  readonly method: Method
-  readonly path: string
-  readonly schema: RouteSchema | undefined
-  /** Effective enforcement evidence, populated only during reflection/introspection. */
-  readonly assurance?: readonly AssuranceEvidence[]
-  /** Normalized declared effect tokens, populated only when the route declares any. */
-  readonly capabilities?: readonly string[]
-  readonly tool?: {
-    readonly name: string
-    readonly description: string
-    readonly annotations?: ToolAnnotations
-  }
-}
-
-/** A message in an MCP prompt's rendered output (see {@link Server.prompt}). */
-export interface PromptMessage {
-  readonly role: "user" | "assistant"
-  readonly content: { readonly type: "text"; readonly text: string }
-}
-
-/** One declared argument of an MCP prompt, surfaced in `prompts/list`. */
-export interface PromptArgument {
-  readonly name: string
-  readonly description?: string
-  readonly required?: boolean
-}
-
-/** An app-declared MCP resource — read-only data an agent can fetch through `nifra mcp`. */
-export interface McpResourceDescriptor {
-  readonly uri: string
-  readonly name: string
-  readonly description?: string
-  readonly mimeType?: string
-  readonly read: () => MaybePromise<string | { readonly text: string; readonly mimeType?: string }>
-}
-
-/** An app-declared MCP prompt — a reusable prompt template an agent can fetch through `nifra mcp`. */
-export interface McpPromptDescriptor {
-  readonly name: string
-  readonly description: string
-  readonly arguments?: readonly PromptArgument[]
-  readonly handler: (args: Record<string, string>) => MaybePromise<readonly PromptMessage[]>
-}
-
-/**
- * The handle `listen()` returns — the slice of Bun's server nifra holds and exposes.
- * Declared explicitly (rather than `ReturnType<typeof Bun.serve>`) so the public type
- * surface doesn't leak the ambient `Bun` global into consumers' `.d.ts` resolution.
- */
-export interface RunningServer {
-  readonly port: number
-  readonly hostname: string
-  readonly pendingRequests: number
-  stop(closeActiveConnections?: boolean): void
-}
-
-/**
- * A bundle of lifecycle hooks applied together via {@link Server.use} — the unit
- * `@nifrajs/middleware` ships (cors, security headers, rate-limit). Every hook is
- * optional and wired to its lifecycle point. Middleware is context-agnostic (sees
- * the base `Context`); `use` does no context-type merging — the full type-merging
- * plugin system is deferred, and `.use` is reserved as its future entry point.
- */
-export interface Middleware {
-  readonly name?: string
-  readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
-  readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>
-  readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
-  readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
-  readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>
-  readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
-  readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>
-}
-
-/** The terminal response-pipeline outcome observed after every transforming `onResponse` hook. */
-export interface ResponseFinalization {
-  /** The final response, or the last response available when a transformation failed. */
-  readonly response: Response
-  /** A response-hook failure. Terminal observers run fail-open before the error is rethrown. */
-  readonly error?: unknown
+// Route/option/descriptor + middleware-bundle types now live in `./server-types.ts`; re-exported so
+// existing importers keep resolving them from the server module.
+export type {
+  AdmissionController,
+  AdmissionDecision,
+  McpPromptDescriptor,
+  McpResourceDescriptor,
+  Middleware,
+  PromptArgument,
+  PromptMessage,
+  ResponseFinalization,
+  RouteDescriptor,
+  RunningServer,
+  ServerOptions,
+  ToolAnnotations,
 }
 
 // A plugin operates over arbitrary Server shapes; `any` here is the standard framework escape hatch
@@ -508,119 +416,19 @@ export interface ResponseFinalization {
 // biome-ignore lint/suspicious/noExplicitAny: plugins are generic over any Server's Registry/Context
 export type AnyServer = Server<any, any>
 
-/**
- * A nifra **plugin**: a function that augments an app — calling `use`/`derive`/`decorate` and/or
- * registering routes — and returns it. Because `derive`/`decorate` are type-threaded, an **inline**
- * `app.use((a) => a.derive(...).decorate(...))` carries the added context to handlers defined after
- * it (the `use` overload is generic over the concrete `this`). Wrap with {@link definePlugin} to
- * attach a name for idempotent dedupe (applying the same named plugin twice — e.g. transitively — is
- * a no-op).
- */
-export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer = In> = ((
-  app: In,
-) => Out) & { readonly pluginName?: string }
-
-/**
- * A named type-identity plugin built with {@link defineIdentityPlugin}. It returns the same concrete
- * server type it receives, preserving the caller's typed registry and context across `.use()` while
- * still allowing the plugin to register runtime hooks or handlers.
- */
-export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
-  readonly pluginName?: string
-}
-
-/**
- * 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<In extends AnyServer, Out extends AnyServer>(
-  name: string,
-  apply: (app: In) => Out,
-): NifraPlugin<In, Out> {
-  return Object.assign(apply, { pluginName: name }) as NifraPlugin<In, Out>
-}
-
-/**
- * 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: string,
-  apply: <S extends AnyServer>(app: S) => S,
-): IdentityPlugin {
-  return Object.assign(apply, { pluginName: name }) as IdentityPlugin
-}
-
-/**
- * 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: typeof defineIdentityPlugin = 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,
+  type NifraPlugin,
+} from "./plugin.ts"
+export type { IdentityPlugin }
 
 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: AbortSignal | undefined
-let unboundedRequestBudget: RequestBudget | undefined
-const getNeverAbortSignal = (): AbortSignal => {
-  neverAbortSignal ??= new AbortController().signal
-  return neverAbortSignal
-}
-const getUnboundedRequestBudget = (): RequestBudget => {
-  unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal())
-  return unboundedRequestBudget
-}
-
-function jsonError(status: number, error: string, headers?: Record<string, string>): Response {
-  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
@@ -641,178 +449,12 @@ function validationError(issues: ReadonlyArray<StandardIssue>): Response {
   return Response.json({ ok: false, error: "validation", issues: serialized }, { status: 422 })
 }
 
-interface UrlParts {
-  readonly pathname: string
-  readonly search: string
-}
-
-// 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: string): UrlParts {
-  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: string): string {
-  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: string): string {
-  return urlPartsOf(url).search
-}
-
-/** A query value: a single occurrence is a string; a repeated key promotes to a string[] so an
- * array query schema (`t.array(t.string())`) can validate `?tag=a&tag=b` — last-wins silently
- * dropped values before (audit 2026-06). Single-occurrence keys stay plain strings, so existing
- * `t.string()` schemas are untouched; a repeated key against a string schema now FAILS validation
- * (an explicit 400 beats silently picking one). */
-export type QueryValue = string | string[]
-
-/** 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: Record<string, QueryValue>, key: string, value: string): void {
-  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: string): Record<string, QueryValue> {
-  // 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: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
-  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)) as Record<string, QueryValue>
-
-export function queryObjectOf(search: string): Record<string, QueryValue> {
-  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: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
-  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: string): boolean {
-  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: RequestSource,
-  maxBytes: number,
-): Promise<Record<string, QueryValue> | Response> {
-  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: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
-  // 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: Record<string, string>): Record<string, string> | null {
-  let out: Record<string, string> | undefined
-  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.ts"
+// Query-string + urlencoded-form parsing now lives in `./query.ts`; re-exported so existing
+// importers keep resolving `searchOf`/`queryObjectOf`/`QueryValue` from here.
+export { type QueryValue, queryObjectOf, searchOf }
 
 function hasReplacementParam(params: Record<string, string>): boolean {
   for (const key in params) {
@@ -823,48 +465,12 @@ function hasReplacementParam(params: Record<string, string>): boolean {
 
 /** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
  * anything when no handler touched `c.set.*`. Server-internal. */
-type CtxSet = ResponseControls & {
+export type CtxSet = ResponseControls & {
   _headers?: Record<string, string>
   /** Accumulated `Set-Cookie` values — a list, since a `Record` would collapse multiple cookies. */
   _cookies?: string[]
 }
 
-class LazyResponseControls implements CtxSet {
-  status?: number
-  _headers?: Record<string, string>
-  _cookies?: string[]
-
-  get headers(): Record<string, string> {
-    this._headers ??= {}
-    return this._headers
-  }
-
-  cookie(name: string, value: string, options?: CookieOptions): void {
-    // Secure-by-default: HttpOnly + Secure + SameSite=Lax + Path=/, overridable per call.
-    const merged: CookieOptions = {
-      httpOnly: true,
-      secure: true,
-      sameSite: "lax",
-      path: "/",
-      ...options,
-    }
-    this._cookies ??= []
-    this._cookies.push(serializeCookie(name, value, merged))
-  }
-
-  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void {
-    // 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({}) as CtxSet
-
 function responseSet(ctx: RawContext): CtxSet {
   return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS
 }
@@ -878,407 +484,9 @@ function isContextlessNoArgArrow(handler: (context: never) => unknown): boolean
   }
 }
 
-/** Coerce `c.json`/`c.text`'s second arg — a status number (the common case) or a full `ResponseInit`. */
-function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
-  return typeof init === "number" ? { status: init } : init
-}
-
-class RequestContext implements RawContext {
-  // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
-  // constructor initializes only the eager request state, while lazy fields remain absent until used.
-  declare readonly params: Record<string, string>
-  declare body: unknown
-  private declare searchValue: string | undefined
-  private declare signalValue: AbortSignal | undefined
-  private declare budgetValue: RequestBudget | undefined
-  private declare platformValue: Platform | undefined
-
-  private declare setValue: CtxSet | undefined
-  private declare queryValue: unknown
-  private declare queryReady: boolean
-  private declare cookiesValue: Readonly<Record<string, string>> | undefined
-  private declare readonly source: RequestSource
-  private declare readonly maxBodyBytes: number
-
-  constructor(source: RequestSource, params: Record<string, string>, maxBodyBytes: number)
-  constructor(
-    source: RequestSource,
-    params: Record<string, string>,
-    search: string | undefined,
-    signal: AbortSignal,
-    budget: RequestBudget,
-    platform: Platform | undefined,
-    maxBodyBytes: number,
-  )
-  constructor(
-    source: RequestSource,
-    params: Record<string, string>,
-    searchOrMaxBodyBytes: string | number | undefined,
-    signal?: AbortSignal,
-    budget?: RequestBudget,
-    platform?: Platform,
-    maxBodyBytes?: number,
-  ) {
-    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 as number
-  }
-
-  static native(
-    source: RequestSource,
-    params: Record<string, string>,
-    maxBodyBytes: number,
-  ): RequestContext {
-    return new RequestContext(source, params, maxBodyBytes)
-  }
-
-  [CONTEXT_SET](): CtxSet | undefined {
-    return this.setValue
-  }
-
-  get [CONTEXT_SEARCH](): string {
-    this.searchValue ??= searchOf(this.source.url)
-    return this.searchValue
-  }
-
-  get set(): CtxSet {
-    this.setValue ??= new LazyResponseControls()
-    return this.setValue
-  }
-
-  get signal(): AbortSignal {
-    return this.signalValue ?? getNeverAbortSignal()
-  }
-
-  get budget(): RequestBudget {
-    return this.budgetValue ?? getUnboundedRequestBudget()
-  }
-
-  get env(): unknown {
-    return this.platformValue?.env
-  }
-
-  get waitUntil(): (promise: Promise<unknown>) => void {
-    return this.platformValue?.waitUntil ?? fallbackWaitUntil
-  }
-
-  get req(): Request {
-    return requestOf(this.source)
-  }
-
-  get request(): Request {
-    return requestOf(this.source)
-  }
-
-  json(body: unknown, init?: ResponseInit | number): Response {
-    return Response.json(body, statusInit(init))
-  }
-
-  text(body: string, init?: ResponseInit | number): Response {
-    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(): unknown {
-    if (!this.queryReady) {
-      this.queryValue = new URLSearchParams(this[CONTEXT_SEARCH])
-      this.queryReady = true
-    }
-    return this.queryValue
-  }
-
-  set query(v: unknown) {
-    this.queryValue = v
-    this.queryReady = true
-  }
-
-  get cookies(): Readonly<Record<string, string>> {
-    this.cookiesValue ??= parseCookies(headerOf(this.source, "cookie"))
-    return this.cookiesValue
-  }
-
-  boundedBody(maxBytes?: number): Promise<Uint8Array> {
-    return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes)
-  }
-
-  boundedJson<T = unknown>(maxBytes?: number): Promise<T> {
-    return readBoundedJsonBodyOrThrow<T>(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: RequestSource,
-  maxBodyBytes: number,
-  maxBytes?: number,
-): Promise<Uint8Array> {
-  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<T>(
-  req: RequestSource,
-  maxBodyBytes: number,
-  maxBytes?: number,
-): Promise<T> {
-  const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes)
-  if (parsed instanceof Response) throw parsed
-  return parsed as T
-}
-
-/**
- * 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: RequestSource,
-  maxBytes: number,
-): Promise<unknown | Response> {
-  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: CtxSet): Record<string, string> | Headers | undefined {
-  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: ResponseInit = { 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: unknown): Response {
-  if (
-    result !== undefined &&
-    !(result instanceof Response) &&
-    typeof result === "object" &&
-    result !== null &&
-    !isResponseResult(result)
-  ) {
-    return Response.json(result)
-  }
-  return toResponse(result as HandlerResult, 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: unknown, ctx: RawContext): Response {
-  const set = ctx[CONTEXT_SET]()
-  if (set === undefined) return fusedRespondNoSet(result)
-  return toResponse(result as HandlerResult, set)
-}
-
-function toResponse(result: HandlerResult, set: CtxSet): Response {
-  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) as string | undefined
-    if (body !== undefined) {
-      return new Response(
-        body,
-        status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS },
-      )
-    }
-  }
-  const init: ResponseInit = headers === undefined ? { status } : { status, headers }
-  return result === undefined ? new Response(null, init) : Response.json(result, init)
-}
-
-function appendCookiesToResponse(response: Response, set: CtxSet): Response {
-  // 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
-}
-
-/**
- * What {@link Server.resolveNode} returns: either a plain-data render the `@nifrajs/node` adapter writes
- * to the socket directly (`kind: "json"` — status + headers + cookies + a pre-stringified body, **no**
- * undici `Response` built or drained), a marked buffered response body (`kind: "body"` — e.g.
- * @nifrajs/web's non-deferred SSR HTML), or a `Response` (`kind: "response"`) for everything else
- * (redirects, 404/405/errors, unmarked or streaming bodies). Internal to the nifra↔node bridge.
- */
-export type NodeServeOutcome =
-  | { readonly kind: "response"; readonly response: Response }
-  | {
-      readonly kind: "json"
-      readonly status: number
-      /** `c.set.headers` backing, or `undefined` when the handler never set a header. */
-      readonly headers: Readonly<Record<string, string>> | undefined
-      /** Queued `Set-Cookie` lines, or `undefined`; the adapter emits one header line each. */
-      readonly cookies: readonly string[] | undefined
-      /** The JSON body already stringified, or `null` for an empty (204) response. */
-      readonly body: string | null
-    }
-  | {
-      readonly kind: "body"
-      readonly status: number
-      readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
-      readonly body: string | Uint8Array
-    }
-
-/**
- * `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: HandlerResult, set: CtxSet): NodeServeOutcome {
-  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): Response => response
 const RESPONSE_TIMEOUT = (): Response => jsonError(503, "request_timeout")
-const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
-const NODE_FROM_RESPONSE = (response: Response): NodeServeOutcome =>
-  nodeOutcomeFromResponse(response)
-const NODE_TIMEOUT = (): NodeServeOutcome => ({
-  kind: "response",
-  response: jsonError(503, "request_timeout"),
-})
-
-function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
-  const body = nodeResponseBody(response)
-  return body === undefined
-    ? { kind: "response", response }
-    : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body }
-}
-
-function nodeResponseBody(response: Response): string | Uint8Array | undefined {
-  if (response.bodyUsed) return undefined
-  const body = (response as { readonly [NODE_RESPONSE_BODY]?: unknown })[NODE_RESPONSE_BODY]
-  return typeof body === "string" || body instanceof Uint8Array ? body : undefined
-}
-
-function responseHeadersForNode(
-  response: Response,
-): Readonly<Record<string, string | readonly string[]>> | undefined {
-  let headers: Record<string, string | readonly string[]> | undefined
-  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: Readonly<Record<string, string | readonly string[]>> | undefined,
-  cookies: readonly string[] | undefined,
-): Readonly<Record<string, string | readonly string[]>> | undefined {
-  if (cookies === undefined || cookies.length === 0) return headers
-  const out: Record<string, string | readonly string[]> =
-    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`/
@@ -1289,7 +497,7 @@ function appendCookiesToNodeHeaders(
  *      .get("/me", (c) => c.user)            // c.user + c.db are typed
  */
 export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
-  private readonly router: Router<RouteEntry>
+  private readonly catalog: RouteCatalog
   /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
   private readonly wsRouter: Router<WsEntry>
   private wsRouteCount: number
@@ -1297,10 +505,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * 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. */
   private topics: TopicRegistry | undefined
-  private readonly routeList: RouteDescriptor[]
   private readonly maxBodyBytes: number
   private readonly wsMaxPayloadBytes: number
   private readonly requestTimeoutMs: number
+  /** Opt-in caller-IP trust declaration; `undefined` = socket peer only, no forwarded header believed. */
+  private readonly clientIpTrust: ClientIpTrust | undefined
   private readonly acceptInboundDeadlines: boolean
   private readonly maxInboundDeadlineMs: number
   private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
@@ -1308,17 +517,25 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
   private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
-  /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
-  private readonly effectLedger:
-    | Omit<ResolvedEffectLedger, "method" | "path" | "declared">
-    | undefined
-  /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
-  private readonly configuredIdempotencyStore: IdempotencyStore | undefined
-  private lazyIdempotencyStore: IdempotencyStore | undefined
+  /** The installed effect-ledger runtime (owns the sink + per-route resolution + settle), or
+   * `undefined` when the effect-ledger plugin is not installed. */
+  private effectLedgerRuntime: EffectLedgerRuntime | undefined
+  /** The installed idempotency runtime (owns the app-wide default store + the dedupe lane), or
+   * `undefined` when the idempotency plugin is not installed. */
+  private idempotencyRuntime: IdempotencyRuntime | undefined
+  /** Installed opt-in runtime for `.tool()`/`.resource()`/`.prompt()`; `undefined` until `.use(mcp())`. */
+  private mcpRuntime: McpRuntime | undefined
+  /** Installed Node-direct renderer for direct `resolveNode()` callers; `undefined` until `.use(nodeDirect())`. */
+  private nodeOutcomeRuntime: NodeOutcomeRuntime | undefined
+  /** Installed streaming runtime for `.sse()` routes; `undefined` until `.use(streaming())`. */
+  private sseRuntime: SseRuntime | undefined
+  /** Installed WebSocket runtime for `.ws()` routes; `undefined` until `.use(websocket())`. */
+  private wsRuntime: WsRuntime | undefined
   private readonly logger: Logger
   /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
   private readonly defaultOnValidationError?: RouteSchema["onValidationError"]
   private bunServer: RunningServer | undefined
+  private sealed: boolean
   private readonly derives: RawDerive[]
   private readonly decorations: Record<string, unknown>
   private readonly beforeHandleHooks: RawBeforeHandle[]
@@ -1338,29 +555,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
   private readonly mcpResourceList: McpResourceDescriptor[]
   private readonly mcpPromptList: McpPromptDescriptor[]
-  /**
-   * 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.
-   */
-  private readonly rawEntries: Array<{
-    readonly method: Method
-    readonly path: string
-    readonly entry: RouteEntry
-    readonly descriptor: RouteDescriptor
-    readonly assurance: readonly AssuranceDeclaration[]
-  }>
-
   constructor(options: ServerOptions = {}) {
-    this.router = new Router<RouteEntry>()
+    this.catalog = new RouteCatalog()
     this.wsRouter = new Router<WsEntry>()
     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({
@@ -1376,28 +579,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     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 = []
@@ -1413,17 +604,27 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.globalAssurance = []
     this.mcpResourceList = []
     this.mcpPromptList = []
-    this.rawEntries = []
+  }
+
+  private assertConfigurable(operation: string): void {
+    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<D extends object>(fn: (context: Context & Ctx) => MaybePromise<D>): Server<R, Ctx & D> {
+    this.assertConfigurable("derive()")
     this.derives.push(fn as unknown as RawDerive)
     return this as unknown as Server<R, Ctx & D>
   }
 
   /** Add a static context value for subsequent routes. */
   decorate<const K extends string, V>(key: K, value: V): Server<R, Ctx & Record<K, V>> {
+    this.assertConfigurable("decorate()")
     this.decorations[key] = value
     return this as unknown as Server<R, Ctx & Record<K, V>>
   }
@@ -1435,12 +636,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   onRequest(
     fn: (req: Request, platform?: Platform<EnvOf<Ctx>>) => MaybePromise<OnRequestResult>,
   ): this {
+    this.assertConfigurable("onRequest()")
     this.onRequestHooks.push(fn as RawOnRequest)
     return this
   }
 
   /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
   beforeHandle(fn: (context: Context & Ctx) => MaybePromise<unknown>): this {
+    this.assertConfigurable("beforeHandle()")
     this.beforeHandleHooks.push(fn as unknown as RawBeforeHandle)
     return this
   }
@@ -1451,24 +654,28 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * a Web `Response`. The first registered wrapper is outermost.
    */
   around(fn: <T>(context: Context & Ctx, next: () => MaybePromise<T>) => MaybePromise<T>): this {
+    this.assertConfigurable("around()")
     this.aroundHooks.push(fn as unknown as RawAround)
     return this
   }
 
   /** Transform the handler's result before it is serialized. Order-scoped. */
   afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
+    this.assertConfigurable("afterHandle()")
     this.afterHandleHooks.push(fn as unknown as RawAfterHandle)
     return this
   }
 
   /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
   onError(fn: (error: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
+    this.assertConfigurable("onError()")
     this.onErrorHooks.push(fn as unknown as RawErrorHandler)
     return this
   }
 
   /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */
   onResponse(fn: (response: Response, req: Request) => MaybePromise<Response>): this {
+    this.assertConfigurable("onResponse()")
     this.onResponseHooks.push(fn)
     return this
   }
@@ -1477,6 +684,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   onResponseFinalized(
     fn: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>,
   ): this {
+    this.assertConfigurable("onResponseFinalized()")
     this.onResponseFinalizedHooks.push(fn)
     return this
   }
@@ -1504,6 +712,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    */
   use(mw: Middleware): this
   use(arg: Middleware | ((app: this) => AnyServer)): AnyServer {
+    this.assertConfigurable("use()")
     if (typeof arg === "function") {
       const name = (arg as { pluginName?: string }).pluginName
       if (name !== undefined) {
@@ -1570,7 +779,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * 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)
@@ -1593,7 +803,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     init?: SSEInit,
   ): Server<AddRoute<R, "GET", Path, RouteInfoFor<Path, S, Response>>, Ctx> {
     const handler = (context: Context<Path, S> & Ctx): Response =>
-      sse(context, (stream) => run(context, typedSSEStream(stream)), init)
+      requireSseRuntime(this.sseRuntime).response(context, (stream) => run(context, stream), init)
     return this.route("GET", path, schema, handler as unknown as ErasedHandler) as Server<
       AddRoute<R, "GET", Path, RouteInfoFor<Path, S, Response>>,
       Ctx
@@ -1668,6 +878,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this.route("DELETE", path, schemaOrHandler, handler)
   }
 
+  /**
+   * Declare an **MCP tool** an agent can call (via `nifra mcp`, or a mounted MCP endpoint): a typed
+   * `POST /_nifra/tool/<name>` route whose `input`/`output` schemas contract the call and surface in
+   * `tools/list`. Requires `.use(mcp())` - without it, `.tool()` is a registration error, so an
+   * ordinary HTTP app never bundles the MCP wiring. Siblings: {@link resource}, {@link prompt}.
+   *
+   *   import { mcp } from "@nifrajs/core/mcp"
+   *   const app = server().use(mcp()).tool(
+   *     "search",
+   *     { description: "Search posts", input: t.object({ q: t.string() }) },
+   *     ({ q }) => findPosts(q),
+   *   )
+   */
   tool<
     Name extends string,
     S extends {
@@ -1709,24 +932,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     },
     handler: (input: unknown, ctx: Context & Ctx) => unknown,
   ): Server<Registry, Ctx> {
-    const path = `/_nifra/tool/${name}`
-    const routeSchema: 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: Context & Ctx): unknown => handler(c.body, c)
-    this.register("POST", path, routeSchema, run as (context: never) => unknown)
+    const plan = requireMcpRuntime(this.mcpRuntime).tool(
+      name,
+      config,
+      handler as (input: unknown, context: Context) => unknown,
+    )
+    this.register("POST", plan.path, plan.schema, plan.run as (context: never) => unknown)
     // 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 as { tool?: RouteDescriptor["tool"] }).tool = {
-        name,
-        description: config.description,
-        ...(config.annotations !== undefined ? { annotations: config.annotations } : {}),
-      }
+      ;(lastRoute as { tool?: RouteDescriptor["tool"] }).tool = plan.descriptor
     }
     return this as unknown as Server<Registry, Ctx>
   }
@@ -1742,13 +958,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     config: { readonly name: string; readonly description?: string; readonly mimeType?: string },
     read: McpResourceDescriptor["read"],
   ): Server<R, Ctx> {
-    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
   }
 
@@ -1761,12 +972,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     config: { readonly description: string; readonly arguments?: readonly PromptArgument[] },
     handler: McpPromptDescriptor["handler"],
   ): Server<R, Ctx> {
-    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
   }
 
@@ -1787,15 +994,29 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * 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<Data = unknown, Schema extends StandardSchemaV1 | undefined = undefined>(
-    path: string,
-    handler: WebSocketHandler<Data, EnvOf<Ctx>, Schema>,
-  ): this {
+  ws<
+    Data = unknown,
+    Schema extends StandardSchemaV1 | undefined = undefined,
+    Send extends StandardSchemaV1 | undefined = undefined,
+    Path extends string = string,
+  >(
+    path: Path,
+    handler: WebSocketHandler<Data, EnvOf<Ctx>, Schema, Send>,
+  ): string extends Path
+    ? Server<R, Ctx>
+    : Server<AddRoute<R, "WS", Path, WsRouteInfoFor<Path, Schema, Send>>, Ctx> {
+    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.
@@ -1803,7 +1024,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       handler: runtime.wrapHandler(handler as WebSocketHandler),
     })
     this.wsRouteCount += 1
-    return this
+    return this as never
   }
 
   /**
@@ -1848,6 +1069,34 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): void {
+    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: readonly {
+      readonly method: Method
+      readonly path: string
+      readonly schema: RouteSchema | undefined
+      readonly handler: (context: never) => unknown
+    }[],
+  ): void {
+    this.assertConfigurable("route registration")
+    const staged = routes.map(({ method, path, schema, handler }) =>
+      this.prepareRoute(method, path, schema, handler),
+    )
+    this.catalog.addBatch(staged)
+  }
+
+  private prepareRoute(
+    method: Method,
+    path: string,
+    schema: RouteSchema | undefined,
+    handler: (context: never) => unknown,
+  ): CatalogRoute {
+    const pattern = compileRoutePattern(path)
     const capabilities = normalizeRouteCapabilities(schema?.capabilities)
     const handlerAssurance = assuranceDeclarationsOf(handler as unknown as object)
     const invalidHandlerScope = handlerAssurance.find(
@@ -1876,16 +1125,26 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     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: ResolvedEffectLedger | undefined =
-      capabilities.length > 0 && this.effectLedger !== undefined
-        ? Object.freeze({ ...this.effectLedger, method, path, declared: capabilities })
-        : undefined
+    const ledgered: ResolvedEffectLedger | undefined = this.effectLedgerRuntime?.resolve(
+      capabilities,
+      method,
+      path,
+    )
     const bare =
+      schema?.params === undefined &&
       schema?.body === undefined &&
       schema?.query === undefined &&
       idempotent === undefined &&
@@ -1902,6 +1161,33 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             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: RouteEntry = {
       // (context: never) => unknown -> InternalHandler: the framework invokes it
       // with the concrete RawContext the typed handler expects, so this is sound.
@@ -1909,7 +1195,6 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       schema,
       idempotent,
       ledgered,
-      fusedWeb,
       derives: [...this.derives],
       decorations: routeDecorations,
       hasDecorations,
@@ -1917,141 +1202,217 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       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,
-    }
-    this.router.add(method, path, entry)
+      execution,
+    }
     const descriptor: RouteDescriptor = {
       method,
       path,
       schema,
       ...(capabilities.length > 0 ? { capabilities } : {}),
+      ...(schema?.family === true ? { family: true } : {}),
     }
-    this.routeList.push(descriptor)
     const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance, ...handlerAssurance]
-    if (schema?.body !== undefined) {
-      routeAssurance.push(
-        Object.freeze({
-          id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
-          source: "route-schema",
-          scope: "plugin",
-        }),
-      )
+    // 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" }))
     }
-    // Declaring `schema.idempotency` is evidence for request replay only. It deliberately never proves
-    // durable command execution; that stronger evidence belongs to a command/outbox adapter.
-    if (schema?.idempotency !== undefined) {
+    if (schema?.body !== undefined) {
       routeAssurance.push(
         Object.freeze({
-          id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
-          source: "route-schema",
-          scope: "plugin",
-        }),
-      )
-    }
-    this.rawEntries.push({
-      method,
-      path,
-      entry,
-      descriptor,
-      assurance: Object.freeze(routeAssurance),
-    })
-  }
-
-  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
-  private resolveIdempotency(
-    schema: RouteSchema | undefined,
-    authenticated: boolean,
-  ): ResolvedIdempotency | undefined {
-    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",
+          id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
+          source: "route-schema",
+          scope: "plugin",
+        }),
       )
     }
-    if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
-      throw new RouteConfigError(
-        "INVALID_IDEMPOTENCY",
-        `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+    // Declaring `schema.idempotency` is evidence for request replay only. It deliberately never proves
+    // durable command execution; that stronger evidence belongs to a command/outbox adapter.
+    if (schema?.idempotency !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+          source: "route-schema",
+          scope: "plugin",
+        }),
       )
     }
-    if (authenticated && typeof namespace !== "function") {
-      throw new RouteConfigError(
-        "INVALID_IDEMPOTENCY",
-        "authenticated idempotency routes require a principal namespace resolver",
-      )
+    return {
+      method,
+      path,
+      pattern,
+      entry,
+      descriptor,
+      assurance: Object.freeze(routeAssurance),
     }
-    const maxResponseBytes = config.maxResponseBytes ?? this.maxBodyBytes
-    if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
-      throw new RouteConfigError(
-        "INVALID_IDEMPOTENCY",
-        "idempotency maxResponseBytes must be a positive integer",
+  }
+
+  /** 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. */
+  private compileExecutionPlan(
+    lane: "bare" | "body" | "query" | "lifecycle",
+    contextless: boolean,
+    hasAround: boolean,
+    hasLedger: boolean,
+    fusedWeb: FusedWebRunner | undefined,
+  ): RouteExecutionPlan {
+    if (contextless) {
+      const run: RouteExecutionRunner = (
+        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: ContextRouteRunner
+    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: ContextRouteRunner = hasAround
+      ? (runtime, entry, source, ctx, finalize, wrapResponse) =>
+          runtime.runWithAround(
+            entry,
+            ctx,
+            () => inner(runtime, entry, source, ctx, finalize, wrapResponse),
+            finalize,
+            wrapResponse,
+          )
+      : inner
+    const run: RouteExecutionRunner = (
+      runtime,
+      entry,
+      source,
+      params,
+      search,
+      signal,
+      budget,
+      platform,
+      finalize,
+      wrapResponse,
+    ) => {
+      const ctx = new RequestContext(
+        source,
+        params,
+        search,
+        signal,
+        budget,
+        platform,
+        runtime.maxBodyBytes,
       )
+      let ledger: RequestLedger | undefined
+      // 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 as ResolvedEffectLedger
+        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 as ResolvedEffectLedger
+        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({
-      store,
-      ttlMs,
-      headerName,
-      namespace,
-      maxResponseBytes,
-    })
+    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). */
+  private idempotencyRunLanes(
+    buffered: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+  ): Promise<Response> {
+    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: IdempotencyRuntime): void {
+    this.assertConfigurable("idempotency()")
+    this.idempotencyRuntime = runtime
+  }
+
+  /** @internal Symbol-keyed install seam for the `mcp()` plugin. Off the public typed surface. */
+  [INSTALL_MCP](runtime: McpRuntime): void {
+    this.assertConfigurable("mcp()")
+    this.mcpRuntime = runtime
+  }
+
+  /** @internal Symbol-keyed install seam for the `nodeDirect()` plugin. Off the public typed surface. */
+  [INSTALL_NODE_DIRECT](runtime: NodeOutcomeRuntime): void {
+    this.assertConfigurable("nodeDirect()")
+    this.nodeOutcomeRuntime = runtime
+  }
+
+  /** @internal Symbol-keyed install seam for the `streaming()` plugin. Off the public typed surface. */
+  [INSTALL_SSE](runtime: SseRuntime): void {
+    this.assertConfigurable("streaming()")
+    this.sseRuntime = runtime
   }
 
-  /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
-  private defaultIdempotencyStore(): IdempotencyStore {
-    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: WsRuntime): void {
+    this.assertConfigurable("websocket()")
+    this.wsRuntime = runtime
   }
 
   /**
@@ -2074,6 +1435,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * those on the parent).
    */
   merge<R2 extends Registry, Ctx2>(other: Server<R2, Ctx2>): Server<R & R2, Ctx> {
+    this.assertConfigurable("merge()")
     const source = other as unknown as Server<Registry, EmptyContext>
     if (source.wsRouteCount > 0) {
       throw new RouteConfigError(
@@ -2081,11 +1443,18 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         "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)
@@ -2095,6 +1464,25 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this as unknown as Server<R & R2, Ctx>
   }
 
+  /** 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. */
+  private bindFusedRuntime(route: CatalogRoute): CatalogRoute {
+    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
@@ -2102,10 +1490,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    */
   routes(): ReadonlyArray<RouteDescriptor> {
     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
     })
@@ -2136,7 +1525,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<Response> {
     // 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<Response>(
@@ -2249,6 +1638,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   resolveNodeSource(
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
+    suppliedRuntime?: NodeOutcomeRuntime,
   ): MaybePromise<NodeServeOutcome> {
     // 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.
@@ -2262,15 +1652,22 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         ? 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.
+    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<NodeServeOutcome>(
       source,
       platform,
-      toNodeOutcome,
-      NODE_FROM_RESPONSE,
-      NODE_TIMEOUT,
+      runtime.toOutcome,
+      runtime.fromResponse,
+      runtime.timeout,
       false,
     )
   }
@@ -2294,11 +1691,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     if (!match.found) return WS_PASS // upgrade header, no WS route here → normal routing decides
     // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
     // already did and made every plain dynamic route pay for unrelated static path bytes.
-    const params = match.params === EMPTY_PARAMS ? match.params : 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 as TopicRegistry
+    const attach = (this.wsRuntime as 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`.
@@ -2317,7 +1715,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       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(
@@ -2332,7 +1730,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const settle = (value: unknown): WebSocketUpgradeOutcome =>
       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 as unknown as WebSocketContext<EnvOf<Ctx>>)
       return result instanceof Promise
@@ -2354,7 +1752,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     server: BunUpgradeServer,
   ): MaybePromise<Response | undefined> {
     const handle = (o: WebSocketUpgradeOutcome): MaybePromise<Response | undefined> => {
-      if (o.kind === "pass") return this.fetch(req)
+      if (o.kind === "pass")
+        return this.fetch(req, bunPeerPlatform(server, req) as Platform<EnvOf<Ctx>>)
       if (o.kind === "reject") return o.response
       return server.upgrade(req, { data: { handler: o.handler, data: o.data } })
         ? undefined
@@ -2371,6 +1770,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * 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. */
+  private deriveClientIp(
+    source: RequestSource,
+    platform: Platform | undefined,
+  ): Platform | undefined {
+    const derived = resolveClientIp(platform?.clientIp, requestOf(source), this.clientIpTrust)
+    return { ...platform, clientIp: derived }
+  }
+
   private dispatch<T>(
     source: RequestSource,
     platform: Platform | undefined,
@@ -2381,12 +1790,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // `Response` (`T = Response` there by construction; the node path always passes false).
     webFast: boolean,
   ): MaybePromise<T> {
+    // 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)
   }
 
   /**
@@ -2475,7 +1889,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
 
   /**
    * 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.
    */
   private routeAndRun<T>(
@@ -2487,7 +1901,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     webFast: boolean,
   ): MaybePromise<T> {
     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(
@@ -2499,7 +1913,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
 
     // 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"))
     }
@@ -2531,8 +1945,22 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   ): MaybePromise<T> {
     // 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)
+    // 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 as RouteEntry, prm, srch),
+        },
+      )
     }
     return this.runMatchedLanes(
       source,
@@ -2547,131 +1975,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     )
   }
 
-  /**
-   * 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.
-   */
-  private async runIdempotent<T>(
-    source: RequestSource,
-    platform: Platform | undefined,
-    entry: RouteEntry,
-    params: Record<string, string>,
-    search: string | undefined,
-    wrapResponse: (response: Response) => T,
-  ): Promise<T> {
-    const config = entry.idempotent as ResolvedIdempotency
-    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: RequestInit = {
-      method: req.method,
-      headers: req.headers,
-      signal: req.signal,
-    }
-    if (read.bytes.byteLength > 0)
-      bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
-    const buffered: RequestSource = new Request(req.url, bufferedInit)
-    let response: 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: Awaited<ReturnType<typeof serializeResponse>>
-      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,
-      })
-      if (!completed) {
-        return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }))
-      }
-    } else {
-      await config.store.abandon({ namespace, key, reservation })
-    }
-    return wrapResponse(response)
-  }
-
-  /** 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. */
   private runMatchedLanes<T>(
     source: RequestSource,
     platform: Platform | undefined,
@@ -2717,95 +2021,30 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       controller === undefined
         ? getUnboundedRequestBudget()
         : createRequestBudget({ deadline: admission!.deadline as number, 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: MaybePromise<T>
-    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,
-      ) as MaybePromise<T>
-    } 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: RequestLedger | undefined
-      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 as ResolvedEffectLedger
-        const active = ledger
-        outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) =>
-          this.settleEffectLedger(active, resolved, value),
-        )
-      }
-    }
+    const plan = entry.execution
+    const outcome: MaybePromise<T> =
+      webFast && plan.fusedWeb !== undefined
+        ? (plan.fusedWeb(
+            source,
+            params,
+            search,
+            signal,
+            budget,
+            platform,
+            false,
+          ) as MaybePromise<T>)
+        : 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) {
@@ -2823,32 +2062,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     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.
-   */
-  private async settleEffectLedger<T>(
-    ledger: RequestLedger,
-    resolved: ResolvedEffectLedger,
-    value: T,
-  ): Promise<T> {
-    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: EffectLedgerRuntime): void {
+    this.assertConfigurable("effectLedger()")
+    this.effectLedgerRuntime = runtime
   }
 
   /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
@@ -2923,7 +2140,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   }
 
   /**
-   * 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
@@ -2956,7 +2173,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** 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
@@ -2967,7 +2184,6 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     decorations: Record<PropertyKey, unknown> | undefined,
     contextless: boolean,
   ): FusedWebRunner {
-    const maxBodyBytes = this.maxBodyBytes
     const logError = (err: unknown, ctx: RawContext): Response => {
       if (err instanceof Response) return err
       this.logRequestError(err, ctx)
@@ -2985,8 +2201,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           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) {
@@ -2994,7 +2218,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             logError(
               err,
               nativeContext
-                ? RequestContext.native(source, params, maxBodyBytes)
+                ? RequestContext.native(source, params, this.maxBodyBytes)
                 : new RequestContext(
                     source,
                     params,
@@ -3002,7 +2226,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
                     signal,
                     budget,
                     platform,
-                    maxBodyBytes,
+                    this.maxBodyBytes,
                   ),
             ),
           )
@@ -3012,8 +2236,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     }
     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: unknown
       try {
@@ -3487,8 +2711,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     wrapResponse: (response: Response) => T,
   ): Promise<T> {
     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)
       }
       if (entry.schema?.query !== undefined) {
@@ -3499,8 +2732,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           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.
@@ -3581,7 +2814,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
 
   private async readAndValidateBody(
     req: RequestSource,
-    schema: StandardSchemaV1,
+    entry: RouteEntry,
     ctx: RawContext,
   ): Promise<Response | undefined> {
     const contentType = headerOf(req, "content-type") ?? ""
@@ -3599,10 +2832,44 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       // 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 validationError(result.issues)
-    ctx.body = result.value
+    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. */
+  private async applyLifecycleValidation(
+    entry: RouteEntry,
+    result: StandardResult<unknown>,
+    ctx: RawContext,
+    kind: "body" | "query" | "params",
+  ): Promise<Response | undefined> {
+    const assign = (value: unknown): void => {
+      if (kind === "body") ctx.body = value
+      else if (kind === "query") ctx.query = value
+      else ctx.params = value as Record<string, string>
+    }
+    if (result.issues === undefined) {
+      assign(result.value)
+      return undefined
+    }
+    const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError
+    if (hook === undefined) return validationError(result.issues)
+    const attempted = hook(result.issues, ctx as unknown as Context, 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
   }
 
@@ -3624,12 +2891,70 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     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. */
+  private compileBunNativeHandler(
+    entry: RouteEntry,
+    paramNames: readonly string[],
+    fused: FusedWebRunner | undefined,
+    signal: AbortSignal | undefined,
+    budget: RequestBudget | undefined,
+  ): BunNativeHandler {
+    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: Record<string, string>) => params[paramNames[0]!]?.includes("\uFFFD") === true
+        : hasReplacementParam
+    if (fused === undefined) {
+      return (request) => {
+        const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+        if (malformed(params)) return this.fetchSource(request)
+        return this.fetchMatched(request, entry, params)
+      }
+    }
+    if (this.acceptInboundDeadlines) {
+      return (request) => {
+        const params = (request as BunRequestWithParams).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 as BunRequestWithParams).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. */
   private buildBunNativeRoutes(): BunNativeRoutes | undefined {
-    if (this.onRequestHooks.length > 0 || this.wsRouteCount > 0) return undefined
+    // 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: BunNativeRoutes = Object.create(null) as BunNativeRoutes
     const mayUseFusedNative =
@@ -3642,143 +2967,22 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined
     const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined
     let count = 0
-    for (const { method, path, entry } of this.rawEntries) {
-      if (path.includes("*")) continue
+    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) as BunNativeMethodTable
         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 as AbortSignal,
-                      unboundedBudget as RequestBudget,
-                      undefined,
-                      true,
-                    )
-            : (request) =>
-                fused(
-                  request,
-                  EMPTY_PARAMS,
-                  undefined,
-                  unboundedSignal as AbortSignal,
-                  unboundedBudget as RequestBudget,
-                  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: unknown, ctx: RawContext): Response => {
-            if (error instanceof Response) return error
-            this.logRequestError(error, ctx)
-            return jsonError(500, "internal_error")
-          }
-          methods[method] = this.acceptInboundDeadlines
-            ? (request) => {
-                const params = (request as BunRequestWithParams).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: unknown
-                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 as BunRequestWithParams).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: unknown
-                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 as BunRequestWithParams).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 as AbortSignal,
-                      unboundedBudget as RequestBudget,
-                      undefined,
-                      true,
-                    )
-              }
-            : (request) => {
-                const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
-                if (hasReplacementParam(params)) return this.fetchSource(request)
-                return fused(
-                  request,
-                  params,
-                  undefined,
-                  unboundedSignal as AbortSignal,
-                  unboundedBudget as RequestBudget,
-                  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 as BunRequestWithParams).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 as BunRequestWithParams).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
@@ -3821,12 +3025,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // `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() as WsRuntime).bunHandlers(this.topics as TopicRegistry)
+        : (this.wsRuntime as WsRuntime).bunHandlers(this.topics as TopicRegistry)
     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.
@@ -3838,7 +3042,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           reusePort,
           ...bind,
           ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
-          fetch: (req: Request) => this.fetch(req),
+          fetch: (req: Request, server) =>
+            this.fetch(req, bunPeerPlatform(server, req) as Platform<EnvOf<Ctx>>),
         })
       : Bun.serve<BunWsData>({
           port,
@@ -3858,6 +3063,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           },
         })) as unknown as RunningServer
     this.bunServer = running
+    this.sealed = true
     if (this.gracefulSignals) this.installSignalHandlers()
     return running
   }
@@ -4017,9 +3223,9 @@ export function toFetchHandler<Env = unknown>(
           const pair = new Pair()
           const server = pair[1]
           server.accept()
-          // Non-null: an `upgrade` outcome only exists for an app with ws() routes, and ws()
-          // requires the `@nifrajs/core/ws` runtime at registration.
-          ;(getWsRuntime() as WsRuntime).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,
           })