@nifrajs/core 2.2.0 → 2.3.0

package/dist/server/edge.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The edge adapter: a nifra app presented as a Cloudflare-Workers-shaped `ExportedHandler`.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * `toFetchHandler` never touches the `Server` class. It takes a STRUCTURAL app - anything with `fetch`, and
+ * optionally `resolveWebSocketUpgrade` - which is what lets it wrap an app it has no access to the
+ * internals of, and what makes it a separate concern from the kernel rather than a method on it. It sat
+ * in `server.ts` for no reason other than that both were written the same week.
+ *
+ * The types here are all structural too (`ExecutionContext`, `ScheduledController`,
+ * `DurableObjectNamespaceLike`), so `@nifrajs/core` declares the Workers surface it needs instead of
+ * depending on `@cloudflare/workers-types`. The real Workers types satisfy them.
+ *
+ * The `MaybePromise` import is type-only and erased, so there is no runtime cycle back into the kernel.
+ */
+import type { Platform } from "./context.js";
+import type { MaybePromise } from "./server.js";
+import type { WebSocketUpgradeOutcome } from "./websocket.js";
+/** A Cloudflare Workers-style execution context (the `fetch` 3rd arg). Structural - only
+ * `waitUntil` is used; declared here so `@nifrajs/core` needs no Workers type dependency. */
+export interface ExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** A Cloudflare Workers-style scheduled (cron) controller. Structural - no Workers type dependency. */
+export interface ScheduledController {
+    /** Epoch ms the run was scheduled for. */
+    readonly scheduledTime: number;
+    /** The matching cron expression from `wrangler.toml` `[triggers]`. */
+    readonly cron: string;
+    /** Tell the platform not to retry this run on failure. */
+    noRetry(): void;
+}
+/** A nifra cron handler: the platform controller + the same typed `env`/`waitUntil` nifra threads into
+ * request handlers. Schedule background work with `waitUntil` so it outlives the trigger. */
+export type ScheduledHandler<Env = unknown> = (controller: ScheduledController, context: {
+    readonly env: Env;
+    waitUntil(promise: Promise<unknown>): void;
+}) => MaybePromise<void>;
+/** Structural view of a Cloudflare Durable Object namespace binding - keeps `@cloudflare/workers-types`
+ * out of `@nifrajs/core`. The real `DurableObjectNamespace` satisfies it. */
+export interface DurableObjectNamespaceLike {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+/**
+ * Adapt a nifra app to an edge "ExportedHandler" - use it as a Cloudflare Workers (or any
+ * `fetch(request, env, ctx)` runtime) default export. It threads `env` + `ctx.waitUntil` into the
+ * nifra Context, so handlers read `c.env` and schedule background work via `c.waitUntil`:
+ *
+ *   export default toFetchHandler(app)
+ *
+ * Pass `{ scheduled }` to also export a Workers cron handler (for a `[triggers]` schedule) - it
+ * receives the platform controller plus the same typed `env`/`waitUntil`:
+ *
+ *   export default toFetchHandler(app, {
+ *     scheduled: (controller, { env, waitUntil }) =>
+ *       waitUntil(env.KV.put("last-run", String(controller.scheduledTime))),
+ *   })
+ *
+ * No Workers-only deps - `app.fetch` stays a portable Web-standard handler; this is the thin
+ * shim from the platform's 3-arg `fetch`/`scheduled` to it.
+ */
+export declare function toFetchHandler<Env = unknown>(app: {
+    fetch(request: Request, platform?: Platform<Env>): MaybePromise<Response>;
+    resolveWebSocketUpgrade?(request: Request, platform?: Platform<Env>): MaybePromise<WebSocketUpgradeOutcome>;
+}, options?: {
+    scheduled?: ScheduledHandler<Env>;
+    /**
+     * Route WebSocket upgrades to a Durable Object that holds the connections and runs the app's
+     * pub/sub - enabling cross-connection broadcast (`app.publish`) on Cloudflare Workers, where a
+     * stateless isolate can't. Pass the DO namespace binding from `env`; pair with `@nifrajs/workers`'
+     * `createWebSocketHub(app)` (the DO class) + a `wrangler.toml` binding. Without this, WS upgrades use
+     * a per-connection `WebSocketPair` (no broadcast).
+     */
+    webSocketHub?: (env: Env) => DurableObjectNamespaceLike;
+}): {
+    fetch(request: Request, env: Env, ctx: ExecutionContext): MaybePromise<Response>;
+    scheduled?(controller: ScheduledController, env: Env, ctx: ExecutionContext): MaybePromise<void>;
+};
+//# sourceMappingURL=edge.d.ts.map

package/dist/server/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/server/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAqB,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAEhF;6FAC6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C;AAED,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;6FAC6F;AAC7F,MAAM,MAAM,gBAAgB,CAAC,GAAG,GAAG,OAAO,IAAI,CAC5C,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAAE,KACvE,YAAY,CAAC,IAAI,CAAC,CAAA;AAQvB;6EAC6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;CACjE;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAG,OAAO,EAC1C,GAAG,EAAE;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;IACzE,uBAAuB,CAAC,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,GACvB,YAAY,CAAC,uBAAuB,CAAC,CAAA;CACzC,EACD,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACjC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,0BAA0B,CAAA;CACxD,GACA;IACD,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;IAChF,SAAS,CAAC,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;CACjG,CAkDA"}

package/dist/server/edge.js

@@ -0,0 +1,71 @@
+/** 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";
+/**
+ * Adapt a nifra app to an edge "ExportedHandler" - use it as a Cloudflare Workers (or any
+ * `fetch(request, env, ctx)` runtime) default export. It threads `env` + `ctx.waitUntil` into the
+ * nifra Context, so handlers read `c.env` and schedule background work via `c.waitUntil`:
+ *
+ *   export default toFetchHandler(app)
+ *
+ * Pass `{ scheduled }` to also export a Workers cron handler (for a `[triggers]` schedule) - it
+ * receives the platform controller plus the same typed `env`/`waitUntil`:
+ *
+ *   export default toFetchHandler(app, {
+ *     scheduled: (controller, { env, waitUntil }) =>
+ *       waitUntil(env.KV.put("last-run", String(controller.scheduledTime))),
+ *   })
+ *
+ * No Workers-only deps - `app.fetch` stays a portable Web-standard handler; this is the thin
+ * shim from the platform's 3-arg `fetch`/`scheduled` to it.
+ */
+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=edge.js.map

package/dist/server/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/server/edge.ts"],"names":[],"mappings":"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"}

package/dist/server/install.d.ts

@@ -18,4 +18,6 @@ export declare const INSTALL_SSE: unique symbol;
 export declare const INSTALL_NODE_DIRECT: unique symbol;
 /** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
 export declare const INSTALL_WS: unique symbol;
+/** @internal Install the response-contract runtime on a server (called by the `responseContract()` plugin). */
+export declare const INSTALL_RESPONSE_CONTRACT: unique symbol;
 //# sourceMappingURL=install.d.ts.map

package/dist/server/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/server/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAwD,CAAA;AAEjG,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAE1C,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAA;AAEjF,8FAA8F;AAC9F,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAA;AAEjF,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAwD,CAAA;AAEjG,gGAAgG;AAChG,eAAO,MAAM,UAAU,EAAE,OAAO,MAA+C,CAAA"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/server/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAwD,CAAA;AAEjG,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAE1C,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAA;AAEjF,8FAA8F;AAC9F,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAA;AAEjF,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAwD,CAAA;AAEjG,gGAAgG;AAChG,eAAO,MAAM,UAAU,EAAE,OAAO,MAA+C,CAAA;AAE/E,+GAA+G;AAC/G,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAE9C,CAAA"}

package/dist/server/install.js

@@ -18,4 +18,6 @@ export const INSTALL_SSE = Symbol.for("@nifrajs/core/install-sse");
 export const INSTALL_NODE_DIRECT = Symbol.for("@nifrajs/core/install-node-direct");
 /** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
 export const INSTALL_WS = Symbol.for("@nifrajs/core/install-ws");
+/** @internal Install the response-contract runtime on a server (called by the `responseContract()` plugin). */
+export const INSTALL_RESPONSE_CONTRACT = Symbol.for("@nifrajs/core/install-response-contract");
 //# sourceMappingURL=install.js.map

package/dist/server/install.js.map

@@ -1 +1 @@
-{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/server/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,uGAAuG;AACvG,MAAM,CAAC,MAAM,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAC5D,qCAAqC,CACtC,CAAA;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA"}
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/server/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,uGAAuG;AACvG,MAAM,CAAC,MAAM,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAC5D,qCAAqC,CACtC,CAAA;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;AAE/E,+GAA+G;AAC/G,MAAM,CAAC,MAAM,yBAAyB,GAAkB,MAAM,CAAC,GAAG,CAChE,yCAAyC,CAC1C,CAAA"}

package/dist/server/logger.d.ts

@@ -12,12 +12,12 @@ export interface Logger {
 }
 /**
  * Tunes redaction. Key-name redaction always runs; the rest is **opt-in**:
- * - `keyParts` — extra case-insensitive key fragments, added to the built-in denylist.
- * - `valuePatterns` — regexes matched against string **values** *and* the log message; each match is
+ * - `keyParts` - extra case-insensitive key fragments, added to the built-in denylist.
+ * - `valuePatterns` - regexes matched against string **values** *and* the log message; each match is
  *   replaced with the placeholder. This is the value-scanning hook for secrets that land in a value or
- *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided — the
+ *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided - the
  *   default path does no value scanning, so it stays allocation-light. See {@link commonSecretPatterns}.
- * - `placeholder` — the replacement string (default `[REDACTED]`).
+ * - `placeholder` - the replacement string (default `[REDACTED]`).
  */
 export interface RedactOptions {
     readonly keyParts?: readonly string[];
@@ -25,7 +25,7 @@ export interface RedactOptions {
     readonly placeholder?: string;
 }
 /**
- * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} - opt in by
  * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
  * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
  * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
@@ -39,11 +39,11 @@ export declare const commonSecretPatterns: ReadonlyArray<RegExp>;
 export declare function redactLogFields(fields: LogFields, options?: RedactOptions): LogFields;
 /**
  * The default logger: one redacted JSON object per line. `write` is injectable for tests or
- * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * alternative sinks (defaults to stderr). `options` tunes redaction - pass `valuePatterns` (e.g.
  * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
  * (`level`, `message`, `time`) always win over user fields of the same name.
  */
 export declare function jsonLogger(write?: (line: string) => void, options?: RedactOptions): Logger;
-/** Discards everything — for tests, or when log output is handled elsewhere. */
+/** Discards everything - for tests, or when log output is handled elsewhere. */
 export declare const silentLogger: Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/server/logger.js

@@ -22,7 +22,7 @@ const SENSITIVE_KEY_PARTS = [
     "ssn",
 ];
 /**
- * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} - opt in by
  * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
  * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
  * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
@@ -72,7 +72,7 @@ function redactValue(value, seen, config) {
         return value.map((item) => redactValue(item, seen, config));
     const out = {};
     for (const [key, val] of Object.entries(value)) {
-        // A sensitive key wins outright (don't scan it) — the whole value is replaced.
+        // A sensitive key wins outright (don't scan it) - the whole value is replaced.
         out[key] = isSensitiveKey(key, config.keyParts)
             ? config.placeholder
             : redactValue(val, seen, config);
@@ -92,7 +92,7 @@ function writeToStderr(line) {
 }
 /**
  * The default logger: one redacted JSON object per line. `write` is injectable for tests or
- * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * alternative sinks (defaults to stderr). `options` tunes redaction - pass `valuePatterns` (e.g.
  * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
  * (`level`, `message`, `time`) always win over user fields of the same name.
  */
@@ -115,7 +115,7 @@ export function jsonLogger(write = writeToStderr, options) {
     };
 }
 const noop = () => undefined;
-/** Discards everything — for tests, or when log output is handled elsewhere. */
+/** Discards everything - for tests, or when log output is handled elsewhere. */
 export const silentLogger = {
     debug: noop,
     info: noop,

package/dist/server/registry.d.ts

@@ -83,20 +83,20 @@ export type WsRouteInfoFor<Path extends string, In extends StandardSchemaV1 | un
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *
- * SCALING CEILING (measured — see many-routes.test-d.ts and the isolation study below): a single
- * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause — in isolation it
+ * SCALING CEILING (measured - see many-routes.test-d.ts and the isolation study below): a single
+ * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause - in isolation it
  * accumulates 1000+ routes cleanly, and heavy per-route `Params<Path>`/schema inference alone
  * reaches 600+. The wall is an INTERACTION unique to the fluent builder: each `.get(path, handler)`
  * both (a) computes the handler's context type from the path (`c.params.id` inferred from `:id`)
  * AND (b) returns `Server<AddRoute<growing-R, …>, Ctx>`. Neither alone strains the compiler; the
- * PRODUCT — recomputing the handler context while re-threading the ever-larger registry at each of
- * N steps — exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
+ * PRODUCT - recomputing the handler context while re-threading the ever-larger registry at each of
+ * N steps - exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
  * O(N) and inherent to any builder that infers handler context AND accumulates a typed route
  * registry (Elysia/tRPC/hono's typed clients cap the same way); it is not fixable by reshaping
  * AddRoute. Past ~90 routes, use a path that DOESN'T form the product: split into domain groups and
  * `.merge()` them (each group is a short chain; a merge is one `R & R2` intersection with no
  * per-call context work), or contract-first `implement()` (the registry is one object type declared
- * upfront — no grow-R-per-call, so no ceiling at all).
+ * upfront - no grow-R-per-call, so no ceiling at all).
  */
 export type AddRoute<R extends Registry, Method extends string, Path extends string, Info extends RouteInfo> = R & {
     [P in Path]: {

package/dist/server/response-contract-lane.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Making a route's declared `response` schema mean something at runtime.
+ *
+ * ## The gap this closes
+ *
+ * A `response` schema is a LOWER bound, not an upper one. It says "at least these fields, of these
+ * types"; it never said "only these". TypeScript does not close the gap either - excess-property
+ * checking fires on a fresh object literal in an annotated position, and a handler is neither: it is a
+ * contextually-typed argument that usually returns a variable. So this compiles, and ships every field:
+ *
+ *     app.get("/me", { response: PublicUser }, async () => {
+ *       const user = await db.users.find(id)   // { id, name, email, passwordHash, ... }
+ *       return user                            // all of it goes on the wire
+ *     })
+ *
+ * The client's type says `{ id, name }`, so the leak is invisible from both ends. And it can appear
+ * with no code change at all: add a column to `users`, and the next deploy ships it to browsers.
+ *
+ * ## Why the behaviour follows the schema, not this module
+ *
+ * Standard Schema exposes exactly one operation - `validate` - and no way to enumerate a schema's
+ * declared keys. So a projection of "just the declared fields" cannot be written generically here;
+ * the only clean value available is whatever `validate()` returns. That is deliberate on the spec's
+ * part, and it means enforcement inherits each validator's own semantics:
+ *
+ *   - a STRIPPING schema (zod, valibot) returns a cleaned value -> the undeclared fields are removed
+ *   - a STRICT schema (`@nifrajs/schema`'s `t.object`) reports issues -> the response is a violation
+ *
+ * That is not an inconsistency to paper over: a strict schema has already declared that extra fields
+ * are an error, and a stripping one has declared they are ignorable. Enforcement honours what the
+ * author wrote rather than overriding it.
+ */
+import type { StandardSchemaV1 } from "../schema/standard.js";
+import type { IdentityPlugin } from "./plugin.js";
+/**
+ * How hard a declared `response` schema is held.
+ *
+ *   - `warn`    - check and log; the response is sent UNCHANGED, so enabling it cannot break anything.
+ *   - `enforce` - serialize the validated value, so undeclared data cannot reach the wire.
+ *
+ * There is no `off`: not installing the plugin IS off, and that is what keeps this module out of an
+ * app's bundle entirely rather than shipping a disabled branch to everyone.
+ */
+export type ResponseContractMode = "warn" | "enforce";
+/** The outcome of checking one handler result against its declared response schema. */
+export type ResponseContractOutcome = 
+/** Nothing to report. `value` is what should be serialized (the original result, or the cleaned one). */
+{
+    readonly kind: "ok";
+    readonly value: unknown;
+}
+/** `warn` only: the payload differed from the contract. The ORIGINAL result is still served. */
+ | {
+    readonly kind: "warn";
+    readonly value: unknown;
+    readonly message: string;
+}
+/** `enforce` only: the payload cannot be reconciled with the contract, so it must not be sent. */
+ | {
+    readonly kind: "violation";
+    readonly message: string;
+};
+/**
+ * Check one result against the route's declared response schema.
+ *
+ * Returns synchronously when the schema does (the common case), so an app that opts in does not pay a
+ * microtask per response for a check that had no work to do.
+ */
+export declare function checkResponseContract(schema: StandardSchemaV1, result: unknown, mode: "warn" | "enforce"): ResponseContractOutcome | Promise<ResponseContractOutcome>;
+/**
+ * What the server holds when the plugin is installed. The kernel calls `check` through this object and
+ * never imports the implementation, so an app that does not install the plugin does not carry it.
+ */
+export interface ResponseContractRuntime {
+    readonly mode: ResponseContractMode;
+    check(schema: StandardSchemaV1, result: unknown): ResponseContractOutcome | Promise<ResponseContractOutcome>;
+}
+/**
+ * Hold every route's declared `response` schema to what the handler actually returned.
+ *
+ *     app.use(responseContract("enforce"))
+ *
+ * Install it before the routes it should cover - like `idempotency()`, the decision is made per route
+ * at registration, so routes registered earlier are not retroactively covered.
+ *
+ * A contracted route leaves the fused and native fast paths, because the check needs the handler's
+ * value before it becomes bytes. That is the same trade an idempotent route makes, and the reason this
+ * is opt-in rather than always on.
+ */
+export declare function responseContract(mode?: ResponseContractMode): IdentityPlugin;
+//# sourceMappingURL=response-contract-lane.d.ts.map

package/dist/server/response-contract-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-contract-lane.d.ts","sourceRoot":"","sources":["../../src/server/response-contract-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAiC,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAAA;AAErD,uFAAuF;AACvF,MAAM,MAAM,uBAAuB;AACjC,yGAAyG;AACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAClD,gGAAgG;GAC9F;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC9E,kGAAkG;GAChG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AA0B5D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAQ5D;AA0BD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;IACnC,KAAK,CACH,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CAC9D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,oBAA6B,GAAG,cAAc,CAUpF"}

package/dist/server/response-contract-lane.js

@@ -0,0 +1,81 @@
+import { INSTALL_RESPONSE_CONTRACT } from "./install.js";
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Top-level keys present in the handler's result but absent from the validated value. */
+function droppedKeys(result, value) {
+    if (!isPlainObject(result) || !isPlainObject(value))
+        return [];
+    return Object.keys(result).filter((k) => !(k in value));
+}
+function describeIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = Array.isArray(issue.path)
+            ? issue.path
+                .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+                .join(".")
+            : "";
+        return path === "" ? issue.message : `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Check one result against the route's declared response schema.
+ *
+ * Returns synchronously when the schema does (the common case), so an app that opts in does not pay a
+ * microtask per response for a check that had no work to do.
+ */
+export function checkResponseContract(schema, result, mode) {
+    // A handler may return a raw Response as deliberate control flow (a redirect, a stream). There is no
+    // JSON payload to hold to the contract, and re-serializing one would corrupt it.
+    if (result instanceof Response || result === undefined)
+        return { kind: "ok", value: result };
+    const settled = schema["~standard"].validate(result);
+    return settled instanceof Promise
+        ? settled.then((r) => interpret(r, result, mode))
+        : interpret(settled, result, mode);
+}
+function interpret(settled, result, mode) {
+    if (settled.issues !== undefined) {
+        const message = `response does not satisfy its declared contract: ${describeIssues(settled.issues)}`;
+        // `warn` never changes what is served - it reports and gets out of the way, so switching it on can
+        // never be the thing that broke production.
+        return mode === "warn"
+            ? { kind: "warn", value: result, message }
+            : { kind: "violation", message };
+    }
+    const dropped = droppedKeys(result, settled.value);
+    if (mode === "enforce")
+        return { kind: "ok", value: settled.value };
+    return dropped.length === 0
+        ? { kind: "ok", value: result }
+        : {
+            kind: "warn",
+            value: result,
+            message: `response carries fields its contract does not declare: ${dropped.join(", ")}. They are being sent; \`responseContract: "enforce"\` would strip them.`,
+        };
+}
+/**
+ * Hold every route's declared `response` schema to what the handler actually returned.
+ *
+ *     app.use(responseContract("enforce"))
+ *
+ * Install it before the routes it should cover - like `idempotency()`, the decision is made per route
+ * at registration, so routes registered earlier are not retroactively covered.
+ *
+ * A contracted route leaves the fused and native fast paths, because the check needs the handler's
+ * value before it becomes bytes. That is the same trade an idempotent route makes, and the reason this
+ * is opt-in rather than always on.
+ */
+export function responseContract(mode = "warn") {
+    const runtime = {
+        mode,
+        check: (schema, result) => checkResponseContract(schema, result, mode),
+    };
+    const apply = (app) => {
+        ;
+        app[INSTALL_RESPONSE_CONTRACT](runtime);
+        return app;
+    };
+    return Object.assign(apply, { pluginName: "nifra:response-contract" });
+}
+//# sourceMappingURL=response-contract-lane.js.map

package/dist/server/response-contract-lane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-contract-lane.js","sourceRoot":"","sources":["../../src/server/response-contract-lane.ts"],"names":[],"mappings":"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"}