@nifrajs/core 5.0.0 → 5.2.0

package/src/server/server-types.ts

@@ -59,10 +59,18 @@ export interface ServerOptions {
    * `__proto__` key, or a `constructor` carrying a `prototype`, is the payload shape that turns a
    * later innocent merge/assign into prototype pollution. `"reject"` (default) answers the same
    * flat 400 as malformed JSON; `"strip"` removes the offending keys and continues; `"ignore"`
-   * parses as-is (only for routes that never merge body input into other objects). Clean payloads
-   * pay a substring pre-scan only - the deep walk runs solely on suspect text.
+   * parses as-is (only for routes that never merge body input into other objects). Every guarded
+   * payload pays one iterative pass over its parsed object nodes; `"ignore"` skips it.
    */
   readonly protoPoisoning?: "reject" | "strip" | "ignore"
+  /**
+   * Other sites whose HTML forms may post to a body-schema route: exact origins, or a function that
+   * receives the `Origin`. A urlencoded, multipart or `text/plain` body is one a form on any site can
+   * send with the visitor's cookies and no preflight, so one whose `Origin` names another site is
+   * refused with `403` before it is read. Same-origin posts and requests without an `Origin`, such
+   * as server-to-server calls, pass. JSON is not affected: a browser preflights it, so CORS decides.
+   */
+  readonly formOrigins?: ReadonlyArray<string> | ((origin: string) => boolean)
   /**
    * Declare that every `Request` reaching `app.fetch` was framed by a runtime HTTP parser, so its
    * `Content-Length` is an exact transport boundary rather than a hint. Set this ONLY when the
@@ -81,9 +89,12 @@ export interface ServerOptions {
    * untrusted input.
    */
   readonly trustBodyFraming?: boolean
-  /** 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). */
+  /**
+   * Max inbound WebSocket message size (bytes). A larger message never reaches the handler and the
+   * socket closes with `1009`. Default: `maxBodyBytes` (1 MB). Bun and Node stop buffering at the cap,
+   * so a huge frame is never held in memory; on Bun a mounted app's smaller cap, and on Deno and
+   * Workers every cap, is checked after the runtime has buffered the whole message.
+   */
   readonly wsMaxPayloadBytes?: number
   /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
   readonly requestTimeoutMs?: number
@@ -153,10 +164,13 @@ export interface ServerOptions {
    */
   readonly onValidationError?: RouteSchema["onValidationError"]
   /**
-   * What to do when an order-scoped hook (`derive`/`beforeHandle`/`around`/`aroundCapability`/
-   * `afterHandle`/`onError`/`decorate`) covers no route because it was added after the last route was
-   * registered. `register()` snapshots the current chain into each route as it is declared, so a hook
-   * appended after every route reaches nothing and is silently dead. `"warn"` (default) logs once at
+   * What to do when an order-scoped hook (`derive`/`authenticate`/`beforeHandle`/`around`/
+   * `aroundCapability`/`afterHandle`/`onError`/`decorate`) covers no route because it was added after
+   * the last route was registered. `register()` snapshots the current chain into each route as it is
+   * declared, so a hook appended after every route reaches nothing and is silently dead. A `merge()`d
+   * route keeps the chain of the server that declared it, so a hook followed only by merges is dead
+   * too. The same report covers `responseContract()` and `effectLedger()` installed after routes they
+   * would have covered (a declared response, declared capabilities). `"warn"` (default) logs once at
    * seal (first `listen()`/`fetch`/`resolveNode`); `"error"` throws a `FrameworkError`
    * (`UNUSED_SCOPED_HOOKS`); `"off"` skips the bookkeeping entirely, including the one-frame stack
    * capture. App-global hooks (`onRequest`/`onResponse`/...) are unaffected in every mode.

package/src/server/server.ts

@@ -23,6 +23,8 @@ import {
   leavePlugin,
   tagAdoption,
   tagHook,
+  tagMergeAuthGap,
+  tagRouteSite,
   tagScoped,
   tagStatic,
 } from "../internal/hook-origins.ts"
@@ -30,9 +32,10 @@ import {
   type AssuranceDeclaration,
   assuranceDeclarationsOf,
   assuranceEvidenceFor,
+  NIFRA_ASSURANCE_IDS,
 } from "../internal/route-assurance.ts"
 import { type CatalogRoute, RouteCatalog } from "../internal/route-catalog.ts"
-import { compileRouteOptions } from "../internal/route-compiler.ts"
+import { adoptRouteRuntimes, compileRouteOptions } from "../internal/route-compiler.ts"
 import {
   compileRouteExecutionPlan,
   type FusedBodyRunner,
@@ -67,19 +70,20 @@ import {
   type RawBodyReaders,
   UNLIMITED_BODY_BYTES,
 } from "./body.ts"
+import type { FormOrigins } from "./body-lane.ts"
 import {
   type ClientIpTrust,
   NIFRA_PLATFORM_CLIENT_IP_DERIVED,
   resolveClientIp,
 } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
-import "./core-copies.ts"
+import { mergeRefusal, recordCopyVersion } from "./core-copies.ts"
 import {
   hasLowercaseHeaderKeysMark,
   headerKeysAllLowercase,
   markLowercaseHeaderKeys,
 } from "./header-case.ts"
-import { headerObjectOf } from "./headers.ts"
+import { declaredHeaders, headerObjectOf } from "./headers.ts"
 import {
   isRoutableMethod,
   jsonError,
@@ -786,6 +790,7 @@ const RESPONSE_TIMEOUT = (): Response => jsonError(503, "request_timeout")
 // node-compat `process`, so `typeof process` does NOT gate it out there, yet reading `process.env`
 // throws `NotCapable` without `--allow-env`. The flag short-circuits before the env read on Deno (audit
 // off) while a production define still folds `<flag> && false` to `false` on every other runtime.
+// It must live in this module: imported from another, Bun leaves `<flag>,` at every folded guard.
 const hookAuditRuntime = typeof (globalThis as { Deno?: unknown }).Deno === "undefined"
 
 // This module's own path, captured once from a sentinel stack. Every internal frame of an
@@ -796,9 +801,10 @@ const SERVER_MODULE_PATH = /* @__PURE__ */ ((): string | undefined => {
   return frame?.match(/\(?([^()\s]+):\d+:\d+\)?\s*$/)?.[1]
 })()
 
-/** One `file:line:col` frame for the caller of an order-scoped hook method, for the unused-hook
- * report. Only ever called behind the `unusedScopedHooks !== "off"` guard, so the `Error` (the sole
- * non-trivial cost) is never constructed when the check is disabled. */
+/** One `file:line:col` frame for the caller of an order-scoped hook method or a route registration,
+ * for the unused-hook report and route provenance. Only ever called behind a development guard that
+ * also requires the feature to be on, so the `Error` (the sole non-trivial cost) is never constructed
+ * otherwise. */
 const captureCallerSite = (): string | undefined => {
   const stack = new Error().stack
   if (stack === undefined) return undefined
@@ -822,9 +828,19 @@ interface HookAuditState {
   readonly hasCustomLogger: boolean
   readonly sites: {
     readonly kind: string
+    /** Routes that captured the chain so far: merged routes excluded, they keep their own. */
     readonly routesAtPush: number
+    readonly mergedAtPush: number
     readonly site: string | undefined
   }[]
+  /** Registration-time plugins installed after routes they would have covered. */
+  readonly lateInstalls: {
+    readonly plugin: string
+    readonly site: string | undefined
+    readonly routes: readonly string[]
+  }[]
+  /** Routes adopted by `merge()`, which keep the chain of the server that declared them. */
+  merged: number
   checked: boolean
 }
 const hookAudit = /* @__PURE__ */ new WeakMap<object, HookAuditState>()
@@ -859,7 +875,14 @@ const beginHookAudit = (
   policy: "warn" | "error" | "off",
   hasCustomLogger: boolean,
 ): void => {
-  hookAudit.set(key, { policy, hasCustomLogger, sites: [], checked: false })
+  hookAudit.set(key, {
+    policy,
+    hasCustomLogger,
+    sites: [],
+    lateInstalls: [],
+    merged: 0,
+    checked: false,
+  })
 }
 
 /** Record one order-scoped hook push: the route count at that moment (so `routesAtPush === total` at
@@ -876,7 +899,62 @@ const recordScopedHook = (key: object, routesAtPush: number, kind: string): void
   }
   const state = hookAudit.get(key)
   if (state === undefined || state.policy === "off") return
-  state.sites.push({ kind, routesAtPush, site: captureCallerSite() })
+  state.sites.push({
+    kind,
+    routesAtPush: routesAtPush - state.merged,
+    mergedAtPush: state.merged,
+    site: captureCallerSite(),
+  })
+}
+
+/** Count routes a `merge()` adopted: they never run this server's order-scoped hooks, so a hook
+ * followed only by merges covers nothing. */
+const noteMergedRoutes = (key: object, count: number): void => {
+  const state = hookAudit.get(key)
+  if (state !== undefined) state.merged += count
+}
+
+/** Record a `merge()` whose server authenticates none of its routes while this server's order-scoped
+ * auth - `authenticate()` stages, or `authenticated` evidence scoped to subsequent routes - would
+ * cover some of them. A server that authenticates any of its own routes chose its own auth, so its
+ * unauthenticated routes are taken as public on purpose. `nifra check` reports what this records. */
+const noteMergeAuthGap = (
+  target: object,
+  authStages: readonly RawAuthStage[],
+  active: readonly AssuranceDeclaration[],
+  routes: readonly CatalogRoute[],
+  sourceGlobal: readonly AssuranceDeclaration[],
+): void => {
+  const parentAuth = active.filter((item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
+  if (authStages.length === 0 && parentAuth.length === 0) return
+  const authenticates = (route: CatalogRoute): boolean =>
+    route.assurance.some((item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED) ||
+    assuranceEvidenceFor(sourceGlobal, route.method, route.path).some(
+      (item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED,
+    )
+  if (routes.some(authenticates)) return
+  const covered = routes.filter(
+    (route) =>
+      authStages.length > 0 ||
+      assuranceEvidenceFor(parentAuth, route.method, route.path).length > 0,
+  )
+  if (covered.length === 0) return
+  tagMergeAuthGap(target, {
+    site: captureCallerSite(),
+    auth: [
+      ...authStages.map((stage) => `authenticate(${stage.id})`),
+      ...new Set(parentAuth.map((item) => item.source)),
+    ],
+    routes: covered.map((route) => `${route.method} ${route.path}`),
+  })
+}
+
+/** Record a registration-time plugin (`responseContract()`, `effectLedger()`) installed after routes
+ * it would have covered, named as `METHOD /path`. Reported with the dead hooks at seal. */
+const recordLateInstall = (key: object, plugin: string, routes: readonly string[]): void => {
+  const state = hookAudit.get(key)
+  if (state === undefined || state.policy === "off" || routes.length === 0) return
+  state.lateInstalls.push({ plugin, site: captureCallerSite(), routes })
 }
 
 /** Hook provenance for an adoption (dev only, see `internal/hook-origins.ts`): which scope each
@@ -913,20 +991,46 @@ const sealHookAudit = (
   if (state === undefined || state.checked) return
   state.checked = true
   if (state.policy === "off" || total + sockets === 0) return
+  const own = total - state.merged
   const dead = state.sites.filter(
     (hook) =>
       hook.routesAtPush ===
       (hook.kind === "around" || hook.kind === "aroundCapability" || hook.kind === "afterHandle"
-        ? total
-        : total + sockets),
+        ? own
+        : own + sockets),
   )
-  if (dead.length === 0) return
-  const detail = dead.map((hook) => `  ${hook.kind}()  at ${hook.site ?? "<unknown>"}`).join("\n")
-  const message =
-    `[nifra] ${dead.length} order-scoped hook(s) apply to no route - they were added after the ` +
-    `last route was registered, and register() snapshots the chain into each route as it is ` +
-    `declared:\n${detail}\nMove them before the routes they should cover. App-global hooks ` +
-    `(onRequest/onResponse) are not order-scoped and can be added at any time.`
+  const parts: string[] = []
+  if (dead.length > 0) {
+    const mergedAfter = (hook: (typeof dead)[number]): boolean => state.merged > hook.mergedAtPush
+    const detail = dead
+      .map(
+        (hook) =>
+          `  ${hook.kind}()  at ${hook.site ?? "<unknown>"}${mergedAfter(hook) ? "  (only merge()d routes follow it)" : ""}`,
+      )
+      .join("\n")
+    parts.push(
+      `[nifra] ${dead.length} order-scoped hook(s) apply to no route - they were added after the ` +
+        `last route was registered, and register() snapshots the chain into each route as it is ` +
+        `declared:\n${detail}\nMove them before the routes they should cover. App-global hooks ` +
+        `(onRequest/onResponse) are not order-scoped and can be added at any time.` +
+        (dead.some(mergedAfter)
+          ? " A merge()d route keeps the hooks of the server that declared it and never runs this " +
+            "server's: wire the hook on the merged server, or declare those routes in a group()."
+          : ""),
+    )
+  }
+  for (const late of state.lateInstalls) {
+    const shown = late.routes.slice(0, 5).join(", ")
+    const more = late.routes.length > 5 ? ` and ${late.routes.length - 5} more` : ""
+    parts.push(
+      `[nifra] ${late.plugin}() at ${late.site ?? "<unknown>"} was installed after ` +
+        `${late.routes.length} route(s) it would have covered: ${shown}${more}. It is decided per ` +
+        `route at registration and merge(), so those routes run without it. Install it before the ` +
+        `routes and merge() calls it should cover.`,
+    )
+  }
+  if (parts.length === 0) return
+  const message = parts.join("\n")
   if (state.policy === "error") throw new FrameworkError("UNUSED_SCOPED_HOOKS", message)
   if (state.hasCustomLogger) logger.warn(message)
   else console.warn(message)
@@ -982,6 +1086,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     | undefined
   private readonly maxBodyBytes: number
   private readonly protoPoisoning: "reject" | "strip" | "ignore"
+  private readonly formOrigins: FormOrigins | undefined
   /** `trustBodyFraming`: mark every `app.fetch` request as runtime-framed (see ServerOptions). */
   private readonly trustBodyFraming: boolean
   private readonly wsMaxPayloadBytes: number
@@ -1117,6 +1222,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
     assertByteLimit(maxBodyBytes, "maxBodyBytes")
     this.protoPoisoning = options.protoPoisoning ?? "reject"
+    this.formOrigins = options.formOrigins
     this.trustBodyFraming = options.trustBodyFraming ?? false
     const wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? maxBodyBytes
     assertByteLimit(wsMaxPayloadBytes, "wsMaxPayloadBytes")
@@ -1174,6 +1280,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // for the bundler to eliminate; a non-bundled production run skips it the same way.
     if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
       beginHookAudit(this, options.unusedScopedHooks ?? "warn", options.logger !== undefined)
+      recordCopyVersion()
     }
     this.derives = []
     this.authStages = []
@@ -1229,6 +1336,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * Mount a legacy fetch handler under a literal path prefix. Mounted handlers sit behind typed
    * routes, so routes can move one at a time while the remaining legacy surface stays live.
    * Mounted responses are outside Nifra's typed route and response-contract checks.
+   *
+   * It carries HTTP only: a WebSocket upgrade under the prefix reaches the handler as an ordinary
+   * request and never becomes a socket. Serve that path's sockets with `app.ws()` routes or a
+   * mounted child app, or keep the legacy server running beside this one for them.
    */
   mountFetch(
     path: string,
@@ -1366,6 +1477,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * Unlike `derive`, this stage receives a body-blind authentication capsule and is compiled before
    * route validation. Keeping it separate prevents an unrelated derive from accidentally becoming a
    * security gate and lets the route compiler retain a protected fast lane.
+   *
+   * A stage that throws, or returns anything but `authenticated(principal)` or `rejected(...)`, fails
+   * closed with 503 `{ ok: false, error: "auth_unavailable" }`. The cause goes where a handler's error
+   * goes: to `onError`, whose response replaces the 503, and when no hook answers, to the logger. A
+   * thrown `Response` or `status(...)` is sent as thrown, as it is from a handler.
    */
   authenticate<Principal>(
     stage: AuthenticationStage<Principal, EnvOf<Ctx>>,
@@ -1384,8 +1500,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       throw new TypeError('authenticate() stage mode must be "sync" or "async"')
     }
     this.authStages.push(stage as unknown as RawAuthStage)
-    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
+      recordScopedHook(this, this.catalog.size + this.wsRoutes.length, "authenticate")
       tagHook(stage, "authenticate", this)
+    }
     return this as unknown as Server<R, Ctx & { readonly principal: Principal }, HookOutput>
   }
 
@@ -1502,9 +1620,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     return this as unknown as Server<R, Ctx, HookOutput | HookOutputOf<ReturnType<H>>>
   }
 
-  /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500).
-   * Order-scoped: captured by routes declared *after* this call, none before; one added after the last
-   * route reaches nothing (see {@link ServerOptions.unusedScopedHooks}). */
+  /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500, or 503
+   * `auth_unavailable` for a failed {@link authenticate} stage). Order-scoped: captured by routes
+   * declared *after* this call, none before; one added after the last route reaches nothing (see
+   * {@link ServerOptions.unusedScopedHooks}). */
   onError<H extends (error: unknown, context: Context & Ctx) => MaybePromise<unknown>>(
     fn: H,
   ): Server<R, Ctx, HookOutput | HookOutputOf<ReturnType<H>>> {
@@ -2258,6 +2377,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): CatalogRoute {
+    // Route provenance for the CLI's capability walk, which sets NIFRA_ROUTE_SITES while it loads the
+    // app: the module that registered the route, read where a static scan cannot see the path.
+    if (
+      hookAuditRuntime &&
+      process.env.NODE_ENV !== "production" &&
+      process.env.NIFRA_ROUTE_SITES === "1"
+    ) {
+      const site = captureCallerSite()
+      if (site !== undefined) tagRouteSite(this, `${method.toUpperCase()} ${path}`, site)
+    }
     const compiled = compileRouteOptions(
       {
         maxBodyBytes: this.maxBodyBytes,
@@ -2458,6 +2587,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   [INSTALL_RESPONSE_CONTRACT](runtime: ResponseContractRuntime): void {
     this.assertConfigurable("responseContract()")
     this.responseContractRuntime = runtime
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordLateInstall(
+        this,
+        "responseContract",
+        this.catalog
+          .entries()
+          .filter(
+            ({ entry }) =>
+              entry.responseContract === undefined &&
+              (entry.schema?.response !== undefined || entry.schema?.errors !== undefined),
+          )
+          .map((route) => `${route.method} ${route.path}`),
+      )
   }
 
   /** @internal Symbol-keyed install seam for the response observer plugin. */
@@ -2586,6 +2728,31 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * registered before a `derive`). Fail closed: a path+method collision throws
    * `RouteConfigError` at merge time, and a group with WebSocket routes or mounts is refused
    * (register those on the parent).
+   *
+   * What this server's `.use()`, made BEFORE the merge, covers on a merged route versus a
+   * `group()` route:
+   *
+   *   | installed on this server                   | group() route | merge()d route                 |
+   *   | ------------------------------------------ | ------------- | ------------------------------ |
+   *   | derive/decorate/beforeHandle/afterHandle,  | yes           | no - wire it on the merged     |
+   *   | onError/around, authenticate, route-scoped |               | server                         |
+   *   | assurance                                  |               |                                |
+   *   | onRequest/onResponse/responseHeaders hooks | yes           | yes (app-wide)                 |
+   *   | responseContract()                         | yes           | yes, when the route declares a |
+   *   |                                            |               | response and its own server    |
+   *   |                                            |               | installed no contract          |
+   *   | effectLedger()                             | yes           | yes, when the route declares   |
+   *   |                                            |               | capabilities and has no ledger |
+   *   | idempotency()                              | yes           | the merged server's own; a     |
+   *   |                                            |               | route declaring it without one |
+   *   |                                            |               | is refused at registration     |
+   *
+   * The response contract and the ledger can only add a check or a record, so a merged route is
+   * recompiled under them. A runtime installed AFTER the merge covers neither kind of route.
+   *
+   * In development, {@link ServerOptions.unusedScopedHooks} reports a hook followed only by merges and
+   * a contract or ledger installed after the routes it would cover; `nifra check` reports a merge whose
+   * server authenticates none of its routes under this server's `authenticate()` (NF-C043).
    */
   merge<R2 extends Registry, Ctx2, HookOutput2>(
     other: Server<R2, Ctx2, HookOutput2>,
@@ -2594,7 +2761,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     if (!(other instanceof Server)) {
       // A server from another copy of this package reaches this copy's private request state through
       // symbols it does not share, and would fail per request. The boot warning names the copies.
-      throw new TypeError("merge() requires a server() from this copy of @nifrajs/core")
+      throw new TypeError(
+        hookAuditRuntime && process.env.NODE_ENV !== "production"
+          ? mergeRefusal()
+          : "merge() requires a server() from this copy of @nifrajs/core",
+      )
     }
     if (this.routePrefix !== "") {
       // The merged routes were compiled under their own paths; adopting them here would publish them
@@ -2611,7 +2782,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         "merge() does not carry WebSocket routes or mounts - register them on the parent server",
       )
     }
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      noteMergeAuthGap(
+        this,
+        this.authStages,
+        this.activeAssurance,
+        source.catalog.entries(),
+        source.globalAssurance,
+      )
     this.adopt(source, undefined, 0)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      noteMergedRoutes(this, source.catalog.size)
     return this as unknown as Server<R & R2, Ctx, HookOutput>
   }
 
@@ -2630,7 +2811,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * The builder receives a scope that INHERITS this server's route chain as it stands at the call
    * (`derive`/`decorate`/`authenticate`/`beforeHandle`/`afterHandle`/`onError`/`around`, assurance,
    * capability interceptors, installed runtimes, applied plugins), exactly as a route declared here
-   * would. A plugin this server already applied is in effect for the group: the group's `use()` of
+   * would. {@link merge} documents how that differs for a merged server. A plugin this server already applied is in effect for the group: the group's `use()` of
    * that same instance does nothing, and its `use()` of another instance under the same name throws a
    * `RouteConfigError` (`PLUGIN_RECONFIGURED`), because that instance could never replace the parent's.
    * A plugin the group applies still shares the parent's copy of a dependency it `use()`s itself.
@@ -2738,7 +2919,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           })
         : (route: CatalogRoute): CatalogRoute => route
     this.catalog.addBatch(
-      sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(route))),
+      sourceRoutes.map((route) =>
+        this.bindFusedRuntime(
+          foldedAssurance(
+            adoptRouteRuntimes(route, this.responseContractRuntime, this.effectLedgerRuntime),
+          ),
+        ),
+      ),
     )
     // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
     // runtime object supplies the generic execution machinery. If the parent already has a runtime,
@@ -3547,6 +3734,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
               pubsub,
               attach: runtime.attach,
               maxPayloadBytes: this.wsMaxPayloadBytes,
+              sender: runtime.sender,
             }
       }
       const wrap = (response: Response | ResponseResult): WebSocketUpgradeOutcome =>
@@ -3659,9 +3847,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       if (o.kind === "pass")
         return this.fetch(req, bunPeerPlatform(server, req) as Platform<EnvOf<Ctx>>)
       if (o.kind === "reject") return o.response
-      return server.upgrade(req, {
-        data: { handler: o.handler, data: o.data, pubsub: o.pubsub },
-      })
+      // A copy: the Bun socket keeps per-connection state on it, and a hand-built outcome may be shared.
+      return server.upgrade(req, { data: { ...o } })
         ? undefined
         : jsonError(426, "upgrade_required")
     }
@@ -4288,6 +4475,18 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   [INSTALL_EFFECT_LEDGER](runtime: EffectLedgerRuntime): void {
     this.assertConfigurable("effectLedger()")
     this.effectLedgerRuntime = runtime
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordLateInstall(
+        this,
+        "effectLedger",
+        this.catalog
+          .entries()
+          .filter(
+            ({ entry, descriptor }) =>
+              entry.ledgered === undefined && (descriptor.capabilities?.length ?? 0) > 0,
+          )
+          .map((route) => `${route.method} ${route.path}`),
+      )
   }
 
   /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
@@ -4689,6 +4888,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         wrapResponse,
         (err) => logError(err, ctx, finalize, wrapResponse),
         bodySchema,
+        this.formOrigins,
       )
     }
   }
@@ -5103,6 +5303,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         (response) => this.wrapWebResponse(response),
         (err) => Promise.resolve(logError(err, ctx)),
         bodySchema,
+        this.formOrigins,
       ) as MaybePromise<Response>
     }
   }
@@ -5534,6 +5735,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         wrapResponse,
         (err) => logError(err, ctx, finalize, wrapResponse),
         bodySchema,
+        this.formOrigins,
       )
     }
   }
@@ -5607,7 +5809,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     if (stage.kind === "body") return this.readProgramBody(entry, source, ctx)
     const input =
       stage.kind === "headers"
-        ? headerObjectOf(source.headers)
+        ? stage.names === undefined
+          ? headerObjectOf(source.headers)
+          : declaredHeaders(source.headers, stage.names)
         : stage.kind === "query"
           ? queryObjectOf(ctx[CONTEXT_SEARCH])
           : ctx[stage.kind]
@@ -5636,8 +5840,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
+    fallback?: () => T,
   ): MaybePromise<T> {
-    return this.handleLifecycleError(entry, error, ctx, finalize, wrapResponse)
+    return this.handleLifecycleError(entry, error, ctx, finalize, wrapResponse, fallback)
   }
 
   /** Finish a successful program result through response-contract enforcement and finalization. */
@@ -6107,6 +6312,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
+    // The answer when no hook does; the default 500 unless a stage owns a different fail-closed status.
+    fallback?: () => T,
   ): MaybePromise<T> {
     // A *thrown* Response is deliberate control flow, not an error - a guard throws a redirect/401,
     // an action throws an error page. Send it as the same Response returned would be sent (Remix/
@@ -6122,9 +6329,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
       // (redacting) logger. Body-read failures and around-hook failures land here too.
       this.logRequestError(err, ctx)
-      return wrapResponse(plainError(500, "internal_error"))
+      return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback()
     }
-    return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse)
+    return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse, fallback)
   }
 
   /** The `onError` chain, split off {@link handleLifecycleError} so its `await` costs only the routes
@@ -6135,6 +6342,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
+    fallback?: () => T,
   ): Promise<T> {
     // Indexed for the same reason as the `beforeHandle` chain above: the iterator would outlive
     // the `await` and stay heap-allocated on both engines.
@@ -6155,7 +6363,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       }
     }
     this.logRequestError(err, ctx)
-    return wrapResponse(plainError(500, "internal_error"))
+    return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback()
   }
 
   /** Log an unhandled request error to the (redacting) logger - shared by the compiled route program and the
@@ -6189,6 +6397,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       (response) => response,
       (error) => Promise.reject(error),
       bodySchema,
+      this.formOrigins,
     )
   }
 
@@ -6554,7 +6763,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // the parent.
     const nativePubsub =
       this.wsRoutes.length > 0 && !this.mountsTakeUpgrades() && !this.wsHasValidatedSend
-    const wsHandlers = wsRuntime?.bunHandlers(this.topics ?? wsRuntime.createTopics(), nativePubsub)
+    const wsHandlers = wsRuntime?.bunHandlers(
+      this.topics ?? wsRuntime.createTopics(),
+      nativePubsub,
+      this,
+    )
     // Spread rather than pass `hostname: undefined` (or an undefined idle timeout or TLS) - Bun treats
     // an explicit undefined as a value on some option paths, and omitting is what selects its own
     // defaults, 0.0.0.0 among them.
@@ -6602,8 +6815,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           // `unknown` params bridge a TS structural-variance quirk. Round-trip covered by websocket.test.ts.
           websocket: {
             // Cap inbound frames so a huge message can't be buffered/JSON-parsed into memory; the runtime
-            // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes).
-            maxPayloadLength: this.wsMaxPayloadBytes,
+            // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes). One
+            // limit per listener: the largest cap among this app and the apps mounted on it.
+            maxPayloadLength: wsHandlers.maxPayloadLength,
             open: (ws) => wsHandlers.open(ws),
             message: (ws, message) => wsHandlers.message(ws, message),
             close: (ws, code, reason) => wsHandlers.close(ws, code, reason),