@nifrajs/core 2.12.1 → 2.14.1

package/src/server/registry.ts

@@ -1,3 +1,4 @@
+import type { BinaryResponse, RawResponse } from "../binary.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
 
@@ -79,12 +80,26 @@ export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
   readonly sse: RegistrySse<S>
 }
 
-/** The client-visible output of a handler: its awaited return, minus raw `Response`. */
-export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
-  Awaited<ReturnType<H>>,
-  Response
+/**
+ * The client-visible output of a handler: its awaited return, with an UNbranded raw `Response` removed
+ * (a route returning a bare `Response` has no describable body). A response branded by `bytes()`
+ * ({@link BinaryResponse}) or `raw()` ({@link RawResponse}) is KEPT, so the brand reaches the client's
+ * `Jsonify` and types `data` as `Blob` / `Jsonify<T>` rather than collapsing to `never`.
+ */
+export type OutputOf<H extends (...args: never[]) => unknown> = KeepBrandedResponse<
+  Awaited<ReturnType<H>>
 >
 
+/** Preserve a `bytes()`/`raw()`-branded response; drop only a bare `Response`. Distributes over a
+ * union return, so `Foo | BinaryResponse` keeps both arms. */
+type KeepBrandedResponse<O> = O extends BinaryResponse
+  ? O
+  : O extends RawResponse<unknown>
+    ? O
+    : O extends Response
+      ? never
+      : O
+
 /**
  * The registry entry for a WebSocket route (stored under the pseudo-method key `"WS"`, so WS routes
  * ride the same path → method map as HTTP routes - no extra Server generic). `in` is the client →

package/src/server/request-context.ts

@@ -19,6 +19,7 @@ import { headerObjectOf } from "./headers.ts"
 import { jsonError } from "./http.ts"
 import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
+import { responseJsonContentType } from "./respond.ts"
 import {
   CONTEXT_SEARCH,
   CONTEXT_SET,
@@ -88,6 +89,80 @@ function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
   return typeof init === "number" ? { status: init } : init
 }
 
+/**
+ * Whether a body built here should be deferred instead of turned into a `Response` on the spot.
+ *
+ * Only the Node bridge can use a deferred body: it writes status + headers + bytes straight to the
+ * socket, so the undici `Response` those two helpers used to build (~2us, about a quarter of the
+ * request budget on a small text response) was pure loss. Bun and Deno hand the `Response` to their
+ * native server, where nothing reads the deferral. Probed once at module load, not per response.
+ */
+const DEFERS_RESPONSE =
+  typeof (globalThis as { Deno?: unknown }).Deno === "undefined" &&
+  typeof (globalThis as { Bun?: unknown }).Bun === "undefined" &&
+  typeof (globalThis as { process?: { versions?: { node?: unknown } } }).process?.versions?.node ===
+    "string"
+
+/**
+ * The Node adapter's deferred-response factory, received over the shared-symbol seam rather than a
+ * package import - `@nifrajs/node` stays dependency-free from core's runtime and talks to it only
+ * through `Symbol.for` marks, so the stand-in it builds (and the ~0.4 KB gzip the class costs) never
+ * ships in a Bun/Deno bundle that will never run this branch. `c.json`/`c.text` route the Node fast
+ * lane through it: given a status, an owned header record, and the bytes, it returns a `Response`-shaped
+ * value the bridge writes straight to the socket (no undici `Response` built, no body stream drained).
+ * Absent - no adapter loaded - the two helpers fall back to a real `Response`. Cached on first read;
+ * the adapter registers at its own module load, before any request reaches a handler.
+ */
+const DEFERRED_RESPONDER_KEY = Symbol.for("nifra.deferred.responder")
+type DeferredResponder = (body: string, status: number, headers: Record<string, string>) => Response
+let deferredResponder: DeferredResponder | undefined
+function deferredResponderFor(): DeferredResponder | undefined {
+  if (deferredResponder === undefined) {
+    deferredResponder = (globalThis as unknown as Record<symbol, DeferredResponder | undefined>)[
+      DEFERRED_RESPONDER_KEY
+    ]
+  }
+  return deferredResponder
+}
+
+/**
+ * A header record the deferred response can own outright - a fresh object with lowercase names, since
+ * the Node writer mutates it in place to declare `content-length`. `undefined` means the caller's
+ * shape (a `Headers`, an entries array) is not worth walking here: those take the `Response` path.
+ */
+function ownHeaderRecord(
+  // `unknown`: the lib's `ResponseInit.headers` is a runtime-specific `HeadersInit` (Bun's vs
+  // undici's differ), and this only needs to recognize the plain-record case anyway.
+  headers: unknown,
+  contentType: string,
+): Record<string, string> | undefined {
+  if (headers === undefined) return { "content-type": contentType }
+  if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return undefined
+  if (headers instanceof Headers) return undefined
+  const record: Record<string, string> = {}
+  let hasContentType = false
+  for (const name of Object.keys(headers)) {
+    const lower = name.toLowerCase()
+    if (lower === "content-type") hasContentType = true
+    record[lower] = (headers as Record<string, string>)[name] as string
+  }
+  if (!hasContentType) record["content-type"] = contentType
+  return record
+}
+
+/** The content-type the runtime's own `Response` puts on a string body, read off it once. A deferred
+ * text response fills it in itself, so it must fill in exactly what the `Response` would have. */
+let stringBodyContentType: string | undefined
+function responseTextContentType(): string {
+  stringBodyContentType ??=
+    new Response("").headers.get("content-type") ?? "text/plain;charset=UTF-8"
+  return stringBodyContentType
+}
+
+/** `c.text`'s own default, unchanged: the explicit one nifra has always declared when the caller
+ * passes no headers of their own. */
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
+
 export class RequestContext implements RawContext {
   // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
   // constructor initializes only the eager request state, while lazy fields remain absent until used.
@@ -234,15 +309,53 @@ export class RequestContext implements RawContext {
     this.headersValue = value
   }
 
+  /**
+   * Return a JSON body. Prefer this (and {@link text}) over a hand-rolled `return new Response(...)`:
+   * on Node these helpers hand the adapter a status, a header record, and the bytes directly, so the
+   * Web `Response` is deferred and the reply lands on the fastest write lane. A raw `new Response` is
+   * fully supported and returns identical bytes, but it is the last-resort lane - the adapter has to
+   * drain its body stream, which no direct-write helper pays.
+   */
   json(body: unknown, init?: ResponseInit | number): Response {
-    return Response.json(body, statusInit(init))
+    const i = statusInit(init)
+    if (!DEFERS_RESPONSE) return Response.json(body, i)
+    const defer = deferredResponderFor()
+    if (defer === undefined) return Response.json(body, i)
+    // The same bytes `Response.json` would produce, kept one step short of it so the direct writer
+    // can have them. `JSON.stringify` returns `undefined` for a value with no JSON form (`undefined`,
+    // a function, a symbol) - exactly the case where `Response.json` throws, so hand it back the
+    // throw rather than inventing a body. The content-type is the runtime's own, read off
+    // `Response.json` once, so a deferred response carries the same one byte for byte.
+    const text = JSON.stringify(body) as string | undefined
+    if (text === undefined) return Response.json(body, i)
+    const headers = ownHeaderRecord(i?.headers, responseJsonContentType())
+    if (headers === undefined) return Response.json(body, i)
+    return defer(text, i?.status ?? 200, headers)
   }
 
+  /**
+   * Return a text body. The fast lane on Node - see {@link json}. Reach for a raw `return new
+   * Response(body)` only when you need a Response shape these helpers do not build; it costs the
+   * adapter a body-stream drain that this path skips.
+   */
   text(body: string, init?: ResponseInit | number): Response {
     const i = statusInit(init)
+    if (DEFERS_RESPONSE) {
+      const defer = deferredResponderFor()
+      if (defer !== undefined) {
+        // The content-type each shape would have ended up with: nifra's declared default when the
+        // caller brought no headers, the runtime's own string-body default when they did (there the
+        // caller owns the content-type, and only fills in for one they did not set).
+        const headers = ownHeaderRecord(
+          i?.headers,
+          i?.headers === undefined ? TEXT_CONTENT_TYPE : responseTextContentType(),
+        )
+        if (headers !== undefined) return defer(body, i?.status ?? 200, headers)
+      }
+    }
     // Default to text/plain; if the caller passes their own headers, they own the content-type.
     if (i?.headers !== undefined) return new Response(body, i)
-    return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } })
+    return new Response(body, { ...i, headers: { "content-type": TEXT_CONTENT_TYPE } })
   }
 
   get query(): unknown {
@@ -386,31 +499,34 @@ export function readBoundedJsonSource<T>(
       return onResult === undefined
         ? Promise.resolve(jsonError(413, "payload_too_large"))
         : Promise.resolve(jsonError(413, "payload_too_large")).then(onResult)
+    // Trusted framing (Bun's native route table, Deno.serve): the runtime's HTTP parser already
+    // delimited the bytes, so the declared length IS the transport frame and chunked routing is
+    // moot - the over-cap 413 above already enforced the byte cap. Take the runtime's fused
+    // decode+parse straight away, before the transfer-encoding probe that only exists to route
+    // *untrusted* Node/adapter sources to the streaming lane. Skipping that probe drops one
+    // `Headers.get()` from every Bun/Deno JSON POST; Node/adapter sources are never marked and fall
+    // through below. The parsed-value poisoning walk still applies.
+    if (hasTrustedBodyFraming(req)) {
+      return raw.json().then(
+        (parsed) => {
+          let guarded: unknown
+          try {
+            guarded = guardParsedValue(parsed, protoPoisoning)
+          } catch {
+            return onResult === undefined
+              ? jsonError(400, "invalid_json")
+              : onResult(jsonError(400, "invalid_json"))
+          }
+          return onResult === undefined ? guarded : onResult(guarded)
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
+    }
     const chunked =
       (sourceHeader === undefined
         ? req.headers.get("transfer-encoding")
         : sourceHeader.call(req, "transfer-encoding")) !== null
     if (!chunked) {
-      // Bun's compiled native route table receives a Request whose bytes were already delimited by
-      // Bun's HTTP parser. Keep the exact-byte path for every portable/adapted source, but preserve
-      // Bun's fused decode+parse on this trusted ingress; the declared length is the transport frame
-      // there, not an attacker-controlled hint. The parsed-value poisoning walk still applies.
-      if (hasTrustedBodyFraming(req)) {
-        return raw.json().then(
-          (parsed) => {
-            let guarded: unknown
-            try {
-              guarded = guardParsedValue(parsed, protoPoisoning)
-            } catch {
-              return onResult === undefined
-                ? jsonError(400, "invalid_json")
-                : onResult(jsonError(400, "invalid_json"))
-            }
-            return onResult === undefined ? guarded : onResult(guarded)
-          },
-          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-        )
-      }
       const jsonWithByteLength = raw.jsonWithByteLength
       if (jsonWithByteLength !== undefined) {
         return jsonWithByteLength.call(raw).then(

package/src/server/respond.ts

@@ -150,7 +150,7 @@ function withStaticHeaderInit(
 const IS_DENO = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
 let denoJsonContentType: string | undefined
 
-function responseJsonContentType(): string {
+export function responseJsonContentType(): string {
   if (denoJsonContentType === undefined) {
     denoJsonContentType = Response.json(0).headers.get("content-type") ?? "application/json"
   }

package/src/server/server-types.ts

@@ -144,6 +144,21 @@ export interface ServerOptions {
    * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
    */
   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
+   * 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.
+   *
+   * This is a development-time diagnostic: the whole audit is guarded by `process.env.NODE_ENV !==
+   * "production"`, so any bundler that defines `NODE_ENV` (vite/esbuild/webpack/next, `bun build
+   * --production`) dead-code-eliminates it, leaving zero bytes and zero per-request cost in the shipped
+   * bundle. It fires in development, test, and CI - where you catch the mistake - not in production.
+   */
+  readonly unusedScopedHooks?: "warn" | "error" | "off"
 }
 
 /** A fetch-compatible handler used by {@link Server.mountFetch}. */

package/src/server/server.ts

@@ -49,7 +49,12 @@ import type {
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import { assertByteLimit, markTransportCap, markTrustedBodyFraming } from "./body.ts"
+import {
+  assertByteLimit,
+  markTransportCap,
+  markTrustedBodyFraming,
+  type RawBodyReaders,
+} from "./body.ts"
 import { type ClientIpTrust, resolveClientIp } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
 import {
@@ -223,7 +228,12 @@ import {
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "./ledger-lane.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
 import type { McpRuntime } from "./mcp-hook.ts"
-import type { ContextPlugin, IdentityPlugin } from "./plugin.ts"
+import type {
+  ContextPlugin,
+  IdentityPlugin,
+  PluginTypeCollapsed,
+  ServerTypeUnpinned,
+} from "./plugin.ts"
 import type {
   AddRoute,
   EmptyRegistry,
@@ -285,6 +295,11 @@ export interface RequestSource {
   /** Present only when materializing a `Request` is non-trivial (the Node lazy source); for a real
    * `Request` passed as the source it's absent and {@link requestOf} returns the source itself. */
   readonly request?: Request
+  /** Optional pre-`Request` reader surface for the transport cap. A source that reads its own
+   * transport bytes (the Node lazy source reads the socket) exposes them here so a capped direct
+   * read (`c.req.json()`) buffers off the transport instead of routing through the deferred
+   * `Request`. `body` must stay the live stream - the cap still guards a chunked body mid-flight. */
+  rawBodyReaders?(): RawBodyReaders
 }
 
 /** The empty context extension. `NonNullable<unknown>` is `{}` without tripping noBannedTypes. */
@@ -566,6 +581,104 @@ export type NifraFeatureVersion = FeatureVersionOf<Version>
 const IDENTITY_RESPONSE = (response: Response): Response => response
 const RESPONSE_TIMEOUT = (): Response => jsonError(503, "request_timeout")
 
+// The unused-order-scoped-hook audit (recorder, seal check, stack capture, message) is a dev-time
+// diagnostic. Every guard below keeps the INLINE literal `process.env.NODE_ENV !== "production"` at the
+// branch - never a shared const holding the folded boolean - because a bundler's `process.env.NODE_ENV`
+// define only dead-code-eliminates the audit when the literal appears at the `if`; Bun does not
+// propagate a module const's value into the branch. Every real production bundler (vite/esbuild/webpack/
+// next, `bun build --production`) injects that define, turning each guard into `hookAuditRuntime &&
+// false`, which folds away - dropping the whole audit and restoring the bare kernel size.
+//
+// `hookAuditRuntime` is the one shared flag: `typeof globalThis.Deno === "undefined"`. Deno ships a
+// 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.
+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
+// order-scoped hook push (the public method, its `use()`-bundle dispatcher, the recorder) lives here,
+// so `captureCallerSite` skips anything starting with it and lands on the user's calling frame.
+const SERVER_MODULE_PATH = /* @__PURE__ */ ((): string | undefined => {
+  const frame = new Error().stack?.split("\n")[1]
+  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. */
+const captureCallerSite = (): string | undefined => {
+  const stack = new Error().stack
+  if (stack === undefined) return undefined
+  for (const line of stack.split("\n").slice(1)) {
+    const frame = line.match(/\(?([^()\s]+:\d+:\d+)\)?\s*$/)?.[1]
+    if (frame === undefined) continue
+    if (SERVER_MODULE_PATH !== undefined && frame.startsWith(`${SERVER_MODULE_PATH}:`)) continue
+    return frame
+  }
+  return undefined
+}
+
+/** Per-server bookkeeping for the unused-order-scoped-hook audit. Deliberately NOT `Server` fields or
+ * methods: those emit class members (a field declaration, a method shell) that a bundler cannot remove
+ * even after their bodies fold away. Held here in a module WeakMap and reached only through the
+ * functions below, every call guarded by `process.env.NODE_ENV !== "production"`, so a production define
+ * folds the guards away, leaves this map and these functions unreferenced, and the bundler eliminates
+ * the whole audit - restoring the bare kernel size. */
+interface HookAuditState {
+  readonly policy: "warn" | "error" | "off"
+  readonly hasCustomLogger: boolean
+  readonly sites: {
+    readonly kind: string
+    readonly routesAtPush: number
+    readonly site: string | undefined
+  }[]
+  checked: boolean
+}
+const hookAudit = /* @__PURE__ */ new WeakMap<object, HookAuditState>()
+
+/** Start tracking one server's order-scoped hook pushes (once, from the constructor). */
+const beginHookAudit = (
+  key: object,
+  policy: "warn" | "error" | "off",
+  hasCustomLogger: boolean,
+): void => {
+  hookAudit.set(key, { policy, hasCustomLogger, sites: [], checked: false })
+}
+
+/** Record one order-scoped hook push: the route count at that moment (so `routesAtPush === total` at
+ * seal means no route was declared after it) and the caller's frame. */
+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() })
+}
+
+/** Run the deadness check exactly once. A hook whose recorded route count equals the final route count
+ * had no route declared after it - unambiguously dead, since the scoping feature (a hook that covers
+ * only later routes) always leaves at least one such route. Zero-route apps are exempt (different
+ * mistake, and the warning would be noise). */
+const sealHookAudit = (
+  key: object,
+  total: number,
+  logger: { warn(message: string): void },
+): void => {
+  const state = hookAudit.get(key)
+  if (state === undefined || state.checked) return
+  state.checked = true
+  if (state.policy === "off" || total === 0) return
+  const dead = state.sites.filter((hook) => hook.routesAtPush === total)
+  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.`
+  if (state.policy === "error") throw new FrameworkError("UNUSED_SCOPED_HOOKS", message)
+  if (state.hasCustomLogger) logger.warn(message)
+  else console.warn(message)
+}
+
 /**
  * The inline server. Routes are chainable and fully type-inferred. `derive`/
  * `decorate` extend the handler context (`Ctx`) for routes defined *after* them,
@@ -734,6 +847,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
     this.sealed = false
+    // Guarded so a production define strips the call, leaving `beginHookAudit`/`hookAudit` unreferenced
+    // 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)
+    }
     this.derives = []
     this.decorations = {}
     this.beforeHandleHooks = []
@@ -802,17 +920,30 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
-  /** Add a per-request, computed context extension for subsequent routes. */
+  /**
+   * Add a per-request, computed context extension. Order-scoped: it is snapshotted into every route
+   * declared *after* this call, and reaches none declared before. One added after the last route
+   * (e.g. on the app returned by a route-registering factory) covers nothing - see
+   * {@link ServerOptions.unusedScopedHooks}.
+   */
   derive<D extends object>(fn: (context: Context & Ctx) => MaybePromise<D>): Server<R, Ctx & D> {
     this.assertConfigurable("derive()")
     this.derives.push(fn as unknown as RawDerive)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "derive")
     return this as unknown as Server<R, Ctx & D>
   }
 
-  /** Add a static context value for subsequent routes. */
+  /**
+   * Add a static context value. Order-scoped: captured by every route declared *after* this call, and
+   * by none before; one added after the last route reaches nothing
+   * (see {@link ServerOptions.unusedScopedHooks}).
+   */
   decorate<const K extends string, V>(key: K, value: V): Server<R, Ctx & Record<K, V>> {
     this.assertConfigurable("decorate()")
     this.decorations[key] = value
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "decorate")
     return this as unknown as Server<R, Ctx & Record<K, V>>
   }
 
@@ -830,10 +961,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
-  /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
+  /**
+   * Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped:
+   * it is snapshotted into every route declared *after* this call and covers none declared before, so
+   * one added after the last route reaches nothing (see {@link ServerOptions.unusedScopedHooks}).
+   */
   beforeHandle(fn: (context: Context & Ctx) => MaybePromise<unknown>): this {
     this.assertConfigurable("beforeHandle()")
     this.beforeHandleHooks.push(fn as unknown as RawBeforeHandle)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "beforeHandle")
     return this
   }
 
@@ -841,10 +978,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * Wrap the matched route lifecycle for subsequent routes. This is intentionally generic over the
    * route output, so wrappers like async context storage do not force Node's direct JSON path through
    * a Web `Response`. The first registered wrapper is outermost.
+   *
+   * Order-scoped: captured by every route declared *after* this call, none before; one added after the
+   * last route reaches nothing (see {@link ServerOptions.unusedScopedHooks}).
    */
   around(fn: <T>(context: Context & Ctx, next: () => MaybePromise<T>) => MaybePromise<T>): this {
     this.assertConfigurable("around()")
     this.aroundHooks.push(fn as unknown as RawAround)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "around")
     return this
   }
 
@@ -869,6 +1011,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.capabilityInterceptors.push(
       Object.freeze({ interceptor, timeoutMs: Math.min(timeoutMs, 2_147_483_647) }),
     )
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "aroundCapability")
     return this
   }
 
@@ -882,17 +1026,25 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
-  /** Transform the handler's result before it is serialized. Order-scoped. */
+  /** Transform the handler's result before it is serialized. Order-scoped: captured by routes declared
+   * *after* this call, none before; one added after the last route reaches nothing (see
+   * {@link ServerOptions.unusedScopedHooks}). */
   afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
     this.assertConfigurable("afterHandle()")
     this.afterHandleHooks.push(fn as unknown as RawAfterHandle)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "afterHandle")
     return this
   }
 
-  /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
+  /** 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}). */
   onError(fn: (error: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
     this.assertConfigurable("onError()")
     this.onErrorHooks.push(fn as unknown as RawErrorHandler)
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      recordScopedHook(this, this.catalog.size, "onError")
     return this
   }
 
@@ -1049,13 +1201,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * called with `this` and its result is returned, so an inline plugin's `derive`/`decorate` thread
    * the added context to handlers defined after `use` (the overload is generic over the concrete
    * `this`). A named plugin already applied is skipped (idempotent dedupe).
+   *
+   * If the plugin's return type is unpinned - `Server<any, any>`, as a hand-rolled `(app) => app` or a
+   * `NifraPlugin<AnyServer, AnyServer>` infers (e.g. an auth plugin whose own types collapsed) - this
+   * returns the non-callable {@link PluginTypeCollapsed} instead of silently widening the whole typed
+   * client to `any`. `.get()`/`.post()` then fail right here rather than surfacing as `any` hundreds of
+   * lines away. Fix at the plugin: build it with {@link defineIdentityPlugin}/{@link defineContextPlugin},
+   * or pin its input server type. This mirrors the guard {@link definePlugin} already applies.
    */
-  use<Out extends AnyServer>(plugin: (app: this) => Out): Out
+  use<Out extends AnyServer>(
+    plugin: (app: this) => Out,
+  ): [ServerTypeUnpinned<Out>] extends [true] ? PluginTypeCollapsed : Out
   /**
    * Apply a {@link Middleware} bundle - wire each hook it provides to its lifecycle point. Returns
    * `this` (no context-type merging); call it before the routes its `beforeHandle`/`afterHandle`
-   * should cover (those are order-scoped; `onRequest`/`onResponse` are global). A named bundle already
-   * applied is skipped (idempotent).
+   * should cover (those are order-scoped; `onRequest`/`onResponse` are global). A bundle applied after
+   * the last route reaches nothing - {@link ServerOptions.unusedScopedHooks} logs that at seal. A named
+   * bundle already applied is skipped (idempotent).
    */
   use(mw: Middleware): this
   use(arg: Middleware | ((app: this) => AnyServer)): AnyServer {
@@ -2017,6 +2179,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<Response> {
+    // Seal once on the first request so test servers (no `listen()`) still get the dead-hook check.
+    // After that it is a single boolean read - the per-request cost the option promises to keep at zero.
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      sealHookAudit(this, this.catalog.size, this.logger)
     // Off path (default): straight through - one property check, no closure, no promise.
     if (this.capacityGate === undefined) return this.fetchSourceInner(source, platform)
     return this.admitGated(requestOf(source), () => this.fetchSourceInner(source, platform))
@@ -2141,6 +2307,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     platform?: Platform<EnvOf<Ctx>>,
     suppliedRuntime?: NodeOutcomeRuntime,
   ): MaybePromise<NodeServeOutcome> {
+    // Seal once on the Node-direct lane too - it can bypass `fetchSource` entirely (hookless outcome).
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      sealHookAudit(this, this.catalog.size, this.logger)
     // A paired header-only native hook can preserve the Node-direct JSON/body outcome for successful
     // responses. Arbitrary onResponse transforms need a real Web Response, but a buffered outcome can
     // be materialized with a direct-write marker and return to the socket path when the hook mutates
@@ -4863,6 +5032,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         "listen() uses Bun.serve and runs only on Bun. Serve on Node with @nifrajs/node or on Deno with @nifrajs/deno, or hand app.fetch to any fetch-compatible runtime (Workers, etc.).",
       )
     }
+    // Seal before Bun.serve: in `"error"` mode this throws instead of leaving a bound port behind.
+    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+      sealHookAudit(this, this.catalog.size, this.logger)
     // Bun's `Server` is the concrete handle; we expose the stable `RunningServer`
     // subset so the public types don't depend on the ambient `Bun` global. The cast
     // bridges them - Bun's `.port` is `number | undefined` (undefined only for unix