refactor(gui): host graph from dshClient discovery; webserver self-watches bundles for HMR

The registry scans mounted Loader entries' dshClient declarations and
composes __DSH_BOOT__ {rev, entries} — inject edges and the immediately
mark come from manifests, never hand-copied; malformed fields fail loud
at load. The composing app owns one flat roster plus the --dev switch
(hmr row and bundle watching are dev-graph decisions).

The rebuild signal is the webserver's own observation: in dev mode the
registry stat-polls each scanned bundle (fs.watchFile; polling because
network mounts deliver no inotify), re-hashes on change, and broadcasts
a rebuilt frame on the /plugins/events SSE channel only when the rev
actually changed. Watch membership follows the table across rescans;
dispose drops all watches; a torn read self-heals on the next tick.
The POST /plugins/rebuilt endpoint is gone — builders and the host
share zero protocol. dsh web --dev logs the watched bundle list and
each rebuilt id with its rev transition.

packages/host/webserver/src/index.ts

@@ -13,12 +13,14 @@ import { readFile } from 'node:fs/promises'
 import type { AddressInfo } from 'node:net'
 import { dirname } from 'node:path'
 import { serveStatic } from './static.ts'
-import type { HostWebPluginRegistry } from './web-plugins.ts'
+import { createPluginEventChannel } from './plugin-events.ts'
+import type { HostWebPluginRegistry, WebBootGraph } from './web-plugins.ts'
 
 export { createHostWebPluginRegistry } from './web-plugins.ts'
 export type {
-  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebPluginBootEntry, WebPluginRegistryDeps,
+  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebBootEntry, WebBootGraph, WebPluginRegistryDeps,
 } from './web-plugins.ts'
+export type { PluginEventChannel, PluginEventFrame } from './plugin-events.ts'
 
 /** Options for startWebServer. */
 export interface WebServerOptions {
@@ -34,11 +36,14 @@ export interface WebServerOptions {
   /** Fetch-shaped API carrier; /api/*-prefixed requests are bridged to it. */
   apiHandler: { fetch: typeof fetch }
   /**
-   * Web plugin table. When present, every index.html response carries a
-   * `window.__DSH_BOOT__` manifest script and `/plugins/<id>/client.js` serves
-   * each plugin's client bundle. Absent = both surfaces off (carrier-only use).
+   * Web plugin table. When present, every index.html response carries the
+   * `window.__DSH_BOOT__` entry graph script, `/plugins/<id>/client.js` serves
+   * each fetch entry's client bundle, and `GET /plugins/events` streams graph/
+   * rebuilt frames (SSE) — rebuilt frames ride the registry's own bundle-watch
+   * notifications (`onRebuilt`). Absent = all three surfaces off (carrier-only
+   * use).
    */
-  webPlugins?: Pick<HostWebPluginRegistry, 'snapshot' | 'clientPath'>
+  webPlugins?: Pick<HostWebPluginRegistry, 'graph' | 'clientPath' | 'onRebuilt'>
 }
 
 /** Listening web server handle. */
@@ -70,8 +75,14 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
   const distRoot = dirname(distIndex)
   const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
     const html = await readFile(distIndex, 'utf8')
-    return injectBootManifest(html, webPlugins.snapshot())
+    return injectBootManifest(html, webPlugins.graph())
   }
+  const pluginEvents = webPlugins === undefined ? undefined : createPluginEventChannel()
+  // Rebuilt frames come from the registry's own bundle watch (dev mode); a
+  // prod registry without watching simply never notifies.
+  const unsubscribeRebuilt = webPlugins !== undefined && pluginEvents !== undefined
+    ? webPlugins.onRebuilt((id, rev) => { pluginEvents.broadcast({ type: 'rebuilt', id, rev }) })
+    : undefined
 
   const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
@@ -86,6 +97,10 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
       res.end()
       return
     }
+    if (webPlugins !== undefined && pluginEvents !== undefined && rawPath === '/plugins/events') {
+      pluginEvents.connect(res, webPlugins.graph())
+      return
+    }
     if (webPlugins !== undefined && rawPath.startsWith('/plugins/') && rawPath.endsWith('/client.js')) {
       await servePluginBundle(decodeURIComponent(rawPath), res, webPlugins)
       return
@@ -110,6 +125,7 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 
   let closing: Promise<void> | undefined
   const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
+    unsubscribeRebuilt?.()
     server.close(() => { resolveClose() })
     server.closeAllConnections()
   }))
@@ -125,15 +141,15 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 }
 
 /**
- * Inject the boot manifest into index.html: `window.__DSH_BOOT__` as the first
- * script in <head> (before the shell bundle reads it). `<` is escaped in the
- * JSON so plugin-controlled strings cannot break out of the script element.
+ * Inject the boot entry graph into index.html: `window.__DSH_BOOT__` as the
+ * first script in <head> (before the shell bundle reads it). `<` is escaped in
+ * the JSON so plugin-controlled strings cannot break out of the script element.
  * @param html - the index.html source.
- * @param plugins - the manifest rows from the registry snapshot.
- * @returns the html with the manifest script injected.
+ * @param graph - the composed entry graph from the registry.
+ * @returns the html with the graph script injected.
  */
-export function injectBootManifest(html: string, plugins: readonly unknown[]): string {
-  const json = JSON.stringify({ plugins }).replaceAll('<', '\\u003c')
+export function injectBootManifest(html: string, graph: WebBootGraph): string {
+  const json = JSON.stringify(graph).replaceAll('<', '\\u003c')
   const script = `<script>window.__DSH_BOOT__ = ${json}</script>`
   const head = html.indexOf('<head>')
   if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
@@ -141,7 +157,12 @@ export function injectBootManifest(html: string, plugins: readonly unknown[]): s
   return `${script}${html}`
 }
 
-/** Serve one plugin client bundle from the registry table (unknown id = 404; the id may contain a scope slash). */
+/**
+ * Serve one plugin client bundle from the registry table (unknown id = 404;
+ * the id may contain a scope slash). The `?rev=` query is a cache-busting
+ * parameter only — serving ignores it; `no-cache` makes the browser revalidate
+ * so a stale rev never sticks.
+ */
 async function servePluginBundle(
   pathname: string, res: ServerResponse, webPlugins: Pick<HostWebPluginRegistry, 'clientPath'>,
 ): Promise<void> {
@@ -154,7 +175,7 @@ async function servePluginBundle(
   }
   try {
     const body = await readFile(path)
-    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' })
+    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' })
     res.end(body)
   } catch {
     // Registered but unreadable (bundle not built yet): loud 404 beats a silent SPA-fallback HTML page.

packages/host/webserver/src/invariant.ts

@@ -15,25 +15,27 @@ export const name = 'host-webserver-invariant'
 export const inject = ['invariants']
 
 /**
- * Owned relation: the web plugin registry's boot manifest must stay
- * self-consistent — every snapshot() row must resolve a clientPath under the
- * same id (the /plugins/<id>/client.js URL it advertises would otherwise 404
- * on a browser that just received the manifest). Checked synchronously on
- * every rescan trigger (cordis 'internal/plugin'): snapshot() and
- * clientPath() read the same table object, so the relation is
- * self-consistent at any instant — no need to wait out the registry's own
- * debounced rescan. The registry arrives through the context key the
- * assembly publishes it under.
+ * Owned relation: the web plugin registry's boot entry graph must stay
+ * self-consistent — every row must resolve a clientPath under the same id
+ * (the /plugins/<id>/client.js URL it advertises would otherwise 404 on a
+ * browser that just received the graph). Checked synchronously on every
+ * rescan trigger (cordis 'internal/plugin'): graph() and clientPath() read
+ * the same table object, so the relation is self-consistent at any instant —
+ * no need to wait out the registry's own debounced rescan. The registry
+ * arrives through the context key the assembly publishes it under.
  */
 const install: InvariantInstaller = (ctx, fail) => {
   ctx.on('internal/plugin', () => {
     const registry = ctx.get('webPlugins') as
-      | { snapshot(): { id: string; url: string }[]; clientPath(id: string): string | undefined }
+      | {
+        graph(): { entries: { id: string; url: string }[] }
+        clientPath(id: string): string | undefined
+      }
       | undefined
     if (registry === undefined) return // carrier-only deployments never publish the registry
-    for (const row of registry.snapshot()) {
+    for (const row of registry.graph().entries) {
       if (registry.clientPath(row.id) === undefined) {
-        fail(`web plugin manifest row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
+        fail(`web plugin graph row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
       }
     }
   }, { global: true })

packages/host/webserver/src/plugin-events.ts

@@ -0,0 +1,56 @@
+/**
+ * `/plugins/events` SSE channel: the system-side push surface for the client
+ * entry graph (connect → current graph frame; dev rebuild → rebuilt frame).
+ * Presentation-only wire — frames never enter the session log (distinct from
+ * the /api/* session SSE, which is api-contract territory). Connections are
+ * plain node:http responses held in a set; the server's closeAllConnections
+ * tears them down on shutdown.
+ */
+
+import type { ServerResponse } from 'node:http'
+import type { WebBootGraph } from './web-plugins.ts'
+
+/** One `/plugins/events` frame: the full graph on connect, or one rebuilt bundle notice. */
+export type PluginEventFrame =
+  | { type: 'graph'; graph: WebBootGraph }
+  | { type: 'rebuilt'; id: string; rev: string }
+
+/** Broadcast surface owned by the webserver routing layer. */
+export interface PluginEventChannel {
+  /** Adopt one incoming SSE request: writes the SSE preamble and the current-graph frame, then keeps the response open. */
+  connect(res: ServerResponse, graph: WebBootGraph): void
+  /** Push one frame to every open connection. */
+  broadcast(frame: PluginEventFrame): void
+}
+
+/** Serialize one frame as an SSE data line. */
+function sseData(frame: PluginEventFrame): string {
+  return `data: ${JSON.stringify(frame)}\n\n`
+}
+
+/**
+ * Create the channel (one per running server).
+ * @returns the connect/broadcast surface.
+ */
+export function createPluginEventChannel(): PluginEventChannel {
+  const connections = new Set<ServerResponse>()
+  return {
+    connect(res, graph) {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        'connection': 'keep-alive',
+      })
+      // Comment line on open so clients/proxies see a live channel even when
+      // no rebuild ever happens; EventSource frame parsing skips it naturally.
+      res.write(': connected\n\n')
+      res.write(sseData({ type: 'graph', graph }))
+      connections.add(res)
+      res.on('close', () => { connections.delete(res) })
+    },
+    broadcast(frame) {
+      const line = sseData(frame)
+      for (const res of connections) res.write(line)
+    },
+  }
+}

packages/host/webserver/src/web-plugins.ts

@@ -1,10 +1,17 @@
 /**
- * HostWebPluginRegistry: discovers web-client plugins among the host Loader's
- * loaded entries by their package.json `dshClient` declaration and resolves
- * each one's client bundle path from `exports["./client"]`. The webserver
- * consumes the table to emit `window.__DSH_BOOT__` and to serve
- * `GET /plugins/<id>/client.js`. Discovery is declaration-only: plugin authors
- * write package.json; no serve() call surface exists.
+ * HostWebPluginRegistry: composes the client entry graph served as
+ * `window.__DSH_BOOT__` ({rev, entries}). Every row is discovered among the
+ * host Loader's loaded entries by its package.json `dshClient` declaration
+ * (all client plugin packages arrive by fetch — one uniform bundle shape),
+ * resolving each one's client bundle path from `exports["./client"]` and
+ * hashing the bundle content into a `rev` (cache busting + HMR diff anchor).
+ * `inject` edges and the `immediately` prefetch mark come from the manifest
+ * (dshClient — the package owns its dependency edges and its boot tier); the
+ * composition layer contributes only the roster. The webserver consumes the
+ * table to emit the boot graph and to serve `GET /plugins/<id>/client.js`;
+ * in dev mode the registry additionally stat-polls each scanned bundle file
+ * and re-hashes + notifies `onRebuilt` subscribers on change (the rebuild
+ * signal is the registry's own observation — no builder protocol exists).
  *
  * The vendored loader emits no "entry loaded" event (only `loader/entry-init`,
  * which fires at Entry construction before import/apply), so the registry
@@ -14,33 +21,59 @@
  * fresh within a process lifetime.
  */
 
-import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFileSync, unwatchFile, watchFile } from 'node:fs'
+import type { Stats } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from 'cordis'
 
-/** One `window.__DSH_BOOT__.plugins` row (wire shape of api-contracts v3 §9.2). */
-export interface WebPluginBootEntry {
-  /** Plugin id = package name (may contain a scope slash). */
+/** One composed client entry (`window.__DSH_BOOT__.entries` row). */
+export interface WebBootEntry {
+  /** Entry name == package name. */
   id: string
-  /** Bundle URL served by this webserver (`/plugins/<id>/client.js`). */
+  /** Bundle URL served by this webserver (`/plugins/<id>/client.js?rev=<rev>`). */
   url: string
-  /** Client-half load dependencies (plugin ids), topologically ordered by the client loader. */
-  inject: string[]
-  /** Marks the early-load group: fetched in parallel and applied before all other plugins. */
+  /** Bundle content hash (sha1, shortened). */
+  rev: string
+  /** Package-name dependency edges from the manifest (dshClient.inject), informational (preflight/HMR display). */
+  inject?: string[]
+  /** Boot phase-one prefetch tier: the shell fetches these bundles in parallel before creating entries. */
   immediately?: boolean
 }
 
-/** The web plugin table consumed by the boot injection and the bundle endpoint. */
+/** The composed entry graph: injected into index.html and pushed on /plugins/events connect. */
+export interface WebBootGraph {
+  /** Consistency anchor over all rows: changes whenever any entry row changes. */
+  rev: string
+  /** All composed entries (order carries no semantics; governance ordering is the client Loader's job). */
+  entries: WebBootEntry[]
+}
+
+/** The web plugin table consumed by the boot injection, the bundle endpoint, and the rebuild channel. */
 export interface HostWebPluginRegistry {
-  /** Current manifest rows (stable order: loader entry order). */
-  snapshot(): WebPluginBootEntry[]
+  /** Current composed entry graph (stable object between changes). */
+  graph(): WebBootGraph
   /**
-   * Absolute path of a plugin's client bundle.
-   * @param id - plugin id (package name).
+   * Absolute path of an entry's client bundle.
+   * @param id - entry id (package name).
    * @returns the path, or undefined for an unknown id.
    */
   clientPath(id: string): string | undefined
-  /** Remove the loader subscription. */
+  /**
+   * Re-hash one entry's bundle: updates the row's rev/url and the graph rev.
+   * The dev bundle watch calls this on every observed file change.
+   * @param id - entry id (package name).
+   * @returns the new bundle rev, or undefined for an unknown id.
+   */
+  rebuilt(id: string): string | undefined
+  /**
+   * Subscribe to bundle rebuilds observed by the dev watch (only fires when
+   * the re-hash produced a different rev — an unchanged bundle is silent).
+   * @param listener - receives the entry id and its new bundle rev.
+   * @returns the unsubscriber.
+   */
+  onRebuilt(listener: (id: string, rev: string) => void): () => void
+  /** Remove the loader subscription, all bundle watches, and all rebuild listeners. */
   dispose(): void
 }
 
@@ -72,17 +105,28 @@ export interface WebPluginRegistryDeps {
   resolvePkgJson: (name: string) => string
   /** Sink for rescan failures (the initial scan throws instead — misconfiguration fails loud at load). */
   onError: (err: Error) => void
+  /**
+   * Dev-mode bundle watching: stat-poll every scanned row's client bundle
+   * (fs.watchFile — polling by design: network mounts deliver no inotify
+   * events) and re-hash + notify onRebuilt subscribers on change. Absent =
+   * no watching (prod composition).
+   */
+  watch?: {
+    /** Stat-poll interval in milliseconds; default 500 (the build-side watcher's polling default). */
+    intervalMs?: number
+  }
 }
 
 /** package.json `dshClient` declaration shape (file boundary — validated field by field). */
 interface DshClientDeclaration {
   inject?: string[]
   platform: string
+  /** Boot phase-one prefetch mark; absent means lazy (fetched on demand). */
   immediately?: boolean
 }
 
 interface WebPluginRecord {
-  entry: WebPluginBootEntry
+  entry: WebBootEntry
   clientPath: string
 }
 
@@ -122,15 +166,94 @@ function clientExportOf(name: string, exportsField: unknown): string | undefined
   throw new Error(`web-plugins: ${name} exports["./client"] has an unsupported shape`)
 }
 
+/** sha1 content hash shortened to 12 hex chars (bundle rev / graph rev). */
+function shortHash(input: string | Buffer): string {
+  return createHash('sha1').update(input).digest('hex').slice(0, 12)
+}
+
+/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+function graphRow(id: string, rev: string, inject: string[] | undefined, immediately: boolean): WebBootEntry {
+  return {
+    id,
+    url: `/plugins/${id}/client.js?rev=${rev}`,
+    rev,
+    ...(inject !== undefined ? { inject } : {}),
+    ...(immediately ? { immediately: true } : {}),
+  }
+}
+
+/** Compose the graph value from the current table. */
+function composeGraph(table: Map<string, WebPluginRecord>): WebBootGraph {
+  const entries = [...table.values()].map(record => record.entry)
+  return { rev: shortHash(JSON.stringify(entries)), entries }
+}
+
 /**
  * Build the web plugin registry: scan once synchronously (a malformed
- * declaration throws here — load-time fail loud), then rescan on
- * `internal/plugin`, microtask-debounced (failures go to `deps.onError`).
- * @param deps - loader view, resolution hook, and error sink (see {@link WebPluginRegistryDeps}).
+ * declaration, an unbuilt bundle, or an invalid watch interval throws here —
+ * load-time fail loud), then rescan on `internal/plugin`, microtask-debounced
+ * (failures go to `deps.onError`). With `deps.watch`, every scanned bundle
+ * file is stat-polled and a content change re-hashes the row and notifies
+ * `onRebuilt` subscribers.
+ * @param deps - loader view, resolution hook, error sink, and optional dev watch (see {@link WebPluginRegistryDeps}).
  * @returns the registry handle.
  */
 export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWebPluginRegistry {
+  const watchInterval = deps.watch === undefined ? undefined : deps.watch.intervalMs ?? 500
+  if (watchInterval !== undefined && (!Number.isInteger(watchInterval) || watchInterval <= 0)) {
+    throw new Error(`web-plugins: watch.intervalMs must be a positive integer (got ${String(deps.watch?.intervalMs)})`)
+  }
+
   let table = scan(deps)
+  let graph = composeGraph(table)
+  const rebuildListeners = new Set<(id: string, rev: string) => void>()
+
+  const rebuilt = (id: string): string | undefined => {
+    const record = table.get(id)
+    if (record === undefined) return undefined
+    const rev = shortHash(readFileSync(record.clientPath))
+    record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true)
+    graph = composeGraph(table)
+    return rev
+  }
+
+  // Dev bundle watch: one fs.watchFile stat poll per table row. A torn read
+  // of a half-written bundle self-heals — the ongoing write keeps changing
+  // the stats, so the next poll tick re-hashes the completed file.
+  const watched = new Map<string, { path: string; listener: (curr: Stats, prev: Stats) => void }>()
+  const syncWatches = (): void => {
+    if (watchInterval === undefined) return
+    for (const [id, watch] of watched) {
+      if (table.get(id)?.clientPath === watch.path) continue
+      unwatchFile(watch.path, watch.listener)
+      watched.delete(id)
+    }
+    for (const [id, record] of table) {
+      if (watched.has(id)) continue
+      const listener = (curr: Stats, prev: Stats): void => {
+        // fs.watchFile fires on any stat delta (atime included); only content
+        // signals count. An all-zero curr means the file vanished mid-rebuild
+        // — the completing write fires the next tick, so skipping is safe.
+        if (curr.mtimeMs === prev.mtimeMs && curr.size === prev.size) return
+        if (curr.mtimeMs === 0) return
+        const before = table.get(id)?.entry.rev
+        let rev: string | undefined
+        try {
+          rev = rebuilt(id)
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code
+          if (code === 'ENOENT') return // mid-rename window; the completed write fires the next poll tick
+          deps.onError(error instanceof Error ? error : new Error(String(error)))
+          return
+        }
+        if (rev === undefined || rev === before) return
+        for (const notify of rebuildListeners) notify(id, rev)
+      }
+      watchFile(record.clientPath, { interval: watchInterval, persistent: false }, listener)
+      watched.set(id, { path: record.clientPath, listener })
+    }
+  }
+  syncWatches()
 
   let pending = false
   const unsubscribe = deps.ctx.on('internal/plugin', () => {
@@ -140,8 +263,10 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
       pending = false
       try {
         table = scan(deps)
+        graph = composeGraph(table)
+        syncWatches()
       } catch (error) {
-        // Keep serving the previous table: a mid-flight rescan failure must not
+        // Keep serving the previous graph: a mid-flight rescan failure must not
         // take down the boot manifest for plugins that were fine.
         deps.onError(error instanceof Error ? error : new Error(String(error)))
       }
@@ -149,13 +274,23 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
   })
 
   return {
-    snapshot: () => [...table.values()].map(record => record.entry),
+    graph: () => graph,
     clientPath: id => table.get(id)?.clientPath,
-    dispose: () => { unsubscribe() },
+    rebuilt,
+    onRebuilt: (listener) => {
+      rebuildListeners.add(listener)
+      return () => { rebuildListeners.delete(listener) }
+    },
+    dispose: () => {
+      unsubscribe()
+      for (const { path, listener } of watched.values()) unwatchFile(path, listener)
+      watched.clear()
+      rebuildListeners.clear()
+    },
   }
 }
 
-/** One full table build from the loader's current entries. */
+/** One full table build from the loader's current entries (bundle content is hashed here — an unreadable bundle throws). */
 function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
   const table = new Map<string, WebPluginRecord>()
   for (const entry of deps.loader.entries()) {
@@ -170,15 +305,9 @@ function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
     if (clientRel === undefined) {
       throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
     }
-    table.set(name, {
-      entry: {
-        id: name,
-        url: `/plugins/${name}/client.js`,
-        inject: decl.inject ?? [],
-        ...(decl.immediately === true ? { immediately: true } : {}),
-      },
-      clientPath: join(dirname(pkgPath), clientRel),
-    })
+    const clientPath = join(dirname(pkgPath), clientRel)
+    const rev = shortHash(readFileSync(clientPath))
+    table.set(name, { entry: graphRow(name, rev, decl.inject, decl.immediately === true), clientPath })
   }
   return table
 }