Merge origin/master into fix-webplugins-watch-flake

# Conflicts:
#	.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
#	.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
#	.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
#	packages/host/webserver/tests/web-plugins.spec.ts

packages/README.md

@@ -34,6 +34,8 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
 | [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service, shared LLM policy, and opt-in providers | Product — stable surface |
+| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
+| [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/one-shot CLI/ACP/JSON-RPC bins) the leaves load | Support — example infra |

packages/client/connection/package.json

@@ -43,10 +43,12 @@
     "src"
   ],
   "peerDependencies": {
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/client/connection/src/api-path.ts

@@ -0,0 +1,8 @@
+/**
+ * The /api URL prefix — single source for both halves of the web transport.
+ * The node half registers this prefix on the web server; browser-side path
+ * literals currently live in the apiproxy client layer (out of scope here).
+ */
+
+/** Route prefix owning every api request (`/api` and `/api/<anything>`). */
+export const API_PATH = '/api'

packages/client/connection/src/http-bridge.ts

@@ -0,0 +1,59 @@
+/**
+ * node:http ↔ WHATWG fetch bridge for the /api transport (host side of the
+ * web carrier; the fetch-shaped handler itself is transport-agnostic).
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/**
+ * Bridge one node:http request to the fetch-shaped handler (client close
+ * aborts; SSE bodies stream out chunk by chunk).
+ * @param req - incoming node:http request (fully read before dispatch).
+ * @param res - node:http response the bridge writes and owns to completion.
+ * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
+ */
+export async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
+  const abort = new AbortController()
+  // Client-disconnect detection MUST hang off the response, not the request:
+  // since Node 16, IncomingMessage 'close' fires as soon as the request body is
+  // fully consumed (immediately for a bodyless GET), which would abort every SSE
+  // stream right after open. ServerResponse 'close' fires on connection teardown;
+  // writableEnded distinguishes a normal end() from the client going away.
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  /* v8 ignore next 3 -- `??` arms: node:http always sets url/method on server
+  requests; the fields are only optional on the client-side IncomingMessage type */
+  const request = new Request(new URL(req.url ?? '/', 'http://dsh.internal'), {
+    method: req.method ?? 'GET',
+    headers: Object.fromEntries(Object.entries(req.headers).filter(([, v]) => typeof v === 'string') as [string, string][]),
+    ...chunks.length > 0 ? { body: Buffer.concat(chunks) } : {},
+    signal: abort.signal,
+  })
+  const response = await apiHandler.fetch(request)
+  res.writeHead(response.status, Object.fromEntries(response.headers.entries()))
+  if (response.body === null) {
+    res.end()
+    return
+  }
+  for await (const chunk of response.body) {
+    // Backpressure: a false return means the socket buffer is full — wait for drain
+    // instead of buffering unboundedly (slow/suspended SSE consumers). 'close' also
+    // resolves so a mid-wait disconnect can't park this loop forever; the close
+    // handler above aborts the handler stream, which then ends the iteration.
+    if (!res.write(chunk)) {
+      await new Promise<void>((resolve) => {
+        const done = (): void => {
+          res.off('drain', done)
+          res.off('close', done)
+          resolve()
+        }
+        res.once('drain', done)
+        res.once('close', done)
+      })
+    }
+  }
+  res.end()
+}

packages/client/connection/src/index.ts

@@ -1,10 +1,36 @@
 /**
- * Connection plugin, node half. The package IS a dshClient plugin: the wire
- * consumer layer lives in its client half in full (src/client/ — contract:
- * api-contracts v3 section 3, inventory §3.2); consumers import the /client
- * subpath. The empty apply exists so the plugin appears in the host Loader
- * (lifecycle governance + dshClient discovery).
+ * Connection plugin, node half: the host end of the web transport. Registers
+ * the /api prefix route on the web server and bridges node:http requests to
+ * the transport-agnostic fetch-shaped api handler. The wire consumer layer
+ * lives in the client half (src/client/ — contract: api-contracts v3
+ * section 3); consumers import the /client subpath.
  */
+import type { Context } from 'cordis'
+// Type-only route import; it also carries the httpServer Context merge.
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { API_PATH } from './api-path.ts'
+import { bridge } from './http-bridge.ts'
 
-/** Host plugin body — no host-side behavior for the connection plugin. */
-export function apply(_ctx: unknown): void {}
+export { API_PATH } from './api-path.ts'
+
+/** Cordis plugin name. */
+export const name = 'client-connection'
+
+/** Required services: the route registry and the api gateway. */
+export const inject = ['httpServer', 'apiProxy']
+
+/**
+ * Mount the /api transport: wrap the api gateway into a fetch handler and
+ * serve it under the /api prefix.
+ * @param ctx - host plugin context carrying httpServer and apiProxy.
+ */
+export function apply(ctx: Context): void {
+  const apiHandler = toFetchHandler(ctx.apiProxy)
+  const route: WebRoute = {
+    kind: 'prefix',
+    path: API_PATH,
+    handler: (req, res) => bridge(req, res, apiHandler),
+  }
+  ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
+}

packages/client/connection/src/invariant.ts

@@ -15,10 +15,11 @@ export const name = 'client-connection-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the pure wire layer emits no cordis events and owns no
+ * No runtime invariant: the wire layer emits no cordis events and owns no
  * mutable cross-plugin relation — stream/reconnect sequencing is exercised
- * directly by its behavior specs, and rpcId round-trip discipline is owned by
- * the apiproxy contract layer.
+ * directly by its behavior specs, rpcId round-trip discipline is owned by the
+ * apiproxy contract layer, and the node half's single route registration's
+ * register/dispose symmetry is audited by the webserver package's invariant.
  */
 const install: InvariantInstaller = () => {}
 

packages/client/connection/tests/node-half.spec.ts

@@ -1,10 +1,33 @@
-/** Node half: the empty host apply (Loader governance + dshClient discovery placeholder). */
+/** Node half: registers the /api prefix route bridging to the api gateway. */
+import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
-import { apply } from '../src/index.ts'
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { API_PATH, apply, inject } from '../src/index.ts'
 
-describe('node half', () => {
-  it('apply is a no-op host placeholder', () => {
-    apply(undefined)
-    expect(true).toBe(true) // reaching here without throw is the contract
+describe('connection node half', () => {
+  it('registers the /api prefix route and removes it with the fiber', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    // Structural fake: the plugin only touches register(); the service class
+    // carries private state a literal cannot (and need not) reproduce.
+    const httpServer: Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> = {
+      register(route) {
+        routes.push(route)
+        return () => { routes.splice(routes.indexOf(route), 1) }
+      },
+      tapIndex: () => () => {},
+      port: 0,
+    }
+    ctx.provide('httpServer', httpServer as HttpServerService)
+    ctx.provide('apiProxy', {} as unknown as ApiProxy)
+
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
+
+    await fiber.dispose()
+    expect(routes).toHaveLength(0)
   })
 })

packages/client/connection/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types"
+    "outDir": "lib/types",
+    "types": ["node"]
   },
   "include": [
     "src"
@@ -20,6 +21,9 @@
     {
       "path": "../../host/apiproxy"
     },
+    {
+      "path": "../../host/webserver"
+    },
     {
       "path": "../../ui/user-approval"
     },

packages/client/hmr/README.md

@@ -2,7 +2,7 @@
 
 Hot reload for fetch-arrival client plugins. A static-arrival entry composed only into `--dev` graphs (`dsh web --dev`); production graphs omit the row, so the shell-bundled code stays inert.
 
-The plugin subscribes to the webserver's system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame, serialized through a queue (the bundle handoff slot is single). The sequence per frame — `prefetch` (fetch the new bundle before touching anything), `invalidate`, `registry.delete` (before the fiber: a bare fiber dispose trips the vendored Loader's self-dispose branch, which would mark the entry disabled), drain the old fiber, delete `entry.fiber`, remove owned `<style data-plugin>` tags, `entry.refresh()` re-imports and remounts, `fiber.await()` rethrows startup failures loud. Dependents reload through cordis itself: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber cascades every dependent with zero client-side graph analysis. Rebuild detection lives on the webserver: in dev mode it stat-polls each plugin's built `lib/client.js` (`fs.watchFile`) and broadcasts the `rebuilt` frame when the bundle's rev changes, so any tsdown watch process producing the bundle triggers HMR with no builder→host channel.
+The browser half subscribes to the system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame, serialized through a queue (the bundle handoff slot is single). The sequence per frame — `prefetch` (fetch the new bundle before touching anything), `invalidate`, `registry.delete` (before the fiber: a bare fiber dispose trips the vendored Loader's self-dispose branch, which would mark the entry disabled), drain the old fiber, delete `entry.fiber`, remove owned `<style data-plugin>` tags, `entry.refresh()` re-imports and remounts, `fiber.await()` rethrows startup failures loud. Dependents reload through cordis itself: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber cascades every dependent with zero client-side graph analysis. The node half detects rebuilds with one interval that stat-polls each graph bundle from a synchronous baseline, immediately re-hashes after adding a row, retains missing rows as dirty, and broadcasts only real rev changes; any tsdown watch process producing the bundle therefore triggers HMR with no builder→host channel.
 
 ## Model Experience
 

packages/client/hmr/package.json

@@ -28,15 +28,20 @@
     "immediately": true
   },
   "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "peerDependencies": {
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",
     "@deepseek-ai/dsh-client-modules": "^0.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   },

packages/client/hmr/src/client/index.ts

@@ -64,20 +64,11 @@
  */
 import type { Context } from 'cordis'
 import type { Entry, Loader } from '@cordisjs/plugin-loader'
-import type { WebBootGraph } from '@deepseek-ai/dsh-client-modules'
+import type { PluginsEventFrame } from '../events.ts'
+import { EVENTS_ENDPOINT } from '../events.ts'
 
-/**
- * Frames on the `GET /plugins/events` system SSE channel (owned host-side by
- * dsh-host-webserver's PluginEventFrame). Mirrored here because this is a
- * wire boundary: frames arrive as JSON text and are validated at the parse
- * point, not shared as a same-process typed seam.
- */
-export type PluginsEventFrame =
-  | { type: 'graph'; graph: WebBootGraph }
-  | { type: 'rebuilt'; id: string; rev: string }
-
-/** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
-export const EVENTS_ENDPOINT = '/plugins/events'
+export type { PluginsEventFrame } from '../events.ts'
+export { EVENTS_ENDPOINT } from '../events.ts'
 
 /** Cordis plugin name. */
 export const name = 'client-hmr'

packages/client/hmr/src/events.ts

@@ -0,0 +1,16 @@
+/**
+ * Wire protocol of the `/plugins/events` dev SSE channel — single source for
+ * both halves of this package. Frames still cross a wire boundary: the
+ * browser half validates them at its JSON parse point; sharing the type keeps
+ * the two ends from drifting, not from parsing.
+ */
+
+import type { WebBootGraph } from '@deepseek-ai/dsh-client-modules'
+
+/** One SSE frame: the full graph on connect, or one rebuilt bundle notice. */
+export type PluginsEventFrame =
+  | { type: 'graph'; graph: WebBootGraph }
+  | { type: 'rebuilt'; id: string; rev: string }
+
+/** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
+export const EVENTS_ENDPOINT = '/plugins/events'

packages/client/hmr/src/index.ts

@@ -1,9 +1,189 @@
 /**
- * HMR plugin, node half. The package IS a dshClient plugin (dev-only row in
- * the host graph): the reload driver lives in its client half in full
- * (src/client/); the empty apply exists so the plugin appears in the host
- * Loader (lifecycle governance + dshClient discovery).
+ * HMR plugin, node half: the host end of the dev reload chain. One interval
+ * stat-polls every graph row's client bundle (polling by design: network
+ * mounts deliver no inotify events), reports content changes through
+ * `clientModuleHost.rebuilt(id)`, and serves the `/plugins/events` SSE channel
+ * broadcasting graph/rebuilt frames to the browser half (src/client/).
+ * Dev-only row: prod compositions never mount this plugin.
  */
+import { statSync } from 'node:fs'
+import type { ServerResponse } from 'node:http'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+// Empty type imports carry the clientModuleHost/httpServer Context merges.
+import type {} from '@deepseek-ai/dsh-client-modules'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { PluginsEventFrame } from './events.ts'
+import { EVENTS_ENDPOINT } from './events.ts'
 
-/** Host plugin body — no host-side behavior for the HMR plugin. */
-export function apply(): void {}
+export type { PluginsEventFrame } from './events.ts'
+export { EVENTS_ENDPOINT } from './events.ts'
+
+/** Cordis plugin name. */
+export const name = 'client-hmr'
+
+/** Required services: the web plugin table and the route registry. */
+export const inject = ['clientModuleHost', 'httpServer']
+
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+  /** Bundle stat-poll interval in milliseconds (default 500, the build-side watcher's polling default). */
+  pollIntervalMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  pollIntervalMs: z.number().step(1).min(1).default(500),
+})
+
+/** Serialize one frame as an SSE data line. */
+function sseData(frame: PluginsEventFrame): string {
+  return `data: ${JSON.stringify(frame)}\n\n`
+}
+
+interface WatchedBundle {
+  path: string
+  mtimeMs: number
+  size: number
+  dirty: boolean
+}
+
+/**
+ * Mount the dev chain: bundle watches, rebuilt reporting, and the SSE channel.
+ * @param ctx - host plugin context carrying clientModuleHost and httpServer.
+ * @param config - validated {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  // schemastery's .default() guarantees the field is set after validation.
+  const pollIntervalMs = config.pollIntervalMs as number
+
+  // --- bundle watch: one HMR-owned stat poll ------------------------------
+  const watched = new Map<string, WatchedBundle>()
+
+  const rehash = (id: string, watch: WatchedBundle, current: { mtimeMs: number; size: number }): void => {
+    try {
+      // rebuilt() re-hashes; an unchanged hash stays silent (clientModuleHost
+      // fires onRebuilt only on a real rev change).
+      ctx.clientModuleHost.rebuilt(id)
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        watch.dirty = true
+        return
+      }
+      ctx.logger.warn(error)
+    }
+    watch.mtimeMs = current.mtimeMs
+    watch.size = current.size
+    watch.dirty = false
+  }
+
+  const watchRow = (id: string, path: string): void => {
+    let baseline: { mtimeMs: number; size: number }
+    try {
+      baseline = statSync(path)
+    } catch (error) {
+      watched.set(id, { path, mtimeMs: 0, size: 0, dirty: true })
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') ctx.logger.warn(error)
+      return
+    }
+    const watch = { path, mtimeMs: baseline.mtimeMs, size: baseline.size, dirty: false }
+    watched.set(id, watch)
+    // The module host hashed before publishing the graph. Re-hash immediately
+    // after capturing this baseline so a write in between cannot become an
+    // already-current baseline paired with a stale graph rev.
+    rehash(id, watch, baseline)
+  }
+
+  const pollWatches = (): void => {
+    for (const [id, watch] of watched) {
+      let current: { mtimeMs: number; size: number }
+      try {
+        current = statSync(watch.path)
+      } catch (error) {
+        watch.dirty = true
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') ctx.logger.warn(error)
+        continue
+      }
+      if (!watch.dirty && current.mtimeMs === watch.mtimeMs && current.size === watch.size) continue
+      // Stat-before-hash preserves a detectable older baseline for writes that
+      // land during hashing. Repeated stat changes heal a torn read.
+      rehash(id, watch, current)
+    }
+  }
+
+  // Diff the watch set against the current graph: drop watches for removed
+  // rows (or rows whose bundle path moved), add watches for new rows.
+  const syncWatches = (): void => {
+    const rows = new Map<string, string>()
+    for (const row of ctx.clientModuleHost.graph().entries) {
+      const path = ctx.clientModuleHost.clientPath(row.id)
+      if (path !== undefined) rows.set(row.id, path)
+    }
+    for (const [id, watch] of watched) {
+      if (rows.get(id) === watch.path) continue
+      watched.delete(id)
+    }
+    for (const [id, path] of rows) {
+      if (!watched.has(id)) watchRow(id, path)
+    }
+  }
+
+  ctx.effect(() => {
+    // Initial sync covers rows already in the graph; the subscription covers
+    // rows arriving later (boot-window activations, including this plugin's
+    // own row — no self-exemption, a modules/hmr rebuild rides the same chain).
+    syncWatches()
+    const unsubscribe = ctx.clientModuleHost.onGraphChanged(syncWatches)
+    const timer = setInterval(pollWatches, pollIntervalMs)
+    timer.unref()
+    return () => {
+      unsubscribe()
+      clearInterval(timer)
+      watched.clear()
+    }
+  }, 'client-hmr: bundle watches')
+
+  // --- /plugins/events SSE channel ----------------------------------------
+  const connections = new Set<ServerResponse>()
+
+  const connect = (res: ServerResponse): void => {
+    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: ctx.clientModuleHost.graph() }))
+    connections.add(res)
+    res.on('close', () => { connections.delete(res) })
+  }
+
+  ctx.effect(() => {
+    const disposeRoute = ctx.httpServer.register({
+      kind: 'exact',
+      path: EVENTS_ENDPOINT,
+      handler: (req, res) => {
+        // Named routes match ahead of the carrier's method gate; keep the old
+        // global 405 semantics for non-GET hits on this endpoint.
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          res.writeHead(405)
+          res.end()
+          return
+        }
+        connect(res)
+      },
+    })
+    const unsubscribe = ctx.clientModuleHost.onRebuilt((id, rev) => {
+      const line = sseData({ type: 'rebuilt', id, rev })
+      for (const res of connections) res.write(line)
+    })
+    return () => {
+      unsubscribe()
+      disposeRoute()
+      for (const res of connections) res.destroy()
+      connections.clear()
+    }
+  }, 'client-hmr: /plugins/events channel')
+}

packages/client/hmr/src/invariant.ts

@@ -3,8 +3,7 @@
  * @module @deepseek-ai/dsh-client-hmr/invariant
  */
 
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
+import type { Context, Fiber } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-client-hmr'
@@ -14,14 +13,42 @@ export const name = 'client-hmr-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
+/** Live fs.watchFile pollers (this package is the composition's only stat-poll user). */
+function statWatchers(): number {
+  return process.getActiveResourcesInfo().filter(kind => kind === 'StatWatcher').length
+}
+
 /**
- * No runtime invariant: a dev-only reload driver — it consumes the loader
- * entry tree and module cache but owns no events and no cross-plugin mutable
- * state; reload correctness (dispose → style removal → re-execute ordering)
- * is observable only through the assembled browser runtime, not a host-side
- * event relation.
+ * Owned relation: every bundle stat watcher the node half starts must die
+ * with its fiber — a surviving poller would keep re-hashing bundles for a
+ * torn-down dev chain forever. Checked as a baseline delta: the StatWatcher
+ * count observed at fiber creation must be restored once disposal has drained
+ * the fiber's effects (`internal/plugin` fires at dispose start; the microtask
+ * hop lets the disposer queue its unload before `fiber.await()` joins it).
+ * SSE-connection and listener teardown live inside the same ctx.effect
+ * disposers, so the watcher count is the relation's observable proxy.
  */
-const install: InvariantInstaller = () => {}
+const install: InvariantInstaller = (ctx, fail) => {
+  const baselines = new WeakMap<Fiber, number>()
+  // Async listener by design: emitPluginDisposed awaits-and-logs returned
+  // promises, so a violation surfaces loudly instead of unhandled.
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  ctx.on('internal/plugin', async (fiber) => {
+    if (fiber.name !== 'client-hmr') return
+    if (fiber.uid !== null) {
+      baselines.set(fiber, statWatchers())
+      return
+    }
+    const baseline = baselines.get(fiber)
+    if (baseline === undefined) return
+    await Promise.resolve()
+    await fiber.await()
+    const remaining = statWatchers()
+    if (remaining > baseline) {
+      fail(`client-hmr fiber disposed but ${remaining - baseline} bundle stat watcher(s) survived teardown`)
+    }
+  }, { global: true })
+}
 
 /**
  * Register this package's invariant companion.
@@ -30,4 +57,3 @@ const install: InvariantInstaller = () => {}
  */
 export const apply = (ctx: Context): Promise<() => void> =>
   Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */

packages/client/hmr/tests/node-half.spec.ts

@@ -1,14 +1,204 @@
 /**
- * Node half of the HMR plugin: an empty apply placeholder (the reload driver
- * lives in the client half) whose only contract is mounting and disposing
- * cleanly in the host Loader.
+ * Node half of the HMR plugin: bundle watches follow the graph, stat changes
+ * report through clientModuleHost.rebuilt, and everything dies with the fiber.
  */
-import { describe, expect, it } from 'vitest'
-import { apply } from '@deepseek-ai/dsh-client-hmr'
+import { mkdtempSync, rmSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WebBootGraph, ClientModuleHostService } from '@deepseek-ai/dsh-client-modules'
+import type { WebRoute, HttpServerService } from '@deepseek-ai/dsh-host-webserver'
+import { apply, Config, EVENTS_ENDPOINT, inject } from '../src/index.ts'
+
+const POLL_MS = 20
+
+let dir: string
+
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-')) })
+afterEach(() => { rmSync(dir, { recursive: true, force: true }) })
+
+/**
+ * Controllable clientModuleHost fake over a mutable id → bundle-path table.
+ * Structural (Pick+cast): the plugin only touches the read/notify surface;
+ * the service class carries private scan state a literal need not reproduce.
+ */
+type FakeHost = ClientModuleHostService & { rebuiltCalls: string[]; fireGraphChanged(): void }
+interface FakeHostOptions {
+  beforeGraphRead?: () => void
+  rebuilt?: (id: string) => string | undefined
+}
+
+function fakeClientModuleHost(rows: Map<string, string>, options: FakeHostOptions = {}): FakeHost {
+  const graphListeners = new Set<() => void>()
+  const rebuiltCalls: string[] = []
+  const fake: Pick<FakeHost, 'graph' | 'clientPath' | 'rebuilt' | 'onRebuilt' | 'onGraphChanged' | 'rebuiltCalls' | 'fireGraphChanged'> = {
+    rebuiltCalls,
+    fireGraphChanged: () => { for (const l of graphListeners) l() },
+    graph: (): WebBootGraph => {
+      options.beforeGraphRead?.()
+      return {
+        rev: 'r',
+        entries: [...rows.keys()].map(id => ({ id, url: `/plugins/${id}/client.js?rev=r`, rev: 'r' })),
+      }
+    },
+    clientPath: id => rows.get(id),
+    rebuilt: (id) => {
+      rebuiltCalls.push(id)
+      return options.rebuilt?.(id) ?? 'r2'
+    },
+    onRebuilt: () => () => {},
+    onGraphChanged: (listener) => {
+      graphListeners.add(listener)
+      return () => { graphListeners.delete(listener) }
+    },
+  }
+  return fake as FakeHost
+}
+
+// Structural fake: the plugin only touches register(); the service class
+// carries private state a literal cannot (and need not) reproduce.
+function fakeHttpServer(routes: WebRoute[]): HttpServerService {
+  const fake: Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> = {
+    register(route) {
+      routes.push(route)
+      return () => { routes.splice(routes.indexOf(route), 1) }
+    },
+    tapIndex: () => () => {},
+    port: 0,
+  }
+  return fake as HttpServerService
+}
+
+async function mount(clientModuleHost: FakeHost, httpServer: HttpServerService) {
+  const ctx = new Context()
+  ctx.provide('clientModuleHost', clientModuleHost)
+  ctx.provide('httpServer', httpServer)
+  const fiber = ctx.plugin(
+    { inject: [...inject], Config, apply },
+    { pollIntervalMs: POLL_MS },
+  )
+  await fiber.await()
+  return fiber
+}
 
 describe('hmr node half', () => {
-  it('apply is a no-op host placeholder', () => {
-    apply()
-    expect(true).toBe(true) // reaching here without throw is the contract
+  it('watches graph bundles, reports stat changes, and unwatches on dispose', async () => {
+    const bundle = join(dir, 'a.js')
+    writeFileSync(bundle, 'v1')
+    const clientModuleHost = fakeClientModuleHost(new Map([['pkg-a', bundle]]))
+    const routes: WebRoute[] = []
+    const fiber = await mount(clientModuleHost, fakeHttpServer(routes))
+
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'exact', path: EVENTS_ENDPOINT })
+    expect(clientModuleHost.rebuiltCalls).toEqual(['pkg-a'])
+    clientModuleHost.rebuiltCalls.length = 0
+
+    // Nudge mtime past stat granularity so the poller sees a content signal.
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 2))
+    writeFileSync(bundle, 'v2-longer')
+    await vi.waitFor(() => { expect(clientModuleHost.rebuiltCalls).toContain('pkg-a') }, { timeout: 3_000 })
+
+    await fiber.dispose()
+    expect(routes).toHaveLength(0)
+    // Watcher gone: further file changes report nothing.
+    clientModuleHost.rebuiltCalls.length = 0
+    writeFileSync(bundle, 'v3-even-longer')
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 4))
+    expect(clientModuleHost.rebuiltCalls).toHaveLength(0)
+  })
+
+  it('follows graph changes: rows added after activation get watched', async () => {
+    const early = join(dir, 'early.js')
+    const late = join(dir, 'late.js')
+    writeFileSync(early, 'v1')
+    const rows = new Map([['pkg-early', early]])
+    const clientModuleHost = fakeClientModuleHost(rows)
+    const fiber = await mount(clientModuleHost, fakeHttpServer([]))
+    clientModuleHost.rebuiltCalls.length = 0
+
+    writeFileSync(late, 'v1')
+    rows.set('pkg-late', late)
+    clientModuleHost.fireGraphChanged()
+    expect(clientModuleHost.rebuiltCalls).toEqual(['pkg-late'])
+    clientModuleHost.rebuiltCalls.length = 0
+
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 2))
+    writeFileSync(late, 'v2-longer')
+    await vi.waitFor(() => { expect(clientModuleHost.rebuiltCalls).toContain('pkg-late') }, { timeout: 3_000 })
+
+    rows.delete('pkg-late')
+    clientModuleHost.fireGraphChanged()
+    clientModuleHost.rebuiltCalls.length = 0
+    writeFileSync(late, 'v3-even-longer')
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 3))
+    expect(clientModuleHost.rebuiltCalls).toHaveLength(0)
+    await fiber.dispose()
+  })
+
+  it('rehashes after baseline capture so a construction-window write cannot become the baseline', async () => {
+    const bundle = join(dir, 'construction.js')
+    writeFileSync(bundle, 'v1')
+    let rewrite = true
+    const clientModuleHost = fakeClientModuleHost(new Map([['pkg-a', bundle]]), {
+      beforeGraphRead: () => {
+        if (!rewrite) return
+        rewrite = false
+        // The graph carries the hash from before this write. The old
+        // fs.watchFile registration asynchronously captured the new file as
+        // its first baseline and never requested a re-hash.
+        writeFileSync(bundle, 'v2-written-during-watch-construction')
+      },
+    })
+
+    const fiber = await mount(clientModuleHost, fakeHttpServer([]))
+
+    expect(clientModuleHost.rebuiltCalls).toEqual(['pkg-a'])
+    clientModuleHost.rebuiltCalls.length = 0
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 3))
+    expect(clientModuleHost.rebuiltCalls).toHaveLength(0)
+    await fiber.dispose()
+  })
+
+  it('marks a vanished bundle dirty so identical metadata still re-hashes after it reappears', async () => {
+    const bundle = join(dir, 'replace.js')
+    writeFileSync(bundle, 'seed')
+    const fixedTime = new Date(1_600_000_000_000)
+    utimesSync(bundle, fixedTime, fixedTime)
+    const baseline = statSync(bundle)
+    const clientModuleHost = fakeClientModuleHost(new Map([['pkg-a', bundle]]))
+    const fiber = await mount(clientModuleHost, fakeHttpServer([]))
+    clientModuleHost.rebuiltCalls.length = 0
+
+    unlinkSync(bundle)
+    await new Promise(resolve => setTimeout(resolve, POLL_MS * 2))
+    writeFileSync(bundle, 'x'.repeat(baseline.size))
+    utimesSync(bundle, fixedTime, fixedTime)
+    const restored = statSync(bundle)
+    expect({ mtimeMs: restored.mtimeMs, size: restored.size }).toEqual({
+      mtimeMs: baseline.mtimeMs,
+      size: baseline.size,
+    })
+    await vi.waitFor(() => { expect(clientModuleHost.rebuiltCalls).toEqual(['pkg-a']) }, { timeout: 3_000 })
+    await fiber.dispose()
+  })
+
+  it('retains a dirty baseline when the immediate re-hash races a rename', async () => {
+    const bundle = join(dir, 'rename.js')
+    writeFileSync(bundle, 'v1')
+    let first = true
+    const clientModuleHost = fakeClientModuleHost(new Map([['pkg-a', bundle]]), {
+      rebuilt: () => {
+        if (!first) return 'r2'
+        first = false
+        throw Object.assign(new Error('bundle renamed'), { code: 'ENOENT' })
+      },
+    })
+
+    const fiber = await mount(clientModuleHost, fakeHttpServer([]))
+
+    await vi.waitFor(() => { expect(clientModuleHost.rebuiltCalls).toEqual(['pkg-a', 'pkg-a']) }, { timeout: 3_000 })
+    await fiber.dispose()
   })
 })

packages/client/hmr/tsconfig.json

@@ -8,7 +8,7 @@
       "DOM",
       "DOM.Iterable"
     ],
-    "types": []
+    "types": ["node"]
   },
   "include": [
     "src"
@@ -23,6 +23,12 @@
     {
       "path": "../modules"
     },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../support/invariants"
     }

packages/client/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-modules",
-  "description": "Client module loader: the browser peer of Node's internal ESM loader, consumed by the vendored cordis Loader as its internal seam (resolve/import/loadCache/invalidate over seed table, static registry and fetch bundles)",
+  "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dshClient scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -11,6 +11,10 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
     "./invariant": {
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
@@ -18,14 +22,26 @@
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
+  "dshClient": {
+    "platform": "web",
+    "inject": [],
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
   "license": "BSD-3-Clause",
   "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/client.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"

packages/client/modules/src/client/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Browser half (the standard `./client` export): the module-system class and
+ * wire contract, plus the enrollment plugin face. The module system itself is
+ * built by the shell kernel BEFORE cordis exists (the bootstrap exception,
+ * design §4.7 — the mechanism that loads plugins cannot arrive through
+ * itself); the plugin face only enrolls that pre-existing instance by
+ * providing it as `ctx.modules`. The kernel statically registers this module,
+ * so the graph row for this package never triggers a real fetch — arrival is
+ * a no-op against the already-registered entry.
+ * @module @deepseek-ai/dsh-client-modules/client
+ */
+import type { Context } from 'cordis'
+import type { DshWindow } from './manifest.ts'
+
+export { ClientModuleSystem } from './system.ts'
+export { parseBootManifest } from './manifest.ts'
+export type {
+  BootManifest, BootModuleRow, BootPluginRow, ClientModuleLoader, ClientModuleRecord,
+  ClientModuleSystemOptions, ClientPluginHandoff, DshWindow, WebBootEntry, WebBootGraph,
+} from './manifest.ts'
+
+/**
+ * Enroll the kernel-built module system as `ctx.modules`.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: Context): void {
+  const modules = (globalThis as DshWindow).__DSH_MODULES__
+  // The kernel writes the slot right after constructing the instance, before
+  // any cordis entry exists — a missing slot means the kernel sequencing broke.
+  if (modules === undefined) {
+    throw new Error('client-modules: window.__DSH_MODULES__ missing — the shell kernel must construct the module system before plugin boot')
+  }
+  ctx.reflect.provide('modules', modules)
+}

packages/client/modules/src/client/manifest.ts

@@ -0,0 +1,243 @@
+/**
+ * Client module system: the browser peer of Node's internal ESM loader, built
+ * as a lazy CJS table. The vendored cordis Loader consumes this object
+ * through its `internal` seam (the only call site is `EntryTree.import` →
+ * `internal.import`), which keeps entry governance (fiber lifecycle, inject
+ * waiting, update/refresh) entirely on the vendored side while this package
+ * owns code arrival.
+ *
+ * Lazy CJS model (web2 §0): executing a plugin bundle only REGISTERS its
+ * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
+ * side effect — including CSS injection — lives inside the factory closure
+ * and runs at materialization, not at script execution. Materialization
+ * (factory(require) → export surface) happens on first import/require and is
+ * memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
+ * another registered-but-unmaterialized module materializes it recursively,
+ * so load order needs no external sequencing.
+ *
+ * Resolution branch order (import): seed word → shell instance; memoized
+ * record → surface; static registry (shell-own modules, e.g. app-shell) →
+ * module; registered factory → materialize; graph row → fetch + execute +
+ * materialize; anything else → throw (loud — the runtime mirror of the
+ * build-time bundle purity gate). The synchronous `require` handed to
+ * factories walks the same order minus the fetch branch: fetching is async,
+ * so only already-executed bundles can be required — and cross-plugin value
+ * imports are a build error anyway.
+ *
+ * This file is the browser-safe contract face (zero node imports): the
+ * `__DSH_BOOT__` wire types, the boot-manifest parser, and the seams around
+ * {@link ClientModuleSystem}. The package root is the host-side service that
+ * composes the wire.
+ */
+
+import type {} from 'cordis'
+import type { ClientModuleSystem } from './system.ts'
+
+declare module 'cordis' {
+  interface Context {
+    /** The client module system the web shell builds at boot (contract C5; provided by the `./client` wrapper plugin). */
+    modules: ClientModuleLoader
+  }
+}
+
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's dshClient
+ * declaration and reach fibers through entry creation).
+ */
+export interface WebBootEntry {
+  /** Entry name == package name. */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash (cache-busting consistency anchor). */
+  rev: string
+  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+  inject?: string[]
+  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  immediately?: boolean
+}
+
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+export interface WebBootGraph {
+  /** Consistency anchor over the whole graph (content + bundle hashes). */
+  rev: string
+  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+  entries: WebBootEntry[]
+}
+
+/** The npm-package view of one boot row: what the module table needs to fetch the bundle. */
+export interface BootModuleRow {
+  /** Entry name == package name (module-table key). */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash. */
+  rev: string
+}
+
+/** The cordis-plugin view of one boot row: what entry composition needs (optional wire fields normalized). */
+export interface BootPluginRow {
+  /** Entry name == package name. */
+  id: string
+  /** Package-name dependency edges ([] when the wire omits them). */
+  inject: string[]
+  /** Stage-one prefetch tier (false when the wire omits it). */
+  immediately: boolean
+}
+
+/** The parsed boot manifest: one wire, two consumer views. */
+export interface BootManifest {
+  /** Consistency anchor over the whole graph. */
+  rev: string
+  /** Rows as the module table consumes them. */
+  modules: BootModuleRow[]
+  /** Rows as entry composition consumes them. */
+  plugins: BootPluginRow[]
+}
+
+/**
+ * Parse `window.__DSH_BOOT__` into the two consumer views. Wire boundary:
+ * a missing or malformed graph throws (the shell shows the loud failure —
+ * a page without a valid manifest cannot boot anything).
+ * @param wire - the raw `window.__DSH_BOOT__` value.
+ * @returns the manifest with optional plugin-view fields normalized.
+ */
+export function parseBootManifest(wire: unknown): BootManifest {
+  if (typeof wire !== 'object' || wire === null) {
+    throw new Error('client-modules: window.__DSH_BOOT__ is missing or not an object')
+  }
+  const graph = wire as Record<string, unknown>
+  if (typeof graph.rev !== 'string') {
+    throw new Error('client-modules: boot manifest rev must be a string')
+  }
+  if (!Array.isArray(graph.entries)) {
+    throw new Error('client-modules: boot manifest entries must be an array')
+  }
+  const modules: BootModuleRow[] = []
+  const plugins: BootPluginRow[] = []
+  for (const value of graph.entries as unknown[]) {
+    if (typeof value !== 'object' || value === null) {
+      throw new Error('client-modules: boot manifest entry is not an object')
+    }
+    const row = value as Record<string, unknown>
+    const where = typeof row.id === 'string' ? `"${row.id}"` : JSON.stringify(row)
+    if (typeof row.id !== 'string' || typeof row.url !== 'string' || typeof row.rev !== 'string') {
+      throw new Error(`client-modules: boot manifest entry ${where} must carry string id/url/rev`)
+    }
+    if (row.inject !== undefined && (!Array.isArray(row.inject) || row.inject.some(i => typeof i !== 'string'))) {
+      throw new Error(`client-modules: boot manifest entry ${where} inject must be a string array`)
+    }
+    if (row.immediately !== undefined && typeof row.immediately !== 'boolean') {
+      throw new Error(`client-modules: boot manifest entry ${where} immediately must be a boolean`)
+    }
+    modules.push({ id: row.id, url: row.url, rev: row.rev })
+    plugins.push({
+      id: row.id,
+      inject: row.inject === undefined ? [] : [...row.inject as string[]],
+      immediately: row.immediately === true,
+    })
+  }
+  return { rev: graph.rev, modules, plugins }
+}
+
+/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff, contract C6). */
+export interface ClientPluginHandoff {
+  /** Plugin id (package name) — the registration key; must match the graph row being executed. */
+  id: string
+  /**
+   * Closure factory holding the whole bundle body: receives the synchronous
+   * require bound to the module table and returns the bundle's export
+   * surface. Runs once, at materialization.
+   */
+  factory: (require: (spec: string) => unknown) => Record<string, unknown>
+}
+
+/** Window surface of the web boot protocol: the host-injected graph, the registration sink, and the kernel handoff slot. */
+export interface DshWindow {
+  /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
+  __DSH_BOOT__?: unknown
+  /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor (contract C6). */
+  __ModuleLoader__?: { load(handoff: ClientPluginHandoff): void }
+  /**
+   * Kernel handoff slot: the shell kernel stores the instance here right
+   * after construction (before cordis exists) so the `./client` wrapper
+   * plugin can provide it as `ctx.modules`. Missing slot at wrapper apply
+   * time = kernel sequencing bug, thrown loud.
+   */
+  __DSH_MODULES__?: ClientModuleSystem
+}
+
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph seam, flat today). */
+export interface ClientModuleRecord {
+  /** Module id (entry name / package name). */
+  id: string
+  /** The materialized export surface (factory `module.exports`, or the shell module for static registrations). */
+  surface: unknown
+  /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
+  styles: string[]
+  /** Observed `require()` edges (module-graph seam; only table words can appear today). */
+  edges: Set<string>
+}
+
+/**
+ * The internal-seam subset the vendored Loader and the client HMR plugin
+ * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
+ * as `ctx.modules` (contract C5).
+ */
+export interface ClientModuleLoader {
+  /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
+  version: 'client'
+  /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
+  loadCache: Map<string, ClientModuleRecord>
+  /**
+   * Internal seam consumed by the vendored Loader's `tree.import`. Resolves
+   * `specifier` through the branch order documented on the module, fetching
+   * and executing a bundle when needed.
+   * @param specifier - module specifier (entry name or table word).
+   * @param parentURL - importer URL (unused — the client module graph is flat).
+   * @param attrs - import attributes (unused; interface parity with Node's seam).
+   * @returns the module's export surface.
+   */
+  import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
+  /**
+   * Register a shell-own module (app-shell — code that ships inside the shell
+   * bundle and never arrives as a plugin bundle).
+   * @param id - entry name (shell-owned pseudo id).
+   * @param module - the statically imported module namespace.
+   */
+  registerStatic(id: string, module: unknown): void
+  /**
+   * Stage-one arrival: fetch the entry's bundle and execute it, registering
+   * its factory (no materialization — module side effects wait for import).
+   * No-op for static-registered ids and ids whose factory is already
+   * registered; concurrent calls share one in-flight task. To force a fresh
+   * fetch (HMR), {@link invalidate} first.
+   * @param id - graph entry name.
+   */
+  prefetch(id: string): Promise<void>
+  /**
+   * Full reset of one module: drop its registered factory, its materialized
+   * record, and any consumed bundle text, so the next prefetch/import
+   * refetches and re-executes (the HMR invalidation hook).
+   * @param id - entry name to invalidate.
+   */
+  invalidate(id: string): void
+}
+
+/** Options for {@link ClientModuleSystem} (assembled by the web shell kernel at boot). */
+export interface ClientModuleSystemOptions {
+  /** Boot rows in the module-table view (from {@link parseBootManifest}). */
+  modules: BootModuleRow[]
+  /** Module-table seed: platform-singleton specifier → shell instance. */
+  staticModules: Record<string, unknown>
+  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
+  fetchBundle?: (url: string) => Promise<string>
+  /**
+   * Bundle execution seam (synchronously performs the load() registration).
+   * Defaults to a <script> element carrying the code.
+   */
+  executeBundle?: (code: string, url: string) => void
+}

packages/client/modules/src/client/system.ts

@@ -1,13 +1,13 @@
 /**
- * ClientModuleLoaderImpl — the implementation behind the {@link ClientModuleLoader}
+ * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
  * seam. The conceptual contract (lazy CJS model, resolution branch order) is
- * documented on the package module and the public interfaces in `./index.ts`;
- * this file owns the state tables and the fetch/execute/materialize machinery.
+ * documented on the public interfaces in `./manifest.ts`; this file owns the
+ * state tables and the fetch/execute/materialize machinery.
  */
 import type {
-  ClientModuleLoader, ClientModuleLoaderOptions, ClientModuleRecord,
-  ClientPluginHandoff, DshWindow, WebBootEntry,
-} from './index.ts'
+  BootModuleRow, ClientModuleLoader, ClientModuleRecord,
+  ClientModuleSystemOptions, ClientPluginHandoff, DshWindow,
+} from './manifest.ts'
 
 /** A registered-but-unmaterialized bundle: the factory plus its source URL (diagnostics). */
 interface RegisteredFactory {
@@ -35,13 +35,6 @@ const defaultExecuteBundle = (code: string, url: string): void => {
   el.remove()
 }
 
-const urlOf = (row: WebBootEntry): string => {
-  // url is conditional on the wire (shell-own pseudo rows omit it); those
-  // ids resolve through the static registry and never reach a fetch.
-  if (row.url === undefined) throw new Error(`client-modules: entry "${row.id}" has no bundle url and no static registration`)
-  return row.url
-}
-
 /**
  * A plugin bundle IS its package's client half: `<id>/client` (the exports
  * subpath external bundles emit) and the bare graph id name the same
@@ -70,10 +63,10 @@ const claimStyles = (id: string): string[] => {
 /**
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
- * seam contract docs). Construction indexes the boot graph and installs the
+ * seam contract docs). Construction indexes the boot rows and installs the
  * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
  */
-export class ClientModuleLoaderImpl implements ClientModuleLoader {
+export class ClientModuleSystem implements ClientModuleLoader {
   readonly version = 'client'
   readonly loadCache = new Map<string, ClientModuleRecord>()
 
@@ -84,7 +77,7 @@ export class ClientModuleLoaderImpl implements ClientModuleLoader {
   private readonly pendingArrival = new Map<string, Promise<void>>()
   /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
   private readonly materializing = new Set<string>()
-  private readonly graphRows = new Map<string, WebBootEntry>()
+  private readonly graphRows = new Map<string, BootModuleRow>()
   // Execution URL of the bundle currently being executed (bound into the
   // factory registration so diagnostics can name the source).
   private executingUrl = ''
@@ -97,17 +90,17 @@ export class ClientModuleLoaderImpl implements ClientModuleLoader {
   private readonly executeBundle: (code: string, url: string) => void
 
   /**
-   * Build the module system over the host graph.
-   * @param options - entry graph, module-table staticModules, fetch/execute seams.
+   * Build the module system over the parsed boot rows.
+   * @param options - module rows, module-table staticModules, fetch/execute seams.
    */
-  constructor(options: ClientModuleLoaderOptions) {
+  constructor(options: ClientModuleSystemOptions) {
     this.seed = new Map(Object.entries(options.staticModules))
     this.fetchBundle = options.fetchBundle ?? defaultFetchBundle
     this.executeBundle = options.executeBundle ?? defaultExecuteBundle
 
-    for (const entry of options.graph.entries) {
-      if (this.graphRows.has(entry.id)) throw new Error(`client-modules: duplicate graph entry "${entry.id}"`)
-      this.graphRows.set(entry.id, entry)
+    for (const row of options.modules) {
+      if (this.graphRows.has(row.id)) throw new Error(`client-modules: duplicate graph entry "${row.id}"`)
+      this.graphRows.set(row.id, row)
     }
 
     const win = globalThis as DshWindow
@@ -129,13 +122,12 @@ export class ClientModuleLoaderImpl implements ClientModuleLoader {
   }
 
   /** Fetch + execute one graph row so its factory is registered (idempotent per in-flight arrival). */
-  private arrive(row: WebBootEntry): Promise<void> {
-    const { id } = row
+  private arrive(row: BootModuleRow): Promise<void> {
+    const { id, url } = row
     const pending = this.pendingArrival.get(id)
     if (pending !== undefined) return pending
     if (this.factories.has(id)) return Promise.resolve()
     const task = (async (): Promise<void> => {
-      const url = urlOf(row)
       const code = await this.fetchBundle(url)
       this.executingUrl = url
       this.executingId = id

packages/client/modules/src/index.ts

@@ -1,175 +1,393 @@
 /**
- * Client module system: the browser peer of Node's internal ESM loader, built
- * as a lazy CJS table. The vendored cordis Loader consumes this object
- * through its `internal` seam (the only call site is `EntryTree.import` →
- * `internal.import`), which keeps entry governance (fiber lifecycle, inject
- * waiting, update/refresh) entirely on the vendored side while this package
- * owns code arrival.
+ * Node half of the client module system (dshClient dual-face package): scans
+ * the host Loader's entries for `dshClient` packages, composes the
+ * `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
+ * in `./client/manifest.ts`), serves `/plugins/<id>/client.js`, taps the
+ * index render to inject the boot manifest, and provides the
+ * `clientModuleHost` service (the HMR node half's registration/notification
+ * face).
  *
- * Lazy CJS model (web2 §0): executing a plugin bundle only REGISTERS its
- * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
- * side effect — including CSS injection — lives inside the factory closure
- * and runs at materialization, not at script execution. Materialization
- * (factory(require) → export surface) happens on first import/require and is
- * memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
- * another registered-but-unmaterialized module materializes it recursively,
- * so load order needs no external sequencing.
- *
- * Resolution branch order (import): seed word → shell instance; memoized
- * record → surface; static registry (shell-own modules, e.g. app-shell) →
- * module; registered factory → materialize; graph row → fetch + execute +
- * materialize; anything else → throw (loud — the runtime mirror of the
- * build-time bundle purity gate). The synchronous `require` handed to
- * factories walks the same order minus the fetch branch: fetching is async,
- * so only already-executed bundles can be required — and cross-plugin value
- * imports are a build error anyway.
+ * Scanning is incremental per package — there is no full-rescan code path.
+ * Every cordis `internal/plugin` emission (fiber construction/disposal) marks
+ * the fiber's entry name dirty; a microtask flush reconciles each dirty name
+ * against the live loader entries. The activation pass seeds the same dirty
+ * set with all current entries and flushes synchronously, so first scan and
+ * steady state share one implementation. Package metadata (including the
+ * negative "not a client package" verdict) is cached per name and never
+ * expires — plugin-set changes take effect on restart per the config-source
+ * ruling; bundle content changes reach the graph only through
+ * {@link ClientModuleHostService.rebuilt}.
  * @module @deepseek-ai/dsh-client-modules
  */
 
-import { ClientModuleLoaderImpl } from './loader.ts'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type {} from '@cordisjs/plugin-loader'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { WebBootEntry, WebBootGraph } from './client/manifest.ts'
 
-export { ClientModuleLoaderImpl }
+export type {
+  BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootGraph,
+} from './client/manifest.ts'
 
 declare module 'cordis' {
   interface Context {
-    /** The client module system the web shell provides at boot (contract C5). */
-    modules: ClientModuleLoader
+    /** The web plugin table (provided by the client-modules node half). */
+    clientModuleHost: ClientModuleHostService
+  }
+}
+
+/** 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
+}
+
+/** Resolved package metadata for one dshClient package (cached per name, never expires). */
+interface PkgMeta {
+  clientPath: string
+  inject?: string[]
+  immediately: boolean
+}
+
+/** One composed table row: the wire entry plus its bundle path. */
+interface WebPluginRecord {
+  entry: WebBootEntry
+  clientPath: string
+}
+
+/** Narrow an unknown parsed JSON value to the dshClient declaration, throwing on malformed fields. */
+function parseDshClient(pkgName: string, value: unknown): DshClientDeclaration | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`client-modules: ${pkgName} has a non-object dshClient declaration`)
+  }
+  const decl = value as Record<string, unknown>
+  if (typeof decl.platform !== 'string') {
+    throw new Error(`client-modules: ${pkgName} dshClient.platform must be a string`)
+  }
+  if (decl.inject !== undefined && (!Array.isArray(decl.inject) || decl.inject.some(i => typeof i !== 'string'))) {
+    throw new Error(`client-modules: ${pkgName} dshClient.inject must be a string array`)
+  }
+  if (decl.immediately !== undefined && typeof decl.immediately !== 'boolean') {
+    throw new Error(`client-modules: ${pkgName} dshClient.immediately must be a boolean`)
+  }
+  return {
+    platform: decl.platform,
+    ...(decl.inject !== undefined ? { inject: decl.inject as string[] } : {}),
+    ...(decl.immediately !== undefined ? { immediately: decl.immediately } : {}),
+  }
+}
+
+/** Resolve `exports["./client"]` to a relative path, accepting the string and one-level conditional forms. */
+function clientExportOf(pkgName: string, exportsField: unknown): string | undefined {
+  if (typeof exportsField !== 'object' || exportsField === null) return undefined
+  const client = (exportsField as Record<string, unknown>)['./client']
+  if (client === undefined) return undefined
+  if (typeof client === 'string') return client
+  if (typeof client === 'object' && client !== null) {
+    const fallback = (client as Record<string, unknown>).default
+    if (typeof fallback === 'string') return fallback
+  }
+  throw new Error(`client-modules: ${pkgName} 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, injectEdges: string[] | undefined, immediately: boolean): WebBootEntry {
+  return {
+    id,
+    url: `/plugins/${id}/client.js?rev=${rev}`,
+    rev,
+    ...(injectEdges !== undefined ? { inject: injectEdges } : {}),
+    ...(immediately ? { immediately: true } : {}),
   }
 }
 
 /**
- * One composed client entry pushed by the host (web2 §0 graph row).
- * `immediately` marks stage-one prefetch; `inject` is informational graph
- * metadata (the authoritative edges live in each package's dshClient
- * declaration and reach fibers through entry creation).
- *
- * Wire contract, held on both sides: the producing peer lives in
- * `@deepseek-ai/dsh-host-webserver` (host packages keep zero workspace
- * dependencies, so neither side imports the other's shape — drift between
- * the two declarations is a bug against the web2 contract).
+ * 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 graph - the composed entry graph.
+ * @returns the html with the graph script injected.
  */
-export interface WebBootEntry {
-  /** Entry name == package name (or a shell-owned pseudo id, e.g. app-shell). */
-  id: string
-  /**
-   * Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. Absent only on
-   * shell-owned pseudo rows (app-shell) whose module is statically registered
-   * — a row that is neither fetchable nor static-registered fails loud.
-   */
-  url?: string
-  /** Bundle content hash (cache-busting consistency anchor); absent with url. */
-  rev?: string
-  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
-  inject?: string[]
-  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
-  immediately?: boolean
-}
-
-/** The composed client entry graph the host injects as `window.__DSH_BOOT__` (dual-held wire contract — see {@link WebBootEntry}). */
-export interface WebBootGraph {
-  /** Consistency anchor over the whole graph (content + bundle hashes). */
-  rev: string
-  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
-  entries: WebBootEntry[]
-}
-
-/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff, contract C6). */
-export interface ClientPluginHandoff {
-  /** Plugin id (package name) — the registration key; must match the graph row being executed. */
-  id: string
-  /**
-   * Closure factory holding the whole bundle body: receives the synchronous
-   * require bound to the module table and returns the bundle's export
-   * surface. Runs once, at materialization.
-   */
-  factory: (require: (spec: string) => unknown) => Record<string, unknown>
-}
-
-/** Window surface this loader owns (bundle side of the handoff protocol) plus the host-injected graph. */
-export interface DshWindow {
-  /** Host-composed entry graph, injected before the shell bundle runs. */
-  __DSH_BOOT__?: WebBootGraph
-  /** Bundle registration sink; installed once per page by {@link createClientModuleLoader} (contract C6). */
-  __ModuleLoader__?: { load(handoff: ClientPluginHandoff): void }
-}
-
-/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph seam, flat today). */
-export interface ClientModuleRecord {
-  /** Module id (entry name / package name). */
-  id: string
-  /** The materialized export surface (factory `module.exports`, or the shell module for static registrations). */
-  surface: unknown
-  /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
-  styles: string[]
-  /** Observed `require()` edges (module-graph seam; only table words can appear today). */
-  edges: Set<string>
+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)}`
+  // Headless fixture pages may lack <head>; prepending keeps the read-before-shell ordering.
+  return `${script}${html}`
 }
 
 /**
- * The internal-seam subset the vendored Loader and the client HMR plugin
- * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
- * as `ctx.modules` (contract C5).
+ * The web plugin table service: incremental dshClient scan + wire composition
+ * + bundle route + index tap. Construction runs the activation scan
+ * synchronously — a malformed declaration or missing bundle among the
+ * already-loaded entries aggregates into one loud throw (FAILED fiber; the
+ * boot sweep reports it).
  */
-export interface ClientModuleLoader {
-  /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
-  version: 'client'
-  /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
-  loadCache: Map<string, ClientModuleRecord>
+export class ClientModuleHostService extends Service {
+  static inject = ['httpServer', 'loader']
+
+  private readonly table = new Map<string, WebPluginRecord>()
+  // Negative verdicts (unresolvable specifier — builtins like cordis:include,
+  // subpath rows — or a package without a web dshClient declaration) are
+  // cached as null and never expire: plugin-set changes take effect on restart.
+  private readonly pkgMeta = new Map<string, PkgMeta | null>()
+  private readonly rebuildListeners = new Set<(id: string, rev: string) => void>()
+  private readonly graphListeners = new Set<() => void>()
+  private readonly dirty = new Set<string>()
+  private readonly resolvePkgJson: (spec: string) => string
+  private flushQueued = false
+  private composed: WebBootGraph
+
   /**
-   * Internal seam consumed by the vendored Loader's `tree.import`. Resolves
-   * `specifier` through the branch order documented on the module, fetching
-   * and executing a bundle when needed.
-   * @param specifier - module specifier (entry name or table word).
-   * @param parentURL - importer URL (unused — the client module graph is flat).
-   * @param attrs - import attributes (unused; interface parity with Node's seam).
-   * @returns the module's export surface.
+   * Build the service: subscribe, seed, and run the activation flush.
+   * @param ctx - plugin context carrying httpServer and loader.
    */
-  import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
+  constructor(ctx: Context) {
+    super(ctx, 'clientModuleHost')
+    // Resolution anchor: the config tree's baseUrl (the cordis.yml directory,
+    // whose package declares every composed plugin as a dependency). The
+    // modules package's own URL would miss sibling packages under pnpm's
+    // isolated node_modules.
+    if (ctx.baseUrl === undefined) {
+      throw new Error('client-modules: ctx.baseUrl is unset — the node half needs the config-tree anchor to resolve plugin packages')
+    }
+    const require = createRequire(ctx.baseUrl)
+    this.resolvePkgJson = spec => require.resolve(`${spec}/package.json`)
+
+    // Subscribe before seeding so a fiber arriving mid-activation lands in the
+    // same dirty set (Set idempotence makes the overlap harmless). An entry-less
+    // fiber is a child plugin or a manual mount — never a loader row; O(1) drop.
+    ctx.on('internal/plugin', (fiber) => {
+      const entryName = fiber.entry?.options.name
+      if (entryName === undefined) return
+      this.dirty.add(entryName)
+      if (this.flushQueued) return
+      this.flushQueued = true
+      queueMicrotask(() => {
+        this.flushQueued = false
+        this.flush((err) => { ctx.logger.warn(err) })
+      })
+    })
+
+    // Activation pass: the initial scan IS the incremental path over the
+    // current entries, flushed synchronously (nothing async between subscribe,
+    // seed, and flush).
+    for (const entry of ctx.loader.entries()) this.dirty.add(entry.options.name)
+    this.composed = this.compose()
+    const failures: Error[] = []
+    this.flush(err => failures.push(err))
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        `client-modules: ${String(failures.length)} client package(s) failed to compose:\n${failures.map(e => `  - ${e.message}`).join('\n')}`,
+      )
+    }
+
+    ctx.effect(
+      () => ctx.httpServer.register({ kind: 'prefix', path: '/plugins', handler: this.serveBundle }),
+      'client-modules: bundle route',
+    )
+    ctx.effect(
+      () => ctx.httpServer.tapIndex(html => injectBootManifest(html, this.composed)),
+      'client-modules: boot manifest injection',
+    )
+  }
+
   /**
-   * Register a shell-own module (app-shell — code that ships inside the shell
-   * bundle and never arrives as a plugin bundle).
-   * @param id - entry name (shell-owned pseudo id).
-   * @param module - the statically imported module namespace.
+   * Current composed entry graph (stable object between changes).
+   * @returns the graph served as `window.__DSH_BOOT__`.
    */
-  registerStatic(id: string, module: unknown): void
+  graph(): WebBootGraph {
+    return this.composed
+  }
+
   /**
-   * Stage-one arrival: fetch the entry's bundle and execute it, registering
-   * its factory (no materialization — module side effects wait for import).
-   * No-op for static-registered ids and ids whose factory is already
-   * registered; concurrent calls share one in-flight task. To force a fresh
-   * fetch (HMR), {@link invalidate} first.
-   * @param id - graph entry name.
+   * Absolute path of an entry's client bundle.
+   * @param id - entry id (package name).
+   * @returns the path, or undefined for an unknown id.
    */
-  prefetch(id: string): Promise<void>
+  clientPath(id: string): string | undefined {
+    return this.table.get(id)?.clientPath
+  }
+
   /**
-   * Full reset of one module: drop its registered factory, its materialized
-   * record, and any consumed bundle text, so the next prefetch/import
-   * refetches and re-executes (the HMR invalidation hook).
-   * @param id - entry name to invalidate.
+   * Re-hash one bundle (the HMR watch's registration hook — the only entry
+   * point through which bundle content changes reach the graph).
+   * @param id - entry id (package name).
+   * @returns the new rev, or undefined for an unknown id.
    */
-  invalidate(id: string): void
+  rebuilt(id: string): string | undefined {
+    const record = this.table.get(id)
+    if (record === undefined) return undefined
+    const rev = shortHash(readFileSync(record.clientPath))
+    if (rev === record.entry.rev) return rev
+    record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true)
+    this.composed = this.compose()
+    for (const notify of this.rebuildListeners) {
+      // Containment: rebuilt() runs inside the HMR watch callback — a
+      // throwing subscriber must not kill the poll or skip later subscribers.
+      try {
+        notify(id, rev)
+      } catch (error) {
+        this.ctx.logger.error(error)
+      }
+    }
+    this.notifyGraphChanged()
+    return rev
+  }
+
+  /**
+   * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+   * @param listener - receives the entry id and its new bundle rev.
+   * @returns the unsubscriber.
+   */
+  onRebuilt(listener: (id: string, rev: string) => void): () => void {
+    this.rebuildListeners.add(listener)
+    return () => { this.rebuildListeners.delete(listener) }
+  }
+
+  /**
+   * Fires after any flush that recomposed the graph (row added/removed, or a
+   * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+   * @param listener - notified with no payload.
+   * @returns the unsubscriber.
+   */
+  onGraphChanged(listener: () => void): () => void {
+    this.graphListeners.add(listener)
+    return () => { this.graphListeners.delete(listener) }
+  }
+
+  private compose(): WebBootGraph {
+    const entries = [...this.table.values()].map(record => record.entry)
+    return { rev: shortHash(JSON.stringify(entries)), entries }
+  }
+
+  private notifyGraphChanged(): void {
+    for (const listener of this.graphListeners) {
+      // A throwing subscriber must not skip later subscribers (or escape into
+      // whatever triggered the flush — possibly an fs.watchFile callback).
+      try {
+        listener()
+      } catch (error) {
+        this.ctx.logger.error(error)
+      }
+    }
+  }
+
+  private resolveMeta(pkgName: string): PkgMeta | null {
+    const cached = this.pkgMeta.get(pkgName)
+    if (cached !== undefined) return cached
+    let pkgPath: string
+    try {
+      pkgPath = this.resolvePkgJson(pkgName)
+    } catch {
+      // Not a resolvable package root: loader builtins (cordis:include) and
+      // subpath entries (…/gateway) land here — permanently not a client row.
+      this.pkgMeta.set(pkgName, null)
+      return null
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
+    const decl = parseDshClient(pkgName, pkg.dshClient)
+    if (decl === undefined || decl.platform !== 'web') {
+      this.pkgMeta.set(pkgName, null)
+      return null
+    }
+    const clientRel = clientExportOf(pkgName, pkg.exports)
+    if (clientRel === undefined) {
+      throw new Error(`client-modules: ${pkgName} declares dshClient but exports no "./client" bundle`)
+    }
+    const meta: PkgMeta = {
+      clientPath: join(dirname(pkgPath), clientRel),
+      ...(decl.inject !== undefined ? { inject: decl.inject } : {}),
+      immediately: decl.immediately === true,
+    }
+    this.pkgMeta.set(pkgName, meta)
+    return meta
+  }
+
+  /** Reconcile one entry name against the live loader entries. @returns whether the table changed. */
+  private processOne(entryName: string): boolean {
+    let qualifies = false
+    for (const entry of this.ctx.loader.entries()) {
+      if (entry.options.name === entryName && entry.fiber !== undefined && !entry.disabled) {
+        qualifies = true
+        break
+      }
+    }
+    if (!qualifies) return this.table.delete(entryName)
+    if (this.table.has(entryName)) return false
+    const meta = this.resolveMeta(entryName)
+    if (meta === null) return false
+    // The rev rides the row from here on: a fiber restart reuses the row (and
+    // its rev) untouched; only rebuilt() re-reads the bundle.
+    const rev = shortHash(readFileSync(meta.clientPath))
+    this.table.set(entryName, { entry: graphRow(entryName, rev, meta.inject, meta.immediately), clientPath: meta.clientPath })
+    return true
+  }
+
+  private flush(onError: (err: Error) => void): void {
+    let changed = false
+    for (const entryName of [...this.dirty]) {
+      this.dirty.delete(entryName)
+      try {
+        if (this.processOne(entryName)) changed = true
+      } catch (error) {
+        // Steady state: one broken package must not poison the others; the
+        // activation pass aggregates these into a loud throw instead.
+        onError(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+    if (changed) {
+      this.composed = this.compose()
+      this.notifyGraphChanged()
+    }
+  }
+
+  private readonly serveBundle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
+    const pathname = decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname)
+    // The id may contain a scope slash. Anything else under /plugins (including
+    // /plugins/events when the HMR row is absent) is an unknown resource.
+    const path = pathname.startsWith('/plugins/') && pathname.endsWith('/client.js')
+      ? this.clientPath(pathname.slice('/plugins/'.length, -'/client.js'.length))
+      : undefined
+    if (path === undefined) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    try {
+      const body = await readFile(path)
+      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.
+      res.writeHead(404)
+      res.end()
+    }
+  }
 }
 
-/** Options for {@link createClientModuleLoader} (assembled by the web shell at boot). */
-export interface ClientModuleLoaderOptions {
-  /** Host-composed entry graph. */
-  graph: WebBootGraph
-  /** Module-table seed: platform-singleton specifier → shell instance. */
-  staticModules: Record<string, unknown>
-  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
-  fetchBundle?: (url: string) => Promise<string>
-  /**
-   * Bundle execution seam (synchronously performs the load() registration).
-   * Defaults to a <script> element carrying the code.
-   */
-  executeBundle?: (code: string, url: string) => void
-}
-
-/**
- * Build the client module system.
- * @param options - entry graph, module-table staticModules, fetch/execute seams.
- * @returns the loader the shell mounts as `ctx.loader.internal` and provides as `ctx.modules`.
- */
-export function createClientModuleLoader(options: ClientModuleLoaderOptions): ClientModuleLoader {
-  return new ClientModuleLoaderImpl(options)
-}
+export default ClientModuleHostService

packages/client/modules/src/invariant.ts

@@ -15,14 +15,25 @@ export const name = 'client-modules-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the module loader is pre-plugin kernel machinery —
- * it emits no cordis events (the vendored Loader owns entry lifecycle events)
- * and its mutable state (loadCache, handoff slot) lives below the plugin
- * layer where invariant observers cannot mount before it runs; resolve branch
- * order and handoff discipline are asserted by the web boot specs against the
- * real execution path.
+ * Owned relation: the node half'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 on every scan trigger (cordis
+ * 'internal/plugin'): graph() and clientPath() read the same table object,
+ * so the relation holds at any instant — no need to wait out the node half's
+ * own microtask-debounced flush.
  */
-const install: InvariantInstaller = () => {}
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/plugin', () => {
+    const host = ctx.get('clientModuleHost')
+    if (host === undefined) return // browser side / host without the node half: nothing to audit
+    for (const row of host.graph().entries) {
+      if (host.clientPath(row.id) === undefined) {
+        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 })
+}
 
 /**
  * Register this package's invariant companion.

packages/client/modules/tests/loader.spec.ts

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * ClientModuleLoaderImpl behavior: lazy CJS arrival (bundle execution only
+ * ClientModuleSystem behavior: lazy CJS arrival (bundle execution only
  * registers the factory), materialization on first import/require with
  * memoization and recursive self-sequencing, the resolution branch order,
  * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
@@ -9,9 +9,9 @@
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
-  ClientModuleLoaderImpl, createClientModuleLoader,
-  type ClientModuleLoader, type ClientPluginHandoff, type DshWindow, type WebBootEntry,
-} from '../src/index.ts'
+  ClientModuleSystem,
+  type BootModuleRow, type ClientModuleLoader, type ClientPluginHandoff, type DshWindow,
+} from '../src/client/index.ts'
 
 const win = globalThis as DshWindow
 
@@ -24,7 +24,7 @@ afterEach(() => {
   for (const el of document.querySelectorAll('style, script')) el.remove()
 })
 
-const row = (id: string): WebBootEntry => ({ id, url: `/plugins/${id}/client.js?rev=0` })
+const row = (id: string): BootModuleRow => ({ id, url: `/plugins/${id}/client.js?rev=0`, rev: '0' })
 
 interface Bench {
   loader: ClientModuleLoader
@@ -38,14 +38,14 @@ interface Bench {
  * through the window sink (`null` scripts a bundle that never calls load).
  */
 function bench(
-  entries: WebBootEntry[],
+  entries: BootModuleRow[],
   bundles: Record<string, Factory | null> = {},
   opts: { seed?: Record<string, unknown>; gated?: string[] } = {},
 ): Bench {
   const fetched: string[] = []
   const gates = new Map<string, () => void>()
-  const loader = createClientModuleLoader({
-    graph: { rev: 'test', entries },
+  const loader = new ClientModuleSystem({
+    modules: entries,
     staticModules: opts.seed ?? {},
     fetchBundle: (url) => {
       fetched.push(url)
@@ -175,7 +175,7 @@ describe('require resolution', () => {
 describe('static registry', () => {
   it('serves shell-own modules to import and require without any fetch', async () => {
     const shell = { marker: 'app-shell' }
-    const b = bench([row('a'), { id: 'app-shell' }], {
+    const b = bench([row('a')], {
       a: req => ({ dep: req('app-shell') }),
     })
     b.loader.registerStatic('app-shell', shell)
@@ -216,18 +216,13 @@ describe('failure modes', () => {
     await expect(b.loader.prefetch('nope')).rejects.toThrow('prefetch("nope") — not a graph entry')
   })
 
-  it('a graph row with no url and no static registration is loud', async () => {
-    const b = bench([{ id: 'ghost' }])
-    await expect(b.loader.import('ghost', '', {})).rejects.toThrow('no bundle url and no static registration')
-  })
-
   it('a duplicate graph entry is loud at construction', () => {
     expect(() => bench([row('a'), row('a')])).toThrow('duplicate graph entry "a"')
   })
 
   it('double boot is loud', () => {
     bench([])
-    expect(() => new ClientModuleLoaderImpl({ graph: { rev: 't', entries: [] }, staticModules: {} }))
+    expect(() => new ClientModuleSystem({ modules: [], staticModules: {} }))
       .toThrow('already installed (double boot?)')
   })
 })
@@ -289,7 +284,7 @@ describe('default transport seams', () => {
     const code = 'window.__ModuleLoader__ = document.__realmBridge;\n'
       + 'window.__ModuleLoader__.load({ id: "dee", factory: function () { return { marker: "via-script" } } })'
     vi.stubGlobal('fetch', async () => ({ ok: true, text: async () => code }))
-    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    const loader: ClientModuleLoader = new ClientModuleSystem({ modules: [row('dee')], staticModules: {} })
     ;(document as unknown as Record<string, unknown>).__realmBridge = win.__ModuleLoader__
     const surface = await loader.import('dee', '', {})
     expect((surface as { marker: string }).marker).toBe('via-script')
@@ -300,7 +295,7 @@ describe('default transport seams', () => {
 
   it('a non-ok bundle response is loud with the status', async () => {
     vi.stubGlobal('fetch', async () => ({ ok: false, status: 404 }))
-    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    const loader = new ClientModuleSystem({ modules: [row('dee')], staticModules: {} })
     await expect(loader.prefetch('dee')).rejects.toThrow('answered 404')
   })
 })

packages/client/modules/tsconfig.json

@@ -3,22 +3,14 @@
   "compilerOptions": {
     "rootDir": "src",
     "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "types": ["node"]
   },
-  "include": [
-    "src"
-  ],
+  "include": ["src"],
   "references": [
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../support/invariants"
-    }
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/loader" },
+    { "path": "../../host/webserver" },
+    { "path": "../../support/invariants" }
   ]
 }

packages/client/modules/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-modules', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/web/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-web
 
-Web shell kernel: `bootWebShell(el, seams?)` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected as its `internal` seam, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
+Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected as its `internal` seam, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
 
 Shell self-sufficiency (web2 hard rule): the kernel value-imports no plugin package — the boot status store and signals are hand-rolled here (`loader-status.ts`), so the loading page works while (and especially when) plugins fail. The app-shell assembly (`@deepseek-ai/dsh-client-app-shell`, a shell-owned pseudo entry with no npm package behind it) is the only module registered through `registerStatic`; it inject-waits on slots/sessions/layout like any plugin.
 

packages/client/web/src/boot.tsx

@@ -1,23 +1,32 @@
 /**
- * Web shell boot — the kernel face consumed by the apps/web entry. Everything
- * here is machinery that cannot itself be an entry, and none of it
+ * Web shell boot kernel — the face consumed by the apps/web entry. Everything
+ * here is machinery that cannot itself be a loader entry, and none of it
  * value-imports a plugin package (web2 shell self-sufficiency rule: the
- * loading page must work while — especially when — plugins fail).
+ * loading page must work while — especially when — plugins fail). The one
+ * sanctioned exception is the modules package (design §4.7 bootstrap
+ * identity): the module system cannot arrive through itself, so its class
+ * and its client-half wrapper are shell-bundled and the kernel adopts its
+ * plugin entry once cordis is up.
  *
- * Two-stage boot (web2 §0):
- *   Stage one (module face): build the module system over the host graph
- *   (`window.__DSH_BOOT__`) and prefetch every `immediately` row in parallel
- *   — fetch + execute registers factories only; module side effects wait for
- *   materialization. Prefetch failures are non-fatal here: stage two's
- *   import path retries the fetch and owns the loud failure.
- *   Stage two (plugin face): mount the vendored cordis Loader, inject the
- *   module system as its internal seam (BEFORE any entry exists — the
- *   bare-import fallback in tree.import must never run in a browser), create
- *   one loader entry per graph row (tree.import materializes each module),
- *   let fibers activate on service availability, then loader.await() + a
- *   full fiber sweep (all ACTIVE, else reject listing who/what/which
- *   service) → flip the settled signal so AppRoot switches to the real UI in
- *   one pass.
+ * AppWebEntry.run(), module face first, then plugin face: parse
+ * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary, D16)
+ * → build the module system over the module-view rows → render the loading
+ * page → prefetch every `immediately` row in parallel with mounting the
+ * vendored cordis Loader (internal-seam injection BEFORE any entry exists —
+ * the bare-import fallback in tree.import must never run in a browser) →
+ * await the prefetch tier, THEN adopt the modules entry and create one
+ * loader entry per plugin-view row plus the shell-own app-shell assembly
+ * entry → loader.await() + a full fiber sweep (all ACTIVE, else fail
+ * listing who/what/which service) → flip the settled signal so AppRoot
+ * switches to the real UI in one pass.
+ *
+ * Entry creation waits for the whole immediately tier: materialization runs
+ * synchronous cross-package require edges (e.g. i18n → runtime/client) that
+ * fiber inject waiting cannot protect — a bundle's factory must be
+ * registered before any dependent entry materializes. Per-row prefetch
+ * failures still resolve silently (the create-side import refetches and
+ * owns the loud failure), so the barrier never turns one bad bundle into a
+ * boot-wide fail-fast.
  *
  * Composition lives in the host graph; the shell makes zero composition
  * decisions (the app-shell assembly is itself a graph entry, the only
@@ -25,148 +34,205 @@
  */
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { createRoot } from 'react-dom/client'
+import { createRoot, type Root } from 'react-dom/client'
+import * as ModulesClient from '@deepseek-ai/dsh-client-modules/client'
 import {
-  createClientModuleLoader,
-  type ClientModuleLoader, type ClientModuleLoaderOptions, type DshWindow, type WebBootGraph,
-} from '@deepseek-ai/dsh-client-modules'
+  ClientModuleSystem, parseBootManifest,
+  type BootManifest, type ClientModuleSystemOptions, type DshWindow,
+} from '@deepseek-ai/dsh-client-modules/client'
 import * as AppShell from './app-shell.ts'
 import { APP_SHELL_ID } from './app-shell.ts'
 import { AppRoot } from './AppRoot.tsx'
 import { getStaticModules } from './seed.ts'
-import {
-  STATE_LABELS, createLoaderStatusStore, createSignal, type LoaderStatusStore,
-} from './loader-status.ts'
+import { STATE_LABELS, createLoaderStatusStore, createSignal } from './loader-status.ts'
 import './base.css'
 
 /** Module transport seams the shell passes through (jsdom tests replace the <script> path). */
-export type BootSeams = Pick<ClientModuleLoaderOptions, 'fetchBundle' | 'executeBundle'>
+export type BootSeams = Pick<ClientModuleSystemOptions, 'fetchBundle' | 'executeBundle'>
 
 /**
- * Sweep every loader entry after the tree quiesced: an entry without a fiber
- * failed its import; a fiber not ACTIVE is FAILED (apply threw) or PENDING
- * (a required service never arrived — cordis inject waiting has no timeout,
- * so this sweep is the fail-loud compensation).
+ * The modules package's own graph row id. The kernel adopts that entry
+ * itself (its wrapper is statically registered — shell-bundled code, never
+ * fetched), so the plugin-row loop must skip it: the vendored Group.create
+ * does not deduplicate by name, and a second fiber would provide 'modules'
+ * twice.
  */
-function assertEntriesActive(ctx: Context): void {
-  const failures: string[] = []
-  for (const entry of ctx.loader.entries()) {
-    const name = entry.options.name
-    if (entry.fiber === undefined) {
-      failures.push(`${name}: import failed (see console for the import error)`)
-      continue
-    }
-    const state = STATE_LABELS[entry.fiber.state]
-    if (state === 'active') continue
-    if (state === 'pending') {
-      const missing = Object.keys(entry.fiber.inject).filter((service) => ctx.get(service) === undefined)
-      failures.push(`${name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)
-    } else {
-      failures.push(`${name}: ${state}`)
-    }
-  }
-  if (failures.length > 0) {
-    throw new Error(`web boot: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)
-  }
-}
-
-/** Stage one: prefetch the immediately tier (factory registration only; failures defer to stage two's import). */
-async function prefetchImmediateTier(modules: ClientModuleLoader, graph: WebBootGraph): Promise<void> {
-  await Promise.all(graph.entries
-    .filter((row) => row.immediately === true)
-    .map((row) => modules.prefetch(row.id).catch(() => {
-      // Import (stage two) refetches and reports this loudly per entry;
-      // swallowing here keeps one failing prefetch from masking the others.
-    })))
-}
-
-/** Stage two: mount the Loader, inject the internal seam, create the graph entries, settle, sweep. */
-async function runPluginBoot(
-  ctx: Context, modules: ClientModuleLoader, graph: WebBootGraph, status: LoaderStatusStore,
-): Promise<void> {
-  await ctx.plugin(Loader)
-  const loader = ctx.loader
-  // Inject the module system BEFORE any entry exists: tree.import falls back
-  // to a bare dynamic import when internal is undefined, which in a browser
-  // is a guaranteed loud failure — correct as a tripwire, never as a path.
-  loader.internal = modules as never
-
-  // Status projection: AppRoot displays fiber truth. Every internal/status
-  // transition under an entry re-projects that entry's row from its ROOT
-  // fiber (child plugin fibers share the same entry).
-  ctx.on('internal/status', (fiber) => {
-    const entry = fiber.entry
-    if (entry === undefined || entry.fiber === undefined) return
-    status.set(entry.options.name, STATE_LABELS[entry.fiber.state])
-  })
-
-  // Entry creation order carries no semantics (fiber inject waiting owns
-  // activation order); creating concurrently lets non-prefetched bundle
-  // fetches parallelize. The app-shell assembly entry is appended by the
-  // kernel: it is shell-own code (host graph rows are all plugin bundles),
-  // and mounting the assembly is not a composition decision — it rides the
-  // same entry lifecycle so the sweep and status cover it uniformly.
-  const rows = [...graph.entries.map((row) => row.id), APP_SHELL_ID]
-  await Promise.all(rows.map(async (name) => {
-    status.set(name, 'loading')
-    const id = await loader.create({ name })
-    // A failed import leaves the entry fiberless (Entry._init logs and
-    // returns); project it as failed — no fiber means no status event.
-    if (loader.resolve(id).fiber === undefined) {
-      status.set(name, 'failed')
-    }
-  }))
-
-  await loader.await()
-  assertEntriesActive(ctx)
-}
+const MODULES_ID = '@deepseek-ai/dsh-client-modules'
 
 /**
- * Mount the web shell into a DOM element and start the two-stage boot chain.
- * @param el - mount point (the app's #root).
- * @param seams - optional module transport overrides (test environments).
- * @returns unmount disposer.
+ * The web shell kernel: mounts the loading page into a DOM element and runs
+ * the two-stage boot over the host graph. Fields hold only what must exist
+ * before cordis does — the parsed manifest, the module system, and the
+ * loading-page UI handles; everything else lives in plugins.
  */
-export function bootWebShell(el: HTMLElement, seams?: BootSeams): () => void {
-  const graph = (globalThis as DshWindow).__DSH_BOOT__
-  if (graph === undefined) throw new Error('web boot: no entry graph (window.__DSH_BOOT__ missing)')
+export class AppWebEntry {
+  private readonly el: HTMLElement
+  private readonly seams: BootSeams | undefined
+  private readonly status = createLoaderStatusStore()
+  private readonly settled = createSignal(false)
+  private readonly error = createSignal<string | undefined>(undefined)
+  // Assigned by run() before any private method or settled-gated closure reads them.
+  private ctx!: Context
+  private modules!: ClientModuleSystem
+  private manifest!: BootManifest
+  private root: Root | undefined
 
-  const ctx = new Context()
-  const modules = createClientModuleLoader({ graph, staticModules: getStaticModules(), ...seams })
-  // The app-shell assembly is the only shell-own module: every other graph
-  // row is a plugin bundle arriving through fetch (web2 single package form).
-  modules.registerStatic(APP_SHELL_ID, AppShell)
-  // Contract C5: the module system is a boot-owned kernel service (ctx.modules).
-  ctx.reflect.provide('modules', modules)
+  /**
+   * Hold the mount point; all work happens in {@link run}.
+   * @param el - mount point (the app's #root).
+   * @param seams - optional module transport overrides (test environments).
+   */
+  constructor(el: HTMLElement, seams?: BootSeams) {
+    this.el = el
+    this.seams = seams
+  }
 
-  const status = createLoaderStatusStore()
-  const settled = createSignal(false)
-  const error = createSignal<string | undefined>(undefined)
+  /**
+   * Run the boot chain to settlement. Boot-chain failures resolve (not
+   * reject): the loading page stays up and renders the failure report (the
+   * fail-loud surface the kernel owns). Rejects only when the boot manifest
+   * is missing or malformed — there is nothing to boot against.
+   * @returns resolves once the UI settled or the failure report rendered.
+   */
+  async run(): Promise<void> {
+    this.manifest = parseBootManifest((globalThis as DshWindow).__DSH_BOOT__)
 
-  const root = createRoot(el)
-  root.render(
-    <AppRoot
-      settled={settled}
-      status={status}
-      error={error}
-      renderApp={() => {
-        const shell = ctx.get('appShell')
-        // Unreachable after a clean settle (the app-shell entry is in every graph).
-        if (shell === undefined) throw new Error('web boot: appShell service missing after settled')
-        return shell.renderApp()
-      }}
-    />,
-  )
+    this.modules = new ClientModuleSystem({
+      modules: this.manifest.modules, staticModules: getStaticModules(), ...this.seams,
+    })
+    // The app-shell assembly is the only shell-own module: every other graph
+    // row is a plugin bundle arriving through fetch (web2 single package form).
+    this.modules.registerStatic(APP_SHELL_ID, AppShell)
+    // Adoption handoff, supply side (design §4.7): register the modules
+    // package's own client half under its bare package name (= graph row id
+    // = entry name — a suffixed key would miss the statics branch and
+    // trigger a real fetch), and put the instance on the kernel slot the
+    // wrapper's apply reads to provide ctx.modules.
+    this.modules.registerStatic(MODULES_ID, ModulesClient)
+    ;(globalThis as DshWindow).__DSH_MODULES__ = this.modules
 
-  prefetchImmediateTier(modules, graph)
-    .then(() => runPluginBoot(ctx, modules, graph, status))
-    .then(
-      () => { settled.set(true) },
-      (reason: unknown) => {
-        // Stay on the loading page; surface the sweep report (fail loud).
-        console.error(reason)
-        error.set(reason instanceof Error ? reason.message : String(reason))
-      },
+    this.root = createRoot(this.el)
+    this.root.render(
+      <AppRoot
+        settled={this.settled}
+        status={this.status}
+        error={this.error}
+        renderApp={() => {
+          const shell = this.ctx.get('appShell')
+          // Unreachable after a clean settle (the app-shell entry is in every graph).
+          if (shell === undefined) throw new Error('web boot: appShell service missing after settled')
+          return shell.renderApp()
+        }}
+      />,
     )
-  return () => { root.unmount() }
+
+    // The immediately tier prefetches in parallel with Loader mounting;
+    // runPluginBoot awaits it before creating entries (see module comment:
+    // cross-package synchronous require edges need every immediately-tier
+    // factory registered before any materialization).
+    const prefetching = this.prefetchImmediateTier()
+    this.ctx = new Context()
+    try {
+      await this.runPluginBoot(prefetching)
+      this.settled.set(true)
+    } catch (reason) {
+      // Stay on the loading page; surface the sweep report (fail loud).
+      console.error(reason)
+      this.error.set(reason instanceof Error ? reason.message : String(reason))
+    }
+  }
+
+  /** Unmount the shell (loading page or settled UI). */
+  dispose(): void {
+    this.root?.unmount()
+  }
+
+  /** Prefetch the immediately tier (factory registration only; failures defer to the import path). */
+  private async prefetchImmediateTier(): Promise<void> {
+    await Promise.all(this.manifest.plugins
+      .filter((row) => row.immediately)
+      .map((row) => this.modules.prefetch(row.id).catch(() => {
+        // Import refetches and reports this loudly per entry; swallowing
+        // here keeps one failing prefetch from masking the others.
+      })))
+  }
+
+  /** Plugin face: mount the Loader, inject the internal seam, adopt modules, create the graph entries, settle, sweep. */
+  private async runPluginBoot(prefetching: Promise<void>): Promise<void> {
+    const ctx = this.ctx
+    await ctx.plugin(Loader)
+    const loader = ctx.loader
+    // Inject the module system BEFORE any entry exists: tree.import falls back
+    // to a bare dynamic import when internal is undefined, which in a browser
+    // is a guaranteed loud failure — correct as a tripwire, never as a path.
+    loader.internal = this.modules as never
+
+    // Status projection: AppRoot displays fiber truth. Every internal/status
+    // transition under an entry re-projects that entry's row from its ROOT
+    // fiber (child plugin fibers share the same entry).
+    ctx.on('internal/status', (fiber) => {
+      const entry = fiber.entry
+      if (entry === undefined || entry.fiber === undefined) return
+      this.status.set(entry.options.name, STATE_LABELS[entry.fiber.state])
+    })
+
+    // Barrier before any entry exists: entry creation materializes bundles,
+    // and materialization runs synchronous cross-package require edges that
+    // need every immediately-tier factory already registered (module
+    // comment). Resolves even when individual prefetches failed.
+    await prefetching
+
+    // Adoption handoff, plugin side: the modules entry is created first —
+    // its wrapper apply reads the kernel slot and provides ctx.modules (the
+    // provide lives on the plugin face; see MODULES_ID for why the row loop
+    // must then skip it).
+    const rows = [MODULES_ID, ...this.manifest.plugins.map((row) => row.id).filter((id) => id !== MODULES_ID), APP_SHELL_ID]
+    // Entry creation order carries no semantics (fiber inject waiting owns
+    // activation order); creating concurrently lets non-prefetched bundle
+    // fetches parallelize. The app-shell assembly entry is appended by the
+    // kernel: it is shell-own code (host graph rows are all plugin bundles),
+    // and mounting the assembly is not a composition decision — it rides the
+    // same entry lifecycle so the sweep and status cover it uniformly.
+    await Promise.all(rows.map(async (name) => {
+      this.status.set(name, 'loading')
+      const id = await loader.create({ name })
+      // A failed import leaves the entry fiberless (Entry._init logs and
+      // returns); project it as failed — no fiber means no status event.
+      if (loader.resolve(id).fiber === undefined) {
+        this.status.set(name, 'failed')
+      }
+    }))
+
+    await loader.await()
+    this.assertEntriesActive()
+  }
+
+  /**
+   * Sweep every loader entry after the tree quiesced: an entry without a
+   * fiber failed its import; a fiber not ACTIVE is FAILED (apply threw) or
+   * PENDING (a required service never arrived — cordis inject waiting has no
+   * timeout, so this sweep is the fail-loud compensation).
+   */
+  private assertEntriesActive(): void {
+    const ctx = this.ctx
+    const failures: string[] = []
+    for (const entry of ctx.loader.entries()) {
+      const name = entry.options.name
+      if (entry.fiber === undefined) {
+        failures.push(`${name}: import failed (see console for the import error)`)
+        continue
+      }
+      const state = STATE_LABELS[entry.fiber.state]
+      if (state === 'active') continue
+      if (state === 'pending') {
+        const missing = Object.keys(entry.fiber.inject).filter((service) => ctx.get(service) === undefined)
+        failures.push(`${name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)
+      } else {
+        failures.push(`${name}: ${state}`)
+      }
+    }
+    if (failures.length > 0) {
+      throw new Error(`web boot: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)
+    }
+  }
 }

packages/client/web/src/index.ts

@@ -1,13 +1,13 @@
 /**
- * Web shell library entry. The shell's product is {@link bootWebShell} —
- * apps/web's vite entry calls it against #root; everything else (AppRoot
+ * Web shell library entry. The shell's product is {@link AppWebEntry} —
+ * apps/web's vite entry runs it against #root; everything else (AppRoot
  * gate, app-shell assembly entry, module-table staticModules, platform constants) is
  * internal to the boot chain. PLATFORM_MODULES is re-exported as the C1
  * single source of truth for the tsdown client externals projection.
  * @module @deepseek-ai/dsh-client-web
  */
 
-export { bootWebShell, type BootSeams } from './boot.tsx'
+export { AppWebEntry, type BootSeams } from './boot.tsx'
 export { AppRoot, type AppRootProps } from './AppRoot.tsx'
 export { buildRenderApp, type AssemblyDeps } from './app.tsx'
 export { DocumentTitle, type DocumentTitleProps } from './DocumentTitle.tsx'

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -188,6 +188,32 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'clientModuleHost',
+    summary: 'The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap.',
+    methods: [
+      {
+        signature: 'graph(): WebBootGraph',
+        jsDoc: '/**\n * Current composed entry graph (stable object between changes).\n * @returns the graph served as `window.__DSH_BOOT__`.\n */',
+      },
+      {
+        signature: 'clientPath(id: string): string | undefined',
+        jsDoc: '/**\n * Absolute path of an entry\'s client bundle.\n * @param id - entry id (package name).\n * @returns the path, or undefined for an unknown id.\n */',
+      },
+      {
+        signature: 'rebuilt(id: string): string | undefined',
+        jsDoc: '/**\n * Re-hash one bundle (the HMR watch\'s registration hook — the only entry\n * point through which bundle content changes reach the graph).\n * @param id - entry id (package name).\n * @returns the new rev, or undefined for an unknown id.\n */',
+      },
+      {
+        signature: 'onRebuilt(listener: (id: string, rev: string) => void): () => void',
+        jsDoc: '/**\n * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.\n * @param listener - receives the entry id and its new bundle rev.\n * @returns the unsubscriber.\n */',
+      },
+      {
+        signature: 'onGraphChanged(listener: () => void): () => void',
+        jsDoc: '/**\n * Fires after any flush that recomposed the graph (row added/removed, or a\n * rebuilt rev change). Pull model: listeners re-read {@link graph}.\n * @param listener - notified with no payload.\n * @returns the unsubscriber.\n */',
+      },
+    ],
+  },
   {
     key: 'codeRuntime',
     summary: 'Registers one `ctx.codeRuntime` implementation.',
@@ -314,6 +340,20 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'httpServer',
+    summary: 'The web-shape HTTP carrier service.',
+    methods: [
+      {
+        signature: 'register(route: WebRoute): () => void',
+        jsDoc: '/**\n * Register a named route. Duplicate (kind, path) throws — route patterns are\n * a composition-level contract, so a collision is a misconfiguration.\n * @param route - kind, path, and the owning handler.\n * @returns the disposer removing the route.\n */',
+      },
+      {
+        signature: 'tapIndex(transform: (html: string) => string): () => void',
+        jsDoc: '/**\n * Register an index.html transform, applied to every index response in\n * registration order.\n * @param transform - pure html-to-html function.\n * @returns the disposer removing the transform.\n */',
+      },
+    ],
+  },
   {
     key: 'invariants',
     summary: 'Package-owned invariant registry with global and regex-based selection.',
@@ -642,6 +682,20 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'storage',
+    summary: 'The storage hub service.',
+    methods: [
+      {
+        signature: 'mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void',
+        jsDoc: '/**\n * Mount a data-form facility on the hub. Mounting is an effect: the\n * returned disposer unmounts the form.\n * @param form - Form key declared in {@link StorageForms}.\n * @param facility - The facility instance to expose.\n * @returns the disposer that unmounts the form.\n */',
+      },
+      {
+        signature: 'form<K extends keyof StorageForms>(form: K): StorageForms[K]',
+        jsDoc: '/**\n * Resolve a mounted data form.\n * @param form - Form key declared in {@link StorageForms}.\n * @returns the mounted facility.\n */',
+      },
+    ],
+  },
   {
     key: 'subagents',
     summary: 'Named provider registry and capability-checked start surface.',
@@ -846,6 +900,28 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'workspace',
+    summary: 'The workspace registry service.',
+    methods: [
+      {
+        signature: 'async create(path: string, title?: string): Promise<Workspace>',
+        jsDoc: '/**\n * Create a workspace over an existing directory. The path is canonicalized\n * through `fs.realpath` first — a nonexistent path rejects with the\n * original `ENOENT`, a path resolving to anything but a directory rejects,\n * and a canonical path already owned by another workspace (including a\n * symlink resolving to it) rejects.\n * @param path - Directory the workspace points at; canonicalized before storing.\n * @param title - Display title; defaults to `basename` of the canonical path.\n * @returns the created workspace after durability.\n */',
+      },
+      {
+        signature: 'get(id: WorkspaceId): Workspace | undefined',
+        jsDoc: '/**\n * Look up a workspace by id.\n * @param id - The workspace id.\n * @returns the workspace, or `undefined` when unknown.\n */',
+      },
+      {
+        signature: 'list(): Workspace[]',
+        jsDoc: '/**\n * Snapshot of all workspaces, in load-then-creation order.\n * @returns a fresh array of the cached entities.\n */',
+      },
+      {
+        signature: 'async resolveByPath(path: string): Promise<Workspace | undefined>',
+        jsDoc: '/**\n * Resolve a workspace by directory path, through the same `fs.realpath`\n * canon as {@link create} (hence async). A path that does not exist rejects\n * with the original error — a missing directory has no canonical form to\n * compare (a workspace whose recorded directory vanished is only reachable\n * by id; see `Workspace.status`).\n * @param path - Directory path in any spelling (symlinks, `..`, trailing slash).\n * @returns the owning workspace, or `undefined` when none matches.\n */',
+      },
+    ],
+  },
 ]
 
 /** Every harness event, sorted by name. */
@@ -997,6 +1073,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * A command was registered or unregistered. This is an unfiltered registry\n * notification because a global or scoped change may affect any UI view.\n * Observer failures are contained and cannot veto the registry mutation.\n * @mode emit\n */',
     summary: 'A command was registered or unregistered.',
   },
+  {
+    name: 'domain/changed',
+    mode: 'emit',
+    signature: '\'domain/changed\'(change: DomainChanged): void',
+    jsDoc: '/**\n * A domain record or the global singleton changed, emitted once per write\n * strictly after the backend acknowledged durability. Events of one\n * domain arrive in its write-chain order.\n * @param change - domain, table (`\'\'` for global), key (`\'\'` for global),\n * operation discriminant, and on `put` the new snapshot.\n * @mode emit\n */',
+    summary: 'A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability.',
+  },
   {
     name: 'fs/edit-intent',
     mode: 'waterfall',
@@ -1999,6 +2082,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SpillSource',
     declaration: 'export interface SpillSource {\n    toolName: string;\n    callId: CallId;\n    label: string;\n}',
   },
+  {
+    name: 'StorageForms',
+    declaration: 'export interface StorageForms {\n}',
+  },
   {
     name: 'StreamChunk',
     declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n    replayState?: unknown;\n};',
@@ -2291,6 +2378,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WebFetchResult',
     declaration: 'export interface WebFetchResult {\n    readonly url: string;\n    readonly statusCode: number;\n    readonly body: WebFetchBody;\n    readonly truncated: boolean;\n}',
   },
+  {
+    name: 'WebRoute',
+    declaration: 'export interface WebRoute {\n    kind: WebRouteKind;\n    path: string;\n    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;\n}',
+  },
+  {
+    name: 'WebRouteKind',
+    declaration: 'export type WebRouteKind = \'exact\' | \'prefix\';',
+  },
   {
     name: 'WebSearchProvider',
     declaration: 'export interface WebSearchProvider {\n    readonly id: string;\n    available(): boolean;\n    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;\n}',
@@ -2335,6 +2430,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WorkflowStopReason',
     declaration: 'export type WorkflowStopReason = \'completed\' | \'cancelled\' | \'error\';',
   },
+  {
+    name: 'Workspace',
+    declaration: 'export interface Workspace {\n    readonly id: WorkspaceId;\n    readonly path: string;\n    readonly title: string;\n    readonly sessionIds: readonly SessionId[];\n    setTitle(title: string): Promise<void>;\n    attachSession(sessionId: SessionId): Promise<void>;\n    detachSession(sessionId: SessionId): Promise<void>;\n    status(): Promise<\'ok\' | \'missing-dir\'>;\n}',
+  },
 ]
 
 /** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */

packages/host/apiproxy/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-apiproxy
 
-The ApiProxy front layer every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser) and the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side). Host assembly lives in `dsh-host-runtime`.
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The core spine composition lives in `dsh-host-runtime`.
 
 ## Contract layer (`/api`)
 
@@ -24,6 +24,6 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `dsh-host-runtime` and is still a stub there.
+- **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `src/api-proxy.ts` and is still minimal (questions only, no approvals).
 - **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code.
 - **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.

packages/host/apiproxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-host-apiproxy",
-  "description": "ApiProxy front layer: the TS contract (api/) and the fetch carrier pair (fetch/); host assembly lives in dsh-host-runtime",
+  "description": "API gateway: the ApiProxy contract (api/), the fetch carrier pair (fetch/), and the host-side gateway plugin providing ctx.apiProxy",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -40,12 +40,16 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "schemastery": "^3.18.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

packages/host/apiproxy/src/api-proxy.ts

@@ -11,12 +11,14 @@ import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+// Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
+import type {} from '@deepseek-ai/dsh-tools'
 import type {
   ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
-} from '@deepseek-ai/dsh-host-apiproxy/api'
-import { questionResponsePayloadSchema } from '@deepseek-ai/dsh-host-apiproxy/api/questions.schema'
-import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
-import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+} from './api/index.ts'
+import { questionResponsePayloadSchema } from './api/questions.schema.ts'
+import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from './api/rpc.ts'
+import { RpcId } from './api/rpc.ts'
 import type {
   AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
@@ -170,7 +172,7 @@ async function summarizeCold(persistence: SessionPersistence, meta: SessionHeade
   }
 }
 
-/** Host-level default agent routing (same shape as bootHost's HostDefaults; avoids an impl→index reverse import). */
+/** Host-level default agent routing (same shape as dsh-host-runtime's HostDefaults, kept structural to avoid a reverse dependency). */
 export interface ApiProxyDefaults {
   provider: string
   model: string
@@ -272,8 +274,8 @@ function backscanArgs(events: readonly SessionEvent[], callId: string): { name:
 class SessionNotFound extends Error {}
 
 /**
- * Implement ApiProxy over the ctx composed by bootHost.
- * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
+ * Implement ApiProxy over a composed host context.
+ * @param ctx - a context with the host spine mounted (sessions/agents/tools/userInteraction services).
  * @param defaults - host-level default provider/model: injected as
  * agentOptions on create/resume, reported by describe from the same source.
  * @returns the ApiProxy implementation.

packages/host/apiproxy/src/index.ts

@@ -1,13 +1,70 @@
 /**
- * @deepseek-ai/dsh-host-apiproxy — the front layer every client shape shares:
- * the ApiProxy contract (api/: types + zod schemas, browser-safe) and the
- * fetch carrier pair (fetch/: toFetchHandler on the host side, AbstractApiClient +
- * platform subclasses on the client side). Host assembly (bootHost/createApiProxy/startHost)
- * lives in @deepseek-ai/dsh-host-runtime.
+ * @deepseek-ai/dsh-host-apiproxy — the API gateway every client shape shares:
+ * the ApiProxy contract (api/: types + zod schemas, browser-safe), the fetch
+ * carrier pair (fetch/: toFetchHandler on the host side, AbstractApiClient +
+ * platform subclasses on the client side), and the host-side implementation
+ * (api-proxy.ts: createApiProxy + the ApiProxyService gateway plugin providing
+ * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
+ * routes — carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves.
  */
 
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { ApiProxy } from './api/index.ts'
+import { createApiProxy } from './api-proxy.ts'
+
 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
 export { toFetchHandler } from './fetch/handler.ts'
 export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
 export type { IApiClient } from './fetch/client.ts'
+export { createApiProxy } from './api-proxy.ts'
+export type { ApiProxyDefaults } from './api-proxy.ts'
+
+declare module 'cordis' {
+  interface Context {
+    /** The host-side ApiProxy implementation (the transport-agnostic gateway face). */
+    apiProxy: ApiProxy
+  }
+}
+
+/** Gateway plugin config: the host-level default agent routing. */
+export interface Config {
+  /** Default provider route for created/resumed agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+}
+
+/**
+ * The API gateway service: implements the ApiProxy contract over the composed
+ * host context and provides it as `ctx.apiProxy`. The default project
+ * directory for new sessions is the host process working directory (not a
+ * config field this round).
+ */
+export class ApiProxyService extends Service implements ApiProxy {
+  static inject = ['agents', 'sessions', 'tools', 'userInteraction']
+
+  static Config: z<Config> = z.object({
+    provider: z.string().required(),
+    model: z.string().required(),
+  })
+
+  readonly sessions: ApiProxy['sessions']
+  readonly host: ApiProxy['host']
+  readonly events: ApiProxy['events']
+  readonly respond: ApiProxy['respond']
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'apiProxy')
+    const api = createApiProxy(ctx, { provider: config.provider, model: config.model, cwd: process.cwd() })
+    this.sessions = api.sessions
+    this.host = api.host
+    this.events = api.events
+    // createApiProxy returns closures (no `this` capture); bind only satisfies
+    // the unbound-method lint without changing behavior.
+    this.respond = api.respond.bind(api)
+  }
+}
+
+export default ApiProxyService

packages/host/apiproxy/src/invariant.ts

@@ -15,11 +15,12 @@ export const name = 'host-apiproxy-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: this package is the wire contract layer (types,
- * schemas, fetch carrier glue) — it emits no cordis events and owns no
- * mutable cross-plugin relation. rpcId round-trip and schema acceptance are
- * enforced at the carrier boundary and exercised by the protocol-isomorphism
- * suite; the live implementation relations belong to dsh-host-runtime.
+ * No runtime invariant: this package is the wire contract layer plus the
+ * host-side gateway over services owned elsewhere — it emits no cordis events
+ * of its own; the session/agent event streams it projects are asserted by
+ * their owning packages' companions. rpcId round-trip and schema acceptance
+ * are enforced at the carrier boundary and exercised by the
+ * protocol-isomorphism suite.
  */
 const install: InvariantInstaller = () => {}
 

packages/host/apiproxy/tsconfig.json

@@ -8,18 +8,33 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../util/brand"
     },
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../core/agent"
+    },
     {
       "path": "../../core/session"
     },
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../session-title/session-title"
+    },
     {
       "path": "../../ui/user-approval"
     },

packages/host/runtime/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-runtime
 
-Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence and immediate fallback titles, optional first-message model summaries, system prompt, tools, agents, agent loop, workspace instructions, local bash, and the provider-neutral user-interaction service), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence and immediate fallback titles, optional first-message model summaries, system prompt, tools, agents, agent loop, workspace instructions, local bash, and the provider-neutral user-interaction service), and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }` (its `api` comes from [`dsh-host-apiproxy`](../apiproxy/README.md)'s `createApiProxy` over that composition).
 
 Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
 

packages/host/runtime/package.json

@@ -39,7 +39,6 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",

packages/host/runtime/src/index.ts

@@ -1,14 +1,11 @@
 /**
  * @deepseek-ai/dsh-host-runtime — host runtime assembly layer: the core spine
- * composition (bootHost), the ApiProxy implementation (createApiProxy), and
- * the one-step shell seam (startHost). Host-level configuration (defaults,
- * persistenceRoot, future user profile) lives here.
+ * composition (bootHost) and the one-step shell seam (startHost). The ApiProxy
+ * implementation lives in @deepseek-ai/dsh-host-apiproxy. Host-level
+ * configuration (defaults, persistenceRoot, future user profile) lives here.
  */
 
 export { bootHost } from './boot.ts'
 export type { BootHostOptions, HostDefaults, HostHandle } from './boot.ts'
-export { createApiProxy } from './api-proxy.ts'
-export type { ApiProxyDefaults } from './api-proxy.ts'
 export { startHost } from './start.ts'
 export type { StartHostOptions, RunningHost } from './start.ts'
-export { mountWebPlugins } from './web-plugins.ts'

packages/host/runtime/src/start.ts

@@ -8,10 +8,9 @@
 
 import type { Context } from 'cordis'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
-import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { createApiProxy, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import { bootHost } from './boot.ts'
 import type { BootHostOptions, HostDefaults } from './boot.ts'
-import { createApiProxy } from './api-proxy.ts'
 
 /** Options for startHost. */
 export interface StartHostOptions {

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

@@ -1,57 +0,0 @@
-/**
- * Web client plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
- * entry tree over the caller-supplied client plugin roster. The roster is a
- * composition decision and lives in the composing app (apps/cli); this module
- * only owns the mount/settle/fail-loud mechanics. The web plugin registry
- * discovers fetch-arrival entries among the mounted packages by their
- * package.json dshClient declarations; node halves are empty applies, so
- * mounting them here costs nothing beyond Loader governance.
- */
-import { createRequire } from 'node:module'
-import type { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-
-/** What the shell hands the web plugin registry (loader view + module resolution seam). */
-export interface MountedWebPlugins {
-  /** Entry enumeration surface of the mounted Loader (registry scan source). */
-  loader: { entries(): Iterable<{ options: { name: string }; fiber?: unknown; disabled: boolean }> }
-  /** Resolve a plugin package's package.json absolute path. */
-  resolvePkgJson: (name: string) => string
-}
-
-/**
- * Mount the Loader (when absent) and create one in-memory entry per client
- * plugin package, then wait for the tree to settle. A plugin whose import
- * fails leaves its entry fiber-less — surfaced here as a loud throw listing
- * the failures (misconfiguration must not silently drop a client plugin).
- * @param ctx - host root context (bootHost product).
- * @param plugins - client plugin package names to mount (the composition layer's roster).
- * @param anchor - module URL anchoring bare-specifier resolution (the composing
- * app's import.meta.url; the roster packages must be dependencies of that app).
- * @returns the loader view and package.json resolver the registry consumes.
- */
-export async function mountWebPlugins(
-  ctx: Context, plugins: readonly string[], anchor: string,
-): Promise<MountedWebPlugins> {
-  // The Loader resolves bare specifiers against ctx.baseUrl; without one the
-  // import silently fails and every entry stays fiber-less. The composing app
-  // declares the roster packages as dependencies, so its URL is the right anchor.
-  ctx.baseUrl ??= anchor
-  if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
-  const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
-  for (const name of plugins) {
-    if (!existing.has(name)) await ctx.loader.create({ name })
-  }
-  await ctx.loader.await()
-  const dead = [...ctx.loader.entries()]
-    .filter(entry => plugins.includes(entry.options.name))
-    .filter(entry => entry.fiber === undefined && !entry.disabled)
-  if (dead.length > 0) {
-    throw new Error(`web-plugins: client plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
-  }
-  const require = createRequire(anchor)
-  return {
-    loader: ctx.loader,
-    resolvePkgJson: name => require.resolve(`${name}/package.json`),
-  }
-}

packages/host/runtime/tests/api-proxy-cold.spec.ts

@@ -16,7 +16,7 @@ import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
-import { createApiProxy } from '../src/api-proxy.ts'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
 
 const sid = (id: string): SessionId => id as SessionId
 

packages/host/runtime/tests/api-proxy-view.spec.ts

@@ -21,7 +21,7 @@ import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
-import { createApiProxy } from '../src/api-proxy.ts'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
 
 const reply = (text: string): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text }])
 

packages/host/runtime/tests/web-plugins.spec.ts

@@ -1,111 +0,0 @@
-/**
- * mountWebPlugins unit coverage (keyless). The Loader-facing behavior —
- * baseUrl anchoring, entry creation with idempotent reuse, the fiber-less
- * fail-loud sweep, and the resolver seam — is exercised against a stubbed
- * loader service so it runs without built lib/ artifacts. The roster is
- * caller-supplied now (composition moved to apps/cli), so these tests pass
- * their own lists.
- */
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it } from 'vitest'
-import { mountWebPlugins } from '../src/web-plugins.ts'
-
-const ROSTER = [
-  '@deepseek-ai/dsh-plugin-a',
-  '@deepseek-ai/dsh-plugin-b',
-  '@deepseek-ai/dsh-plugin-c',
-] as const
-
-interface FakeEntry {
-  options: { name: string }
-  fiber?: unknown
-  disabled: boolean
-}
-
-/** Loader stub provided under the real service name (mountWebPlugins skips ctx.plugin(Loader) when present). */
-class FakeLoader {
-  readonly created: string[] = []
-  awaited = 0
-  constructor(private readonly entriesList: FakeEntry[], private readonly onCreate?: (name: string) => void) {}
-  entries(): Iterable<FakeEntry> {
-    return this.entriesList
-  }
-  async create(options: { name: string }): Promise<void> {
-    this.created.push(options.name)
-    this.onCreate?.(options.name)
-  }
-  async await(): Promise<void> {
-    this.awaited += 1
-  }
-}
-
-let root: Context | undefined
-
-afterEach(async () => {
-  await root?.fiber.dispose()
-  root = undefined
-})
-
-function withLoader(entriesList: FakeEntry[], onCreate?: (name: string) => void): { ctx: Context; loader: FakeLoader } {
-  root = new Context()
-  const loader = new FakeLoader(entriesList, onCreate)
-  root.reflect.provide('loader', loader)
-  return { ctx: root, loader }
-}
-
-describe('mountWebPlugins (stubbed loader)', () => {
-  it('creates one entry per roster package, awaits the tree, and returns the loader view + resolver', async () => {
-    const entriesList: FakeEntry[] = []
-    const { ctx, loader } = withLoader(entriesList, (name) => {
-      entriesList.push({ options: { name }, fiber: {}, disabled: false })
-    })
-    const mounted = await mountWebPlugins(ctx, ROSTER, import.meta.url)
-    expect(loader.created).toEqual([...ROSTER])
-    expect(loader.awaited).toBe(1)
-    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...ROSTER])
-    // The resolver resolves a real package manifest through real module resolution, anchored at this test file.
-    expect(mounted.resolvePkgJson('@deepseek-ai/dsh-host-runtime')).toMatch(/package\.json$/)
-    expect(ctx.baseUrl).toBeDefined()
-  })
-
-  it('reuses existing entries (idempotent mount creates no duplicates)', async () => {
-    const preexisting: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: {}, disabled: false }))
-    const { ctx, loader } = withLoader(preexisting)
-    await mountWebPlugins(ctx, ROSTER, import.meta.url)
-    expect(loader.created).toEqual([])
-  })
-
-  it('throws listing every fiber-less entry (silent import failure must not drop a client plugin)', async () => {
-    const entriesList: FakeEntry[] = []
-    const { ctx } = withLoader(entriesList, (name) => {
-      // First one loads; the rest stay fiber-less (import failed silently).
-      entriesList.push({ options: { name }, fiber: entriesList.length < 1 ? {} : undefined, disabled: false })
-    })
-    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url))
-      .rejects.toThrow(/client plugin\(s\) failed to load: .*dsh-plugin-c/)
-  })
-
-  it('skips disabled entries in the fail-loud sweep (disabled is the one valid fiber-less state)', async () => {
-    const entriesList: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
-    const { ctx } = withLoader(entriesList)
-    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url)).resolves.toBeDefined()
-  })
-
-  it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
-    root = new Context()
-    // An empty roster keeps this keyless and artifact-free: the branch under
-    // test is only the Loader auto-mount.
-    await mountWebPlugins(root, [], import.meta.url)
-    expect(root.get('loader') !== undefined).toBe(true)
-  }, 30_000) // cold-cache import of the real vendored Loader crosses the network-disk 5s default
-
-  it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
-    const entriesList: FakeEntry[] = []
-    const { ctx } = withLoader(entriesList, (name) => {
-      entriesList.push({ options: { name }, fiber: {}, disabled: false })
-    })
-    ctx.baseUrl = 'file:///caller/anchor/'
-    await mountWebPlugins(ctx, ROSTER, import.meta.url)
-    expect(ctx.baseUrl).toBe('file:///caller/anchor/')
-  })
-})

packages/host/webserver/README.md

@@ -1,18 +1,16 @@
 # @deepseek-ai/dsh-host-webserver
 
-Web-shape HTTP carrier: a `node:http` server routing `/api/*` to an injected fetch-shaped handler (node:http ↔ WHATWG bridge with SSE streamed out chunk by chunk) and everything else to static file serving with the step1-locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405.
+Plain HTTP route-registration plugin (default-exported `WebServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.webServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics.
 
-The package has zero workspace dependencies on purpose: the handler arrives by structural typing (`{ fetch: typeof fetch }`), so `webserver ← runtime` is a runtime injection relationship, never a package dependency. Callers supply both the bind `host` and `port`; port `0` requests an OS-assigned port and the running handle reports the assigned value. `dsh web` defaults to `127.0.0.1` and accepts `--host 0.0.0.0` for deliberate network access. Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
+The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
 
-Client-disconnect detection hangs off the **response** `close` event, not the request: since Node 16, `IncomingMessage` `close` fires as soon as the request body is consumed (immediately for a bodyless GET), which would abort every SSE stream right after open. `RunningWebServer.close()` pairs `close()` with `closeAllConnections()` because SSE connections never end on their own.
-
-A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and reported to `onError`; it never becomes a process-killing unhandled rejection.
+A listen failure (EADDRINUSE…) throws out of activation — a FAILED fiber the boot's fail-loud sweep reports. A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and logged as a warning; it never exits the process. Disposal pairs `close()` with `closeAllConnections()` because held-open responses (SSE) never end on their own.
 
 In development, the client-plugin registry synchronously captures each built bundle's stat baseline before it returns, then polls those baselines and re-hashes changed content. Each rescan stages its candidate table, graph, and watch map before publishing them, so a baseline failure preserves the prior graph. An immediate rebuild therefore cannot disappear into an asynchronously established watch baseline; a rename window marks the path dirty, retains the last successful baseline, and forces a re-hash when the bundle reappears even with identical metadata.
 
 ## Model Experience
 
-None, as the package is a pure HTTP carrier between the browser and the injected API handler; nothing here reaches a model request.
+None, as the package is a pure HTTP carrier between the browser and the routes other plugins register; nothing here reaches a model request.
 
 #### KV Cache effect
 
@@ -20,6 +18,6 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **No TLS, auth, or origin policy** — callers that bind a non-loopback address expose the server to that network; deployment hardening (or fronting it with a real reverse proxy) is deliberately out of scope for the dev-facing v1.
+- **No TLS, auth, or origin policy** — binding a non-loopback address exposes the server to that network; deployment hardening (or fronting it with a real reverse proxy) is deliberately out of scope for the dev-facing v1.
 - **The starter MIME table is minimal** — extensions beyond the vite-emitted set fall back to `application/octet-stream`; extend the table when an asset class actually ships.
-- **Socket options are fixed** — callers select the bind host and port, while backlog and other socket settings remain internal until a deployment needs them.
+- **Socket options are fixed** — config selects the bind host and port, while backlog and other socket settings remain internal until a deployment needs them.

packages/host/webserver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-host-webserver",
-  "description": "Web-shape HTTP carrier: static file serving plus the /api/* bridge to an injected fetch-shaped handler (SSE streamed through)",
+  "description": "Plain HTTP route-registration plugin: named-route registry (webServer service) + index transform taps + static dist fallback; knows no harness concepts",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -30,6 +30,9 @@
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "^0.0.1"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "workspace:^"

packages/host/webserver/src/index.ts

@@ -1,232 +1,184 @@
 /**
- * @deepseek-ai/dsh-host-webserver — the web-shape HTTP carrier: node:http server
- * routing /api/* to an injected fetch-shaped handler (node:http ↔ WHATWG
- * bridge with SSE streamed out chunk by chunk) and everything else to static
- * file serving. Web (browser) shape only — Electron loads dist over file://
- * and carries fetch over an IPC bridge, not this server. This package never
- * prints: the URL line belongs to the shell.
+ * @deepseek-ai/dsh-host-webserver — plain HTTP route-registration plugin: a
+ * node:http server plus the `httpServer` service (named-route registry + index
+ * transform taps + static dist fallback). Knows no harness concepts — every
+ * feature surface (API bridge, plugin bundles, SSE) is a route some other
+ * plugin registers. Web (browser) shape only — Electron loads dist over
+ * file:// and carries fetch over an IPC bridge, not this server. This package
+ * never prints: the URL line belongs to the shell.
  */
 
 import { createServer } from 'node:http'
-import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { IncomingMessage, ServerResponse, Server } from 'node:http'
 import { readFile } from 'node:fs/promises'
 import type { AddressInfo } from 'node:net'
 import { dirname } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
 import { serveStatic } from './static.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, WebBootEntry, WebBootGraph, WebPluginRegistryDeps,
-} from './web-plugins.ts'
-export type { PluginEventChannel, PluginEventFrame } from './plugin-events.ts'
-
-/** Options for startWebServer. */
-export interface WebServerOptions {
-  /** Address or hostname to listen on. */
-  host: string
-  /** Port to listen on; zero requests an OS-assigned port. */
-  port: number
-  /**
-   * Absolute path of index.html inside the static root — the caller resolves
-   * it (dist location is workspace knowledge of the shell, not this package's).
-   */
-  distIndex: string
-  /** 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 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, 'graph' | 'clientPath' | 'onRebuilt'>
+declare module 'cordis' {
+  interface Context {
+    httpServer: HttpServerService
+  }
 }
 
-/** Listening web server handle. */
-export interface RunningWebServer {
-  /** The listening port, including the OS-assigned value when options.port is zero. */
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+export type WebRouteKind = 'exact' | 'prefix'
+
+/** One named route registration. */
+export interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+export interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /**
-   * Shutdown: close + closeAllConnections (SSE connections never end on their
-   * own; without the force-close, close() would hang). Idempotent.
-   */
-  close(): Promise<void>
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
 }
 
 /**
- * Start the web-shape HTTP server on the caller-selected host and port.
- * Routing: /api/* → apiHandler bridge; non-GET/HEAD → 405; everything else →
- * static with the step1-locked semantics (403 traversal, SPA fallback 200).
- * A listen failure (EADDRINUSE…) rejects — the shell decides how to exit; a
- * server error after listen goes to onError. A request whose handling throws
- * (malformed %-escapes, a client dropping mid-body) is answered 400 — or the
- * socket destroyed when headers are already out — and reported to onError;
- * it never becomes an unhandled rejection.
- * @param options - port, static root anchor, and the API carrier.
- * @param onError - sink for post-listen server errors and per-request handling failures.
- * @returns the running server handle once listening.
+ * The web-shape HTTP carrier service. Activation listens immediately (route
+ * registration order carries no request-facing semantics: named routes are
+ * composed to be disjoint, and the static dist fallback answers anything not
+ * yet claimed during the boot window). A listen failure throws out of init —
+ * a FAILED fiber the boot's fail-loud sweep reports.
  */
-export function startWebServer(options: WebServerOptions, onError: (err: Error) => void): Promise<RunningWebServer> {
-  const { host, port, distIndex, apiHandler, webPlugins } = options
-  const distRoot = dirname(distIndex)
-  const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
-    const html = await readFile(distIndex, 'utf8')
-    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
+export class HttpServerService extends Service {
+  static Config: z<Config> = z.object({
+    host: z.union([z.const('127.0.0.1'), z.const('0.0.0.0')]).required(),
+    port: z.natural().max(65535).required(),
+    distIndex: z.string().required(),
+  })
 
-  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
-    requests; the field is only optional on the client-side IncomingMessage type */
-    const rawPath = new URL(req.url ?? '/', 'http://x').pathname
-    if (rawPath.startsWith('/api/')) {
-      await bridge(req, res, apiHandler)
-      return
-    }
-    if (req.method !== 'GET' && req.method !== 'HEAD') {
-      res.writeHead(405)
-      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
-    }
-    await serveStatic(decodeURIComponent(rawPath), res, distRoot, distIndex, renderIndex)
+  private readonly exact = new Map<string, WebRoute>()
+  private readonly prefixes = new Map<string, WebRoute>()
+  private readonly indexTaps: ((html: string) => string)[] = []
+  private readonly distRoot: string
+  private readonly distIndex: string
+  private server!: Server
+  private listenedPort!: number
+
+  constructor(ctx: Context, private config: Config) {
+    super(ctx, 'httpServer')
+    this.distIndex = config.distIndex
+    this.distRoot = dirname(config.distIndex)
   }
-  // Last-resort guard: handle() rejecting would otherwise be an unhandled
-  // rejection, and one malformed request (a bad %-escape hitting
-  // decodeURIComponent, a client dropping mid-body) would kill the whole
-  // process. Nothing after this catch can throw again on the same response.
-  const server = createServer((req, res) => {
-    handle(req, res).catch((err: unknown) => {
-      onError(err instanceof Error ? err : new Error(String(err)))
-      if (res.headersSent) {
-        res.destroy()
+
+  /** The listening port (the OS-assigned value when config.port is 0). */
+  get port(): number {
+    return this.listenedPort
+  }
+
+  /**
+   * Register a named route. Duplicate (kind, path) throws — route patterns are
+   * a composition-level contract, so a collision is a misconfiguration.
+   * @param route - kind, path, and the owning handler.
+   * @returns the disposer removing the route.
+   */
+  register(route: WebRoute): () => void {
+    const table = route.kind === 'exact' ? this.exact : this.prefixes
+    if (table.has(route.path)) {
+      throw new Error(`webserver: duplicate ${route.kind} route "${route.path}"`)
+    }
+    table.set(route.path, route)
+    return () => { table.delete(route.path) }
+  }
+
+  /**
+   * Register an index.html transform, applied to every index response in
+   * registration order.
+   * @param transform - pure html-to-html function.
+   * @returns the disposer removing the transform.
+   */
+  tapIndex(transform: (html: string) => string): () => void {
+    this.indexTaps.push(transform)
+    return () => {
+      const at = this.indexTaps.indexOf(transform)
+      if (at !== -1) this.indexTaps.splice(at, 1)
+    }
+  }
+
+  /** Listen; resolves once the socket is bound (rejection = FAILED fiber). */
+  async [Service.init](): Promise<void> {
+    const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
+      requests; the field is only optional on the client-side IncomingMessage type */
+      const rawPath = new URL(req.url ?? '/', 'http://x').pathname
+      const route = this.match(rawPath)
+      if (route !== undefined) {
+        await route.handler(req, res)
         return
       }
-      res.writeHead(400)
-      res.end()
-    })
-  })
-
-  let closing: Promise<void> | undefined
-  const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
-    unsubscribeRebuilt?.()
-    server.close(() => { resolveClose() })
-    server.closeAllConnections()
-  }))
-
-  return new Promise((resolveListen, rejectListen) => {
-    server.once('error', rejectListen)
-    server.listen(port, host, () => {
-      server.off('error', rejectListen)
-      server.on('error', onError)
-      resolveListen({ port: (server.address() as AddressInfo).port, close })
-    })
-  })
-}
-
-/**
- * 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 graph - the composed entry graph from the registry.
- * @returns the html with the graph script injected.
- */
-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)}`
-  // Headless fixture pages may lack <head>; prepending keeps the read-before-shell ordering.
-  return `${script}${html}`
-}
-
-/**
- * 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> {
-  const id = pathname.slice('/plugins/'.length, -'/client.js'.length)
-  const path = webPlugins.clientPath(id)
-  if (path === undefined) {
-    res.writeHead(404)
-    res.end()
-    return
-  }
-  try {
-    const body = await readFile(path)
-    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.
-    res.writeHead(404)
-    res.end()
-  }
-}
-
-/** Bridge one node:http request to the WHATWG fetch handler (client close aborts; SSE bodies stream out chunk by chunk). */
-async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
-  const abort = new AbortController()
-  // Client-disconnect detection MUST hang off the response, not the request:
-  // since Node 16, IncomingMessage 'close' fires as soon as the request body is
-  // fully consumed (immediately for a bodyless GET), which would abort every SSE
-  // stream right after open. ServerResponse 'close' fires on connection teardown;
-  // writableEnded distinguishes a normal end() from the client going away.
-  res.on('close', () => {
-    if (!res.writableEnded) abort.abort()
-  })
-  const chunks: Buffer[] = []
-  for await (const chunk of req) chunks.push(chunk as Buffer)
-  /* v8 ignore next 3 -- `??` arms: node:http always sets url/method on server
-  requests; the fields are only optional on the client-side IncomingMessage type */
-  const request = new Request(new URL(req.url ?? '/', 'http://dsh.internal'), {
-    method: req.method ?? 'GET',
-    headers: Object.fromEntries(Object.entries(req.headers).filter(([, v]) => typeof v === 'string') as [string, string][]),
-    ...chunks.length > 0 ? { body: Buffer.concat(chunks) } : {},
-    signal: abort.signal,
-  })
-  const response = await apiHandler.fetch(request)
-  res.writeHead(response.status, Object.fromEntries(response.headers.entries()))
-  if (response.body === null) {
-    res.end()
-    return
-  }
-  for await (const chunk of response.body) {
-    // Backpressure: a false return means the socket buffer is full — wait for drain
-    // instead of buffering unboundedly (slow/suspended SSE consumers). 'close' also
-    // resolves so a mid-wait disconnect can't park this loop forever; the close
-    // handler above aborts the handler stream, which then ends the iteration.
-    if (!res.write(chunk)) {
-      await new Promise<void>((resolve) => {
-        const done = (): void => {
-          res.off('drain', done)
-          res.off('close', done)
-          resolve()
-        }
-        res.once('drain', done)
-        res.once('close', done)
-      })
+      // Static fallback keeps the pre-plugin semantics: non-GET/HEAD is 405,
+      // traversal 403, miss falls back to index.html 200 (SPA routing).
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405)
+        res.end()
+        return
+      }
+      await serveStatic(decodeURIComponent(rawPath), res, this.distRoot, this.distIndex, () => this.renderIndex())
     }
+    // Last-resort guard: handle() rejecting would otherwise be an unhandled
+    // rejection killing the process on one malformed request (bad %-escape,
+    // client dropping mid-body). Per-request failures log and answer 400 —
+    // never a process exit.
+    this.server = createServer((req, res) => {
+      handle(req, res).catch((err: unknown) => {
+        this.ctx.logger.warn(err instanceof Error ? err : new Error(String(err)))
+        if (res.headersSent) {
+          res.destroy()
+          return
+        }
+        res.writeHead(400)
+        res.end()
+      })
+    })
+
+    await new Promise<void>((resolve, reject) => {
+      this.server.once('error', reject)
+      this.server.listen(this.config.port, this.config.host, () => {
+        this.server.off('error', reject)
+        this.server.on('error', (err) => { this.ctx.logger.error(err) })
+        this.listenedPort = (this.server.address() as AddressInfo).port
+        resolve()
+      })
+    })
+
+    // close + closeAllConnections: held-open responses (SSE) never end on
+    // their own; without the force-close, close() would hang teardown.
+    this.ctx.effect(() => () => new Promise<void>((resolve) => {
+      this.server.close(() => { resolve() })
+      this.server.closeAllConnections()
+    }), 'httpServer.listen')
+  }
+
+  /** Longest-prefix-wins over the prefix table after an exact-table miss. */
+  private match(pathname: string): WebRoute | undefined {
+    const exact = this.exact.get(pathname)
+    if (exact !== undefined) return exact
+    let best: WebRoute | undefined
+    for (const [prefix, route] of this.prefixes) {
+      if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) continue
+      if (best === undefined || prefix.length > best.path.length) best = route
+    }
+    return best
+  }
+
+  /** Index body: dist index.html through the registered taps in order. */
+  private async renderIndex(): Promise<string> {
+    let html = await readFile(this.distIndex, 'utf8')
+    for (const transform of this.indexTaps) html = transform(html)
+    return html
   }
-  res.end()
 }
+
+export default HttpServerService

packages/host/webserver/src/invariant.ts

@@ -15,28 +15,30 @@ export const name = 'host-webserver-invariant'
 export const inject = ['invariants']
 
 /**
- * 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.
+ * Owned relation: route registrations and their disposers must stay
+ * symmetric — after the owning fiber of a registered route unloads, the
+ * route table must no longer answer for its path (a stale route would keep
+ * serving a disposed plugin's handler). Checked on every fiber teardown
+ * (cordis 'internal/plugin'): the service's own registry state is compared
+ * against the set of live fibers' registrations indirectly, by probing that
+ * dispose really removed the entry — the register() disposer contract.
  */
 const install: InvariantInstaller = (ctx, fail) => {
   ctx.on('internal/plugin', () => {
-    const registry = ctx.get('webPlugins') as
-      | {
-        graph(): { entries: { id: string; url: string }[] }
-        clientPath(id: string): string | undefined
-      }
+    const server = ctx.get('httpServer') as
+      | { register(route: { kind: 'exact'; path: string; handler: () => void }): () => void }
       | undefined
-    if (registry === undefined) return // carrier-only deployments never publish the registry
-    for (const row of registry.graph().entries) {
-      if (registry.clientPath(row.id) === undefined) {
-        fail(`web plugin graph row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
-      }
+    if (server === undefined) return // no webserver row in this composition
+    // Register/dispose probe on a reserved path: if dispose leaves the route
+    // behind, a second register throws the duplicate error — the asymmetry.
+    // Each register(probe)() is one register+dispose cycle, so the probe never
+    // leaves residue; a leftover from the first cycle makes the second throw.
+    const probe = { kind: 'exact' as const, path: '/__dsh_invariant_probe__', handler: () => {} }
+    try {
+      server.register(probe)()
+      server.register(probe)()
+    } catch {
+      fail('httpServer.register() disposer left the route registered — route table and fiber lifecycles diverged')
     }
   }, { global: true })
 }

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

@@ -1,56 +0,0 @@
-/**
- * `/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,360 +0,0 @@
-/**
- * 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
- * scans `loader.entries()` and rescans on cordis `internal/plugin` (fiber
- * create/dispose), microtask-debounced. Plugin-set changes take effect on
- * restart per the config-source ruling; the subscription only keeps the table
- * fresh within a process lifetime.
- */
-
-import { createHash } from 'node:crypto'
-import { readFileSync, statSync, type Stats } from 'node:fs'
-import { dirname, join } from 'node:path'
-import type { Context } from 'cordis'
-
-/** 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?rev=<rev>`). */
-  url: string
-  /** 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 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 composed entry graph (stable object between changes). */
-  graph(): WebBootGraph
-  /**
-   * 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
-  /**
-   * 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
-}
-
-/** Structural view of a loader entry (webserver keeps zero workspace dependencies; cordis stays a type-only peer). */
-export interface LoaderEntryView {
-  options: { name: string }
-  /** Present once the entry's plugin fiber exists (import succeeded and apply ran/started). */
-  fiber?: unknown
-  /** True when the entry or an owning group is disabled. */
-  disabled: boolean
-}
-
-/** Structural view of the host Loader (entry enumeration is all the registry needs). */
-export interface LoaderView {
-  entries(): Iterable<LoaderEntryView>
-}
-
-/** Dependencies injected by the assembly layer. */
-export interface WebPluginRegistryDeps {
-  /** Host root context; used only to subscribe `internal/plugin` for rescans. */
-  ctx: Context
-  /** The host Loader owning the plugin entries. */
-  loader: LoaderView
-  /**
-   * Resolve a package specifier to its package.json absolute path (assembly
-   * passes `createRequire(...).resolve(`${name}/package.json`)`); injected so
-   * the registry makes no module-resolution assumptions of its own.
-   */
-  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
-   * with an explicit stat baseline (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: WebBootEntry
-  clientPath: string
-}
-
-interface WatchedBundle {
-  path: string
-  mtimeMs: number
-  size: number
-  dirty: boolean
-}
-
-/** Narrow an unknown parsed JSON value to the dshClient declaration, throwing on malformed fields. */
-function parseDshClient(name: string, value: unknown): DshClientDeclaration | undefined {
-  if (value === undefined) return undefined
-  if (typeof value !== 'object' || value === null) {
-    throw new Error(`web-plugins: ${name} has a non-object dshClient declaration`)
-  }
-  const decl = value as Record<string, unknown>
-  if (typeof decl.platform !== 'string') {
-    throw new Error(`web-plugins: ${name} dshClient.platform must be a string`)
-  }
-  if (decl.inject !== undefined && (!Array.isArray(decl.inject) || decl.inject.some(i => typeof i !== 'string'))) {
-    throw new Error(`web-plugins: ${name} dshClient.inject must be a string array`)
-  }
-  if (decl.immediately !== undefined && typeof decl.immediately !== 'boolean') {
-    throw new Error(`web-plugins: ${name} dshClient.immediately must be a boolean`)
-  }
-  return {
-    platform: decl.platform,
-    ...(decl.inject !== undefined ? { inject: decl.inject as string[] } : {}),
-    ...(decl.immediately !== undefined ? { immediately: decl.immediately } : {}),
-  }
-}
-
-/** Resolve `exports["./client"]` to a relative path, accepting the string and one-level conditional forms. */
-function clientExportOf(name: string, exportsField: unknown): string | undefined {
-  if (typeof exportsField !== 'object' || exportsField === null) return undefined
-  const client = (exportsField as Record<string, unknown>)['./client']
-  if (client === undefined) return undefined
-  if (typeof client === 'string') return client
-  if (typeof client === 'object' && client !== null) {
-    const fallback = (client as Record<string, unknown>).default
-    if (typeof fallback === 'string') return fallback
-  }
-  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, 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)})`)
-  }
-
-  const stageWatches = (
-    candidateTable: Map<string, WebPluginRecord>,
-    currentWatches: Map<string, WatchedBundle>,
-  ): Map<string, WatchedBundle> => {
-    const candidateWatches = new Map<string, WatchedBundle>()
-    if (watchInterval === undefined) return candidateWatches
-    for (const [id, record] of candidateTable) {
-      const current = currentWatches.get(id)
-      if (current?.path === record.clientPath) {
-        candidateWatches.set(id, { ...current })
-        continue
-      }
-      const baseline = statSync(record.clientPath)
-      candidateWatches.set(id, {
-        path: record.clientPath,
-        mtimeMs: baseline.mtimeMs,
-        size: baseline.size,
-        dirty: false,
-      })
-    }
-    return candidateWatches
-  }
-
-  let table = scan(deps)
-  let graph = composeGraph(table)
-  let watched = stageWatches(table, new Map())
-  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: capture every row's baseline synchronously before the
-  // registry is returned, then poll those baselines. fs.watchFile establishes
-  // its first baseline asynchronously, so an immediate rebuild can otherwise
-  // become the baseline and disappear without an observed delta.
-  const pollWatches = (): void => {
-    for (const [id, watch] of watched) {
-      let current: Stats
-      try {
-        current = statSync(watch.path)
-      } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code
-        if (code === 'ENOENT') {
-          watch.dirty = true
-          continue
-        }
-        deps.onError(error instanceof Error ? error : new Error(String(error)))
-        continue
-      }
-      if (!watch.dirty && current.mtimeMs === watch.mtimeMs && current.size === watch.size) continue
-      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') {
-          watch.dirty = true
-          continue
-        }
-        watch.mtimeMs = current.mtimeMs
-        watch.size = current.size
-        deps.onError(error instanceof Error ? error : new Error(String(error)))
-        continue
-      }
-      watch.mtimeMs = current.mtimeMs
-      watch.size = current.size
-      watch.dirty = false
-      if (rev === undefined || rev === before) continue
-      for (const notify of rebuildListeners) {
-        // A throwing subscriber must not skip later subscribers or escape the
-        // polling callback into the process event loop.
-        try {
-          notify(id, rev)
-        } catch (error) {
-          deps.onError(error instanceof Error ? error : new Error(String(error)))
-        }
-      }
-    }
-  }
-  const watchTimer = watchInterval === undefined ? undefined : setInterval(pollWatches, watchInterval)
-  watchTimer?.unref()
-
-  let pending = false
-  const unsubscribe = deps.ctx.on('internal/plugin', () => {
-    if (pending) return
-    pending = true
-    queueMicrotask(() => {
-      pending = false
-      try {
-        const candidateTable = scan(deps)
-        const candidateGraph = composeGraph(candidateTable)
-        const candidateWatches = stageWatches(candidateTable, watched)
-        table = candidateTable
-        graph = candidateGraph
-        watched = candidateWatches
-      } catch (error) {
-        // 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)))
-      }
-    })
-  })
-
-  return {
-    graph: () => graph,
-    clientPath: id => table.get(id)?.clientPath,
-    rebuilt,
-    onRebuilt: (listener) => {
-      rebuildListeners.add(listener)
-      return () => { rebuildListeners.delete(listener) }
-    },
-    dispose: () => {
-      unsubscribe()
-      if (watchTimer !== undefined) clearInterval(watchTimer)
-      watched.clear()
-      rebuildListeners.clear()
-    },
-  }
-}
-
-/** 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()) {
-    if (entry.fiber === undefined || entry.disabled) continue
-    const name = entry.options.name
-    if (table.has(name)) continue
-    const pkgPath = deps.resolvePkgJson(name)
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
-    const decl = parseDshClient(name, pkg.dshClient)
-    if (decl === undefined || decl.platform !== 'web') continue
-    const clientRel = clientExportOf(name, pkg.exports)
-    if (clientRel === undefined) {
-      throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
-    }
-    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
-}

packages/host/webserver/tests/invariant.spec.ts

@@ -1,50 +0,0 @@
-/**
- * Webserver invariant companion: the boot-graph consistency audit — every
- * fetch-arrival graph row must resolve a clientPath, checked on fiber
- * lifecycle events against the assembly-published 'webPlugins' context key.
- */
-import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-import * as WebserverInvariant from '../src/invariant.ts'
-
-interface RegistryStub {
-  graph(): { entries: { id: string; url: string }[] }
-  clientPath(id: string): string | undefined
-}
-
-async function setup(registry?: RegistryStub): Promise<Context> {
-  const ctx = new Context()
-  await ctx.plugin(InvariantService, { enabled: true })
-  await ctx.plugin(WebserverInvariant).await()
-  if (registry !== undefined) ctx.reflect.provide('webPlugins', registry)
-  return ctx
-}
-
-/** Fire the audit trigger directly (same technique as the scope invariant
- *  spec): a synchronous emit propagates the fail() throw to the caller. */
-function trigger(ctx: Context): void {
-  ;(ctx.emit as (event: string, ...args: unknown[]) => void)('internal/plugin', ctx.fiber)
-}
-
-describe('webserver manifest invariant', () => {
-  it('stays silent without a registry (carrier-only deployment) and with a consistent table', async () => {
-    const bare = await setup()
-    expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published
-
-    const consistent = await setup({
-      graph: () => ({ entries: [{ id: 'p1', url: '/plugins/p1/client.js?rev=abc' }] }),
-      clientPath: id => id === 'p1' ? '/tmp/p1/lib/client.js' : undefined,
-    })
-    expect(() => { trigger(consistent) }).not.toThrow()
-  })
-
-  it('throws on a graph row whose bundle path no longer resolves', async () => {
-    const ctx = await setup({
-      graph: () => ({ entries: [{ id: 'ghost', url: '/plugins/ghost/client.js?rev=abc' }] }),
-      clientPath: () => undefined,
-    })
-    expect(() => { trigger(ctx) })
-      .toThrow(/graph row "ghost".*resolves no client bundle path/)
-  })
-})

packages/host/webserver/tests/web-plugins.spec.ts

@@ -1,368 +0,0 @@
-import {
-  mkdirSync,
-  mkdtempSync,
-  statSync,
-  type PathLike,
-  type Stats,
-  unlinkSync,
-  utimesSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
-import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'
-
-const fsControl = vi.hoisted(() => ({ failNextStatPath: undefined as string | undefined }))
-
-vi.mock('node:fs', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('node:fs')>()
-  return {
-    ...actual,
-    statSync: (path: PathLike): Stats => {
-      if (String(path) === fsControl.failNextStatPath) {
-        fsControl.failNextStatPath = undefined
-        throw Object.assign(new Error('staged bundle missing'), { code: 'ENOENT' })
-      }
-      return actual.statSync(path)
-    },
-  }
-})
-
-afterEach(() => {
-  fsControl.failNextStatPath = undefined
-  vi.useRealTimers()
-})
-
-/** Write a fake installed package (package.json + optional client bundle) and return its package.json path. */
-function makePkg(root: string, name: string, pkg: Record<string, unknown>, withBundle = true): string {
-  const dir = join(root, name.replaceAll('/', '__'))
-  mkdirSync(join(dir, 'lib'), { recursive: true })
-  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name, ...pkg }))
-  if (withBundle) writeFileSync(join(dir, 'lib', 'client.js'), `// bundle of ${name}`)
-  return join(dir, 'package.json')
-}
-
-const webDecl = (extra: Record<string, unknown> = {}): Record<string, unknown> => ({
-  dshClient: { inject: [], platform: 'web', ...extra },
-  exports: { '.': './lib/index.js', './client': './lib/client.js' },
-})
-
-interface Fixture {
-  deps: WebPluginRegistryDeps
-  entries: LoaderEntryView[]
-  errors: Error[]
-  ctx: Context
-  root: string
-}
-
-function makeDeps(
-  specs: { name: string; pkg: Record<string, unknown>; loaded?: boolean; disabled?: boolean; withBundle?: boolean }[],
-): Fixture {
-  const root = mkdtempSync(join(tmpdir(), 'dsh-webplugins-'))
-  const paths = new Map<string, string>()
-  const entries: LoaderEntryView[] = specs.map((spec) => {
-    paths.set(spec.name, makePkg(root, spec.name, spec.pkg, spec.withBundle ?? true))
-    return { options: { name: spec.name }, fiber: spec.loaded === false ? undefined : {}, disabled: spec.disabled ?? false }
-  })
-  const ctx = new Context()
-  const errors: Error[] = []
-  const deps: WebPluginRegistryDeps = {
-    ctx,
-    loader: { entries: () => entries },
-    resolvePkgJson: (name) => {
-      const path = paths.get(name)
-      if (path === undefined) throw new Error(`unresolvable ${name}`)
-      return path
-    },
-    onError: err => void errors.push(err),
-  }
-  return { deps, entries, errors, ctx, root }
-}
-
-describe('createHostWebPluginRegistry', () => {
-  it('discovers dshClient rows with rev-stamped urls, manifest inject edges, and the declared immediately mark', () => {
-    const { deps } = makeDeps([
-      { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
-      { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
-      { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
-    ])
-    const registry = createHostWebPluginRegistry(deps)
-    const graph = registry.graph()
-    expect(graph.rev).toMatch(/^[0-9a-f]{12}$/)
-    const connection = graph.entries[0]
-    expect(connection?.id).toBe('@deepseek-ai/dsh-client-connection')
-    expect(connection?.rev).toMatch(/^[0-9a-f]{12}$/)
-    expect(connection?.url).toBe(`/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=${connection?.rev ?? ''}`)
-    expect(connection?.immediately).toBe(true)
-    const layout = graph.entries[1]
-    expect(layout?.id).toBe('@deepseek-ai/dsh-client-ui-layout')
-    expect(layout?.inject).toEqual(['@deepseek-ai/dsh-client-runtime'])
-    expect(layout?.immediately).toBeUndefined()
-    expect(graph.entries).toHaveLength(2)
-    expect(registry.clientPath('@deepseek-ai/dsh-client-ui-layout')).toMatch(/lib[/\\]client\.js$/)
-    expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
-    registry.dispose()
-  })
-
-  it('skips entries that are unloaded, disabled, or declare another platform', () => {
-    const { deps } = makeDeps([
-      { name: 'not-loaded', pkg: webDecl(), loaded: false },
-      { name: 'disabled', pkg: webDecl(), disabled: true },
-      { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
-    ])
-    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.graph().entries).toEqual([])
-    registry.dispose()
-  })
-
-  it('fails loud at build time on a dshClient declaration without a "./client" export', () => {
-    const { deps } = makeDeps([
-      { name: 'broken', pkg: { dshClient: { platform: 'web' }, exports: { '.': './lib/index.js' } } },
-    ])
-    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
-  })
-
-  it('fails loud at build time on a registered bundle that is not built (rev hashing reads the file)', () => {
-    const { deps } = makeDeps([{ name: 'unbuilt', pkg: webDecl(), withBundle: false }])
-    expect(() => createHostWebPluginRegistry(deps)).toThrow(/ENOENT/)
-  })
-
-  it('fails loud on malformed declaration fields', () => {
-    for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
-      const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
-      expect(() => createHostWebPluginRegistry(deps)).toThrow(/dshClient/)
-    }
-  })
-
-  it('rebuilt(id) re-hashes the bundle, updates the row and graph rev, and keeps the immediately mark', () => {
-    const { deps, root } = makeDeps([{ name: 'hot', pkg: webDecl({ immediately: true }) }])
-    const registry = createHostWebPluginRegistry(deps)
-    const before = registry.graph()
-    const beforeRow = before.entries.find(e => e.id === 'hot')
-    writeFileSync(join(root, 'hot', 'lib', 'client.js'), '// rebuilt bundle contents')
-    const rev = registry.rebuilt('hot')
-    expect(rev).toMatch(/^[0-9a-f]{12}$/)
-    expect(rev).not.toBe(beforeRow?.rev)
-    const after = registry.graph()
-    const afterRow = after.entries.find(e => e.id === 'hot')
-    expect(afterRow?.rev).toBe(rev)
-    expect(afterRow?.url).toBe(`/plugins/hot/client.js?rev=${rev ?? ''}`)
-    expect(afterRow?.immediately).toBe(true)
-    expect(after.rev).not.toBe(before.rev)
-    // Unknown ids are not rebuildable.
-    expect(registry.rebuilt('nope')).toBeUndefined()
-    registry.dispose()
-  })
-
-  it('watch mode: a bundle content change re-hashes the row and notifies onRebuilt; dispose stops the watch', async () => {
-    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
-    deps.watch = { intervalMs: 20 }
-    const registry = createHostWebPluginRegistry(deps)
-    const before = registry.graph().entries[0]?.rev
-    const rebuilds: { id: string; rev: string }[] = []
-    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
-
-    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// new bundle contents')
-    await vi.waitFor(() => { expect(rebuilds).toHaveLength(1) }, { timeout: 5000 })
-    expect(rebuilds[0]?.id).toBe('watched')
-    expect(rebuilds[0]?.rev).not.toBe(before)
-    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
-
-    registry.dispose()
-    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// post-dispose contents')
-    await new Promise((resolve) => { setTimeout(resolve, 100) })
-    expect(rebuilds).toHaveLength(1)
-  })
-
-  it('watch mode: a write landing during registry construction is still detected (regression: fs.watchFile baseline absorption)', async () => {
-    // The old fs.watchFile watch captured its comparison baseline with an
-    // ASYNCHRONOUS first stat; a rewrite in the same tick as construction was
-    // absorbed into that baseline and never reported (the CI flake). The
-    // synchronous stageWatches baseline stats before the registry returns, so
-    // this exact timing must now always notify.
-    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
-    deps.watch = { intervalMs: 20 }
-    const registry = createHostWebPluginRegistry(deps)
-    const rebuilds: string[] = []
-    registry.onRebuilt(id => rebuilds.push(id))
-    // Same tick as construction — inside the old watch's blind window. The
-    // rewrite deliberately differs in SIZE from the seed: a same-millisecond
-    // same-size rewrite is invisible to any mtime+size poll by construction
-    // (coarse filesystem timestamps), which is a stat-polling limit, not the
-    // regression under test.
-    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// same-tick rewritten contents')
-    await vi.waitFor(() => { expect(rebuilds).toEqual(['watched']) }, { timeout: 5000 })
-    registry.dispose()
-  })
-
-  it('watch mode: a failed rescan baseline preserves the published table and graph', async () => {
-    const { deps, entries, errors, ctx, root } = makeDeps([
-      { name: 'stable', pkg: webDecl() },
-      { name: 'late', pkg: webDecl(), loaded: false },
-    ])
-    deps.watch = { intervalMs: 1_000 }
-    const registry = createHostWebPluginRegistry(deps)
-    const before = registry.graph()
-
-    ;(entries[1] as { fiber?: unknown }).fiber = {}
-    fsControl.failNextStatPath = join(root, 'late', 'lib', 'client.js')
-    ctx.emit('internal/plugin', ctx.fiber)
-    await Promise.resolve()
-
-    expect(errors[0]?.message).toContain('staged bundle missing')
-    expect(registry.graph()).toBe(before)
-    expect(registry.clientPath('late')).toBeUndefined()
-
-    ctx.emit('internal/plugin', ctx.fiber)
-    await Promise.resolve()
-    expect(registry.graph().entries.map(row => row.id)).toEqual(['stable', 'late'])
-    registry.dispose()
-  })
-
-  it('watch mode: a missing bundle forces a re-hash when identical metadata reappears', async () => {
-    vi.useFakeTimers()
-    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
-    const bundle = join(root, 'watched', 'lib', 'client.js')
-    const fixedTime = new Date(1_600_000_000_000)
-    utimesSync(bundle, fixedTime, fixedTime)
-    deps.watch = { intervalMs: 20 }
-    const registry = createHostWebPluginRegistry(deps)
-    const baseline = statSync(bundle)
-    const rebuilds: { id: string; rev: string }[] = []
-    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
-
-    unlinkSync(bundle)
-    await vi.advanceTimersByTimeAsync(20)
-    writeFileSync(bundle, 'x'.repeat(baseline.size))
-    utimesSync(bundle, fixedTime, fixedTime)
-    const restored = statSync(bundle)
-    expect({ mtimeMs: restored.mtimeMs, size: restored.size }).toEqual({
-      mtimeMs: baseline.mtimeMs,
-      size: baseline.size,
-    })
-    await vi.advanceTimersByTimeAsync(20)
-
-    expect(rebuilds).toHaveLength(1)
-    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
-    registry.dispose()
-  })
-
-  it('rejects a non-positive or non-integer watch interval at build time', () => {
-    for (const intervalMs of [0, -5, 1.5]) {
-      const { deps } = makeDeps([{ name: 'p', pkg: webDecl() }])
-      deps.watch = { intervalMs }
-      expect(() => createHostWebPluginRegistry(deps)).toThrow(/watch\.intervalMs/)
-    }
-  })
-
-  it('rescans on internal/plugin (debounced) and keeps the old graph when a rescan fails', async () => {
-    const { deps, entries, errors, ctx } = makeDeps([
-      { name: 'late-loader', pkg: webDecl(), loaded: false },
-    ])
-    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.graph().entries).toEqual([])
-
-    // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
-    ;(entries[0] as { fiber?: unknown }).fiber = {}
-    ctx.emit('internal/plugin', ctx.fiber)
-    ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
-    await Promise.resolve()
-    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
-
-    // A failing rescan reports the error and keeps serving the previous graph.
-    entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
-    ctx.emit('internal/plugin', ctx.fiber)
-    await Promise.resolve()
-    expect(errors).toHaveLength(1)
-    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
-
-    // After dispose, further fiber events no longer rescan.
-    registry.dispose()
-    entries.pop()
-    ctx.emit('internal/plugin', ctx.fiber)
-    await Promise.resolve()
-    expect(errors).toHaveLength(1)
-  })
-})
-
-describe('injectBootManifest', () => {
-  it('injects the graph as the first script inside <head> and escapes </script> breakouts', () => {
-    const html = '<html><head><script src="app.js"></script></head><body></body></html>'
-    const out = injectBootManifest(html, {
-      rev: 'r1',
-      entries: [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js?rev=r2', rev: 'r2' }],
-    })
-    expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
-    expect(out).not.toContain('</script><script>alert(1)')
-    expect(out).toContain('\\u003c/script')
-  })
-
-  it('prepends when the page has no <head>', () => {
-    const out = injectBootManifest('<body>x</body>', { rev: 'r0', entries: [] })
-    expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
-  })
-})
-
-describe('clientExportOf shapes (through the registry build)', () => {
-  it('accepts the conditional {types, default} export form', () => {
-    const { deps } = makeDeps([{
-      name: 'conditional',
-      pkg: {
-        dshClient: { platform: 'web' },
-        exports: { './client': { types: './lib/types/client/index.d.ts', default: './lib/client.js' } },
-      },
-    }])
-    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.clientPath('conditional')).toMatch(/lib[/\\]client\.js$/)
-    registry.dispose()
-  })
-
-  it('rejects a conditional form without a string default, an array form, and a non-object exports field', () => {
-    for (const exportsField of [
-      { './client': { types: './x.d.ts' } },
-      { './client': ['./a.js'] },
-    ]) {
-      const { deps } = makeDeps([{ name: 'bad-shape', pkg: { dshClient: { platform: 'web' }, exports: exportsField } }])
-      expect(() => createHostWebPluginRegistry(deps)).toThrow(/unsupported shape/)
-    }
-    // Non-object exports: treated as "no ./client export" → the declares-but-no-bundle throw.
-    const { deps } = makeDeps([{ name: 'no-exports', pkg: { dshClient: { platform: 'web' }, exports: './single.js' } }])
-    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
-  })
-
-  it('skips duplicate loader entries for the same package name (first wins)', () => {
-    const { deps, entries } = makeDeps([{ name: 'dup-entry', pkg: webDecl() }])
-    const first = entries[0] as LoaderEntryView
-    entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
-    void first
-    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.graph().entries.filter(r => r.id === 'dup-entry')).toHaveLength(1)
-    registry.dispose()
-  })
-
-  it('rejects a null conditional form and wraps a non-Error rescan throw', async () => {
-    // client: null → the object-form branch's null guard.
-    const nulled = makeDeps([{ name: 'null-client', pkg: { dshClient: { platform: 'web' }, exports: { './client': null } } }])
-    expect(() => createHostWebPluginRegistry(nulled.deps)).toThrow(/unsupported shape/)
-
-    // Non-Error rescan throw: resolvePkgJson throws a string; onError must get a wrapped Error.
-    const { deps, entries, errors, ctx } = makeDeps([{ name: 'ok-one', pkg: webDecl() }])
-    const registry = createHostWebPluginRegistry(deps)
-    entries.push({ options: { name: 'ghost-two' }, fiber: {}, disabled: false })
-    const original = deps.resolvePkgJson
-    deps.resolvePkgJson = (name) => {
-
-      if (name === 'ghost-two') throw 'string failure'
-      return original(name)
-    }
-    ctx.emit('internal/plugin', ctx.fiber)
-    await Promise.resolve()
-    expect(errors[0]).toBeInstanceOf(Error)
-    expect(String(errors[0])).toContain('string failure')
-    registry.dispose()
-  })
-
-})

packages/host/webserver/tests/webserver.spec.ts

@@ -1,400 +0,0 @@
-import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
-import { Server as NetServer } from 'node:net'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { startWebServer, type RunningWebServer } from '../src/index.ts'
-
-/** dist fixture: index.html + one asset of each MIME class + a subdir. */
-function makeDist(): { distIndex: string; distRoot: string } {
-  const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
-  writeFileSync(join(distRoot, 'index.html'), '<html>INDEX</html>')
-  writeFileSync(join(distRoot, 'app.js'), 'console.log(1)')
-  writeFileSync(join(distRoot, 'app.css'), 'body{}')
-  writeFileSync(join(distRoot, 'logo.svg'), '<svg/>')
-  writeFileSync(join(distRoot, 'data.json'), '{}')
-  writeFileSync(join(distRoot, 'app.js.map'), '{}')
-  writeFileSync(join(distRoot, 'blob.bin'), 'BIN')
-  mkdirSync(join(distRoot, 'sub'))
-  writeFileSync(join(distRoot, 'sub', 'page.html'), '<html>SUB</html>')
-  return { distIndex: join(distRoot, 'index.html'), distRoot }
-}
-
-const echoingApi = {
-  fetch: async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-    const req = input instanceof Request ? input : new Request(input, init)
-    if (req.url.endsWith('/api/echo')) {
-      return Response.json({ method: req.method, body: await req.text(), header: req.headers.get('x-probe') })
-    }
-    if (req.url.endsWith('/api/empty')) return new Response(null, { status: 204 })
-    if (req.url.endsWith('/api/big')) {
-      // Chunks far above any socket highWaterMark force res.write to return false.
-      const big = new Uint8Array(4 * 1024 * 1024).fill(65)
-      const stream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          controller.enqueue(big)
-          controller.enqueue(big)
-          controller.close()
-        },
-      })
-      return new Response(stream, { headers: { 'content-type': 'application/octet-stream' } })
-    }
-    if (req.url.endsWith('/api/sse')) {
-      const encoder = new TextEncoder()
-      const stream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          controller.enqueue(encoder.encode('data: one\n\n'))
-          controller.enqueue(encoder.encode('data: two\n\n'))
-          controller.close()
-        },
-      })
-      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
-    }
-    if (req.url.endsWith('/api/throw-string')) {
-      // Non-Error rejection: the guard must wrap it for onError.
-      throw 'string failure'
-    }
-    if (req.url.endsWith('/api/explode-mid-stream')) {
-      // Headers go out with the first chunk, then the source errors: the
-      // guard's headersSent leg must destroy the socket, not writeHead again.
-      // The error is deferred a tick so the 200 + first chunk actually flush
-      // to the client before the teardown.
-      const stream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          controller.enqueue(new TextEncoder().encode('data: first\n\n'))
-          setTimeout(() => { controller.error(new Error('stream exploded')) }, 20)
-        },
-      })
-      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
-    }
-    if (req.url.endsWith('/api/abort-probe')) {
-      // Endless SSE that only ends when the request signal aborts.
-      const stream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          req.signal.addEventListener('abort', () => {
-            try {
-              controller.close()
-            } catch { /* already closed by teardown: nothing else can reach this */ }
-          }, { once: true })
-          controller.enqueue(new TextEncoder().encode('data: open\n\n'))
-        },
-      })
-      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
-    }
-    return new Response('nope', { status: 404 })
-  },
-}
-
-let server: RunningWebServer | undefined
-
-afterEach(async () => {
-  await server?.close()
-  server = undefined
-})
-
-async function boot(onError: (err: Error) => void = () => undefined): Promise<string> {
-  const { distIndex } = makeDist()
-  server = await startWebServer({ host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi }, onError)
-  return `http://127.0.0.1:${String(server.port)}`
-}
-
-describe('startWebServer', () => {
-  it('reports the listening port and closes idempotently', async () => {
-    const { distIndex } = makeDist()
-    server = await startWebServer({ host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi }, () => undefined)
-    expect(server.port).toBeGreaterThan(0)
-    const first = server.close()
-    const second = server.close()
-    expect(second).toBe(first)
-    await first
-    server = undefined
-  })
-
-  it.each(['127.0.0.1', '0.0.0.0'])('forwards bind address %s without opening a socket', async (host) => {
-    const { distIndex } = makeDist()
-    const port = 3080
-    const listen = vi.spyOn(NetServer.prototype, 'listen').mockImplementation(function (
-      this: NetServer, ...args: unknown[]
-    ): NetServer {
-      const callback = args.at(-1)
-      if (typeof callback !== 'function') throw new TypeError('listen callback missing')
-      queueMicrotask(callback as () => void)
-      return this
-    })
-    const address = vi.spyOn(NetServer.prototype, 'address').mockReturnValue({ address: host, family: 'IPv4', port })
-    try {
-      const inertServer = await startWebServer({ host, port, distIndex, apiHandler: echoingApi }, () => undefined)
-      expect(listen).toHaveBeenCalledWith(port, host, expect.any(Function))
-      await inertServer.close()
-    } finally {
-      address.mockRestore()
-      listen.mockRestore()
-    }
-  })
-
-  it('rejects when the port is already taken', async () => {
-    const { distIndex } = makeDist()
-    server = await startWebServer({ host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi }, () => undefined)
-    const { port } = server
-    await expect(startWebServer({ host: '127.0.0.1', port, distIndex, apiHandler: echoingApi }, () => undefined))
-      .rejects.toMatchObject({ code: 'EADDRINUSE' })
-  })
-})
-
-describe.skipIf(process.platform === 'win32')('static serving', () => {
-  it('serves index at /, subpaths by MIME, octet-stream for unknown, SPA fallback on miss', async () => {
-    const base = await boot()
-    const index = await fetch(`${base}/`)
-    expect(index.status).toBe(200)
-    expect(index.headers.get('content-type')).toBe('text/html; charset=utf-8')
-    expect(await index.text()).toBe('<html>INDEX</html>')
-
-    expect((await fetch(`${base}/app.js`)).headers.get('content-type')).toBe('text/javascript; charset=utf-8')
-    expect((await fetch(`${base}/app.css`)).headers.get('content-type')).toBe('text/css; charset=utf-8')
-    expect((await fetch(`${base}/logo.svg`)).headers.get('content-type')).toBe('image/svg+xml')
-    expect((await fetch(`${base}/data.json`)).headers.get('content-type')).toBe('application/json')
-    expect((await fetch(`${base}/app.js.map`)).headers.get('content-type')).toBe('application/json')
-    expect((await fetch(`${base}/blob.bin`)).headers.get('content-type')).toBe('application/octet-stream')
-    expect(await (await fetch(`${base}/sub/page.html`)).text()).toBe('<html>SUB</html>')
-
-    const miss = await fetch(`${base}/routes/deep/link`)
-    expect(miss.status).toBe(200)
-    expect(await miss.text()).toBe('<html>INDEX</html>')
-  })
-
-  it('403s traversal outside the dist root and 405s non-GET/HEAD', async () => {
-    const base = await boot()
-    // %2e%2e would be dot-collapsed by WHATWG URL parsing on both ends; an
-    // encoded slash keeps the segment intact until the server's decodeURIComponent.
-    const traversal = await fetch(`${base}/..%2f..%2fetc%2fpasswd`)
-    expect(traversal.status).toBe(403)
-    const put = await fetch(`${base}/index.html`, { method: 'PUT', body: 'x' })
-    expect(put.status).toBe(405)
-  })
-
-  it('answers HEAD like GET (no 405)', async () => {
-    const base = await boot()
-    const head = await fetch(`${base}/`, { method: 'HEAD' })
-    expect(head.status).toBe(200)
-  })
-})
-
-describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint + events channel)', () => {
-  const FETCH_ID = '@deepseek-ai/dsh-client-ui-layout'
-  const graphValue = {
-    rev: 'graphrev00001',
-    entries: [
-      { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=eeee2222ffff', rev: 'eeee2222ffff', immediately: true },
-      { id: FETCH_ID, url: `/plugins/${FETCH_ID}/client.js?rev=aaaa0000bbbb`, rev: 'aaaa0000bbbb', inject: [] },
-    ],
-  }
-
-  /** Captures the server's onRebuilt subscription so tests can fire registry notifications by hand. */
-  interface RebuiltHarness {
-    notify: (id: string, rev: string) => void
-    unsubscribed: boolean
-  }
-
-  async function bootWithPlugins(harness?: RebuiltHarness): Promise<string> {
-    const { distIndex, distRoot } = makeDist()
-    writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
-    const webPlugins = {
-      graph: () => graphValue,
-      clientPath: (id: string) => id === FETCH_ID ? join(distRoot, 'bundle.js') : undefined,
-      onRebuilt: (listener: (id: string, rev: string) => void) => {
-        if (harness !== undefined) harness.notify = listener
-        return () => {
-          if (harness !== undefined) harness.unsubscribed = true
-        }
-      },
-    }
-    server = await startWebServer(
-      { host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
-    )
-    return `http://127.0.0.1:${String(server.port)}`
-  }
-
-  it('injects the window.__DSH_BOOT__ graph into / and SPA fallbacks; asset requests stay verbatim', async () => {
-    const base = await bootWithPlugins()
-    const index = await (await fetch(`${base}/`)).text()
-    expect(index).toContain('window.__DSH_BOOT__')
-    const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
-    expect(JSON.parse(manifest ?? '')).toEqual(graphValue)
-
-    const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
-    expect(fallback).toContain('window.__DSH_BOOT__')
-    const direct = await (await fetch(`${base}/index.html`)).text()
-    expect(direct).toContain('window.__DSH_BOOT__')
-
-    expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
-  })
-
-  it('serves registered client bundles with no-cache (rev query ignored) and 404s unknown ids (no SPA fallback)', async () => {
-    const base = await bootWithPlugins()
-    const bundle = await fetch(`${base}/plugins/${FETCH_ID}/client.js?rev=whatever`)
-    expect(bundle.status).toBe(200)
-    expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
-    expect(bundle.headers.get('cache-control')).toBe('no-cache')
-    expect(await bundle.text()).toContain('DSHClientProxy')
-
-    expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
-  })
-
-  it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
-    const { distIndex } = makeDist()
-    const webPlugins = {
-      graph: () => graphValue,
-      clientPath: () => '/nonexistent/lib/client.js',
-      onRebuilt: () => () => undefined,
-    }
-    server = await startWebServer(
-      { host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined,
-    )
-    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/${FETCH_ID}/client.js`)
-    expect(res.status).toBe(404)
-  })
-
-  it('keeps all plugin surfaces off without the webPlugins option', async () => {
-    const base = await boot()
-    expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
-    // No plugin routes: fall through to static SPA fallback semantics.
-    const res = await fetch(`${base}/plugins/x/client.js`)
-    expect(res.status).toBe(200)
-    expect(await res.text()).toBe('<html>INDEX</html>')
-    const events = await fetch(`${base}/plugins/events`)
-    expect(await events.text()).toBe('<html>INDEX</html>')
-  })
-
-  it('GET /plugins/events opens SSE with the current graph frame; a registry rebuild notification broadcasts', async () => {
-    const harness: RebuiltHarness = { notify: () => { throw new Error('onRebuilt never subscribed') }, unsubscribed: false }
-    const base = await bootWithPlugins(harness)
-    const events = await fetch(`${base}/plugins/events`)
-    expect(events.status).toBe(200)
-    expect(events.headers.get('content-type')).toBe('text/event-stream')
-    const reader = events.body?.getReader()
-    const decoder = new TextDecoder()
-    let buffer = ''
-    async function readUntil(marker: string): Promise<void> {
-      while (!buffer.includes(marker)) {
-        const chunk = await reader?.read()
-        if (chunk?.done !== false) throw new Error('SSE stream ended early')
-        buffer += decoder.decode(chunk.value, { stream: true })
-      }
-    }
-    await readUntil('"type":"graph"')
-    expect(buffer).toContain(': connected')
-    const graphLine = /data: (.*)\n\n/.exec(buffer)?.[1]
-    expect(JSON.parse(graphLine ?? '')).toEqual({ type: 'graph', graph: graphValue })
-
-    // The registry's bundle watch observed a rebuild: the server relays it as an SSE frame.
-    harness.notify(FETCH_ID, 'cccc1111dddd')
-    await readUntil('"type":"rebuilt"')
-    expect(buffer).toContain(JSON.stringify({ type: 'rebuilt', id: FETCH_ID, rev: 'cccc1111dddd' }))
-    await reader?.cancel()
-
-    // Shutdown unsubscribes the relay (no broadcast into a closed channel).
-    await server?.close()
-    server = undefined
-    expect(harness.unsubscribed).toBe(true)
-  })
-})
-
-describe('request-handling guard (one bad request must not kill the process)', () => {
-  it('400s malformed %-escapes, reports to onError, and stays alive', async () => {
-    const errors: Error[] = []
-    const base = await boot(err => errors.push(err))
-    for (const path of ['/%', '/%c0', '/%zz%']) {
-      expect((await fetch(`${base}${path}`)).status).toBe(400)
-    }
-    expect(errors.length).toBe(3)
-    expect(errors[0]?.name).toBe('URIError')
-    // The barrage left the server serving.
-    expect((await fetch(`${base}/`)).status).toBe(200)
-  })
-
-  it('wraps a non-Error throw for onError and still answers 400', async () => {
-    const errors: Error[] = []
-    const base = await boot(err => errors.push(err))
-    expect((await fetch(`${base}/api/throw-string`, { method: 'POST' })).status).toBe(400)
-    expect(errors[0]).toBeInstanceOf(Error)
-    expect(errors[0]?.message).toBe('string failure')
-  })
-
-  it('destroys the socket when the failure lands after headers went out', async () => {
-    const errors: Error[] = []
-    const base = await boot(err => errors.push(err))
-    const response = await fetch(`${base}/api/explode-mid-stream`)
-    expect(response.status).toBe(200) // headers made it out before the explosion
-    await expect(response.text()).rejects.toThrow() // then the socket is torn down
-    expect(errors.length).toBe(1)
-    expect((await fetch(`${base}/`)).status).toBe(200)
-  })
-})
-
-describe('/api bridge', () => {
-  it('forwards method, headers, and body; relays status and body back', async () => {
-    const base = await boot()
-    const response = await fetch(`${base}/api/echo`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', 'x-probe': 'p1' },
-      body: JSON.stringify({ n: 1 }),
-    })
-    expect(response.status).toBe(200)
-    expect(await response.json()).toEqual({ method: 'POST', body: '{"n":1}', header: 'p1' })
-  })
-
-  it('relays a bodyless response', async () => {
-    const base = await boot()
-    const response = await fetch(`${base}/api/empty`, { method: 'POST' })
-    expect(response.status).toBe(204)
-    expect(await response.text()).toBe('')
-  })
-
-  it('streams SSE frames through chunk by chunk', async () => {
-    const base = await boot()
-    const response = await fetch(`${base}/api/sse`)
-    expect(response.headers.get('content-type')).toBe('text/event-stream')
-    expect(await response.text()).toBe('data: one\n\ndata: two\n\n')
-  })
-
-  it('waits for drain when a streamed chunk overfills the socket buffer', async () => {
-    // 4 MiB chunks dwarf the socket highWaterMark, so res.write returns false
-    // and the bridge parks on 'drain'; reading the body to completion proves
-    // the loop resumed instead of dropping the remainder.
-    const base = await boot()
-    const response = await fetch(`${base}/api/big`)
-    const body = new Uint8Array(await response.arrayBuffer())
-    expect(body.length).toBe(8 * 1024 * 1024)
-    expect(body[0]).toBe(65)
-    expect(body[body.length - 1]).toBe(65)
-  })
-
-  it('releases a drain wait when the client disconnects mid-chunk', async () => {
-    // The 'close' leg of the drain race: abort while the socket buffer is
-    // still full so the parked write wakes via 'close', not 'drain'.
-    const base = await boot()
-    const ac = new AbortController()
-    const response = await fetch(`${base}/api/big`, { signal: ac.signal })
-    const reader = response.body?.getReader()
-    const first = await reader?.read()
-    expect(first?.value?.length).toBeGreaterThan(0)
-    ac.abort()
-    // afterEach close() completing is the leak assertion, same as abort-probe.
-    await new Promise((resolve) => { setTimeout(resolve, 50) })
-  })
-
-  it('aborts the bridged request when the client disconnects mid-SSE', async () => {
-    const base = await boot()
-    const ac = new AbortController()
-    const response = await fetch(`${base}/api/abort-probe`, { signal: ac.signal })
-    const reader = response.body?.getReader()
-    expect(reader).toBeDefined()
-    const first = await reader?.read()
-    expect(new TextDecoder().decode(first?.value)).toContain('open')
-    ac.abort()
-    // server-side abort propagation has no client-observable handshake beyond
-    // the closed connection; close() would hang on a leaked live SSE socket,
-    // so afterEach completing IS the assertion that the bridge released it.
-    await new Promise((resolve) => { setTimeout(resolve, 50) })
-  })
-})

packages/host/webserver/tsconfig.json

@@ -11,6 +11,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../support/invariants"
     }

packages/storage/README.md

@@ -0,0 +1,12 @@
+# storage/ — non-session storage family
+
+The storage family persists everything that is not a session event log: a hub where named backends and typed data forms meet. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+| Package | Role | ctx key |
+|---|---|---|
+| `storage/` | The hub: named backend registry + merge-extensible data-form mounts, backend facet vocabulary, shared conformance suite | `ctx.storage` |
+| `storage-json/` | JSON backend: one human-readable file per unit, atomic whole-file rewrite | registers backend `json` |
+| `storage-sqlite/` | SQLite backend: one database hosting all routed units, document-per-row | registers backend `sqlite` |
+| `domain/` | Domain data form: zod-validated records, per-domain write chain, `domain/changed` events, backend routing by configuration | mounts `ctx.storage.domain` |
+
+Backends own one medium each and expose data-shape **facets** (`kv` today; an append-log facet is reserved for the future session-backend migration). Consumers never touch backends directly — they open declared domains through the domain form.

packages/storage/storage-domain/README.md

@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-storage-domain
+
+Domain data form for the DeepSeek Harness storage hub: mounts `ctx.storage.domain`, opening schema-validated KV domains over configured storage backends. A domain is declared once with `defineDomain` (zod record schemas, `z.infer`-derived types), opened through `DomainFacility.open`, and served from authoritative in-memory state — reads are synchronous, writes serialize on one per-domain chain, reach durability on the routed backend first, then update memory and emit `domain/changed`. The opening consumer owns the handle's lifecycle and releases it with `Domain.close()` (idempotent; typically its own `ctx.effect` disposer); domains still open when the plugin unmounts are closed by the facility.
+
+Design rationale, open semantics, and the storage/domain layer split live in the [Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Configuration
+
+| key | meaning |
+| --- | --- |
+| `backend` | Default backend name for every domain (required; no universally correct medium exists). |
+| `routes` | Per-domain overrides: domain name → backend name. |
+
+## Model Experience
+
+### Durable domain state
+
+#### What the model sees
+
+Nothing. The package registers no tools, injects no prompts, and appends no session events; it stores non-session data (workspace records, future session sidecars) behind `ctx.storage.domain` and emits only the in-process `domain/changed` event, which reaches a model only if a consumer package renders it through its own documented surface.
+
+#### Token effect
+
+Zero. No text from this package enters any model request.
+
+#### KV Cache effect
+
+Independent: domain reads and writes never touch request prefixes, so nothing here can invalidate provider cache reuse.
+
+## Known Limitations and Deferred Work
+
+- **Single-process change visibility** — `domain/changed` is an in-process event; a second host process or a reconnecting GUI observes no changes until the cross-process revision pattern deferred in the Agent Note lands.
+- **No cross-table transactions, secondary indexes, or multi-segment keys** — each write touches one record; triggers and rework points for these extensions are tabled in the Agent Note's deferred-work list.

packages/storage/storage-domain/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-storage-domain",
+  "description": "Domain data form (ctx.storage.domain): schema-validated, event-emitting KV domains over storage backends for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/storage/storage-domain/src/domain.ts

@@ -0,0 +1,357 @@
+/**
+ * Runtime of one open domain: authoritative in-memory state, the single
+ * per-domain write chain, and change-event emission. Reads are synchronous
+ * from memory; every write queues on the chain, awaits backend durability
+ * FIRST, then mutates memory, then emits `domain/changed` — a rejected
+ * backend write leaves memory untouched (no divergence between reads and the
+ * medium), and events carry values that equal the in-memory state at
+ * emission, in write order.
+ * @module @deepseek-ai/dsh-storage-domain/src/domain
+ */
+
+import type { Context } from 'cordis'
+import type { KvUnit } from '@deepseek-ai/dsh-storage'
+import { DomainError } from './error.ts'
+import type { DomainSpec, DomainGlobalSpec, TableKeyOf, TableValueOf } from './spec.ts'
+import type { DomainChanged } from './events.ts'
+
+/** Handle on a domain's global singleton. */
+export interface DomainGlobal<G> {
+  /**
+   * Current value, synchronously from the authoritative in-memory state.
+   * Before the first `set` this is the spec's `initial`.
+   * @returns the current global value.
+   */
+  get(): G
+
+  /**
+   * Replace the value durably. Queued on the domain's write chain; the first
+   * `set` is what materializes the global on the medium.
+   * @param value - New value; must satisfy the spec's schema (not re-checked
+   * here — validation happens at the durable read boundary).
+   * @returns resolution after durability and event emission.
+   */
+  set(value: G): Promise<void>
+}
+
+/**
+ * Handle on one declared table. Records are plain immutable data: returned
+ * values are the stored objects themselves (no defensive copies) and must not
+ * be mutated in place — replace via `put`/`update`.
+ */
+export interface KvTable<K extends string, V> {
+  /**
+   * Read one record, synchronously from memory.
+   * @param key - Record key.
+   * @returns the record, or `undefined` when absent.
+   */
+  get(key: K): V | undefined
+
+  /**
+   * Snapshot iterator over `[key, record]` pairs. A snapshot, not a live
+   * view: iteration stays stable while queued writes land.
+   * @returns the pair iterator.
+   */
+  entries(): IterableIterator<[K, V]>
+
+  /**
+   * Snapshot iterator over keys.
+   * @returns the key iterator.
+   */
+  keys(): IterableIterator<K>
+
+  /** Current record count. */
+  readonly size: number
+
+  /**
+   * Insert or overwrite one record durably.
+   * @param key - Record key.
+   * @param value - The full new record (no partial merge).
+   * @returns resolution after durability and event emission.
+   */
+  put(key: K, value: V): Promise<void>
+
+  /**
+   * Delete one record durably.
+   * @param key - Record key.
+   * @returns `true` when the record existed, `false` when it was already
+   * absent (no write and no event in that case).
+   */
+  delete(key: K): Promise<boolean>
+
+  /**
+   * Atomic read-modify-write on the domain's write chain: `fn` sees the
+   * value current at its queue slot, so concurrent updates never interleave.
+   * @param key - Record key; a missing key rejects with `missing-key`.
+   * @param fn - Synchronous pure transform from current to next record.
+   * @returns the stored next record.
+   */
+  update(key: K, fn: (current: V) => V): Promise<V>
+}
+
+/** Global handle of a spec: typed when declared, `never` (inaccessible) when not. */
+export type DomainGlobalHandleOf<S extends DomainSpec> =
+  S extends { readonly global: DomainGlobalSpec<infer G> } ? DomainGlobal<G> : never
+
+/** One open domain, typed by its spec. */
+export interface Domain<S extends DomainSpec> {
+  /** Domain name from the spec. */
+  readonly name: string
+  /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
+  readonly global: DomainGlobalHandleOf<S>
+  /**
+   * Resolve one declared table handle. Handles are stable — repeated calls
+   * return the same instance.
+   * @param name - Declared table name.
+   * @returns the typed table handle.
+   */
+  table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), release the backend unit, then free
+   * the domain name for a later open. Idempotent — repeated calls share one
+   * teardown. The consumer owns this call (typically as its own `ctx.effect`
+   * disposer); the facility closes any domain left open when it unmounts.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}
+
+/** Internal seam handing table handles their domain-owned write machinery. */
+interface TableHost {
+  readonly domainName: string
+  readonly unit: KvUnit
+  /** Queue one job on the domain's single write chain. */
+  enqueue<T>(job: () => Promise<T>): Promise<T>
+  /** Throw `closed` once the domain has fully closed (reads stay valid while draining). */
+  assertReadable(): void
+  /** Emit `domain/changed` for one durably landed write. */
+  emitChanged(change: DomainChanged): void
+}
+
+const noop = () => {}
+
+/**
+ * The single domain implementation behind the {@link Domain} interface. The
+ * facility constructs it from a validated `loadAll` snapshot and erases it to
+ * `Domain<S>`; nothing outside this package constructs one.
+ */
+export class DomainImpl {
+  /** Domain name from the spec. */
+  readonly name: string
+
+  private readonly tables = new Map<string, KvTableImpl<string, unknown>>()
+  private globalValue: unknown
+  private readonly globalHandle?: DomainGlobal<unknown>
+
+  /** Tail of the write chain; every link settles (rejections are observed by the caller's slice). */
+  private chain: Promise<void> = Promise.resolve()
+  /** Set when close begins: new writes reject while already-queued writes drain. */
+  private disposing = false
+  /** Set when close finishes (chain drained, unit closed): reads reject from here on. */
+  private closed = false
+  private disposal?: Promise<void>
+
+  /**
+   * @param ctx - Context that carries `domain/changed` emissions.
+   * @param spec - The domain declaration.
+   * @param unit - The opened backend unit; this instance owns its lifecycle.
+   * @param records - Validated records from the unit's `loadAll`, one entry
+   * per declared table (empty maps included) — the facility builds it from
+   * the spec, so the entry set IS the table set.
+   * @param globalValue - Validated stored global, or the spec's `initial`
+   * when the medium held none; `undefined` when the spec declares no global.
+   * @param onClosed - Facility hook run once after teardown completes; frees
+   * the domain name for a later open.
+   */
+  constructor(
+    private readonly ctx: Context,
+    spec: DomainSpec,
+    private readonly unit: KvUnit,
+    records: Map<string, Map<string, unknown>>,
+    globalValue: unknown,
+    private readonly onClosed: () => void,
+  ) {
+    this.name = spec.name
+    const host: TableHost = {
+      domainName: spec.name,
+      unit,
+      enqueue: job => this.enqueue(job),
+      assertReadable: () => { this.assertReadable() },
+      emitChanged: (change) => { this.emitChanged(change) },
+    }
+    for (const [table, tableRecords] of records) {
+      this.tables.set(table, new KvTableImpl(host, table, tableRecords))
+    }
+    if (spec.global !== undefined) {
+      this.globalValue = globalValue
+      this.globalHandle = {
+        get: () => {
+          this.assertReadable()
+          return this.globalValue
+        },
+        set: value => this.enqueue(async () => {
+          await this.unit.setGlobal(value)
+          this.globalValue = value
+          this.emitChanged({ domain: this.name, table: '', key: '', operation: 'put', value })
+        }),
+      }
+    }
+  }
+
+  /** Global singleton handle; accessing it on a spec that declares no global is a caller bug and throws. */
+  get global(): DomainGlobal<unknown> {
+    if (this.globalHandle === undefined) {
+      throw new Error(`domain '${this.name}' declares no global`)
+    }
+    return this.globalHandle
+  }
+
+  /**
+   * Resolve one declared table handle; an undeclared name is a caller bug
+   * and throws.
+   * @param name - Declared table name.
+   * @returns the stable table handle.
+   */
+  table(name: string): KvTable<string, unknown> {
+    const table = this.tables.get(name)
+    if (table === undefined) {
+      throw new Error(`domain '${this.name}' declares no table '${name}'`)
+    }
+    return table
+  }
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), close the unit, then free the name via
+   * the facility hook. Idempotent — repeated calls share one teardown.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void> {
+    this.disposal ??= this.runClose()
+    return this.disposal
+  }
+
+  private async runClose(): Promise<void> {
+    this.disposing = true
+    // Chain links never reject (each is settled via then(noop, noop)), so
+    // this await is a pure drain barrier.
+    await this.chain
+    await this.unit.close()
+    this.closed = true
+    this.onClosed()
+  }
+
+  /**
+   * Dispatch one post-durability change notification, containing observer
+   * failures: the write is already committed (medium and memory both hold
+   * the new state), so a throwing listener must not retroactively reject it.
+   */
+  private emitChanged(change: DomainChanged): void {
+    try {
+      this.ctx.emit('domain/changed', change)
+    } catch (error) {
+      // Swallows synchronous observer exceptions only: emit dispatches
+      // listeners inline and nothing else runs in the try. The event is a
+      // notification, not a transaction participant — the commit point has
+      // passed, so containment (with a log) is the only correct outcome.
+      this.ctx.logger.warn(`domain '${this.name}': domain/changed listener failed: ${String(error)}`)
+    }
+  }
+
+  private enqueue<T>(job: () => Promise<T>): Promise<T> {
+    if (this.disposing) {
+      return Promise.reject(new DomainError('closed', `domain '${this.name}' is closed`))
+    }
+    const result = this.chain.then(job)
+    this.chain = result.then(noop, noop)
+    return result
+  }
+
+  private assertReadable(): void {
+    if (this.closed) {
+      throw new DomainError('closed', `domain '${this.name}' is closed`)
+    }
+  }
+}
+
+/** Table handle bound to one in-memory record map and its domain's write chain. */
+class KvTableImpl<K extends string, V> implements KvTable<K, V> {
+  constructor(
+    private readonly host: TableHost,
+    private readonly tableName: string,
+    private readonly records: Map<string, unknown>,
+  ) {}
+
+  get(key: K): V | undefined {
+    this.host.assertReadable()
+    return this.records.get(key) as V | undefined
+  }
+
+  entries(): IterableIterator<[K, V]> {
+    this.host.assertReadable()
+    return ([...this.records.entries()] as [K, V][])[Symbol.iterator]()
+  }
+
+  keys(): IterableIterator<K> {
+    this.host.assertReadable()
+    return ([...this.records.keys()] as K[])[Symbol.iterator]()
+  }
+
+  get size(): number {
+    this.host.assertReadable()
+    return this.records.size
+  }
+
+  put(key: K, value: V): Promise<void> {
+    return this.host.enqueue(async () => {
+      await this.host.unit.putRecord(this.tableName, key, value)
+      this.records.set(key, value)
+      this.emitPut(key, value)
+    })
+  }
+
+  delete(key: K): Promise<boolean> {
+    return this.host.enqueue(async () => {
+      // Existence is decided at this job's chain slot, not at call time: an
+      // earlier queued put of the same key makes this delete observe it.
+      if (!this.records.has(key)) return false
+      await this.host.unit.deleteRecord(this.tableName, key)
+      this.records.delete(key)
+      this.host.emitChanged({
+        domain: this.host.domainName,
+        table: this.tableName,
+        key,
+        operation: 'deleted',
+      })
+      return true
+    })
+  }
+
+  update(key: K, fn: (current: V) => V): Promise<V> {
+    return this.host.enqueue(async () => {
+      if (!this.records.has(key)) {
+        throw new DomainError(
+          'missing-key',
+          `domain '${this.host.domainName}' table '${this.tableName}' has no record '${key}' to update`,
+        )
+      }
+      const next = fn(this.records.get(key) as V)
+      await this.host.unit.putRecord(this.tableName, key, next)
+      this.records.set(key, next)
+      this.emitPut(key, next)
+      return next
+    })
+  }
+
+  private emitPut(key: K, value: V): void {
+    this.host.emitChanged({
+      domain: this.host.domainName,
+      table: this.tableName,
+      key,
+      operation: 'put',
+      value,
+    })
+  }
+}

packages/storage/storage-domain/src/error.ts

@@ -0,0 +1,53 @@
+/**
+ * Error vocabulary of the domain data form.
+ * @module @deepseek-ai/dsh-storage-domain/src/error
+ */
+
+/** Discriminant codes carried by every {@link DomainError}. */
+export type DomainErrorCode =
+  | 'already-open'
+  | 'facet-unsupported'
+  | 'invalid-record'
+  | 'missing-key'
+  | 'closed'
+
+/** Location of the record that failed schema validation at the durable boundary. */
+export interface InvalidRecordDetail {
+  /** Table holding the rejected record; `''` for the global singleton. */
+  readonly table: string
+  /** Key of the rejected record; `''` for the global singleton. */
+  readonly key: string
+}
+
+/** Construction options: standard `cause` plus the `invalid-record` location. */
+export interface DomainErrorOptions extends ErrorOptions {
+  /** Present exactly when `code` is `invalid-record`. */
+  readonly detail?: InvalidRecordDetail
+}
+
+/**
+ * Error thrown by the domain layer. The `code` is the stable contract
+ * consumers may switch on; `message` is diagnostic prose. Backend failures
+ * (`backend-not-found`, `version-mismatch`, …) pass through as
+ * `StorageError` — the domain layer does not rewrap them.
+ */
+export class DomainError extends Error {
+  override readonly name = 'DomainError'
+
+  /** Present exactly when `code` is `invalid-record`. */
+  readonly detail?: InvalidRecordDetail
+
+  /**
+   * @param code - Stable discriminant for the failure class.
+   * @param message - Human-readable diagnostic detail.
+   * @param options - Standard error options plus the `invalid-record` location.
+   */
+  constructor(
+    readonly code: DomainErrorCode,
+    message: string,
+    options?: DomainErrorOptions,
+  ) {
+    super(message, options)
+    if (options?.detail) this.detail = options.detail
+  }
+}

packages/storage/storage-domain/src/events.ts

@@ -0,0 +1,48 @@
+/**
+ * Change-event vocabulary of the domain data form. Every durable write emits
+ * one event after the backend resolves durability, carrying the new snapshot
+ * and an operation discriminant — never the old value (a diffing consumer
+ * keeps its own previous snapshot). This is the event source for cross-process
+ * change push (RPC frames) in a later phase.
+ * @module @deepseek-ai/dsh-storage-domain/src/events
+ */
+
+/** Shared location fields of one durable domain change. */
+export interface DomainChangedBase {
+  /** Owning domain name. */
+  readonly domain: string
+  /** Table name; `''` for a global-singleton write. */
+  readonly table: string
+  /** Record key; `''` for a global-singleton write. */
+  readonly key: string
+}
+
+/** A record (or the global singleton) was inserted or overwritten. */
+export interface DomainChangedPut extends DomainChangedBase {
+  readonly operation: 'put'
+  /** The new snapshot. */
+  readonly value: unknown
+}
+
+/** A record was deleted; tombstones carry no value. */
+export interface DomainChangedDeleted extends DomainChangedBase {
+  readonly operation: 'deleted'
+  readonly value?: never
+}
+
+/** One durable domain change; a closed union — switch on `operation`. */
+export type DomainChanged = DomainChangedPut | DomainChangedDeleted
+
+declare module 'cordis' {
+  interface Events {
+    /**
+     * A domain record or the global singleton changed, emitted once per write
+     * strictly after the backend acknowledged durability. Events of one
+     * domain arrive in its write-chain order.
+     * @param change - domain, table (`''` for global), key (`''` for global),
+     * operation discriminant, and on `put` the new snapshot.
+     * @mode emit
+     */
+    'domain/changed'(change: DomainChanged): void
+  }
+}

packages/storage/storage-domain/src/index.ts

@@ -0,0 +1,203 @@
+/**
+ * Domain data form (`ctx.storage.domain`): schema-validated, change-emitting
+ * KV domains over storage backends. The single implementation of the domain
+ * layer — consumers depend on this package and never touch backends directly.
+ * Plugin `Config` is schemastery; record schemas inside domain specs are zod
+ * (see `src/spec.ts` for the split rationale).
+ * @module @deepseek-ai/dsh-storage-domain
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { DomainError } from './error.ts'
+import { descriptorOf } from './spec.ts'
+import type { DomainSpec } from './spec.ts'
+import { DomainImpl } from './domain.ts'
+import type { Domain } from './domain.ts'
+
+export { DomainError } from './error.ts'
+export type { DomainErrorCode, DomainErrorOptions, InvalidRecordDetail } from './error.ts'
+export { defineDomain, domainTable, descriptorOf } from './spec.ts'
+export type {
+  DomainSpec, DomainGlobalSpec, DomainTableSpec,
+  TableKeyOf, TableValueOf, GlobalValueOf,
+} from './spec.ts'
+export type { DomainChanged } from './events.ts'
+export type { Domain, DomainGlobal, DomainGlobalHandleOf, KvTable } from './domain.ts'
+
+declare module '@deepseek-ai/dsh-storage' {
+  interface StorageForms {
+    domain: DomainFacility
+  }
+}
+
+/** Cordis plugin name. */
+export const name = 'storage-domain'
+/** The storage hub must be present before the form can mount. */
+export const inject = ['storage']
+
+/**
+ * Plugin config. Which backend serves which domain is decided here, not
+ * globally on the hub: `backend` is the default route and `routes` overrides
+ * it per domain name. A route naming an unregistered backend fails loud at
+ * `open` with `backend-not-found`.
+ */
+export interface Config {
+  /** Default backend name for every domain without an explicit route. Required: there is no universally correct medium. */
+  backend: string
+  /** Per-domain overrides: domain name → backend name. */
+  routes?: Record<string, string>
+}
+
+export const Config: z<Config> = z.object({
+  backend: z.string().required(),
+  routes: z.dict(z.string()).default({}),
+})
+
+/**
+ * The mounted domain facility. Opens declared domains over routed backends;
+ * one facility instance owns the open-domain table and enforces single-open
+ * per domain name.
+ */
+export class DomainFacility {
+  private readonly domains = new Map<string, DomainImpl>()
+  /** Names reserved by an in-flight or completed open, so concurrent opens of one name fail loud. */
+  private readonly reserved = new Set<string>()
+
+  /**
+   * @param ctx - Context of the domain plugin; open-domain effects and change
+   * events attach here.
+   * @param config - Validated plugin config.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: Config,
+  ) {}
+
+  /**
+   * Open one declared domain. Steps, each failing the whole call: reject a
+   * name that is already open (`already-open`); resolve the backend route
+   * (`backend-not-found` passes through from the hub); require its `kv` facet
+   * (`facet-unsupported`); open the unit projected from the spec (backend
+   * `version-mismatch`/`malformed-medium` pass through); load and validate
+   * every stored record against the spec's zod schemas (`invalid-record`
+   * with the offending table and key); construct the domain.
+   *
+   * Lifecycle: the CALLER owns the returned handle and closes it via
+   * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
+   * facility does not tie the domain to any consumer fiber. Domains still
+   * open when the facility unmounts are closed by the plugin disposer.
+   * @param spec - The domain declaration, typically from `defineDomain`.
+   * @returns the opened domain handle, typed by the spec.
+   */
+  async open<S extends DomainSpec>(spec: S): Promise<Domain<S>> {
+    if (this.reserved.has(spec.name)) {
+      throw new DomainError('already-open', `domain '${spec.name}' is already open`)
+    }
+    this.reserved.add(spec.name)
+    try {
+      const backendName = this.config.routes?.[spec.name] ?? this.config.backend
+      const backend = this.ctx.storage.backend.get(backendName)
+      if (!backend.kv) {
+        throw new DomainError(
+          'facet-unsupported',
+          `backend '${backendName}' routed for domain '${spec.name}' has no kv facet`,
+        )
+      }
+      const unit = await backend.kv.open(descriptorOf(spec))
+      try {
+        const snapshot = await unit.loadAll()
+        const tables = new Map<string, Map<string, unknown>>()
+        for (const [table, tableSpec] of Object.entries(spec.tables)) {
+          const records = new Map<string, unknown>()
+          for (const [key, raw] of Object.entries(snapshot.tables[table] ?? {})) {
+            records.set(key, parseRecord(spec.name, table, key, () => tableSpec.valueSchema.parse(raw)))
+          }
+          tables.set(table, records)
+        }
+        // A null stored global means "never written": serve `initial` without
+        // materializing it — the first `set` writes.
+        const globalSpec = spec.global
+        const globalValue = globalSpec === undefined
+          ? undefined
+          : snapshot.global === null
+            ? globalSpec.initial
+            : parseRecord(spec.name, '', '', () => globalSpec.schema.parse(snapshot.global))
+        // The onClosed hook runs strictly after teardown completes: writes
+        // landing during the drain still emit domain/changed, and the domain
+        // stays resolvable (the package invariant cross-checks each event)
+        // until fully closed — only then does the name free up for reopening.
+        const domain: DomainImpl = new DomainImpl(this.ctx, spec, unit, tables, globalValue, () => {
+          this.domains.delete(spec.name)
+          this.reserved.delete(spec.name)
+        })
+        this.domains.set(spec.name, domain)
+        // The single type-erasure point: DomainImpl is the untyped runtime,
+        // Domain<S> the spec-typed view; the unknown hop is required because
+        // S's conditional global-handle type stays unresolved here.
+        return domain as unknown as Domain<S>
+      } catch (error) {
+        await unit.close()
+        throw error
+      }
+    } catch (error) {
+      // Any failure means the domain never registered (nothing can throw
+      // after it), so releasing the name reservation is unconditional.
+      this.reserved.delete(spec.name)
+      throw error
+    }
+  }
+
+  /**
+   * Look up an open domain by name, untyped. Diagnostic surface (the package
+   * invariant cross-checks change events against live domain state); typed
+   * consumers hold the handle returned by {@link open}.
+   * @param name - Domain name.
+   * @returns the open domain runtime, or `undefined` when not open.
+   */
+  get(name: string): DomainImpl | undefined {
+    return this.domains.get(name)
+  }
+
+  /**
+   * Close every domain still open on this facility. The unmount path for
+   * consumers that never called `Domain.close()` themselves; closing is
+   * idempotent, so double-closing an already-closed domain is harmless.
+   * @returns resolution after every unit is released.
+   */
+  async closeAll(): Promise<void> {
+    await Promise.all([...this.domains.values()].map(domain => domain.close()))
+  }
+}
+
+/** Run one zod parse, translating failure to `invalid-record` with its location. */
+function parseRecord<T>(domain: string, table: string, key: string, parse: () => T): T {
+  try {
+    return parse()
+  } catch (error) {
+    const slot = table === '' ? 'global' : `record '${key}' in table '${table}'`
+    throw new DomainError(
+      'invalid-record',
+      `domain '${domain}': stored ${slot} does not match its schema`,
+      { detail: { table, key }, cause: error },
+    )
+  }
+}
+
+/**
+ * Mount the domain data form on the storage hub.
+ * @param ctx - Plugin context.
+ * @param config - Validated plugin config.
+ */
+export function apply(ctx: Context, config: Config) {
+  const facility = new DomainFacility(ctx, config)
+  ctx.effect(() => {
+    const unmount = ctx.storage.mount('domain', facility)
+    return async () => {
+      // Close leftovers before unmounting: draining writes still emit
+      // domain/changed, whose invariant resolves the facility through the hub.
+      await facility.closeAll()
+      unmount()
+    }
+  })
+}

packages/storage/storage-domain/src/invariant.ts

@@ -0,0 +1,67 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-storage-domain`: every
+ * `domain/changed` event must agree with the emitting domain's authoritative
+ * in-memory state (the owned event-stream ↔ mutable-data relationship of this
+ * package). Writes emit strictly after mutating memory and the write chain
+ * serializes them, so at emission time the event's snapshot equals the
+ * current read — any divergence means a write path skipped the chain or
+ * emitted a stale value.
+ * @module @deepseek-ai/dsh-storage-domain/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { DomainChanged } from './events.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-storage-domain'
+
+/** Cordis companion plugin name. */
+export const name = 'storage-domain-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Install the change-event ↔ memory-state agreement check. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  ctx.on('domain/changed', (change: DomainChanged) => {
+    const domain = ctx.storage.form('domain').get(change.domain)
+    if (domain === undefined) {
+      return fail(`domain/changed for '${change.domain}' emitted while that domain is not open`)
+    }
+    if (change.table === '') {
+      // Global write: the event snapshot must be the current global value.
+      if (domain.global.get() !== change.value) {
+        return fail(`domain/changed global value for '${change.domain}' differs from the in-memory global`)
+      }
+      return
+    }
+    const current = domain.table(change.table).get(change.key)
+    switch (change.operation) {
+      case 'deleted':
+        if (current !== undefined) {
+          return fail(
+            `domain/changed deletion of '${change.domain}'.'${change.table}'['${change.key}'] `
+            + 'emitted while the record is still in memory',
+          )
+        }
+        return
+      case 'put':
+        if (current !== change.value) {
+          return fail(
+            `domain/changed value for '${change.domain}'.'${change.table}'['${change.key}'] `
+            + 'differs from the in-memory record',
+          )
+        }
+        return
+      default:
+        change satisfies never
+    }
+  }, { global: true })
+}, { inject: ['storage'] })
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/storage/storage-domain/src/spec.ts

@@ -0,0 +1,112 @@
+/**
+ * Domain declaration vocabulary. A spec object is the single source of a
+ * domain's identity, layout, and record schemas: the owning package defines
+ * it once with {@link defineDomain} and both the type surface and the runtime
+ * (validation, descriptor projection) derive from it. Record schemas are zod
+ * (`z.infer` keeps types un-duplicated and the same schemas later project to
+ * RPC wire schemas); plugin `Config` stays schemastery.
+ * @module @deepseek-ai/dsh-storage-domain/src/spec
+ */
+
+import type { ZodType } from 'zod'
+import { UNIT_NAME_RE, type KvUnitDescriptor } from '@deepseek-ai/dsh-storage'
+
+/** Global singleton declaration: schema plus the value used before the first write. */
+export interface DomainGlobalSpec<G> {
+  /** Validates the stored global at the durable boundary. */
+  readonly schema: ZodType<G>
+  /** Value served when the medium holds no global yet; not written until the first `set`. */
+  readonly initial: G
+}
+
+/**
+ * One table declaration. `K` is a phantom key type (typically a branded
+ * string) carried for compile-time projection only; keys are plain strings on
+ * the medium.
+ */
+export interface DomainTableSpec<K extends string = string, V = unknown> {
+  /** Validates every stored record at the durable boundary. */
+  readonly valueSchema: ZodType<V>
+  /** Phantom carrier for the key type; never present at runtime. */
+  readonly __key?: K
+}
+
+/** Static declaration of one domain: identity, version, and record layout. */
+export interface DomainSpec {
+  /** Domain name; must match `UNIT_NAME_RE` (doubles as the backend unit name). */
+  readonly name: string
+  /** Domain format version; a medium stamped with a different version rejects at open. */
+  readonly version: number
+  /** Optional global singleton slot. */
+  readonly global?: DomainGlobalSpec<unknown>
+  /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */
+  readonly tables: Record<string, DomainTableSpec>
+}
+
+/** Key type of one declared table, recovered from its phantom carrier. */
+export type TableKeyOf<S extends DomainSpec, N extends keyof S['tables']> =
+  S['tables'][N] extends DomainTableSpec<infer K> ? K : never
+
+/** Value type of one declared table. */
+export type TableValueOf<S extends DomainSpec, N extends keyof S['tables']> =
+  S['tables'][N] extends DomainTableSpec<string, infer V> ? V : never
+
+/** Global value type of a spec; `never` when the spec declares no global. */
+export type GlobalValueOf<S extends DomainSpec> =
+  S['global'] extends DomainGlobalSpec<infer G> ? G : never
+
+/**
+ * Declare one table.
+ * @param schema - zod schema validating every stored record of this table.
+ * @returns the table declaration, key-typed by `K`.
+ */
+export function domainTable<K extends string, V>(schema: ZodType<V>): DomainTableSpec<K, V> {
+  return { valueSchema: schema }
+}
+
+/**
+ * Identity helper that pins a spec's literal types and validates its shape.
+ * Misconfiguration fails loud at the owning package's module load, before any
+ * medium is touched: a domain or table name outside `UNIT_NAME_RE`, a version
+ * that is not a non-negative integer, or a global schema that accepts `null`
+ * all throw. The `null` rejection guards round-tripping: backends store the
+ * global as opaque JSON with `null` as the "never written" sentinel, so a
+ * nullable global would be indistinguishable from an absent one on reopen
+ * (a stored `null` silently reverts to `initial`).
+ * @param spec - The domain declaration.
+ * @returns the same spec, narrowed to its literal type.
+ */
+export function defineDomain<S extends DomainSpec>(spec: S): S {
+  if (!UNIT_NAME_RE.test(spec.name)) {
+    throw new Error(`domain name '${spec.name}' must match ${UNIT_NAME_RE}`)
+  }
+  if (!Number.isInteger(spec.version) || spec.version < 0) {
+    throw new Error(`domain '${spec.name}' version must be a non-negative integer, got ${spec.version}`)
+  }
+  for (const table of Object.keys(spec.tables)) {
+    if (!UNIT_NAME_RE.test(table)) {
+      throw new Error(`domain '${spec.name}' table name '${table}' must match ${UNIT_NAME_RE}`)
+    }
+  }
+  if (spec.global !== undefined && spec.global.schema.safeParse(null).success) {
+    throw new Error(
+      `domain '${spec.name}' global schema must not accept null: `
+      + 'null is the medium\'s "never written" sentinel, so a stored null could not round-trip',
+    )
+  }
+  return spec
+}
+
+/**
+ * Project a spec onto the backend-facing unit descriptor.
+ * @param spec - The domain declaration.
+ * @returns the descriptor handed to `KvFacet.open`.
+ */
+export function descriptorOf(spec: DomainSpec): KvUnitDescriptor {
+  return {
+    name: spec.name,
+    version: spec.version,
+    tables: Object.keys(spec.tables),
+    hasGlobal: spec.global !== undefined,
+  }
+}

packages/storage/storage-domain/tests/domain.spec.ts

@@ -0,0 +1,326 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { z } from 'zod'
+import Storage from '@deepseek-ai/dsh-storage'
+import { DomainFacility, defineDomain, domainTable } from '../src/index.ts'
+import type { Config } from '../src/index.ts'
+import type { DomainChanged } from '../src/events.ts'
+import { MemoryMediaPool, MemoryStorageBackend } from './helpers/memory-backend.ts'
+
+const itemSchema = z.object({ label: z.string(), count: z.number().int() })
+type Item = z.infer<typeof itemSchema>
+
+const settingsSchema = z.object({ theme: z.string() })
+
+const spec = defineDomain({
+  name: 'demo',
+  version: 1,
+  global: { schema: settingsSchema, initial: { theme: 'plain' } },
+  tables: { items: domainTable<string, Item>(itemSchema) },
+})
+
+const bareSpec = defineDomain({
+  name: 'bare',
+  version: 1,
+  tables: { rows: domainTable<string, Item>(itemSchema) },
+})
+
+/** Boot a context with the storage hub, one memory backend, and a facility over it. */
+async function harness(options?: { pool?: MemoryMediaPool; config?: Partial<Config> }) {
+  const ctx = new Context()
+  await ctx.plugin(Storage)
+  const backend = new MemoryStorageBackend(options?.pool)
+  ctx.storage.backend.register('memory', backend)
+  const facility = new DomainFacility(ctx, { backend: 'memory', routes: {}, ...options?.config })
+  // Mounted, not just constructed: the package invariant resolves the form
+  // through ctx.storage to cross-check every domain/changed emission.
+  ctx.storage.mount('domain', facility)
+  const changes: DomainChanged[] = []
+  ctx.on('domain/changed', (change) => { changes.push(change) })
+  return { ctx, backend, facility, changes }
+}
+
+describe('defineDomain', () => {
+  it('rejects invalid names and versions loudly', () => {
+    expect(() => defineDomain({ name: 'Bad-Name', version: 1, tables: {} })).toThrow(/must match/)
+    expect(() => defineDomain({ name: 'ok', version: 1.5, tables: {} })).toThrow(/non-negative integer/)
+    expect(() => defineDomain({
+      name: 'ok', version: 1, tables: { 'Bad Table': domainTable<string, Item>(itemSchema) },
+    })).toThrow(/table name/)
+  })
+
+  it('rejects a global schema that accepts null (the never-written sentinel)', () => {
+    expect(() => defineDomain({
+      name: 'ok',
+      version: 1,
+      global: { schema: settingsSchema.nullable(), initial: null },
+      tables: {},
+    })).toThrow(/must not accept null/)
+  })
+})
+
+describe('DomainFacility.open', () => {
+  it('opens, reads back stored records, and rejects a second open of the same name', async () => {
+    const { facility } = await harness()
+    const domain = await facility.open(spec)
+    await domain.table('items').put('a', { label: 'first', count: 1 })
+    await expect(facility.open(spec)).rejects.toMatchObject({ name: 'DomainError', code: 'already-open' })
+    expect(domain.table('items').get('a')).toEqual({ label: 'first', count: 1 })
+  })
+
+  it('routes per domain name and fails loud on an unregistered route target', async () => {
+    const { facility } = await harness({ config: { routes: { demo: 'nonexistent' } } })
+    await expect(facility.open(spec)).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'backend-not-found',
+    })
+    // The failed open releases the name for a later attempt.
+    const { facility: healthy } = await harness()
+    await expect(healthy.open(spec)).resolves.toBeDefined()
+  })
+
+  it('rejects a backend without the kv facet', async () => {
+    const { ctx, facility } = await harness({ config: { backend: 'nokv' } })
+    ctx.storage.backend.register('nokv', { close: async () => {} })
+    await expect(facility.open(spec)).rejects.toMatchObject({ code: 'facet-unsupported' })
+  })
+
+  it('falls back to the default backend when no route table is configured', async () => {
+    // A second, unmounted facility whose config omits `routes` entirely
+    // (exactOptionalPropertyTypes forbids an explicit undefined). Opening
+    // emits no events, so the mounted facility's invariant never consults it.
+    const { ctx } = await harness()
+    const routeless = new DomainFacility(ctx, { backend: 'memory' })
+    await expect(routeless.open(bareSpec)).resolves.toBeDefined()
+  })
+
+  it('treats a table key the backend omitted from loadAll as empty', async () => {
+    // A sparse backend: loadAll omits declared table keys entirely instead of
+    // returning them as empty objects.
+    const { ctx, facility } = await harness({ config: { backend: 'sparse' } })
+    ctx.storage.backend.register('sparse', {
+      kv: {
+        open: async () => ({
+          loadAll: async () => ({ tables: {}, global: null }),
+          putRecord: async () => {},
+          deleteRecord: async () => {},
+          setGlobal: async () => {},
+          close: async () => {},
+        }),
+      },
+      close: async () => {},
+    })
+    const domain = await facility.open(bareSpec)
+    expect(domain.table('rows').size).toBe(0)
+  })
+
+  it('rejects stored records that fail their schema, naming table and key', async () => {
+    const pool = new MemoryMediaPool()
+    {
+      const { facility } = await harness({ pool })
+      await (await facility.open(spec)).table('items').put('bad', { label: 'x', count: 2 })
+    }
+    pool.media.get('demo')!.tables.get('items')!.set('bad', { label: 'x', count: 'NaN' })
+    const { facility } = await harness({ pool })
+    await expect(facility.open(spec)).rejects.toMatchObject({
+      code: 'invalid-record',
+      detail: { table: 'items', key: 'bad' },
+    })
+  })
+
+  it('rejects a stored global that fails its schema with the global marker', async () => {
+    const pool = new MemoryMediaPool()
+    pool.versions.set('demo', 1)
+    pool.media.set('demo', { tables: new Map(), global: { theme: 42 } })
+    const { facility } = await harness({ pool })
+    await expect(facility.open(spec)).rejects.toMatchObject({
+      code: 'invalid-record',
+      detail: { table: '', key: '' },
+    })
+  })
+
+  it('passes through a backend version mismatch', async () => {
+    const pool = new MemoryMediaPool()
+    pool.versions.set('demo', 7)
+    const { facility } = await harness({ pool })
+    await expect(facility.open(spec)).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'version-mismatch',
+    })
+  })
+})
+
+describe('plugin apply', () => {
+  it('mounts the facility as ctx.storage.domain through the plugin effect', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    ctx.storage.backend.register('memory', new MemoryStorageBackend())
+    const DomainPlugin = await import('../src/index.ts')
+    const fiber = await ctx.plugin(DomainPlugin, { backend: 'memory' })
+    expect(ctx.storage.domain).toBeInstanceOf(DomainFacility)
+    await fiber.dispose()
+    expect(() => ctx.storage.form('domain')).toThrow(/not mounted/)
+  })
+})
+
+describe('table and snapshot reads', () => {
+  it('serves entries, keys, and size as stable snapshots; unknown table names throw', async () => {
+    const { facility } = await harness()
+    const domain = await facility.open(spec)
+    const table = domain.table('items')
+    await table.put('a', { label: 'x', count: 1 })
+    await table.put('b', { label: 'y', count: 2 })
+    expect(table.size).toBe(2)
+    expect([...table.keys()].sort()).toEqual(['a', 'b'])
+    expect(new Map(table.entries()).get('a')).toEqual({ label: 'x', count: 1 })
+    expect(() => domain.table('nope' as never)).toThrow(/declares no table/)
+  })
+})
+
+describe('KvTable writes', () => {
+  it('serializes concurrent updates on one key without losing increments', async () => {
+    const { facility } = await harness()
+    const table = (await facility.open(spec)).table('items')
+    await table.put('counter', { label: 'c', count: 0 })
+    await Promise.all(Array.from({ length: 50 }, () =>
+      table.update('counter', current => ({ ...current, count: current.count + 1 }))))
+    expect(table.get('counter')).toEqual({ label: 'c', count: 50 })
+  })
+
+  it('update rejects a missing key; delete reports prior existence', async () => {
+    const { facility } = await harness()
+    const table = (await facility.open(spec)).table('items')
+    await expect(table.update('ghost', v => v)).rejects.toMatchObject({ code: 'missing-key' })
+    await table.put('a', { label: 'x', count: 1 })
+    await expect(table.delete('a')).resolves.toBe(true)
+    await expect(table.delete('a')).resolves.toBe(false)
+  })
+
+  it('emits domain/changed per durable write, in order, with tombstones and global marker', async () => {
+    const { facility, changes } = await harness()
+    const domain = await facility.open(spec)
+    const table = domain.table('items')
+    await table.put('a', { label: 'x', count: 1 })
+    await table.update('a', current => ({ ...current, count: 2 }))
+    await table.delete('a')
+    await table.delete('a') // no event: already absent
+    await domain.global.set({ theme: 'dark' })
+    expect(changes).toEqual([
+      { domain: 'demo', table: 'items', key: 'a', operation: 'put', value: { label: 'x', count: 1 } },
+      { domain: 'demo', table: 'items', key: 'a', operation: 'put', value: { label: 'x', count: 2 } },
+      { domain: 'demo', table: 'items', key: 'a', operation: 'deleted' },
+      { domain: 'demo', table: '', key: '', operation: 'put', value: { theme: 'dark' } },
+    ])
+  })
+})
+
+describe('durability failure', () => {
+  it('leaves memory untouched and emits nothing when the backend rejects a write', async () => {
+    const pool = new MemoryMediaPool()
+    const { facility, changes } = await harness({ pool })
+    const domain = await facility.open(spec)
+    const table = domain.table('items')
+    await table.put('a', { label: 'x', count: 1 })
+    const seen = changes.length
+
+    pool.failNextWrites = 3
+    await expect(table.put('a', { label: 'x', count: 99 })).rejects.toThrow(/injected/)
+    await expect(table.update('a', c => ({ ...c, count: c.count + 1 }))).rejects.toThrow(/injected/)
+    await expect(table.delete('a')).rejects.toThrow(/injected/)
+
+    // Reads still serve the pre-failure record; no events leaked.
+    expect(table.get('a')).toEqual({ label: 'x', count: 1 })
+    expect(pool.media.get('demo')!.tables.get('items')!.get('a')).toEqual({ label: 'x', count: 1 })
+    expect(changes).toHaveLength(seen)
+
+    // The chain survives rejections: the next write lands cleanly with no residue.
+    await table.update('a', c => ({ ...c, count: c.count + 1 }))
+    expect(table.get('a')).toEqual({ label: 'x', count: 2 })
+  })
+
+  it('keeps serving initial when the first global set fails durability', async () => {
+    const pool = new MemoryMediaPool()
+    const { facility } = await harness({ pool })
+    const domain = await facility.open(spec)
+    pool.failNextWrites = 1
+    await expect(domain.global.set({ theme: 'dark' })).rejects.toThrow(/injected/)
+    expect(domain.global.get()).toEqual({ theme: 'plain' })
+    expect(pool.media.get('demo')!.global).toBeNull()
+  })
+})
+
+describe('global singleton', () => {
+  it('serves initial before first set without materializing, then persists the first set', async () => {
+    const pool = new MemoryMediaPool()
+    {
+      const { facility } = await harness({ pool })
+      const domain = await facility.open(spec)
+      expect(domain.global.get()).toEqual({ theme: 'plain' })
+      expect(pool.media.get('demo')!.global).toBeNull() // initial never touches the medium
+      await domain.global.set({ theme: 'dark' })
+      expect(pool.media.get('demo')!.global).toEqual({ theme: 'dark' })
+    }
+    const { facility } = await harness({ pool })
+    expect((await facility.open(spec)).global.get()).toEqual({ theme: 'dark' })
+  })
+
+  it('throws on access when the spec declares no global', async () => {
+    const { facility } = await harness()
+    const domain = await facility.open(bareSpec)
+    expect(() => (domain as { global: unknown }).global).toThrow(/declares no global/)
+  })
+})
+
+describe('close and lifecycle', () => {
+  it('close drains queued writes, then rejects reads and writes, and frees the name', async () => {
+    const pool = new MemoryMediaPool()
+    const { facility } = await harness({ pool })
+    const domain = await facility.open(spec)
+    const table = domain.table('items')
+    const pending = Promise.all([
+      table.put('a', { label: 'x', count: 1 }),
+      table.put('b', { label: 'y', count: 2 }),
+    ])
+    await Promise.all([domain.close(), domain.close()]) // idempotent
+    await pending // queued before close → still landed
+    // Durability is the drain contract: both queued writes reached the medium.
+    expect([...pool.media.get('demo')!.tables.get('items')!.keys()].sort()).toEqual(['a', 'b'])
+    await expect(table.put('c', { label: 'z', count: 3 })).rejects.toMatchObject({ code: 'closed' })
+    expect(() => table.get('a')).toThrow(/closed/)
+    // The name is free again: reopening sees the drained state.
+    const reopened = await facility.open(spec)
+    expect([...reopened.table('items').keys()].sort()).toEqual(['a', 'b'])
+  })
+
+  it('facility unmount closes domains the consumer never closed', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    ctx.storage.backend.register('memory', new MemoryStorageBackend())
+    const DomainPlugin = await import('../src/index.ts')
+    const fiber = await ctx.plugin(DomainPlugin, { backend: 'memory' })
+    const domain = await ctx.storage.domain.open(bareSpec)
+    const table = domain.table('rows')
+    await table.put('a', { label: 'x', count: 1 })
+    await fiber.dispose()
+    await expect(table.put('b', { label: 'y', count: 2 })).rejects.toMatchObject({ code: 'closed' })
+    expect(() => ctx.storage.form('domain')).toThrow(/not mounted/)
+  })
+
+  it('contains a throwing domain/changed listener without rejecting the committed write', async () => {
+    const pool = new MemoryMediaPool()
+    const { ctx, facility, changes } = await harness({ pool })
+    const domain = await facility.open(spec)
+    const table = domain.table('items')
+    ctx.on('domain/changed', () => {
+      throw new Error('hostile observer')
+    })
+    await expect(table.put('a', { label: 'x', count: 1 })).resolves.toBeUndefined()
+    // Commit survived intact on both planes, and well-behaved listeners
+    // (registered before the thrower) still observed the event.
+    expect(table.get('a')).toEqual({ label: 'x', count: 1 })
+    expect(pool.media.get('demo')!.tables.get('items')!.get('a')).toEqual({ label: 'x', count: 1 })
+    expect(changes).toHaveLength(1)
+    // The chain is unpoisoned: subsequent writes proceed normally.
+    await expect(table.delete('a')).resolves.toBe(true)
+  })
+})

packages/storage/storage-domain/tests/helpers/memory-backend.ts

@@ -0,0 +1,160 @@
+/**
+ * In-memory {@link StorageBackend} test double implementing the full KvUnit
+ * primitive set. Shared test infrastructure: the domain suite uses it to
+ * exercise open/route/write semantics without touching disk, and the
+ * workspace package's tests import it by relative path (it lives under
+ * `tests/`, never `src/`, so it stays out of the published surface).
+ *
+ * Fidelity to the backend contract (`dsh-storage` `src/backend.ts`): version
+ * stamping and `version-mismatch` on reopen, `malformed` never (memory cannot
+ * corrupt), per-call atomicity trivially, `closed` after close, delete
+ * idempotence. Media survive across backends through the shared `media` map
+ * passed into the constructor, which simulates process restarts; stamp
+ * `versions` directly to fabricate an on-medium version and force a
+ * `version-mismatch` without a prior open.
+ * @module
+ */
+
+import { StorageError } from '@deepseek-ai/dsh-storage'
+import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from '@deepseek-ai/dsh-storage'
+
+/** One unit's medium: tables of records plus the global slot (`null` = never written). */
+export interface MemoryMedium {
+  tables: Map<string, Map<string, unknown>>
+  global: unknown
+}
+
+/**
+ * Shared media pool. Construct one and hand it to several
+ * {@link MemoryStorageBackend} instances to simulate reopening the same
+ * medium after a restart; `versions` holds the stamped unit versions and is
+ * writable by tests to inject a mismatching on-medium version, and
+ * `failNextWrites` injects write-primitive failures.
+ */
+export class MemoryMediaPool {
+  /** Unit name → its records; a missing entry is a never-materialized unit. */
+  readonly media = new Map<string, MemoryMedium>()
+  /** Unit name → stamped version; tests may pre-stamp to force `version-mismatch`. */
+  readonly versions = new Map<string, number>()
+  /**
+   * When positive, that many subsequent write primitives (putRecord /
+   * deleteRecord / setGlobal) reject without touching the medium, decrementing
+   * per rejection. Negative-path seam: callers assert their state is
+   * untouched after a durability failure.
+   */
+  failNextWrites = 0
+
+  /** Consume one injected failure, throwing in a rejected write's place. */
+  consumeInjectedFailure(): void {
+    if (this.failNextWrites > 0) {
+      this.failNextWrites -= 1
+      throw new Error('injected write failure')
+    }
+  }
+}
+
+/** In-memory KV unit over one pooled medium. */
+class MemoryKvUnit implements KvUnit {
+  private closed = false
+
+  constructor(
+    private readonly pool: MemoryMediaPool,
+    private readonly medium: MemoryMedium,
+    private readonly descriptor: KvUnitDescriptor,
+    private readonly onClose: () => void,
+  ) {}
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new StorageError('closed', `memory unit '${this.descriptor.name}' is closed`)
+    }
+  }
+
+  async loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }> {
+    this.assertOpen()
+    const tables: Record<string, Record<string, unknown>> = {}
+    for (const table of this.descriptor.tables) {
+      tables[table] = Object.fromEntries(this.medium.tables.get(table) ?? [])
+    }
+    return { tables, global: this.medium.global }
+  }
+
+  async putRecord(table: string, key: string, value: unknown): Promise<void> {
+    this.assertOpen()
+    this.pool.consumeInjectedFailure()
+    let records = this.medium.tables.get(table)
+    if (records === undefined) {
+      records = new Map()
+      this.medium.tables.set(table, records)
+    }
+    records.set(key, value)
+  }
+
+  async deleteRecord(table: string, key: string): Promise<void> {
+    this.assertOpen()
+    this.pool.consumeInjectedFailure()
+    this.medium.tables.get(table)?.delete(key)
+  }
+
+  async setGlobal(value: unknown): Promise<void> {
+    this.assertOpen()
+    this.pool.consumeInjectedFailure()
+    this.medium.global = value
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    this.onClose()
+  }
+}
+
+/**
+ * In-memory storage backend with a `kv` facet. Pass a shared
+ * {@link MemoryMediaPool} to let a second instance reopen the same media;
+ * omit it for a throwaway isolated pool.
+ */
+export class MemoryStorageBackend implements StorageBackend {
+  readonly kv: KvFacet
+  private readonly openUnits = new Set<string>()
+  private closed = false
+
+  /**
+   * @param pool - Media shared across instances; a fresh private pool when omitted.
+   */
+  constructor(readonly pool: MemoryMediaPool = new MemoryMediaPool()) {
+    this.kv = {
+      open: async (descriptor: KvUnitDescriptor): Promise<KvUnit> => {
+        if (this.closed) {
+          throw new StorageError('closed', 'memory backend is closed')
+        }
+        // Double-open is a caller bug per the backend contract; no dedicated
+        // StorageError code exists for it, so a plain Error is correct.
+        if (this.openUnits.has(descriptor.name)) {
+          throw new Error(`memory unit '${descriptor.name}' is already open (double-open is a caller bug)`)
+        }
+        const stamped = this.pool.versions.get(descriptor.name)
+        if (stamped === undefined) {
+          this.pool.versions.set(descriptor.name, descriptor.version)
+        } else if (stamped !== descriptor.version) {
+          throw new StorageError(
+            'version-mismatch',
+            `memory unit '${descriptor.name}' is stamped v${stamped}, descriptor wants v${descriptor.version}`,
+          )
+        }
+        let medium = this.pool.media.get(descriptor.name)
+        if (medium === undefined) {
+          medium = { tables: new Map(), global: null }
+          this.pool.media.set(descriptor.name, medium)
+        }
+        this.openUnits.add(descriptor.name)
+        return new MemoryKvUnit(this.pool, medium, descriptor, () => this.openUnits.delete(descriptor.name))
+      },
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    this.openUnits.clear()
+  }
+}

packages/storage/storage-domain/tests/invariant.spec.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { z } from 'zod'
+import Storage from '@deepseek-ai/dsh-storage'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+import * as DomainInvariantCompanion from '@deepseek-ai/dsh-storage-domain/invariant'
+import { DomainFacility, defineDomain, domainTable } from '../src/index.ts'
+import type { DomainChanged } from '../src/events.ts'
+import { MemoryStorageBackend } from './helpers/memory-backend.ts'
+
+const itemSchema = z.object({ n: z.number() })
+type Item = z.infer<typeof itemSchema>
+
+const spec = defineDomain({
+  name: 'inv',
+  version: 1,
+  global: { schema: itemSchema, initial: { n: 0 } },
+  tables: { rows: domainTable<string, Item>(itemSchema) },
+})
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(Storage)
+  await ctx.plugin(InvariantService, { enabled: true })
+  await ctx.plugin(DomainInvariantCompanion)
+  ctx.storage.backend.register('memory', new MemoryStorageBackend())
+  const facility = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+  ctx.storage.mount('domain', facility)
+  return { ctx, facility }
+}
+
+const invariantViolation: unknown = expect.objectContaining<Partial<InvariantError>>({
+  code: 'INVARIANT',
+  packageName: '@deepseek-ai/dsh-storage-domain',
+})
+
+describe('domain change-event invariants', () => {
+  it('accepts every write shape emitted by the real write paths', async () => {
+    const { facility } = await setup()
+    const domain = await facility.open(spec)
+    const rows = domain.table('rows')
+    await rows.put('a', { n: 1 })
+    await rows.update('a', current => ({ n: current.n + 1 }))
+    await expect(rows.delete('a')).resolves.toBe(true)
+    await domain.global.set({ n: 5 })
+  })
+
+  it('rejects an event for a domain that is not open', async () => {
+    const { ctx } = await setup()
+    expect(() => { ctx.emit('domain/changed', {
+      domain: 'ghost', table: 'rows', key: 'a', operation: 'put', value: { n: 1 },
+    }) }).toThrow(invariantViolation)
+  })
+
+  it('rejects a put event whose value is not the in-memory record', async () => {
+    const { ctx, facility } = await setup()
+    const domain = await facility.open(spec)
+    await domain.table('rows').put('a', { n: 1 })
+    expect(() => { ctx.emit('domain/changed', {
+      domain: 'inv', table: 'rows', key: 'a', operation: 'put', value: { n: 999 },
+    }) }).toThrow(invariantViolation)
+  })
+
+  it('rejects a deletion event while the record is still in memory', async () => {
+    const { ctx, facility } = await setup()
+    const domain = await facility.open(spec)
+    await domain.table('rows').put('a', { n: 1 })
+    expect(() => { ctx.emit('domain/changed', {
+      domain: 'inv', table: 'rows', key: 'a', operation: 'deleted',
+    }) }).toThrow(invariantViolation)
+  })
+
+  it('rejects a global event whose value is not the in-memory global', async () => {
+    const { ctx, facility } = await setup()
+    await facility.open(spec)
+    expect(() => { ctx.emit('domain/changed', {
+      domain: 'inv', table: '', key: '', operation: 'put', value: { n: 42 },
+    }) }).toThrow(invariantViolation)
+  })
+
+  it('tolerates operations outside the closed union without failing falsely', async () => {
+    const { ctx, facility } = await setup()
+    const domain = await facility.open(spec)
+    await domain.table('rows').put('a', { n: 1 })
+    // Merge-hostile input: the closed union's satisfies-never default arm is
+    // unreachable in typed code; an untyped emit must not crash the check.
+    expect(() => { ctx.emit('domain/changed', {
+      domain: 'inv', table: 'rows', key: 'a', operation: 'exotic',
+    } as unknown as DomainChanged) }).not.toThrow()
+  })
+})

packages/storage/storage-domain/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../storage"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/storage/storage-json/README.md

@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-storage-json
+
+JSON backend for the [storage hub](../storage/README.md): one human-readable `<unit>.json` file per unit under a configured root, registered as backend `json`. Design: [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Model
+
+- The in-memory unit state is authoritative; every write primitive republishes the whole file via temp-write + fsync + atomic `rename()` replace. A unit file is always the complete current net state — legibility is this backend's reason to exist; scale is the SQLite backend's job.
+- A missing file opens as an empty unit and materializes on the first write. A foreign or unparsable file rejects with `malformed-medium`; a stored version differing from the descriptor rejects with `version-mismatch` (no migration, pre-release stance).
+- Write ordering across calls belongs to the caller (the domain layer's write chain); each single call is atomic and durable once resolved.
+
+## Config
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `root` | string | required — no default (a cwd fallback would scatter files) | Directory holding unit files; created `0o700` on demand |
+
+## Model Experience
+
+### Stored domain records
+
+#### What the model sees
+
+Nothing. This backend contributes no prompt, tool, or schema; it persists non-session domain data behind `ctx.storage` for host-side consumers only.
+
+#### Token effect
+
+Zero live-request tokens.
+
+#### KV Cache effect
+
+None — the backend never touches live request prefixes.
+
+## Known Limitations and Deferred Work
+
+- Windows durability relies on libuv's `rename()` (`MoveFileExW` with replacement) without an explicit write-through flag; the session-log backend's stricter Win32 write-through publish helper is planned to move down here when the append-log facet lands (see the Agent Note's migration section).
+- No cross-process write locking: two processes writing the same root can interleave whole-file replacements (last write wins). Single-host-process deployments are the current consumer; the multi-process story is deferred per the Agent Note's out-of-scope table.

packages/storage/storage-json/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-storage-json",
+  "description": "JSON file KV storage backend for the DeepSeek Harness storage hub",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/storage/storage-json/src/atomic.ts

@@ -0,0 +1,53 @@
+/**
+ * Atomic whole-file replacement for the JSON backend.
+ *
+ * Publish protocol: write a same-directory temp file, fsync it, then
+ * `rename()` over the target. Rename is an atomic replace on POSIX and on
+ * Windows (libuv maps it to `MoveFileExW(..., MOVEFILE_REPLACE_EXISTING)`),
+ * and replacement is the intended semantic here — unlike the session-log
+ * backend's link()+unlink() no-clobber protocol, a unit file has exactly one
+ * writer per process and last-write-wins is correct. After the rename the
+ * parent directory is fsynced on POSIX so the new entry is crash-durable.
+ * @module @deepseek-ai/dsh-storage-json/src/atomic
+ */
+
+import { open, rename, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+/**
+ * Durably replace `path` with `data`.
+ * @param path - Absolute target file path.
+ * @param data - Full new file content.
+ * @returns resolution after the replacement is crash-durable.
+ */
+export async function writeAtomic(path: string, data: string): Promise<void> {
+  const tmp = join(dirname(path), `.${randomUUID()}.tmp`)
+  try {
+    const handle = await open(tmp, 'wx', 0o600)
+    try {
+      await handle.writeFile(data, 'utf8')
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await rename(tmp, path)
+    await fsyncDirectory(dirname(path))
+  } catch (error) {
+    await rm(tmp, { force: true })
+    throw error
+  }
+}
+
+/** fsync a POSIX directory so a just-renamed entry is crash-durable. */
+/* v8 ignore start -- Windows rejects O_RDONLY directory opens; POSIX coverage exercises this. */
+async function fsyncDirectory(path: string): Promise<void> {
+  if (process.platform === 'win32') return
+  const handle = await open(path, 'r')
+  try {
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+/* v8 ignore stop */

packages/storage/storage-json/src/format.ts

@@ -0,0 +1,84 @@
+/**
+ * On-disk JSON unit format: the file is always the current net state, kept
+ * human-readable (pretty-printed, stable key order from insertion) — that
+ * legibility is this backend's reason to exist.
+ * @module @deepseek-ai/dsh-storage-json/src/format
+ */
+
+import { StorageError } from '@deepseek-ai/dsh-storage'
+import type { KvUnitDescriptor } from '@deepseek-ai/dsh-storage'
+
+/** In-memory authoritative state of one unit; the file is its projection. `global` is `null` until first written. */
+export interface UnitState {
+  version: number
+  global: unknown
+  tables: Map<string, Map<string, unknown>>
+}
+
+/**
+ * Serialize a unit state to file content.
+ * @param name - Unit name, stamped into the header.
+ * @param state - Authoritative in-memory state.
+ * @returns pretty-printed JSON document with a trailing newline.
+ */
+export function serialize(name: string, state: UnitState): string {
+  const tables: Record<string, Record<string, unknown>> = {}
+  for (const [table, records] of state.tables) {
+    tables[table] = Object.fromEntries(records)
+  }
+  const document = {
+    unit: { name, version: state.version },
+    global: state.global,
+    tables,
+  }
+  return `${JSON.stringify(document, null, 2)}\n`
+}
+
+/**
+ * Parse file content into unit state, validating shape and version.
+ * @param text - Raw file content.
+ * @param descriptor - Expected identity; version mismatch rejects.
+ * @returns the parsed state.
+ */
+export function parse(text: string, descriptor: KvUnitDescriptor): UnitState {
+  let document: unknown
+  try {
+    document = JSON.parse(text)
+  } catch (error) {
+    throw new StorageError('malformed-medium', `unit '${descriptor.name}': file is not valid JSON`, { cause: error })
+  }
+  if (typeof document !== 'object' || document === null) {
+    throw new StorageError('malformed-medium', `unit '${descriptor.name}': file is not a JSON object`)
+  }
+  const { unit, global: globalValue, tables } = document as Record<string, unknown>
+  if (
+    typeof unit !== 'object' || unit === null ||
+    (unit as Record<string, unknown>)['name'] !== descriptor.name ||
+    typeof (unit as Record<string, unknown>)['version'] !== 'number'
+  ) {
+    throw new StorageError('malformed-medium', `unit '${descriptor.name}': missing or foreign unit header`)
+  }
+  const version = (unit as Record<string, unknown>)['version'] as number
+  if (version !== descriptor.version) {
+    throw new StorageError(
+      'version-mismatch',
+      `unit '${descriptor.name}': stored version ${version} != expected ${descriptor.version}`,
+    )
+  }
+  if (typeof tables !== 'object' || tables === null) {
+    throw new StorageError('malformed-medium', `unit '${descriptor.name}': tables is not an object`)
+  }
+  const state: UnitState = { version, global: globalValue ?? null, tables: new Map() }
+  for (const table of descriptor.tables) {
+    const records = (tables as Record<string, unknown>)[table]
+    if (records === undefined) {
+      state.tables.set(table, new Map())
+      continue
+    }
+    if (typeof records !== 'object' || records === null || Array.isArray(records)) {
+      throw new StorageError('malformed-medium', `unit '${descriptor.name}': table '${table}' is not an object`)
+    }
+    state.tables.set(table, new Map(Object.entries(records as Record<string, unknown>)))
+  }
+  return state
+}

packages/storage/storage-json/src/index.ts

@@ -0,0 +1,113 @@
+/**
+ * JSON storage backend: one human-readable file per unit under a configured
+ * root, published by atomic whole-file rewrite. Registers as backend `json`
+ * on the storage hub.
+ * @module @deepseek-ai/dsh-storage-json
+ */
+
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { StorageError, UNIT_NAME_RE } from '@deepseek-ai/dsh-storage'
+import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from '@deepseek-ai/dsh-storage'
+import { openJsonUnit } from './unit.ts'
+
+/** Cordis plugin name. */
+export const name = 'storage-json'
+/** The hub must exist before the backend can register. */
+export const inject = ['storage']
+
+/**
+ * Plugin configuration.
+ * `root` has NO default on purpose: a `process.cwd()` fallback would scatter
+ * unit files wherever the process happens to start; assemblies state the
+ * location explicitly.
+ */
+export interface Config {
+  /** Directory holding one `<unit>.json` file per unit. */
+  root: string
+}
+
+/** Config schema. */
+export const Config: z<Config> = z.object({
+  root: z.string().required(),
+})
+
+/** JSON backend: owns the file-tree root and serves the `kv` facet. */
+export class JsonStorageBackend implements StorageBackend {
+  private readonly open = new Map<string, KvUnit>()
+  // Reserved synchronously at open() entry so a concurrent open of the same
+  // unit fails, and close() can await opens still in flight.
+  private readonly opening = new Map<string, Promise<KvUnit>>()
+  private closed = false
+
+  constructor(private readonly root: string) {}
+
+  readonly kv: KvFacet = {
+    // The body up to the first await runs synchronously, so the opening-slot
+    // reservation below still excludes a concurrent open of the same unit.
+    open: async (descriptor: KvUnitDescriptor): Promise<KvUnit> => {
+      if (this.closed) throw new StorageError('closed', 'json backend is closed')
+      validateDescriptor(descriptor)
+      if (this.open.has(descriptor.name) || this.opening.has(descriptor.name)) {
+        // Double-open is a caller bug, not a medium condition.
+        throw new Error(`unit '${descriptor.name}' is already open; a unit has exactly one live handle`)
+      }
+      const opening = this.openUnit(descriptor)
+      this.opening.set(descriptor.name, opening)
+      return opening.finally(() => this.opening.delete(descriptor.name))
+    },
+  }
+
+  private async openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
+    await mkdir(this.root, { recursive: true, mode: 0o700 })
+    const path = join(this.root, `${descriptor.name}.json`)
+    const unit = await openJsonUnit(descriptor, path, () => this.open.delete(descriptor.name))
+    if (this.closed) {
+      // The backend closed while this open was in flight: do not hand out a
+      // live unit past close().
+      await unit.close()
+      throw new StorageError('closed', 'json backend is closed')
+    }
+    this.open.set(descriptor.name, unit)
+    return unit
+  }
+
+  async close(): Promise<void> {
+    if (!this.closed) {
+      this.closed = true
+    }
+    await Promise.allSettled([...this.opening.values()])
+    for (const unit of [...this.open.values()]) {
+      await unit.close()
+    }
+  }
+}
+
+function validateDescriptor(descriptor: KvUnitDescriptor): void {
+  if (!UNIT_NAME_RE.test(descriptor.name)) {
+    throw new StorageError('malformed-medium', `invalid unit name '${descriptor.name}'`)
+  }
+  for (const table of descriptor.tables) {
+    if (!UNIT_NAME_RE.test(table)) {
+      throw new StorageError('malformed-medium', `invalid table name '${table}' in unit '${descriptor.name}'`)
+    }
+  }
+}
+
+/**
+ * Register the `json` backend on the storage hub.
+ * @param ctx - Plugin context.
+ * @param config - Validated configuration.
+ */
+export function apply(ctx: Context, config: Config) {
+  const backend = new JsonStorageBackend(config.root)
+  ctx.effect(() => {
+    const unregister = ctx.storage.backend.register('json', backend)
+    return async () => {
+      unregister()
+      await backend.close()
+    }
+  })
+}

packages/storage/storage-json/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-storage-json`.
+ * @module @deepseek-ai/dsh-storage-json/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-storage-json'
+
+/** Cordis companion plugin name. */
+export const name = 'storage-json-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: correctness here is write-durability and
+ * publish-then-reparse equivalence, which require medium round-trip tests
+ * (the shared backend conformance suite); the backend exposes no continuously
+ * observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/storage/storage-json/src/unit.ts

@@ -0,0 +1,141 @@
+/**
+ * One opened JSON unit. The in-memory state is authoritative; every write
+ * primitive mutates it and republishes the whole file atomically. Writes are
+ * NOT queued here — per the backend contract, write ordering belongs to the
+ * caller (the domain layer's write chain); this unit only guarantees that
+ * each single call publishes a complete, durable file.
+ * @module @deepseek-ai/dsh-storage-json/src/unit
+ */
+
+import { readFile } from 'node:fs/promises'
+import { StorageError } from '@deepseek-ai/dsh-storage'
+import type { KvUnit, KvUnitDescriptor } from '@deepseek-ai/dsh-storage'
+import { writeAtomic } from './atomic.ts'
+import { parse, serialize } from './format.ts'
+import type { UnitState } from './format.ts'
+
+/**
+ * Open (load or lazily create) one unit backed by `path`.
+ * @param descriptor - Static identity and shape of the unit.
+ * @param path - Absolute unit file path under the backend root.
+ * @param onClose - Backend callback releasing the unit's open-slot.
+ * @returns the opened unit.
+ */
+export async function openJsonUnit(
+  descriptor: KvUnitDescriptor,
+  path: string,
+  onClose: () => void,
+): Promise<KvUnit> {
+  let text: string | undefined
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    // Missing file = empty unit; materialization defers to the first write.
+  }
+  const state: UnitState =
+    text === undefined
+      ? {
+        version: descriptor.version,
+        global: null,
+        tables: new Map(descriptor.tables.map(table => [table, new Map<string, unknown>()])),
+      }
+      : parse(text, descriptor)
+  return new JsonKvUnit(descriptor, path, state, onClose)
+}
+
+class JsonKvUnit implements KvUnit {
+  private closed = false
+  /** In-flight publishes; close() drains them before releasing the unit. */
+  private readonly inFlight = new Set<Promise<void>>()
+
+  constructor(
+    private readonly descriptor: KvUnitDescriptor,
+    private readonly path: string,
+    private readonly state: UnitState,
+    private readonly onClose: () => void,
+  ) {}
+
+  // eslint-disable-next-line @typescript-eslint/require-await -- async keeps the closed guard a rejection, not a synchronous throw
+  async loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }> {
+    this.assertOpen()
+    const tables: Record<string, Record<string, unknown>> = {}
+    for (const [table, records] of this.state.tables) {
+      tables[table] = Object.fromEntries(records)
+    }
+    return { tables, global: this.state.global }
+  }
+
+  async putRecord(table: string, key: string, value: unknown): Promise<void> {
+    this.assertOpen()
+    const records = this.records(table)
+    const hadKey = records.has(key)
+    const previous = records.get(key)
+    records.set(key, value)
+    // Roll back on a failed publish: memory is authoritative, so a rejected
+    // write must not survive in memory (or ride along with the next publish).
+    await this.publish().catch((error: unknown) => {
+      if (hadKey) records.set(key, previous)
+      else records.delete(key)
+      throw error
+    })
+  }
+
+  async deleteRecord(table: string, key: string): Promise<void> {
+    this.assertOpen()
+    const records = this.records(table)
+    if (!records.has(key)) return
+    const previous = records.get(key)
+    records.delete(key)
+    await this.publish().catch((error: unknown) => {
+      records.set(key, previous)
+      throw error
+    })
+  }
+
+  async setGlobal(value: unknown): Promise<void> {
+    this.assertOpen()
+    if (!this.descriptor.hasGlobal) {
+      throw new Error(`unit '${this.descriptor.name}' does not declare a global slot`)
+    }
+    const previous = this.state.global
+    this.state.global = value
+    await this.publish().catch((error: unknown) => {
+      this.state.global = previous
+      throw error
+    })
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      await Promise.allSettled(this.inFlight)
+      return
+    }
+    this.closed = true
+    await Promise.allSettled(this.inFlight)
+    this.onClose()
+  }
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new StorageError('closed', `unit '${this.descriptor.name}' is closed`)
+    }
+  }
+
+  private records(table: string): Map<string, unknown> {
+    const records = this.state.tables.get(table)
+    if (!records) {
+      throw new Error(`unit '${this.descriptor.name}' does not declare table '${table}'`)
+    }
+    return records
+  }
+
+  private publish(): Promise<void> {
+    const write = writeAtomic(this.path, serialize(this.descriptor.name, this.state))
+    this.inFlight.add(write)
+    // Swallow only on the tracking branch: the caller still awaits `write`
+    // itself, so rejections stay observed exactly once.
+    write.catch(() => {}).finally(() => this.inFlight.delete(write))
+    return write
+  }
+}

packages/storage/storage-json/tests/json-backend.spec.ts

@@ -0,0 +1,222 @@
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Storage from '@deepseek-ai/dsh-storage'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { runKvBackendContract } from '../../storage/tests/contract.ts'
+import { Config, JsonStorageBackend, apply } from '../src/index.ts'
+import * as InvariantCompanion from '../src/invariant.ts'
+
+const roots: string[] = []
+
+async function freshRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-storage-json-'))
+  roots.push(root)
+  return root
+}
+
+afterAll(async () => {
+  for (const root of roots) await rm(root, { recursive: true, force: true })
+})
+
+runKvBackendContract('json', async () => {
+  const root = await freshRoot()
+  return {
+    backend: new JsonStorageBackend(root),
+    reopen: async () => new JsonStorageBackend(root),
+  }
+})
+
+describe('json backend specifics', () => {
+  const descriptor = { name: 'shape', version: 1, tables: ['t'], hasGlobal: true }
+
+  it('publishes a human-readable pretty-printed file', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    const unit = await backend.kv.open(descriptor)
+    await unit.putRecord('t', 'k', { hello: 'world' })
+    const text = await readFile(join(root, 'shape.json'), 'utf8')
+    expect(text).toBe(`${JSON.stringify(
+      { unit: { name: 'shape', version: 1 }, global: null, tables: { t: { k: { hello: 'world' } } } },
+      null,
+      2,
+    )}\n`)
+    await backend.close()
+  })
+
+  it('defers materialization until the first write', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    await backend.kv.open(descriptor)
+    await expect(readFile(join(root, 'shape.json'), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+    await backend.close()
+  })
+
+  it('rejects a malformed medium', async () => {
+    const root = await freshRoot()
+    await writeFile(join(root, 'shape.json'), 'not json at all', 'utf8')
+    const backend = new JsonStorageBackend(root)
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'malformed-medium' })
+    await backend.close()
+  })
+
+  it('rejects a foreign unit header', async () => {
+    const root = await freshRoot()
+    await writeFile(
+      join(root, 'shape.json'),
+      JSON.stringify({ unit: { name: 'other', version: 1 }, global: null, tables: {} }),
+      'utf8',
+    )
+    const backend = new JsonStorageBackend(root)
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'malformed-medium' })
+    await backend.close()
+  })
+
+  it('rejects double-open of one unit as a plain caller error', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    await backend.kv.open(descriptor)
+    await expect(backend.kv.open(descriptor)).rejects.toThrow(/already open/)
+    await backend.close()
+  })
+
+  it('rolls back memory when a publish fails', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    const unit = await backend.kv.open(descriptor)
+    await unit.putRecord('t', 'k', { v: 'committed' })
+    await unit.setGlobal({ g: 'committed' })
+    // Make every publish fail: revoke write permission on the root.
+    await chmod(root, 0o500)
+    await expect(unit.putRecord('t', 'k', { v: 'rejected' })).rejects.toThrow()
+    await expect(unit.putRecord('t', 'k2', { v: 'also rejected' })).rejects.toThrow()
+    await expect(unit.deleteRecord('t', 'k')).rejects.toThrow()
+    await expect(unit.setGlobal({ g: 'rejected' })).rejects.toThrow()
+    await chmod(root, 0o700)
+    const snapshot = await unit.loadAll()
+    expect(snapshot.tables['t']).toEqual({ k: { v: 'committed' } })
+    expect(snapshot.global).toEqual({ g: 'committed' })
+    // The next successful publish must not carry rejected writes to disk.
+    await unit.putRecord('t', 'k3', { v: 'later' })
+    const text = await readFile(join(root, 'shape.json'), 'utf8')
+    expect(text).not.toContain('rejected')
+    await backend.close()
+  })
+
+  it('rejects undeclared table and global access as caller errors', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    const unit = await backend.kv.open({ name: 'shape', version: 1, tables: ['t'], hasGlobal: false })
+    await expect(unit.putRecord('undeclared', 'k', {})).rejects.toThrow(/does not declare table/)
+    await expect(unit.setGlobal({})).rejects.toThrow(/does not declare a global slot/)
+    await backend.close()
+  })
+
+  it('rejects invalid unit and table names', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    await expect(backend.kv.open({ ...descriptor, name: 'Bad-Name' })).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'malformed-medium',
+    })
+    await expect(backend.kv.open({ ...descriptor, tables: ['ok', 'not ok'] })).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'malformed-medium',
+    })
+    await backend.close()
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'closed' })
+  })
+
+  it('opens a file missing a declared table as that table empty', async () => {
+    const root = await freshRoot()
+    await writeFile(
+      join(root, 'contract_unit.json'),
+      JSON.stringify({ unit: { name: 'contract_unit', version: 3 }, global: null, tables: { alpha: { k: 1 } } }),
+      'utf8',
+    )
+    const backend = new JsonStorageBackend(root)
+    const unit = await backend.kv.open({ name: 'contract_unit', version: 3, tables: ['alpha', 'beta'], hasGlobal: true })
+    const snapshot = await unit.loadAll()
+    expect(snapshot.tables['alpha']).toEqual({ k: 1 })
+    expect(snapshot.tables['beta']).toEqual({})
+    await backend.close()
+  })
+
+  it('propagates non-ENOENT read failures', async () => {
+    const root = await freshRoot()
+    const { mkdir } = await import('node:fs/promises')
+    // A directory where the unit file should be: readFile fails with EISDIR.
+    await mkdir(join(root, 'shape.json'))
+    const backend = new JsonStorageBackend(root)
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'EISDIR' })
+    await backend.close()
+  })
+
+  it('rejects malformed table shapes and foreign versions distinctly', async () => {
+    const root = await freshRoot()
+    await writeFile(
+      join(root, 'shape.json'),
+      JSON.stringify({ unit: { name: 'shape', version: 1 }, global: null, tables: { t: ['not', 'an', 'object'] } }),
+      'utf8',
+    )
+    const backend = new JsonStorageBackend(root)
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'malformed-medium' })
+
+    await writeFile(
+      join(root, 'shape.json'),
+      JSON.stringify({ unit: { name: 'shape', version: 9 }, global: null, tables: {} }),
+      'utf8',
+    )
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'version-mismatch' })
+
+    await writeFile(join(root, 'shape.json'), JSON.stringify({ unit: { name: 'shape', version: 1 }, global: null }), 'utf8')
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'malformed-medium' })
+
+    await writeFile(join(root, 'shape.json'), JSON.stringify('just a string'), 'utf8')
+    await expect(backend.kv.open(descriptor)).rejects.toMatchObject({ code: 'malformed-medium' })
+    await backend.close()
+  })
+
+  it('registers on the hub via apply and closes on dispose', async () => {
+    const root = await freshRoot()
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    const fiber = await ctx.plugin({ apply, Config, inject: ['storage'] }, { root })
+    const backend = ctx.storage.backend.get('json')
+    const unit = await backend.kv!.open(descriptor)
+    await unit.putRecord('t', 'k', { v: 1 })
+    await fiber.dispose()
+    expect(() => ctx.storage.backend.get('json')).toThrow()
+    await expect(unit.putRecord('t', 'x', {})).rejects.toMatchObject({ code: 'closed' })
+  })
+
+  it('registers the invariant companion and disposes cleanly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService)
+    const fiber = await ctx.plugin(InvariantCompanion)
+    // Disposal releases the reservation: a fresh mount succeeds.
+    await fiber.dispose()
+    await ctx.plugin(InvariantCompanion)
+  })
+
+  it('close drains in-flight writes and blocks in-flight opens', async () => {
+    const root = await freshRoot()
+    const backend = new JsonStorageBackend(root)
+    const unit = await backend.kv.open(descriptor)
+    const bigWrite = unit.putRecord('t', 'big', { blob: 'x'.repeat(4 * 1024 * 1024) })
+    await unit.close()
+    await expect(bigWrite).resolves.toBeUndefined()
+    const onDisk = JSON.parse(await readFile(join(root, 'shape.json'), 'utf8')) as {
+      tables: Record<string, Record<string, unknown>>
+    }
+    expect(onDisk.tables['t']?.['big']).toBeDefined()
+
+    const backend2 = new JsonStorageBackend(root)
+    const opening = backend2.kv.open(descriptor)
+    const closing = backend2.close()
+    await expect(opening.then(u => u.putRecord('t', 'x', {}))).rejects.toMatchObject({ code: 'closed' })
+    await closing
+  })
+})

packages/storage/storage-json/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../storage"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/storage/storage-sqlite/README.md

@@ -0,0 +1,41 @@
+# @deepseek-ai/dsh-storage-sqlite
+
+SQLite backend for the [storage hub](../storage/README.md): registers as backend `sqlite`, serving the `kv` facet over one `node:sqlite` database file (or `:memory:`). Design and trade-offs: [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Storage model
+
+Document-per-row: each unit table becomes a physical `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)` STRICT table whose `value` is the record's JSON text, so one key updates one row (the reason to route a high-churn domain here instead of the JSON backend). Unit identity lives in two metadata tables — `units` stamps each unit's format version at first open and rejects a differing descriptor with `version-mismatch`; `unit_globals` holds each unit's global singleton row. The physical layout version lives in `PRAGMA user_version`; any other stamped value rejects (unreleased format, no migrations). Unit and table names are validated against the hub's `UNIT_NAME_RE` before they reach DDL, so no external input is ever interpolated into SQL identifiers.
+
+Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend, whose open sequence this package copies verbatim until the planned media-layer extraction.
+
+## Configuration (schemastery)
+
+```ts
+interface Config {
+  path: string   // SQLite database file path, or ':memory:' for an in-process DB
+  journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
+}
+```
+
+## Model Experience
+
+### Stored domain records
+
+#### What the model sees
+
+Nothing. This backend contributes no prompt, tool, or schema; it persists non-session domain data (workspace records, future session sidecar metadata) behind `ctx.storage` for host-side consumers only.
+
+#### Token effect
+
+Zero live-request tokens.
+
+#### KV Cache effect
+
+None — the backend never touches live request prefixes.
+
+## Known Limitations and Deferred Work
+
+- **`DatabaseSync` is synchronous** — each write blocks the event loop for its (single-statement) duration; acceptable at domain-data scale.
+- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; multi-process write protection is on the design's future-work list.
+- **Only the current `STORAGE_SQLITE_SCHEMA_VERSION` opens** — any other stamped version is rejected rather than migrated (pre-release stance).
+- **`openDatabase` duplicates the session-persistence SQLite open sequence** — extraction into a shared media layer is deferred to the planned session-backend migration (see the Agent Note's reuse audit).

packages/storage/storage-sqlite/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-storage-sqlite",
+  "description": "SQLite storage backend (kv facet) for the DeepSeek Harness storage hub",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/storage/storage-sqlite/src/index.ts

@@ -0,0 +1,167 @@
+/**
+ * SQLite storage backend for the storage hub: one database file hosts every
+ * routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
+ * as backend `sqlite`; the disposer unregisters first, then closes the medium.
+ * @module @deepseek-ai/dsh-storage-sqlite
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { DatabaseSync } from 'node:sqlite'
+import { StorageError, UNIT_NAME_RE } from '@deepseek-ai/dsh-storage'
+import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from '@deepseek-ai/dsh-storage'
+import { openDatabase, recordTableName, type JournalMode } from './schema.ts'
+import { SqliteKvUnit } from './unit.ts'
+
+export { STORAGE_SQLITE_SCHEMA_VERSION, type JournalMode } from './schema.ts'
+
+/** Cordis plugin name. */
+export const name = 'storage-sqlite'
+/** The backend registers on the storage hub. */
+export const inject = ['storage']
+
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing
+   * database fail the open. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
+   * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
+   * where WAL's shared-memory files do not work (network mounts). See
+   * {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+}
+
+/** Schemastery validator for {@link Config}. */
+export const Config: z<Config> = z.object({
+  path: z.string().required(),
+  journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
+})
+
+/**
+ * The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
+ * the open-unit table; `kv.open` validates names, enforces the per-unit
+ * version stamp in `units`, and ensures the unit's record tables.
+ */
+export class SqliteStorageBackend implements StorageBackend {
+  /** The key-value facet; the only shape this backend serves. */
+  readonly kv: KvFacet = { open: descriptor => this.openUnit(descriptor) }
+
+  private readonly ready: Promise<DatabaseSync>
+  /** Open (or still-opening) units by name; presence is the double-open guard. */
+  private readonly units = new Map<string, Promise<SqliteKvUnit>>()
+  private closing: Promise<void> | undefined
+
+  /**
+   * @param config - Validated plugin configuration.
+   */
+  constructor(config: Config) {
+    this.ready = openDatabase(config.path, (config as Required<Config>).journalMode)
+    // Mark the rejection handled: every primitive re-awaits `ready`, so an
+    // open failure still surfaces to each caller; this guard only prevents an
+    // unhandled-rejection crash when the failure precedes the first use.
+    this.ready.catch(() => {})
+  }
+
+  private openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
+    if (this.closing !== undefined) {
+      return Promise.reject(new StorageError('closed', 'sqlite storage backend is closed'))
+    }
+    if (!UNIT_NAME_RE.test(descriptor.name)) {
+      return Promise.reject(new Error(`kv unit name '${descriptor.name}' violates ${UNIT_NAME_RE}`))
+    }
+    for (const table of descriptor.tables) {
+      if (!UNIT_NAME_RE.test(table)) {
+        return Promise.reject(new Error(`kv table name '${table}' in unit '${descriptor.name}' violates ${UNIT_NAME_RE}`))
+      }
+    }
+    if (this.units.has(descriptor.name)) {
+      return Promise.reject(new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`))
+    }
+    // Reserve the name synchronously so a concurrent second open of the same
+    // name rejects instead of racing past the guard during the awaits below.
+    const pending = this.materializeUnit(descriptor)
+    this.units.set(descriptor.name, pending)
+    pending.catch(() => this.units.delete(descriptor.name))
+    return pending
+  }
+
+  private async materializeUnit(descriptor: KvUnitDescriptor): Promise<SqliteKvUnit> {
+    const db = await this.ready
+    const row = db.prepare('SELECT version FROM units WHERE name = ?').get(descriptor.name) as
+      | { version: number }
+      | undefined
+    if (row === undefined) {
+      db.prepare('INSERT INTO units (name, version) VALUES (?, ?)').run(descriptor.name, descriptor.version)
+    } else if (row.version !== descriptor.version) {
+      throw new StorageError(
+        'version-mismatch',
+        `kv unit '${descriptor.name}' is stamped version ${row.version} on the medium, incompatible with descriptor version ${descriptor.version}`,
+      )
+    }
+    for (const table of descriptor.tables) {
+      // Both segments passed UNIT_NAME_RE, so the identifier is safe in DDL.
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS "${recordTableName(descriptor.name, table)}" (
+          key   TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        ) STRICT
+      `)
+    }
+    return new SqliteKvUnit(db, descriptor, () => {
+      this.units.delete(descriptor.name)
+    })
+  }
+
+  /**
+   * Close every open unit and release the database. Idempotent; concurrent
+   * and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void> {
+    this.closing ??= this.doClose()
+    return this.closing
+  }
+
+  private async doClose(): Promise<void> {
+    let db: DatabaseSync
+    try {
+      db = await this.ready
+    } catch {
+      // The medium never opened; that failure already rejected the opener and
+      // every unit call, so there is nothing left to release here.
+      return
+    }
+    for (const pending of [...this.units.values()]) {
+      const unit = await pending.catch(() => undefined)
+      await unit?.close()
+    }
+    db.close()
+  }
+}
+
+/**
+ * Register the SQLite backend as `sqlite` on the storage hub. The disposer
+ * unregisters the name first, then closes the backend.
+ * @param ctx - Plugin context (must inject `storage`).
+ * @param config - Validated plugin configuration.
+ */
+export function apply(ctx: Context, config: Config) {
+  const backend = new SqliteStorageBackend(config)
+  ctx.effect(() => {
+    const dispose = ctx.storage.backend.register('sqlite', backend)
+    return async () => {
+      dispose()
+      await backend.close()
+    }
+  }, 'storage-sqlite.registerBackend')
+}

packages/storage/storage-sqlite/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-storage-sqlite`.
+ * @module @deepseek-ai/dsh-storage-sqlite/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-storage-sqlite'
+
+/** Cordis companion plugin name. */
+export const name = 'storage-sqlite-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: schema-version and unit-version consistency are
+ * open-time checks that reject before a unit exists, and durability needs the
+ * backend round-trip tests in the shared KV conformance suite; this package
+ * exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/storage/storage-sqlite/src/schema.ts

@@ -0,0 +1,120 @@
+/**
+ * Schema + open-time helpers for the SQLite storage backend: the physical
+ * layout version, the database open/configure sequence (permissions, pragmas,
+ * version stamp/reject), and the unit metadata tables. Unit record tables are
+ * created per descriptor in `unit.ts`.
+ * @module @deepseek-ai/dsh-storage-sqlite/schema
+ */
+
+import { DatabaseSync } from 'node:sqlite'
+import { mkdir, open } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { StorageError } from '@deepseek-ai/dsh-storage'
+
+/**
+ * The on-disk physical layout version, stored in `PRAGMA user_version`.
+ * Orthogonal to each unit's own `version` (stamped per unit in the `units`
+ * row). Bumped only on a breaking change to the table layout; any other
+ * stamped version rejects — this unreleased format has no migrations.
+ */
+export const STORAGE_SQLITE_SCHEMA_VERSION = 1
+
+/**
+ * Journal modes the backend will run under. `wal` is the default; the
+ * rollback-journal modes (`delete`/`truncate`/`persist`) exist for
+ * filesystems where WAL's shared-memory files do not work (network mounts).
+ * `memory`/`off` are excluded: dropping journal durability silently
+ * contradicts the durability clause of the KV backend contract.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+
+/* jscpd:ignore-start -- deliberately mirrors the session-persistence-sqlite /
+   session-query-sqlite open sequence; this group is the third user, and the
+   shared medium helper is deferred to the log-facet migration so the session
+   packages stay untouched this phase (see the domain KV storage Agent Note's
+   reuse audit). */
+/**
+ * Exclusively create a missing database file with owner-only permissions.
+ * Existing files retain their modes, and errors other than `EEXIST` propagate.
+ * `DatabaseSync` reopens by path, so this does not protect confidentiality or
+ * integrity when another principal can replace the database entry in its
+ * parent directory.
+ */
+async function createDatabaseFile(path: string): Promise<void> {
+  try {
+    const handle = await open(path, 'wx', 0o600)
+    await handle.close()
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+  }
+}
+
+/**
+ * Open the database and apply its schema and pragmas. Missing directories and
+ * database files are created owner-only (`:memory:` skips filesystem setup).
+ * A zero `user_version` is stamped with {@link STORAGE_SQLITE_SCHEMA_VERSION};
+ * every other non-current version rejects rather than being migrated in place.
+ * @param path - the SQLite database file to open, or `:memory:`.
+ * @param journalMode - validated journal pragma.
+ * @returns the open handle with pragmas applied and the unit metadata tables ensured.
+ */
+export async function openDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync> {
+  const actual = path === ':memory:' ? path : resolve(path)
+  if (actual !== ':memory:') {
+    await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+    await createDatabaseFile(actual)
+  }
+  const db = new DatabaseSync(actual)
+  try {
+    configureDatabase(db, actual, journalMode)
+    return db
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalMode): void {
+  db.exec('PRAGMA foreign_keys = ON')
+  // The validated union is safe to interpolate into a non-bindable PRAGMA.
+  db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
+  // `PRAGMA user_version` always returns exactly one row { user_version }.
+  const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+  if (onDisk !== 0 && onDisk !== STORAGE_SQLITE_SCHEMA_VERSION) {
+    throw new StorageError(
+      'version-mismatch',
+      `storage database at "${path}" has schema version ${onDisk}, incompatible with this build (${STORAGE_SQLITE_SCHEMA_VERSION})`,
+    )
+  }
+  /* jscpd:ignore-end */
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS units (
+      name    TEXT PRIMARY KEY,
+      version INTEGER NOT NULL
+    ) STRICT
+  `)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS unit_globals (
+      unit  TEXT PRIMARY KEY REFERENCES units(name),
+      value TEXT NOT NULL
+    ) STRICT
+  `)
+  if (onDisk === 0) {
+    // Stamp fresh databases LAST: the stamp asserts the layout is complete,
+    // so a failure above must leave the medium unstamped (a re-open after
+    // the obstruction is cleared retries materialization from scratch).
+    db.exec(`PRAGMA user_version = ${STORAGE_SQLITE_SCHEMA_VERSION}`)
+  }
+}
+
+/**
+ * Physical table name for one unit table. Both segments are validated against
+ * `UNIT_NAME_RE` before reaching this, so the result is safe to interpolate
+ * into DDL and prepared-statement text.
+ * @param unit - Validated unit name.
+ * @param table - Validated table name.
+ * @returns the `u_<unit>_<table>` identifier.
+ */
+export function recordTableName(unit: string, table: string): string {
+  return `u_${unit}_${table}`
+}

packages/storage/storage-sqlite/src/unit.ts

@@ -0,0 +1,156 @@
+/**
+ * One opened SQLite KV unit: prepared per-table statements over the
+ * `u_<unit>_<table>` record tables plus this unit's row in the shared
+ * `unit_globals` table. Each primitive is a single statement, so atomicity
+ * comes from SQLite itself — no explicit transactions, and no write queue
+ * (write ordering is the caller's responsibility per the KV contract).
+ * @module @deepseek-ai/dsh-storage-sqlite/unit
+ */
+
+import type { DatabaseSync, StatementSync } from 'node:sqlite'
+import { StorageError } from '@deepseek-ai/dsh-storage'
+import type { KvUnit, KvUnitDescriptor } from '@deepseek-ai/dsh-storage'
+import { recordTableName } from './schema.ts'
+
+/** Prepared statements for one declared table. */
+interface TableStatements {
+  upsert: StatementSync
+  remove: StatementSync
+  selectAll: StatementSync
+}
+
+/**
+ * The SQLite {@link KvUnit}. Constructed by the backend AFTER the unit's
+ * record tables exist; statements are prepared once here and reused for every
+ * primitive. Values are stored as JSON text in the `value` column.
+ */
+export class SqliteKvUnit implements KvUnit {
+  private readonly tables = new Map<string, TableStatements>()
+  private readonly globalUpsert: StatementSync | undefined
+  private readonly globalSelect: StatementSync | undefined
+  private closed = false
+
+  /**
+   * @param db - Open database handle owned by the backend (never closed here).
+   * @param descriptor - Validated descriptor whose record tables already exist.
+   * @param onClose - Backend callback releasing this unit's open-name slot.
+   */
+  constructor(
+    db: DatabaseSync,
+    private readonly descriptor: KvUnitDescriptor,
+    private readonly onClose: () => void,
+  ) {
+    for (const table of descriptor.tables) {
+      // Both name segments are validated against UNIT_NAME_RE by the backend,
+      // so the physical identifier is safe to interpolate into statement text.
+      const physical = recordTableName(descriptor.name, table)
+      this.tables.set(table, {
+        upsert: db.prepare(
+          `INSERT INTO "${physical}" (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+        ),
+        remove: db.prepare(`DELETE FROM "${physical}" WHERE key = ?`),
+        selectAll: db.prepare(`SELECT key, value FROM "${physical}"`),
+      })
+    }
+    this.globalUpsert = descriptor.hasGlobal
+      ? db.prepare(
+        'INSERT INTO unit_globals (unit, value) VALUES (?, ?) ON CONFLICT(unit) DO UPDATE SET value = excluded.value',
+      )
+      : undefined
+    this.globalSelect = descriptor.hasGlobal
+      ? db.prepare('SELECT value FROM unit_globals WHERE unit = ?')
+      : undefined
+  }
+
+  loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }> {
+    return this.settle(() => {
+      const tables: Record<string, Record<string, unknown>> = {}
+      for (const [name, statements] of this.tables) {
+        // Null prototype: record keys are arbitrary strings, so '__proto__'
+        // must land as an own property instead of mutating the prototype.
+        const records: Record<string, unknown> = Object.create(null) as Record<string, unknown>
+        for (const row of statements.selectAll.all() as unknown as Array<{ key: string; value: string }>) {
+          records[row.key] = this.parseValue(row.value, `table '${name}' key '${row.key}'`)
+        }
+        tables[name] = records
+      }
+      let global: unknown = null
+      if (this.globalSelect !== undefined) {
+        const row = this.globalSelect.get(this.descriptor.name) as { value: string } | undefined
+        if (row !== undefined) global = this.parseValue(row.value, 'global slot')
+      }
+      return { tables, global }
+    })
+  }
+
+  /** Parse one stored value column, mapping bad JSON to `malformed-medium`. */
+  private parseValue(text: string, slot: string): unknown {
+    try {
+      return JSON.parse(text)
+    } catch (error) {
+      throw new StorageError(
+        'malformed-medium',
+        `kv unit '${this.descriptor.name}' holds unparsable JSON at ${slot}`,
+        { cause: error },
+      )
+    }
+  }
+
+  putRecord(table: string, key: string, value: unknown): Promise<void> {
+    return this.settle(() => {
+      this.statementsFor(table).upsert.run(key, JSON.stringify(value))
+    })
+  }
+
+  deleteRecord(table: string, key: string): Promise<void> {
+    return this.settle(() => {
+      this.statementsFor(table).remove.run(key)
+    })
+  }
+
+  setGlobal(value: unknown): Promise<void> {
+    return this.settle(() => {
+      if (this.globalUpsert === undefined) {
+        throw new Error(`kv unit '${this.descriptor.name}' declared no global slot`)
+      }
+      this.globalUpsert.run(this.descriptor.name, JSON.stringify(value))
+    })
+  }
+
+  close(): Promise<void> {
+    if (!this.closed) {
+      this.closed = true
+      this.onClose()
+    }
+    return Promise.resolve()
+  }
+
+  /**
+   * Run one synchronous primitive behind the closed guard, mapping a throw to
+   * a rejection so the Promise-returning contract never throws synchronously.
+   */
+  private settle<T>(operation: () => T): Promise<T> {
+    try {
+      this.ensureOpen()
+      return Promise.resolve(operation())
+    } catch (error) {
+      // Non-Error throws can only enter through JSON.stringify propagating a
+      // value's own toJSON throw; wrap those, preserve every real Error.
+      return Promise.reject(error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+
+  private ensureOpen(): void {
+    if (this.closed) {
+      throw new StorageError('closed', `kv unit '${this.descriptor.name}' is closed`)
+    }
+  }
+
+  private statementsFor(table: string): TableStatements {
+    const statements = this.tables.get(table)
+    if (statements === undefined) {
+      throw new Error(`kv unit '${this.descriptor.name}' declared no table '${table}'`)
+    }
+    return statements
+  }
+}

packages/storage/storage-sqlite/tests/invariant.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as StorageSqliteInvariant from '../src/invariant.ts'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an explained-empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(StorageSqliteInvariant).await()).resolves.toBeDefined()
+  })
+})

packages/storage/storage-sqlite/tests/sqlite-backend.spec.ts

@@ -0,0 +1,263 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import Storage from '@deepseek-ai/dsh-storage'
+import type { KvUnitDescriptor } from '@deepseek-ai/dsh-storage'
+import { runKvBackendContract } from '../../storage/tests/contract.ts'
+import * as StorageSqlite from '../src/index.ts'
+import { Config, SqliteStorageBackend, STORAGE_SQLITE_SCHEMA_VERSION } from '../src/index.ts'
+
+/** Mirror the loader: resolve schemastery defaults before construction. */
+function backendAt(path: string): SqliteStorageBackend {
+  return new SqliteStorageBackend(new Config({ path }))
+}
+
+const dirs: string[] = []
+afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
+
+async function freshDbPath(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-storage-sqlite-'))
+  dirs.push(dir)
+  return join(dir, 'storage.db')
+}
+
+// The contract suite's reopen() needs a surviving medium, so the harness binds
+// a real file; :memory: gets its own cases below.
+runKvBackendContract('sqlite', async () => {
+  const path = await freshDbPath()
+  return {
+    backend: backendAt(path),
+    reopen: async () => backendAt(path),
+  }
+})
+
+const DESCRIPTOR: KvUnitDescriptor = {
+  name: 'specimen',
+  version: 1,
+  tables: ['records'],
+  hasGlobal: true,
+}
+
+describe('sqlite backend specifics', () => {
+  it('opens an in-memory database', async () => {
+    const backend = backendAt(':memory:')
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', 'k', { n: 1 })
+    expect((await unit.loadAll()).tables['records']).toEqual({ k: { n: 1 } })
+    await backend.close()
+  })
+
+  it('materializes STRICT record tables and stamps the schema version', async () => {
+    const path = await freshDbPath()
+    const backend = backendAt(path)
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', 'k', { n: 1 })
+    await backend.close()
+
+    const db = new DatabaseSync(path)
+    try {
+      const { user_version: version } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+      expect(version).toBe(STORAGE_SQLITE_SCHEMA_VERSION)
+      const table = db.prepare(
+        "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'u_specimen_records'",
+      ).get() as { sql: string } | undefined
+      expect(table?.sql).toContain('STRICT')
+      const unitRow = db.prepare('SELECT version FROM units WHERE name = ?').get('specimen') as { version: number }
+      expect(unitRow.version).toBe(DESCRIPTOR.version)
+    } finally {
+      db.close()
+    }
+  })
+
+  it('rejects a mismatched database schema version', async () => {
+    const path = await freshDbPath()
+    const db = new DatabaseSync(path)
+    db.exec('PRAGMA user_version = 999')
+    db.close()
+
+    const backend = backendAt(path)
+    await expect(backend.kv.open(DESCRIPTOR)).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'version-mismatch',
+    })
+    await backend.close()
+  })
+
+  it('rejects invalid unit and table names before touching the medium', async () => {
+    const backend = backendAt(':memory:')
+    await expect(backend.kv.open({ ...DESCRIPTOR, name: 'Bad-Name' })).rejects.toThrow(/violates/)
+    await expect(backend.kv.open({ ...DESCRIPTOR, tables: ['ok', '1bad'] })).rejects.toThrow(/violates/)
+    await backend.close()
+  })
+
+  it('rejects a second open of the same unit name', async () => {
+    const backend = backendAt(':memory:')
+    await backend.kv.open(DESCRIPTOR)
+    await expect(backend.kv.open(DESCRIPTOR)).rejects.toThrow(/already open/)
+    await backend.close()
+  })
+
+  it('allows re-open after unit close, and rejects open on a closed backend', async () => {
+    const backend = backendAt(':memory:')
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.close()
+    const again = await backend.kv.open(DESCRIPTOR)
+    await again.putRecord('records', 'k', 1)
+    await backend.close()
+    await expect(backend.kv.open(DESCRIPTOR)).rejects.toMatchObject({ code: 'closed' })
+  })
+
+  it('round-trips prototype-polluting keys as own properties', async () => {
+    const backend = backendAt(':memory:')
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', '__proto__', { evil: true })
+    await unit.putRecord('records', 'constructor', { n: 1 })
+    const { tables } = await unit.loadAll()
+    const records = tables['records']!
+    expect(Object.hasOwn(records, '__proto__')).toBe(true)
+    expect(records['__proto__']).toEqual({ evil: true })
+    expect(records['constructor']).toEqual({ n: 1 })
+    expect(Object.getPrototypeOf({})).not.toHaveProperty('evil')
+    await backend.close()
+  })
+
+  it('leaves a failed materialization unstamped so a repaired medium reopens', async () => {
+    const path = await freshDbPath()
+    // Obstruct table creation: an index squatting on the unit_globals name
+    // makes CREATE TABLE IF NOT EXISTS throw AFTER the units table exists.
+    const setup = new DatabaseSync(path)
+    setup.exec('CREATE TABLE squatter (x TEXT)')
+    setup.exec('CREATE INDEX unit_globals ON squatter(x)')
+    setup.close()
+
+    const broken = backendAt(path)
+    await expect(broken.kv.open(DESCRIPTOR)).rejects.toThrow(/already an index/)
+    await broken.close()
+
+    // Clear the obstruction; the medium must still be version 0, not a
+    // half-materialized database stamped as current.
+    const repair = new DatabaseSync(path)
+    expect((repair.prepare('PRAGMA user_version').get() as { user_version: number }).user_version).toBe(0)
+    repair.exec('DROP INDEX unit_globals')
+    repair.close()
+
+    const backend = backendAt(path)
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', 'k', { n: 1 })
+    await backend.close()
+  })
+
+  it('rejects unparsable stored JSON with malformed-medium', async () => {
+    const path = await freshDbPath()
+    const backend = backendAt(path)
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', 'good', { n: 1 })
+    await unit.setGlobal({ g: 1 })
+    await backend.close()
+
+    const db = new DatabaseSync(path)
+    db.prepare('UPDATE u_specimen_records SET value = ? WHERE key = ?').run('{not json', 'good')
+    db.close()
+
+    const reopened = backendAt(path)
+    const damaged = await reopened.kv.open(DESCRIPTOR)
+    await expect(damaged.loadAll()).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'malformed-medium',
+    })
+    await reopened.close()
+  })
+
+  it('wraps a non-Error toJSON throw into an Error rejection', async () => {
+    const backend = backendAt(':memory:')
+    const unit = await backend.kv.open(DESCRIPTOR)
+    // JSON.stringify propagates a value's own toJSON throw verbatim; the unit
+    // must still reject with an Error instance.
+    const hostile = { toJSON: () => { throw 'not an error' } }
+    await expect(unit.putRecord('records', 'k', hostile)).rejects.toThrow('not an error')
+    await expect(unit.putRecord('records', 'k', hostile)).rejects.toBeInstanceOf(Error)
+    await backend.close()
+  })
+
+  it('rejects setGlobal on a unit without a global slot and writes to undeclared tables', async () => {
+    const backend = backendAt(':memory:')
+    const unit = await backend.kv.open({ ...DESCRIPTOR, hasGlobal: false })
+    await expect(unit.setGlobal({ g: 1 })).rejects.toThrow(/declared no global slot/)
+    await expect(unit.putRecord('undeclared', 'k', 1)).rejects.toThrow(/declared no table/)
+    expect((await unit.loadAll()).global).toBeNull()
+    await backend.close()
+  })
+
+  it('drains a still-pending failed open during close', async () => {
+    const path = await freshDbPath()
+    const first = backendAt(path)
+    await (await first.kv.open(DESCRIPTOR)).close()
+    await first.close()
+
+    const backend = backendAt(path)
+    // Do not await: close() must tolerate an in-flight open that will reject
+    // (version mismatch) while its name is still reserved in the unit table.
+    const pending = backend.kv.open({ ...DESCRIPTOR, version: 99 })
+    const closed = backend.close()
+    await expect(pending).rejects.toMatchObject({ code: 'version-mismatch' })
+    await closed
+  })
+
+  it('propagates filesystem errors other than an existing database file', async () => {
+    if (process.platform === 'win32') return
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-storage-sqlite-'))
+    dirs.push(dir)
+    await chmod(dir, 0o500)
+    const backend = backendAt(join(dir, 'storage.db'))
+    await expect(backend.kv.open(DESCRIPTOR)).rejects.toMatchObject({ code: 'EACCES' })
+    await backend.close()
+    await chmod(dir, 0o700)
+  })
+
+  it('preserves the mode of an existing database file', async () => {
+    if (process.platform === 'win32') return
+    const path = await freshDbPath()
+    await writeFile(path, '', { mode: 0o644 })
+    await chmod(path, 0o644)
+    const backend = backendAt(path)
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.putRecord('records', 'k', 1)
+    await backend.close()
+  })
+
+  it('registers on the storage hub as backend sqlite and closes on dispose', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    const fiber = await ctx.plugin(StorageSqlite, { path: ':memory:' })
+    const backend = ctx.storage.backend.get('sqlite')
+    const unit = await backend.kv!.open(DESCRIPTOR)
+    await unit.putRecord('records', 'k', { n: 1 })
+
+    await fiber.dispose()
+    expect(ctx.storage.backend.names()).toEqual([])
+    await expect(backend.kv!.open(DESCRIPTOR)).rejects.toMatchObject({ code: 'closed' })
+  })
+
+  it('rejects an unparsable global slot with malformed-medium', async () => {
+    const path = await freshDbPath()
+    const backend = backendAt(path)
+    const unit = await backend.kv.open(DESCRIPTOR)
+    await unit.setGlobal({ g: 1 })
+    await backend.close()
+
+    const db = new DatabaseSync(path)
+    db.prepare('UPDATE unit_globals SET value = ? WHERE unit = ?').run('][', 'specimen')
+    db.close()
+
+    const reopened = backendAt(path)
+    const damaged = await reopened.kv.open(DESCRIPTOR)
+    await expect(damaged.loadAll()).rejects.toMatchObject({
+      name: 'StorageError',
+      code: 'malformed-medium',
+    })
+    await reopened.close()
+  })
+})

packages/storage/storage-sqlite/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../storage"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/storage/storage/README.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-storage
+
+Storage hub (`ctx.storage`) for non-session data: a named backend registry plus mounted data-form facilities. The hub performs no IO itself — backends own media, data forms own semantics. Design and trade-offs: [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Shape
+
+- `ctx.storage.backend` — name → backend table. Multiple backends stay mounted side by side (`json`, `sqlite`); which backend serves a consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register()` returns the disposer; duplicate names and unknown lookups fail loud.
+- `ctx.storage.mount(form, facility)` / `ctx.storage.form(form)` — data-form mounting. `StorageForms` is merge-extensible; the domain layer merges `domain` and is reached as `ctx.storage.domain`.
+- A backend owns one medium (file-tree root, database file) and exposes optional data-shape **facets** — `kv` today; an append-log facet is reserved for the future session-backend migration. `src/backend.ts` is the normative contract text; `tests/contract.ts` exports the shared conformance suite every backend runs.
+
+## Packages in this group
+
+| Package | Role |
+| --- | --- |
+| `dsh-storage` | The hub service + backend vocabulary + shared conformance suite |
+| `dsh-storage-json` | JSON backend: one unit per human-readable file, atomic whole-file rewrite |
+| `dsh-storage-sqlite` | SQLite backend: one database hosting all routed units, document-per-row |
+| `dsh-storage-domain` | Domain data form (`ctx.storage.domain`): typed schemas, write chain, change events |
+
+## Model Experience
+
+### Backend and form registrations
+
+#### What the model sees
+
+Nothing. `ctx.storage` is a host-side registration table; the hub registers no tools, injects no prompts, and writes no session events.
+
+#### Token effect
+
+Zero direct tokens on every request.
+
+#### KV Cache effect
+
+Independent of live requests: the hub never touches a request prefix, so it cannot invalidate provider cache reuse.
+
+## Known Limitations and Deferred Work
+
+- **`kv` is the only data shape** — the append-log facet the future session-backend migration needs is reserved in the design note but not yet defined; backends currently have exactly one facet to implement.
+- **Forms resolve lazily** — reading `ctx.storage.domain` before the domain plugin mounts throws `form-not-mounted`; assemblies order plugins accordingly (misconfiguration fails loud rather than silently deferring).

packages/storage/storage/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-storage",
+  "description": "Storage hub (ctx.storage): named backend registry plus mounted data-form facilities for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/storage/storage/src/backend.ts

@@ -0,0 +1,104 @@
+/**
+ * Backend-facing vocabulary of the storage hub: a backend owns one medium
+ * (a file-tree root, a database file) and exposes data-shape facets over it.
+ * This module is the normative contract text for backend implementers; the
+ * shared conformance suite in `tests/contract.ts` asserts every clause.
+ * @module @deepseek-ai/dsh-storage/src/backend
+ */
+
+/** Allowed shape for unit and table names: safe as a file name and as a SQL identifier segment without escaping. */
+export const UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/
+
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a shape simply omits it, and resolution fails loud instead.
+ */
+export interface StorageBackend {
+  /** Key-value data shape; absent when this backend cannot serve it. */
+  readonly kv?: KvFacet
+
+  /**
+   * Drain in-flight writes across all open units and release the medium.
+   * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void>
+}
+
+/** The key-value data shape: whole-unit snapshots plus per-record durable writes. */
+export interface KvFacet {
+  /**
+   * Open one unit, creating it when the medium holds no trace of it yet
+   * (materialization may defer to the first write, but {@link KvUnit.loadAll}
+   * must immediately serve the empty shape). A version already stamped on the
+   * medium that differs from `descriptor.version` rejects with
+   * `version-mismatch`; a medium that cannot be parsed as this unit rejects
+   * with `malformed-medium`. Opening the same unit name twice without closing
+   * is a caller bug and rejects.
+   * @param descriptor - Static identity and shape of the unit to open.
+   * @returns the opened unit.
+   */
+  open(descriptor: KvUnitDescriptor): Promise<KvUnit>
+}
+
+/** Static identity and shape of one KV unit, projected from its owner's spec. */
+export interface KvUnitDescriptor {
+  /** Unit name; must match {@link UNIT_NAME_RE}. Also the file-name / SQL-identifier segment. */
+  readonly name: string
+  /** Unit format version; a non-negative integer stamped on the medium at first materialization. */
+  readonly version: number
+  /** Table names; each must match {@link UNIT_NAME_RE}. */
+  readonly tables: readonly string[]
+  /** Whether this unit carries the global singleton slot. */
+  readonly hasGlobal: boolean
+}
+
+/**
+ * One opened unit. Values are opaque JSON to this layer: no schema, no
+ * events, no domain meaning. The unit does NOT serialize concurrent writes —
+ * write ordering is the caller's responsibility (the domain layer runs one
+ * write chain per unit); the unit only guarantees that each single call is
+ * atomic on the medium and durable once resolved (a crash after resolution
+ * followed by a re-open observes the write). Any call after {@link close}
+ * rejects with `closed`.
+ */
+export interface KvUnit {
+  /**
+   * Read the full current snapshot.
+   * @returns every table's records keyed by table name, plus the global
+   * singleton (`null` when never written or not declared).
+   */
+  loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }>
+
+  /**
+   * Upsert one record durably. Overwrite semantics: an existing key is replaced.
+   * @param table - Declared table name.
+   * @param key - Record key; any string is safe (keys never reach file paths).
+   * @param value - Opaque JSON-serializable record.
+   * @returns resolution after durability.
+   */
+  putRecord(table: string, key: string, value: unknown): Promise<void>
+
+  /**
+   * Delete one record durably. Idempotent: a missing key is a no-op.
+   * @param table - Declared table name.
+   * @param key - Record key.
+   * @returns resolution after durability.
+   */
+  deleteRecord(table: string, key: string): Promise<void>
+
+  /**
+   * Write the global singleton durably. Only valid when the descriptor
+   * declared `hasGlobal`.
+   * @param value - Opaque JSON-serializable value.
+   * @returns resolution after durability.
+   */
+  setGlobal(value: unknown): Promise<void>
+
+  /**
+   * Drain this unit's in-flight writes and release it. Idempotent.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}

packages/storage/storage/src/error.ts

@@ -0,0 +1,35 @@
+/**
+ * Error vocabulary for the storage hub and its backends.
+ * @module @deepseek-ai/dsh-storage/src/error
+ */
+
+/** Discriminant codes carried by every {@link StorageError}. */
+export type StorageErrorCode =
+  | 'backend-not-found'
+  | 'form-not-mounted'
+  | 'duplicate-backend'
+  | 'duplicate-mount'
+  | 'version-mismatch'
+  | 'malformed-medium'
+  | 'closed'
+
+/**
+ * Error thrown by the hub and by backend implementations. The `code` is the
+ * stable contract consumers may switch on; `message` is diagnostic prose.
+ */
+export class StorageError extends Error {
+  override readonly name = 'StorageError'
+
+  /**
+   * @param code - Stable discriminant for the failure class.
+   * @param message - Human-readable diagnostic detail.
+   * @param options - Standard error options (`cause`).
+   */
+  constructor(
+    readonly code: StorageErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+}

packages/storage/storage/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Storage hub (`ctx.storage`): a named backend registry plus mounted
+ * data-form facilities. The hub itself performs no IO — backends own media,
+ * data forms (the domain layer first) own semantics.
+ * @module @deepseek-ai/dsh-storage
+ */
+
+import { Context, Service } from 'cordis'
+import { StorageError } from './error.ts'
+import { BackendRegistry } from './registry.ts'
+
+export { BackendRegistry } from './registry.ts'
+export { StorageError } from './error.ts'
+export type { StorageErrorCode } from './error.ts'
+export { UNIT_NAME_RE } from './backend.ts'
+export type { StorageBackend, KvFacet, KvUnit, KvUnitDescriptor } from './backend.ts'
+
+declare module 'cordis' {
+  interface Context {
+    storage: Storage
+  }
+}
+
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+export interface StorageForms {}
+
+/**
+ * The storage hub service. Backends register under `backend`; data forms
+ * mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+ */
+export class Storage extends Service {
+  /** Named backend table; multiple backends stay mounted side by side. */
+  readonly backend = new BackendRegistry()
+
+  private readonly forms = new Map<keyof StorageForms, unknown>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'storage')
+  }
+
+  /**
+   * Mount a data-form facility on the hub. Mounting is an effect: the
+   * returned disposer unmounts the form.
+   * @param form - Form key declared in {@link StorageForms}.
+   * @param facility - The facility instance to expose.
+   * @returns the disposer that unmounts the form.
+   */
+  mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void {
+    if (this.forms.has(form)) {
+      throw new StorageError('duplicate-mount', `storage form '${String(form)}' is already mounted`)
+    }
+    this.forms.set(form, facility)
+    return () => {
+      // Same stale-disposer guard as BackendRegistry.register.
+      if (this.forms.get(form) === facility) {
+        this.forms.delete(form)
+      }
+    }
+  }
+
+  /**
+   * Resolve a mounted data form.
+   * @param form - Form key declared in {@link StorageForms}.
+   * @returns the mounted facility.
+   */
+  form<K extends keyof StorageForms>(form: K): StorageForms[K] {
+    if (!this.forms.has(form)) {
+      throw new StorageError('form-not-mounted', `storage form '${String(form)}' is not mounted`)
+    }
+    return this.forms.get(form) as StorageForms[K]
+  }
+
+  /** Domain data form; present once the domain layer plugin is loaded. */
+  get domain(): StorageForms extends { domain: infer D } ? D : never {
+    return this.form('domain' as keyof StorageForms)
+  }
+}
+
+// Service packages default-export their service class and nothing else
+// plugin-shaped (packages/AGENTS.md): mixing a default export with a
+// function-plugin `apply` makes the Loader drop the plugin namespace.
+export default Storage

packages/storage/storage/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-storage`.
+ * @module @deepseek-ai/dsh-storage/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-storage'
+
+/** Cordis companion plugin name. */
+export const name = 'storage-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the hub is a pure registration table (names →
+ * backends, forms → facilities) whose consistency is fully enforced at the
+ * call sites (duplicate/missing entries fail loud synchronously); it owns no
+ * event stream or mutable medium to cross-check.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/storage/storage/src/registry.ts

@@ -0,0 +1,62 @@
+/**
+ * Named backend registry of the storage hub.
+ * @module @deepseek-ai/dsh-storage/src/registry
+ */
+
+import type { StorageBackend } from './backend.ts'
+import { StorageError } from './error.ts'
+
+/**
+ * Mutable name → backend table. Multiple backends stay mounted side by side;
+ * which backend serves which consumer is the consumer's configuration
+ * (e.g. the domain layer's route table), never a hub-global choice.
+ */
+export class BackendRegistry {
+  private readonly backends = new Map<string, StorageBackend>()
+
+  /**
+   * Register a named backend. Registration is an effect: the returned
+   * disposer removes the name. Disposal does NOT close the backend — the
+   * owning plugin closes it after unregistering.
+   * @param name - Backend name, e.g. `json` or `sqlite`.
+   * @param backend - The backend instance.
+   * @returns the disposer that unregisters the name.
+   */
+  register(name: string, backend: StorageBackend): () => void {
+    if (this.backends.has(name)) {
+      throw new StorageError('duplicate-backend', `storage backend '${name}' is already registered`)
+    }
+    this.backends.set(name, backend)
+    return () => {
+      // Remove only this registration's contribution: after dispose + re-register,
+      // a stale disposer firing again must not remove the successor.
+      if (this.backends.get(name) === backend) {
+        this.backends.delete(name)
+      }
+    }
+  }
+
+  /**
+   * Resolve a backend by name.
+   * @param name - Registered backend name.
+   * @returns the backend.
+   */
+  get(name: string): StorageBackend {
+    const backend = this.backends.get(name)
+    if (!backend) {
+      throw new StorageError(
+        'backend-not-found',
+        `storage backend '${name}' is not registered (registered: ${[...this.backends.keys()].join(', ') || 'none'})`,
+      )
+    }
+    return backend
+  }
+
+  /**
+   * Registered backend names, for diagnostics.
+   * @returns a snapshot array of names.
+   */
+  names(): string[] {
+    return [...this.backends.keys()]
+  }
+}

packages/storage/storage/tests/contract.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared KV-backend conformance suite. Each backend's spec file calls
+ * {@link runKvBackendContract} with a factory bound to its own medium; the
+ * suite asserts every clause of the `src/backend.ts` contract so both
+ * backends are held to identical semantics.
+ * @module
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { KvUnitDescriptor, StorageBackend } from '../src/backend.ts'
+
+/** One conformance run: a fresh backend plus a way to reopen the same medium (crash simulation). */
+export interface KvBackendContractHarness {
+  /** The backend under test, freshly created over an empty medium. */
+  backend: StorageBackend
+  /** Open a NEW backend instance over the SAME medium, as after a process restart. */
+  reopen(): Promise<StorageBackend>
+}
+
+const DESCRIPTOR: KvUnitDescriptor = {
+  name: 'contract_unit',
+  version: 3,
+  tables: ['alpha', 'beta'],
+  hasGlobal: true,
+}
+
+/**
+ * Run the shared conformance suite against one backend implementation.
+ * @param label - Suite label, e.g. `json` / `sqlite`.
+ * @param create - Factory producing a fresh harness per test.
+ */
+export function runKvBackendContract(label: string, create: () => Promise<KvBackendContractHarness>) {
+  describe(`kv backend contract: ${label}`, () => {
+    it('opens a missing unit as empty and serves loadAll immediately', async () => {
+      const { backend } = await create()
+      const unit = await backend.kv!.open(DESCRIPTOR)
+      const snapshot = await unit.loadAll()
+      expect(snapshot.tables).toEqual({ alpha: {}, beta: {} })
+      expect(snapshot.global).toBeNull()
+      await backend.close()
+    })
+
+    it('round-trips records and global durably across reopen', async () => {
+      const harness = await create()
+      const unit = await harness.backend.kv!.open(DESCRIPTOR)
+      await unit.putRecord('alpha', 'k1', { n: 1 })
+      await unit.putRecord('alpha', 'k2', { n: 2 })
+      await unit.putRecord('beta', 'weird key / with:stuff', { ok: true })
+      await unit.setGlobal({ counter: 7 })
+      await harness.backend.close()
+
+      const reopened = await harness.reopen()
+      const unit2 = await reopened.kv!.open(DESCRIPTOR)
+      const snapshot = await unit2.loadAll()
+      expect(snapshot.tables['alpha']).toEqual({ k1: { n: 1 }, k2: { n: 2 } })
+      expect(snapshot.tables['beta']).toEqual({ 'weird key / with:stuff': { ok: true } })
+      expect(snapshot.global).toEqual({ counter: 7 })
+      await reopened.close()
+    })
+
+    it('putRecord overwrites and deleteRecord is idempotent', async () => {
+      const { backend } = await create()
+      const unit = await backend.kv!.open(DESCRIPTOR)
+      await unit.putRecord('alpha', 'k', { v: 'old' })
+      await unit.putRecord('alpha', 'k', { v: 'new' })
+      await unit.deleteRecord('alpha', 'k')
+      await unit.deleteRecord('alpha', 'k')
+      await unit.deleteRecord('alpha', 'never-existed')
+      const snapshot = await unit.loadAll()
+      expect(snapshot.tables['alpha']).toEqual({})
+      await backend.close()
+    })
+
+    it('rejects a version mismatch on reopen without touching the data', async () => {
+      const harness = await create()
+      const unit = await harness.backend.kv!.open(DESCRIPTOR)
+      await unit.putRecord('alpha', 'k', { v: 1 })
+      await harness.backend.close()
+
+      const reopened = await harness.reopen()
+      await expect(reopened.kv!.open({ ...DESCRIPTOR, version: 4 })).rejects.toMatchObject({
+        name: 'StorageError',
+        code: 'version-mismatch',
+      })
+      // Original version still opens and still holds the data.
+      const unit2 = await reopened.kv!.open(DESCRIPTOR)
+      expect((await unit2.loadAll()).tables['alpha']).toEqual({ k: { v: 1 } })
+      await reopened.close()
+    })
+
+    it('rejects operations after unit close, and close is idempotent', async () => {
+      const { backend } = await create()
+      const unit = await backend.kv!.open(DESCRIPTOR)
+      await unit.close()
+      await unit.close()
+      await expect(unit.putRecord('alpha', 'k', {})).rejects.toMatchObject({ code: 'closed' })
+      await expect(unit.loadAll()).rejects.toMatchObject({ code: 'closed' })
+      await backend.close()
+      await backend.close()
+    })
+  })
+}

packages/storage/storage/tests/registry.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Storage, { BackendRegistry } from '../src/index.ts'
+import type { StorageBackend } from '../src/index.ts'
+
+const fakeBackend = (): StorageBackend => ({ close: async () => {} })
+
+describe('BackendRegistry', () => {
+  it('registers, resolves, and disposes names', () => {
+    const registry = new BackendRegistry()
+    const backend = fakeBackend()
+    const dispose = registry.register('json', backend)
+    expect(registry.get('json')).toBe(backend)
+    expect(registry.names()).toEqual(['json'])
+    dispose()
+    expect(registry.names()).toEqual([])
+    expect(() => registry.get('json')).toThrowMatchingObject({ code: 'backend-not-found' })
+  })
+
+  it('rejects duplicate names', () => {
+    const registry = new BackendRegistry()
+    registry.register('json', fakeBackend())
+    expect(() => registry.register('json', fakeBackend())).toThrowMatchingObject({ code: 'duplicate-backend' })
+  })
+})
+
+describe('Storage service', () => {
+  it('mounts on the context and exposes registry plus form mounting', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    expect(ctx.storage).toBeInstanceOf(Storage)
+
+    const facility = { marker: true }
+    const dispose = ctx.storage.mount('domain' as never, facility as never)
+    expect(ctx.storage.form('domain' as never)).toBe(facility)
+    expect(ctx.storage.domain).toBe(facility)
+    expect(() => ctx.storage.mount('domain' as never, facility as never)).toThrowMatchingObject({
+      code: 'duplicate-mount',
+    })
+    dispose()
+    expect(() => ctx.storage.form('domain' as never)).toThrowMatchingObject({ code: 'form-not-mounted' })
+    expect(() => ctx.storage.domain).toThrowMatchingObject({ code: 'form-not-mounted' })
+  })
+
+  it('ignores a stale disposer after dispose and re-mount / re-register', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Storage)
+    const first = { first: true }
+    const second = { second: true }
+    const staleMount = ctx.storage.mount('domain' as never, first as never)
+    staleMount()
+    ctx.storage.mount('domain' as never, second as never)
+    staleMount()
+    expect(ctx.storage.form('domain' as never)).toBe(second)
+
+    const backendA = fakeBackend()
+    const backendB = fakeBackend()
+    const staleRegister = ctx.storage.backend.register('json', backendA)
+    staleRegister()
+    ctx.storage.backend.register('json', backendB)
+    staleRegister()
+    expect(ctx.storage.backend.get('json')).toBe(backendB)
+  })
+})
+
+expect.extend({
+  toThrowMatchingObject(received: () => unknown, expected: object) {
+    try {
+      received()
+    } catch (error) {
+      const pass = Object.entries(expected).every(
+        entry => (error as Record<string, unknown>)[entry[0]] === entry[1],
+      )
+      return { pass, message: () => `expected thrown error to match ${JSON.stringify(expected)}, got ${String(error)}` }
+    }
+    return { pass: false, message: () => 'expected function to throw' }
+  },
+})
+
+declare module 'vitest' {
+  interface Assertion<T> {
+    toThrowMatchingObject(expected: object): T
+  }
+}

packages/storage/storage/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/workspace/README.md

@@ -0,0 +1,9 @@
+# workspace/ — the workspace entity
+
+The workspace family owns the persistent workspace concept: a directory the user works in, with a title and the ordered list of sessions that belong to it. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+| Package | Role | ctx key |
+|---|---|---|
+| `workspace/` | `WorkspaceRegistry` service over the storage domain form: realpath-unique paths, session-ownership accounting, entity cache | `ctx.workspace` |
+
+Ownership truth lives in the workspace record's `sessionIds` (ordered), never derived from session cwd; `attachSession` verifies the session header's cwd resolves to the workspace path, so one session structurally belongs to at most one workspace. Deletion (workspace and session cascade) is deliberately absent this phase and ships with the session-side primitives.

packages/workspace/workspace/README.md

@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-workspace
+
+Workspace entity registry (`ctx.workspace`) for the DeepSeek Harness: durable workspace records — a stable `WorkspaceId`, a canonical directory path, a display title, and the ordered account of owned sessions — stored through the domain data form (`workspaceDomainSpec`, table `workspaces`). Consumers see the `Workspace` interface only; the entity implementation stays package-private.
+
+Design rationale, the path/uniqueness canon, and the consistency rules live in the [Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Shape
+
+- `ctx.workspace.create(path, title?)` — canonicalizes `path` via `fs.realpath` (trailing slashes, `..`, symlinks), rejects a nonexistent path (the original `ENOENT`), a path resolving to anything but a directory, and a canonical path another workspace already owns. Title defaults to `basename(path)`.
+- `ctx.workspace.get(id)` / `list()` / `resolveByPath(path)` — cache-served lookups; `resolveByPath` is async because it runs the same `realpath` canon first.
+- `Workspace.attachSession(id)` — idempotent; validates that the session's stored header `cwd`, canonicalized the same way, equals the workspace path. A missing persistence service, unknown session, absent or unresolvable `cwd`, or mismatch rejects without writing (what cannot be validated is not recorded). `detachSession` removes from the account only, never touching the session's own log.
+- `Workspace.sessionIds` — the ordered ownership account (array order is display order). Accounted ids whose session no longer exists are filtered from the projection and pruned durably on the next mutation. A medium accounting one session under two workspaces, or claiming one canonical path from two records, rejects at startup (external edit — the write side makes both unreachable). Attach/detach idempotence is decided on the domain write chain, so unawaited concurrent calls settle in call order.
+- `Workspace.status()` — uncached directory check, `'ok' | 'missing-dir'`; a missing directory never mutates the record.
+
+Session persistence is an optional peer resolved with `ctx.get`: absent, attach rejects and projections serve the account unfiltered.
+
+## Model Experience
+
+### Workspace records and session accounts
+
+#### What the model sees
+
+Nothing. `ctx.workspace` serves workspace records to host-side consumers only: the package registers no tools, injects no prompts, and writes no session events, so no request field ever carries this package's data.
+
+#### Token effect
+
+Zero direct tokens on every request.
+
+#### KV Cache effect
+
+Independent of live requests: the package never touches a request prefix, so it cannot invalidate provider cache reuse.
+
+## Known Limitations and Deferred Work
+
+- No delete entry point in this phase — workspace deletion ships as one complete semantic together with the session-delete primitive and cascade orchestration (future-work section of the Agent Note); a half "drop the record, keep the sessions" operation is deliberately not exposed.
+- No RPC surface or GUI wiring yet; the record schema is the direct source of the next phase's wire projection.
+- The known-session view refreshes at startup and on attach validation; a session deleted by an external process during this one is filtered only after the next refresh.

packages/workspace/workspace/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@deepseek-ai/dsh-workspace",
+  "description": "Workspace entity registry (ctx.workspace): durable workspace records with validated session attachment over the domain data form for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/workspace/workspace/src/entity.ts

@@ -0,0 +1,169 @@
+/**
+ * Package-private workspace entity: the single {@link Workspace}
+ * implementation. Holds a record snapshot that is swapped in place after each
+ * durable mutation; every write funnels through the private `mutate` so
+ * `updatedAt` stamping and dead-account pruning happen exactly once.
+ * Not re-exported from the package entrypoint — consumers see only the
+ * `Workspace` interface.
+ * @module @deepseek-ai/dsh-workspace/src/entity
+ */
+
+import { stat } from 'node:fs/promises'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
+import type { WorkspaceRecord } from './spec.ts'
+import type { Workspace, WorkspaceId } from './types.ts'
+import { realpathNormalize } from './paths.ts'
+
+/**
+ * The registry-owned machinery an entity mutates through. Entities never see
+ * the registry itself — only the open table, the known-session view backing
+ * the `sessionIds` projection, and header reads for attach validation.
+ */
+export interface WorkspaceEntityHost {
+  /**
+   * Resolve the open `workspaces` table.
+   * @returns the table; throws while the registry has not started yet.
+   */
+  table(): KvTable<WorkspaceId, WorkspaceRecord>
+
+  /**
+   * Synchronous view of the session ids known to exist in session
+   * persistence.
+   * @returns the id set, or `undefined` when persistence has been absent so
+   * far (membership cannot be verified, so projections serve the account
+   * unfiltered).
+   */
+  knownSessionIds(): ReadonlySet<string> | undefined
+
+  /**
+   * Read one stored session header for attach validation.
+   * @param id - The session whose header to read.
+   * @returns the header; rejects when session persistence is absent or holds
+   * no session with this id.
+   */
+  readSessionHeader(id: SessionId): Promise<SessionHeader>
+}
+
+/** Chain-slot abort sentinel thrown by the update fn when the record needs no change; only `mutate` observes it. */
+const unchangedSentinel = new Error('workspace record unchanged (internal sentinel)')
+
+/** The single {@link Workspace} implementation; constructed only by the registry. */
+export class WorkspaceEntity implements Workspace {
+  private record: WorkspaceRecord
+
+  /**
+   * @param host - Registry-owned table, known-session view, and header reads.
+   * @param id - The record's stable id.
+   * @param record - The validated record snapshot loaded or just written.
+   */
+  constructor(
+    private readonly host: WorkspaceEntityHost,
+    readonly id: WorkspaceId,
+    record: WorkspaceRecord,
+  ) {
+    this.record = record
+  }
+
+  get path(): string {
+    return this.record.path
+  }
+
+  get title(): string {
+    return this.record.title
+  }
+
+  get sessionIds(): readonly SessionId[] {
+    const known = this.host.knownSessionIds()
+    if (known === undefined) return this.record.sessionIds
+    return this.record.sessionIds.filter(id => known.has(id))
+  }
+
+  async setTitle(title: string): Promise<void> {
+    await this.mutate(record => ({ ...record, title }))
+  }
+
+  async attachSession(sessionId: SessionId): Promise<void> {
+    // Validation is skipped when the settled snapshot already accounts the
+    // id: the cwd fact was checked when it first attached and both inputs
+    // (stored header cwd, workspace path) are immutable. Membership itself is
+    // decided on the write chain inside `mutate`, never on this snapshot.
+    if (!this.record.sessionIds.includes(sessionId)) {
+      const header = await this.host.readSessionHeader(sessionId)
+      if (header.cwd === undefined) {
+        throw new Error(
+          `cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+          + 'its stored header carries no cwd to validate against',
+        )
+      }
+      let cwd: string
+      try {
+        cwd = await realpathNormalize(header.cwd)
+      } catch (error) {
+        throw new Error(
+          `cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+          + `its cwd '${header.cwd}' does not resolve, so it cannot be validated`,
+          { cause: error },
+        )
+      }
+      if (cwd !== this.record.path) {
+        throw new Error(
+          `cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+          + `its cwd resolves to '${cwd}'`,
+        )
+      }
+    }
+    await this.mutate(record => record.sessionIds.includes(sessionId)
+      ? record
+      : { ...record, sessionIds: [...record.sessionIds, sessionId] })
+  }
+
+  async detachSession(sessionId: SessionId): Promise<void> {
+    await this.mutate(record => record.sessionIds.includes(sessionId)
+      ? { ...record, sessionIds: record.sessionIds.filter(id => id !== sessionId) }
+      : record)
+  }
+
+  async status(): Promise<'ok' | 'missing-dir'> {
+    try {
+      return (await stat(this.record.path)).isDirectory() ? 'ok' : 'missing-dir'
+    } catch {
+      // Any stat failure (ENOENT, dangling parent, permission loss) means the
+      // directory is not usable right now; the record itself never mutates.
+      return 'missing-dir'
+    }
+  }
+
+  /**
+   * The single write path: run `fn` on the domain write chain via
+   * `table.update`, stamping `updatedAt` and pruning accounted ids whose
+   * session no longer exists (consistency rule: dead ids are dropped on the
+   * next mutation, whatever that mutation is), then swap the snapshot.
+   *
+   * `fn` sees the value current at its chain slot, so membership decisions
+   * (attach/detach idempotence) are race-free against queued writes; a fn
+   * signalling no change by returning `current` verbatim aborts the slot
+   * through the sentinel when pruning also finds nothing, so a no-op neither
+   * rewrites the medium nor emits a change event.
+   */
+  private async mutate(fn: (record: WorkspaceRecord) => WorkspaceRecord): Promise<void> {
+    const known = this.host.knownSessionIds()
+    let next: WorkspaceRecord
+    try {
+      next = await this.host.table().update(this.id, (current) => {
+        const changed = fn(current)
+        const sessionIds = known === undefined
+          ? changed.sessionIds
+          : changed.sessionIds.filter(id => known.has(id))
+        if (changed === current && sessionIds.length === current.sessionIds.length) {
+          throw unchangedSentinel
+        }
+        return { ...changed, sessionIds, updatedAt: new Date().toISOString() }
+      })
+    } catch (error) {
+      if (error === unchangedSentinel) return
+      throw error
+    }
+    this.record = next
+  }
+}

packages/workspace/workspace/src/index.ts

@@ -0,0 +1,231 @@
+/**
+ * Workspace entity registry (`ctx.workspace`): durable workspace records over
+ * the domain data form, with session attachment validated against stored
+ * session headers. This package owns the `WorkspaceId` brand and the
+ * `workspace` domain; consumers see the {@link Workspace} interface only.
+ * @module @deepseek-ai/dsh-workspace
+ */
+
+import { randomUUID } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { Context, Service } from 'cordis'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+// Type-only: merges `sessionPersistence` into the Context service map for the
+// optional `ctx.get` lookups below.
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
+import { workspaceDomainSpec } from './spec.ts'
+import type { WorkspaceRecord } from './spec.ts'
+import { WorkspaceEntity } from './entity.ts'
+import type { WorkspaceEntityHost } from './entity.ts'
+import { realpathNormalize } from './paths.ts'
+import type { Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts'
+
+export type { Workspace } from './types.ts'
+export { workspaceRecord, workspaceDomainSpec } from './spec.ts'
+export type { WorkspaceRecord } from './spec.ts'
+export { realpathNormalize } from './paths.ts'
+
+/** Identifies one workspace record (see `src/types.ts` for the brand rationale). */
+export type WorkspaceId = WorkspaceIdBrand
+
+/**
+ * Brand a string as a {@link WorkspaceId}.
+ * @param id - the raw workspace id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
+export function WorkspaceId(id: string): WorkspaceId {
+  return id as WorkspaceId
+}
+
+declare module 'cordis' {
+  interface Context {
+    workspace: WorkspaceRegistry
+  }
+}
+
+/**
+ * The workspace registry service. Opens the `workspace` domain at startup,
+ * rebuilds one entity per stored record, and serves entities from an
+ * in-memory cache keyed by id. Session persistence is an OPTIONAL peer
+ * (resolved via `ctx.get`, never injected): while it is absent, session
+ * attachment rejects (what cannot be validated is not recorded) and
+ * `sessionIds` projections serve the account unfiltered.
+ *
+ * There is deliberately no delete entry point in this phase: workspace
+ * deletion ships as one complete semantic together with the session-cascade
+ * primitives (future work in the owning Agent Note).
+ */
+export class WorkspaceRegistry extends Service {
+  static inject = ['storage']
+
+  private table?: KvTable<WorkspaceId, WorkspaceRecord>
+  private readonly entities = new Map<WorkspaceId, WorkspaceEntity>()
+  /**
+   * Session ids known to exist in session persistence; `undefined` until the
+   * first successful listing. Refreshed at startup and on every attach
+   * validation — within one process sessions are only ever added (this phase
+   * has no delete primitive), so the set can only lag by missing very recent
+   * sessions, never by holding dead ones from this process's lifetime.
+   */
+  private known?: Set<string>
+
+  private readonly host: WorkspaceEntityHost = {
+    table: () => this.requireTable(),
+    knownSessionIds: () => this.known,
+    readSessionHeader: id => this.readSessionHeader(id),
+  }
+
+  constructor(ctx: Context) {
+    super(ctx, 'workspace')
+  }
+
+  /** Open the domain and rebuild the entity cache before the service is published as active. */
+  protected async [Service.init](): Promise<void> {
+    const domain = await this.ctx.storage.domain.open(workspaceDomainSpec)
+    // This registry owns the domain handle it opened: closing on fiber
+    // disposal frees the domain name, so a re-plugged registry can reopen it.
+    this.ctx.effect(() => () => domain.close(), 'workspace.domainClose')
+    this.table = domain.table('workspaces')
+    const persistence = this.ctx.get('sessionPersistence')
+    if (persistence !== undefined) {
+      this.known = new Set<string>((await persistence.list()).map(header => header.id))
+    }
+    // Rebuild entities, rejecting states the write side makes structurally
+    // impossible (an external medium edit is the only way in, and hiding it
+    // would silently pick a winner): one session accounted under two
+    // workspaces, or two records claiming one canonical path (plain string
+    // equality — stored paths are already canonical, so no realpath here).
+    const accounted = new Map<string, WorkspaceId>()
+    const paths = new Map<string, WorkspaceId>()
+    for (const [id, record] of this.table.entries()) {
+      const pathHolder = paths.get(record.path)
+      if (pathHolder !== undefined) {
+        throw new Error(
+          `workspace domain is inconsistent: path '${record.path}' is claimed `
+          + `by both workspace '${pathHolder}' and workspace '${id}'`,
+        )
+      }
+      paths.set(record.path, id)
+      for (const sessionId of record.sessionIds) {
+        const holder = accounted.get(sessionId)
+        if (holder !== undefined) {
+          throw new Error(
+            `workspace domain is inconsistent: session '${sessionId}' is accounted `
+            + `by both workspace '${holder}' and workspace '${id}'`,
+          )
+        }
+        accounted.set(sessionId, id)
+      }
+      this.entities.set(id, new WorkspaceEntity(this.host, id, record))
+    }
+  }
+
+  /**
+   * Create a workspace over an existing directory. The path is canonicalized
+   * through `fs.realpath` first — a nonexistent path rejects with the
+   * original `ENOENT`, a path resolving to anything but a directory rejects,
+   * and a canonical path already owned by another workspace (including a
+   * symlink resolving to it) rejects.
+   * @param path - Directory the workspace points at; canonicalized before storing.
+   * @param title - Display title; defaults to `basename` of the canonical path.
+   * @returns the created workspace after durability.
+   */
+  async create(path: string, title?: string): Promise<Workspace> {
+    const table = this.requireTable()
+    const canonical = await realpathNormalize(path)
+    if (!(await stat(canonical)).isDirectory()) {
+      throw new Error(`cannot create a workspace at '${canonical}': path is not a directory`)
+    }
+    for (const entity of this.entities.values()) {
+      if (entity.path === canonical) {
+        throw new Error(`a workspace for '${canonical}' already exists ('${entity.id}')`)
+      }
+    }
+    const id = WorkspaceId(randomUUID())
+    const now = new Date().toISOString()
+    const record: WorkspaceRecord = {
+      path: canonical,
+      title: title ?? basename(canonical),
+      sessionIds: [],
+      createdAt: now,
+      updatedAt: now,
+    }
+    const entity = new WorkspaceEntity(this.host, id, record)
+    // Cache before the durable put: a concurrent same-path create fails the
+    // scan above, and the entity already exists when `domain/changed` fires.
+    this.entities.set(id, entity)
+    try {
+      await table.put(id, record)
+    } catch (error) {
+      this.entities.delete(id)
+      throw error
+    }
+    return entity
+  }
+
+  /**
+   * Look up a workspace by id.
+   * @param id - The workspace id.
+   * @returns the workspace, or `undefined` when unknown.
+   */
+  get(id: WorkspaceId): Workspace | undefined {
+    return this.entities.get(id)
+  }
+
+  /**
+   * Snapshot of all workspaces, in load-then-creation order.
+   * @returns a fresh array of the cached entities.
+   */
+  list(): Workspace[] {
+    return [...this.entities.values()]
+  }
+
+  /**
+   * Resolve a workspace by directory path, through the same `fs.realpath`
+   * canon as {@link create} (hence async). A path that does not exist rejects
+   * with the original error — a missing directory has no canonical form to
+   * compare (a workspace whose recorded directory vanished is only reachable
+   * by id; see `Workspace.status`).
+   * @param path - Directory path in any spelling (symlinks, `..`, trailing slash).
+   * @returns the owning workspace, or `undefined` when none matches.
+   */
+  async resolveByPath(path: string): Promise<Workspace | undefined> {
+    const canonical = await realpathNormalize(path)
+    for (const entity of this.entities.values()) {
+      if (entity.path === canonical) return entity
+    }
+    return undefined
+  }
+
+  private requireTable(): KvTable<WorkspaceId, WorkspaceRecord> {
+    if (this.table === undefined) {
+      throw new Error('workspace registry is not started yet')
+    }
+    return this.table
+  }
+
+  /**
+   * Read one stored session header for attach validation, refreshing the
+   * known-session view from the same listing. Rejects when session
+   * persistence is absent or holds no session with this id.
+   */
+  private async readSessionHeader(id: SessionId): Promise<SessionHeader> {
+    const persistence = this.ctx.get('sessionPersistence')
+    if (persistence === undefined) {
+      throw new Error(
+        `cannot validate session '${id}': no session persistence service is available`,
+      )
+    }
+    const headers = await persistence.list()
+    this.known = new Set<string>(headers.map(header => header.id))
+    const header = headers.find(candidate => candidate.id === id)
+    if (header === undefined) {
+      throw new Error(`cannot validate session '${id}': session persistence holds no such session`)
+    }
+    return header
+  }
+}
+
+export default WorkspaceRegistry

packages/workspace/workspace/src/invariant.ts

@@ -0,0 +1,53 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-workspace`.
+ * @module @deepseek-ai/dsh-workspace/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { DomainChanged } from '@deepseek-ai/dsh-storage-domain'
+import { WorkspaceId } from '@deepseek-ai/dsh-workspace'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-workspace'
+
+/** Cordis companion plugin name. */
+export const name = 'workspace-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * Owned relationship: the registry's entity cache mirrors the workspace
+ * domain's durable table. Every `domain/changed` for the `workspaces` table
+ * must name a record the cache already holds an entity for (the registry
+ * caches before the durable put and mutates only through cached entities),
+ * and no `deleted` operation may appear at all — this phase ships no delete
+ * entry point, so a deletion proves a write path outside the registry.
+ */
+const install: InvariantInstaller = Object.assign(
+  (ctx: Context, fail: (message: string) => never) => {
+    ctx.on('domain/changed', (change: DomainChanged) => {
+      if (change.domain !== 'workspace' || change.table !== 'workspaces') return
+      if (change.operation === 'deleted') {
+        fail(
+          `workspace record '${change.key}' emitted a deleted change, but the registry `
+          + 'exposes no delete entry point — some write path bypassed ctx.workspace',
+        )
+      }
+      if (ctx.workspace.get(WorkspaceId(change.key)) === undefined) {
+        fail(
+          `workspace record '${change.key}' landed durably but the registry cache holds `
+          + 'no entity for it — the cache and the domain table have diverged',
+        )
+      }
+    })
+  },
+  { inject: ['workspace'] },
+)
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))