@earendil-works/chord 1.3.0 → 1.5.0

package/docs/next/slice-7b/book.md

@@ -0,0 +1,608 @@
+---
+title: Slice 7b: reloading plugins in a running Chord app
+cover: Slice 7b / Reload
+kicker: A design brief · Chord v2 · slice 7b · 2026-10-29
+subtitle: What a plugin is, how it is built and loaded, how a mini p2 is assembled from Chord, and what happens when a plugin's code changes on one host or across many
+stats:
+  - 4 | steps of a reload on one host
+  - 3 | fates of a live object
+  - 26 | carry-over items from slices 3a to 7a
+  - 11 ms | to rebuild one facet after an edit
+  - 6 | decisions open
+note: |
+  A brief before the slice 7b spec, written by the redesign session from `design.md` §21, the dependency model
+  (`dependencies/model.md`, decided and built for 7a in pi `339847eb1`), the carry-over in `slices.md` and the code at
+  `339847eb1`. Marks: **Decided** points cite the decision; **Open** points are the owner's, with a recommendation.
+colophon: Slice 7b brief · 2026-10-29 · Chord v2
+---
+
+# Before we begin {.preface}
+
+Mario edits the notes plugin while a session is open: a new method, a renamed field in a document, a second state
+member. He presses Reload. The server, the session's worker and two browser tabs run the old notes code; within a
+second they should all run the new one, with the notes, the open views and the running export job intact, and without
+restarting a single process.
+
+Chord v2 can do everything around that today: objects, references across hosts, the store, jobs, registries, and since
+7a a dependency model in which a missing provider is a wait, not an error. What it cannot do yet is change code. `load`
+runs once per host (`host.ts`: "load runs once per host"). Slice 7b adds the reload, on one host and across hosts.
+
+## Eight things to know
+
+:::findings
+1. **A reload is a transaction per host.** Load the bundles, stage the new declarations, commit atomically, then let
+   each object follow; any code error before the commit leaves the host entirely on its old code.
+2. **A live object has three fates.** Pure objects swap in place; objects with natives drain and restart; objects of a
+   removed type end, and their holders wait.
+3. **Old calls finish on old code.** A pure swap keeps the running calls' old handles valid until they settle; only new
+   calls see the new code.
+4. **Versions are the provider's business.** A provider accepts older consumers through `accepts`; a consumer that does
+   not fit waits (7a), it is not ended.
+5. **7a already decided most of the hard part.** Removal, dropped versions and installs are waits woken by a
+   publication; a reload's commit is such a publication.
+6. **A plugin is a directory with a `package.json` and one file per surface.** Each facet is bundled alone; host
+   packages are passed in, never copied; a whole plugin set builds in a few hundred milliseconds.
+7. **Chord should ship the app kit** (proposed): loader, HTTP, workers, web, TUI and dev reload as optional
+   components, so a mini p2 is a page of code.
+8. **Six points are open:** the reload API, the rollout across hosts, a `writable` across a swap, the install
+   watchdog, where the loader lives, and the app kit.
+:::
+
+## Words used throughout
+
+A **reload** changes the code of one or more plugins on one host. A **facet** is a plugin's code for one host kind; a
+**bundle** is the built JavaScript of a facet. **Staging** runs the new facets and factories against a recording
+`self` without activating anything. The **commit** switches the host to the new code at once and is a **publication**
+in 7a's sense. A **pure** object has no natives (`self.open`), in its old or its new code. A **rollout** is a reload
+of the same code set on every host, server first.
+
+# A Plugin, File by File {#plugin lede="What a plugin looks like on disk, and what each file is for."}
+
+A plugin is a directory. Its name is its `package.json` name; its code is one file per host kind it runs on, a
+**facet**; everything else is ordinary TypeScript the facets import. This is p2's layout today (`apps/p2/plugins/*`),
+plus the `package.json` that loader D needs (p2's `plugin-loading.md` §8; p2's built-in plugins have none yet and are
+named by their directory).
+
+```text
+plugins/notes/
+  package.json        name = the plugin's name; peerDependencies = host packages; dependencies = bundled npm deps
+  contract.ts         the plugin's object types and registries (shared by its facets and by other plugins)
+  server.ts           facet for the server     (default export: defineFacet(...))
+  worker.ts           facet for session workers
+  web.tsx             facet for browser tabs
+  tui.ts              facet for the TUI
+  store.ts            plain modules the facets import
+  NoteList.tsx
+  notes.css
+  assets/
+    template.md       files the plugin ships (read at runtime, or offered for download)
+    icon.svg
+  skills/notes/SKILL.md   optional resources (p2 §4.4)
+```
+
+```json
+{
+  "name": "@pi/notes",
+  "version": "1.4.0",
+  "type": "module",
+  "peerDependencies": {
+    "@earendil-works/chord": "^2",
+    "@earendil-works/pi-durable": "^1",
+    "react": "^19"
+  },
+  "dependencies": {
+    "marked": "16.4.1"
+  }
+}
+```
+
+- **`name`** identifies the plugin everywhere: its facets, its registry contributions, diagnostics, reloads.
+- **`peerDependencies`** are **host packages**: the running app supplies them, one instance per process (one Chord,
+  one React; `instanceof ChordError` and React hooks only work that way). The bundler never copies them.
+- **`dependencies`** are the plugin's own npm packages (`marked`): installed into the plugin's `node_modules` with
+  `--ignore-scripts` and bundled into every facet that imports them. **Decided** (owner, 2026-10-29): bundled by
+  default; on Node a plugin may keep named packages external by an explicit list, `"chord": { "external":
+  ["better-sqlite3"] }`. Server and worker facets then load them from the plugin's `node_modules` with `createRequire`,
+  as pi 1.0 loads extension dependencies, native addons included; they stay in Node's module cache until the process
+  ends, so a new version takes effect after a restart. A browser or TUI facet that imports one fails to build.
+- **No `tsconfig.json` is needed.** The bundler strips types and does not type-check; JSX is compiled with the
+  automatic React runtime, a fixed setting of the loader. A plugin may keep a `tsconfig.json` for its editor and for
+  `tsc --noEmit` (the SDK ships one to extend); the loader ignores it.
+
+A facet only declares (chapter III of the model): it serves object types, serves or contributes to registries, and
+returns nothing.
+
+```ts
+// plugins/notes/contract.ts
+import { defineRegistry, local, remote, str, obj, arr, method } from "@earendil-works/chord/next";
+import { Session } from "@app/core";                        // the app's host kinds, a host package
+export const NoteStore = local("notes.store", { version: 1, params: {}, members: { /* … */ } });
+export const Notes = remote("notes", {
+  version: 2,
+  params: { session: str() },
+  hostAddress: ({ session }) => Session({ id: session }),
+  variants: { editor: { state: { list: arr(obj({ id: str(), text: str() })) }, methods: { add: method(obj({ text: str() })) } } },
+});
+
+// plugins/notes/worker.ts
+import { defineFacet } from "@app/core";                    // bound to the app's principal type
+import { NoteStore, Notes } from "./contract.ts";
+import { serveStore } from "./store.ts";
+export default defineFacet((host) => {
+  host.serve(NoteStore, serveStore);
+  host.serve(Notes, ({ session }, principal, self) => { /* … */ });
+});
+
+// plugins/notes/web.tsx
+import { defineFacet } from "@app/core";
+import { NoteList } from "./NoteList.tsx";                  // a React component, bundled
+import "./notes.css";                                       // bundled into the facet's stylesheet
+export default defineFacet((host, self) => {
+  self.contribute(Panels, { notes: NoteList });             // the app's UI registry
+});
+```
+
+# Building and Loading {#loading lede="How the bundler knows what to pull in, and how the code gets into a running process."}
+
+Each facet is built on its own, as one script. The bundler starts at the facet file and follows its imports:
+
+| An import of | Becomes |
+| --- | --- |
+| the plugin's own files (`./store.ts`, `./NoteList.tsx`) | inlined into the facet's script |
+| another plugin's contract (`../sessions/contract.ts`, or `@pi/sessions/contract` for an installed package) | inlined too: a copy, so a plugin carries the contract version it was built against (`accepts` needs that); only contracts and side-effect-free modules may be imported across plugins |
+| an npm package in `dependencies` (`marked`) | inlined, resolved from the plugin's own `node_modules` |
+| an npm package listed in `chord.external` (Node facets only) | external: `require`d from the plugin's own `node_modules` at evaluation |
+| a host package (`@earendil-works/chord/next`, `react`, `@app/core`, …) | **external**: a parameter of the script, the host's instance at load time |
+| a Node builtin (`node:fs`) | external, through the `require` the loader passes (server and worker facets only; a web facet that imports one fails to build) |
+| CSS (`import "./notes.css"`) | collected into one stylesheet per web facet |
+| an asset by URL (`import iconUrl from "./assets/icon.svg?url"`) | a content-hashed file served by the app; the import is its URL |
+
+The built script is a function of its host packages. That is the whole trick of loader D: there is no module map, no
+second copy of Chord, and an old version is garbage-collected once nothing holds its closures.
+
+```js
+// what the bundler emits for plugins/notes/worker.ts (simplified)
+(function (require, __files) {
+  const { defineFacet } = require("@app/core");             // the host's instance
+  const { local, remote, str } = require("@earendil-works/chord/next");
+  const { marked } = /* marked's code, inlined */;
+  /* contract.ts, store.ts, inlined */
+  return defineFacet((host) => { /* … */ });
+})
+```
+
+```ts
+// the loader (proposed @earendil-works/chord/next/loader), Node side
+import { buildFacet, evaluateFacet } from "@earendil-works/chord/next/loader";
+
+const HOST_PACKAGES = {                                     // the app's base bundle exports these
+  "@earendil-works/chord/next": chordNext, "@earendil-works/pi-durable": durable,
+  "@app/core": core, react, "react/jsx-runtime": jsxRuntime,
+};
+const script = await buildFacet({ plugin: "/data/plugins/notes", facet: "worker.ts", hostPackages: Object.keys(HOST_PACKAGES), platform: "node" });
+const facet = evaluateFacet(script, { hostPackages: HOST_PACKAGES, require: createRequire(import.meta.url), dir: "/data/plugins/notes" });
+await host.reload([{ name: "@pi/notes", facet }], ctx);    // or host.load the first time
+```
+
+- `buildFacet` is esbuild with: the facet as entry, the host packages and `node:*` external, `format: "cjs"` wrapped
+  as the function above, minified, an `onResolve` that refuses anything outside the plugin, its `node_modules`, a
+  contract of another plugin or a host package. It returns the script, its content hash and esbuild's metafile (the
+  dev loop knows which files a facet used).
+- `evaluateFacet` runs the script with `vm.Script` and a stable filename per (facet, hash) on Node, or as a classic
+  `<script>` in the browser (the page fetches the script and its stylesheet by hash, which caches forever).
+- **Imports a plugin cannot use:** dynamic `import()` (resolved at build, or not at all), top-level `await` (a facet is a
+  synchronous declaration), `require` of anything but builtins.
+
+:::review | Open 5: where the loader lives
+(a) Chord ships `chord/next/loader` (discovery, `buildFacet`, `evaluateFacet`, `pluginFile`), an app chooses its host
+packages; (b) Chord knows only `host.reload(facets)` and the app bundles and evaluates. Recommended: (a); the kernel
+stays free of it, and Durable Objects (no `eval`) compose statically as before.
+:::
+
+# Assets and Files {#assets lede="Files a plugin ships: bundled into the browser, read at runtime, or offered for download."}
+
+A plugin has files that are not code. They fall into three cases.
+
+**1. Imported by a web facet.** CSS, images, wasm. The bundler emits them as content-hashed files next to the facet's
+script, and the import evaluates to their URL. The app serves the bundle's files under one path; p2 does exactly this
+today for the terminal's wasm (`plugins/terminals/Terminal.tsx`: `import ghosttyWasm from
+"../../vendor/ghostty/ghostty-vt.wasm?url"`, served under `/__p2_web/`).
+
+```tsx
+import iconUrl from "./assets/icon.svg?url";
+export const NoteIcon = () => <img src={iconUrl} alt="" />;
+```
+
+**2. Read at runtime by a server or worker facet.** A template, a wasm module for a native, a script a native runs. A
+bundled script has no meaningful `import.meta.url` (today's `plugins/terminals/main.ts` reads its wasm with
+`new URL("../../vendor/…", import.meta.url)`). The loader passes the plugin's directory, and a helper resolves a path
+inside it, refusing `..` out of it:
+
+```ts
+// plugins/notes/worker.ts
+import { pluginFile } from "@earendil-works/chord/next/loader";   // reads the directory the loader passed
+const template = await readFile(pluginFile("assets/template.md"), "utf8");
+```
+
+**3. Offered for download over HTTP.** A plugin contributes a route to the app's HTTP registry; the handler opens the
+file through the same helper and streams it, with the plugin's own authorization:
+
+```ts
+// plugins/notes/server.ts
+export default defineFacet((host, self) => {
+  self.contribute(Http, {
+    routes: {
+      "GET /notes/template.md": async (request, ctx) => {
+        if (ctx.principal.kind !== "owner") return { kind: "error", status: 403 };
+        const path = pluginFile("assets/template.md");
+        const { size } = await stat(path);
+        return { kind: "bytes", name: "template.md", mime: "text/markdown", size, read: (offset, length) => readRange(path, offset, length) };
+      },
+    },
+  });
+});
+```
+
+So yes: a plugin can offer its files for download, because the loader tells it where it lives. Each facet sees only its
+own plugin's directory; nothing gives it another plugin's files.
+
+# HTTP {#http lede="What Chord provides, what p2 has, and what p3 needs."}
+
+**Chord v2 has no HTTP server today.** Design §23 designs one (`@earendil-works/chord/next/http`) and defers it until
+"the kernel fixes and a first real proof" are done. p2's HTTP is its own, about 30 lines of helpers plus the server host:
+
+```ts
+// apps/p2/src/runtime/server.ts (p2 today, Chord v1)
+export const Routes = defineRegistry<RouteHandler>("p2.routes", { conflict: "error" });        // "METHOD /path" → handler
+export const Upgrades = defineRegistry<UpgradeHandler>("p2.upgrades", { conflict: "error" });   // WebSocket upgrades
+export const RequestResolvers = defineRegistry<RequestResolver>("p2.request-resolvers", { conflict: "error" });
+type RouteHandler = (request: IncomingMessage, response: ServerResponse, access: RequestAccess, ctx: Ctx) => void | Promise<void>;
+```
+
+Plugins contribute handlers that write to Node's `ServerResponse` themselves; the files plugin implements ranges,
+download headers and previews by hand (`plugins/files/server.ts`).
+
+The designed component (§23) replaces raw responses with descriptions, so every plugin gets ranges (206/416), `HEAD`,
+safe download headers, streaming and abort on disconnect from one place:
+
+```ts
+export const Http = defineRegistry<HttpContribution, Router>("chord.http", { version: 1 });
+type HttpContribution = { routes?: Record<string, Route>; wraps?: Wrap[] };
+type Route = (req: HttpRequest, ctx: Ctx) => Promise<HttpResponse>;   // ctx.principal: the request's principal
+type HttpResponse =
+  | { kind: "json"; value: JsonValue } | { kind: "page"; title: string; body: string }
+  | { kind: "bytes"; name: string; mime: string; size: number; read(offset: number, length: number): Promise<Uint8Array> }
+  | { kind: "redirect"; to: string } | { kind: "error"; status: number };
+```
+
+- Routes compose by `keyedEntries`: a duplicate pattern is a reported conflict, the first by plugin name wins.
+- Wraps (middleware) run in phases the owner defines (`observe`, `headers`, `transform`), by default only around their
+  own plugin's routes.
+- Request resolvers (who sent a request: cookie, loopback, relay) are hooks; WebSocket byte channels for terminals are
+  a separate component.
+
+# Performance {#perf lede="Measured on slayer, Node 24, esbuild from the repo, p2's plugins as they are."}
+
+Built with the loader D settings above (each facet alone, host packages and `apps/p2/src` external, minified), on
+p2's real plugins:
+
+| Measurement | Result |
+| --- | --- |
+| all 25 worker facets, one script each, cold | 237 ms, 294 KB in total, largest `models/worker.ts` 35 KB |
+| all 20 server facets, cold | 167 ms, 236 KB |
+| all 17 web facets, cold | 144 ms, 912 KB, of which 688 KB is the terminal's wasm |
+| one facet rebuilt after an edit (esbuild context, warm) | 11 ms |
+| compile and evaluate all 25 worker scripts (`vm.Script`) | 23 ms |
+| worker spawn to ready, p2 today (TypeScript through the source resolver, `nodeLoader`) | 549 ms (p2's measurement, `plugin-loading.md` §14.1) |
+| the same with one bundle per worker plugin set | 218 ms |
+| base bundle plus one script per plugin through ESM (model B) | 254 ms; D is expected near it |
+
+The plugins are small; the time goes into the host packages and the runtime (85% of a worker's load time, p2 §14.1),
+which the base bundle loads once per process. A reload of one plugin costs one rebuild (about 11 ms warm) and one
+evaluation (about 1 ms per facet), then Chord's reload. The memory caveat is V8's compilation cache: every distinct
+compiled script stays cached, so scripts get a stable name per (facet, hash) and hosts that reload in place run with
+the cache off (+0.1 MiB instead of +5.6 MiB per 100 reloads, p2's measurement).
+
+# A Mini p2 from Chord {#kit lede="The owner: building a small p2 with a web and a TUI surface and plugins should be trivial from Chord; optional components should come out of the box."}
+
+p2 has about 10,700 lines of host code in `apps/p2/src/hosts` and its runtime: the server's HTTP and WebSocket
+entry, the worker supervisor, plugin discovery, the web and TUI bundles, the web shell, the TUI sandbox and launcher,
+the reload control. Almost none of it is p2-specific. The proposal: Chord ships it as optional components, each a
+subpath an app imports only if it wants it, none of them in Chord's kernel.
+
+## What it would look like
+
+```ts
+// server.ts: a whole app with plugins, a web and a TUI surface
+import { createHost } from "@earendil-works/chord/next";
+import { discoverPlugins, pluginLoader } from "@earendil-works/chord/next/loader";
+import { httpServer } from "@earendil-works/chord/next/http";
+import { workerRoute } from "@earendil-works/chord/next/workers";
+import { webSurface } from "@earendil-works/chord/next/web";
+import { tuiSurface } from "@earendil-works/chord/next/tui";
+import { devReload } from "@earendil-works/chord/next/dev";
+import { Server, Session, core } from "./core.ts";              // the app's base code: host kinds, principals, core facet
+
+const plugins = await discoverPlugins(["./plugins", join(dataDir, "plugins")]);
+const loader = pluginLoader({ hostPackages: core.hostPackages });
+
+const server = createHost<P>({ address: Server(), principal: { kind: "server" }, onError });
+server.route(Session, workerRoute({ entry: "./worker.ts", idleMs: 300_000, authorize: core.authorize }), ctx);
+await server.load([core.serverFacet, ...(await loader.facets(plugins, "server"))], ctx);
+
+const http = httpServer(server, { port: 4321, authenticate: core.authenticate });   // routes from the Http registry
+http.surface(webSurface({ loader, plugins, shell: core.webShell }));                  // /: the page, its bundle, its socket
+http.surface(tuiSurface({ loader, plugins }));                                        // the TUI launcher's bundle and socket
+devReload({ server, loader, plugins, watch: true });                                 // a changed plugin reloads everywhere
+```
+
+```ts
+// worker.ts
+import { workerMain } from "@earendil-works/chord/next/workers";
+await workerMain(async ({ address, init, parent }) => {
+  const worker = createHost<P>({ address, principal: { kind: "worker", session: init.id }, onError });
+  worker.connect(parent, { principal: { kind: "server" }, trusted: true }, ctx);
+  await worker.load([core.workerFacet(init), ...(await loader.facets(init.plugins, "worker"))], ctx);
+  return worker;
+});
+```
+
+```tsx
+// core.ts, the web shell: the app decides the layout; plugins fill registries
+export const Panels = defineRegistry<Record<string, ComponentType>, Panel[]>("app.panels", { version: 1 });
+export const webShell = ({ host }: ShellProps) => {
+  const panels = useRegistry(host, Panels);                     // from chord/next/web: a hook over a registry value
+  return <Tabs>{panels.map((p) => <p.component key={p.name} />)}</Tabs>;
+};
+```
+
+And a plugin is what chapter I shows: a directory, a `package.json`, facets that serve types and contribute to the
+app's registries (`Http`, `Panels`, a TUI command list).
+
+## The components
+
+| Subpath | What it does | Replaces in p2 |
+| --- | --- | --- |
+| `chord/next/loader` | `discoverPlugins` (directory listing, `package.json` names, no parsing), `buildFacet` (esbuild, host packages external), `evaluateFacet` (Node `vm`, browser `<script>`), `pluginFile`, npm/git install with `--ignore-scripts` | `src/hosts/plugins.ts`, `bundles.ts`, the source resolver, `nodeLoader` |
+| `chord/next/http` | the Node HTTP server, the `Http` registry (routes, wraps, request resolvers, responses as descriptions: ranges, downloads, `HEAD`), WebSocket entry calling `host.accept` | `src/hosts/server.ts` (HTTP part), `runtime/http.ts`, `Routes`, `Upgrades`, `RequestResolvers` |
+| `chord/next/workers` | `workerRoute` (fork a worker per address, IPC link, start message, idle stop from `host.activity`, crash restart with backoff), `workerMain` (the child's side) | `SessionHosts` in `runtime/server.ts`, `hosts/worker.ts` |
+| `chord/next/web` | the page host (connect over a WebSocket with reconnect, load web facets from their scripts, React provider and hooks: `useObject` over `host.hold`, `useRegistry`, `useWatch`), serving the bundle by hash, reload on a new manifest | `hosts/web/*`, `runtime/web.tsx`, `src/web/reconnect.ts` |
+| `chord/next/tui` | the TUI launcher and sandbox (pi-tui, the bundle download, a link over the launcher's socket), slots and commands as registries | `hosts/tui-*.ts`, `runtime/tui.ts` |
+| `chord/next/dev` | the source watcher marking plugins dirty, the reload control (`reload(plugins)` on every host in order: server, workers, then a manifest bump for pages and the TUI) | `performReload` in `hosts/server.ts`, the dev protocol |
+
+Each is ordinary code on top of Chord's public API: nothing in the kernel depends on it, a Durable Object deployment
+uses none of it, and an app can replace any one (its own HTTP server, its own shell). React is a host package of the web
+component, pi-tui of the TUI component; an app without them never imports them.
+
+## What stays the app's
+
+The principal type and authentication; the host kinds (`Server`, `Session`) and what a worker's start message holds;
+the core facet and core objects (catalog, harness); the web shell's layout and the TUI's look; which registries plugins
+contribute to beyond `Http`. That is roughly what p3's base code should be: a few hundred lines, not ten thousand.
+
+:::review | Open 6: the app kit
+(a) Chord ships these six components as optional subpaths of `@earendil-works/chord`, built in this order: `loader`
+and `dev` with 7b (reload needs them), `http` and `workers` next (p3 needs them first), `web` and `tui` after (lifted
+from p2's code, which works today). (b) Chord ships only `loader`; the rest is p3's base code. Recommended: (a), as the
+owner asked; each component gets its own slice spec and review, after 7b and before slice 9 or alongside p3's base.
+:::
+
+# One Host Reloads {#host lede="Four steps, all or nothing up to the commit."}
+
+Design §21 fixes the shape. **Decided.**
+
+```text
+1. load      the new bundles; an import or syntax error rejects
+2. staging   facet setups and every live object's new factory run with a recording `self`
+             (declarations only, nothing activated); any throw rejects
+3. commit    the host switches to the new code atomically: a publication (7a)
+4. after     each object follows its fate (chapter II)
+```
+
+Rollback is all or nothing per host, and only for code errors: an import error, a throwing setup or factory. A failed
+`open`, a registry conflict or a failing `migrate` after the commit are runtime states of single objects, never a
+reason to roll back. A host is at revision R or R−1, never in between.
+
+Staging runs factories against a recording `self` because a factory only declares: it returns members and calls
+`self.state`, `self.get`, `self.open` and so on, and the recording tells Chord what changed (a new dependency, a native
+added or removed, a member gone) before anything happens.
+
+:::sequence animate | A reload of the notes plugin on the worker. Nothing is visible to callers until the commit.
+actor app "base code" "reload control"
+actor host "worker W" ""
+actor objs "notes objects" "live"
+app -> host: reload([notes v2], ctx)
+host -> host: load bundles
+host -> host: staging: setups + new factories (recording self)
+host => host: commit: types, registries, contributions swapped; publication
+host => objs: each follows its fate
+objs --> app: resolved: { reloaded, restarted, ended, failed }
+:::
+
+:::review | Open 1: the API
+Today a host has `load(facets, ctx)`, once. Proposal: `host.reload(facets, ctx)` with the plugins' new facets (by
+plugin name: added, changed; a plugin missing from the list is removed), resolving with a report of what each object
+did, rejecting with the code error and nothing changed. `load` stays the first call. Alternative: one
+`host.load` that may be called again. Recommended: the separate `reload`, because its result differs (a report, not a
+barrier) and its rollback rule does not apply to the first load (a throwing first setup closes the host).
+:::
+
+# Three Fates {#fates lede="What happens to each live object at the commit."}
+
+The commit compares each live object's old and new declarations. **Decided** (design §21, owner 2026-10-26, the
+dependency model).
+
+| The object | Fate | Calls | Documents, jobs |
+| --- | --- | --- | --- |
+| pure, old and new (no `self.open`) | **swapped in place**: new methods, derives and routines; references kept, new ones made | running calls finish on old handles; new calls see new code | stay |
+| has natives, old or new | **restarted**: new calls park, running calls drain (`closeTimeout`), natives close (`reload`), the new factory runs, natives reopen | park during the restart | stay; running job runs end `aborted { reload }`, `finish` runs on new code |
+| its type is gone | **ended**: natives close (`end`), callers rejected, handlers drain | rejected | in-memory gone; persisted stay until retired |
+| a new dependency is missing (any of the above) | **parks** (decision 4): gate closed, `failed { waiting }` | reject | stay |
+
+```ts
+// notes v1                                     // notes v2: pure, swapped in place
+host.serve(NoteStore, (_, self) => {           host.serve(NoteStore, (_, self) => {
+  const notes = self.state(Notes);               const notes = self.state(Notes);      // same document, v2 migrates it
+  return {                                       const count = self.derive([notes], ([n]) => n.list.length);
+    notes,                                       return {
+    add: (a, ctx) => self.tx(…, ctx),              notes, count,                       // a new exposed member
+  };                                               add: (a, ctx) => self.tx(…, ctx),
+});                                                rename: (a, ctx) => self.tx(…, ctx), // a new method
+                                                 };
+                                               });
+```
+
+Rules that come with the fates, all **decided**:
+
+- **R15, old code and migrated documents:** an old call that touches a document whose version rose throws once; the
+  document stays intact; the call is not resent.
+- **Derives** have no names: exposed derives are matched by their member name, internal ones are rebuilt.
+- **Routines** hand over per object: the old ones are aborted, the new ones start once the old calls finished, bounded
+  by `closeTimeout`; calls do not wait for it.
+- **Instance ids:** a restarted object gets a new instance id (an old activation chain must not match it); a swapped one
+  keeps it.
+- **Broken objects** of a reloaded plugin are retried, as `ref.retry()` does.
+- **A parked object** of a reloaded plugin is replaced by the new factory's attempt in one handover: the new requests
+  bind before the old ones are released (the mechanism 7a removed comes back here).
+- **In-memory documents** migrate on reload through their definition's `migrate` (6a built the version check).
+
+:::review | Open 2: a `writable` across a pure swap
+A pure swap runs the new factory, so `self.writable(initial)` makes a new writable at its initial value. An object that
+contributes MCP's tool list through a writable then contributes an empty list until its restarted routine sets it again:
+the tools vanish for a moment. Options: (a) accept it (the routine refills it within one call); (b) keep a writable's
+value across a swap when the new factory declares a writable at the same position (as members are matched by name).
+Recommended: (a); writables have no names, and position matching would be the first positional rule in Chord.
+:::
+
+# Consumers Across a Reload {#consumers lede="Holds, versions and old calls; 7a decided that nothing is ended for a code change."}
+
+A reference on another host points at an object whose code may change under it. **Decided** (design §21, §22 and the
+dependency model):
+
+| The provider's reload | The consumer's hold | It sees |
+| --- | --- | --- |
+| still accepts the hold's version, object swapped | kept; re-subscribed through the version's mappings | one `[["r", value]]` per changed member |
+| still accepts it, object restarted | kept | `loading`, then a fresh `bound` |
+| stops accepting the version | unbound `version` | `failed { waiting }`; it binds again if a later reload accepts it |
+| removes the type | unbound `not_served` | `failed { waiting }`; it binds again when the type comes back |
+
+A provider accepts older consumers through `accepts`, written once with the provider, never in the shared contract
+(Q10):
+
+```ts
+export const NotesV2 = evolve(NotesV1, (e) => e.state("editor", "notes", arr(NoteV2)).args("add", NoteV2));
+
+host.serve(NotesV2, factory, {
+  accepts: {
+    1: {
+      state: { editor: { notes: (current) => current.map(toV1) } },   // what a v1 tab sees, as a diff per commit
+      methods: { add: { args: (old) => toV2(old) } },                 // a v1 tab's call, mapped forward
+    },
+  },
+});
+```
+
+- **Old-version calls:** `checkArgs` returns `{ kind: "method", args, result? }` or `{ kind: "call", args, call }`; Chord
+  runs the handler or the provider's replacement and maps the result back (L1 built the check; 7b invokes it).
+- **Adapted bindings get diffs:** Chord keeps the last adapted value per binding and sends `diffRevisions`, so an old
+  tab never receives a whole state per commit.
+- **On the wire** (7b's half of 7a's model): a `failed` on a bound hold unbinds it; the provider drops its unsent
+  pending work and keeps the ack slots of messages already sent; a consumer whose own code moves to a new version
+  releases its old hold and makes a new one.
+- **A consumer reloaded itself** gets new requests from its new factory; the handover binds them before it releases the
+  old.
+
+Today `host.serve` binds every provider with an empty accepts table (`host.ts`: `bindProvider(contract, {})`); 7b passes
+the provider's table. Small and **decided** in shape (Q10, `bindProvider`); the option's place is `host.serve(Type,
+factory, { accepts, linger })`.
+
+# Jobs Across a Reload {#jobs lede="Runs belong to the object; their versions are mapped forward."}
+
+**Decided** (design §15, owner 2026-10-24 and 2026-10-26):
+
+```ts
+const ExportJob = defineJob("notes.export", {
+  version: 2,
+  args: obj({ format: oneOf("md", "html") }),
+  result: obj({ path: str() }),
+  accepts: { 1: { args: (old) => ({ format: "md" }), result: (old) => ({ path: old.file }) } },
+});
+```
+
+- A run started on an older version finishes on its old code across a pure swap; `finish` and `running` see its args
+  and result mapped forwards, once per run.
+- Without an adapter, or for a run of a newer version (a rollback), the run is `blocked { version }` until a reload
+  brings matching code; blocked runs are retried on every reload. Nothing is aborted or discarded for a version change.
+- A native restart aborts running runs (`aborted { reload }`) and `finish` runs on the new code.
+- A job the new code no longer declares: its runs are `blocked { version }` (the same family), kept until a reload
+  declares it again or they are aborted.
+- Persisted runs of another version or fingerprint stay blocked with their record as stored, resolved by the reload
+  that brings their version.
+
+# Registries Across a Reload {#registries lede="A provider and its contributions are swapped in one batch."}
+
+**Decided** (slice 8 §6, design §17): the commit replaces a plugin's contributions and a registry's provider in one
+batch; staging composes nothing (D1). The record keeps the provider, facet contributions by plugin and object
+contributions by object apart, so a reload of one plugin replaces exactly its parts (today `RegistryRecord.serve`
+refuses a second serve). Older readers across a reload of the provider follow its new `accepts[old].value`. A reader
+waits (7a) when the new provider no longer serves its version. `retryOn` watches are re-declared by the new factory.
+
+# Across Hosts {#rollout lede="The same reload on every host, in an order that cannot deadlock."}
+
+**Decided** (design §21 and the dependency model): a revision is the complete code set; the server installs first,
+then workers, then clients; installs are serialized per host; a host that starts or reconnects installs the current
+revision first; a revision carries a code-set digest so an unchanged server restart reinstalls nothing; an install
+never waits for activations (a reverse-order rollout would deadlock); each host knows only its own install: while it
+installs, holds that do not fit its running code wait `installing`, re-evaluated when the install ends; a host whose
+own install was rejected fails its own requests with the reason.
+
+:::steps | The notes contract goes from v1 to v2; the server installs first
++++ Before
+S, W and T run revision R. T's notes view holds W's `Notes` v1. All live.
++++ S installs R+1
+S has no notes objects of its own; its install commits. T, still on R, holds nothing on S that changed.
++++ W installs R+1 with `accepts[1]`
+W's `Notes` v2 swaps in place and still accepts v1: T's hold is re-subscribed through the mapping and gets one diff.
++++ W installs R+1 without `accepts[1]`
+T's hold becomes unbound `version`: `failed { waiting }`, last notes readable, calls reject with "update the page".
++++ T reloads its page
+T's new code holds v2 with a new hold id; it binds; the old hold is released.
+:::
+
+:::review | Open 3: who runs the rollout
+Chord's part is per host: `host.reload`, the `installing` state, and what a hold sees. The rest is distribution:
+building bundles, sending them to workers, telling tabs to reload, ordering, the digest. Options: (a) Chord ships a
+rollout protocol over its links (an `install` message from the server down, `installed`/`rejected` up, the digest in
+`hello`); (b) distribution is the app's (p3's base code calls `host.reload` on each host and orders them), as p2 does
+today (`apps/p2/src/hosts/server.ts` `performReload`: prepare every host, commit, publish bundles). Recommended: (b) for
+7b, with Chord's per-host guarantees; a protocol only if a second app needs the same code.
+:::
+
+:::review | Open 4: the install watchdog (design §26 #24)
+An install that hangs (a bundle that never loads, a staging factory that awaits forever, which it may not) leaves its
+holds `installing` forever. Options: (a) a watchdog: `host.reload` rejects after `installTimeout` (default 60 s) and the
+host stays on its old code; (b) no Chord timer: the app's context bounds the reload. Recommended: (b): `reload` takes a
+context like everything else, and the app passes its deadline; a host option would be the only timer left in reload.
+:::
+
+# Decisions {.epilogue lede="What is settled for the spec, and what the owner decides first."}
+
+**Decided** (spec material): the four steps and rollback per host; the three fates and the parking of a swap with a
+missing dependency; old calls on old handles (R15); derives matched by member name; the routine handover; new instance
+ids on restart; broken objects retried on reload; the handover of a parked attempt; in-memory `migrate`; holds kept,
+re-subscribed or freshly bound; unbound `version` and `not_served` instead of `gone`; old-version calls and adapted
+bindings as diffs; `accepts` in `host.serve`; jobs' version mapping, `blocked { version }` and retries on reload, runs
+aborted on a native restart; registries swapped in one batch; rollout order, serialized installs, the digest,
+`installing`, installs never waiting for activations; loader D's design: one script per facet, host packages passed in,
+contracts bundled, no module map, stable script names, plugins' npm dependencies installed with `--ignore-scripts`.
+
+**Open** for the owner:
+
+| # | Point | Recommended |
+| --- | --- | --- |
+| 1 | the API: `host.reload(facets, ctx)` returning a report, or `load` callable again | `host.reload` |
+| 2 | a `writable` across a pure swap: back to its initial value, or kept by position | back to initial |
+| 3 | who runs the rollout: a Chord protocol, or the app calling `host.reload` per host | the app |
+| 4 | the install watchdog: a host option `installTimeout`, or the app's context | the app's context |
+| 5 | where loader D lives: Chord (`chord/next/loader`), or the app | Chord |
+| 6 | the app kit: Chord ships loader, HTTP, workers, web, TUI and dev reload as optional subpaths, or only the loader | Chord ships them, in that order |