@earendil-works/chord 1.4.0 → 1.5.1

package/docs/slice-7b.md

@@ -0,0 +1,255 @@
+# Slice 7b: reload in the kernel (spec)
+
+Status: **built** (2026-10-29; the rules folded into `design.md` §21, §6, §7, §15, §17, §22, §27). Spec: owner,
+2026-10-29, the brief `slice-7b/` and its six points decided as recommended, decision "Slice 7b's open points, as
+recommended"; decisions of the build, below each section where they apply (owner, 2026-10-29). 7b builds `host.reload` and everything an object, a reference, a job and a
+registry does across it, on one host. Facets are passed in imported (tests import them statically); the bundler and
+the dev loop are slice 7c, the rollout across hosts is the app's.
+
+Read in full before writing code: this spec, the brief `slice-7b/book.md` (chapters "One Host Reloads" to "Across
+Hosts"), `dependencies/model.md` (decided; built for 7a, its 7b parts are listed in its status line), `design.md` (§5,
+§6, §9, §14, §15, §17, §21, §22, §27), `decisions.md` (the 2026-10-29 entries; R15, R16, Q10, "The seal fence", "Job runs
+belong to the object", "A native restart drains first", "Slice 8 D1"), `slices.md` (slice 7b's carry-over: every entry
+is in this spec or named as out of scope in §12).
+
+## 1. The API
+
+```ts
+interface Host<P> {
+  load(facets: readonly PluginFacet<P>[], context: Context): Promise<void>;                 // once, first
+  reload(facets: readonly PluginFacet<P>[], context: Context): Promise<ReloadReport>;      // after load, any number
+}
+type PluginFacet<P> = { readonly name: string; readonly facet: Facet<P> };
+
+type ReloadReport = {
+  readonly plugins: { readonly added: readonly string[]; readonly changed: readonly string[]; readonly removed: readonly string[] };
+  readonly objects: readonly ReloadedObject[];                  // every live, activating, parked or failed object of a reloaded plugin
+};
+type ReloadedObject = { readonly object: string } & (
+  | { readonly kind: "swapped" }                                // pure, in place
+  | { readonly kind: "restarted" }                              // natives: drained, closed (`reload`), activated again
+  | { readonly kind: "ended" }                                  // its type is gone
+  | { readonly kind: "parked"; readonly cause: FailureCause }   // the new code waits for a dependency (decision 4)
+  | { readonly kind: "retried" }                                // it was failed or parked; a new attempt runs on the new code
+);
+```
+
+- `facets` is the host's **complete new plugin set**: a plugin in it and not loaded is added; one in it and loaded is
+  changed (Chord compares no code), unless its facet is the very same object as the loaded one (`===`): that plugin
+  is unchanged, untouched and not in the report (owner, 2026-10-29); one loaded and not in it is removed. The core
+  facet is a plugin like the others; base code passes the same facet value every time.
+- `reload` resolves once the commit happened and every object has taken its fate (§4): swaps done, restarts and retries
+  started (it does not wait for them to go live; their outcome is in their `ref.state`). It rejects with the code error
+  when load or staging fails, and nothing has changed. Reloads are serialized per host (a second call waits for the
+  first). Before `load` resolved: throws; after `host.close`: rejects `released/closed`. `context` bounds the reload
+  (decision 4: no install watchdog); its abort before the commit rejects `aborted` and changes nothing; after the commit
+  it only ends the wait.
+
+## 2. Staging (all or nothing; **superseded** 2026-10-30 by "Per plugin at startup and reload": a failing plugin keeps its old code, slice 7c §4)
+
+1. **Setups.** Every facet's setup runs into a **staged** table, beside the live one: served types (with their factory,
+   options and `bindProvider(contract, options.accepts)`, which runs `checkAccepts`), served registries (provider
+   with `compose` and `accepts`), facet contributions. The checks of `load` apply (plugin names, a type or registry
+   served twice, a remote type on a host without principal or address).
+2. **Factories.** For every object of a changed or removed plugin's types that exists now (live, activating, parked,
+   failed), and whose type is still served: the new factory runs against a **recording `self`**, with the object's
+   params (and principal), and declares only: what it opens (`self.open`), the documents and tables it declares with
+   their versions, its jobs with their versions, its contributions, its requests. Nothing is activated, bound or
+   opened; handles from a recording `self` are inert. This gives each object's fate (§4) before the commit.
+3. **Any throw** (a setup, a factory, `checkAccepts`, a declaration error) rejects `reload` with that error, names the
+   plugin (and object), and the host stays entirely on its old code: the staged table is dropped.
+4. **While staging,** the host is **installing** (model §1): a hold that arrives for a type or version that the running
+   code does not serve waits `installing` (`loading`) instead of `not_served`/`version`, and is re-evaluated when the
+   reload ends, by its commit or its rejection.
+
+## 3. The commit (one batch)
+
+In one `batch.commit`, synchronous:
+
+- The served types table becomes the staged one: added and changed types replace their entries (factory, provider,
+  `linger`); removed types are dropped.
+- **Registries** (slice 8 §6): a changed or added plugin's provider replaces the old one (`RegistryRecord.serve` refuses
+  a second serve today: it becomes `replace` for a reload); a removed plugin's provider goes (its readers become
+  unbound `not_served`); the reloaded plugins' facet contributions replace theirs, by plugin; object contributions stay
+  with their objects (they follow the objects' fates); every changed table recomposes once, lazily, as today. The record
+  keeps the provider, facet contributions by plugin and object contributions by object apart.
+- **The publication** (model §4): after the batch, the unbound requests waiting for the names the reload serves (types,
+  registries, versions) are re-evaluated (`UnboundIndex.wake(names)`, per name: the carry-over "Publications wake per
+  name"), refused holds for those names re-run their start, and `installing` holds are re-evaluated against the new
+  code.
+- `host.references(Type)` of a removed type is dropped (carry-over from 4b).
+
+## 4. Fates
+
+Each object of a changed or removed plugin's types takes one fate, decided in staging (design §21, decisions above):
+
+| The object | Fate |
+| --- | --- |
+| its type is removed | **ended**: as an object end today (natives close with reason `end`, callers of running calls rejected `released`, handlers drained); its requests are released; its holders' requests become unbound `not_served` (§6) |
+| failed or parked | **retried**: its attempt is replaced by one of the new factory (a parked attempt in one handover: the new requests bind before the old ones are released; the mechanism 7a removed comes back here, carry-over) |
+| live, old and new code open no natives, and no table of the new factory is at a newer version | **swapped** in place (§5) |
+| live, otherwise | **restarted**: new calls park (the gate closes, holders see `loading`), running calls drain (bounded by `closeTimeout`; a call outliving the drain is cut off by the seal fence), the attempt is sealed, natives close (reason `reload`), the new factory's attempt activates (documents stay; eager table migrations run as at activation) |
+| any of the above whose new factory declares a dependency that is not there | **parked** on it (decision 4): the gate stays closed, holders see `loading` or `failed { waiting }`; no overlap of old and new code |
+
+- A restarted object gets a new instance id (an old activation chain must not match it, carry-over from 4b); a swapped
+  object keeps it; a retried one keeps it, as any retry does (slice 4b; fix round 1, Opus F3).
+- Objects of plugins not in the reload are untouched; their requests to changed types follow §6.
+- Host-lifetime objects of an added plugin start after the commit as at `load` (no barrier: `reload` does not wait for
+  first outcomes).
+
+## 5. The pure swap
+
+A pure swap is not a replacement (decision "The seal fence"): the old attempt is not sealed while its calls run.
+
+- **Gate.** For the swap itself the gate closes; new calls park (bounded) until the new attempt is live.
+- **New attempt.** The new factory's attempt is made with the same object: same documents and line (they are the
+  object's), same job records. Its requests are made and bound before the old attempt's are released: a request equal
+  to an old one (same type, params, principal, version) binds to the same target with no gap. It parks if a new
+  dependency is not live (§4, parked). It runs its own steps (no natives by definition: derives, member checks), its
+  members re-bind by name (`#rebind` exists: one frame from the last value per member; a member the new variant lacks
+  fails `invalid/member`), its contributions replace the old attempt's in the registries in one batch, its routines
+  start after the handover (below), its jobs take over the job records (§8).
+- **Old calls.** Running calls finish on the old attempt with its handles valid (their transactions commit) until they
+  settle, except R15: an old call touching a document whose version rose throws once (the document intact, the call
+  not resent); the same for a table whose version rose (old table handles' version fence, carry-over from 6a: old code
+  never issues SQL for a dropped column). Once the old attempt's calls settled, it is sealed and its references are
+  released.
+- **Routines** hand over per object: the old attempt's routines are aborted; the new ones start once the old routine
+  calls finished, bounded by `closeTimeout` (a stuck one is reported and the new ones start anyway); calls never wait for
+  it; each old routine invocation is fenced on its own (carry-over from 6a).
+- **Derives** have no names: exposed derives are matched by member name (references move to the new instance's members, §13
+  item 11); internal ones are rebuilt.
+- **In-memory documents** migrate through their definition's `migrate` when the new code declares a higher version
+  (6a built the slot version check; carry-over).
+- **`self.writable`** starts at its new initial value (decision 2).
+- **`retryOn`** sources are re-declared by the new factory.
+
+## 6. References across a reload
+
+**Provider side** (holds this host serves, and bindings on this host):
+
+| The reload | A hold or binding |
+| --- | --- |
+| the object is swapped, its version still accepted | kept; re-subscribed through the version's mappings; one `[["r", value]]` per member whose value changed |
+| the object is restarted, version still accepted | kept; `loading`, then a fresh `bound` (a `bound` on a bound hold, which 4a's consumer applies as a re-binding) |
+| the new code no longer accepts the hold's version | unbound `version` (`failed { waiting }`); the object and its other holds stay |
+| the type is removed | unbound `not_served` (`failed { waiting }`) |
+
+- **Over a link,** a `failed` on a bound hold unbinds it (model §5): the consumer applies it as `#startOver` plus
+  `failed`; the provider detaches the hold's sources, drops its unsent pending ops and a queued `bound`, keeps the ack
+  slots of `bound`/`state` messages already sent until their `ack` or the link's loss, and rejects the calls in flight on
+  it once. `Hold.moved` and `ProviderSide.unbind` handle bound and binding holds (carry-over from 3a/6a). A served hold
+  whose object leaves `live` while its `bound` waits for a slot goes back to pending.
+- **On the same host,** a `Binding` whose target ended by removal becomes unbound and accepts a second `bind` (model
+  §5): the reference moves its members to the next object by name (§13 item 11), keyed pins re-pin, parked calls flush or reject, presence lists it again.
+- **The consumer's own reload:** the new factory makes new requests (§5's handover). A reference made by outside code
+  (`host.hold`) keeps the token its caller passed; Chord reloads no caller code.
+- **A remote object that leaves `live`** (`RemoteObject.failed` ignores a failure while live today): handled by the
+  unbinding above.
+
+## 7. Versions in use (`accepts`)
+
+- `host.serve(Type, factory, { accepts, linger })`: today every provider is bound with an empty table
+  (`bindProvider(contract, {})`); 7b passes `options.accepts`, checked by `checkAccepts` at the setup (a declaration
+  error rejects the reload or the load).
+- **Binding an older consumer:** a hold whose version is accepted binds through the mappings of that version (Q10):
+  state members through `(current) => old`, served like a derive of the provider's member per object and version
+  (adapted bindings get diffs: the last adapted value per object and version, `diffRevisions`, never a whole value per
+  commit; §13.11); method calls through
+  `checkArgs`: `{ kind: "method", args, result? }` runs the handler and maps the result back with `result`; `{ kind:
+  "call", args, call }` runs the provider's replacement (L1 built the check; 7b invokes it). Removed state members with
+  `"refuse"` and removed methods with `"refuse"` fail the binding or the call `contract_mismatch`.
+- **Keyed members** are mapped per key (carry-over from 6a), only on `local` contracts.
+
+## 8. Jobs across a reload
+
+- **Job records** keep the definition of the version their runs were started with; the new attempt's `self.job(Def,
+  impl)` at another version no longer throws (`ChordObject.jobRecords` today): the records take the new definition, and
+  each run keeps its own version.
+- A run started on an older version and still running finishes on its old code across a pure swap (its invocation keeps
+  the old implementation); `finish` runs on the new code with the outcome's args and result mapped forwards through
+  `accepts[old]` (once per run); `running` shows its args mapped.
+- No adapter for a run's version, or a run of a newer version (a rollback): the run is `blocked { version }` until a
+  reload brings matching code; blocked runs (also `finish_failed` ones) are retried on every reload.
+- A native restart aborts running runs (`aborted { reason: "reload" }`); `finish` runs on the new code.
+- A job the new code no longer declares: its runs are `blocked { version }` (kept, not invoked) until a reload declares
+  it again or they are aborted; a persisted run of another version or fingerprint stays blocked with its record as
+  stored and is resolved by the reload that brings its version.
+- A `finish` in flight across a reload completes on the code it started with; the next one runs on the new code.
+- A job's fingerprint covers args, result and state: a schema change without a version bump is refused at declaration
+  (as documents).
+- An older run's state document migrates through its own `migrate` only once its run settled or moved to the new code
+  (the old code keeps writing the version it knows).
+
+## 9. Errors, cycles, presence
+
+- A broken object of a reloaded plugin is retried (as `ref.retry()`), whatever broke it.
+- Cycles: the walk and chains as today, checked again for the new attempts; `parked_long` unchanged.
+- Presence: holds kept across a swap stay listed; a restart lists them again when they re-bind.
+
+## 10. Telemetry and reports
+
+`onError` gets what fails after the commit as today (`activation_failed`, `close_failed`, `routine_failed`, …). No new
+`HostError` kind; the report returned by `reload` is the summary.
+
+## 11. Tests, examples, cost
+
+- One `describe` per mechanism: the API (serialized, before load, after close, abort before and after the commit);
+  staging (each kind of throw leaves the host unchanged; recorded declarations decide the fate); the commit (types,
+  registries, per-name wakes, `installing` holds); each fate (swap, restart, end, retry, parked, a new dependency
+  missing); the swap (old calls on old handles, R15 for documents and tables, the handover of references without a gap,
+  member re-binding, routines handed over and fenced, derives, in-memory migrate, a writable back to initial);
+  references (each provider-side row over a memory link and through a relay, the window full while unbinding, a
+  removed-then-re-served type with a live local dependent and with a remote one); `accepts` (state mapped per object and version as
+  diffs, old args mapped, a result mapped back, a replacement `call`, `"refuse"`, keyed members per key); jobs (each
+  rule of §8, in memory and persisted); registries (provider replaced, contributions by plugin replaced, a reader of an
+  older version); a three-host scenario (server, worker, tab) reloaded in the app's order, as an example's test.
+- Examples: `33-reload.ts` (a pure swap, a restart and a removal, with old calls and holders shown) and `34-versions.ts`
+  (a contract and a job at v2 with `accepts`, an old tab and an old run carried across).
+- Benchmarks: the hot paths against HEAD (calls, commits through a watched derive, activation, links) within the bar;
+  plus a reload benchmark (one plugin of 20 reloaded on a host with 1,000 live objects, swap and restart) reported in
+  `benchmarks.md`.
+- GC tests: an old attempt and its closures collected after its calls settled; a removed type's objects, providers
+  and registry entries collected; an old facet's code collected after a reload (the precondition for loader D).
+
+## 12. Out of scope
+
+Slice 7c: the bundler and loader (`chord/loader`), the dev loop (`chord/dev`), plugin discovery and npm
+dependencies. The app: the rollout across hosts (decision 3: it calls `host.reload` per host in order). Slices 10 and
+11: the app kit. `rebuild` of tables (key or column-type changes): only if a case needs it (carry-over stays).
+
+## 13. Decisions of the build (owner, 2026-10-29; 11 is the builder's, reported for review)
+
+1. An object of a reloaded plugin that is activating but not parked (its own steps), or waiting for its backoff, is
+   `retried` (an activating attempt sealed, its natives closed `reload`).
+2. The report's `parked` is for swaps and retries whose new attempt's first dependency check is not live (`reload`
+   waits for that check, not for live); restarts are reported `restarted` at once (their check follows the drain). A
+   blocker that is only loading gives the cause `waiting` "waiting for X: X is loading".
+3. A swapped-out attempt is sealed once its running calls settled (bounded by `closeTimeout`, `drain_timeout`) and
+   the swap ended; its references are released then. Its job invocations finish on their old code. Retiring
+   attempts are bounded by `closeTimeout` each; a later swap does not wait for them (several may retire at once after
+   quick reloads), a restart, an end and the host's close do (an end rejects their callers at once). (Fix round 1:
+   Fable, Opus F1.)
+4. A stuck old routine call past the handover is reported `drain_timeout`; the old attempt's routine calls share one
+   fence token, sealed when the new routines start.
+5. A swap whose new factory picks another variant sends its holds a fresh `bound`; so does one after which a hold's
+   version is an older one (adapted members).
+6. A native restart: in-memory runs end `aborted { reason: "reload" }` and finish on the new code; persisted runs
+   follow 6b R3 (a seal while the object continues is a clean stop): written back stopped, resumed per `resume` by the
+   new attempt without counting a restart.
+7. Staging is synchronous; `installing` is built and tested from inside a staged factory.
+8. ~~A removed object's member sources and pinned keys are frozen and handed over to the next object of its identity.~~
+   **Superseded** (owner, 2026-10-29, decision "References are the only indirection"): references keep their last
+   values while unbound and move their subscriptions to the next object; nothing is handed between objects.
+9. A loaded plugin passed as the same facet object is unchanged (§1).
+10. Keyed members' versions (§7) are built with L1's keyed edits (`keyed`, `addKeyed`, `removeKeyed`) and an accepts
+    section `keyed: { member: (current) => old | "refuse" }` (removed ones: `"refuse"`).
+11. Adapted state members are shared per object instance and version (not per binding): one cached value and one diff
+    per commit for every consumer of a version; each hold encodes its own ops. Fix rounds 1 to 7 built sources owned by
+    (identity, version) that outlived their object and moved to the next one (`host/handover.ts`), and kept finding
+    edge cases in that hand-over. **Replaced** (owner, 2026-10-29, decision "References are the only indirection"): a
+    consumer's watches and derives attach through the reference's member, which passes them straight to the object's
+    own document or derive and moves them when the reference's target changes (one frame); while unbound the reference
+    keeps its last values (watches get one `failed` call); an older consumer attaches to the instance's shared mapping
+    for its version (made on first use, dropped when no reference of the version is left, gone with the instance).
+    Nothing outlives its object instance.

package/docs/slice-7c.md

@@ -0,0 +1,165 @@
+# Slice 7c: plugins (spec)
+
+Status: **ready to build** (owner, 2026-10-30: decisions "Slice 7c's points" and "Per plugin at startup and reload";
+spec reviews by Fable and Opus, `/tmp/s7c-spec-review-{fable,opus}.md`, folded in). 7c builds `chord/plugins`: the
+code that turns plugin directories into facets, loads and reloads them per plugin, and watches them. A Chord app is
+self-modifying (the owner or an agent edits a plugin while it runs), so this is core machinery, not a dev tool (no
+dev/prod split). It also changes the kernel's `load` and `reload` to per-plugin failure (§4). HTTP and workers are slice
+10, the web page host and the TUI slice 11: 7c builds scripts for every surface and evaluates them on Node; its build
+results are plain data those slices ship.
+
+Read in full before writing code: this spec; `decisions.md` (2026-10-29/30: "Slice 7b's open points, as recommended",
+"A plugin's npm dependencies are bundled", "Per plugin at startup and reload", "Slice 7c's points"); `design.md` (§3
+`load`/`reload`, §16, §18, §21 in full); the 7b brief `slice-7b/book.md` (chapters "A Plugin, File by File", "Building
+and Loading", "Assets and Files", "Performance", "A Mini p2 from Chord"); the two spec reviews; p2's
+`apps/p2/src/hosts/{bundles,plugins}.ts` and `apps/p2/docs/plugin-loading.md` §4.1, §7.1, §8, §9, §14; coding-agent's
+`packages/coding-agent/src/core/package-manager.ts` (dependency installs). Code lives in
+`packages/chord/src/node/plugins/` (Node-only: `fs`, esbuild, `vm`; the kernel stays portable),
+exported as `./next/plugins` when v2 gets its entry point; until then tests import the source.
+
+## 1. A plugin on disk
+
+```text
+plugins/notes/
+  package.json        "name": the plugin's name (required, npm style); "dependencies": bundled; "peerDependencies":
+                      host packages; "chord": { "external": ["better-sqlite3"] } (optional, Node facets only)
+  server.ts  worker.ts  web.tsx  tui.ts      one file per facet kind the app names; default export: a facet
+  contract.ts  store.ts  NoteList.tsx  notes.css  assets/…   plain files
+  node_modules/       its own npm dependencies (`installDependencies`)
+```
+
+- The plugin's name is its `package.json` `name`, never the directory name. A directory without a `package.json`, or
+  with an invalid name, is reported, not a plugin.
+- Facet kinds are the app's (`["server", "worker", "web", "tui"]` in p3), each `.ts`, `.tsx`, `.js` or `.mjs`; two
+  files of one kind are reported (not chosen by extension). A plugin with none of the kinds (contracts only) is a
+  plugin with no facets: imported by others, never loaded.
+- Discovery lists each root one level deep, reads only `package.json`, follows symlinks to their real paths, and keeps
+  the first root's plugin of a duplicate name (the other reported).
+
+## 2. Building
+
+```ts
+const plugins = await discoverPlugins(["./plugins", join(dataDir, "plugins")], { kinds: KINDS }, ctx);
+const built = await buildFacet(plugins[0], "worker", { hostPackages: HOST_NAMES, platform: "node" }, ctx);
+// { kind: "script", plugin, facet: "worker", source, digest, inputs: [{ file, hash }], copied: [file],
+//   css?: { name, text }, assets: [{ name, bytes }] }   |   { kind: "failed", plugin, facet, errors }
+```
+
+One esbuild build per (plugin, kind), from cold (no kept contexts: about 10 ms per facet; p2 measured 237 ms for 25
+worker facets). A failed build is a result, never a throw. The result is plain data (strings, bytes, arrays): the same
+value a worker (slice 10) or a page (slice 11) evaluates where it runs.
+
+| An import of | Becomes |
+| --- | --- |
+| the plugin's own files | inlined |
+| a file of another discovered plugin (`../sessions/contract.ts`) | inlined (a copy), listed in `copied`; it may import only host packages and files of its own plugin, never packages (a build error otherwise): contracts and side-effect-free modules only (decision 4) |
+| a package in the plugin's `dependencies` | inlined from its `node_modules` |
+| a package in `chord.external` (Node builds) | external, `require`d at evaluation from the plugin's `node_modules`; a browser build fails |
+| a host package (`options.hostPackages`, e.g. `@earendil-works/chord`, `react`, `react/jsx-runtime`, `@app/core`) | external, from the map at evaluation |
+| `@earendil-works/chord/plugins` | external always (its `pluginFile` is per facet, §3) |
+| a Node builtin (`node:fs`, `fs`) | external (Node builds); a browser build fails |
+| CSS (browser builds) | one stylesheet per facet (`css`) |
+| an asset (`import url from "./icon.svg?url"`, `.wasm`, browser builds) | a content-hashed file in `assets`; the import is its URL under the app's `options.publicPath` |
+| `import.meta.url`, `__dirname`, `__filename`, a literal dynamic `import("x")`, top-level `await` | a build error pointing to `pluginFile` (§3); a computed `import(x)` cannot be seen at build and fails when it runs, through the facet's `require` naming the facet |
+| anything else (a relative path into base code, a package not in `dependencies`) | a build error naming the file and the rule |
+
+- Output: `format: "cjs"`, wrapped `(function (require, module, exports) { … })`; TypeScript stripped, JSX automatic
+  (`react/jsx-runtime`); no type check; minified; an inline source map whose `sources` are relative to the plugin's
+  directory (so the script and its `digest`, a hash of the source, are the same on every machine and checkout).
+- `inputs` are captured where esbuild loads each file (an `onLoad` that hashes the exact bytes it hands esbuild, as p2's
+  `captureBundleInputs`; the metafile has no hashes), absolute paths, for the watcher.
+
+## 3. Evaluating (Node)
+
+```ts
+const facet = evaluateFacet(built, { hostPackages: HOST, plugin });   // returns the facet, or throws its error
+```
+
+- `vm.Script` under a stable filename per (plugin, kind, digest), path-like (`/chord-plugins/@pi/notes/worker.ts`
+  plus the digest), run in this context; the default export, checked to be a facet (a declaration error otherwise).
+- **The `require` it passes answers, in order:** the host-package map (each value is what Node's `require` would give:
+  a CommonJS package's exports, an ESM package's namespace wrapped once with `__esModule: true`, so default and named
+  imports both work); `@earendil-works/chord/plugins` → `{ pluginFile }` bound to this plugin's directory;
+  `chord.external` packages and Node builtins through `createRequire(join(plugin.dir, "package.json"))`; anything else
+  throws naming the facet.
+- **`pluginFile(path)`** gives the absolute path of a file inside the plugin's directory; `..` out of it is refused.
+- **No module map, no cache:** an old facet's closures are collected once nothing holds them. The component turns V8's
+  compilation cache off when it is created (`v8.setFlagsFromString("--no-compilation-cache")`, once per process; an
+  app may pass the flag itself).
+- **Stack traces** (decision Q1 (b)): `mapStack(error)` returns the error's stack with plugin scripts' positions mapped
+  through their source maps (a `module.SourceMap` per evaluated script, kept while the script is) to `notes/worker.ts:12`;
+  the app's reporters call it. Nothing global (no `Error.prepareStackTrace`, no process-wide source-map switch).
+
+## 4. Loading and reloading, per plugin (kernel change)
+
+Decision "Per plugin at startup and reload" changes `host.load` and `host.reload` (slice 7b) and the component's
+`load`/`reload` helpers:
+
+- **`host.load(facets, ctx)`** resolves with `{ failed: [{ plugin, error }] }`: a plugin whose setup throws (or that is
+  refused at declaration: invalid name, a type or registry served twice, a remote type on a host without principal or
+  address, `checkAccepts`) is left out and reported; the others publish; its consumers wait `failed { waiting }`. `load`
+  never closes the host for a plugin (base code decides whether its core failing is fatal). A plugin left out is
+  loaded by the next reload after an edit rebuilt it (it is dirty).
+- **`host.reload(facets, ctx)`**: staging per plugin. A plugin whose new code fails in staging (setup, a factory against
+  the recording `self`, a declaration error, `checkAccepts`) keeps its loaded facet (as if passed unchanged), and
+  staging runs again without its new code. **The closure rule:** a changed plugin whose recorded requests (staging
+  records them, for its existing objects, with their contract versions) would not bind (the same check as a real
+  bind, the provider's host address included) because the plugin they need was kept old, or because nobody serves the
+  name while any plugin of this reload failed (a failed new setup may be what would have served it: owner, 2026-10-30,
+  "keep"), is kept old too (repeat until stable). The report gains `failed: [{ plugin, error }]` (the same list as `load`'s; an added plugin that fails is left out); the commit applies the rest.
+- **The component** builds and evaluates per plugin: a plugin whose build fails or whose evaluation throws is passed to
+  the host as its loaded facet at a reload, with `reload(facets, context, { failed })` naming it (the host applies the
+  closure rule to it and lists it in `failed`), left out at startup and reported with the host's report.
+  `plugins.load(host, ctx)` and `plugins.reload(host, names, ctx)` keep, per host, the facet loaded for every plugin, so
+  `reload` always passes the complete set (unchanged plugins as the same facet object, removed ones left out) and never
+  restarts an unchanged plugin.
+
+## 5. Watching and rollout
+
+```ts
+const plugins = createPlugins({ roots: ["./plugins"], kinds: KINDS, hostPackages: HOST, base: ["./src"] }, ctx);
+plugins.state      // a JSON watchable: { dirty: ["@pi/notes"], install: ["@pi/notes"], set: false, base: false }
+const next = await plugins.build(["@pi/notes"], ctx);                 // built results per (plugin, kind), plain data
+await rollout([serverStep, ...workerSteps, ...clientSteps], next, ctx);   // the app's order (decision 3)
+```
+
+- **The watcher** (`fs.watch` recursive over roots and `base`) ignores `node_modules` and `.git`. A changed file marks
+  dirty every plugin whose facets used it (`inputs`; a copied contract dirties every user) or whose directory contains
+  it; a changed `package.json` marks `install`; a plugin directory added or removed sets `set` (discovery runs again
+  at the next build); a file under `base` sets `base` (the app restarts its hosts; Chord restarts nothing). A change
+  during a build keeps its mark. If the watcher cannot watch (the system's limit), it reports once and the app builds
+  on demand. It marks, never applies.
+- **`installDependencies(plugin, ctx)`**: `npm install --omit=dev --legacy-peer-deps --ignore-scripts --no-audit
+  --no-fund` in the plugin's real directory, the command overridable (decision 3); it clears `install`.
+- **`rollout(steps, built, ctx)`**: each step is `{ name, kinds, reload(built, ctx) }` and returns the host's report;
+  steps run in order; a step's `reload` evaluates the facets of its kinds where its host runs (an in-process step through
+  the component's per-host state, §4; a remote one, slice 10/11, gets the built data). It stops at a step that rejects
+  (a host closed, an abort); kept plugins do not stop it. Marks clear for plugins applied on every step; a plugin kept
+  on any host stays dirty.
+
+## 6. Not in 7c
+
+Installing plugins from npm or git (p2 §8), project plugins with trust and snapshots (design §26 #14), a base bundle per
+surface, evaluating in a browser (slice 11), shipping built scripts to workers and pages (slices 10, 11), static checks
+of cross-plugin imports beyond §2's rule.
+
+## 7. Tests, examples, cost
+
+- One test file per source file; fixture plugins under `test/node/fixtures/plugins/`. Discovery (names, duplicates,
+  missing or invalid `package.json`, two files of a kind, contracts-only plugins, symlinks); build (every row of §2's
+  table, failures as results, relative source maps and stable digests across two checkout paths, inputs hashed at
+  load); evaluation (host packages as the host's instances: `instanceof ChordError` across a plugin; default and named
+  imports of ESM and CommonJS host packages; `pluginFile` and its `..` refusal; an import-time throw; a non-facet
+  export); `mapStack` naming plugin files and lines; per plugin at startup and reload (§4: a failing setup, factory,
+  declaration, build, evaluation; the closure rule with a provider and consumer changed together; the report's `failed`
+  and `failed`; `load` never closing the host); the watcher (dirty marks from inputs and directories, `install`, `set`,
+  `base`, a change during a build, `node_modules` ignored); `rollout` (order, stopping at a rejecting step, marks).
+- **GC:** 200 reloads of an evaluated plugin facet: old closures collected, heap flat after warm-up.
+- **End to end:** a server and a worker (memory links) loading plugin directories, a plugin edited on disk, built and
+  rolled out (server, then worker), a holder seeing one frame; a broken edit kept old on both hosts and reported.
+- Examples (owner, 2026-10-30: full coverage, each a folder `NN-topic/` with the hosts in `main.ts` and real plugin
+  directories under `plugins/`): `35-plugins` (load, edit, build, rollout), `36-plugin-failures` (per plugin at startup
+  and reload, the closure rule, an abort after the commit), `37-plugin-imports` (copied contracts, dependencies,
+  `chord.external`, host packages, `pluginFile`, the refusals), `38-watch-and-rollout` (the marks, plugins added and
+  removed, a stopped rollout), `39-browser-build` (CSS, assets, the built result as plain data). Benchmark (`benchmarks.md`): cold build of a 20-plugin set, a rebuild of one facet,
+  evaluation per facet, heap after 100 reloads.

package/docs/slice-8.md

@@ -0,0 +1,194 @@
+# Slice 8: registries and `host.root` (spec)
+
+Status: **built** (2026-10-28; build review and two fix rounds by the same four reviewers,
+`/tmp/s8-build-review-*.md`, `/tmp/s8-build-rereview-*.md`). Before: ready to build (2026-10-27; D1-D3, the registry failures and S1-S3 decided by the owner; two spec reviews,
+`/tmp/s8-review{,2}-{astra,fable,opus,sol}.md`, found no remaining blocker; S3 refined after the second: with no value
+after `load`, a reader fails at once, as `self.get` of a type not served here)
+
+8 builds the extension point between plugins (registries), in-process values that change (`self.writable`), wake
+signals for failed objects (`retryOn`), and the call scope for code outside objects (`host.root`). The harness object
+is p3's base code; Chord shows it only in an example.
+
+## What an app can do after this slice
+
+```ts
+// the defining plugin (e.g. http): the token, exported for other plugins
+export const Http = defineRegistry<HttpContribution, Router>("chord.http", { version: 2 });   // shared: identity only
+export default defineFacet((host, self) => {
+  host.serve(Http, {                                              // the one provider (Q8), as for object types
+    compose: (table, { report }) => buildRouter(table, report),   // pure; always a value; conflicts reported
+    accepts: { 1: { contribution: (old: HttpContributionV1) => upgrade(old), value: (router) => routerV1(router) } },
+  });
+  host.serve(HttpServer, (_, self) => {
+    const router = self.registry(Http);                           // a NativeWatchable of the composed value
+    self.on(router, ({ value }, ctx) => …);
+    return { … };
+  });
+});
+
+// any plugin: a facet or a host-lifetime object contributes one value per registry
+export default defineFacet((host, self) => {
+  self.contribute(Http, { routes: { "GET /notes/export": exportNotes } });
+});
+host.serve(McpStore, (_, self) => {                               // local, empty params (R21)
+  const ext = self.writable(mcpExtension([]));                    // an in-process value that changes
+  self.contribute(HarnessExtensions, ext);
+  self.on(mcp.tools, ({ value: tools }) => ext.set(mcpExtension(tools)));
+  self.retryOn(self.registry(HarnessModels));                     // a model contribution wakes a failed attempt
+  return {};
+});
+
+// code outside objects (a Durable tool, a CLI): a call scope
+await host.root(async (ctx) => (await ctx.get(Notes, { session })).add(note, ctx), context);
+```
+
+## 1. Registries
+
+- **Token and provider (D1, owner, 2026-10-27):** the token `defineRegistry<C, V>(name, { version })` is shared, as a
+  contract: its name (as types, `[a-z0-9@/._~-]`), the contribution type `C`, the composed value type `V`, and the
+  version the bundling plugin was built against. The defining plugin's facet provides it with `host.serve(R, {
+  compose, accepts? })`, as it serves object types (adapters with the provider, never in the shared token, as
+  `checkAccepts` for contracts); a second serve on a host is refused; a reload replaces it (slice 7).
+
+- **Contributors** (R21): facets (by plugin name) and host-lifetime objects (`local`, empty params: by plugin name and
+  type), at most one value per registry each; `self.contribute(R, value | Watchable | NativeWatchable)` in a facet setup
+  or such an object's factory (a type error elsewhere; a declaration error at runtime). A facet's contribution is in the
+  table while its plugin is loaded; an object's from `live` until it ends, fails or restarts.
+- **The table:** an immutable list of `{ contributor, plugin, value }`, sorted by plugin name, then type (never load
+  order); a contribution carries its token's version: an older one is adapted once with the declaration's `accepts`
+  when the table is built, an older one without an adapter or a newer one is left out and reported (`HostError`
+  `contribution_refused { registry, plugin, version }`).
+- **Contributions:** a plain value, or a Chord watchable (a `writable`, a derive, a document member; another
+  registry's value too, a cycle of registries reading each other refused when the second one serves or contributes (superseded by audit A2: caught at the first composition by the runtime guard, reported `contribution_failed`)), followed as a dependent of the table (its change recomposes), recognised by Chord's own mark; anything
+  else is a plain value, whatever methods it has (a harness, a conversation handle or a runtime is contributed as a plain
+  value, not followed; build review 2026-10-27, replacing "a foreign watchable is refused"). The table's entry is `{ plugin, type?, version, value }` (`type` for
+  an object contributor; served types carry their plugin's name).
+- **`compose(table, { report })`:** pure, lazy as a derive: the registry's value is marked when its table changes (a
+  contributor goes live or ends, a watchable contribution changes) and composed when read or, while watched, in the
+  owner's flush (W4: never by another owner's adoption itself; the flush after a commit step is where it runs). The first
+  composition happens at the serve: the facets' setups of one `load` serve and contribute, then every served registry
+  composes once in one batch at the end of the setups (an empty table composes too), so a served registry always has
+  a value before any object activates. `report(conflict)` goes to `onError` as `registry_conflict { registry, message,
+  plugins }`, once per conflict episode.
+- **Failures (owner, 2026-10-27):** contributions never fail the registry. A contribution that is a watchable and fails
+  is left out of the table and reported (`contribution_failed { registry, plugin, error }`), the table recomposes without
+  it, and it is back once it heals. A `compose` that throws (the owner's bug) is reported (`registry_failed { registry,
+  error }`), the composed value's watches get a `failed` call, and `.value` keeps the last good composition (an extension
+  point stays available; derives keep their own rule, `.value` throwing while failed); the next good composition
+  replaces it. Before any good composition `.value` throws the error.
+- **Without a provider** (the defining plugin is not loaded): the registry has no value; contributions wait in the
+  table; its serve composes it.
+- **Reading is a dependency (S3, owner, 2026-10-27: "isn't self.registry meant to wait like self.get?"):**
+  `self.registry(R)` in a factory declares the registry as a dependency of the attempt, as `self.get`: activation waits
+  until it has a value; once `load`'s setups ran, a registry with no value cannot get one before a reload (a provider
+  comes only with a plugin), so a reader then fails at once `transient` with `unavailable/undeclared` as the
+  dependency's cause (as `self.get` of a type not served here fails at once, and the start barrier waits for no
+  contribution) and is retried the moment the registry gets its first value (R18); a first `compose` that throws fails
+  its readers the same way. It returns a `RegistryValue<V>` (a native source: a derive source, an `on` source, a `retryOn` source; never a
+  state member); methods and routines read `.value` at use. Once the object is live, a later failure of the registry
+  (a throwing `compose`) changes nothing for it: `.value` keeps the last good composition. Code outside objects:
+  `await host.registry(R, ctx)` waits the same way.
+- **Older readers (S2, owner, 2026-10-27):** a reader whose bundled token has an older version than the provider's gets
+  the composed value mapped back with `accepts[old].value` (computed once per composition and version, while such a
+  reader exists); without that mapping, or for a reader newer than the provider, its dependency fails
+  `contract_mismatch` (reported). `accepts: { [old]: { contribution?: (old) => current, value?: (current) => old } }`.
+  Adapters are the provider's code, guarded as `compose`: a `contribution` adapter that throws leaves that contribution
+  out (reported `contribution_failed`); a `value` adapter that throws fails only that version's value, by the rules of a
+  throwing `compose` (its readers keep the last good mapped value; before any, a reader of that version waiting at
+  activation fails `transient`, retried when a mapped value arrives); current readers are never affected.
+- **Helpers:** `keyed(table, entriesOf, report)` (a map, a duplicate key reported through `report`, the first by plugin
+  name wins) and
+  `ordered(table, itemsOf, orderOf?)`.
+- **Use sites guard contributions** (Q8): Chord's helpers keep each entry's plugin name; the guide shows catching a
+  contribution's throws and rejections, reporting the plugin, and continuing.
+- **Registries carry natives** (design §17): a contribution may be any in-process value; an entry lives exactly as long
+  as its contributor.
+
+## 2. `self.writable(initial)` and native sources
+
+A `NativeWatchable<T>` with `set(value)` (identity compared: `set` of the same value notifies nobody; a new value is a
+new frame), owned by the attempt (dropped with it; `set` after the attempt's seal throws `released`); never a state
+member; usable as a contribution, a derive source and an `on` source. `set` inside a batch marks it there; outside, it
+opens its own batch. `writable`, `RegistryValue` and `ref.state` (a `NativeWatchable` since slice 3b, until now not derivable: design audit,
+2026-10-27) are native sources: one base (`NativeSource`) the batch marks and derives depend on; `self.derive` takes JSON and native sources (its type and the source resolver widen), while the
+member check still refuses a native as a state member.
+
+## 3. `self.retryOn(...sources)`
+
+In any object's factory, anywhere: Chord follows each source with watches owned by the object (under its context,
+replaced by each attempt's declaration, stopped at the object's end; GC-tested), installed right after the factory
+returns, before natives open, so a failed open still has them; a `value` call of a source while the object is failed
+(`transient` or `broken`) retries it as `ref.retry()` does (backoff skipped, an attempt now, holders told `loading`);
+a call while it activates is remembered and retries it at once if that attempt fails (decision S1); ignored while live. Sources
+are those that live independently of the attempt: a `RegistryValue`, `constant`; anything else (a reference's member,
+a `writable` of the same attempt) is refused at runtime (declaration policy; TypeScript cannot tell them apart).
+
+**Which calls retry (D2, owner, 2026-10-27):** only `value` calls: a new value of a source wakes a failed object; a
+`failed` call (a throwing `compose`) does nothing, its next good composition retries.
+
+## 4. `host.root(fn, context, options?)`
+
+**Signature and guarantees (D3, owner, 2026-10-27; design §26 #25):** `host.root<T>(fn: (ctx: Ctx) => Promise<T>,
+context: Context, options?: { principal?: P }): Promise<T>`. `fn` gets a call context like a handler's: the host's
+principal (or `options.principal`, a trusted same-host caller's choice, as base code acting for an authenticated
+user), this host's incarnation, `context`'s telemetry and abort signal linked until `fn` settles
+(`withLinkedAbortSignal`), and `ctx.get`. When `fn` settles or `context` aborts, the call context is sealed:
+`ctx.abortSignal` aborted, `ctx.get` rejects `released`, every reference it took released (their calls reject
+`released`, their watches end), so an uncooperative `fn` fails at its next use of Chord, as a handler after its caller
+cancelled; work outside Chord runs on until then. `ctx.get` before `load` resolved parks like any reference;
+`host.close` seals every open root scope (the host keeps them), so an `fn` waiting in `sleep(ms, ctx)` ends; `host.root`
+after `host.close` rejects `released`. No span of its own until slice 9.
+
+- `chord(fn, context)` is p3's helper over `host.root` (design §24); Chord ships none.
+
+## 5. Durable on registries (examples, p3's pattern)
+
+- Durable's `HarnessOptions.registry` takes a `RegistryReader` (`snapshot()`, `subscribe(listener)`, the listener
+  called synchronously after every publication). A `RegistryValue` offers a synchronous observer of its compositions
+  (`observe(observer, ctx)`, as Durable's `observeXXX`: `advance` inside the flush that composed, record only; an
+  attached observer counts as watching, so the lazy compose runs for it); Durable's
+  `registryReader(value)` (in its `src`) reads `.value` in `snapshot()` and forwards `observe` to `subscribe`. The
+  harness object declares the extensions registry with `self.registry(...)`, so it activates (and opens Durable) only
+  once the registry has a value. p3's `compose` builds Durable's snapshot without throwing (a duplicate task name is
+  reported and the later extension left out).
+- **Durable's views from other objects** (carry-over from 6b): the object that opens Durable contributes its harness to
+  a registry (`HarnessRegistry`, p3's); another object declares it in its factory and follows a view through its value:
+
+  ```ts
+  const harness = self.registry(HarnessRegistry);          // a dependency: activation waits for it
+  self.retryOn(harness);                                   // the new harness's contribution wakes the failed follower
+  const view = self.follow((observer, ctx) => harness.value.observeConversation(id, observer, ctx));
+  ```
+
+  When that harness closes, Durable ends the observer `failed` (S1, a Durable change in this slice: a Session close
+  ends observers `failed`, `ended` only when the observed owner ended), so the follower fails `transient` and its retry
+  follows the new harness.
+- Examples: Chord's `29-registries.ts` (a router registry with two contributing plugins, a conflict reported, a
+  `writable` contribution, a missing provider healing) and `30-host-root.ts`; Durable's `test/examples/37-harness-
+  registry.ts` (a Durable harness on the store, its extensions from a registry, its views followed by a second object)
+  and the `registryReader` tests in Durable's tree. Durable's `subscribe` listeners then run inside Chord's flush:
+  they only wake Durable's scheduler (no Chord call; a reentrant one would throw `invalid/reentrant`), which the
+  `registryReader` test pins.
+
+## 6. Carry-over
+
+From `slices.md` "Slice 8": `host.root` (D3); `retryOn` (section 3); registries recomposing in the owner's flush (W4);
+`host.activity` on the facet's host: not built (nothing needs it; dropped from the carry-over); Durable's views from
+other objects (section 5). Left to slice 7: registries on reload (a reload replaces a contribution and a provider
+atomically; staging composes nothing, decision D1 of "Review round 1"); `accepts` of contracts and jobs; a `writable`
+across a pure swap; older registry readers across a reload of the provider.
+
+**New names** (design §3, §5, the pinned reason list): the reason `unavailable/undeclared`; `HostError` kinds
+`registry_conflict`, `registry_failed`, `contribution_failed`, `contribution_refused`, each reported once per episode.
+
+## 7. Tests and cost
+
+- One `describe` per mechanism: tokens and providers (two serves refused, a missing one healing), contributors
+  (R21's type and runtime refusals, facet and object lifetimes, one value each), the table (order by plugin, versions
+  adapted, refused versions reported), `compose` (in the flush, after a commit that changed a watchable contribution,
+  conflicts reported, a throw as a failure call and its heal), reading (`self.registry` in derives and `on`, `.value` at
+  use), `writable` (identity, batching, as a contribution), `retryOn` (a failed object retried by a contribution, value
+  calls only, sources installed before natives), `host.root` (principal, release at settle, abort, before load, after
+  close), `registryReader` with a Durable harness; GC for every table, writable and root scope.
+- Cost guards: one compose per flush per changed table; no compose for an unchanged table; a `writable.set` of the same
+  value costs one comparison.