@earendil-works/chord 1.5.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-9.md

@@ -0,0 +1,110 @@
+# Slice 9: telemetry (spec)
+
+Status: **draft for the build** (owner, 2026-11-03: "build i18n, then slice 9 (we said we want cross host spans)";
+2026-11-04: "go ahead"). Telemetry was decided on 2026-10-18 (decisions under "## Telemetry" in `decisions.md`, from
+"Context" to "Telemetry store") and is stated in design.md §29 and §30 (cost guards). Chord v2 so far records only
+metrics (cost counters such as `chord.data.validations`, `chord.link.encodes`) and stores a persisted job run's start
+carrier (slice 6b). This slice adds the spans, events and metrics of §29, carriers across links, and Chord's telemetry
+schema, so one trace follows a call from a page through the server's relay into a worker's method, Durable's phases
+and pi-ai's model request.
+
+Read in full before writing code: this spec; `decisions.md` (the telemetry decisions of 2026-10-18, R5 in "R4 and R5,
+protocol header schema", and every later entry that touches telemetry, links, relays, workers or jobs); `design.md`
+(all of it; §22 wire, §29 telemetry and §30 cost model in particular); `slices.md` (the feature map rows for §8
+`ctx.trace`, §12 the container-width benchmark, §22 trace carriers, §29; the carry-over "Slice 9"); pi-telemetry
+(`packages/telemetry/src`: `TelemetrySpan`, `TelemetryContext`, propagation, links, metrics, typed schemas, the in-memory
+adapter, `render.ts`, the conformance tests); Chord's `src/telemetry-sqlite/`; Durable's `harness/telemetry.ts` and how
+Durable starts its spans (the model for a typed schema); pi-ai's `pi.ai.request` wrapper; Chord's `src/context`,
+`src/host` (ctx, object, attempt, root, host, routines, jobs), `src/link`, `src/remote`, `src/node/http`,
+`src/node/workers`. Root `AGENTS.md` "Chord v2 Code Style" (binding).
+
+## 1. Chord's telemetry schema
+
+`CHORD_TELEMETRY_SCHEMA` (`src/telemetry.ts`, exported from the root), typed with pi-telemetry's
+`defineTelemetrySchema` like `DURABLE_TELEMETRY_SCHEMA`: every span, event and metric name Chord emits with its
+attributes. The existing cost counters (`chord.data.*`, `chord.link.*`, `chord.store.*`, `chord.query.runs`,
+`chord.cycle.visits`) are declared in it and recorded through it. Ids (object identity, hold, call, address key) are
+span attributes only, never metric attributes.
+
+## 2. Spans
+
+All spans are short and in one process (decision "Durable and AI spans"). Names and their parent:
+
+| Span | Where | Parent | Attributes (besides ids) |
+| --- | --- | --- | --- |
+| `chord.call` | a consumer's call of a remote member (`ref.method(args, ctx)`) | the caller's `ctx.telemetry` | type, member, address kind |
+| `chord.method` | a provider running a method | the call's carrier (remote) or the caller's span (local) | type, member, principal kind, outcome |
+| `chord.relay` | a relay forwarding a hold or a call | the arriving carrier | type, member or `hold`, upstream address kind |
+| `chord.hold` | a consumer's hold until bound (the first `bound` or failure) | the holder's span | type, outcome |
+| `chord.activate` | one activation attempt of an object (factory, natives opened, live or failed) | root, linked to its first trigger | type, attempt, outcome (live, failed, parked) |
+| `chord.open` / `chord.close` | one native's open / close | the attempt's span / root | type, native index |
+| `chord.load`, `chord.reload` | a host's load / reload | the caller's span | plugins, fates counts |
+| `chord.resolve` | a route resolving an address (a worker start included) | root, linked to its first trigger | kind, outcome |
+| `chord.revoke` | a revocation | the caller's span | count |
+| `chord.routine` | one routine run (`self.on`, `onLive` handler) | root, linked to the commit that triggered it when known | type, routine |
+| `chord.job` | one job run phase (intent, run, finish) | the stored carrier (persisted) or the starter's span | job, phase, outcome |
+
+- **Shared work** (one activation for several getters, a worker start for several holds) is its own root span linked
+  to its first trigger; each waiting span links to it (decision "Across links" / "Shared work").
+- **Failed spans** carry `status: "error"` with a fixed category (`activation_failed`, `call_failed`, ...) and the
+  error message truncated to 500 characters; cancelling is not an error (decision "Errors in telemetry").
+- **`ctx.trace(name, attributes, fn)`** (round-3 cut C11, decided here as kept: design §29 already states it): a child
+  span of the handler's `ctx.telemetry`, `fn` gets a child `ctx` (principal and `get` kept), so calls inside are parented.
+
+## 3. Across hosts
+
+- **Carriers on the wire:** `call` and `hold` get an optional `trace` field (R5: a `TelemetryCarrier`, bounded: at most
+  8 keys, keys and values at most 256 characters; over the bounds the message fails the `MESSAGE` schema as any malformed
+  header). The consumer injects `ctx.telemetry`'s carrier when its adapter has propagation; the provider extracts it
+  (malformed or absent: the adapter's root, never a throw) and starts `chord.method` under it. The binary codec gets a
+  flag bit for the field; the text codec an optional element. `PROTOCOL_VERSION` stays 1 (nothing is deployed outside
+  our own apps; the carry-over rule for bumps applies once p3 ships).
+- **Relays** read the carrier from the envelope, start `chord.relay` under it, and forward the relay span's carrier
+  upstream (the envelope rewrite already copies the header once).
+- **Workers** (`chord/workers`): a worker start is a `chord.resolve` root span; a held worker's methods are
+  `chord.method` under the forwarded carrier, so a trace reads tab → server relay → worker method.
+- **HTTP** (`chord/http`): a request is a `chord.http` span (method, route pattern, status; the path never, it may
+  carry ids or secrets), its handler's `ctx` under it; an incoming W3C `traceparent` header is extracted only from a
+  contributed relay that `verify`s (never from browsers).
+- **Durable and pi-ai** already accept a span (`HarnessOptions.telemetry`, pi-ai's `telemetry` option): a worker's
+  Harness gets its host's adapter, and a method that submits input passes its `ctx.telemetry`, so `pi.durable.submit`
+  is a child of `chord.method` (Durable starts its own trace per input submission and links to the trigger, as decided).
+
+## 4. Events and metrics
+
+- **Events** on the enclosing span: `chord.commit` (documents, ops, duration) for commits inside a method or routine,
+  `chord.retry` (backoff), `chord.park` (cause), `chord.reload.fate` (one per object fate: swapped, restarted, parked).
+- **Metrics** (low cardinality, never ids): `chord.link.state_messages`, `chord.link.bytes` (encoded WebSocket frames,
+  sizes the code already has), `chord.commit.duration`, `chord.calls.in_flight` (up/down), `chord.holds.active`,
+  `chord.links.open`, `chord.park.duration`, `chord.backpressure.wait`. Nothing is serialized or walked to measure.
+
+## 5. Storage and reading
+
+`chord/telemetry-sqlite` exists (decision "Telemetry store"); check it against §29 and fix gaps (links inline, metrics
+per 10 s series, retention, bounded queue). The app kit: `startServer` and `startWorker` take an optional `telemetry`
+adapter (default NOOP) and pass it to their hosts, HTTP and workers; a worker's adapter comes from its `startWorker`
+options (the kit does not ship spans across processes itself: each process exports to the store it is given; a shared
+SQLite file per data directory is the app's choice, documented with a short example).
+
+## 6. Cost
+
+With the NOOP adapter every span site costs one call and an empty object; no carrier is injected (no propagation),
+no attribute objects are built when the adapter cannot record (check pi-telemetry's API for the cheapest form; no
+`isRecording` exists: decided). Cost guards: the slice's tests assert through the in-memory adapter that a call over a
+relay produces exactly the spans of §2 and no extra encodes; a benchmark (`test/bench/telemetry.ts`, by hand) measures
+a call over a link with the NOOP adapter versus without the span code (target: within noise) and with the in-memory
+adapter; results in `docs/benchmarks.md`. The §12 container-width benchmark (R24) is carried over into this slice's
+benchmark file if not done yet (check `benchmarks.md`).
+
+## 7. Tests and examples
+
+- One test file per source file, one `describe` per mechanism; the in-memory adapter and `renderTrace` for assertions.
+- A cross-host test: a client calls a method over a relay into a worker (memory links or the workers component), the
+  method commits and calls a local object; the store-rendered trace shows client `chord.call` → server `chord.relay` →
+  worker `chord.method` → `chord.commit` event, one trace id; a malformed carrier from a client gives a new root.
+- Jobs: a persisted run resumed in a new attempt stays under its stored carrier (slice 6b's field, now used).
+- Example `62-telemetry`: a kit app (server and a worker kind) with the SQLite telemetry store, a page or a client
+  calling a worker method that submits to a fake Durable harness or does a model-free piece of work; it prints the
+  rendered trace across the three hosts and a metric query.
+- Docs: design.md §29 marked built with anything refined; the guide gets a short chapter "Seeing a request across
+  hosts"; CHANGELOG under Unreleased; delete the carry-over section "Slice 9".