@nifrajs/core 5.1.0 → 5.3.0

package/src/index.ts

@@ -16,7 +16,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "5.1.0" as const
+export const VERSION = "5.3.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/hook-origins.ts

@@ -16,6 +16,10 @@ export type HookKind =
   | "onResponse"
   | "responseHeaders"
   | "onResponseFinalized"
+  // Runtimes a route resolved at registration: reflected beside its hooks, never tagged as one.
+  | "effectLedger"
+  | "idempotency"
+  | "responseContract"
 
 export interface HookOrigin {
   readonly kind: HookKind
@@ -48,11 +52,24 @@ export interface AdoptionTag {
   readonly prefix: string | undefined
 }
 
+/** A `merge()` whose routes carry no authentication of their own while the parent authenticates the
+ * routes it declares: the parent's order-scoped auth never runs for merged routes. */
+export interface MergeAuthGapTag {
+  /** The `merge()` call's `file:line:col`, when a frame outside core was found. */
+  readonly site: string | undefined
+  /** The parent's auth in effect at the merge: `authenticate(<id>)` stages and evidence sources. */
+  readonly auth: readonly string[]
+  /** `METHOD /path` of each merged route the parent's auth would have covered. */
+  readonly routes: readonly string[]
+}
+
 const origins = new WeakMap<object, HookOrigin>()
 const scopes = new WeakMap<object, HookScopeTag>()
 const sources = new WeakMap<object, unknown>()
 const statics = new WeakMap<object, StaticHeadersTag[]>()
 const adoptions = new WeakMap<object, AdoptionTag[]>()
+const mergeAuthGaps = new WeakMap<object, MergeAuthGapTag[]>()
+const routeSites = new WeakMap<object, Map<string, string>>()
 let applying: string | undefined
 // A merged server whose static headers are about to become one of the target's response hooks.
 let staticsOwner: object | undefined
@@ -130,6 +147,20 @@ export function tagAdoption(target: object, source: object, prefix: string | und
   else list.push(tag)
 }
 
+export function tagMergeAuthGap(target: object, gap: MergeAuthGapTag): void {
+  const list = mergeAuthGaps.get(target)
+  if (list === undefined) mergeAuthGaps.set(target, [gap])
+  else list.push(gap)
+}
+
+/** Where `server` registered the route `key` (`METHOD /path`): a `file:line:col` frame. The first
+ * registration of a key wins, as it does for the router. */
+export function tagRouteSite(server: object, key: string, site: string): void {
+  const sites = routeSites.get(server)
+  if (sites === undefined) routeSites.set(server, new Map([[key, site]]))
+  else if (!sites.has(key)) sites.set(key, site)
+}
+
 const outer: (string | undefined)[] = []
 
 /** Mark the plugin a `use()` is applying, until the matching {@link leavePlugin}. */
@@ -151,3 +182,7 @@ export const hookSourceOf = (hook: unknown): unknown =>
 export const staticHeadersOf = (server: object): readonly StaticHeadersTag[] =>
   statics.get(server) ?? []
 export const adoptionsOf = (server: object): readonly AdoptionTag[] => adoptions.get(server) ?? []
+export const mergeAuthGapsOf = (server: object): readonly MergeAuthGapTag[] =>
+  mergeAuthGaps.get(server) ?? []
+export const routeSitesOf = (server: object): ReadonlyMap<string, string> =>
+  routeSites.get(server) ?? new Map()

package/src/internal/route-program.ts

@@ -9,6 +9,7 @@
 
 import type { StandardSchemaV1 } from "../schema/standard.ts"
 import { markAuthenticatedRequest } from "../server/auth.ts"
+import { declaredHeaderNames } from "../server/headers.ts"
 import { pathnameOf } from "../server/http.ts"
 import { queryObjectOf } from "../server/query.ts"
 import type { Registry } from "../server/registry.ts"
@@ -35,7 +36,12 @@ import type {
 export type ProgramValidationKind = "headers" | "cookies" | "params" | "body" | "query"
 
 export type RouteProgramStage =
-  | { readonly kind: ProgramValidationKind; readonly schema: StandardSchemaV1 }
+  | {
+      readonly kind: ProgramValidationKind
+      readonly schema: StandardSchemaV1
+      /** Headers only: the names a closed schema validates, read case-insensitively. */
+      readonly names?: readonly string[] | undefined
+    }
   | { readonly kind: "derive"; readonly run: RawDerive }
   | { readonly kind: "before"; readonly run: RawBeforeHandle }
   | { readonly kind: "handler"; readonly run: InternalHandler }
@@ -90,7 +96,8 @@ export function compileRouteProgram(input: RouteProgramInput): RouteProgram {
   for (const kind of ["headers", "cookies", "params", "body", "query"] as const) {
     const validator = schema?.[kind]
     if (validator !== undefined) {
-      const stage = { kind, schema: validator }
+      const names = kind === "headers" ? declaredHeaderNames(validator) : undefined
+      const stage = { kind, schema: validator, names }
       stages.push(stage)
       validationStages.push(stage)
     }
@@ -142,6 +149,7 @@ interface RouteProgramRuntime {
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
+    fallback?: () => T,
   ): MaybePromise<T>
   finishProgramResult<T>(
     entry: RouteEntry,
@@ -243,6 +251,21 @@ function validAuthenticationFailureReason(
   )
 }
 
+/** A failed stage still answers 503, but its cause takes the handler-error path (onError, else the
+ * logger) instead of vanishing. */
+function failAuthentication<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  error: unknown,
+): ProgramResult<T> {
+  return host.handleProgramError(entry, error, ctx, finalize, wrapResponse, () =>
+    finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx),
+  )
+}
+
 function runAuthenticationStages<T>(
   host: RouteProgramRuntime,
   entry: RouteEntry,
@@ -287,8 +310,8 @@ function runAuthenticationStages<T>(
   let outcome: MaybePromise<import("../server/auth.ts").AuthenticationResult<unknown>>
   try {
     outcome = stage.run(input)
-  } catch {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
+  } catch (error) {
+    return failAuthentication(host, entry, ctx, finalize, wrapResponse, error)
   }
   if (outcome instanceof Promise) {
     return outcome.then(
@@ -312,7 +335,7 @@ function runAuthenticationStages<T>(
           return host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
         }
       },
-      () => finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx),
+      (error) => failAuthentication(host, entry, ctx, finalize, wrapResponse, error),
     )
   }
   return finishAuthentication(
@@ -344,27 +367,23 @@ function finishAuthentication<T>(
   if (
     result === null ||
     typeof result !== "object" ||
-    (result.kind !== "authenticated" && result.kind !== "rejected")
+    (result.kind === "rejected"
+      ? !validAuthenticationFailureReason(result.reason) ||
+        (result.response !== undefined &&
+          !(result.response instanceof Response) &&
+          !isResponseResult(result.response))
+      : result.kind !== "authenticated" ||
+        result.principal === null ||
+        result.principal === undefined)
   ) {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
+    const id = program.authStages[next - 1]!.id
+    const error = new TypeError(`authenticate() stage "${id}" returned an invalid decision`)
+    return failAuthentication(host, entry, ctx, finalize, wrapResponse, error)
   }
   if (result.kind === "rejected") {
-    if (!validAuthenticationFailureReason(result.reason)) {
-      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-    }
-    if (
-      result.response !== undefined &&
-      !(result.response instanceof Response) &&
-      !isResponseResult(result.response)
-    ) {
-      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-    }
     const response = result.response ?? defaultAuthenticationResponse(result.reason)
     return finalize(response, responseSet(ctx), ctx)
   }
-  if (result.principal === null || result.principal === undefined) {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-  }
   Object.defineProperty(ctx, "principal", {
     value: result.principal,
     enumerable: true,

package/src/mount.ts

@@ -76,6 +76,31 @@ export function preRouteMountPaths(app: unknown): readonly string[] {
   return paths
 }
 
+const RESIDENT_BODIES = new WeakSet<Response>()
+
+/** Set once an in-process client exists, so the leanest response lane records its bodies too. */
+export let residentBodiesRecorded = false
+
+/** Called by an in-process client: nothing else reads the record, so until then it can be skipped. */
+export function recordResidentBodies(): void {
+  residentBodiesRecorded = true
+}
+
+/**
+ * Record a Response whose body the framework serialized into memory before building it. An
+ * in-process client reads only such a body whole; any other, a handler's own stream included, is
+ * read under its byte cap.
+ */
+export function markResidentBody(response: Response): Response {
+  RESIDENT_BODIES.add(response)
+  return response
+}
+
+/** Whether {@link markResidentBody} recorded `response`. Another copy of this module did not. */
+export function hasResidentBody(response: Response): boolean {
+  return RESIDENT_BODIES.has(response)
+}
+
 /** Structural mount capability exposed by an in-process typed client. */
 export interface BackendMount<Env = unknown> {
   readonly [NIFRA_BACKEND_MOUNT]: BackendMountHandler<Env>

package/src/reflection.ts

@@ -20,6 +20,9 @@ import {
   hookOriginOf,
   hookScopeOf,
   hookSourceOf,
+  type MergeAuthGapTag,
+  mergeAuthGapsOf,
+  routeSitesOf,
   staticHeadersOf,
 } from "./internal/hook-origins.ts"
 import {
@@ -33,6 +36,8 @@ import { NIFRA_BACKEND_EVIDENCE } from "./mount.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
+export { declaredHeaderNames } from "./server/headers.ts"
+
 /** JSON Schema permits either a schema object or the boolean schemas `true` and `false`. */
 export type JsonSchema = boolean | Readonly<Record<string, unknown>>
 
@@ -460,7 +465,9 @@ export interface ReflectedHook {
   readonly kind: HookKind
   /** The plugin that registered it, else the function's own name, else `(anonymous)`. */
   readonly name: string
-  /** Where it was registered: `app`, `group /api`, `merge #1`, `mount /auth`, or `unknown`. */
+  /** Where it was registered: `app`, `group /api`, `merge #1`, `mount /auth`, or `unknown`; `route`
+   * for a runtime the route resolved at registration (`responseContract`, `effectLedger`,
+   * `idempotency`), whose `name` is the contract mode or the runtime. */
   readonly site: string
   /** The header names a static `responseHeaders()` declaration sets. */
   readonly headers?: readonly string[]
@@ -559,6 +566,51 @@ const catalogOf = (
 const joinPath = (base: string, path: string): string =>
   base === "" ? path : path === "/" ? base : `${base}${path}`
 
+/** A `merge()` that authenticates none of its routes under a parent that authenticates its own. */
+export type ReflectedMergeAuthGap = MergeAuthGapTag
+
+/**
+ * Every `merge()` in the app, its merged servers included, whose server authenticates none of its
+ * routes while the parent's order-scoped auth - an `authenticate()` stage, or `authenticated` evidence
+ * scoped to subsequent routes - covers the parent's own: that auth never runs for a merged route.
+ * Recorded by a development load only (the same provenance {@link reflectHooks} reads), so reflect the
+ * app outside production. `nifra check` reports each one (NF-C043).
+ */
+export function reflectMergeAuthGaps(source: unknown): readonly ReflectedMergeAuthGap[] {
+  if (!isServerRecord(source)) return []
+  const gaps: ReflectedMergeAuthGap[] = []
+  const seen = new Set<object>()
+  const visit = (server: object): void => {
+    if (seen.has(server)) return
+    seen.add(server)
+    gaps.push(...mergeAuthGapsOf(server))
+    for (const adoption of adoptionsOf(server)) visit(adoption.source)
+  }
+  visit(source)
+  return gaps
+}
+
+/**
+ * Where each route was registered: `METHOD /path` (`WS` for a socket) mapped to the `file:line:col` of
+ * the call outside nifra's core that registered it, through every `group()` and `merge()`. Recorded only
+ * by a development load with `NIFRA_ROUTE_SITES=1` (the CLI sets it while it loads `nifra.assurance.ts`),
+ * so the map is empty otherwise. The paths are absolute, which is why they stay out of
+ * {@link reflectRoutes}, whose output is written into artifacts.
+ */
+export function reflectRouteSites(source: unknown): ReadonlyMap<string, string> {
+  const sites = new Map<string, string>()
+  if (!isServerRecord(source)) return sites
+  const seen = new Set<object>()
+  const visit = (server: object): void => {
+    if (seen.has(server)) return
+    seen.add(server)
+    for (const [key, site] of routeSitesOf(server)) if (!sites.has(key)) sites.set(key, site)
+    for (const adoption of adoptionsOf(server)) visit(adoption.source)
+  }
+  visit(source)
+  return sites
+}
+
 /**
  * Every hook that actually runs for each route, and for each prefix's unmatched paths, with the plugin
  * that registered it and where: the app, a `group()`, a `merge()`d server, or a `mount()`ed one. It
@@ -698,16 +750,24 @@ export function reflectHooks(source: unknown): ReflectedHookReport {
       const entry = recordOf(route.entry)
       const chain = (field: string, kind: HookKind) =>
         entry === undefined ? [] : listOf(entry, field).flatMap((hook) => entriesOf(hook, kind))
+      // A runtime is pinned into the route when it registers (or is merged), so it is listed with the
+      // route's site rather than a hook's; the mode is the name so a warn -> enforce change shows.
+      const mode = recordOf(recordOf(entry?.responseContract)?.runtime)?.mode
+      const pinned = (present: boolean, kind: HookKind, name: string): ReflectedHook[] =>
+        present ? [{ kind, name, site: "route" }] : []
       routes.push({
         method: route.method,
         path: reportPath(route.path),
         hooks: [
           ...requestPhase(probes),
           ...chain("around", "around"),
+          ...pinned(entry?.ledgered !== undefined, "effectLedger", "effectLedger"),
           ...chain("authStages", "authenticate"),
           ...chain("derives", "derive"),
           ...chain("beforeHandle", "beforeHandle"),
+          ...pinned(entry?.idempotent !== undefined, "idempotency", "idempotency"),
           ...chain("afterHandle", "afterHandle"),
+          ...pinned(typeof mode === "string", "responseContract", String(mode)),
           ...chain("onError", "onError"),
           ...responsePhase(probes),
         ],

package/src/server/context.ts

@@ -312,9 +312,12 @@ export interface RouteSchema {
    * The schema must cover every path param; with the strict default an undeclared path param is rejected.
    * When omitted, `c.params` stays the path-inferred `Record<name, string>`. */
   readonly params?: StandardSchemaV1
-  /** Optional request-header schema. Header names are normalized to lower-case and the validated
-   * output is exposed as `c.headers`; use lower-case keys because HTTP header names are
-   * case-insensitive. */
+  /** Optional request-header schema; the validated output is `c.headers` and a failure is a `422`.
+   * Every client sends headers a route never declares (`host`, `user-agent`, `accept`), so a closed
+   * object schema (`t.object`) validates only the names it declares, each read case-insensitively and
+   * keyed as declared. `t.headers` is the open form: it receives every header, names lower-cased,
+   * and coerces values like `t.query`. A schema that does not expose its JSON Schema (a zod
+   * `.strict()` or valibot `strictObject`) receives every header, so declare it open. */
   readonly headers?: StandardSchemaV1
   /** Optional request-cookie schema. It validates the cookies parsed from the `Cookie` header -
    * names as sent, values URL-decoded strings, the first of a repeated name - before the handler
@@ -446,7 +449,7 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   /** Read one request header without materializing a Web `Request` on the Node adapter hot path. */
   readonly header: (name: string) => string | null
   readonly params: ParamsOf<S, Path>
-  /** Lower-case request headers, validated/coerced when `schema.headers` is declared. */
+  /** Request headers, names lower-cased; when `schema.headers` is declared, its validated output. */
   readonly headers: HeadersOf<S>
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>

package/src/server/core-copies.ts

@@ -10,6 +10,7 @@
  */
 const registry = globalThis as unknown as Record<symbol, string[] | undefined>
 const COPIES = Symbol.for("nifra.core.copies")
+const VERSIONS = Symbol.for("nifra.core.copy-versions")
 registry[COPIES] ??= []
 const copies = registry[COPIES]
 const here = String(import.meta.url).split("?")[0] as string
@@ -19,3 +20,42 @@ if (!copies.includes(here) && copies.push(here) > 1) {
     `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}`,
   )
 }
+
+/** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
+ * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
+const COPY_VERSION = "5.3.0"
+
+/** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
+ * so a production bundle drops it with the version; a copy that built a server has recorded one. */
+export function recordCopyVersion(): void {
+  versionsByUrl().set(here, COPY_VERSION)
+}
+
+/** The process-wide URL -> version map every copy shares. */
+const versionsByUrl = (): Map<unknown, unknown> => {
+  const found: unknown = Reflect.get(globalThis, VERSIONS)
+  if (found instanceof Map) return found
+  const created = new Map<unknown, unknown>()
+  Reflect.set(globalThis, VERSIONS, created)
+  return created
+}
+
+const labelled = (url: string): string => {
+  const version = versionsByUrl().get(url)
+  return typeof version === "string" ? `${url} (${version})` : url
+}
+
+/** Why `merge()` refused a value that is not a server of this copy: when another copy is loaded, the
+ * value is most likely its server, so both copies are named, with their versions where recorded
+ * (copies before 5.2 record none), and the way to collapse them. Called only outside production. */
+export function mergeRefusal(): string {
+  const base = "merge() requires a server() from this copy of @nifrajs/core"
+  const others = copies.filter((url) => url !== here)
+  if (others.length === 0) return base
+  return [
+    `${base}, and ${copies.length} copies are loaded:`,
+    `  this copy:  ${labelled(here)}`,
+    ...others.map((url) => `  other copy: ${labelled(url)}`),
+    "A server() from another copy cannot be merged. Make every package that builds a server() resolve one copy: in a linked repository, install the same nifra version (`nifra upgrade <version> --write`, then `bun install`); `nifra doctor` names each importer.",
+  ].join("\n")
+}

package/src/server/headers.ts

@@ -9,3 +9,42 @@ export function headerObjectOf(headers: Headers): Record<string, string> {
   for (const [name, value] of headers) out[name.toLowerCase()] = value
   return out
 }
+
+const HEADER_NAME = /^[\w!#$%&'*+.^`|~-]+$/
+
+/** The parts of a header schema's JSON Schema that decide how the slot reads the request. */
+interface HeaderJsonSchema {
+  readonly type?: unknown
+  readonly additionalProperties?: unknown
+  readonly patternProperties?: unknown
+  readonly properties?: object
+}
+
+/**
+ * The names a closed header schema declares, or `undefined` when it is open or lists no names.
+ * Every client sends headers no route declares (`host`, `user-agent`, `accept`), so a closed schema
+ * fed the whole record would refuse all real traffic; it is fed the names it declares instead,
+ * which is also how OpenAPI publishes it. A name that is not a valid header token is never sent.
+ */
+export function declaredHeaderNames(schema: object): readonly string[] | undefined {
+  const json: HeaderJsonSchema | null | undefined = Reflect.get(schema, "jsonSchema")
+  return json?.type === "object" &&
+    json.additionalProperties === false &&
+    json.patternProperties === undefined &&
+    json.properties
+    ? Object.keys(json.properties).filter((name) => HEADER_NAME.test(name))
+    : undefined
+}
+
+/** The declared headers present on the request, each under the name as declared. */
+export function declaredHeaders(
+  headers: Headers,
+  names: readonly string[],
+): Record<string, string> {
+  const out: Record<string, string> = Object.create(null)
+  for (const name of names) {
+    const value = headers.get(name)
+    if (value !== null) out[name] = value
+  }
+  return out
+}

package/src/server/registry.ts

@@ -65,27 +65,26 @@ type IsSuccessCode<Code extends number> = `${Code}` extends `2${string}` ? true
 
 type EmptyResponseMap = NonNullable<unknown>
 
-type StatusBodies<Output, Codes extends number = StatusCodeOf<Output>> = [Codes] extends [never]
-  ? EmptyResponseMap
-  : { [Code in Codes]: StatusBodyAt<Output, Code> }
-
-/** A dynamic status code cannot be classified as success or failure; expose an opaque success arm
- * rather than guessing a status or body schema. Explicit route schemas still override this fallback. */
-type DynamicStatusResponses<Output> =
-  Output extends StatusResponse<infer Code, unknown>
-    ? number extends Code
-      ? { 200: unknown }
-      : EmptyResponseMap
-    : EmptyResponseMap
-
-type InferredResponses<Output> = (Exclude<
+type PlainOutput<Output> = Exclude<Output, StatusResponse<number, unknown> | Response>
+
+type HasDynamicStatus<Output> =
+  Output extends StatusResponse<infer Code, unknown> ? (number extends Code ? true : never) : never
+
+/** A dynamic code may be an error at runtime, but whenever it is a 2xx its body is the one passed to
+ * `status()`, so it joins the 200 arm (`StatusBodyAt` matches it there) instead of reading `unknown`. */
+type UnnamedSuccessCode<Output> = [PlainOutput<Output> | HasDynamicStatus<Output>] extends [never]
+  ? never
+  : 200
+
+/** One map, so a plain return and a `status(200, …)` union on the 200 arm rather than intersect. */
+type InferredResponses<
   Output,
-  StatusResponse<number, unknown> | Response
-> extends never
+  Codes extends number = StatusCodeOf<Output> | UnnamedSuccessCode<Output>,
+> = [Codes] extends [never]
   ? EmptyResponseMap
-  : { 200: Exclude<Output, StatusResponse<number, unknown> | Response> }) &
-  StatusBodies<Output> &
-  DynamicStatusResponses<Output>
+  : {
+      [Code in Codes]: StatusBodyAt<Output, Code> | (Code extends 200 ? PlainOutput<Output> : never)
+    }
 
 type ExplicitResponses<S extends RouteSchema> = (S extends {
   response: infer R extends StandardSchemaV1

package/src/server/request-context.ts

@@ -5,6 +5,7 @@
  * sits below the server module in the graph.
  */
 import type { RequestBudget } from "../budget.ts"
+import { markResidentBody } from "../mount.ts"
 import { applyTransportCap, readBoundedBytes } from "./body.ts"
 import { readBoundedJsonSource } from "./body-lane.ts"
 import type { Platform } from "./context.ts"
@@ -348,7 +349,7 @@ export class RequestContext implements RawContext {
         reply = defer(text, i?.status ?? 200, headers)
       }
     }
-    reply ??= Response.json(body, i)
+    reply ??= markResidentBody(Response.json(body, i))
     // Remembered so a response contract holds the value to the route's schema: this is the
     // framework's JSON helper, not a raw-Response escape hatch.
     this.jsonBody = body
@@ -377,8 +378,10 @@ export class RequestContext implements RawContext {
       }
     }
     // 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_CONTENT_TYPE } })
+    if (i?.headers !== undefined) return markResidentBody(new Response(body, i))
+    return markResidentBody(
+      new Response(body, { ...i, headers: { "content-type": TEXT_CONTENT_TYPE } }),
+    )
   }
 
   get query(): unknown {

package/src/server/request-target.ts

@@ -1,5 +1,6 @@
 /**
- * Dot segments in a request target, resolved the way a WHATWG URL parser resolves them.
+ * Dot segments in a request target, resolved the way a WHATWG URL parser resolves them, and the
+ * characters it percent-encodes in a path, encoded.
  *
  * Bun and workerd hand an app a request whose URL is already parsed: a client that sends
  * `/users/../posts`, `/users/%2e%2e/posts` or `/users/..\posts` is asking for `/posts`, and that
@@ -7,24 +8,28 @@
  * exactly as it was sent. Routing the raw text on those runtimes and the parsed text on the others
  * sends one request to two different handlers - with two different sets of guards - depending on
  * where the app runs. So a raw target is resolved before anything reads it, and every runtime routes
- * the same path.
+ * the same path. The same goes for a raw `/vault<tag>`: the parsed URL is `/vault%3Ctag%3E`, the
+ * path a route registered for that text matches.
  *
  * No imports: `@nifrajs/node` carries a generated copy of this module, since it never depends on
  * core at runtime.
  */
 
-// A `.` or `..` segment (`%2e` counts as a dot, in either case), or a backslash, which a WHATWG
-// parser reads as a `/` in an http(s) path.
-const DOT_SEGMENT = /\\|\/(?:\.|%2e){1,2}(?:[/?#]|$)/i
+// A `.` or `..` segment (`%2e` counts as a dot, in either case), a backslash, which a WHATWG
+// parser reads as a `/` in an http(s) path, or, before any `?` or `#`, a character outside the
+// class the parser keeps as written in a path: a control, space, `"`, `<`, `>`, `^`, `` ` ``, `{`,
+// `}`, or anything past ASCII, all of which it percent-encodes.
+const DOT_SEGMENT =
+  /\\|\/(?:\.|%2e){1,2}(?:[/?#]|$)|^[^?#]*[^!#$%&'()*+,\-./0-9:;=?@A-Z[\\\]_a-z|~]/i
 
 /**
  * Whether `target` - an absolute URL or an origin-form `/path?query` - may hold a `.` or `..`
- * segment, raw or percent-encoded, or a backslash: what a WHATWG parser would rewrite. Never false
- * when the path has one. It can be true when only the query looks like one (`?next=/../x`):
- * resolving that target leaves its path and query as they are, apart from the characters a parser
- * always percent-encodes.
+ * segment, raw or percent-encoded, a backslash, or a character a WHATWG parser percent-encodes in a
+ * path: what that parser would rewrite. Never false when the path has one. It can be true when only
+ * the query looks like one (`?next=/../x`): resolving that target leaves its path and query as they
+ * are, apart from the characters a parser always percent-encodes.
  */
-export function hasDotSegment(target: string): boolean {
+export function needsResolving(target: string): boolean {
   // One regex pass: measured faster on Node and Deno than substring scans that gate it.
   return DOT_SEGMENT.test(target)
 }
@@ -37,10 +42,14 @@ export function hasDotSegment(target: string): boolean {
  * `*`, or text no URL parser accepts - comes back as it arrived: there is no path to resolve.
  */
 export function resolveDotSegments(target: string): string {
+  // Bun, Node and workerd's parsers percent-encode a `^` in a path; Deno's keeps it as written.
   if (target.charCodeAt(0) === 47 /* / */) {
     // Appended to an origin, not resolved against one: `//host/..` must stay a path on this origin.
     const url = new URL(`http://localhost${target}`)
-    return url.pathname + url.search
+    return url.pathname.replaceAll("^", "%5E") + url.search
   }
-  return URL.canParse(target) ? new URL(target).href : target
+  if (!URL.canParse(target)) return target
+  const url = new URL(target)
+  url.pathname = url.pathname.replaceAll("^", "%5E")
+  return url.href
 }

package/src/server/respond.ts

@@ -4,6 +4,7 @@
  * spine types, so the wire-response format lives in one module distinct from the request engine.
  */
 
+import { hasResidentBody, markResidentBody, residentBodiesRecorded } from "../mount.ts"
 import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
 import { plainError } from "./http.ts"
 import {
@@ -227,7 +228,8 @@ const RESPONSE_BODY = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseBody)
 
 /**
  * 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
+ * foreign ones `writableResponse` has already checked. A body the framework serialized itself is
+ * recorded by `markResidentBody` instead, and counts the same. 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.
  */
@@ -252,10 +254,9 @@ export function rememberRenderedResponse(response: Response, hasBody: boolean):
   return response
 }
 
-/** `rememberRenderedResponse` for a Response the framework constructed with a body. */
+/** `rememberRenderedResponse` for a Response the framework built around a body it serialized. */
 function withBody(response: Response): Response {
-  WRITABLE_BODY_RESPONSES.add(response)
-  return response
+  return markResidentBody(response)
 }
 
 const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
@@ -289,7 +290,7 @@ function headersTakeWrites(headers: Headers): boolean {
  * 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 (hasResidentBody(response) || 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.
@@ -426,7 +427,8 @@ export function fusedRespondNoSet(
   // 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.
+  // Default false: an unknown caller pays one WeakSet write rather than a probe per response. Once an
+  // in-process client exists the write is no longer dead: it reads a recorded body whole.
   if (
     unstamped &&
     (tagResponseBody === false || tagResponseBody === undefined) &&
@@ -437,7 +439,8 @@ export function fusedRespondNoSet(
     !(result instanceof Response) &&
     !isResponseResult(result)
   ) {
-    return Response.json(result)
+    const response = Response.json(result)
+    return residentBodiesRecorded ? markResidentBody(response) : response
   }
   if (
     result !== undefined &&