@nifrajs/core 2.1.0 → 2.3.0

package/dist/server/server.js

@@ -2,7 +2,9 @@ import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA
 import { FrameworkError, RouteConfigError } from "../errors.js";
 import { CAPABILITY_GUARD, createCapabilityGuard, DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS, normalizeRouteCapabilities, } from "../internal/capability-runtime.js";
 import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, validEvidenceId, } from "../internal/route-assurance.js";
-import { compileRoutePattern, decodeRouteParams, } from "../router/pattern.js";
+import { RouteCatalog } from "../internal/route-catalog.js";
+import { isSameOriginRequest } from "../internal/same-origin.js";
+import { compileRoutePattern, decodeRouteParams } from "../router/pattern.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
 import { parseContentLength } from "./body.js";
 import { resolveClientIp } from "./client-ip.js";
@@ -11,61 +13,10 @@ import { isUrlEncodedForm, queryObjectOf, readBoundedForm, searchOf, } from "./q
 import { RequestContext, readBoundedJsonSource } from "./request-context.js";
 import { fusedRespond, fusedRespondNoSet, toResponse } from "./respond.js";
 import { CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, requestOf, } from "./runtime-core.js";
-import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_SSE, INSTALL_WS, } from "./install.js";
+import { INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_RESPONSE_CONTRACT, INSTALL_SSE, INSTALL_WS, } from "./install.js";
 import { jsonLogger } from "./logger.js";
 const functionToString = Function.prototype.toString;
 const CONTEXTLESS_ARROW = /^(?:async\s*)?\(\s*\)\s*(?::[\s\S]*?)?=>/;
-/**
- * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
- * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
- * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
- * reflection unchanged.
- */
-class RouteCatalog {
-    matcher = new Router();
-    records = [];
-    /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
-    descriptors = [];
-    assurancePresent = false;
-    add(route) {
-        this.matcher.add(route.method, route.pattern, route.entry);
-        this.records.push(route);
-        this.descriptors.push(route.descriptor);
-        if (route.assurance.length > 0)
-            this.assurancePresent = true;
-    }
-    addBatch(routes) {
-        if (routes.length === 0)
-            return;
-        const nextRecords = this.records.concat(routes);
-        const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor));
-        const nextAssurancePresent = this.assurancePresent || routes.some((route) => route.assurance.length > 0);
-        const staged = new Router();
-        for (const route of this.records)
-            staged.add(route.method, route.pattern, route.entry);
-        for (const route of routes)
-            staged.add(route.method, route.pattern, route.entry);
-        this.matcher = staged;
-        this.records = nextRecords;
-        this.descriptors = nextDescriptors;
-        this.assurancePresent = nextAssurancePresent;
-    }
-    find(method, path) {
-        return this.matcher.find(method, path);
-    }
-    entries() {
-        return this.records;
-    }
-    routeDescriptors() {
-        return this.descriptors;
-    }
-    lastDescriptor() {
-        return this.records[this.records.length - 1]?.descriptor;
-    }
-    hasAssurance() {
-        return this.assurancePresent;
-    }
-}
 /** The socket peer Bun observed, as a `Platform` for the request lifecycle (`undefined` if unknown).
  * Typed structurally on `requestIP` alone so any Bun `Server` (WS or not) satisfies it. */
 function bunPeerPlatform(server, req) {
@@ -98,17 +49,10 @@ export { defineIdentityPlugin, definePlugin, defineRouterPlugin, } from "./plugi
 const DEFAULT_MAX_BODY_BYTES = 1_000_000;
 const DEFAULT_DRAIN_MS = 10_000;
 const DRAIN_POLL_MS = 10;
-/** Same-origin check for a WebSocket handshake (CSWSH default): the `Origin`'s host[:port] must equal the
- * request's own host (from `req.url`, which the runtime builds from the `Host` header). Scheme differs
- * (ws↔http), so compare host only. An unparseable Origin is treated as NOT same-origin (rejected). */
-function wsSameOrigin(origin, req) {
-    try {
-        return new URL(origin).host === new URL(req.url).host;
-    }
-    catch {
-        return false;
-    }
-}
+/** Same-origin check for a WebSocket handshake (CSWSH default). {@link isSameOriginRequest} is the one
+ * owner, shared with the server-function mount in `@nifrajs/web` - the two used to answer differently
+ * for the same request, so a browser that could open a socket was told its POST was cross-origin. */
+const wsSameOrigin = isSameOriginRequest;
 function validationError(issues) {
     const serialized = issues.map((issue) => {
         const path = issue.path?.map((seg) => String(typeof seg === "object" ? seg.key : seg));
@@ -159,12 +103,15 @@ export class Server {
     wsRouter;
     wsRouteCount;
     /** In-process pub/sub backing `ws.subscribe(topic)` + `app.publish(topic, data)` (single-instance).
-     * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime — `undefined` until then, so a
+     * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime - `undefined` until then, so a
      * no-WebSocket app never constructs (or bundles) it. */
     topics;
     maxBodyBytes;
     wsMaxPayloadBytes;
     requestTimeoutMs;
+    /** Installed by the `responseContract()` plugin; `undefined` = not installed, which is the default
+     * and the state in which a declared `response` schema stays a compile-time contract only. */
+    responseContractRuntime;
     /** Opt-in caller-IP trust declaration; `undefined` = socket peer only, no forwarded header believed. */
     clientIpTrust;
     acceptInboundDeadlines;
@@ -205,7 +152,7 @@ export class Server {
     onResponseHooks;
     onResponseFinalizedHooks;
     responseRequests;
-    /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */
+    /** Names of plugins/middleware already applied via `use` - for idempotent dedupe. */
     appliedPlugins;
     /** Order-scoped evidence captured by routes registered after an assured plugin. */
     activeAssurance;
@@ -245,6 +192,7 @@ export class Server {
         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.responseContractRuntime = undefined;
         this.idempotencyRuntime = undefined;
         this.logger = options.logger ?? jsonLogger();
         this.defaultOnValidationError = options.onValidationError;
@@ -347,7 +295,7 @@ export class Server {
         this.onErrorHooks.push(fn);
         return this;
     }
-    /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */
+    /** Transform every outgoing response - success, error, 404, 405, short-circuit. Global. */
     onResponse(fn) {
         this.assertConfigurable("onResponse()");
         this.onResponseHooks.push(fn);
@@ -417,11 +365,11 @@ export class Server {
         return this.route("GET", path, schemaOrHandler, handler);
     }
     /**
-     * Register a **typed SSE route** — a GET endpoint streaming `text/event-stream` whose event
+     * Register a **typed SSE route** - a GET endpoint streaming `text/event-stream` whose event
      * payloads are contracted by `schema.sse`. The handler receives the validated context plus a
      * {@link TypedSSEStream}: `stream.send(event)` is compile-time-checked against the schema and
      * 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.
+     * `.subscribe(onEvent)` for the route with the same payload type - end-to-end typed streaming.
      *
      *   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() }) },
@@ -457,7 +405,7 @@ export class Server {
         const plan = requireMcpRuntime(this.mcpRuntime).tool(name, config, handler);
         this.register("POST", plan.path, plan.schema, plan.run);
         // Tag the just-registered descriptor as an MCP tool. `tool` is readonly on RouteDescriptor (an
-        // introspection field), so write it through a narrow mutable view — not `any`.
+        // introspection field), so write it through a narrow mutable view - not `any`.
         const lastRoute = this.catalog.lastDescriptor();
         if (lastRoute) {
             ;
@@ -466,7 +414,7 @@ export class Server {
         return this;
     }
     /**
-     * Declare an MCP **resource** — read-only data an agent can fetch through `nifra mcp` (app config, a
+     * Declare an MCP **resource** - read-only data an agent can fetch through `nifra mcp` (app config, a
      * generated document, …). `read` runs in the app process, so capture whatever app state it needs in the
      * closure. `uri` is the MCP resource identifier (e.g. `"myapp://config"`). The sibling of {@link tool}
      * for the resource half of MCP.
@@ -477,7 +425,7 @@ export class Server {
         return this;
     }
     /**
-     * Declare an MCP **prompt** — a reusable prompt template an agent can fetch through `nifra mcp`.
+     * Declare an MCP **prompt** - a reusable prompt template an agent can fetch through `nifra mcp`.
      * `handler` receives the caller's arguments and returns the rendered messages.
      */
     prompt(name, config, handler) {
@@ -485,11 +433,11 @@ export class Server {
         this.mcpPromptList.push(requireMcpRuntime(this.mcpRuntime).prompt(name, config, handler));
         return this;
     }
-    /** The MCP resources declared via {@link resource} — enumerated by `nifra mcp`. */
+    /** The MCP resources declared via {@link resource} - enumerated by `nifra mcp`. */
     mcpResources() {
         return this.mcpResourceList;
     }
-    /** The MCP prompts declared via {@link prompt} — enumerated by `nifra mcp`. */
+    /** The MCP prompts declared via {@link prompt} - enumerated by `nifra mcp`. */
     mcpPrompts() {
         return this.mcpPromptList;
     }
@@ -497,7 +445,7 @@ export class Server {
      * Register a **WebSocket** route. The connection upgrades on a `GET` to `path` carrying
      * `Upgrade: websocket`; the optional `handler.upgrade(c)` runs in the request context first and may
      * reject (return a `Response`) or seed per-connection `ws.data`. WebSockets are served by the
-     * adapter (`listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler`) — not by bare `app.fetch`, which
+     * 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
@@ -511,10 +459,10 @@ export class Server {
     ws(path, handler) {
         this.assertConfigurable("ws()");
         // Boot-time guard: the WS runtime is a subpath (`@nifrajs/core/ws`) so no-WebSocket apps don't
-        // bundle it. Registration is the loud, early failure point — never the first connection.
+        // bundle it. Registration is the loud, early failure point - never the first connection.
         const runtime = requireWsRuntime(this.wsRuntime);
         this.topics ??= runtime.createTopics();
-        // A `messageSchema` wraps `message` with validation once, here — every adapter then dispatches
+        // A `messageSchema` wraps `message` with validation once, here - every adapter then dispatches
         // already-validated, typed messages (Bun/Deno/Node/Workers) with no per-adapter code.
         this.wsRouter.add("GET", path, {
             handler: runtime.wrapHandler(handler),
@@ -524,11 +472,11 @@ export class Server {
     }
     /**
      * 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
+     * In-process and **single-instance** (see {@link TopicRegistry}) - a multi-instance deploy must bridge
      * an external fan-out (Redis, a Durable Object) to this. A no-op when nobody is subscribed.
      */
     publish(topic, data) {
-        // No `app.ws()` yet ⇒ no registry and necessarily no subscribers — a publish is a no-op anyway.
+        // No `app.ws()` yet ⇒ no registry and necessarily no subscribers - a publish is a no-op anyway.
         this.topics?.publish(topic, data);
     }
     route(method, path, schemaOrHandler, handler) {
@@ -549,7 +497,7 @@ export class Server {
     }
     /**
      * Low-level route registration shared by the inline builder and `implement()`.
-     * Captures the server's current `derive`/`decorate` chain into the route — this
+     * Captures the server's current `derive`/`decorate` chain into the route - this
      * is the "compiled", order-scoped per-route chain.
      */
     register(method, path, schema, handler) {
@@ -578,7 +526,7 @@ export class Server {
         }
         const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0;
         // An idempotency route runs a dedupe lane that must buffer the body and capture the response, so it
-        // never takes the fused/native fast path — force it onto the portable matched lane (which routes
+        // never takes the fused/native fast path - force it onto the portable matched lane (which routes
         // 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.
@@ -588,13 +536,21 @@ export class Server {
         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.
+        // fused/contextless fast path. Resolved per route, at registration - like the capability guard.
         const ledgered = this.effectLedgerRuntime?.resolve(capabilities, method, path);
+        // A checked response schema needs the handler's VALUE before it becomes bytes, and the fused and
+        // native lanes exist precisely to skip that step. So a contracted route leaves them - the same
+        // trade an idempotent route makes above, and the reason this is opt-in per server.
+        const runtime = this.responseContractRuntime;
+        const contracted = runtime !== undefined && schema?.response !== undefined
+            ? { runtime, schema: schema.response }
+            : undefined;
         const bare = schema?.params === undefined &&
             schema?.body === undefined &&
             schema?.query === undefined &&
             idempotent === undefined &&
             ledgered === undefined &&
+            contracted === undefined &&
             this.derives.length === 0 &&
             this.beforeHandleHooks.length === 0 &&
             this.afterHandleHooks.length === 0 &&
@@ -603,9 +559,12 @@ export class Server {
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
             : undefined;
         const contextless = bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler);
+        // The body and query lanes finalize the handler's result themselves, so a contracted route takes
+        // the general lifecycle lane instead - one place owns the check rather than three.
         const lane = bare
             ? "bare"
-            : schema?.body !== undefined &&
+            : contracted === undefined &&
+                schema?.body !== undefined &&
                 schema.query === undefined &&
                 schema.params === undefined &&
                 this.derives.length === 0 &&
@@ -613,7 +572,8 @@ export class Server {
                 this.afterHandleHooks.length === 0 &&
                 this.onErrorHooks.length === 0
                 ? "body"
-                : schema?.body === undefined &&
+                : contracted === undefined &&
+                    schema?.body === undefined &&
                     schema?.query !== undefined &&
                     schema.params === undefined &&
                     this.derives.length === 0 &&
@@ -630,6 +590,7 @@ export class Server {
             schema,
             idempotent,
             ledgered,
+            responseContract: contracted,
             derives: [...this.derives],
             decorations: routeDecorations,
             hasDecorations,
@@ -730,6 +691,11 @@ export class Server {
     idempotencyRunLanes(buffered, platform, entry, params, search) {
         return Promise.resolve(this.runMatchedLanes(buffered, platform, entry, params, search, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, false));
     }
+    /** @internal Symbol-keyed install seam for the `responseContract()` plugin. Off the public typed surface. */
+    [INSTALL_RESPONSE_CONTRACT](runtime) {
+        this.assertConfigurable("responseContract()");
+        this.responseContractRuntime = runtime;
+    }
     /** @internal Symbol-keyed install seam for the `idempotency()` plugin. Off the public typed surface. */
     [INSTALL_IDEMPOTENCY](runtime) {
         this.assertConfigurable("idempotency()");
@@ -756,16 +722,16 @@ export class Server {
         this.wsRuntime = runtime;
     }
     /**
-     * Merge another server's routes into this one — the composition escape hatch for large apps.
+     * Merge another server's routes into this one - the composition escape hatch for large apps.
      *
      * WHY: the fluent chain accumulates one type-alias level per route, and TypeScript resolves
-     * that stack in one recursion — a single chain hits TS2589 at ~95 routes. Groups keep every
+     * that stack in one recursion - a single chain hits TS2589 at ~95 routes. Groups keep every
      * chain short: build each domain (`listings`, `agents`, …) as its own `server()` (its registry
-     * resolves independently), then `app.merge(listings).merge(agents)` — each merge adds ONE level
+     * resolves independently), then `app.merge(listings).merge(agents)` - each merge adds ONE level
      * regardless of group size. 300+ routes stay fully typed (see many-routes.test-d.ts). The
      * other escape hatch is contract-first `implement()`, whose registry is a single object type.
      *
-     * Semantics: merged routes keep the chains captured where they were DEFINED — the group's
+     * Semantics: merged routes keep the chains captured where they were DEFINED - the group's
      * `derive`/`decorate`/`beforeHandle`/`afterHandle`/`onError`/`around` apply to its routes
      * exactly as they did standalone, so a group wires its own plugins. The group's request-level
      * hooks (`onRequest`/`onResponse`/`onResponseFinalized`) are appended to this server's. This
@@ -778,7 +744,7 @@ export class Server {
         this.assertConfigurable("merge()");
         const source = other;
         if (source.wsRouteCount > 0) {
-            throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes — register .ws() routes on the parent server");
+            throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes - register .ws() routes on the parent server");
         }
         this.catalog.addBatch(source.catalog.entries().map((route) => this.bindFusedRuntime(route)));
         // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
@@ -786,6 +752,7 @@ export class Server {
         // when the parent has none so merging cannot silently disable a safety lane. If the parent already
         // has a runtime, either implementation can execute every resolved entry because route-specific
         // options were pinned during registration.
+        this.responseContractRuntime ??= source.responseContractRuntime;
         this.idempotencyRuntime ??= source.idempotencyRuntime;
         this.effectLedgerRuntime ??= source.effectLedgerRuntime;
         this.mcpRuntime ??= source.mcpRuntime;
@@ -832,17 +799,17 @@ export class Server {
         });
     }
     /**
-     * Resolve a `Request` to a `Response` — the whole lifecycle, testable without a port. The
+     * Resolve a `Request` to a `Response` - the whole lifecycle, testable without a port. The
      * optional `platform` carries edge inputs (`env`, `waitUntil`); edge adapters pass it, and
      * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).
      */
     fetch(req, platform) {
-        // A real `Request` satisfies `RequestSource`, so it's passed straight through — no per-request
+        // A real `Request` satisfies `RequestSource`, so it's passed straight through - no per-request
         // wrapper allocation on the Web/Bun hot path.
         return this.fetchSource(req, platform);
     }
     fetchSource(source, platform) {
-        // Off path (default): straight through — one property check, no closure, no promise.
+        // Off path (default): straight through - one property check, no closure, no promise.
         if (this.capacityGate === undefined)
             return this.fetchSourceInner(source, platform);
         return this.admitGated(requestOf(source), () => this.fetchSourceInner(source, platform));
@@ -856,7 +823,7 @@ export class Server {
         if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
             return outcome;
         }
-        // onResponse sees every response — success, validation error, 404/405, timeout, onRequest
+        // onResponse sees every response - success, validation error, 404/405, timeout, onRequest
         // short-circuit; normalize to a promise, then thread through the hooks.
         return outcome instanceof Promise
             ? outcome.then((response) => this.applyOnResponseAndFinalize(response, this.takeResponseRequest(source)))
@@ -881,7 +848,7 @@ export class Server {
     /**
      * Run `produce` under the capacity gate: admit → run → release exactly once when the response is
      * produced (or the run throws). Only reached when {@link capacityGate} is set, so the off path pays
-     * nothing. The slot is held for the duration of handler execution, not the streaming of the body —
+     * nothing. The slot is held for the duration of handler execution, not the streaming of the body -
      * capacity here bounds concurrent *work*, matching how in-flight is counted.
      */
     admitGated(req, produce) {
@@ -908,7 +875,7 @@ export class Server {
             release();
             throw error;
         }
-        // Release the slot once the response settles — on resolve OR reject — via `finally`, which passes
+        // Release the slot once the response settles - on resolve OR reject - via `finally`, which passes
         // the value/rejection through unchanged. (A single settle hook, rather than separate then-arms: the
         // request pipeline resolves handler errors to a Response, so a rejection arm would be unreachable.)
         if (outcome instanceof Promise)
@@ -917,11 +884,11 @@ export class Server {
         return outcome;
     }
     /**
-     * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the
+     * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` - the
      * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici
      * `Response` build + body drain (the bulk of the Node bridge cost, measured ≈4µs/req). A handler that
      * returns a `Response`, an error/short-circuit, or any registered `onResponse` hook falls back to the
-     * full Web path (`{ kind: "response" }`), so behavior is identical — only the common JSON-data case is
+     * full Web path (`{ kind: "response" }`), so behavior is identical - only the common JSON-data case is
      * faster. Same lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final
      * render differs.
      */
@@ -929,7 +896,7 @@ export class Server {
         return this.resolveNodeSource(req, platform);
     }
     resolveNodeSource(source, platform, suppliedRuntime) {
-        // onResponse hooks transform a Response, and the capacity gate wraps the Web response path — both
+        // onResponse hooks transform a Response, and the capacity gate wraps the Web response path - both
         // force the Web path here (the gated `fetchSource` admits/sheds/releases); wrap its result.
         if (this.onResponseHooks.length > 0 ||
             this.onResponseFinalizedHooks.length > 0 ||
@@ -949,7 +916,7 @@ export class Server {
         return this.dispatch(source, platform, runtime.toOutcome, runtime.fromResponse, runtime.timeout, false);
     }
     /**
-     * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS
+     * 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
      * `upgrade()` rejected, or the path was malformed → return `response`), or `upgrade` (perform the
      * runtime upgrade, then dispatch the native socket's events to `handler`, seeding `ws.data` with
@@ -986,7 +953,7 @@ export class Server {
                 return { kind: "reject", response: jsonError(403, "forbidden_origin") };
         }
         else if (origin !== null && !wsSameOrigin(origin, req)) {
-            // Secure default (no explicit `allowedOrigins`): reject a CROSS-ORIGIN browser handshake — the
+            // Secure default (no explicit `allowedOrigins`): reject a CROSS-ORIGIN browser handshake - the
             // CSWSH case, since browsers send cookies on WS handshakes and don't apply CORS. Non-browser
             // clients send no `Origin` and pass; same-origin browsers pass. Set `allowedOrigins` to permit
             // specific cross-origin clients (or `() => true` for a genuinely public socket).
@@ -1034,7 +1001,7 @@ export class Server {
      * result + `set` into the output `T` (`toResponse` → a Web `Response`; `toNodeOutcome` → node-direct
      * primitives), `wrapResponse` lifts an early/error `Response` into that same `T`, and `onTimeout`
      * produces the 503. The Web `fetch` and `resolveNode` are thin callers over this one routing +
-     * context + lifecycle implementation — no duplication across the trust boundary.
+     * 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. */
@@ -1043,7 +1010,7 @@ export class Server {
         return { ...platform, clientIp: derived };
     }
     dispatch(source, platform, finalize, wrapResponse, onTimeout, 
-    // True only from the Web `fetch` path — unlocks each route's fused lane, whose output type IS
+    // True only from the Web `fetch` path - unlocks each route's fused lane, whose output type IS
     // `Response` (`T = Response` there by construction; the node path always passes false).
     webFast) {
         // Resolve the trust declaration into the platform's `clientIp` ONCE, here at the shared funnel, so
@@ -1059,7 +1026,7 @@ export class Server {
     }
     /**
      * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the
-     * common case — e.g. CORS returning `undefined` for a non-preflight request): an `async` version
+     * common case - e.g. CORS returning `undefined` for a non-preflight request): an `async` version
      * here put EVERY request of any app with one onRequest hook onto the promise machinery, profiled
      * at ~13% of a realistic request. The first hook that returns a Promise hands the REMAINING
      * hooks to the async continuation; behavior is identical.
@@ -1085,7 +1052,7 @@ export class Server {
         return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
     }
     /** Async tail of {@link runWithOnRequest}: applies the first awaited hook's outcome, then runs
-     * the remaining hooks (awaiting freely — we're already async here). */
+     * the remaining hooks (awaiting freely - we're already async here). */
     async continueOnRequest(first, nextIndex, originalRequest, sourceAtAwait, platform, finalize, wrapResponse, onTimeout, webFast) {
         let current = sourceAtAwait;
         let early = first;
@@ -1140,7 +1107,7 @@ export class Server {
     /** Run a route that has already been matched by the runtime or Nifra's portable router. */
     runMatched(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
         // 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.
+        // (with the body buffered). All non-idempotent routes skip straight to the lanes - no added cost.
         // 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, {
@@ -1188,7 +1155,7 @@ export class Server {
         const outcome = webFast && plan.fusedWeb !== undefined
             ? plan.fusedWeb(source, params, search, signal, budget, platform, false)
             : plan.run(this, entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
-        // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
+        // 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) {
             const timedOut = admission?.inherited === true
@@ -1227,11 +1194,11 @@ export class Server {
     }
     /**
      * 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
+     * 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
      * (a thrown `Response` is control flow; anything else is a logged flat 500). This is where nifra skips
-     * the per-request async-frame tax — the same win codegen routers get, but without `eval`.
+     * the per-request async-frame tax - the same win codegen routers get, but without `eval`.
      */
     runBare(entry, ctx, finalize, wrapResponse) {
         let result;
@@ -1249,12 +1216,12 @@ export class Server {
         }
         return finalize(result, responseSet(ctx));
     }
-    /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError
+    /** 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 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
+     * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair - same
      * decoration order, same error routing (thrown `Response` = control flow; anything else logs and
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
@@ -1266,7 +1233,7 @@ export class Server {
             return jsonError(500, "internal_error");
         };
         if (contextless && decorations === undefined) {
-            // `() => ...` can't observe the context — skip allocating one entirely (errors still build
+            // `() => ...` can't observe the context - skip allocating one entirely (errors still build
             // one for the structured log, exactly like runContextlessBare).
             const contextlessHandler = handler;
             return (source, params, search, signal, budget, platform, nativeContext) => {
@@ -1355,10 +1322,10 @@ export class Server {
             return Promise.resolve(wrapResponse(jsonError(415, "unsupported_media_type")));
         }
         // Inline fast path (profiled): a framed, in-cap, non-chunked body parses with the native
-        // `req.json()` directly — one promise, one `.then` closure per request. The generic
+        // `req.json()` directly - one promise, one `.then` closure per request. The generic
         // `readBoundedJson` (an extra async-fn frame + per-request `finish`/`applyValidation`
         // closures) is kept for the chunked / length-less / oversized cases it exists for.
-        // Semantics are identical to readBoundedJsonSource — same checks, same error codes.
+        // Semantics are identical to readBoundedJsonSource - same checks, same error codes.
         const declared = headerOf(source, "content-length");
         if (declared !== null) {
             const length = parseContentLength(declared);
@@ -1386,7 +1353,7 @@ export class Server {
             return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
         }
     }
-    /** Validate + run the handler for the bodyOnly path — shared by the inline fast path and the
+    /** Validate + run the handler for the bodyOnly path - shared by the inline fast path and the
      * streaming fallback. A method (not per-request closures) so the hot path allocates nothing
      * beyond the one `.then` continuation. */
     finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse) {
@@ -1484,7 +1451,7 @@ export class Server {
     }
     runQueryOnly(entry, ctx, finalize, wrapResponse) {
         try {
-            // Call the validator directly for the raw StandardResult (read `.issues`/`.value`) — skip
+            // Call the validator directly for the raw StandardResult (read `.issues`/`.value`) - skip
             // `validateStandard`'s per-request wrapper-object allocation, mirroring the bodyOnly path.
             const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
             if (validation instanceof Promise) {
@@ -1525,7 +1492,7 @@ export class Server {
     }
     /**
      * Thread the response through each global `onResponse` hook. Stays SYNCHRONOUS until a hook
-     * actually returns a Promise — an `async` version forced a promise + microtask on EVERY response
+     * actually returns a Promise - an `async` version forced a promise + microtask on EVERY response
      * of any app with an onResponse hook (cors/securityHeaders/etag/timing all use onResponse), the
      * same ~13%/req tax the onRequest walk was de-async'd to avoid. The first async hook hands the
      * rest to {@link continueOnResponse}.
@@ -1604,7 +1571,7 @@ export class Server {
     /**
      * Bound the response time. On timeout we abort `ctx.signal` (so cancellation-aware
      * handlers can bail) and return 503; the in-flight work keeps running but its
-     * result is discarded — JS can't forcibly cancel a promise.
+     * result is discarded - JS can't forcibly cancel a promise.
      */
     async withTimeout(work, controller, onTimeout, timeoutMs) {
         let timer;
@@ -1655,7 +1622,7 @@ export class Server {
                     return wrapResponse(queryError);
             }
             // Context extensions: static decorations, then per-request derives.
-            // Each hook below only awaits when it actually returns a Promise — a sync hook
+            // Each hook below only awaits when it actually returns a Promise - a sync hook
             // skips the microtask tick (a fast-path; ~64 ns/hook).
             if (entry.hasDecorations)
                 Object.assign(ctx, entry.decorations); // skip the no-op on bare routes
@@ -1686,6 +1653,35 @@ export class Server {
                     result = transformed instanceof Promise ? await transformed : transformed;
                 }
             }
+            // The response contract is checked LAST, after afterHandle, so it holds what actually ships
+            // rather than what the handler happened to return. Only reached by a contracted route: the
+            // registration decision above kept those off the fused/native lanes for exactly this step.
+            const contract = entry.responseContract;
+            if (contract !== undefined) {
+                const checked = contract.runtime.check(contract.schema, result);
+                const outcome = checked instanceof Promise ? await checked : checked;
+                if (outcome.kind === "violation") {
+                    // The handler broke a contract it declared itself, so this is a server fault, not the
+                    // caller's. Fail closed: the undeclared payload is never sent, and the detail goes to the
+                    // (redacting) logger rather than to the client.
+                    this.logger.error("response contract violation", {
+                        method: ctx.req.method,
+                        path: pathnameOf(ctx.req.url),
+                        // `detail`, not `message`: the logger uses `message` for its own first argument, so a
+                        // field of that name is silently overwritten and the diagnosis disappears.
+                        detail: outcome.message,
+                    });
+                    return wrapResponse(jsonError(500, "internal_error"));
+                }
+                if (outcome.kind === "warn") {
+                    this.logger.warn("response contract", {
+                        method: ctx.req.method,
+                        path: pathnameOf(ctx.req.url),
+                        detail: outcome.message,
+                    });
+                }
+                result = outcome.value;
+            }
             return finalize(result, responseSet(ctx));
         }
         catch (err) {
@@ -1693,7 +1689,7 @@ export class Server {
         }
     }
     async handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
-        // A *thrown* Response is deliberate control flow, not an error — a guard throws a redirect/401,
+        // A *thrown* Response is deliberate control flow, not an error - a guard throws a redirect/401,
         // an action throws an error page. Return it as-is (Remix/SvelteKit semantics); don't run onError
         // or log it as a 500. This is what makes `throw redirect(...)` / `requireSession(...)` work from
         // any handler or loader.
@@ -1711,7 +1707,7 @@ export class Server {
         this.logRequestError(err, ctx);
         return wrapResponse(jsonError(500, "internal_error"));
     }
-    /** Log an unhandled request error to the (redacting) logger — shared by {@link runLifecycle} and the
+    /** Log an unhandled request error to the (redacting) logger - shared by {@link runLifecycle} and the
      * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */
     logRequestError(err, ctx) {
         this.logger.error("unhandled request error", {
@@ -1738,7 +1734,7 @@ export class Server {
             parsed = form;
         }
         else {
-            // multipart/form-data (file uploads) stays 415 on the schema path by design — files don't
+            // multipart/form-data (file uploads) stays 415 on the schema path by design - files don't
             // fit a value schema; use a schema-less route + @nifrajs/uploads helpers for those.
             return jsonError(415, "unsupported_media_type");
         }
@@ -1785,12 +1781,12 @@ export class Server {
     /**
      * Read the body as text, capped at `maxBodyBytes`. Rejects (`null`) on a
      * `Content-Length` over the cap *before* buffering, and aborts mid-stream once the
-     * running byte count exceeds it — so a lying or absent length can't force us to
+     * running byte count exceeds it - so a lying or absent length can't force us to
      * buffer an oversized payload.
      *
      * Fast path: when a non-chunked request carries a `Content-Length` within the cap,
-     * a native `req.json()` is already bounded — under HTTP/1.1 + HTTP/2 framing the
-     * runtime delivers at most `Content-Length` bytes — so we skip the manual stream
+     * a native `req.json()` is already bounded - under HTTP/1.1 + HTTP/2 framing the
+     * runtime delivers at most `Content-Length` bytes - so we skip the manual stream
      * loop and a separate text decode. It trusts the wire
      * *framing*, not the header value: nifra only ever receives framed Requests from the
      * runtime's HTTP server, never a hand-built one with a mismatched length. Chunked or
@@ -1847,7 +1843,7 @@ export class Server {
      * capture semantics; static and `:param` routes take the native lane. */
     buildBunNativeRoutes() {
         // 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`
+        // 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 ||
@@ -1883,7 +1879,7 @@ export class Server {
      * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).
      *
      * `reusePort` sets `SO_REUSEPORT` so **multiple processes can bind the same port** and the kernel
-     * load-balances connections across them — the standard way to use every core (Bun is
+     * load-balances connections across them - the standard way to use every core (Bun is
      * single-threaded per process). Spawn one process per core, each calling
      * `app.listen(PORT, { reusePort: true })`; see `examples/cluster.ts`. Every process must opt in,
      * and all of them must be the same app. Linux balances ~evenly; macOS accepts the flag but may
@@ -1903,14 +1899,14 @@ export class Server {
         }
         // Bun's `Server` is the concrete handle; we expose the stable `RunningServer`
         // subset so the public types don't depend on the ambient `Bun` global. The cast
-        // bridges them — Bun's `.port` is `number | undefined` (undefined only for unix
+        // bridges them - Bun's `.port` is `number | undefined` (undefined only for unix
         // sockets, never a TCP `listen`) and its `.stop` returns a promise we don't await.
-        // Pass only the request — Bun's `fetch` 2nd arg is the Bun `Server`, not our `platform`.
+        // Pass only the request - Bun's `fetch` 2nd arg is the Bun `Server`, not our `platform`.
         // With WS routes, hand Bun a `websocket` config + a fetch that upgrades matching requests (the
         // `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
+        // `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 installed `.use(websocket())` runtime — non-null
+        // 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
@@ -1953,7 +1949,7 @@ export class Server {
     }
     /**
      * Gracefully stop: wait for in-flight requests to finish (up to `drainMs`), then
-     * issue a single terminal stop — graceful if everything drained, forced if
+     * issue a single terminal stop - graceful if everything drained, forced if
      * stragglers remain. Safe to call when not listening.
      *
      * The Bun semantics: poll `pendingRequests` (awaiting
@@ -1974,7 +1970,7 @@ export class Server {
         server.stop(server.pendingRequests > 0); // force-close iff stragglers remain past the deadline
     }
     installSignalHandlers() {
-        // Drain, then let the process exit naturally — the stopped server no longer
+        // Drain, then let the process exit naturally - the stopped server no longer
         // holds the event loop open. Opt-in (`gracefulSignals`), so taking over the
         // signals is consented; we don't force `process.exit`.
         const onSignal = () => {
@@ -1985,66 +1981,14 @@ export class Server {
     }
 }
 /**
- * Create a new {@link Server}. Pass an `Env` to type the platform bindings — `server<Env>()` makes
+ * Create a new {@link Server}. Pass an `Env` to type the platform bindings - `server<Env>()` makes
  * `c.env: Env` in every handler + middleware, and types the `env` argument of `app.fetch` /
  * `toFetchHandler`. Omit it and `c.env` is `unknown` (validate/cast before use).
  */
 export function server(options) {
     // `Env` is a phantom type-level marker: the runtime `env` arrives via `app.fetch(req, { env })` at
-    // request time, not stored on the builder — so seed the context type with a cast (as `derive`/
+    // request time, not stored on the builder - so seed the context type with a cast (as `derive`/
     // `decorate` do for their `Ctx` extensions).
     return new Server(options);
 }
-/** The single hub Durable Object id nifra routes WS upgrades to (one hub per app — see `@nifrajs/workers`). */
-const NIFRA_WS_HUB_ID = "nifra-ws-hub";
-export function toFetchHandler(app, options) {
-    const scheduled = options?.scheduled;
-    const webSocketHub = options?.webSocketHub;
-    const resolveWs = app.resolveWebSocketUpgrade?.bind(app);
-    return {
-        fetch: (request, env, ctx) => {
-            const platform = { env, waitUntil: (promise) => ctx.waitUntil(promise) };
-            // WebSocket broadcast on Workers: route upgrades to the hub Durable Object (it holds the
-            // connections + runs the app's pub/sub, so `app.publish` reaches every client). The hub itself
-            // resolves the route and rejects non-WS paths. See `@nifrajs/workers`' `createWebSocketHub`.
-            if (webSocketHub !== undefined &&
-                request.headers.get("upgrade")?.toLowerCase() === "websocket") {
-                const ns = webSocketHub(env);
-                return ns.get(ns.idFromName(NIFRA_WS_HUB_ID)).fetch(request);
-            }
-            // Workers WebSockets: a WS upgrade for a registered route becomes a `WebSocketPair` + a 101.
-            // Feature-detected, so non-Workers edge runtimes (which lack `WebSocketPair` — e.g. Deno Deploy
-            // uses `@nifrajs/deno`'s `Deno.upgradeWebSocket`) simply fall through to the normal `fetch`.
-            const Pair = globalThis.WebSocketPair;
-            if (resolveWs !== undefined && Pair !== undefined) {
-                const accept = (outcome) => {
-                    if (outcome.kind === "pass")
-                        return app.fetch(request, platform);
-                    if (outcome.kind === "reject")
-                        return outcome.response;
-                    const pair = new Pair();
-                    const server = pair[1];
-                    server.accept();
-                    // 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,
-                    });
-                    // `webSocket` is a Workers-only `ResponseInit` field (absent from the standard type), and a
-                    // 101 status is only valid on the Workers runtime — both gated by the `Pair` feature check.
-                    return new Response(null, { status: 101, webSocket: pair[0] });
-                };
-                const out = resolveWs(request, platform);
-                return out instanceof Promise ? out.then(accept) : accept(out);
-            }
-            return app.fetch(request, platform);
-        },
-        ...(scheduled !== undefined
-            ? {
-                scheduled: (controller, env, ctx) => scheduled(controller, { env, waitUntil: (promise) => ctx.waitUntil(promise) }),
-            }
-            : {}),
-    };
-}
 //# sourceMappingURL=server.js.map