@c9up/ream 0.2.17 → 0.2.18

package/src/container/Container.ts

@@ -115,15 +115,36 @@ export class Container {
   /** Register a singleton binding (factory called once, cached). */
   singleton<_T>(token: ServiceToken, factory: ServiceFactory): void {
     const key = this.#tokenToKey(token)
+    this.#forgetCached(key)
     this.#bindings.set(key, { token, factory, scope: 'singleton', dependencies: [] })
   }
 
   /** Register a transient binding (new instance per resolve). */
   bind<_T>(token: ServiceToken, factory: ServiceFactory): void {
     const key = this.#tokenToKey(token)
+    this.#forgetCached(key)
     this.#bindings.set(key, { token, factory, scope: 'transient', dependencies: [] })
   }
 
+  /**
+   * Drop what a previous binding produced, because the binding is being
+   * replaced.
+   *
+   * Resolution reads the cache BEFORE the binding, so a token re-registered
+   * with a new factory kept answering with the old instance — a rebind that
+   * changed nothing, silently. That is what a provider does when it boots a
+   * second time in one process (a hot reload, a test that restarts the app):
+   * it rebinds, and the container went on handing out the connection the
+   * previous shutdown had closed.
+   *
+   * The in-flight promise goes too: a resolution already awaiting the OLD
+   * factory must not become the value of the new binding.
+   */
+  #forgetCached(key: ServiceToken): void {
+    this.#singletons.delete(key)
+    this.#pendingSingletons.delete(key)
+  }
+
   /** Bind an existing value directly. */
   bindValue<T>(token: ServiceToken, value: T): void {
     const key = this.#tokenToKey(token)
@@ -348,38 +369,48 @@ export class Container {
       )
     }
     const outerParent = chain.parent
-    chain.parent = target
-    const paramTypes: unknown[] =
-      Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
-    // `@Inject('token')` on a method parameter — a named binding the reflected
-    // type cannot express (an interface, or a class registered under a name).
-    const injectTokens = getMethodInjectTokens(target.prototype, method)
-
-    // `@Inject` counts towards the parameter span too: a method may carry named
-    // tokens without `design:paramtypes` being emitted for it, and computing the
-    // span from the reflected types alone left the loop at zero iterations —
-    // the tokens were read and then never used.
-    const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
-    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
-    // Sequential resolution keeps the shared cycle-detection stack consistent.
+    // Declared outside the try so the call below can still read it: only the
+    // RESOLUTION is guarded, because that is what can throw with the parent
+    // installed.
     const args: unknown[] = []
-    for (let index = 0; index < len; index += 1) {
-      // Runtime values take precedence (and fill slots beyond paramTypes).
-      if (runtimeValues && index < runtimeValues.length) {
-        args.push(runtimeValues[index])
-        continue
-      }
-      const named = injectTokens.get(index)
-      if (named !== undefined) {
-        args.push(await this.resolve(named))
-        continue
+    chain.parent = target
+    try {
+      const paramTypes: unknown[] =
+        Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
+      // `@Inject('token')` on a method parameter — a named binding the reflected
+      // type cannot express (an interface, or a class registered under a name).
+      const injectTokens = getMethodInjectTokens(target.prototype, method)
+
+      // `@Inject` counts towards the parameter span too: a method may carry named
+      // tokens without `design:paramtypes` being emitted for it, and computing the
+      // span from the reflected types alone left the loop at zero iterations —
+      // the tokens were read and then never used.
+      const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
+      const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
+      // Sequential resolution keeps the shared cycle-detection stack consistent.
+      for (let index = 0; index < len; index += 1) {
+        // Runtime values take precedence (and fill slots beyond paramTypes).
+        if (runtimeValues && index < runtimeValues.length) {
+          args.push(runtimeValues[index])
+          continue
+        }
+        const named = injectTokens.get(index)
+        if (named !== undefined) {
+          args.push(await this.resolve(named))
+          continue
+        }
+        const type = paramTypes[index]
+        args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
       }
-      const type = paramTypes[index]
-      args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
+    } finally {
+      // RESTORED whatever happened. Without the `finally`, a parameter that
+      // failed to resolve left the called class installed as the parent, so a
+      // caller that caught the error saw its contextual bindings applied to
+      // every later resolution — a binding meant for one handler leaking into
+      // the whole application.
+      chain.parent = outerParent
     }
 
-    chain.parent = outerParent
-
     const member: unknown = instance[method]
     if (!isCallable(member)) {
       throw new Error(`Container.call: '${method}' is not a callable method`)
@@ -576,19 +607,47 @@ export class Container {
         return instance as T
       }
 
-      // A build already under way: join it rather than start a second one.
+      // A build already under way: join it rather than start a second one —
+      // but only take its result if it was actually PUBLISHED. A factory that
+      // reads a request-scoped value builds that request's instance, and
+      // `#cacheIfAppWide` deliberately refuses to cache it; handing it to the
+      // resolver waiting behind was one request's HttpContext, identity or
+      // tenant answering for another. That resolution builds its own instead.
       const inFlight = this.#pendingSingletons.get(key)
-      if (inFlight) return (await inFlight) as T
+      if (inFlight) {
+        const shared = await inFlight
+        if (this.#wasPublished(key, shared)) return shared as T
+      }
 
       const readsBefore = store?.scopedReads ?? 0
       const building = (async (): Promise<unknown> => {
         const instance = binding.factory ? await binding.factory(this) : undefined
+        // Only cache while this is still the binding that started the build.
+        // A rebind that landed mid-flight already dropped the cache; letting
+        // the old factory write its result afterwards restored exactly what the
+        // rebind existed to replace.
+        if (this.#bindings.get(key) !== binding) return instance
+        // Hooks FIRST, cache after. Published before they ran, a singleton
+        // whose `resolving` hook threw was already in the cache: the caller saw
+        // the error, and the next resolution was handed the same half-built
+        // instance with no hook, no error and nothing to say a step had been
+        // skipped. A hook that opens a connection, validates a config or wraps
+        // a security decorator failing is precisely when the instance must not
+        // be reachable.
+        //
+        // Upstream's hooks are documented as modifying the value BEFORE it is
+        // returned, which only holds if the value is not already shared.
+        //
+        // Inside the promise, so the hooks run exactly once per instance no
+        // matter how many callers were waiting; the pending promise is what
+        // keeps concurrent callers from building a second one.
+        await this.#runResolvingHooks(key, instance)
+        // Re-checked: a rebind can land while the hooks run, and the cache it
+        // dropped must not be refilled by the build it replaced.
+        if (this.#bindings.get(key) !== binding) return instance
         // See `ResolutionChain.scopedReads`: a build that consumed a
         // request-scoped value is that request's, not the application's.
         this.#cacheIfAppWide('singleton', key, instance, store, readsBefore)
-        // Inside the promise, so the hooks run exactly once per instance no
-        // matter how many callers were waiting.
-        await this.#runResolvingHooks(key, instance)
         return instance
       })()
       this.#pendingSingletons.set(key, building)
@@ -596,15 +655,17 @@ export class Container {
         return (await building) as T
       } finally {
         // Cleared either way: a failed build must not poison later attempts.
-        this.#pendingSingletons.delete(key)
+        // Guarded, so a rebind that installed its own pending build is not
+        // undone by the old one finishing afterwards.
+        if (this.#pendingSingletons.get(key) === building) {
+          this.#pendingSingletons.delete(key)
+        }
       }
     }
 
     // 6. Auto-construct if it's a class
     if (typeof token === 'function') {
-      const instance = (await this.#autoConstruct(token, runtimeValues)) as T
-      await this.#runResolvingHooks(key, instance)
-      return instance
+      return (await this.#resolveAutoConstructed(token, runtimeValues)) as T
     }
 
     // 7. Not found
@@ -628,6 +689,66 @@ export class Container {
    * 2. Reflect.getMetadata('design:paramtypes') — decorator metadata (requires SWC/tsc)
    * 3. No params → plain `new Class()`
    */
+  /**
+   * Resolve a class the container builds itself — through the SAME pipeline as
+   * an explicit singleton binding.
+   *
+   * `@Service({ scope: 'singleton' })` never goes through a binding, so this
+   * path had its own, weaker rules: the instance was cached on the way out of
+   * construction and the `resolving` hooks ran afterwards, so a hook that threw
+   * left a half-built object in the cache for the next caller — the failure the
+   * explicit path was fixed for, on the path most applications actually use.
+   * It also never joined `#pendingSingletons`, so two resolutions in flight at
+   * once each built their own and whichever finished last was the one everybody
+   * got.
+   *
+   * Pending promise, then construction, then hooks, then publication. In that
+   * order, on both paths.
+   */
+  async #resolveAutoConstructed(
+    target: abstract new (...args: never[]) => unknown,
+    runtimeValues?: unknown[],
+  ): Promise<unknown> {
+    const metadata = getServiceMetadata(target)
+    const key = metadata?.as ?? target
+
+    if (metadata?.scope !== 'singleton') {
+      const instance = await this.#autoConstruct(target, runtimeValues)
+      await this.#runResolvingHooks(key, instance)
+      return instance
+    }
+
+    if (this.#singletons.has(key)) return this.#singletons.get(key)
+    const inFlight = this.#pendingSingletons.get(key)
+    if (inFlight) {
+      const shared = await inFlight
+      // Joined ONLY if that build was published application-wide. A build that
+      // consumed a request-scoped value belongs to its request — handing it to
+      // another one is exactly the leak `createResolver()` exists to prevent —
+      // so this resolution falls through and builds its own instead.
+      if (this.#wasPublished(key, shared)) return shared
+    }
+
+    // Same rule as the explicit bindings: see `ResolutionChain.scopedReads`.
+    const store = this.#chain.getStore()
+    const readsBefore = store?.scopedReads ?? 0
+    const building = (async (): Promise<unknown> => {
+      const instance = await this.#autoConstruct(target, runtimeValues)
+      await this.#runResolvingHooks(key, instance)
+      this.#cacheIfAppWide('singleton', key, instance, store, readsBefore)
+      return instance
+    })()
+    this.#pendingSingletons.set(key, building)
+    try {
+      return await building
+    } finally {
+      // Cleared either way: a failed build must not poison later attempts.
+      if (this.#pendingSingletons.get(key) === building) {
+        this.#pendingSingletons.delete(key)
+      }
+    }
+  }
+
   async #autoConstruct(
     target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
@@ -649,20 +770,19 @@ export class Container {
     target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
-    const metadata = getServiceMetadata(target)
-    const scope = metadata?.scope ?? 'transient'
     // The class itself, not `target.name`: two classes called `Service` share a
     // name and must not share a singleton cache entry.
+    const metadata = getServiceMetadata(target)
     const key = metadata?.as ?? target
 
-    if (scope === 'singleton' && this.#singletons.has(key)) {
+    // A cached singleton short-circuits construction — for the callers that
+    // reach this directly (`autoRegister`'s factory). PUBLISHING it is not this
+    // method's business: it builds, and `#resolveAutoConstructed` decides when
+    // the result may be shared, after the hooks have had their say.
+    if (metadata?.scope === 'singleton' && this.#singletons.has(key)) {
       return this.#singletons.get(key)
     }
 
-    // Same rule as the explicit singleton bindings: see `scopedReads`.
-    const store = this.#chain.getStore()
-    const readsBefore = store?.scopedReads ?? 0
-
     // A runtime value at this index (from `make(Class, [req, res])`) wins over
     // container resolution for that constructor slot.
     const runtimeAt = (index: number): unknown => runtimeValues?.[index]
@@ -698,7 +818,6 @@ export class Container {
           deps.push(depToken ? await this.resolve(depToken) : undefined)
         }
         const instance = Reflect.construct(target, deps)
-        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (b) No @Inject/metadata, but the caller supplied runtime values — build
@@ -707,7 +826,6 @@ export class Container {
       if (target.length > 0 && (runtimeValues?.length ?? 0) > 0) {
         const deps = Array.from({ length: target.length }, (_value, index) => runtimeAt(index))
         const instance = Reflect.construct(target, deps)
-        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (c) The constructor declares parameters but we have no way to resolve
@@ -729,7 +847,6 @@ export class Container {
       // one is a compile error even though the runtime constructs it happily —
       // `abstract` exists only at compile time.
       const instance = Reflect.construct(target, [])
-      this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
       return instance
     }
 
@@ -752,7 +869,6 @@ export class Container {
     }
 
     const instance = Reflect.construct(target, deps)
-    this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
     return instance
   }
 
@@ -764,6 +880,20 @@ export class Container {
    * later one. AdonisJS does not guard this; it is the kind of silent
    * cross-request leak worth refusing.
    */
+  /**
+   * Is `instance` the value that was published under `key`?
+   *
+   * `Object.is`, not `===`: a factory answering `NaN` compares unequal to
+   * itself, so a waiter concluded the build had not been published and built a
+   * second singleton. And `has()` before the comparison, because an absent
+   * entry and one holding `undefined` both read back as `undefined` — a
+   * request-scoped build that produced nothing was then shared with the next
+   * request, which is the whole thing this check exists to prevent.
+   */
+  #wasPublished(key: ServiceToken, instance: unknown): boolean {
+    return this.#singletons.has(key) && Object.is(this.#singletons.get(key), instance)
+  }
+
   #cacheIfAppWide(
     scope: string,
     key: ServiceToken,

package/src/container/types.ts

@@ -38,6 +38,17 @@ export type ServiceToken = (abstract new (...args: never[]) => unknown) | string
  */
 export interface FactoryResolver {
   make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T>
+  /**
+   * Call a method with its dependencies injected. Declared here because a
+   * factory that dispatches to a handler needs it and both implementations
+   * have it — leaving it off did not make the capability go away, it only
+   * hid it from the callers allowed to use it.
+   */
+  call<T, K extends string & keyof T>(
+    instance: T,
+    method: K,
+    runtimeValues?: unknown[],
+  ): Promise<unknown>
 }
 
 /**

package/src/dev/hmr.ts

@@ -0,0 +1,83 @@
+/**
+ * What the browser watches to know the server changed under it.
+ *
+ * Two things can happen while `ream dev` runs, and the page has no way to see
+ * either: a module is swapped in the running process (hot-hook invalidated it),
+ * or the process restarts. Both change what the server would render, and both
+ * used to leave a stale page on screen until someone pressed reload.
+ *
+ * NAMED DEVIATION — upstream has no equivalent. AdonisJS' assembler does not
+ * refresh the browser; that comes from its Vite integration, i.e. from the
+ * asset pipeline. Ream has no such pipeline in the general case, so this lives
+ * in the framework, and it is deliberately the smallest thing that works: a
+ * token the page polls, not a socket. A socket would still need a reconnect
+ * loop and a boot identity to survive the restart half, which is most of a
+ * poller with more moving parts.
+ */
+
+/** Where the token is served, and what the injected script polls. */
+export const HMR_PATH = '/__ream/hmr'
+
+/**
+ * Identifies THIS process. A restart produces a new one, which is how the page
+ * detects a reboot without the server having to survive it to say so.
+ */
+const BOOT_ID = `${process.pid}-${Date.now().toString(36)}`
+
+/** Bumped by `@c9up/ream/hot` every time hot-hook swaps a module. */
+const COUNTER = Symbol.for('ream.dev.hotReloadCount')
+
+interface CounterHolder {
+  [COUNTER]?: number
+}
+
+/**
+ * A module-level variable would not do: `@c9up/ream/hot` is loaded through a
+ * different module graph than the running application (it is an `--import`
+ * entry), so the two would each hold their own copy. A well-known symbol on
+ * `globalThis` is the one place both can see.
+ */
+function holder(): CounterHolder {
+  return globalThis as unknown as CounterHolder
+}
+
+/** Called by the hot entry when hot-hook reports a module was swapped. */
+export function hotReloadHappened(): void {
+  const store = holder()
+  store[COUNTER] = (store[COUNTER] ?? 0) + 1
+}
+
+/** How many hot swaps this process has seen. */
+export function hotReloadCount(): number {
+  return holder()[COUNTER] ?? 0
+}
+
+/**
+ * The token. Changes on a restart (new boot id) and on a hot swap (new count),
+ * which are exactly the two cases the page must react to.
+ */
+export function hmrToken(): string {
+  return `${BOOT_ID}.${hotReloadCount()}`
+}
+
+/**
+ * The script injected into HTML pages in dev.
+ *
+ * It reloads when the token changes, NOT when the request fails: a server that
+ * is restarting is unreachable for a moment, and reloading then would only show
+ * the browser's error page. It waits for an answer, and the answer carries a
+ * new boot id.
+ */
+export function hmrClientScript(nonce?: string): string {
+  // A nonce-based CSP — which the scaffold ships, via `@c9up/blackhole` —
+  // rejects an inline script that does not carry the request's nonce, and the
+  // page simply never reloads. `response.nonce` is where it lives; the quotes
+  // are escaped because a nonce is generated, not user input, but a broken
+  // attribute would silently disable the tag rather than fail loudly.
+  const attribute = nonce === undefined ? '' : ` nonce="${nonce.replace(/"/g, '"')}"`
+  // A failed poll RETRIES. Returning on `!r.ok` stopped the loop for good, so a
+  // page opened in the window before the endpoint is mounted — or during any
+  // blip — never reloaded again for the life of that tab, which looks exactly
+  // like the feature not working.
+  return `<script${attribute}>(()=>{let t=null;const p=${JSON.stringify(HMR_PATH)};const tick=async()=>{try{const r=await fetch(p,{cache:'no-store'});if(r.ok){const n=(await r.text()).trim();if(t===null){t=n}else if(n!==t){location.reload();return}}}catch(e){}setTimeout(tick,1000)};tick()})()</script>`
+}

package/src/graphql/GraphQLProvider.ts

@@ -9,8 +9,9 @@
  *       const gql = app.container.make<GraphQLEngine>('graphql')
  *       gql.resolver('Query', 'tasks', TaskResolver, 'tasks')
  *
- *   - `boot()` — mount the engine at `engine.path` (default `/graphql`) for both
- *     GET (playground/introspection) and POST (queries).
+ *   - `start()` — mount the engine at `engine.path` (default `/graphql`) for
+ *     both GET (playground/introspection) and POST (queries). In `start`, which
+ *     is the phase upstream documents for routes.
  *
  * @implements Story 24.5
  */
@@ -66,7 +67,17 @@ export class GraphQLProvider extends Provider {
     this.#registered = true
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const engine = this.#engine
     if (!engine) return
     const router = await this.app.container.make<Router>('router')

package/src/hot.ts

@@ -0,0 +1,165 @@
+/**
+ * Dev-only entry hook: hot module replacement for the running server.
+ *
+ * `ream dev` loads this before the application entry:
+ *
+ *   node --import @swc-node/register/esm-register --import @c9up/ream/hot bin/server.ts
+ *
+ * It is a thin shim over `hot-hook`, which does the actual work: it registers
+ * an ESM loader that tracks the import graph, and when a file inside a declared
+ * boundary changes it invalidates just that module instead of the process. The
+ * `hotHook` key in the application's `package.json` configures it, exactly as
+ * upstream reads it.
+ *
+ * NAMED DEVIATION — why this file exists at all.
+ *
+ * Upstream's dev server is itself a Node process: it forks the app, so the two
+ * talk over Node's IPC channel, and `hot-hook` reports a change it cannot swap
+ * by calling `process.send({ type: 'hot-hook:full-reload' })`. Our dev server is
+ * a Rust binary. A process it spawns has NO IPC channel, so `process.send` is
+ * `undefined` and that message goes nowhere: the server would keep serving the
+ * old module and say nothing.
+ *
+ * `hot.init()` takes an `onFullReloadAsked` callback for exactly this case, and
+ * that is the whole of the shim: turn "I cannot hot-swap this" into an exit
+ * code the Rust parent understands and restarts on. Everything else is
+ * upstream's behaviour, unmodified.
+ */
+
+import { hotReloadHappened } from './dev/hmr.js'
+
+/** Exit code meaning "restart me" — see `EXIT_RESTART` in the CLI's dev module. */
+const FULL_RELOAD_EXIT_CODE = 75
+
+interface HotHook {
+  init(options: {
+    rootDirectory: string
+    root?: string
+    boundaries?: string[]
+    restart?: string[]
+    ignore?: string[]
+    throwWhenBoundariesAreNotDynamicallyImported?: boolean
+    onFullReloadAsked?: () => void
+  }): Promise<void>
+}
+
+interface HotHookConfig {
+  root?: string
+  boundaries?: string[]
+  restart?: string[]
+  ignore?: string[]
+  throwWhenBoundariesAreNotDynamicallyImported?: boolean
+}
+
+/** Read `hotHook` out of the application's package.json, with no assumptions. */
+function readConfig(pkg: unknown): HotHookConfig {
+  if (typeof pkg !== 'object' || pkg === null) return {}
+  const raw = Reflect.get(pkg, 'hotHook')
+  if (typeof raw !== 'object' || raw === null) return {}
+  const stringArray = (key: string): string[] | undefined => {
+    const value = Reflect.get(raw, key)
+    if (!Array.isArray(value)) return undefined
+    return value.filter((entry): entry is string => typeof entry === 'string')
+  }
+  const root = Reflect.get(raw, 'root')
+  const strict = Reflect.get(raw, 'throwWhenBoundariesAreNotDynamicallyImported')
+  return {
+    root: typeof root === 'string' ? root : undefined,
+    boundaries: stringArray('boundaries'),
+    restart: stringArray('restart'),
+    ignore: stringArray('ignore'),
+    throwWhenBoundariesAreNotDynamicallyImported: typeof strict === 'boolean' ? strict : undefined,
+  }
+}
+
+const { readFile } = await import('node:fs/promises')
+const { dirname, resolve } = await import('node:path')
+
+const packageJsonPath = resolve(process.cwd(), 'package.json')
+let config: HotHookConfig = {}
+try {
+  config = readConfig(JSON.parse(await readFile(packageJsonPath, 'utf8')))
+} catch {
+  // No package.json, or unreadable: hot-hook still works, it just has no
+  // boundaries, so every change asks for a restart. That is the old
+  // behaviour, not a failure worth stopping dev over.
+}
+
+// `hot-hook` is an optional peer, declared by the application because it is a
+// dev dependency there and has no business in a production install. Imported by
+// specifier built at runtime so a production bundle never resolves it.
+function isHotHook(value: unknown): value is HotHook {
+  return (
+    typeof value === 'object' && value !== null && typeof Reflect.get(value, 'init') === 'function'
+  )
+}
+
+// `hot-hook` belongs to the APPLICATION: it is a dev dependency there and has
+// no business in a production install of the framework. So it is resolved from
+// the project directory rather than from this file — under pnpm's strict layout
+// a bare `import("hot-hook")` here looks inside @c9up/ream and finds nothing.
+// It is the same reason upstream passes `hot-hook/register` from the app's own
+// cwd instead of re-exporting it from the framework.
+const { createRequire } = await import('node:module')
+const { pathToFileURL } = await import('node:url')
+
+let hot: HotHook | undefined
+try {
+  const resolved = createRequire(packageJsonPath).resolve('hot-hook')
+  const module: unknown = await import(pathToFileURL(resolved).href)
+  const candidate =
+    typeof module === 'object' && module !== null ? Reflect.get(module, 'hot') : undefined
+  if (!isHotHook(candidate)) {
+    throw new Error('hot-hook did not expose a `hot` object with init()')
+  }
+  hot = candidate
+} catch (error) {
+  // Loud, and it names the fix. Silence here would start a perfectly healthy
+  // server that never picks up an edit, which reads as "HMR is broken" rather
+  // than "HMR is not installed".
+  //
+  // It does NOT throw: a dev server that refuses to start is worse than one
+  // without hot reloading, and the CLI only loads this file when it has
+  // already seen hot-hook in the project — so reaching here means it went
+  // missing under a running session.
+  console.error(
+    `[ream] hot module replacement is unavailable: ${error instanceof Error ? error.message : String(error)}\n` +
+      '[ream] Install it with: pnpm add -D hot-hook, then restart `ream dev`.\n' +
+      '[ream] Until then the server runs, but an edit will not be picked up.',
+  )
+}
+
+// Impersonate the IPC channel upstream's dev server provides.
+//
+// hot-hook reports BOTH of its outcomes through `process.send`: a change it
+// swapped in place (`hot-hook:invalidated`) and one it could not
+// (`hot-hook:full-reload`). Under a Node parent that function exists and both
+// arrive; under our Rust parent it is `undefined` and both are dropped —
+// `onFullReloadAsked` alone recovers only half of that, leaving a hot swap
+// invisible to the very process it happened in, and so to the browser.
+//
+// This is not a trick played on hot-hook: it is exactly the contract it
+// expects, provided by us instead of by Node.
+const previousSend = process.send
+process.send = (message: unknown, ...rest: unknown[]): boolean => {
+  const type =
+    typeof message === 'object' && message !== null ? Reflect.get(message, 'type') : undefined
+  if (type === 'hot-hook:invalidated') {
+    hotReloadHappened()
+  }
+  // If a real channel ever exists (embedded under a Node supervisor) it still
+  // gets its message: this observes, it does not intercept.
+  if (typeof previousSend === 'function') {
+    return Reflect.apply(previousSend, process, [message, ...rest]) === true
+  }
+  return true
+}
+
+await hot?.init({
+  ...config,
+  rootDirectory: dirname(packageJsonPath),
+  root: config.root ? resolve(dirname(packageJsonPath), config.root) : undefined,
+  // Exiting on a known code is how the Rust parent learns it must restart —
+  // see `EXIT_RESTART` in the CLI's dev module.
+  onFullReloadAsked: () => process.exit(FULL_RELOAD_EXIT_CODE),
+})

package/src/http/Exception.ts

@@ -156,7 +156,7 @@ export class E_VALIDATION_ERROR extends Exception {
   static override code = 'E_VALIDATION_ERROR'
 
   /**
-   * Per-field failures. Named `messages` because that is what VineJS, rune and
+   * Per-field failures. Named `messages` because that is what rune and
    * AdonisJS's own validation renderers read — a handler copied from an Adonis
    * app reaches for `error.messages`.
    */
@@ -249,7 +249,7 @@ export type HttpError = {
   code: string
   stack?: string
   cause?: unknown
-  /** Per-field failures, on a validation error (VineJS / rune shape). */
+  /** Per-field failures, on a validation error (rune's shape). */
   messages?: unknown
   /** Extra detail an exception chose to carry. */
   errors?: unknown
@@ -487,7 +487,7 @@ export class ExceptionHandler extends Macroable {
 
     // Validation failures have per-field detail and their own renderers. Keyed
     // on the code plus the presence of `messages`, exactly as AdonisJS does, so
-    // rune's and VineJS's errors both land here.
+    // rune's errors land here.
     if (httpError.code === 'E_VALIDATION_ERROR' && httpError.messages !== undefined) {
       await this.renderValidationError(httpError, ctx)
       return
@@ -523,7 +523,7 @@ export class ExceptionHandler extends Macroable {
 }
 
 /**
- * The fields a validation message carries (VineJS / rune `RuneErrorNode`).
+ * The fields a validation message carries (rune's `RuneErrorNode`).
  *
  * Read defensively: the messages come from whichever validator the app wired,
  * and a renderer must not throw while rendering someone else's error.