@nifrajs/core 1.13.0 → 2.1.0

package/dist/server/server.d.ts

@@ -1,15 +1,26 @@
-import { type IdempotencyStore } from "../idempotency.js";
-import { type CapabilityUseEvent } from "../internal/capability-runtime.js";
-import { type AssuranceEvidence } from "../internal/route-assurance.js";
-import { type EffectLedgerOptions } from "../ledger.js";
+import { type RequestBudget } from "../budget.js";
+import type { EffectLifecycleObserver } from "../effect-lifecycle.js";
+import { type AroundCapabilityOptions, type CapabilityInterceptor } from "../internal/capability-runtime.js";
 import { type Method } from "../router/router.js";
 import type { InferOutput, StandardSchemaV1 } from "../schema/standard.js";
-import type { Context, Platform, RouteSchema } from "./context.js";
-import { type Logger } from "./logger.js";
-import type { AddRoute, EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.js";
-import { type SSEInit, type TypedSSEStream } from "./sse.js";
+import type { Context, Platform, ResponseControls, RouteSchema } from "./context.js";
+import type { NodeServeOutcome } from "./node-outcome.js";
+import type { NodeOutcomeRuntime } from "./node-outcome-hook.js";
+import { type QueryValue, queryObjectOf, searchOf } from "./query.js";
+import { CONTEXT_SEARCH, CONTEXT_SET, type HandlerResult } from "./runtime-core.js";
+export type { NodeServeOutcome };
+import type { IdempotencyRuntime } from "./idempotency-lane.js";
+import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_SSE, INSTALL_WS } from "./install.js";
+import type { EffectLedgerRuntime } from "./ledger-lane.js";
+import type { McpRuntime } from "./mcp-hook.js";
+import type { IdentityPlugin } from "./plugin.js";
+import type { AddRoute, EmptyRegistry, OutputOf, Registry, RouteInfoFor, WsRouteInfoFor } from "./registry.js";
+import type { AdmissionController, AdmissionDecision, McpPromptDescriptor, McpResourceDescriptor, Middleware, PromptArgument, PromptMessage, ResponseFinalization, RouteDescriptor, RunningServer, ServerOptions, ToolAnnotations } from "./server-types.js";
+import type { SSEInit, TypedSSEStream } from "./sse.js";
+import type { SseRuntime } from "./sse-hook.js";
 import type { WebSocketHandler, WebSocketUpgradeOutcome } from "./websocket.js";
-type MaybePromise<T> = T | Promise<T>;
+import type { WsRuntime } from "./ws-hook.js";
+export type MaybePromise<T> = T | Promise<T>;
 /**
  * Internal request view. A real Web `Request` already satisfies this shape, so Web/edge runtimes pass
  * their `Request` **directly** (zero wrapper allocation on the hot path — `request` is simply absent and
@@ -39,8 +50,27 @@ 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;
+/** Internal, path-erased runtime context. The typed `Context<Path, S>` is a structural view of this. */
+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;
+    params: Record<string, string>;
+    query: unknown;
+    readonly cookies: Readonly<Record<string, string>>;
+    body: unknown;
+    readonly set: ResponseControls;
+    readonly [CONTEXT_SET]: () => CtxSet | undefined;
+    readonly [CONTEXT_SEARCH]: string;
+    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>;
+}
 export type OnRequestResult = Response | Request | undefined;
 /** The handler's permitted return type. When the route declares a `response` schema, the return is
  * constrained to the contract's type (or a raw `Response`) — so the implementation can't drift from the
@@ -53,312 +83,18 @@ type ResponseOf<S extends RouteSchema> = S extends {
  * any accumulated middleware context `Ctx` (from `derive`/`decorate`).
  */
 export type Handler<Path extends string, S extends RouteSchema = RouteSchema, 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;
-}
+export type { AdmissionController, AdmissionDecision, McpPromptDescriptor, McpResourceDescriptor, Middleware, PromptArgument, PromptMessage, ResponseFinalization, RouteDescriptor, RunningServer, ServerOptions, ToolAnnotations, };
 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 declare function definePlugin<In extends AnyServer, Out extends AnyServer>(name: string, apply: (app: In) => Out): 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 declare function defineIdentityPlugin(name: string, apply: <S extends AnyServer>(app: S) => S): 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 declare const defineRouterPlugin: typeof defineIdentityPlugin;
-interface UrlParts {
-    readonly pathname: string;
-    readonly search: string;
-}
-export declare function urlPartsOf(url: string): UrlParts;
-export declare function pathnameOf(url: string): string;
-export declare function searchOf(url: string): string;
-/** 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[];
-export declare function queryObjectOf(search: string): Record<string, QueryValue>;
-/**
- * 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;
+export { defineIdentityPlugin, definePlugin, defineRouterPlugin, type NifraPlugin, } from "./plugin.js";
+export type { IdentityPlugin };
+export { pathnameOf, urlPartsOf } from "./http.js";
+export { type QueryValue, queryObjectOf, searchOf };
+/** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
+ * anything when no handler touched `c.set.*`. Server-internal. */
+export type CtxSet = ResponseControls & {
+    _headers?: Record<string, string>;
+    /** Accumulated `Set-Cookie` values — a list, since a `Record` would collapse multiple cookies. */
+    _cookies?: string[];
 };
 /**
  * The inline server. Routes are chainable and fully type-inferred. `derive`/
@@ -380,6 +116,8 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
     private readonly maxBodyBytes;
     private readonly wsMaxPayloadBytes;
     private readonly requestTimeoutMs;
+    /** Opt-in caller-IP trust declaration; `undefined` = socket peer only, no forwarded header believed. */
+    private readonly clientIpTrust;
     private readonly acceptInboundDeadlines;
     private readonly maxInboundDeadlineMs;
     private readonly deadlineAdmissionOptions;
@@ -387,11 +125,22 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
     /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
     private readonly capacityGate;
     private readonly onCapabilityUse;
-    /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
-    private readonly effectLedger;
-    /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
-    private readonly configuredIdempotencyStore;
-    private lazyIdempotencyStore;
+    private readonly capabilityInterceptors;
+    private readonly capabilityObservers;
+    /** The installed effect-ledger runtime (owns the sink + per-route resolution + settle), or
+     * `undefined` when the effect-ledger plugin is not installed. */
+    private effectLedgerRuntime;
+    /** The installed idempotency runtime (owns the app-wide default store + the dedupe lane), or
+     * `undefined` when the idempotency plugin is not installed. */
+    private idempotencyRuntime;
+    /** Installed opt-in runtime for `.tool()`/`.resource()`/`.prompt()`; `undefined` until `.use(mcp())`. */
+    private mcpRuntime;
+    /** Installed Node-direct renderer for direct `resolveNode()` callers; `undefined` until `.use(nodeDirect())`. */
+    private nodeOutcomeRuntime;
+    /** Installed streaming runtime for `.sse()` routes; `undefined` until `.use(streaming())`. */
+    private sseRuntime;
+    /** Installed WebSocket runtime for `.ws()` routes; `undefined` until `.use(websocket())`. */
+    private wsRuntime;
     private readonly logger;
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     private readonly defaultOnValidationError?;
@@ -435,6 +184,14 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
      * a Web `Response`. The first registered wrapper is outermost.
      */
     around(fn: <T>(context: Context & Ctx, next: () => MaybePromise<T>) => MaybePromise<T>): this;
+    /**
+     * Asynchronously admit each subsequent `executeCapability()` call before its owned effect runs.
+     * Interceptors receive token-only metadata plus an abort signal and must call `next()` exactly once
+     * to admit. Returning without `next()`, timing out, aborting, or throwing fails the effect closed.
+     */
+    aroundCapability(interceptor: CapabilityInterceptor, options?: AroundCapabilityOptions): this;
+    /** Observe token-only admission/execution lifecycle events for subsequent capability routes. */
+    observeCapability(observer: EffectLifecycleObserver): this;
     /** Transform the handler's result before it is serialized. Order-scoped. */
     afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this;
     /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
@@ -474,7 +231,8 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
      * 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)
@@ -498,6 +256,19 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
     patch<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, "PATCH", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;
     delete<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, "DELETE", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;
     delete<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, "DELETE", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;
+    /**
+     * 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 {
         description: string;
         input: StandardSchemaV1;
@@ -539,9 +310,15 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
      * 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>;
     /**
      * Broadcast `data` to every WebSocket connection subscribed to `topic` (via `ws.subscribe(topic)`).
      * In-process and **single-instance** (see {@link TopicRegistry}) — a multi-instance deploy must bridge
@@ -567,10 +344,19 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
     /** 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;
-    /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
-    private resolveIdempotency;
-    /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
-    private defaultIdempotencyStore;
+    /** 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;
+    /** @internal Symbol-keyed install seam for the `idempotency()` plugin. Off the public typed surface. */
+    [INSTALL_IDEMPOTENCY](runtime: IdempotencyRuntime): void;
+    /** @internal Symbol-keyed install seam for the `mcp()` plugin. Off the public typed surface. */
+    [INSTALL_MCP](runtime: McpRuntime): void;
+    /** @internal Symbol-keyed install seam for the `nodeDirect()` plugin. Off the public typed surface. */
+    [INSTALL_NODE_DIRECT](runtime: NodeOutcomeRuntime): void;
+    /** @internal Symbol-keyed install seam for the `streaming()` plugin. Off the public typed surface. */
+    [INSTALL_SSE](runtime: SseRuntime): void;
+    /** @internal Symbol-keyed install seam for the `websocket()` plugin. Off the public typed surface. */
+    [INSTALL_WS](runtime: WsRuntime): void;
     /**
      * Merge another server's routes into this one — the composition escape hatch for large apps.
      *
@@ -630,7 +416,7 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
      * render differs.
      */
     resolveNode(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;
-    resolveNodeSource(source: RequestSource, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;
+    resolveNodeSource(source: RequestSource, platform?: Platform<EnvOf<Ctx>>, suppliedRuntime?: NodeOutcomeRuntime): MaybePromise<NodeServeOutcome>;
     /**
      * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS
      * upgrade for a registered route → handle as normal HTTP), `reject` (a WS route matched but
@@ -651,6 +437,9 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
      * 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;
     private dispatch;
     /**
      * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the
@@ -672,24 +461,10 @@ export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyConte
     private routeAndRun;
     /** Run a route that has already been matched by the runtime or Nifra's portable router. */
     private runMatched;
-    /**
-     * 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 runIdempotent;
     /** Supply request-specific deadline state to the route's precompiled execution plan. */
     private runMatchedLanes;
-    /**
-     * 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 settleEffectLedger;
+    /** @internal Symbol-keyed install seam for the `effectLedger()` plugin. Off the public typed surface. */
+    [INSTALL_EFFECT_LEDGER](runtime: EffectLedgerRuntime): void;
     /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
      * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
     private runContextlessBare;
@@ -874,5 +649,4 @@ export declare function toFetchHandler<Env = unknown>(app: {
     fetch(request: Request, env: Env, ctx: ExecutionContext): MaybePromise<Response>;
     scheduled?(controller: ScheduledController, env: Env, ctx: ExecutionContext): MaybePromise<void>;
 };
-export {};
 //# sourceMappingURL=server.d.ts.map