@earendil-works/chord 1.4.0 → 1.5.0

package/docs/next/slice-1.md

@@ -0,0 +1,236 @@
+# Slice 1: one host, local objects (spec, for the owner's approval)
+
+Status: **approved (owner, 2026-10-22)**, after Astra's and Fable's spec reviews. The single source for building slice 1,
+together with the feature map in `slices.md` (entries assigned to slice 1) and `design.md`, read in full (the most
+relevant sections: §3 host, §5-§7, §8, §9, §11, §12, §16, §18); rules come from the decision log
+(`packages/chord/docs/next/decisions.md`); code style: the section "Chord v2 Code Style" of the root `AGENTS.md`. Builds on
+L1 (`src/next/contracts`, `src/next/data`) and Chord's shared watch handle (`src/watch.ts`).
+
+## What an app can do after this slice
+
+```ts
+const Notes = local("notes.store", {
+  version: 1,
+  params: {},
+  members: {
+    notes: obj({ list: arr(Note) }),
+    titles: arr(str()),
+    count: int(),
+    add: method(obj({ text: str() })),
+    saveDraft: method(obj({ conversation: int(), body: str() })),
+  },
+});
+const Draft = local("notes.draft", {
+  version: 1,
+  params: { conversation: int() },
+  members: { summary: str() },
+});
+
+const NotesDoc = defineState("notes", { schema: obj({ list: arr(Note) }), version: 1, initial: () => ({ list: [] }) });
+const Drafts = defineState("drafts", { schema: obj({ body: str() }), version: 1, initial: () => ({ body: "" }), keyed: true });
+
+const facet = defineFacet<AppPrincipal>((host) => {
+  host.serve(Notes, (_, self) => {                                // empty params: lives as long as the host
+    const notes = self.state(NotesDoc);
+    const drafts = self.state(Drafts);                             // keyed: one document per conversation (P3 pattern)
+    const title = mapShared((note: Note) => note.text.slice(0, 20));
+    return {
+      notes,
+      titles: self.derive([notes], ([n]) => title(n.list)),
+      count: self.derive([notes], ([n]) => n.list.length),
+      add: async ({ text }, ctx) => {
+        await self.tx(async (tx) => { (await tx.draft(notes)).list.push({ text }); }, ctx);
+        return null;
+      },
+      saveDraft: async ({ conversation, body }, ctx) => {
+        await self.tx(async (tx) => { (await tx.draft(drafts, String(conversation))).body = body; }, ctx);
+        return null;
+      },
+    };
+  });
+  host.serve(Draft, ({ conversation }, self) => {                  // params: lives while referenced
+    const store = self.get(Notes, {});                              // declared here, live before this object is
+    return { summary: self.derive([store.count], ([c]) => `conversation ${conversation}, ${c} notes`) };
+  });
+});
+
+const host = createHost({ onError: (error) => log(error) });       // no address: local types only
+await host.load([{ name: "@app/notes", facet }], ctx);
+const notes = await host.get(Notes, {}, ctx);                      // live and hydrated
+await notes.add({ text: "milk" }, ctx);
+notes.count.value;                                                 // 1
+const w = await notes.count.watch(ctx);
+w.start(async (value) => console.log(value));
+notes.release();                                                   // ends w; the object lives on (empty params)
+await host.close(ctx);
+```
+
+## 1. Host and facets
+
+- `createHost({ telemetry?, onError? })`: a host without an address; it serves only `local` types in this slice.
+  `telemetry` is the adapter (NOOP by default); `onError` receives background errors (a throwing watch listener).
+- `defineFacet<P>(setup)` returns a facet typed for the app's principal type `P` (base code binds it once; nothing is
+  checked at runtime). `setup(host, self)` runs synchronously inside `host.load` and only declares: `host.serve(Type,
+  factory)` and facet documents through `self.state(Def)` (C16, owner: built now). `host.serve` outside a setup
+  throws.
+- **Facet documents (design §9, §16):** the facet is a pure object with the host's lifetime; its documents live as long
+  as the host. Objects the facet serves may read the facet's handles and draft them in their own `self.tx`, together
+  with their own documents, atomically (lock order: the object's own line, then the facet's line). The facet never
+  drafts a served object's documents; objects of other facets cannot use them.
+- `host.load(facets, context)`: `facets` is `[{ name, facet }]` with npm-style plugin names; duplicate names or a type
+  served twice are refused. After every setup ran, every served `local` type with empty params is activated (Q-A, the
+  start barrier); `load` resolves when all are live. If one fails, `load` ends everything it activated and rejects;
+  the host is then empty. A `host.get` made before `load` resolves waits for it.
+- `host.close(context)`: rejects new calls, ends every object (in reverse activation order) and resolves when all have
+  ended.
+
+## 2. Objects
+
+- **Identity:** one object per `(type, params key)` (L1's `checkParams` and `identityKey`; local has no principal).
+- **Lifetime (Q-A):** a local type with empty params is created at `load` and lives until `close`; a type with params
+  is created by the first `get` and ends when its last reference is released.
+- **Factory:** `(params, self) => implementation`, synchronous and declarative, run once per object. The
+  implementation has exactly the contract's members: a state member is a JSON `Watchable` of its value (a document
+  handle, a derive, a member of a reference), a method is `(args, ctx) => Promise<result>`. L1's `Implementation<C>`
+  types state members as `Watchable<Static<schema>>` (owner, 2026-10-22).
+- **Activation (design §6):** run the factory; acquire the references it declared with `self.get` (activating their
+  objects if needed) and wait until they are live; check the members (exactly the contract's, state members JSON
+  watchables, Q14); compute every derive's first value; then the object is live and calls proceed. A throw anywhere
+  in activation (factory, a dependency's activation, a member check, a first derive compute, `initial()` failing its
+  schema) rejects the `get` (or `load`) with that error, releases everything acquired and leaves no object. Failure
+  states, backoff and retries are slice 2.
+- **Ending:** new calls on the object fail `released`; the context of each of its running calls is aborted; from then
+  on its `self.tx` throws `released` (a still-running method can no longer change anything); its derives are detached
+  from their sources (no source keeps a reference to an ended object's derive); its references are released; its
+  documents are dropped; every watch on its members ends `ended`. Ending does not wait for running calls (the drain
+  arrives with natives in slice 2, design §3).
+
+## 3. References
+
+- `host.get(Type, params, context)` returns a reference once its object is live; `self.get(Type, params)` declares one
+  in a factory: it is live by the time the object goes live, and released when the object ends.
+- A reference is a plain object built from the contract's member list (no proxy): `ref.<state>` is a `Watchable`
+  (`value`, `watch(ctx)`), `ref.<method>(args, ctx)` calls the method, `ref.release()` releases it (idempotent). After
+  release, every use throws `released`.
+- **Calls:** arguments and results pass by reference; arguments are checked at the provider with L1's `checkArgs`
+  against the current version (`bindProvider(contract, {})` at serve): unknown method `invalid/member`, bad arguments
+  `invalid/args`; results are not checked; no-argument methods take `null`.
+- **Per-reference watches** (owner): watches obtained through a reference end (`ended`) when it is released, even
+  while other references keep the object alive.
+- **Contract match** (owner): at `get`, the caller's contract must have the provider's version and fingerprint (the
+  same declaration, or an identical one), otherwise `contract_mismatch`. Older versions through `accepts` come with
+  slice 7.
+- **Reserved member names** (owner): `then`, `release`, `state` and `retry` are refused as member names at
+  declaration (an L1 check in `remote`, `local` and `evolve`), because a reference has them (`release` now, `state` and
+  `retry` in slice 2) and `then` would make an awaited reference thenable.
+- **Cycles (Q5, one host; owner):** at `self.get` during an activation, Chord follows the chain of objects waiting for
+  activation; reaching the object being activated fails that activation with `invalid/cycle`, naming the cycle
+  (`a → b → a`); nothing is kept.
+- `ctx` in this slice is a plain `Context` (cancellation and telemetry); `ctx.get` and `ctx.principal` come with
+  slice 3.
+
+## 4. Documents in memory (§9, P2)
+
+- `defineState(name, { schema, version, initial, keyed? })`: the root is a JSON object. `checkpointWhen` is required
+  only for persisted documents (slice 6; owner, 2026-10-22). `migrate` comes with slices 6 and 7.
+- `self.state(Def)` returns a handle bound to this object; every document is in memory, instance state of the object
+  (P2), gone when it ends.
+- **Singleton handle:** `handle.value` is the current value, `initial()` until written or after a retire (Q11); the
+  handle is a `Watchable`.
+- **Keyed handle:** `await handle.get(key)` gives the value or `undefined`; `handle.keys()` is an `AsyncIterable` of
+  the present keys (the shape persistence keeps); keys are strings. A keyed handle is not a `Watchable` (a live
+  collection is a singleton holding a list or map).
+- `initial()` is checked against the schema once, the first time a definition's `initial()` is used (R8).
+
+## 5. Transactions (§9, R12, R13)
+
+- `self.tx(fn, ctx)`: an object's transactions run one at a time (its line). `fn` gets `tx`: `await tx.draft(handle,
+  key?)` returns the document's draft (Delta's `track`, `beginChange`; the same document gives the same draft within
+  one transaction); `tx.retire(handle, key?)` removes a document (a no-op when absent). `self.tx` returns what `fn`
+  returns.
+- **Commit:** when `fn` resolves, if `ctx` is aborted the transaction is discarded; otherwise every draft is prepared
+  (Delta's `prepare`: ops recorded, only placed values checked), unchanged drafts commit nothing, and all changed
+  documents are adopted (pointer swap) in **one batch** (section 6). A throw discards everything.
+- Drafts are revoked when the transaction settles (touching one throws, R12); a transaction returns plain values and
+  data is read from the handle after the commit.
+- A transaction drafts only its own object's documents and its facet's (any other handle throws). Inside `fn`: no
+  second `self.tx`, no calls to other objects (Durable's rule; documented, not detected).
+- **Shorthands (C14, owner: built now):** `handle.change(fn, ctx)` (keyed: `handle.change(key, fn, ctx)`) runs one
+  transaction that loads the document and calls the synchronous `fn(draft)`; `handle.retire(ctx)` (keyed:
+  `handle.retire(key, ctx)`) retires it. Both are thin wrappers over `self.tx`.
+
+## 6. Derives and the batch (W1, §11, §12)
+
+- `self.derive(sources, compute)`: sources are JSON `Watchable`s (this object's handles and derives, members of
+  its `self.get` references); only the declared sources are tracked. `compute` is a synchronous pure function of their
+  values; its result is JSON.
+- **Pull model.** A commit only marks: every derive that depends on a changed document, directly or through other
+  derives, including derives of other objects on the host, is flagged dirty (O(dependents), flags only). A derive's
+  `value` recomputes when it is dirty, after reading its sources' values (which recompute first if they are dirty);
+  so each derive computes at most once per batch and always after its sources, diamonds included.
+- **The batch** (one per host): a commit's adoptions happen inside it; after the last adoption, still synchronously,
+  every watched value that changed is read (watched derives recompute through the pull), its ops computed
+  (`diffRevisions(old, new)` for a derive, the commit's ops for a document), and its watches get one frame each. A
+  derive is recomputed in the batch only if something watched depends on it; otherwise it stays dirty until read.
+  Reading `.value` once does not make it watched.
+- A derive that throws fails only itself: its `value` throws the error and its watches end `failed`; a derive over it
+  throws the same error when read. A derive that fails during activation fails the activation (section 2). A failed
+  derive stays failed until the object is rebuilt.
+- **Reentrancy:** inside the batch (adoptions, derive computes, including lazy computes outside a commit), `self.tx`,
+  `watch`, `release`, `get`, `load` and `close` throw `invalid/reentrant`. One flag per host, cleared in a `finally`.
+- `mapShared(f)`: maps an array calling `f` only for object elements not seen before (by identity), returning the
+  previous result for unchanged ones; primitive elements are mapped every time; the cache is a `WeakMap`.
+- `constant(value)`: a JSON `Watchable` that never changes (start data, §18); usable as a state member and a source.
+- State is JSON only (L2 decision): no bytes in documents or derives.
+
+## 7. Watching
+
+`watchable.watch(ctx)` returns Chord's shared `Watch` (`src/watch.ts`): the value at acquisition, then one frame per
+batch that changed it, `(value, ops, ctx)`, in order, asynchronously, with its overflow, `stop` and end semantics.
+Each frame is consistent with its commit; two different watches are not ordered relative to each other. A retired
+singleton gives the frame `[["r", initial]]` (it changes back to `initial()`; a singleton always has a value). `ctx`'s
+abort cancels the watch. A listener that throws ends its watch `listener_error` and is reported to `onError` (taken
+from the carry-over).
+
+## Cost per hop
+
+| Hop | Work |
+| --- | --- |
+| a call | L1's three lookups and one compiled check; arguments by reference |
+| a commit | Delta prepare per changed document, pointer swaps, dirty flags per dependent, then per watched changed value one read (derives recompute once) and one frame per watch, by reference |
+| an unwatched derive | nothing until read |
+
+Counters (telemetry, where the work happens): L1's, plus `chord.derive.computes` and `chord.derive.diffs`.
+
+## Carry-over taken by this slice
+
+From `carry-over.md` (L4 section): watch listener errors reported to `onError`; native watchables refused as state
+(by the member check: only JSON watchables exist in this slice); `defineFacet` typed by `P`. Left for
+later: plugin error shape, old-version calls (7), `broken()` (2), cuts C5, C6, C7, C13 (2).
+
+## Tests
+
+- Host: load runs setups, activates empty-params types, rejects duplicates and double serves; a failing activation
+  makes `load` end what it activated; `get` during load waits; `serve` outside setup throws; close ends everything.
+- Objects: one object per params key; params type created on first get and ended on last release (documents gone,
+  watches end `ended`, its derives detached from other objects' members); empty-params type lives across releases;
+  activation failures (factory, dependency, member check, first derive, `initial()`) reject the get and leave nothing;
+  a method running while its object ends cannot commit (`self.tx` throws `released`) and sees its `ctx` aborted.
+- References: hydrated on get; members watchable; calls checked; released reference throws; `self.get` dependency
+  kept alive and released on end; per-reference watches; contract mismatch; reserved member names refused at
+  declaration; a two-object and a three-object cycle fail with `invalid/cycle` and leave nothing.
+- Documents: singleton initial, retire back to initial; keyed get, keys, retire; `initial()` checked once.
+- Transactions: serialized per object; same draft twice; unchanged commits nothing; throw and abort discard; drafts
+  revoked after settle; another object's handle refused; a served object's transaction over its own and its facet's
+  documents commits both in one batch; shorthands.
+- Batch and derives: two documents in one transaction reach a derive over both in one compute and a watch in one
+  frame; a derive over another object's member updates in that object's commit's batch; diamond computes once;
+  unwatched derive stays lazy and a one-off read does not make it eager; a throwing derive fails only itself and its
+  dependents; reentrancy throws in commits and lazy computes and the flag clears after a throw; `mapShared` identity.
+- Watching: frames in order, retire frame, cancellation, listener error reported.
+- Cost guards per the table. GC: an ended object with its documents, derives and watches is collected; a released
+  reference and a stopped watch hold nothing; a detached derive is not held by its former sources.
+
+## Size
+
+About 1,100 source lines.

package/docs/next/slice-10.md

@@ -0,0 +1,285 @@
+# Slice 10: HTTP and workers (spec)
+
+Status: **built** (2026-10-31; build reviews by Fable, Opus, Astra and Sol, security audits by Fable, Opus and Astra, four fix rounds with rechecks; the shape after the fix rounds is in §2, §3 and design §23). Approved by the owner (2026-10-30: "just build it"; D1-D12, D10b, round 1's R1-R6 and round 2's Q1-Q6 in the
+decision "Slice 10's points"; spec reviews round 1 by Fable and Opus, `/tmp/s10-spec-review-{fable,opus}.md`, round 2
+by Fable, Opus, Astra and Sol, `/tmp/s10-spec-review2-*.md`, folded in).
+Slice 10 builds two Node components of the app kit (decision "Slice 7b's open points" (6)): `chord/next/http` (the
+server's HTTP and WebSocket entry, routes contributed by plugins through a registry, responses as descriptions) and
+`chord/next/workers` (a worker process per host address, started on demand, stopped when idle, its plugins shipped from
+the server). Both live in `packages/chord/src/next-node/` (Node-only); the kernel stays portable. The web page host and
+the TUI are slice 11, telemetry slice 9.
+
+Read in full before writing code: this spec; `decisions.md`; `design.md` (§3 hosts, routes, `host.activity`, §17,
+§18, §21 "Loading plugins and the reload loop", §23 in full); `slices.md`; `slice-7c.md` and
+`src/next-node/plugins/README.md`; the 7b brief `slice-7b/book.md` (chapters "Assets and Files", "HTTP", "A Mini p2
+from Chord"); p2's `src/hosts/server.ts`, `src/runtime/server.ts`, `src/hosts/worker.ts`, `src/hosts/socket-limits.ts`,
+`src/hosts/principals.ts`, `plugins/files/server.ts`, `plugins/terminals/server.ts`, `plugins/radius/server.ts`; Chord
+v1's `src/manager.ts` (`processLock`, `forkDriver`, `createHostManager`, `childControl`).
+
+## 1. What p2 has, and what moves into Chord
+
+p2's server host (`src/hosts/server.ts`, 742 lines; `src/runtime/server.ts`, 720) does, besides p2's own policy:
+
+| p2 today | Moves to |
+| --- | --- |
+| a Node `http` server on loopback, requests parked until `load` resolved, upgrades captured before listening | `http` |
+| `Routes` (`"METHOD /path"`, `/prefix/*`), handlers writing Node's `ServerResponse` themselves (ranges, download headers, `HEAD` by hand in `files`) | `http`: routes returning descriptions |
+| `Upgrades` (a WebSocket by path for terminals and voice), `/chord` (`acceptWebSockets` with per-socket limits) | `http` |
+| `Authenticators`, `RequestResolvers` (cookies, devices, the Radius relay), Fetch Metadata, CSP and the loopback cookie | the app (p3's base code), through `http`'s `authenticate` and `headers` (D3) |
+| loopback and allowed hosts, the `Origin` check on upgrades | `http` (R4), allowed hosts contributable by plugins |
+| `SessionHosts`: a worker per session, `createHostManager` + `forkDriver`, a kernel lock per session, idle stop from reported counts, crash notices, sticky failed starts, ready timeout | `workers` (failures stay until Retry or a rollout, R2) |
+| relocation and pause of a worker, the catalog, `WorkerInitValues` | the app (built on `workers`' `stop` and start data) |
+| `hosts/worker.ts`: the child's control channel, lock, start data, connect, load, report counts, shutdown | `workers`' child side |
+| the dev reload across server and workers, worker plugin lists | `plugins` (7c) plus `workers`' rollout step (§4) |
+
+Every option that is not bootstrap is changeable by plugins (decision "The app kit is malleable by plugins"): either a
+contribution to `Http` or a function the component calls per use, which the app backs with its own registries;
+nothing is copied out of a contribution or an option at startup. Bootstrap (changed by a restart): the listen address
+and port, the links path, the worker entry with its `execArgv` and `env`, the host kind workers serve.
+
+## 2. `chord/next/http`
+
+As built after the fix rounds (decisions "The HTTP core is a fetch handler", "The HTTP server is a native object",
+"Settings are arguments, extensions are registries", "The HTTP component's security baseline", "allowed hosts only
+through contributions", "A CSP nonce per response", "three small points", "a route's overhead accepted"); design §23
+states every rule, `src/next-node/http/README.md` the API.
+
+```ts
+const http = createHttp(server, {
+	listen: { host: "127.0.0.1", port: 8788 },                        // settings: arguments, a restart to change
+	links: { path: "/chord", options: (request, principal) => ({ limits: linkLimits(principal), maxPayload: 64 * MiB }) },
+	closeTimeout: 30_000,
+	onError: (error) => log(error),                                   // `HttpError`, below
+}, ctx);
+const app = defineFacet((_host, self) => {
+	self.contribute(Authenticators, (request, ctx) => principalFromCookie(readCookie(request, "session", secret)));
+	self.contribute(Http, { hosts: ["notes.example.com"], relays: [radiusRelay] });
+});
+await plugins.load(server, { kind: "server", core: [{ name: "chord.http", facet: http.facet }, { name: "@app/core", facet: app }], modules }, ctx);
+…
+await http.close(ctx);   // first: no new requests, sockets closed, running requests waited for up to `closeTimeout`
+await workers.close(ctx);
+await server.close(ctx);
+```
+
+- **The core** is `http.fetch(request, { localAddress?, localPort?, remoteAddress? })`, a Web `Request` to a Web
+  `Response`; `http.upgrade` is Node's upgrade adapter; `nodeRequest(message, res)` converts a Node request with the
+  listener's checks (`{ kind: "request", request, connection } | { kind: "refused", status }`, never a throw) for apps
+  mounting on their own Node server. Chord's own listener (with `listen`) is a host-lifetime object of `chord.http`
+  whose native is a Node server, on a fast path that skips the Web `Request` unless a route or authenticator reads
+  it.
+- **Registries:** `Http` (`"chord.http"`, version 1: `routes`, `wraps`, `sockets`, `maxPayload`, `hosts`, `framers`,
+  `relays`, `csp`; a value or a writable) and `Authenticators` (in contributor order, the first principal wins).
+  Requests before the publication wait for it (503 past `readyTimeout`).
+- **Admission, foreign requests, origins, default headers, cookies, downloads:** the security baseline (design §23).
+  Refusals before any plugin code: a non-loopback socket without an allowed host, forwarded headers without a
+  verified relay, duplicate or missing `Host`, userinfo in `Host`, absolute-form targets (403), unparsable targets
+  (400), `TRACE`/`TRACK`/`CONNECT` (501; a route for them refused at compose).
+- **A request's scope, `HttpRequest`, patterns, wraps, responses, `fileResponse`, sockets, links, revocation,
+  `close`:** design §23. The spec's earlier text (an `httpServer` that listens first, `allowedHosts`, one
+  `authenticate` and a `headers` option, 64 KiB reads) is superseded by those decisions.
+- **Errors** (`onError`, `HttpError`): `route_failed { pattern, plugin, error }`, `wrap_failed { name, plugin, error }`,
+  `socket_failed { pattern, plugin, error }`, `response_failed { pattern, error }`, `hook_failed { hook, plugin?,
+  error }` (`authenticate`, `relay`, `links.options`).
+- `ws` is an optional peer dependency (D7), imported only here.
+
+## 3. `chord/next/workers`
+
+```ts
+// server.ts
+const workers = createWorkers(server, Session, {
+	kind: "worker",                                                                   // the facet kind it ships
+	entry: "./worker.ts", execArgv: ["--import", resolver], env: { … },              // bootstrap
+	authorize: (principal, address) => app.mayReach(principal, address),              // the route's `authorize` (synchronous)
+	principal: (address) => ({ kind: "worker", session: address.params.id }),
+	start: (address, ctx) => app.startData(address, ctx),                             // JSON, before each start
+	lock: (address) => `app:${realpath(dataDir)}:worker:${address.key}`,              // one live worker per address
+	idleMs: () => app.idleMs(),
+	plugins,                                                                          // the plugins component
+	onOutput: (address, stream, chunk) => logs.append(address.key, stream, chunk),
+	onError: (error) => log(error),                                                   // `WorkersError`, below
+}, ctx);
+workers.state                              // JSON watchable (R5)
+await workers.stop(Session({ id }), ctx);  // archive: suspended while held (Q3), then stopped
+await workers.retry(Session({ id }), ctx); // the Retry button: a failed or suspended address resolves again
+await workers.close(ctx);                  // no new starts, every child stopped
+```
+
+```ts
+// worker.ts
+await workerMain(async ({ address, start, parent, plugins, onClose }, ctx) => {
+	const store = await openStore(sqliteBackend(await openNodeSqliteDatabase(join(start.dir, "session.sqlite"))), ctx);
+	onClose((ctx) => store.close(ctx));                                               // closers run in reverse order
+	const worker = createHost<P>({ address, principal: { kind: "worker", session: start.id }, store, onError });
+	onClose((ctx) => worker.close(ctx));
+	worker.connect(parent, { principal: { kind: "server" }, trusted: true }, ctx);   // `started` goes out now: connect
+	                                                                                  // before anything slow (a store opens in ms)
+	await plugins.load(worker, { kind: "worker", core: [{ name: "@app/core", facet: coreWorker(start) }] }, ctx);
+	return { busy: harness.activeTasks };                                             // extra keep-alive counts
+}, {
+	hostPackages: { "@earendil-works/chord/next": chordNext, "@app/core": appCore },  // the child's own instances
+	redact: (error) => ({ message: redactSecrets(String(error)), ...codeOf(error) }), // what crosses as `fatal`
+	onError: (error) => log(error),
+});
+```
+
+- **The route:** `createWorkers` calls `host.route(Kind, { authorize, resolve }, ctx)` itself and keeps the
+  `RouteHandle` (`retry`, `suspend`: D10b, R1). `authorize` is synchronous (the kernel's): a plugin backing it keeps an
+  index.
+- **Per address, events and operations:** a child's events (its exit, its link's close, `started`, `ready`, `fatal`)
+  are observed as they happen and recorded at once on that child (a late event of an old child never changes a new
+  one); the operations (start, stop) run in one queue per address: a start waits for the previous child's exit, a
+  stop during a start waits for it then stops, and a start queued behind an exit checks the address's state after it
+  (a crash recorded meanwhile makes it reject with that failure). Stops record their intent before `shutdown`, so the
+  exit they cause is no crash.
+- **A start** (`resolve(address)`): calls `start(address, ctx)` (abortable; a throw rejects the start), checks that the
+  component is not closing, forks `entry` (`serialization: "advanced"`, a detached process group, stdout and stderr
+  piped: the stderr tail kept, mirrored to the server's when there is no `onOutput`), makes `ipcLink(child)` at once
+  (so the child's `hello` and early holds are queued, never lost), and sends the start message `{ address, start,
+  scripts, lock }` (`scripts`: the worker kind's complete current set, read when the message is sent). The child takes
+  the lock (when an old worker still holds it, it waits by connecting to the lock's socket and trying again when that
+  connection closes: no polling), and sends `started` when the app's host sets its listener on `parent` (`parent` is
+  a thin wrapper of the IPC link, so `connect` is the signal: the app connects before anything slow). `resolve` then
+  returns `{ link, principal: principal(address), trusted: true }`, and the handshake and the worker's server traffic
+  run during its `load`. The start timer (60 s from the fork) covers fork, lock and connect only (Q4): past it the tree is
+  killed and the start fails. `ready` (after the app's function returned, carrying the idle state and its load report) sets `state` to
+  `running` and lets idle stops begin; a `load` that never ends shows `starting` until `stop`.
+- **Workers never restart by themselves** (R2): a crash (an exit nobody asked for), a `fatal`, a link lost while its
+  child lives, or a failed start (`start` threw, the start timer, a lock not taken in time) leaves the address `failed`
+  with its error (`worker_failed` reported once). A link lost while its child lives (the heartbeat after a blocked
+  event loop, a protocol error) starts the stop: the grace (5 s), then the tree is killed; its exit is the crash ("link
+  lost"). `resolve` of a failed address rejects at once with that error; its holders and new holds see `failed {
+  waiting }` with it as cause (Q1) and stay on the address's path, nothing forks. `workers.retry(address)`
+  (`RouteHandle.retry`) or a rollout reaching workers clears it (Q2, §4). An idle stop is no failure: the next hold
+  starts the worker on demand.
+- **Keep-alive** (D9, R3, Q5): the child's idle state is all of `host.activity`'s `references`, `jobs` and `lingering`
+  and the app's `busy` (a JSON watchable of numbers) at zero, not `calls` (a remote call runs on a hold; local calls
+  come from routines, jobs and tasks counted elsewhere). `ready { idle }` carries the first state, then `{ idle }` on
+  each flip; a rollout applying in the child counts as busy. The server stops a worker idle since `idleMs()` (5 min by
+  default; checked every second), never before `ready`. A stop (idle, `stop`, `close`): `shutdown`; the child aborts its
+  `ctx`, runs the closers registered with `onClose` in reverse order and exits, forcing its own exit after 3 s; the
+  server kills the tree after 5 s.
+- **`state`** (R5, decision "worker errors in public"): per address key `{ status: "starting" | "running" |
+  "stopping", pid, startedAt }` or `{ status: "failed", error: { message, code?, reason? }, at }` with a public error
+  (a fixed message, or the child's redacted `fatal`); no entry when stopped or never started. The full error and the
+  stderr tail go only to `onError` (`worker_failed`); every app hook of a start (`start`, `principal`, `lock`, the
+  fork) is inside that boundary.
+- **`stop(address, ctx)`** (R1, Q3): `RouteHandle.suspend(address)`, then the stop. The suspension lasts while the
+  address has holders (they see `failed { waiting }`, "suspended"); with the last holder it goes, and a later hold
+  starts the worker on demand; `retry(address)` lifts it at once. Whether an archived session may be opened is the
+  app's (`authorize`, its views).
+- **`close(ctx)`:** cancels active and queued starts first (a `start(address)` waiting on the app's barrier is
+  aborted; nothing forks after it), then stops every child (grace, then kill), clears the timers; new starts reject
+  `released/closed`; the caller's cancellation ends only its own wait. `createWorkers`'s `ctx` aborting (the host
+  closing aborts the route's context) closes it too, and from then on every exit is a stop, never a crash (no
+  `worker_failed` at shutdown).
+- **The child** (`workerMain(fn, { hostPackages, redact, onError })`): reads the start message, takes the lock, makes
+  `ipcLink(process)` and its wrapper `parent`, creates its plugin runtime with `hostPackages` (the child's own module
+  instances; functions cannot cross IPC), calls `fn({ address, start, parent, plugins, onClose }, ctx)`. `shutdown`,
+  the parent's disconnect, `SIGTERM` and `SIGINT` alike abort `ctx` and run the closers registered so far, also while
+  `fn` still runs (its startup is cancelled through `ctx`). An uncaught error, or `fn` throwing, sends `fatal` with
+  `redact(error)` (never the original message) and exits; after `started` that is a crash like any other.
+- **Control messages** (JSON beside the link's `Uint8Array` frames; the IPC link skips them): parent to child `start`,
+  `shutdown`, `reload { scripts }`; child to parent `started`, `ready { idle }`, `idle { idle }`, `fatal { error }`,
+  `reloaded { report } | { error }`. One `reload` is outstanding per child at a time: a reload whose caller aborted
+  keeps the child's slot until its `reloaded` or the child's exit, and the next waits for it. Errors cross as `{
+  message, code?, reason? }`.
+- **Errors** (`onError`, `WorkersError`, which includes `BatchError` for a `state` watch listener that throws): `worker_failed { address, error, stderrTail? }` (private),
+  `authorize_failed { address, error }` (a throwing `authorize`: the hold is refused `forbidden`), `worker_exited {
+  address, code, signal }` (only for an exit nobody asked for: not after a stop or a start the component failed).
+
+### Plugins in workers (D11)
+
+Workers never build. The plugins component (7c) gets `scripts(kind, ctx)`: the complete current set of one kind (every
+discovered plugin's facet of it, built on first use, then updated by every rollout that ships that kind), each with its
+plugin record (`name`, `dir`, `chord.external`). The component's per-host loading (its loaded map, `#prepare`, `adopt`,
+the queue per host) moves into a file without esbuild or the watcher, `createPluginRuntime()`
+with `load(host, { kind, core, scripts, modules }, ctx)` (`modules`: the host packages' module objects of this process) and `reload(host, scripts, ctx)` (a complete set: removed = loaded −
+shipped; same digests unchanged); `createPlugins` uses it, and the child's `plugins` is a `WorkerPlugins` over one
+(`load(host, { kind, core })` loads the start message's scripts; `reload` messages wait until `fn` returned); `import`
+of `chord/next/plugins/runtime` loads no esbuild. Each kind is defined once in `createPlugins({ kinds: { <kind>: {
+platform, hostPackages } } })` (decision "Slice 11's points", Kinds).
+
+## 4. The rollout across server and workers
+
+```ts
+const built = await plugins.build(plugins.state.value.dirty, ctx);
+const result = await plugins.rollout([plugins.step("server", server), workers.step("workers")], built, ctx);
+// result.steps: [{ name: "server", hosts: [{ host: "server", report }] },
+//                { name: "workers", hosts: [{ host: "session|S1", report }, { host: "session|S2", stopped: true },
+//                                           { host: "session|S3", error }] }]
+```
+
+`RolloutStep.reload(built, ctx)` returns `{ hosts: readonly ({ host; report } | { host; stopped: true } | { host; error
+})[] }` (D12; 7c's in-process step returns a list of one, its `host` the name given to `step`). `workers.step(name)`:
+
+1. replaces the workers' current set (`plugins.scripts(kind)` updated from `built`);
+2. clears the failures recorded before this rollout and calls `RouteHandle.retry` for those addresses that have holders
+   (Q2): they start with the new set and are listed; an unheld one starts at its next hold;
+3. ships the complete set to every running or starting worker whose start message or last reload carried an older one
+   (a child queues a reload that arrives before its `ready` until its load is done); workers reload in parallel.
+
+A worker's entry settles on its `reloaded` or on its exit or link loss, whichever comes first. A worker stopped cleanly
+during the step (idle, `stop`) is listed `stopped` and dirties nothing (its next start gets the current set); one that
+crashed or failed to apply is listed with its error and does not stop the rollout, and every plugin of its kind in the
+build counts as failed there (stays dirty); a worker failing during this rollout stays failed. A plugin's dirty mark
+clears only when it applied on every host of every step, and a kind built in the rollout that no step shipped keeps its
+plugins dirty.
+
+## 5. Not in slice 10
+
+The web page host, the browser's evaluation of scripts and serving them (slice 11); the TUI (slice 11); relocation and
+pause of workers (the app's: `start(address)` is where the app awaits its own barrier); request resolvers and
+authenticators as registries (the app's); chunked transfers as a Chord helper (an owner pattern, design §23); the
+channel component (D6); telemetry spans for requests (slice 9).
+
+## 6. Kernel changes
+
+- `host.route(Kind, options, ctx)` returns a `RouteHandle { retry(address), suspend(address) }` (D10b, R1, Q3).
+- A route has no backoff timer (R2): a rejected `resolve`, or a link that closes before its handshake completed, fails
+  the route's holders `failed { waiting }` with its error (they stay on the address's path, Q1) and resolves nothing
+  more; the route resolves again only for a new hold, on `retry`, or once after a link that had completed its handshake
+  dropped while holds exist; a suspended address resolves nothing while it has holders and forgets the suspension with
+  the last one.
+- `host.root(fn, ctx, { principal: undefined })` runs anonymous (`ctx.principal` undefined); only an omitted
+  `principal` takes the host's (a public-API change of `RootOptions`: `"principal" in options`).
+- Origins only from relays (decision, 2026-10-31, security audit): `origin` is read only on parent and route links;
+  on a child link it is a protocol error; a per-origin record goes once it has no holds, calls or messages in flight.
+- An anonymous `host.root` scope gets no remote object served on its host (`forbidden`).
+- Design §3: the paragraph on a `resolve` waiting for the worker's `load` is updated (done), and "Chord never closes a
+  route link itself except at `host.close`" becomes "except at `host.close`, the heartbeat and protocol errors".
+
+## 7. Tests, examples, cost
+
+- One test file per source file. HTTP: listening before the publication (a request waits, then is served; 503 past
+  `readyTimeout`); the router resolved once; `Host` (loopback forms, allowed from the option and from a writable
+  contribution changing at runtime) and `Origin` checks; anonymous requests (`ctx.principal` undefined on a server with
+  a principal); authentication per request and upgrade; throwing hooks; patterns, decoding, precedence, `HEAD`, 404;
+  conflicts reported; wraps (phases, order, scopes, a missing route, a throwing wrap); every response kind (ranges
+  206/416, multi-range, `HEAD`, download names, chunked without `size`, a short `read`, a disconnect stopping `read`,
+  header merging); `json`/`body` limits and their statuses, an unread body; a throwing route; the links endpoint
+  (`host.accept`, options per socket, a refused socket, the output cap); plugin sockets (an oversized frame closes only
+  that socket; a reload removing the contribution closes its sockets 1012); a removed allowed host closing its
+  connections; a reload swapping a route while a request runs on the old router; `fileResponse` closing its handle on
+  every path; `close` (refusals, waiting, then sealing). Workers: a start on the first hold; the link made at the fork
+  (a load longer than the heartbeat's 30 s binds); `started` on `connect`; the start timer covering only the start (a
+  slow `load` is not killed); the lock (an old worker's lock waited for without polling); `start` throwing; a crash,
+  a `fatal`, a link lost with a live child (killed after the grace), and a failed start each staying failed (no fork for
+  a new hold; holders `failed { waiting }`), `retry` and a rollout clearing them and rebinding the holders; idle stop,
+  a worker idle from its start, a hold keeping it; `busy`; 1,000 sequential local calls sending no message;
+  `stop` with holders (suspended, then forgotten with the last holder); stop during start and start during stop; a
+  crash while a resolve is queued; `close` (cancelling a start waiting in `start(address)`, no `worker_failed` at
+  shutdown); the rollout step (complete sets, a worker starting during it, a clean stop listed `stopped`, a crash during
+  it, an aborted reload's late reply, a kind no step shipped staying dirty); the child's shutdown during its startup,
+  disconnect and signals; `redact` (a secret in the original message reaches neither `fatal` nor `state`). Kernel:
+  `RouteHandle.retry` and `suspend`; a link closing before its handshake (no re-resolve loop); no re-resolve without a
+  hold, a retry or one drop of a healthy link; `host.root` with an explicit `undefined` principal.
+- GC: requests (their scopes, bodies, file handles) and stopped workers' state collected; no listener left on a closed
+  socket; 1,000 addresses started and stopped leave no `state` entries, no per-address queue records and no
+  suspensions.
+- Examples (each a folder, as 7c's): `40-http` (routes, a wrap, a download with ranges, a socket, an allowed host
+  added at runtime), `41-workers` (a server routing a session kind to forked workers, idle stop, a crash staying failed
+  until Retry, a rollout reaching the workers and restarting a held failed one).
+- Benchmark: a route's overhead per request against a plain Node handler (bar: within 10% of a keep-alive round
+  trip; Opus measured 2.5 µs of 54 µs); `bytes` throughput for a 100 MiB file against `pipeline`; a worker's cold start
+  (fork to `started` and to `ready`) with shipped scripts; memory per idle worker on the server.

package/docs/next/slice-11.md

@@ -0,0 +1,93 @@
+# Slice 11: web and TUI surfaces (spec)
+
+Status: **draft** (owner, 2026-10-30: "start on slice 11"; "this one needs to be generic, so apps can do whatever they
+want: css, tui components, themes"). Points marked **Decision needed** go to the owner one at a time.
+
+Slice 11 builds the generic plumbing of the app kit's two client surfaces (decision "Slice 7b's open points" (6)):
+`chord/next/web` (a browser page as a Chord client host that loads the plugins' web facets the server built) and
+`chord/next/tui` (a terminal client that does the same for TUI facets). The app keeps everything visible: its HTML
+shell, CSS, components, themes, navigation, layout, keys. Built on slice 10 (`http` serves, the plugins component
+builds and ships) and 7c (scripts as plain data, `createPluginRuntime`). Rule "The app kit is malleable by plugins"
+applies.
+
+Read in full before writing code: this spec; `decisions.md` ("Slice 7c's points", "Slice 10's points"); `design.md`
+§3 (clients), §21, §23; `slice-10.md`; p2's `src/hosts/web.ts`, `src/hosts/web/main.tsx`, `src/web/reconnect.ts`,
+`src/runtime/web.tsx`, `src/hosts/bundles.ts`, `src/hosts/tui.ts`, `src/hosts/tui-client.ts`, `src/hosts/tui-sandbox.ts`,
+`src/hosts/tui-bootstrap.mjs`, `src/hosts/tui-worker-runtime.ts`.
+
+## 1. What p2 has, and what is generic
+
+| p2 today | Generic (slice 11) | The app's |
+| --- | --- | --- |
+| one esbuild bundle per surface: runtime, React, every plugin's web facet, CSS; the page reloads whole when its version changes | a base bundle per surface (host packages and the surface runtime) plus each plugin's facet script (7c); new scripts applied in place | which host packages a surface has |
+| the page: HTML with a CSP nonce, a theme script, `#root`, the bundle | serving the base bundle, scripts, stylesheets and assets through `http`; a page template hook | the HTML shell, CSP, theme, manifest and icons, service worker |
+| `startWeb`: a client host, `keepConnected` (reconnect with backoff, wake on visibility and network change, stale-socket checks), protocol mismatch reloads the page | `startPage`: the client host, the connection loop, facet loading and reloading | `canRetry` policy (an ended share), connection UI |
+| `runtime/web.tsx`: `HostContext`, `useObject`, `useReadable`, `useRegistry`, slots, sheets, navigation, owner state | optional React bindings: provider, hold, watch, registry, reference state | slots, sheets, navigation, everything else |
+| TUI: a trusted launcher (auth, terminal, local preferences, actions), a permission-dropped worker thread running the downloaded bundle, a bridge terminal, a link through the launcher | a Node client surface: connect, download the base bundle and TUI scripts, evaluate, reload in place; the sandbox as an option | the TUI's components (pi-tui or other), commands, keys, themes, launcher actions |
+
+## 2. `chord/next/web`
+
+```ts
+// server: serve the page surface (routes contributed to `Http`, so they reload like any contribution)
+const web = webSurface(server, {
+	kind: "web",
+	plugins,                                              // the plugins component: the web kind's scripts
+	hostPackages: { "@earendil-works/chord/next": "chord-next", react: "react", "react/jsx-runtime": "react-jsx", "@app/web": "app-web" },
+	base: "./src/web/base.ts",                            // the surface runtime's entry: built once into the base bundle
+	page: (request, ctx, assets) => appShell(assets),     // the app's HTML; `assets` lists the base script and stylesheets
+}, ctx);
+
+// browser: src/web/base.ts (in the base bundle)
+startPage({
+	principal: { kind: "server" },
+	connect: () => new WebSocket(`${location.origin.replace(/^http/, "ws")}/chord`),
+	hostPackages: { "@earendil-works/chord/next": chordNext, react: React, "react/jsx-runtime": jsx, "@app/web": appWeb },
+	core: [{ name: "@app/web", facet: webCore }],
+	canRetry: async () => !(await shareEnded()),
+	onConnected: (connected) => setBanner(!connected),
+});
+```
+
+> **Decision needed P1: scope.** What `chord/next/web` ships: serving the surface (base bundle, scripts, stylesheets,
+> assets, the page through an app template), the browser's client host with its connection loop, loading the plugins'
+> web facets and applying new ones. Not shipped: HTML, CSS, components, themes, navigation, slots. React bindings
+> separately (P7).
+
+> **Decision needed P2: how the browser evaluates a facet script.** (a) Each script served as a file wrapped to register
+> itself (`chordFacet("<plugin>", "<digest>", function (require, module, exports) { … })`), loaded with `<script
+> src>` under a `'self'` CSP; (b) fetched and run with `new Function` (needs `'unsafe-eval'`).
+
+> **Decision needed P3: the base bundle.** Built on the server per surface by esbuild from the app's `base` entry with
+> the host packages inlined once; content-hashed; a change of base code reloads the page (as a server restart).
+
+> **Decision needed P4: applying new scripts in a page.** (a) In place: the page's host reloads per plugin
+> (`host.reload`, 7b), the UI re-renders from its registries; (b) the whole page reloads, as p2.
+
+> **Decision needed P5: how a page learns of new scripts.** (a) Through Chord: the surface serves a `remote` object
+> whose state is the current set (digests and URLs); every page holds it and applies changes; the rollout step publishes
+> without waiting for pages; (b) polling a manifest (p2: every 5 s while visible).
+
+> **Decision needed P6: the connection loop.** p2's `keepConnected`: reconnect after a drop with backoff (250 ms to 5
+> s), wake on visibility, `online` and network change, replace a stale socket, stop on an outdated protocol (reload) or
+> when the app's `canRetry` says no. A network reconnect, not a crash restart.
+
+> **Decision needed P7: React bindings.** An optional subpath (`chord/next/react`) with `HostProvider`,
+> `useHold(Type, params)`, `useWatch(watchable)`, `useRegistry(R)`, `useRefState(ref)`; or none in Chord.
+
+## 3. `chord/next/tui`
+
+> **Decision needed P8: scope.** A Node client surface (`startTerminal`): connect over WebSocket with the app's
+> credentials, download the base bundle and the TUI scripts from the server, evaluate them, run the app's entry with
+> its host, apply new scripts in place; the terminal belongs to the app. p2's sandbox (a permission-dropped worker
+> thread for code from another person's server, a bridge terminal, launcher actions) as an option or not in Chord.
+
+> **Decision needed P9: pi-tui bindings.** None in Chord (the app chooses its TUI library), or optional helpers.
+
+## 4. Not in slice 11
+
+App shells, themes, navigation, slots, offline support (service workers), the TUI's commands and preferences;
+telemetry (slice 9).
+
+## 5. Tests, examples, cost
+
+Filled once the points are decided. Examples: small and cute (owner), each a folder.