@nifrajs/core 5.1.0 → 5.3.0

package/src/server/server.ts

@@ -23,6 +23,8 @@ import {
   leavePlugin,
   tagAdoption,
   tagHook,
+  tagMergeAuthGap,
+  tagRouteSite,
   tagScoped,
   tagStatic,
 } from "../internal/hook-origins.ts"
@@ -30,6 +32,7 @@ import {
   type AssuranceDeclaration,
   assuranceDeclarationsOf,
   assuranceEvidenceFor,
+  NIFRA_ASSURANCE_IDS,
 } from "../internal/route-assurance.ts"
 import { type CatalogRoute, RouteCatalog } from "../internal/route-catalog.ts"
 import { adoptRouteRuntimes, compileRouteOptions } from "../internal/route-compiler.ts"
@@ -67,20 +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 type { FormOrigins } from "./body-lane.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,
@@ -110,7 +113,7 @@ import {
   readBodyFramed,
 } from "./request-context.ts"
 import { recordRequestReplacement } from "./request-lineage.ts"
-import { hasDotSegment, resolveDotSegments } from "./request-target.ts"
+import { needsResolving, resolveDotSegments } from "./request-target.ts"
 import {
   applyStaticResponseHeaders,
   buildStaticResponseHeaders,
@@ -580,14 +583,21 @@ export { plainValidationError } from "./validation.ts"
 // importers keep resolving `searchOf`/`queryObjectOf`/`QueryValue` from here.
 export { type QueryValue, queryObjectOf, searchOf }
 
+// Outside the printable ASCII a parsed path keeps as written: a control, space, `"`, `#`, `<`, `>`,
+// `\`, `^`, `` ` ``, `{`, `}`, or past ASCII (U+FFFD, an invalid escape, included). Bun's table reads
+// a raw `#` and what follows as path, where the parsed URL ends the path there.
+const UNROUTED_CHAR = /[^!$%&'()*+,\-./0-9:;=?@A-Z[\]_a-z|~]/
+
 /**
  * A param value Bun's native route table matched but the portable router must decide: an invalid
  * escape, or a piece of path Bun matched raw while its own parsed URL says otherwise - a `.` / `..`
- * segment (Bun hands `%2e` over decoded), or a backslash, which the parsed URL reads as `/`.
+ * segment (Bun hands `%2e` over decoded), a backslash, which the parsed URL reads as `/`, a `#`,
+ * where the parsed URL's path ends (`/a/..#/b` is `/`), or a character the parsed URL
+ * percent-encodes (`/t/<b>` is `/t/%3Cb%3E`, which a static route for that text matches). The value
+ * is decoded, so a raw `<` and a sent `%3C` look alike; both are re-routed.
  */
 const unroutedParam = (value: string | undefined): boolean =>
-  value !== undefined &&
-  (value.includes("\uFFFD") || value.includes("\\") || value === "." || value === "..")
+  value !== undefined && (value === "." || value === ".." || UNROUTED_CHAR.test(value))
 
 function hasUnroutedParam(params: Record<string, string>): boolean {
   for (const key in params) {
@@ -602,9 +612,19 @@ function hasUnroutedParam(params: Record<string, string>): boolean {
  */
 const rawRequestTargets = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
 
-/** `req` as Bun or workerd would have delivered it: the same request, its URL's dot segments resolved. */
+/** `req` as Bun or workerd would have delivered it: the same request, its URL resolved as they parse it. */
 const withResolvedTarget = (req: Request): Request => new Request(resolveDotSegments(req.url), req)
 
+// A Host as RFC 9110 allows it: a reg-name or an IP literal, then an optional port. Deno builds
+// `Request.url` by appending the target to the Host as received, so `Host: x/admin#` turned a
+// request for `/public` into one for `/admin`. Node refuses such a Host before routing; so does this.
+const HOST_AUTHORITY = /^(?:\[[0-9a-f:.%]+\]|[\w.-]+)(?::\d{1,5})?$/i
+
+const invalidHost = (req: Request): boolean => {
+  const host = req.headers.get("host")
+  return host !== null && !HOST_AUTHORITY.test(host)
+}
+
 function normalizeMountPrefix(path: string): string {
   if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
     throw new TypeError("mountFetch path must be an absolute pathname without a query or hash")
@@ -787,6 +807,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
@@ -797,9 +818,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
@@ -823,9 +845,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>()
@@ -860,7 +892,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
@@ -877,7 +916,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
@@ -914,20 +1008,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)
@@ -1177,6 +1297,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 = []
@@ -1232,6 +1353,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,
@@ -1369,6 +1494,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>>,
@@ -1387,8 +1517,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>
   }
 
@@ -1505,9 +1637,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>>> {
@@ -2261,6 +2394,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,
@@ -2461,6 +2604,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. */
@@ -2610,6 +2766,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    *
    * 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>,
@@ -2618,7 +2778,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
@@ -2635,7 +2799,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>
   }
 
@@ -3002,7 +3176,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response> {
     // Deno's `Request.url` is the target as sent; Bun, workerd and every `new Request()` parse it.
     // Route what the parsed URL says, so `/users/../admin` is `/admin` on every runtime.
-    if (rawRequestTargets && hasDotSegment(req.url)) req = withResolvedTarget(req)
+    if (rawRequestTargets) {
+      if (invalidHost(req)) return jsonError(400, "invalid_host")
+      if (needsResolving(req.url)) req = withResolvedTarget(req)
+    }
     // An edge deployment whose only ingress is this method declares its requests runtime-framed at
     // construction; everything else stays on the delivered-byte check (see `trustBodyFraming`).
     if (this.trustBodyFraming) markTrustedBodyFraming(req)
@@ -3497,8 +3674,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     if (req.method !== "GET") return WS_PASS
     // The adapter answers a pass by handing this same object to `fetch`.
     const received = req
-    // The handshake routes the path `fetch` would: dot segments resolved (see `fetch`).
-    if (rawRequestTargets && hasDotSegment(req.url)) req = withResolvedTarget(req)
+    // The handshake routes the path `fetch` would: Host checked, dot segments resolved (see `fetch`).
+    if (rawRequestTargets) {
+      if (invalidHost(req)) {
+        return { kind: "reject", response: this.wrapWebResponse(jsonError(400, "invalid_host")) }
+      }
+      if (needsResolving(req.url)) req = withResolvedTarget(req)
+    }
     // The handshake's caller is the one `fetch` derives: hooks and `upgrade()` see the trusted IP.
     platform = this.trustedPlatform(req, platform)
 
@@ -4318,6 +4500,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
@@ -5640,7 +5834,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]
@@ -5669,8 +5865,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. */
@@ -6140,6 +6337,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/
@@ -6155,9 +6354,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
@@ -6168,6 +6367,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.
@@ -6188,7 +6388,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

package/src/server/websocket.ts

@@ -60,6 +60,9 @@ export class TopicRegistry {
   private readonly memberships = new WeakMap<NifraWebSocket, Set<string>>()
 
   subscribe(topic: string, ws: NifraWebSocket): void {
+    // CLOSING or CLOSED: close has run, or is about to run, `unsubscribeAll`, so an async handler's
+    // late subscribe would hold the dead socket for good.
+    if (ws.readyState >= 2) return
     let subs = this.topics.get(topic)
     if (subs === undefined) {
       subs = new Set()

package/src/single-copy.ts

@@ -666,6 +666,36 @@ const describeSkips = (name: string, skips: readonly SingleCopySkip[]): string =
   return lines.join("\n")
 }
 
+/** The `node_modules` folder a copy was installed into: `/kit/node_modules/@scope/pkg` -> `/kit/node_modules`. */
+const modulesDirOf = (copy: string): string => {
+  const marker = `${sep}node_modules${sep}`
+  const at = copy.lastIndexOf(marker)
+  return at === -1 ? dirname(copy) : copy.slice(0, at + marker.length - 1)
+}
+
+/**
+ * Version skews that share both trees and both versions, as one report: a linked repository on
+ * another release skews every declared package at once, and a block per package said the same thing
+ * eighteen times. One package keeps the per-package report.
+ */
+const describeSkewGroup = (skips: readonly SingleCopySkip[]): string => {
+  const [first] = skips
+  if (first === undefined || skips.length === 1) return describeSkips(first?.package ?? "", skips)
+  const names = skips.map((skip) => skip.package).sort(codeUnitOrder)
+  return [
+    `[nifra] single-copy: ${names.length} packages are NOT deduplicated (version-skew) - a second copy of each loads, so their module state is not shared.`,
+    copyLine(
+      "app copies",
+      first.to === undefined ? undefined : modulesDirOf(first.to),
+      first.toVersion,
+    ),
+    copyLine("linked copies", modulesDirOf(first.from), first.fromVersion),
+    `  packages: ${names.join(", ")}`,
+    `  ${first.fromVersion ?? "another version"} there, ${first.toVersion ?? "another version"} here - redirecting would serve a version those copies did not ask for`,
+    "  Fix: align the dependency ranges so both trees install one version, then reinstall. nifra never redirects across versions.",
+  ].join("\n")
+}
+
 const strictFromEnv = (): boolean => {
   const value = typeof process === "undefined" ? undefined : process.env[SINGLE_COPY_STRICT_ENV]
   return value === "1" || value === "true"
@@ -685,15 +715,15 @@ export function registerSingleCopy(options: SingleCopyOptions = {}): SingleCopyP
   const root = realpathOrSelf(resolve(options.cwd ?? process.cwd()))
   const strict = options.strict ?? (readSingleCopyStrict(root) || strictFromEnv())
   const warned = processSet(WARNED)
-  const report = (name: string, skips: readonly SingleCopySkip[]): void => {
-    const message = describeSkips(name, skips)
+  const emit = (key: string, message: string): void => {
     if (strict)
       throw new Error(`${message}\n  Strict mode is on, so this process refuses to start.`)
-    const key = `${skips[0]?.reason ?? ""}\0${name}`
     if (warned.has(key)) return
     warned.add(key)
     console.warn(message)
   }
+  const report = (name: string, skips: readonly SingleCopySkip[]): void =>
+    emit(`${skips[0]?.reason ?? ""}\0${name}`, describeSkips(name, skips))
   const plugin = singleCopyPlugin({
     ...options,
     cwd: root,
@@ -703,13 +733,33 @@ export function registerSingleCopy(options: SingleCopyOptions = {}): SingleCopyP
     },
   })
   const byPackage = new Map<string, SingleCopySkip[]>()
+  const bySkew = new Map<string, SingleCopySkip[]>()
   for (const skip of plugin.plan.skipped) {
     options.onSkip?.(skip)
-    const group = byPackage.get(skip.package) ?? []
+    const skew =
+      skip.reason === "version-skew"
+        ? [
+            modulesDirOf(skip.from),
+            skip.to === undefined ? "" : modulesDirOf(skip.to),
+            skip.fromVersion ?? "",
+            skip.toVersion ?? "",
+          ].join("\0")
+        : undefined
+    const groups = skew === undefined ? byPackage : bySkew
+    const key = skew ?? skip.package
+    const group = groups.get(key) ?? []
     group.push(skip)
-    byPackage.set(skip.package, group)
+    groups.set(key, group)
   }
   for (const [name, skips] of byPackage) report(name, skips)
+  for (const skips of bySkew.values()) {
+    if (skips.length === 1) report(skips[0]?.package ?? "", skips)
+    else
+      emit(
+        `version-skew\0${skips.map((skip) => skip.package).join("\0")}`,
+        describeSkewGroup(skips),
+      )
+  }
   // Installing twice (a preload listed twice, or an explicit call on top of the preload) would register
   // two `onLoad` hooks for the same foreign files, and two hooks both answering one file stall the
   // runtime loader. One install per root and declaration is the whole effect anyway.

package/src/tool-contract.ts

@@ -469,8 +469,9 @@ export async function executeTool<Input, Output>(
       await options.idempotency?.abandon(reservationInput(reservation))
     } catch {}
   }
-  // Once the executor has run, the reservation is never released: a retry would repeat a side effect
-  // that may have committed. A store that throws on completion counts as one that refused it.
+  // Once the executor has started, the reservation is never released, even when it throws: a retry
+  // would repeat a side effect that may have committed. A store that throws on completion counts as
+  // one that refused it.
   let executed = false
   const complete = async (): Promise<boolean> => {
     if (reservation === undefined) return true
@@ -660,6 +661,7 @@ export async function executeTool<Input, Output>(
       record("execution", "dry-run")
       return finish({ ok: true, dryRun })
     }
+    executed = true
     const output = await tool.execute(validatedInput.value, {
       effectId,
       signal,
@@ -667,7 +669,6 @@ export async function executeTool<Input, Output>(
       dryRun,
       ...(tool.policy === undefined ? {} : { policy: tool.policy }),
     })
-    executed = true
     record("execution", "committed")
     const validatedOutput = await validateStandard(tool.output, output)
     if (!validatedOutput.ok) {
@@ -699,7 +700,9 @@ export async function executeTool<Input, Output>(
     }
     return finish({ ok: true, dryRun, output: validatedOutput.value })
   } catch (error) {
-    if (!executed) await abandon()
+    // A completion the store refuses still leaves the key pending until its lease lapses.
+    if (executed) await complete()
+    else await abandon()
     const code = signal.aborted || isAbortError(error) ? "cancelled" : "execution_failed"
     record("execution", "failed", code)
     return finish({ ok: false, dryRun, error: { code, stage: "execution" } })

package/src/transport-codec.ts

@@ -228,8 +228,11 @@ export async function readBoundedBytes(
 ): Promise<Uint8Array> {
   const maxBytes = maxBytesOf(options)
   const declared = response.headers.get("content-length")
-  if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes)
+  if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes) {
+    // Refused unread, the body would otherwise hold its connection open until the sender gives up.
+    response.body?.cancel().catch(() => {})
     throw new TransportCodecError("transport payload exceeds maxBytes")
+  }
   if (response.body === null) return new Uint8Array(0)
   const reader = response.body.getReader()
   const chunks: Uint8Array[] = []