@nifrajs/core 4.0.0 → 5.0.0

package/src/server/respond.ts

@@ -5,13 +5,16 @@
  */
 
 import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
+import { plainError } from "./http.ts"
 import {
+  CONTEXT_REQUEST,
   CONTEXT_SET,
   EMPTY_RESPONSE_CONTROLS,
   type HandlerResult,
   isResponseResult,
   type PlainRender,
   plainRenderHeaders,
+  type ResponseResult,
 } from "./runtime-core.ts"
 import type { CtxSet, RawContext } from "./server.ts"
 import { mergeStaticHeaderRecord, type StaticResponseHeaders } from "./static-headers.ts"
@@ -76,28 +79,26 @@ export function buildStaticResponseHeaders(
 /**
  * Apply the static defaults to an ALREADY-BUILT response - the framework's error/404/timeout renders
  * and a handler-returned `Response`, none of which go through the header init below. Defaults, so a
- * name the response already carries is left alone. A guarded `Headers` (a raw `fetch()` result a
- * handler returned) rejects every write, so the first `set` throws with nothing applied and the
- * retry lands on a mutable copy.
+ * name the response already carries is left alone, and a response needing none is returned untouched.
+ * The writes land on {@link writableResponse}'s answer, never on an object other requests may share;
+ * `request` is the request being answered.
  */
 export function applyStaticResponseHeaders(
   response: Response,
   statics: StaticResponseHeaders,
+  request?: Request,
 ): Response {
-  const headers = response.headers
-  if (knownMutableHeaders(headers)) {
-    applyStaticDefaults(headers, statics)
-    return response
-  }
-  try {
-    applyStaticDefaults(headers, statics)
-  } catch {
-    const clone = new Response(response.body, response)
-    applyStaticDefaults(clone.headers, statics)
-    return stamped(clone)
+  let target = response
+  const entries = statics.entries
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!
+    const current = response.headers.get(entry[0])
+    // Set by the request, or already the declared value: nothing to write.
+    if (current === entry[1] || current !== (statics.inherited?.[entry[0]] ?? null)) continue
+    if (target === response) target = writableResponse(response, request)
+    target.headers.set(entry[0], entry[1])
   }
-  rememberMutableHeaders(headers)
-  return response
+  return target
 }
 
 /**
@@ -129,8 +130,12 @@ function staticJsonResponse(
   return new Response(body, init)
 }
 
-function withStatics(response: Response, statics: StaticResponseHeaders | undefined): Response {
-  return statics === undefined ? response : applyStaticResponseHeaders(response, statics)
+function withStatics(
+  response: Response,
+  statics: StaticResponseHeaders | undefined,
+  request: Request | undefined,
+): Response {
+  return statics === undefined ? response : applyStaticResponseHeaders(response, statics, request)
 }
 
 function applyStaticDefaults(headers: Headers, statics: StaticResponseHeaders): void {
@@ -212,7 +217,7 @@ function jsonResponseWithOwnHeaders(
 ): Response {
   const response = status === 200 ? Response.json(result) : Response.json(result, { status })
   for (const name of Object.keys(headers)) response.headers.set(name, headers[name]!)
-  return stamped(response)
+  return withBody(response)
 }
 
 // The framework-buffered-body marker shared with the Node adapter: a Response carrying it exposes
@@ -221,44 +226,118 @@ function jsonResponseWithOwnHeaders(
 const RESPONSE_BODY = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseBody)
 
 /**
- * Headers objects the framework itself constructed - guaranteed mutable, no guard. Response
- * middleware adapters consult this before falling back to a mutability probe, so the hot path
- * (every framework-rendered response) never pays per-request `Headers` operations to learn what
- * construction already knew; only a handler-returned foreign `Response` (a raw `fetch()` result,
- * whose headers are guarded immutable) reaches the probe.
+ * Responses known to carry a body and take header writes: framework renders built with one, and
+ * foreign ones `writableResponse` has already checked. A body is sent once, so such a response belongs
+ * to whichever request holds it and is written in place without reading `.body` again - on Bun that
+ * read turns a string body into a stream, measured at about 6% of a request.
  */
-const MUTABLE_RESPONSE_HEADERS = new WeakSet<Headers>()
+const WRITABLE_BODY_RESPONSES = new WeakSet<Response>()
 
-export function knownMutableHeaders(headers: Headers): boolean {
-  return MUTABLE_RESPONSE_HEADERS.has(headers)
+/**
+ * Body-less responses nifra built for one request - `writableResponse` copies and the framework's own
+ * body-less renders - by that request. Only objects nifra constructs are entered, never one a handler
+ * or hook hands over, so the request's later writers write them in place and any other request that
+ * is handed one copies it.
+ */
+const REQUEST_OWNED = new WeakMap<Response, Request>()
+
+function ownedBy(response: Response, request: Request | undefined): Response {
+  if (request !== undefined) REQUEST_OWNED.set(response, request)
+  return response
 }
 
-export function rememberMutableHeaders(headers: Headers): void {
-  MUTABLE_RESPONSE_HEADERS.add(headers)
+/** Record a Response the framework constructed: one built with a body is single-use and writable. */
+export function rememberRenderedResponse(response: Response, hasBody: boolean): Response {
+  if (hasBody) WRITABLE_BODY_RESPONSES.add(response)
+  return response
 }
 
-/** Stamp a framework-constructed Response's headers as known-mutable, and return it. */
-function stamped(response: Response): Response {
-  MUTABLE_RESPONSE_HEADERS.add(response.headers)
+/** `rememberRenderedResponse` for a Response the framework constructed with a body. */
+function withBody(response: Response): Response {
+  WRITABLE_BODY_RESPONSES.add(response)
   return response
 }
 
+const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
+
+/** Whether `headers` takes writes. A guarded `Headers` rejects the first one, so the probe changes
+ * nothing either way. */
+function headersTakeWrites(headers: Headers): boolean {
+  try {
+    const previous = headers.get(HEADER_MUTABILITY_PROBE)
+    headers.set(HEADER_MUTABILITY_PROBE, "1")
+    if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
+    else headers.set(HEADER_MUTABILITY_PROBE, previous)
+  } catch {
+    return false
+  }
+  return true
+}
+
+/**
+ * The response to write headers on for the request being answered: `response` itself, or a copy.
+ *
+ * A Response without a body can be sent any number of times, so the object a handler, hook or cache
+ * hands over may be answering other requests too - a module-level `new Response(null, { status: 204 })`,
+ * a kept redirect, even one nifra rendered earlier. A cookie or per-request header written onto it would
+ * ship with every later request it answers, so it is always copied, whoever built it. One with a body
+ * can be sent only once, so it already belongs to this request and is written in place; a copy would
+ * cost Bun's file responses their sendfile path and buy nothing. Guarded `Headers`
+ * (`Response.redirect()`, a raw `fetch()` result) reject writes, so those are copied as well.
+ *
+ * Pass the `request` being answered and a copy made for it is written in place by its later writers;
+ * handed back on any other request, that copy is copied again.
+ */
+export function writableResponse(response: Response, request?: Request): Response {
+  if (WRITABLE_BODY_RESPONSES.has(response)) return response
+  if (response.body === null) {
+    // A 101 upgrade and the status-0 `Response.error()` cannot be constructed, and a runtime makes
+    // them per request.
+    if (response.status < 200) return response
+    if (request !== undefined && REQUEST_OWNED.get(response) === request) return response
+    const copy = copiedResponse(
+      response,
+      new Response(null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      }),
+      false,
+    )
+    return ownedBy(copy, request)
+  }
+  if (headersTakeWrites(response.headers)) {
+    WRITABLE_BODY_RESPONSES.add(response)
+    return response
+  }
+  return copiedResponse(response, new Response(response.body, response), true)
+}
+
+/** `copy`, recorded and carrying `original`'s buffered-body marker: the Node writer still sends the
+ * serialized bytes directly, and a marked body-less Response keeps the body only the marker holds. */
+function copiedResponse(original: Response, copy: Response, hasBody: boolean): Response {
+  const marker: unknown = Reflect.get(original, RESPONSE_BODY)
+  if (marker !== undefined) Object.defineProperty(copy, RESPONSE_BODY, { value: marker })
+  return rememberRenderedResponse(copy, hasBody)
+}
+
 function isBodylessStatus(status: number): boolean {
   return status === 204 || status === 205 || status === 304
 }
 
 /** Normalize handler-produced bodyless responses before response middleware sees them. */
-export function normalizeBodylessResponse(response: Response): Response {
+export function normalizeBodylessResponse(response: Response, request?: Request): Response {
   if (!isBodylessStatus(response.status)) return response
   if (response.body === null && !response.headers.has("content-length")) return response
   const headers = new Headers(response.headers)
   headers.delete("content-length")
-  return stamped(
+  return ownedBy(
     new Response(null, {
       status: response.status,
       statusText: response.statusText,
       headers,
     }),
+    request,
   )
 }
 
@@ -321,7 +400,7 @@ function tagged(
   body: string,
   tagResponseBody: ResponseBodyTagOption,
 ): Response {
-  stamped(response)
+  withBody(response)
   return tagResponseBody === false || tagResponseBody === undefined
     ? response
     : markTaggedResponse(
@@ -339,14 +418,15 @@ export function fusedRespondNoSet(
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
   unstamped = false,
+  request?: Request,
 ): Response {
-  // With no response hook registered, no code path ever asks whether these headers are mutable, so
-  // stamping the Headers object into the mutability WeakSet is dead work - `Response.json` alone is
-  // cheaper on Bun than the same construction plus the WeakSet write. `unstamped` is the caller's
-  // assertion that the hook walk is empty; an app that registers ANY response hook keeps the stamp,
-  // because the alternative is the set/delete mutability probe on every single response (each one
-  // carries a fresh `Headers`, so the probe's memo never amortizes) - measured 19% slower than
-  // stamping. Default false: an unknown caller pays one WeakSet write rather than a probe per response.
+  // With no response hook registered, no code path ever asks whether this response takes writes in
+  // place, so recording it in the body WeakSet is dead work - `Response.json` alone is cheaper on Bun
+  // than the same construction plus the WeakSet write. `unstamped` is the caller's assertion that the
+  // hook walk is empty; an app that registers ANY response hook keeps the record, because the
+  // alternative is `writableResponse` reading `.body` and probing the headers of every response (each
+  // one is fresh, so nothing amortizes) - the probe alone measured 19% slower than the WeakSet write.
+  // Default false: an unknown caller pays one WeakSet write rather than a probe per response.
   if (
     unstamped &&
     (tagResponseBody === false || tagResponseBody === undefined) &&
@@ -379,7 +459,7 @@ export function fusedRespondNoSet(
         const entry = statics.entries[i]!
         response.headers.set(entry[0], entry[1])
       }
-      return stamped(response)
+      return withBody(response)
     }
     // With declared static headers the prebuilt init already carries them plus the JSON
     // content-type, so this lane still constructs the response in one call - the whole point of
@@ -406,13 +486,19 @@ export function fusedRespondNoSet(
           tagResponseBody,
         )
     }
-    return stamped(
+    return withBody(
       statics === undefined
         ? Response.json(result)
         : Response.json(result, statics.responseJsonInit200()),
     )
   }
-  return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS, tagResponseBody, statics)
+  return toResponse(
+    result as HandlerResult,
+    EMPTY_RESPONSE_CONTROLS,
+    tagResponseBody,
+    statics,
+    request,
+  )
 }
 
 /** Fused-lane respond with a context: read `c.set` once; untouched (the common case) -> the fast
@@ -425,15 +511,23 @@ export function fusedRespond(
   unstamped = false,
 ): Response {
   const set = ctx[CONTEXT_SET]()
-  if (set === undefined) return fusedRespondNoSet(result, tagResponseBody, statics, unstamped)
-  return toResponse(result as HandlerResult, set, tagResponseBody, statics)
+  const request = unstamped ? undefined : ctx[CONTEXT_REQUEST]
+  if (set === undefined)
+    return fusedRespondNoSet(result, tagResponseBody, statics, unstamped, request)
+  return toResponse(result as HandlerResult, set, tagResponseBody, statics, request)
 }
 
+/**
+ * Render a handler's result. `request` is the request being answered, given when response hooks will
+ * write next: a copy or body-less response built here is then recorded as that request's own, so the
+ * hooks write it in place instead of copying it again.
+ */
 export function toResponse(
   result: HandlerResult,
   set: CtxSet,
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
+  request?: Request,
 ): Response {
   if (isResponseResult(result)) {
     const plain = result.plain
@@ -446,16 +540,56 @@ export function toResponse(
         plainRenderSet(plain, set),
         tagResponseBody,
         statics,
+        request,
       )
     }
     return withStatics(
-      appendCookiesToResponse(normalizeBodylessResponse(result.toResponse()), set),
+      applySetToResponse(normalizeBodylessResponse(result.toResponse(), request), set, request),
       statics,
+      request,
     )
   }
   if (result instanceof Response) {
-    return withStatics(appendCookiesToResponse(normalizeBodylessResponse(result), set), statics)
+    if (result.bodyUsed) {
+      return toResponse(SENT_BODY, EMPTY_RESPONSE_CONTROLS, false, statics, request)
+    }
+    return withStatics(
+      applySetToResponse(normalizeBodylessResponse(result, request), set, request),
+      statics,
+      request,
+    )
   }
+  return renderValue(result, set, tagResponseBody, statics, request)
+}
+
+/**
+ * Render a framework {@link ResponseResult} - a rejection such as a `413`, `415` or `422` - with no
+ * request controls, byte-identical to `toResponse(result, EMPTY_RESPONSE_CONTROLS)`. It never takes a
+ * handler's `Response`, so a compact server rendering only its own rejections ships none of the code
+ * that adopts one.
+ */
+export function renderResult(result: ResponseResult): Response {
+  const plain = result.plain
+  return plain === undefined
+    ? normalizeBodylessResponse(result.toResponse())
+    : renderValue(
+        plain.body,
+        plainRenderSet(plain, EMPTY_RESPONSE_CONTROLS),
+        false,
+        undefined,
+        undefined,
+      )
+}
+
+/** The JSON lane: a value that is neither a `Response` nor a response result, rendered with the
+ * request's status, headers and cookies. */
+function renderValue(
+  result: unknown,
+  set: CtxSet,
+  tagResponseBody: ResponseBodyTagOption,
+  statics: StaticResponseHeaders | undefined,
+  request: Request | undefined,
+): Response {
   // The static tier only changes WHICH prebuilt header shape the branches below reach for: the
   // request's own headers are folded on top of the declared defaults once, here.
   const own = headersInit(set)
@@ -463,7 +597,10 @@ export function toResponse(
   const jsonCtHeaders = statics === undefined ? JSON_CT_HEADERS : statics.jsonHeaders
   const status = set.status ?? (result === undefined ? 204 : 200)
   if (status === 204 || status === 205 || status === 304) {
-    return stamped(new Response(null, headers === undefined ? { status } : { status, headers }))
+    return ownedBy(
+      new Response(null, headers === undefined ? { status } : { status, headers }),
+      request,
+    )
   }
   // Bun and Deno both make a JSON response first and then accept a few header mutations more cheaply
   // than ingesting the same plain record in the constructor. This is the common dynamic-header
@@ -505,7 +642,7 @@ export function toResponse(
     }
   }
   const init: ResponseInit = headers === undefined ? { status } : { status, headers }
-  if (result === undefined) return stamped(new Response(null, init))
+  if (result === undefined) return ownedBy(new Response(null, init), request)
   if (tagResponseBody) {
     const body = JSON.stringify(result) as string | undefined
     if (body !== undefined) {
@@ -528,9 +665,9 @@ export function toResponse(
   }
   if (IS_DENO && headers !== undefined && !(headers instanceof Headers)) {
     const body = JSON.stringify(result) as string | undefined
-    if (body !== undefined) return stamped(denoResponseWithJsonBody(body, status, headers))
+    if (body !== undefined) return withBody(denoResponseWithJsonBody(body, status, headers))
   }
-  return stamped(Response.json(result, init))
+  return withBody(Response.json(result, init))
 }
 
 // Add a JSON content-type without pre-building a `Headers` instance just to check-and-set one key:
@@ -553,21 +690,37 @@ function withJsonContentType(
     : { ...headers, "content-type": "application/json;charset=utf-8" }
 }
 
-export function appendCookiesToResponse(response: Response, set: CtxSet): Response {
-  // A handler may queue cookies (`c.set.cookie` - e.g. a session cookie) AND return its own Response
-  // (e.g. `redirect("/")` after login). Cookies accumulate additively, so append them to the
-  // returned Response - otherwise the canonical set-session-then-redirect pattern would silently drop
-  // the cookie. (Other `c.set` fields stay the returned Response's own concern.)
-  const cookies = set._cookies
-  if (cookies === undefined || cookies.length === 0) return response
-  try {
-    for (const cookie of cookies) response.headers.append("set-cookie", cookie)
-    return response
-  } catch {
-    // Guarded `Headers` (`Response.redirect()`, a raw `fetch()` result) reject every write, so the
-    // first append throws with nothing applied and the cookies land on a mutable copy instead.
-    const clone = new Response(response.body, response)
-    for (const cookie of cookies) clone.headers.append("set-cookie", cookie)
-    return stamped(clone)
+/** Headers that describe a Response's body or its framing: a `c.set` value for one describes a body
+ * the handler did not return. */
+export const RESPONSE_OWNED_HEADERS: ReadonlySet<string> = new Set([
+  "content-type",
+  "content-length",
+  "content-encoding",
+  "content-range",
+  "transfer-encoding",
+])
+
+export function applySetToResponse(response: Response, set: CtxSet, request?: Request): Response {
+  // A guard's `c.set.headers` (a `cache-control: no-store` on private data) and queued cookies belong
+  // to this request whatever the handler returned, so they go on `writableResponse`'s answer, never on
+  // an object another request may be served from. The Response's own headers win, and the ones that
+  // describe its body or framing come from it alone. A 101 or `Response.error()` takes no headers.
+  let target = response
+  const headers = set._headers
+  if (headers !== undefined && response.status >= 200) {
+    for (const name in headers) {
+      if (RESPONSE_OWNED_HEADERS.has(name.toLowerCase()) || target.headers.has(name)) continue
+      if (target === response) target = writableResponse(response, request)
+      target.headers.set(name, headers[name]!)
+    }
   }
+  const cookies = set._cookies
+  if (cookies === undefined || cookies.length === 0) return target
+  if (target === response) target = writableResponse(response, request)
+  for (const cookie of cookies) target.headers.append("set-cookie", cookie)
+  return target
 }
+
+/** What a handler's Response renders as when its body was already sent: a runtime refuses to send it
+ * again, and the headers it carries were written for the request it already answered. */
+export const SENT_BODY = plainError(500, "internal_error")

package/src/server/response-observer-runtime.ts

@@ -1,3 +1,4 @@
+import { tagSource } from "../internal/hook-origins.ts"
 import type {
   NodeRequestContext,
   NodeResponseBodyHook,
@@ -7,7 +8,7 @@ import type {
   ResponseHeadersView,
 } from "./node-outcome-hook.ts"
 import { recordHeadersView } from "./node-outcome-hook.ts"
-import { knownMutableHeaders, rememberMutableHeaders, taggedResponseBody } from "./respond.ts"
+import { taggedResponseBody, writableResponse } from "./respond.ts"
 import { applyBodyReplacement, withReplacedBody } from "./response-hooks.ts"
 
 type MaybePromise<T> = T | Promise<T>
@@ -19,6 +20,9 @@ export type {
   ResponseHeadersHook,
 } from "./node-outcome-hook.ts"
 
+// Deno reports `process.env` reads as `NotCapable` without --allow-env; read it only off Deno.
+declare const Deno: unknown
+
 export interface ResponseObserverHost {
   assertConfigurable(operation: string): void
   addResponseHook(
@@ -44,32 +48,6 @@ export interface ResponseObserverRuntime {
   install(host: ResponseObserverHost): ResponseObserverMethods
 }
 
-const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
-const GUARDED_RESPONSE_HEADERS = new WeakSet<Headers>()
-
-function hasMutableResponseHeaders(headers: Headers): boolean {
-  if (knownMutableHeaders(headers)) return true
-  if (GUARDED_RESPONSE_HEADERS.has(headers)) return false
-  let previous: string | null = null
-  try {
-    previous = headers.get(HEADER_MUTABILITY_PROBE)
-    headers.set(HEADER_MUTABILITY_PROBE, "1")
-    if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
-    else headers.set(HEADER_MUTABILITY_PROBE, previous)
-    rememberMutableHeaders(headers)
-    return true
-  } catch {
-    try {
-      if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
-      else headers.set(HEADER_MUTABILITY_PROBE, previous)
-    } catch {
-      // A guarded response rejected the probe and the clone path is authoritative.
-    }
-    GUARDED_RESPONSE_HEADERS.add(headers)
-    return false
-  }
-}
-
 function webRequestView(req: Request): NodeRequestContext {
   return { method: req.method, url: req.url, header: (name) => req.headers.get(name) }
 }
@@ -82,12 +60,8 @@ function webHeadersView(
   readonly headers: ResponseHeadersView
   readonly request: NodeRequestContext
 } {
-  const request = webRequestView(req)
-  if (!hasMutableResponseHeaders(response.headers)) {
-    const clone = new Response(response.body, response)
-    return { response: clone, headers: clone.headers, request }
-  }
-  return { response, headers: response.headers, request }
+  const writable = writableResponse(response, req)
+  return { response: writable, headers: writable.headers, request: webRequestView(req) }
 }
 
 export function createResponseObserverRuntime(): ResponseObserverRuntime {
@@ -100,12 +74,16 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
           node?: NodeResponseHook,
         ): ResponseObserverMethods {
           host.assertConfigurable("onResponseHeaders()")
+          const web: Parameters<typeof host.addResponseHook>[0] = (response, req) => {
+            const view = webHeadersView(response, req)
+            const out = fn(view.headers, view.request, response.status)
+            return out instanceof Promise ? out.then(() => view.response) : view.response
+          }
+          // Development-only provenance for `reflectHooks`; a production define folds it away.
+          if (typeof Deno === "undefined" && process.env.NODE_ENV !== "production")
+            tagSource(web, fn)
           host.addResponseHook(
-            (response, req) => {
-              const view = webHeadersView(response, req)
-              const out = fn(view.headers, view.request, response.status)
-              return out instanceof Promise ? out.then(() => view.response) : view.response
-            },
+            web,
             node ?? ((response, req) => fn(recordHeadersView(response), req, response.status)),
             true,
           )

package/src/server/runtime-core.ts

@@ -14,6 +14,8 @@ export type HandlerResult = Response | unknown
 export const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult)
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
+/** The request a context answers, read without the transport cap `req` applies for user code. */
+export const CONTEXT_REQUEST = Symbol("nifra.context.request")
 
 /**
  * A transport codec (or other pre-parsing hook) that already decoded the body stashes the value

package/src/server/server-types.ts

@@ -109,8 +109,12 @@ export interface ServerOptions {
    * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
    */
   readonly maxInboundDeadlineMs?: number
-  /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
-  readonly gracefulSignals?: boolean
+  /**
+   * When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false.
+   * `{ drainMs }` sets how long in-flight requests get to finish before the stop forces them closed
+   * (default 10_000) - keep it under the platform's kill grace period (`docker stop` waits 10 s).
+   */
+  readonly gracefulSignals?: boolean | { readonly drainMs?: number }
   /**
    * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
    * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
@@ -196,9 +200,29 @@ export interface MountOptions<Env = unknown> {
    * Why this child is not analyzed, for a handler whose effects nifra cannot follow (a closure from
    * another package). Capability assurance lists a mount with a reason as a known gap; a mount
    * without one fails it, since its routes are invisible. A nifra `server()` belongs in `merge()`,
-   * where its routes are analyzed.
+   * where its routes are analyzed. Pass an {@link OpaqueMountDeclaration} to also state the routes
+   * the child serves.
    */
-  readonly opaque?: string
+  readonly opaque?: string | OpaqueMountDeclaration
+}
+
+/**
+ * An opaque mount's reason plus the routes it serves. Assurance lists those routes as declared, not
+ * analyzed: their capabilities are the mount's word, checked against the policy but never proven.
+ */
+export interface OpaqueMountDeclaration {
+  /** Why the child is not analyzed. A blank reason leaves the mount undeclared. */
+  readonly reason: string
+  readonly routes?: readonly DeclaredMountRoute[]
+}
+
+/** One route an opaque mount serves, as the app states it. */
+export interface DeclaredMountRoute {
+  readonly method: string
+  /** The request path, from the app root, under the mount's prefix (`/api/auth/sign-in`). */
+  readonly path: string
+  /** Capability ids the route exercises. */
+  readonly capabilities?: readonly string[]
 }
 
 /** Options for a legacy fetch-handler mount. */
@@ -210,7 +234,7 @@ export interface MountFetchOptions {
   /** For safe replayable methods only, try the next matching legacy mount when it returns 404. */
   readonly fallbackOn?: 404
   /** Why this handler is not analyzed - see {@link MountOptions.opaque}. */
-  readonly opaque?: string
+  readonly opaque?: string | OpaqueMountDeclaration
 }
 
 /** A callback awaited after the Bun server has drained and stopped. */