@earendil-works/chord 1.5.0 → 1.5.1

package/docs/slice-11.md

@@ -0,0 +1,114 @@
+# Slice 11: web and TUI surfaces (spec)
+
+Status: **approved** (owner, 2026-10-30/11-01: P1-P9 in the decisions "Slice 11's points" and "Slice 11, P3" to "P9",
+then "go ahead, just do all the things"). Built after slices 12 and 13: the surfaces are generic plumbing that the app
+kit wires in (`startApp` serves the web surface; a TUI client entry). The app keeps everything visible: HTML shell,
+CSS, components, themes, navigation, layout, keys.
+
+Read in full before writing code: this spec; `decisions.md` (slice 11's entries, the plugin model, the app kit);
+`design.md` §3 (clients), §21, §23 (all, "Web and TUI" included); `slice-10.md`, `slice-12.md`, `slice-13.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`, `src/runtime/tui.ts` (`TuiScope`).
+
+## 1. `chord/surfaces` (the web surface's server side)
+
+```ts
+// inside startApp (slice 13), or by hand:
+const web = webSurface(server, {
+	kind: "web", plugins,
+	entry: "./src/web/main.tsx",                       // the app's web start code: the base bundle's entry
+	page: (request, assets) => shell(request.nonce, assets),   // the app's HTML; assets: base script, plugins file, styles
+}, ctx);
+// its facet (routes to Http, the WebScripts object) goes into the server's core facets
+```
+
+- **Base bundle** per client kind: built on the server by esbuild from `entry`, with the kind's host packages inlined
+  once (the app's API modules for the kind, Chord, React), content-hashed (`/_chord/web/base.<hash>.js`), cached
+  forever (`Cache-Control: immutable`, overriding the baseline's `no-store` for these routes only); rebuilt when base
+  code changes (the server restarts anyway: built at start).
+- **Plugin scripts:** each web facet served as a script that registers itself (`chordFacet("<plugin>", "<digest>",
+  function (require, module, exports) { … })`, P2), at `/_chord/web/plugin/<plugin>.<digest>.js`, immutable; the
+  current set as one combined file `/_chord/web/plugins.<set-hash>.js` (P3); stylesheets and assets of the build
+  likewise, under `publicPath`.
+- **`WebScripts`** (a `remote` object the surface serves, params `{}`, any principal that may load the app): its state
+  is the current set `{ plugins: [{ name, digest, url, css? }], base }`; a rollout that ships the web kind updates it
+  (the plugins component's `scripts("web")` changes; the surface follows them) without waiting for pages (P5).
+- Routes and the page are `Http` contributions of the surface's facet; the page route is `page: true` (navigation from
+  another site allowed) and public or not as the app says.
+
+## 2. `chord/web` (browser side)
+
+```ts
+// src/web/main.tsx (the app's entry, in the base bundle)
+startPage<P>({
+	connect: () => new WebSocket(`${location.origin.replace(/^http/, "ws")}/chord`),
+	modules: { "@acme/app/v3": api, "@acme/app/v3/web": apiWeb, react: React, "react/jsx-runtime": jsx },
+	core: [{ name: "@acme/web", facet: webCore }],
+	canRetry: async () => true,
+	onConnection: (state) => setBanner(state),
+	render: (host) => createRoot(document.getElementById("root")!).render(<HostProvider host={host}><App /></HostProvider>),
+});
+```
+
+- A client host (no address); the connection loop (P6, p2's `keepConnected`: reconnect 250 ms to 5 s, wake on
+  visibility, `online` and network change, replace a silent socket, stop on an outdated protocol (reload the page) or
+  when `canRetry` says no); `onConnection` reports `connecting | connected | waiting`.
+- Loads the combined plugins file, evaluates each registered facet with `modules` (the `require` they get answers only
+  host packages and `@earendil-works/chord/plugins`'s browser half if any), loads them with `core` in one
+  `host.load`, then holds `WebScripts`: on a new set it fetches the changed scripts (`<script src>`, one each), and
+  calls `host.reload` with the complete set (P4: in place; a failed plugin keeps its old facet, reported to the app);
+  a changed `base` hash reloads the page.
+- CSP: scripts are `'self'` plus the nonce for the page's inline bootstrap; no `eval`.
+
+## 3. `chord/react`
+
+`HostProvider`, `useHost()`, `useHold(Type, params)` (a reference held for the component's life, released on unmount,
+re-held when params change), `useWatch(watchable)` (the current value, re-rendering on change; `useSyncExternalStore`),
+`useRegistry(R)`, `useRefState(ref)`. A component unmounted by a reload has not left (design §21): releases are plain
+releases, presence is the app's. No components, no styling.
+
+## 4. `chord/tui` and `chord/tui/launcher`
+
+- **Launcher** (trusted, a Node process): `startTerminal({ url, token | tokenFile, pairing?, ... })` connects (a token
+  from the owner token file, slice 13, or device pairing), downloads the base bundle and the TUI kind's plugin scripts
+  over HTTP, and starts the **sandbox**: a child process on pipes (decision "The terminal's sandbox is a child
+  process", replacing p2's worker thread: empty environment, Node's permission model granting nothing, no SQLite; no
+  terminal, file system, child processes or network except the bridge), always (P8), whose runtime gets a
+  bridge terminal (input events in, frames out), the Chord link (messages relayed by the launcher) and the evaluated
+  scripts. The launcher keeps credentials, the real terminal and local preferences, and exposes a small set of actions
+  to the sandbox (clipboard, open URL), each confirmed by the launcher's own UI when it touches the machine.
+- **Runtime** (inside the sandbox, in the base bundle): a client host like the page's, the same connection loop over
+  the bridged link, in-place reloads through a `TuiScripts` object as the web.
+- **`TuiScope`** (P9): `new TuiScope(host, changed)` with `hold`, `watch`, `registry`, `dispose`; no pi-tui dependency.
+
+## 4b. Looks and themes (decision "Looks and themes", `docs/theming/`)
+
+- The kit ships `Themes` (`defineRegistry<Theme, readonly Theme[]>`, in the shared module the kit's apps re-export),
+  `Theme = { id, name, mode: "dark" | "light", colors: { accent, bg, fg, muted, error, warning, success, ...app roles },
+  web?, tui? }`, and a `themes` preference per user (`{ dark, light }` theme ids) stored by the kit's users plugin or a
+  local object for single-user apps.
+- Web: `startPage` watches `Themes` and the preference with `prefers-color-scheme`, and writes the active theme as CSS
+  variables on `:root` (`--accent`, ..., plus `web` extras), with no reload; the base bundle's stylesheet is the app's.
+- TUI: `TuiScope`'s host gets a `theme` lookup by role (true colour, else the nearest of 256 colours, `tui` overrides
+  first).
+- CSS modules (`*.module.css`) work in plugin builds (esbuild's local-css loader); documented in `plugin-authoring.md`.
+- Version 1 of `Themes`; a later role is added by a version bump mapping old entries (missing roles from the default
+  theme).
+
+## 5. In the app kit
+
+`startApp` gains `web: { entry, page }` and `tui: { entry }` (optional); with them it creates the surfaces and adds
+their facets. Without, an app has no web or TUI surface (an API-only app).
+
+## 6. Tests, examples
+
+- One test file per source file. Web server side: the base bundle (hash, immutable, rebuilt per start), plugin
+  scripts and the combined file (registration wrapper, no eval, digests), `WebScripts` updated by a rollout, the page
+  route and CSP. Browser side under jsdom or a real browser (the repo's browser smoke setup, if it fits): the loop
+  (backoff, wake events, outdated protocol, `canRetry`), loading the combined file, an in-place reload keeping a
+  component's state, a base change reloading. React hooks (hold released on unmount, watch re-render, registry).
+  TUI: the sandbox cannot read a file or spawn a process (a test plugin that tries), the bridge, an in-place reload,
+  `TuiScope` disposal; pairing a TUI client against a kit app.
+- Examples: `56-web` (a kit app with a page, two web plugins, an edit applied in place), `57-tui` (a kit app with a
+  TUI client, sandboxed), `58-themes` (a theme plugin restyling a page and a TUI live).

package/docs/slice-12.md

@@ -0,0 +1,132 @@
+# Slice 12: the plugin model (spec)
+
+Status: **approved** (owner, 2026-11-01: the plugin model's decisions, then "go ahead, just do all the things"; this
+spec written by the redesign session from them, no separate spec review). Builds on 7c's plugins component
+(`src/node/plugins/`) and slice 10's kinds and `createPluginRuntime`.
+
+Read in full before writing code: this spec; `decisions.md` entries of 2026-11-01 "Contracts come from where the
+plugin's code came from", "Plugins import only the app's versioned API", "The plugin model, points 3, 4, 5 and 8,
+imports and builds", "Single-file plugins", "Testing a plugin alone"; `design.md` §21 (all of it, "The plugin model"
+included) and §16-§17; `slices.md` (carry-over "Slice 12"); `slice-7c.md`, `slice-10.md` §3 "Plugins in workers";
+`src/node/plugins/README.md` and its sources; the primer `docs/plugin-primer/book.md`.
+
+## 1. The app's API (`createPlugins` option `api`)
+
+```ts
+const plugins = createPlugins({
+	roots: [{ path: "./plugins", required: true }, { path: join(dataDir, "plugins") }],
+	api: { name: "@acme/app", versions: ["v3", "v2"] },          // newest first
+	kinds: {
+		server: { platform: "node", hostPackages: ["@acme/app/v3", "@acme/app/v3/server", "@acme/app/v2"] },
+		worker: { platform: "node", hostPackages: ["@acme/app/v3", "@acme/app/v3/worker", "@acme/app/v2"] },
+		web: { platform: "browser", hostPackages: ["@acme/app/v3", "@acme/app/v3/web", "@acme/app/v2", "react", "react/jsx-runtime"] },
+	},
+	onError,
+}, ctx);
+```
+
+- `api` names the app's API package and the versions it provides. A plugin import of `<name>/<version>[/<kind>]`:
+  a version not listed is a build error naming the listed ones ("@acme/app/v1 is not available: this app provides v3,
+  v2"); a listed one that the kind's `hostPackages` lacks (`@acme/app/v3/web` from a worker facet) is a build error
+  naming the kind. One facet's imports of the API all use one version (a mix is a build error naming both).
+- Chord itself (`@earendil-works/chord` and its subpaths other than `/plugins`, which stays as in 7c for
+  `pluginFile`) is not importable by plugins: a build error pointing to the app's API. Apps that do not set `api` keep
+  7c's behaviour (host packages as listed), so Chord's own tests and examples keep importing Chord directly where they
+  model base code.
+- `roots` entries may be strings (as today) or `{ path, required? }`. A plugin of a required root whose build,
+  evaluation or setup fails at `plugins.load` makes `load` reject (`PluginError` naming it), after the host's own load
+  settled; failures in other roots are reported as today. At a reload, a required plugin failing keeps its old code as
+  any plugin (reported).
+
+## 2. Imports between plugins (replaces slice 10's by-name lookup)
+
+- **Relative paths within a root:** an import from one plugin into another plugin's directory under the same root
+  (`../notes/contract.ts`) is inlined (listed in `copied`), the copied file under 7c's rule (only host packages and
+  files of its own plugin). A relative path leaving the root (base code, another root) is a build error naming the file
+  and pointing to the API or a dependency. A git checkout of several plugins cloned into a root is "within a root".
+- **Package names across repositories:** an import of a package in the plugin's `dependencies` resolves as npm does
+  through that package's `exports` (`@bob/notes` → its `contract.ts`, `@bob/notes/web` → `contract.web.tsx`), inlined
+  at the installed version. A dependency may be an npm version or a git URL with a ref (`github:bob/notes#<commit>`,
+  `git+https://...#<tag>`); `installDependencies` installs it with npm as today. A plugin inside a multi-plugin
+  repository is reached through a dependency on the whole repository, by path into it (`@bob/plugins/notes/contract.ts`)
+  or its `exports` (decision "`chord.plugins` is a package's manifest of plugins").
+- **`chord.plugins`** in a package's `package.json` lists the plugin folders it provides (globs, exclusions); used by
+  discovery of a root's packages and by `installPlugin`; without it, conventional discovery.
+- The by-name lookup (`build.ts` `#byName`), its error texts and the six `tsconfig.json` path aliases go; fixtures and
+  examples 35-38 import relatively again.
+
+## 3. Per-kind files and the import check
+
+- A file whose name has a kind segment before its extension (`contract.web.tsx`, `ui.tui.ts`, any `*.<kind>.<ext>` with
+  `<kind>` one of `kinds`) is a file of that kind: importing it (directly or through other files) from a facet of
+  another kind is a build error naming the chain. Facet files keep their names (`web.tsx`); contract files are
+  `contract.ts` (shared) and `contract.<kind>.ts(x)`.
+- The check runs in the existing esbuild `onResolve` path, on the resolved file, for relative imports, dependencies and
+  copied files alike.
+- Documented, not checked: a contract file mentions native things only through `import type` (TypeScript erases it;
+  a runtime import of a package the kind lacks already fails as above).
+
+## 4. Single-file plugins
+
+- Discovery also lists files at a root's top named `<name>.<kind>.(ts|tsx|js|mjs)`; files of one `<name>` form one
+  plugin named `<name>` (an unscoped valid npm name, else reported), one facet per file, `dir` the root, no
+  `package.json` (no dependencies, no `chord.external`). A directory plugin of the same name in the same root is a
+  reported duplicate (the directory wins).
+- Its build allows imports of host packages only (the app's API); anything else is a build error saying to make it a
+  directory. `pluginFile` refuses (it has no directory of its own).
+- The watcher: such a file appearing or disappearing at a root's top sets `set`; a change marks the plugin dirty.
+
+## 5. Installing plugins
+
+`installPlugin(source, root, ctx)`: `source` is `{ git: url, ref }` (a shallow clone of the ref into
+`<root>/<repository name>`; a repository whose top has a `package.json` is one plugin, otherwise its subdirectories
+are plugins) or `{ npm: name, version }` (`npm pack` and extract into `<root>/<name>`), then `installDependencies` for
+each new plugin; marks `set`. Returns the installed plugin names. Removal is deleting the directory (`set`). No
+updating in place: install another ref (a new directory) or delete and install.
+
+## 6. `testPlugin`
+
+```ts
+const t = await testPlugin("./plugins/stats", {
+	kind: "worker",
+	api: { name: "@acme/app", versions: ["v3"] },
+	modules: { "@acme/app/v3": apiV3, "@acme/app/v3/worker": apiV3Worker },   // the real API modules
+	stubs: [{ name: "@acme/notes", facet: notesStub }],                        // facets serving what it uses
+	principal: { kind: "user", id: "u1" },                                      // the host's principal (optional)
+}, ctx);
+const stats = await t.host.get(Stats, { project: "p1" }, ctx);
+t.contributions(Panels);   // what the plugin contributed to a registry nobody serves (the helper serves it)
+t.unserved();              // contract names requests wait for unbound `not_served`
+await t.close(ctx);
+```
+
+- Built with the same build as production (`buildFacet` with the kind's options), evaluated with `modules`, loaded on a
+  host with `address`/`principal` as given, an in-memory store (`:memory:` SQLite); stubs loaded beside it.
+- The helper serves, as a collecting registry, every registry the plugin contributes to that no stub or the plugin
+  itself serves (`t.contributions(R)`: the current entries).
+- `t.unserved()` lists the names of contracts whose requests wait unbound `not_served` on the host (the unbound
+  index), so a test knows what to stub. `t.root(fn, ctx, { principal })` runs as another principal.
+- Exported from `chord/plugins` (`testing.ts`); no test-only modes elsewhere.
+
+## 7. Docs for authors and agents
+
+- `docs/plugin-authoring.md`: a plugin's layout (directory and single-file), its facet and contract files per
+  kind, what it may import and how each import resolves, versions, how the server builds it (esbuild, what the build
+  handles, no build hooks), installing from git or npm, testing with `testPlugin`; written for agents (short, exact,
+  with one complete example plugin).
+- Update `src/node/plugins/README.md`, the guide `docs/guide-plugins-hosts/book.md` (chapters "Plugins Using
+  Plugins" and "Base Code and Plugins"; rebuild `index.html`), design §21's slice-10 note.
+
+## 8. Tests, examples
+
+- One test file per source file; build tests for every refusal and allowance of §1-§4 (an unlisted version, a kind
+  module from another kind, mixed versions, a Chord import, a relative path leaving the root, a per-kind file through
+  a chain, a package from `dependencies` through `exports`, a git dependency with a ref (a local bare repository in a
+  temp directory, no network), a subfolder dependency); discovery of single-file plugins; required roots at load;
+  `installPlugin` from a local git repository and a local npm tarball; `testPlugin` (stubs, collected contributions,
+  `unserved`, a principal).
+- Examples: `49-plugin-api` (an app API with two versions and per-kind modules, a plugin per version, the refusals),
+  `50-plugin-imports` (relative within a root, a git dependency pinned to a commit, per-kind contract files),
+  `51-single-file-plugin`, `52-test-plugin` (a plugin tested with a stub). Examples 35-38 updated.
+- No hot path changes; no benchmark beyond a cold build of the 20-plugin set (as 7c's) to show the checks cost nothing
+  measurable.

package/docs/slice-13.md

@@ -0,0 +1,121 @@
+# Slice 13: the app kit (spec)
+
+Status: **approved** (owner, 2026-11-01: decisions "The app kit, point 1" to "point 5", then "go ahead, just do all
+the things"). Builds on slices 10 (`http`, `workers`) and 12 (the plugin model). `chord/app` in
+`src/node/app/`: an opinionated layer so an app is its API, its built-in plugins and a start script.
+
+Read in full before writing code: this spec; `decisions.md` entries of 2026-10-31 and 2026-11-01 (the app kit, the
+plugin model, "The app kit is opinionated", "Settings are arguments, extensions are registries", "The HTTP
+component's security baseline"); `design.md` §3, §4, §10, §21, §23 (all of it, "The app kit" included); `slices.md`
+(carry-over "Slice 13"); `slice-10.md`, `slice-12.md`; the READMEs of `node/http`, `workers`, `plugins`; p2's
+`src/runtime/server.ts`, `src/hosts/server.ts`, `src/hosts/worker.ts`, `src/runtime/loopback-cookie.ts`,
+`src/hosts/principals.ts`, `plugins/devices/`, `plugins/sharing/`, `plugins/files/` for what exists.
+
+## 1. `startApp` and `startWorker`
+
+```ts
+// start.ts (the app's start script)
+const app = await startApp<P>({
+	name: "acme",                                   // the default data directory: ~/.acme
+	dataDir: process.argv[2],                       // optional; no environment variables
+	listen: { host: "127.0.0.1", port: 8788 },
+	api: { name: "@acme/app", versions: ["v3"], modules: { "@acme/app/v3": apiV3, "@acme/app/v3/server": apiV3Server } },
+	kinds: { server: { platform: "node" }, worker: { platform: "node" }, web: { platform: "browser", packages: { react, "react/jsx-runtime": jsx } } },
+	principal: { server: { kind: "server" }, worker: (address) => ({ kind: "worker", key: address.key }) },
+	workers: [{
+		kind: Project,                              // a host kind the app defines, any params
+		entry: "./worker.ts",
+		start: (address, ctx) => ({ id: address.params.id }),
+		authorize: (principal, address) => mayReach(principal, address),
+		idleMs: () => 5 * 60_000,
+	}],
+	onError: (error) => log(error),
+}, ctx);
+// app.host, app.http, app.workers, app.plugins, app.applyChanges(ctx), app.exportAddress(address, ctx),
+// app.importAddress(archive, address, ctx), app.ownerLink(), app.close(ctx)
+```
+
+```ts
+// worker.ts
+await startWorker<P>({ api, kinds, onError });   // reads the start message, opens the worker's store, loads plugins
+```
+
+- `startApp` creates the data directory layout (§4), opens the server store, creates the host (address `Server()`,
+  the server principal), `createHttp` (settings as arguments), `createWorkers` per worker kind (`kind` named after the
+  host kind; the worker's facet kind is `worker` unless the entry says otherwise), `createPlugins` with the roots of §5
+  and the app's API (slice 12), loads the server's plugins with the kit's own facets (§2, §3, §4) as core, and resolves
+  once loaded. `close` closes in the right order (http, workers, host, store).
+- `startWorker` is `workerMain` plus: the worker's directory and store under its kind and address, the host with the
+  principal from the start message, `connect` first, plugins loaded with the kit's worker facets, `busy` from the app
+  if given.
+- The start-data facet: the kit serves `AppInfo` (data directory, app name, version) on the server and `WorkerInfo`
+  (address, start data) on workers as core objects plugins `get`.
+- Zero worker kinds: no workers component.
+
+## 2. Principals and sessions
+
+- The app's principal type `P`; the kit needs only `principal.server` and `principal.worker(address)`. The kit adds
+  one variant for its owner: `{ kind: "owner" }` must be assignable to `P` (a type check). (Superseded: decision "The
+  kit's owner is a principal the app chooses".)
+- **Sessions** (`app/sessions.ts`, a kit object on the server, persisted in the server store): `issue(principal,
+  { label, kind: "browser" | "device" }, ctx)` returns a token; tokens stored hashed; `revoke(id)`; `list` (watchable:
+  label, kind, created, last used). The kit's authenticator (contributed to `Authenticators`) reads the session cookie
+  (signed, `HttpOnly`, `SameSite=Strict`) or an `Authorization: Bearer` header, and gives its principal.
+- **Owner link:** at start the kit issues a one-time token (random, single use, valid 10 minutes, replaced at each
+  start) and `app.ownerLink()` returns `http://127.0.0.1:8788/_chord/owner#<token>`; the start script prints it. The
+  route `GET /_chord/owner` serves a page that posts the token (from the fragment, never sent in a URL to logs) to
+  `POST /_chord/owner`, which consumes it and sets a browser session cookie for the owner. No owner by loopback alone.
+- **Owner token file:** `<dataDir>/owner-token` (mode 0600, created at first start, a device session of the owner) for
+  command-line clients on the same machine.
+- **Device pairing** (for remote command-line and TUI clients): `POST /_chord/pair` (public) returns `{ code, poll }`;
+  the owner approves the code in a browser (`GET /_chord/pair/<code>`, owner only, a confirm page); the client polls
+  and receives a device token. Codes expire after 10 minutes.
+- **Deny by default** (an HTTP component change): a route or socket without a principal is refused (401) before plugin
+  code, unless its contribution marks it `public: true` (routes: `{ handler, public: true }`; sockets likewise). The
+  `/chord` links endpoint requires a principal. Foreign requests stay anonymous as before, so they reach only public
+  routes. Slice 10's examples and tests mark their anonymous routes public.
+
+## 3. Optional kit plugins
+
+Shipped as plugins (in `packages/chord/plugins/` or exported facets the app adds to its root; choose one and say
+why): `users` (accounts keyed by id, a profile schema the app passes in, `self.get(Users, {})` with `get`, `update`,
+`list`), `invite` (invite links issuing a session for a principal the owner chooses), `ephemeral-login` (a public
+route taking a name, issuing a session for `{ kind: "user", id: <fresh>, name }` that ends with the connection; the
+app's `P` must allow it). Each contributes to `Authenticators` or issues sessions through §2.
+
+## 4. Storage, files, export
+
+- Layout: `<dataDir>/server/store.sqlite`, `<dataDir>/workers/<kind>/<encoded address key>/store.sqlite` plus that
+  worker's files, `<dataDir>/plugins/` (the user's root), `<dataDir>/logs/`, `<dataDir>/owner-token`.
+- **Files** (a kit facet on workers, and on the server for server-scoped files): `Files` (`local`, params `{}`, one per
+  host) with `put({ name, mime, bytes })` for small files, `begin`/`append`/`finish` for large ones (design §23 chunked
+  transfers), `read({ id, offset, length })`, `remove`, `list` (watchable index: id, name, mime, size, created), caps
+  per host (an option). Stored under the host's directory (`files/`), the index in the store.
+- **Export / import per address:** `app.exportAddress(address, ctx)` stops the worker (as `workers.stop`), writes one
+  archive: the store's export archive (slice 6a) plus the worker's directory (files), and returns a readable stream or
+  writes to a path; `importAddress(archive, address, ctx)` refuses an existing address, unpacks, and the next hold
+  starts the worker. Format: a tar of `store.archive` and `files/`, with a small manifest (app name, API version,
+  kit format version).
+
+## 5. Plugins
+
+- Roots: the app's `plugins/` (required, slice 12) and `<dataDir>/plugins/`. Installs (`app.plugins.install(source,
+  ctx)`, slice 12's `installPlugin`) go to the user's root.
+- `app.applyChanges(ctx)`: build the dirty plugins and roll out (server step, then the workers step); returns the
+  rollout result; `app.plugins.state` for the app's button. Never applied by itself.
+
+## 6. Not in slice 13
+
+Web and TUI clients (slice 11, which builds on this kit: `startApp` gains the web surface there); telemetry (9);
+project plugins (§26 #14).
+
+## 7. Tests, examples, docs
+
+- One test file per source file: start and close order; a server without workers; two worker kinds; the owner link
+  (single use, expiry, the fragment), sessions (issue, revoke, list, hashed storage), the token file mode, device
+  pairing, deny by default (a route without principal 401, a public route served, `/chord` refused anonymous), Files
+  (small and chunked, caps, list, remove), export and import (a worker with documents, tables and files round-trips;
+  importing over an existing address refused), `applyChanges`, required root failure stopping `startApp`.
+- Examples: `53-app` (a small app: start script, API, two plugins, a worker kind, the owner link), `54-app-sessions`
+  (pairing a command-line client), `55-app-export` (export and import a worker's address).
+- `src/node/app/README.md`; the guide "Hosts and Plugins" gets a closing chapter on the app kit.

package/docs/slice-2.md

@@ -0,0 +1,174 @@
+# Slice 2: failures and natives (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 2, together with the feature map in `slices.md`
+(entries assigned to slice 2), `design.md` read in full (most relevant: §3 timeouts, §6 lifecycle and failures, §7
+references, §13 natives, §21 start barrier), the decision log, the carry-over (L4 section) and the root `AGENTS.md`
+style section. Builds on slice 1 (`src/state`, `documents`, `host`, committed `d8f5e67e6`) and L1.
+
+## What an app can do after this slice
+
+```ts
+host.serve(Inbox, (_, self) => {
+  const settings = self.get(Settings, {});
+  const watcher = self.open(
+    async (context) => watchDir(settings.dir.value.path, context.abortSignal),   // opened during activation
+    async (w, reason) => w.close(),                                               // closed in reverse when the object ends
+  );
+  return { count: …, rescan: async (ctx) => watcher.value.rescan(ctx) };
+});
+
+host.serve(Remote, (_, self) => {
+  self.open(async (context) => {
+    const config = readConfig();
+    if (!config) throw broken(new Error("no remote configured"));   // retrying is pointless: broken
+    return connect(config, context.abortSignal);                    // a throw here is transient: retried with backoff
+  }, (c) => c.close());
+  return { … };
+});
+
+const host = createHost({ onError, closeTimeout: 30_000, readyTimeout: 60_000 });
+await host.load(facets, ctx);          // resolves once every host-lifetime object is live or failed; failures reported
+const inbox = await host.get(Inbox, {}, ctx);   // waits through transient retries up to readyTimeout
+await host.close(ctx);                 // closes natives (reason "stop"); rejects with every close error
+```
+
+## 1. Natives (§13)
+
+- `self.open(open, close, options?)` in a factory returns a handle (`Native<T>`). Its `value` is readable from the
+  moment its own `open` resolved until its `close` starts (so a later opener and handlers during the drain can use
+  it); before that it throws `not_ready`, after that `released`.
+- `open(context)` receives a context whose abort signal fires when the attempt is abandoned (the object ends, the
+  attempt times out). `close(value, reason, context)` with `reason: { kind: "end" } | { kind: "stop" } | { kind:
+  "reload" }` (`end`: last reference gone or a failed attempt; `stop`: `host.close`; `reload` is used from slice 7);
+  the close context's signal fires at the native's `closeTimeout`, so a slow close can stop its own work. `options.closeTimeout`
+  overrides the host default for this native.
+- **Activation order:** factory; singleton documents hydrated; references live; natives opened **one after another in
+  declaration order**; members checked; derives computed; live. An opener may read documents, references and earlier
+  natives, not derives (they are computed after the opens).
+- **Closing:** in reverse order. Each close is awaited up to its `closeTimeout`; one that takes longer is reported to
+  `onError` as a possible leak and the others continue. A throwing close does not stop the others: `host.close` collects
+  every close error and rejects with them (`AggregateError`); an object ending in the background reports each to
+  `onError`.
+- **Abandoned opens:** a failed or abandoned attempt closes the natives already open (reason `end`). An `open` that
+  resolves after its attempt was abandoned has its value closed at once, exactly once (reason `end`); an abandoned
+  attempt never comes back to life. A later attempt opens every native anew.
+- Facets cannot open natives (`FacetSelf` has no `open`). The two restart patterns of R16 (drain in the background,
+  swap through a registry) are documentation in the host README; there is nothing to build.
+
+## 2. Failures (§6)
+
+- Every activation failure becomes a `FailureCause` (L1: `{ kind: "transient" | "broken"; error: ChordError }`,
+  foreign errors wrapped by `asChordError`). The kind comes from where it failed, never from the error:
+
+  | Where | Kind |
+  | --- | --- |
+  | factory throws; a singleton's `initial()` fails its schema; member check (incl. a native watchable as state, Q14); first derive compute; a dependency cycle (Q5) | broken |
+  | an `open` throws | transient, unless it threw `broken(error)` (L1) |
+  | the attempt did not become live within `readyTimeout` | transient: `unavailable` "did not become live within …" |
+  | a dependency failed (R18) | transient: `unavailable` "A: dependency B failed", with B's error as its `cause` |
+
+  A keyed document's first `initial()` runs inside a later transaction; a failure there fails that transaction, not the
+  object.
+- **Every attempt is bounded** by the host's `readyTimeout`: when it passes, the attempt is abandoned (openers'
+  contexts aborted, open natives closed `end`, a late open closed at once) and fails transient. A hanging `open` can
+  therefore never block an object or the start barrier.
+- **What a failed object keeps:** only an R18 failure keeps the object's references (so the dependency's recovery can
+  retry it); every other failure releases them at once (a cycle, a factory, an open, a derive). A failed object stays
+  while anything references it (host-lifetime objects always); it ends with its last reference.
+- **Retries.** One attempt per object at a time; a trigger arriving during an attempt is ignored. Transient: retried
+  with a **backoff per identity**, 1 s doubling to 60 s. The backoff lives in a host map `identity → { delay, timer }`
+  holding no object (the window is its timer); it is deleted on success, on a broken failure, or when a window has
+  passed with no object left to retry, and cleared by `host.close`; while its object stays failed the entry keeps the
+  delay for the next doubling. A get inside the
+  window waits until `until` before the first attempt; a failed object without references is not retried
+  (host-lifetime objects always are). Broken: no automatic retry and no entry; a new object after its end tries at
+  once. In this slice a broken host-lifetime object stays failed until the host is recreated (reload, slice 7, and
+  `retryOn`, slice 8, add triggers).
+- **Dependency recovery (R18):** when a failed dependency goes live, its R18 dependents are retried at once (their
+  backoff timers cancelled). On every retry the new attempt binds its `self.get` references **before** the previous
+  attempt's are released, so a dependency held only by this object never ends between attempts.
+- **Reporting:** every failed attempt is reported to `onError` (with the object's name and cause); gets waiting for it
+  are rejected in addition (section 3).
+- **The start barrier (§21):** `load` resolves when every host-lifetime object's **first** attempt has an outcome (live
+  or failed); later retries never hold `load`. A facet setup that throws or a facet document's `initial()` failing its
+  schema still rejects `load` (code errors).
+
+## 3. Getting a failing object (§7)
+
+- `host.get(Type, params, context, { readyTimeout? })` resolves with a live reference. Each getter has its own deadline
+  (`readyTimeout`, host default, overridable per get) for its whole wait, including a wait for `load`; it is separate
+  from the attempt's own bound. A broken cause rejects the getter at once with its error; a transient one keeps it
+  waiting through retries until the object is live or its deadline passes, then rejects with the last cause's error
+  (or `unavailable` if no attempt has failed yet). A getter whose deadline passes or whose context is cancelled
+  rejects and releases only its own reference; it never cancels the attempt for other getters.
+
+## 4. Ending with natives (§3, §6)
+
+- When an object ends: its transactions are sealed at once (`self.tx` throws `released`); callers of its running calls
+  are rejected `released` at once and the handlers' contexts aborted (slice 1); Chord keeps each running **handler's**
+  own promise and waits for those to settle (the drain), bounded by `closeTimeout`; then it closes its natives in
+  reverse order (a handler still running after `closeTimeout` sees its natives close; that is reported); its documents
+  stay readable until its closes are done, then are dropped; then the rest as in slice 1.
+- A new attempt or a new object for the same identity starts only after the previous instance's ending has finished;
+  gets arriving meanwhile wait.
+- `host.close(context)`: marks every object ended at once (every call on the host fails `released`, every `self.tx`
+  throws), aborts pending opens (their late values are closed), joins endings already running in the background, then
+  drains and closes object by object in reverse live order (a dependent before its dependencies), with reason `stop`;
+  resolves when all are done, or rejects with the collected close errors.
+
+## 5. Timeouts (§3, cut C13)
+
+Host options with per-thing overrides: `closeTimeout` (default 30 s; per native), `readyTimeout` (default 60 s; per
+get; also bounds each attempt). The call drain uses `closeTimeout` (no separate setting; the design's per-type drain
+override is not built). Park deadline (slice 3), routine handover and `finish` retry (slice 5) and rollout install
+(slice 7) come with their slices.
+
+## Cost per hop
+
+Commits and derives are unchanged. A call adds one set entry for its handler's promise (the drain needs it).
+Activation adds one awaited open per native and one attempt timer; a failure adds one backoff entry; ending adds the
+drain and the closes.
+
+## Carry-over taken by this slice
+
+From `carry-over.md` (L4): `broken()`/`openFailure()` used for opens; a native watchable as state fails `broken`
+naming the member; the drain on ending; cuts C5, C6, C7, C13 decided here.
+
+## Tests
+
+- Natives: open order and access to earlier handles; `not_ready` before live; close in reverse with reasons `end` and
+  `stop`; a slow close reported after `closeTimeout` and the others still closed; throwing closes collected by
+  `host.close` (AggregateError) and reported to `onError` for a background end; a partly failed attempt closes what it
+  opened; the opener's context aborted when the object ends while opening; facets have no `open`.
+- Failures: each row of the table gives the right kind; the cause's error is a ChordError; transient retries follow
+  the backoff (fake timers) and reset on success; concurrent gets share one attempt; a broken failure is not retried;
+  a failed object ends with its last reference and its backoff entry expires; a get right after a failure waits for
+  the scheduled retry.
+- R18: a dependent of a failing dependency fails transient with the dependency's cause, keeps the reference and is
+  retried at once when the dependency goes live; releasing the dependent releases the dependency.
+- Start barrier: load resolves with a failed host-lifetime object, reports it to `onError`, and the object goes live
+  on a later retry; a throwing facet setup still rejects load.
+- Gets: broken rejects at once; transient waits and succeeds on retry; transient past `readyTimeout` rejects with the
+  cause; per-get `readyTimeout`; a cancelled caller releases only its own reference.
+- Ending: the drain waits for a running handler (its own promise, not the rejected caller's) before its native
+  closes, bounded by `closeTimeout`; documents readable during closes; transactions sealed at once.
+- Races: an open resolving after its attempt was abandoned is closed once; a get arriving while the previous instance
+  closes waits and gets a fresh attempt; simultaneous retry triggers give one attempt; two getters with different
+  deadlines; a dependency held only by a retrying dependent is not ended between attempts; `host.close` during a
+  pending open, during a background ending, and with several objects in dependency order; a cycle releases its
+  references.
+- GC: a failed object (documents, dependencies, natives, callbacks) is collected after its last reference while its
+  backoff entry still exists; the entry expires on its own.
+- Examples: `06-natives.ts`, `07-failures.ts` (numbering continues from slice 1).
+
+## Decided with the owner (2026-10-22)
+
+- `ref.state`, `ref.retry()` and `host.hold` move to slice 3 (no app-held reference can be failed before then).
+- `host.get` on a failing object and the start barrier as in sections 2 and 3; C13 as in section 5; C5: no natives in
+  facets; openers take a `Context`; `close` gets a context aborting at `closeTimeout`.
+- C7: `linger` is built in slice 3, with links. The plugin error shape is decided in slice 3, where errors first cross
+  a link.
+
+## Size
+
+About 700 source lines (both reviewers: the attempt states, backoff map, drain and timers).