@nifrajs/core 5.6.0 → 5.7.0

package/src/server/server.ts

@@ -69,7 +69,12 @@ import type {
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import type { AuthenticationStage } from "./auth.ts"
+import { withAnswerSteps } from "./answer-step.ts"
+import {
+  type AuthenticationStage,
+  isAuthenticatedRequest,
+  markAuthenticatedRequest,
+} from "./auth.ts"
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.ts"
 import { LAST_BEFORE_HANDLE } from "./before-handler.ts"
 import {
@@ -158,6 +163,7 @@ import {
   type StatusResponse,
 } from "./runtime-core.ts"
 import { normalizeStaticResponseHeaders, type StaticResponseHeaders } from "./static-headers.ts"
+import { withTextSlots } from "./text-slots.ts"
 import { plainValidationError } from "./validation.ts"
 
 // NodeServeOutcome (the nifra<->node bridge render form) now lives in `./node-outcome.ts`; re-exported
@@ -191,6 +197,7 @@ import {
   NODE_NATIVE_MOUNT,
   REPORT_ERROR,
   RESOLVE_NODE_MOUNT,
+  SERVER_LIFECYCLE,
 } from "./install.ts"
 import type { EffectLedgerRuntime } from "./ledger-lane.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
@@ -233,6 +240,7 @@ import type {
   RunningServer,
   ServerOptions,
   StopHook,
+  StopOptions,
   ToolAnnotations,
 } from "./server-types.ts"
 import type { SSEInit, TypedSSEStream } from "./sse.ts"
@@ -572,6 +580,7 @@ export type {
   RunningServer,
   ServerOptions,
   StopHook,
+  StopOptions,
   ToolAnnotations,
 }
 
@@ -778,12 +787,15 @@ function compareMounts<Env>(a: FetchMount<Env>, b: FetchMount<Env>): number {
   return b.priority - a.priority || b.path.length - a.path.length || a.order - b.order
 }
 
+/** Rebase a mounted request's path without losing the authentication mark used by child caches. */
 function stripMountPrefix(request: Request, prefix: string): Request {
   if (prefix === "/") return request
   const url = new URL(request.url)
   const rest = url.pathname.slice(prefix.length)
   url.pathname = rest === "" ? "/" : rest
-  return new Request(url.href, request)
+  const childRequest = new Request(url.href, request)
+  if (isAuthenticatedRequest(request)) markAuthenticatedRequest(childRequest)
+  return childRequest
 }
 
 /** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
@@ -1269,8 +1281,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   private readonly acceptInboundDeadlines: boolean
   private readonly maxInboundDeadlineMs: number
   private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
-  private readonly gracefulSignals: { readonly drainMs?: number } | undefined
+  private readonly gracefulSignals: StopOptions | undefined
   private readonly stopHooks: StopHook[]
+  private readonly stoppingHooks: StopHook[]
   private readonly fetchMounts: FetchMount<EnvOf<Ctx>>[]
   private mountOrder: number
   /** Number of composed mounts that must run before the parent route table. Keeps legacy mounts off the hot path. */
@@ -1365,6 +1378,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           this.staticResponseHeaders,
           // Response hooks write next, and they run for this same request object.
           ctx !== undefined && this.onResponseHooks.length > 0 ? ctx[CONTEXT_REQUEST] : undefined,
+          this.onResponseHooks.length === 0,
         )
   private readonly responseRequests: WeakMap<Request, Request>
   /** A request the WebSocket handshake check ran the onRequest hooks on and then passed to HTTP →
@@ -1433,6 +1447,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     this.gracefulSignals =
       options.gracefulSignals === true ? {} : options.gracefulSignals || undefined
     this.stopHooks = []
+    this.stoppingHooks = []
     this.fetchMounts = []
     this.mountOrder = 0
     this.preRouteMountCount = 0
@@ -1508,6 +1523,18 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     return this
   }
 
+  /**
+   * Register a callback awaited as soon as `stop()` begins, while the server still serves: readiness
+   * should fail from here, and work that outlives a request (a poller, a queue consumer) should stop
+   * taking more. Hung callbacks are bounded.
+   */
+  onStopping(fn: StopHook): this {
+    this.assertConfigurable("onStopping()")
+    if (typeof fn !== "function") throw new TypeError("onStopping callback must be a function")
+    this.stoppingHooks.push(fn)
+    return this
+  }
+
   /**
    * 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.
@@ -2570,6 +2597,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): CatalogRoute {
+    schema = withTextSlots(schema)
     // 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 (
@@ -2617,6 +2645,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       lanes,
       routeAssurance,
     } = compiled
+    // A schema that writes its answer its own way (`t.bytes()`) wraps every stage that can answer.
+    const stages = withAnswerSteps(schema, method, path, {
+      handler,
+      beforeHandle: this.beforeHandleHooks,
+      afterHandle: this.afterHandleHooks,
+      onError: this.onErrorHooks,
+    })
+    handler = stages.handler
+    const { beforeHandle, afterHandle, onError } = stages
     if (idempotent !== undefined && this.idempotencyRuntime !== undefined) {
       handler = this.idempotencyRuntime.wrapHandler(handler)
     }
@@ -2644,8 +2681,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         ? this.buildFusedBodyDeriveBeforeAfterRunner(
             handler as unknown as InternalHandler,
             this.derives[0]!,
-            this.beforeHandleHooks[0]!,
-            this.afterHandleHooks[0],
+            beforeHandle[0]!,
+            afterHandle[0],
             schema?.body as StandardSchemaV1,
             bodyLimit ?? UNLIMITED_BODY_BYTES,
           )
@@ -2653,7 +2690,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           ? this.buildFusedDeriveBeforeRunner(
               handler as unknown as InternalHandler,
               this.derives[0]!,
-              this.beforeHandleHooks[0]!,
+              beforeHandle[0]!,
               undefined,
               schema?.query,
               bodyLimit ?? UNLIMITED_BODY_BYTES,
@@ -2662,8 +2699,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
             ? this.buildFusedDeriveBeforeRunner(
                 handler as unknown as InternalHandler,
                 this.derives[0]!,
-                this.beforeHandleHooks[0]!,
-                this.afterHandleHooks[0],
+                beforeHandle[0]!,
+                afterHandle[0],
                 schema?.query,
                 bodyLimit ?? UNLIMITED_BODY_BYTES,
               )
@@ -2689,8 +2726,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
               ? this.buildFusedBodyDeriveBeforeAfter(
                   handler as unknown as InternalHandler,
                   this.derives[0]!,
-                  this.beforeHandleHooks[0]!,
-                  this.afterHandleHooks[0],
+                  beforeHandle[0]!,
+                  afterHandle[0],
                   schema?.body as StandardSchemaV1,
                   bodyLimit ?? UNLIMITED_BODY_BYTES,
                 )
@@ -2698,7 +2735,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
                 ? this.buildFusedDeriveBefore(
                     handler as unknown as InternalHandler,
                     this.derives[0]!,
-                    this.beforeHandleHooks[0]!,
+                    beforeHandle[0]!,
                     schema?.query,
                     bodyLimit ?? UNLIMITED_BODY_BYTES,
                   )
@@ -2706,8 +2743,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
                   ? this.buildFusedDeriveBeforeAfter(
                       handler as unknown as InternalHandler,
                       this.derives[0]!,
-                      this.beforeHandleHooks[0]!,
-                      this.afterHandleHooks[0]!,
+                      beforeHandle[0]!,
+                      afterHandle[0]!,
                       schema?.query,
                       bodyLimit ?? UNLIMITED_BODY_BYTES,
                     )
@@ -2717,9 +2754,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       handler: handler as unknown as InternalHandler,
       derives: this.derives,
       authStages: compiled.authStages,
-      beforeHandle: this.beforeHandleHooks,
-      afterHandle: this.afterHandleHooks,
-      onError: this.onErrorHooks,
+      beforeHandle,
+      afterHandle,
+      onError,
       decorations: routeDecorations,
       hasDecorations,
       bodySchema: schema?.body,
@@ -2748,9 +2785,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       authStages: [...compiled.authStages],
       decorations: routeDecorations,
       hasDecorations,
-      beforeHandle: [...this.beforeHandleHooks],
-      afterHandle: [...this.afterHandleHooks],
-      onError: [...this.onErrorHooks],
+      beforeHandle: [...beforeHandle],
+      afterHandle: [...afterHandle],
+      onError: [...onError],
       lifecycleHookLane: lanes.lifecycleHookLane,
       around: [...this.aroundHooks],
       execution,
@@ -3190,6 +3227,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // Cleanup the source registered (a pool, a queue consumer) belongs to the server that now runs
     // its routes; dropping it would leak the resource past `stop()`.
     this.stopHooks.push(...source.stopHooks)
+    this.stoppingHooks.push(...source.stoppingHooks)
     this.mcpResourceList.push(...source.mcpResourceList)
     this.mcpPromptList.push(...source.mcpPromptList)
   }
@@ -3995,14 +4033,6 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
             return refuse(jsonError(500, "internal_error"))
           }
         }
-        const child =
-          mount.authStages.length === 0
-            ? upgrade()
-            : thenMaybe(
-                authenticateMount(mount.authStages, request, platform, this.logger),
-                (refusal): MaybePromise<WebSocketUpgradeOutcome> =>
-                  refusal === undefined ? upgrade() : refuse(refusal),
-              )
         const settle = (outcome: WebSocketUpgradeOutcome): MaybePromise<WebSocketUpgradeOutcome> =>
           outcome.kind === "pass" ||
           (outcome.kind === "reject" && outcome.response.status === 404 && selected!.fallbackOn404)
@@ -4010,7 +4040,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
             : outcome.kind === "reject"
               ? refuse(outcome.response)
               : outcome
-        return child instanceof Promise ? child.then(settle) : settle(child)
+        const run = (): MaybePromise<WebSocketUpgradeOutcome> => {
+          const child = upgrade()
+          return child instanceof Promise ? child.then(settle) : settle(child)
+        }
+        // Only a child's miss may fall through, never an authentication refusal.
+        return mount.authStages.length === 0
+          ? run()
+          : thenMaybe(
+              authenticateMount(mount.authStages, request, platform, this.logger),
+              (refusal) => (refusal === undefined ? run() : refuse(refusal)),
+            )
       }
       return dispatch(0)
     }
@@ -4517,25 +4557,30 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       if (mount === undefined) return fallback ?? jsonError(404, "not_found")
       const selected = mount
       const run = (): MaybePromise<Response> => {
+        const reused = selected.stripPrefix ? selected.wsPassed?.get(request) : undefined
         const childRequest = selected.stripPrefix
-          ? (selected.wsPassed?.get(request) ?? stripMountPrefix(request, selected.path))
+          ? (reused ?? stripMountPrefix(request, selected.path))
           : request
-        return selected.handler(childRequest, platform)
-      }
-      const outcome =
-        mount.authStages.length === 0
-          ? run()
-          : thenMaybe(
-              authenticateMount(mount.authStages, request, platform, this.logger),
-              (refusal) => refusal ?? run(),
-            )
-      if (!replayable || !mount.fallbackOn404) return outcome
-      if (outcome instanceof Promise) {
-        return outcome.then((response) =>
-          response.status === 404 ? dispatch(index + 1, response) : response,
-        )
+        // HTTP authentication may have marked the original since the WebSocket pass.
+        if (reused !== undefined && isAuthenticatedRequest(request)) {
+          markAuthenticatedRequest(reused)
+        }
+        const outcome = selected.handler(childRequest, platform)
+        if (!replayable || !selected.fallbackOn404) return outcome
+        if (outcome instanceof Promise) {
+          return outcome.then((response) =>
+            response.status === 404 ? dispatch(index + 1, response) : response,
+          )
+        }
+        return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome
       }
-      return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome
+      // Keep gate refusals outside the child's 404 fallthrough path.
+      return mount.authStages.length === 0
+        ? run()
+        : thenMaybe(
+            authenticateMount(mount.authStages, request, platform, this.logger),
+            (refusal) => refusal ?? run(),
+          )
     }
     return dispatch(first)
   }
@@ -7205,11 +7250,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * The Bun semantics: poll `pendingRequests` (awaiting
    * `stop()`'s promise drops in-flight requests), and decide graceful-vs-forced in
    * ONE call (Bun can't escalate an already-graceful `stop()` to a forced close).
-   * New connections may be accepted during the drain window; in a real deploy the
-   * load balancer has already stopped routing here, and `drainMs` bounds it. Open WebSockets
-   * get a 1001 close at once and the same window to finish it, before any `onStop` hook runs.
+   * New connections may be accepted during the drain window; `delayMs` is the time a load balancer
+   * gets to stop routing here first. The `onStopping` hooks run before that delay, the `onStop`
+   * hooks after the drain. Open WebSockets get a 1001 close when the drain starts and the same
+   * window to finish it; a socket opened after `stop()` began is closed at once.
    */
-  async stop({ drainMs = DEFAULT_DRAIN_MS }: { drainMs?: number } = {}): Promise<void> {
+  async stop({ drainMs = DEFAULT_DRAIN_MS, delayMs = 0 }: StopOptions = {}): Promise<void> {
     const onSignal = this.signalHandler
     if (onSignal !== undefined) {
       this.signalHandler = undefined
@@ -7218,6 +7264,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     const server = this.bunServer
     if (server === undefined) return
     this.bunServer = undefined
+    await this[SERVER_LIFECYCLE]("stopping")
+    if (delayMs > 0) await Bun.sleep(delayMs)
     const sockets = this.bunSockets
     this.bunSockets = undefined
     if (sockets !== undefined) for (const ws of sockets) ws.close(1001)
@@ -7227,16 +7275,28 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       await Bun.sleep(DRAIN_POLL_MS)
     }
     server.stop(busy()) // force-close iff stragglers remain past the deadline
-    if (this.stopHooks.length === 0) return
-    const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook))
-    const settled = Promise.allSettled(callbacks)
+    await this[SERVER_LIFECYCLE]("stopped")
+  }
+
+  /**
+   * @internal Run the `onStopping` or the `onStop` hooks, each bounded. A runtime adapter that drains
+   * its own listener calls it on either side of the drain, as `stop()` does here.
+   */
+  async [SERVER_LIFECYCLE](phase: "stopping" | "stopped"): Promise<void> {
+    const hooks = phase === "stopping" ? this.stoppingHooks : this.stopHooks
+    if (hooks.length === 0) return
+    let timer: ReturnType<typeof setTimeout> | undefined
     await Promise.race([
-      settled,
-      new Promise<void>((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+      Promise.allSettled(hooks.map((hook) => Promise.resolve().then(hook))),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)
+      }),
     ])
+    // A pending bound would hold the event loop open after every hook settled.
+    clearTimeout(timer)
   }
 
-  private installSignalHandlers(drain: { readonly drainMs?: number }): void {
+  private installSignalHandlers(drain: StopOptions): void {
     // Drain, then let the process exit naturally - the stopped server no longer
     // holds the event loop open. Opt-in (`gracefulSignals`), so taking over the
     // signals is consented; we don't force `process.exit`.

package/src/server/sse.ts

@@ -22,6 +22,7 @@
  *   }, { keepAlive: 15_000 }))
  */
 import { INSTALL_SSE } from "./install.ts"
+import { jsonText } from "./json-text.ts"
 import type { IdentityPlugin } from "./plugin.ts"
 import type { AnyServer } from "./server.ts"
 import type { SseRuntime } from "./sse-hook.ts"
@@ -92,7 +93,7 @@ export interface TypedSSEStream<Event> {
 export function typedSSEStream<Event>(stream: SSEStream): TypedSSEStream<Event> {
   return {
     send(event, init = {}) {
-      stream.send({ ...init, data: JSON.stringify(event) })
+      stream.send({ ...init, data: jsonText(event) })
     },
     comment(text) {
       stream.send({ comment: text })

package/src/server/text-slots.ts

@@ -0,0 +1,21 @@
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { RouteSchema } from "./context.ts"
+
+// What a schema offers for a slot whose values arrive as text: `@nifrajs/schema` sets it on a
+// `t.object` (and any `t` schema that does not coerce) to the coercing form of the same schema.
+const TEXT_SLOT = Symbol.for("nifra.schema.textSlot")
+
+/**
+ * `schema` with its `query`, `headers` and `cookies` schemas swapped for the text form each offers, or
+ * `schema` itself when none offers one. A query string, header values and a `Cookie` header are
+ * always text, so a schema that reads a boolean or a number there can only validate its coercing form.
+ */
+export function withTextSlots(schema: RouteSchema | undefined): RouteSchema | undefined {
+  let out = schema
+  for (const slot of ["query", "headers", "cookies"] as const) {
+    const validate = out?.[slot]?.["~standard"].validate
+    const form: StandardSchemaV1 | undefined = validate && Reflect.get(validate, TEXT_SLOT)
+    if (form !== undefined) out = { ...out, [slot]: form }
+  }
+  return out
+}

package/src/server.ts

@@ -108,6 +108,7 @@ export type {
 } from "./server/registry.ts"
 export { replacedRequestOf } from "./server/request-lineage.ts"
 export { writableResponse } from "./server/respond.ts"
+export { routeTemplateOf } from "./server/route-template.ts"
 export {
   type PlainRender,
   type ResponseResult,

package/src/single-copy.ts

@@ -78,13 +78,9 @@ export const IDENTITY_SENSITIVE_PACKAGES: readonly string[] = [
 /** Files a redirect may rewrite. Everything else in a package (json, css, wasm) loads unchanged. */
 const REDIRECTABLE = /\.(?:m|c)?[jt]sx?$/
 
-/** The loader a {@link REDIRECTABLE} file is parsed with. `.ts` is never `tsx`: under JSX rules a
- * generic arrow (`<T>(x: T) => x`) reads as an unclosed element and swallows the file. */
-function sourceLoader(path: string): "js" | "jsx" | "ts" | "tsx" {
-  if (path.endsWith(".tsx")) return "tsx"
-  if (path.endsWith(".jsx")) return "jsx"
-  return /\.[mc]?ts$/.test(path) ? "ts" : "js"
-}
+/** Appended to a linked file the load hook hands back to Bun untouched; see the hook. */
+const OWN_FILE_QUERY = "?nifra-single-copy"
+
 /** Runaway guards. A real `node_modules` top level is hundreds of entries, a repo walk is a few. */
 const MAX_SCANNED_ENTRIES = 4_096
 const MAX_ANCESTOR_DIRS = 16
@@ -233,6 +229,11 @@ export interface SingleCopyRegistration {
   readonly run: boolean
   /** `[test] preload`: covers `bun test`, the surface that runs app sources unbundled. */
   readonly test: boolean
+  /**
+   * Tables whose `preload` names the registrar although Bun reads it from neither place: below
+   * `[install]` the line is `install.preload`, so `bun run` loads every copy while the file looks armed.
+   */
+  readonly ignored?: readonly string[]
   /** The `bunfig.toml` that was read, if one exists. */
   readonly config?: string
 }
@@ -286,6 +287,7 @@ export function readSingleCopyRegistration(cwd: string): SingleCopyRegistration
   let section = ""
   let run = false
   let test = false
+  const ignored: string[] = []
   for (const line of text.split(/\r?\n/)) {
     const match = PRELOAD_ASSIGNMENT.exec(line)
     if (match?.groups === undefined) continue
@@ -298,8 +300,9 @@ export function readSingleCopyRegistration(cwd: string): SingleCopyRegistration
       continue
     if (section === "test") test = true
     else if (section === "") run = true
+    else if (!ignored.includes(section)) ignored.push(section)
   }
-  return { run, test, config }
+  return ignored.length === 0 ? { run, test, config } : { run, test, ignored, config }
 }
 
 /** The repository a linked checkout resolves its own dependencies from: its nearest `.git` ancestor.
@@ -598,6 +601,8 @@ export function singleCopyPlugin(options: SingleCopyOptions = {}): SingleCopyPlu
       // hook has to return contents for everything it matches, and re-emitting a CommonJS entry as an
       // ES module is how `Export named 'useEffect' not found` happens.
       const filter = new RegExp(`^(?:${roots})[/\\\\].*${REDIRECTABLE.source}`)
+      // `Bun.plugin` leaves `config` unset although the type says otherwise; only `Bun.build` sets it.
+      const bundling = build.config !== undefined
       build.onLoad({ filter }, (args) => {
         for (const redirect of plan.redirects) {
           const target = counterpart(redirect, args.path)
@@ -616,10 +621,13 @@ export function singleCopyPlugin(options: SingleCopyOptions = {}): SingleCopyPlu
             detail: `${relative(owner.from, args.path)} has no file at the same path in the app's copy, so it loads from the linked copy and its module state is not shared`,
           })
         }
-        // A runtime `onLoad` must always return an object - returning nothing fails the load rather
-        // than falling through to the default. Hand back the file as it was, at its own path, so its
-        // relative imports keep resolving exactly as they would have.
-        return { contents: readFileSync(args.path, "utf8"), loader: sourceLoader(args.path) }
+        // The file loads as it is, in its own module format. A bundler takes `undefined` for that. A
+        // runtime `onLoad` must return an object, and source returned from here loads as an ES module,
+        // which empties a CommonJS file's exports - so the runtime gets a re-export of the file under a
+        // query the filter's `$` cannot match, which Bun then loads natively from its own directory.
+        // There its `__filename` and `import.meta.url` carry the query; the bundler cannot resolve it.
+        if (bundling) return undefined
+        return { contents: reexport(`${args.path}${OWN_FILE_QUERY}`), loader: "js" }
       })
     },
   }
@@ -646,12 +654,20 @@ const processSet = (key: symbol): Set<string> => {
 const copyLine = (label: string, path: string | undefined, version: string | undefined): string =>
   `  ${label}: ${path ?? "(not installed for the app)"}${version === undefined ? "" : ` (${version})`}`
 
-/** One report per package: both copies, both versions, the reason, and the fix. */
+/**
+ * One report per package: both copies, both versions, the reason, and the fix. A version skew comes
+ * from the plan, which reads installs, so it says installed: nothing may ever load that copy, and a
+ * runtime `onLoad` cannot watch for it without re-emitting CommonJS files as ES modules.
+ */
 const describeSkips = (name: string, skips: readonly SingleCopySkip[]): string => {
   const first = skips[0]
   const reason = first?.reason ?? "version-skew"
+  const effect =
+    reason === "version-skew"
+      ? "a second copy is installed at another version, and whatever loads it does not share this copy's module state."
+      : "a second copy loads, so its module state is not shared."
   const lines = [
-    `[nifra] single-copy: ${name} is NOT deduplicated (${reason}) - a second copy loads, so its module state is not shared.`,
+    `[nifra] single-copy: ${name} is NOT deduplicated (${reason}) - ${effect}`,
     copyLine("app copy", first?.to, first?.toVersion),
   ]
   for (const skip of skips) {
@@ -683,7 +699,7 @@ const describeSkewGroup = (skips: readonly SingleCopySkip[]): string => {
   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.`,
+    `[nifra] single-copy: ${names.length} packages are NOT deduplicated (version-skew) - a second copy of each is installed at another version, and whatever loads one does not share the app copy's module state.`,
     copyLine(
       "app copies",
       first.to === undefined ? undefined : modulesDirOf(first.to),

package/src/transport-codec.ts

@@ -3,6 +3,8 @@
  * remains the zero-configuration fast path; rich wire is explicit and preserves non-JSON values.
  */
 
+import { jsonText } from "./server/json-text.ts"
+
 const DEFAULT_MAX_BYTES = 16 * 1024 * 1024
 const TOKEN = /^[a-z][a-z0-9_.-]{0,63}$/
 
@@ -81,7 +83,7 @@ export const plainJsonCodec: TransportCodec = Object.freeze({
   version: 1,
   mediaType: "application/json",
   encode(value: unknown): string {
-    const encoded = JSON.stringify(value)
+    const encoded = jsonText(value)
     if (encoded === undefined) throw new TransportCodecError("value is not JSON serializable")
     return encoded
   },