@earendil-works/chord 1.5.0 → 1.5.1

package/docs/guide-plugins-hosts/book.md

@@ -0,0 +1,957 @@
+---
+title: Hosts and Plugins: a tutorial for Chord v2
+cover: Hosts / and Plugins
+kicker: A guide · Chord v2 · 2026-11-02
+subtitle: Build a small notes app step by step, from one host to plugins on a server and on workers, edited while it runs
+stats:
+  - 3 | kinds of host in an app: server, worker, client
+  - 1 | file per host kind in a plugin
+  - 0 | restarts to apply a plugin edit
+  - 1 | rule: plugins talk only through object types and registries
+note: |
+  A tutorial for people building apps on Chord v2, written by the redesign session from `design.md`, `slice-7c.md`,
+  `slice-10.md`, `slice-12.md`, `slice-13.md`, the decision log and the code in `packages/chord/src`. API names
+  are the current ones. The early chapters wire hosts by hand to show the parts; the last chapter shows the app kit
+  (`chord/app`), which does that wiring for an app.
+colophon: Hosts and Plugins · fourth edition · 2026-11-04 · Chord v2 slices 1-13, messages and languages, telemetry
+---
+
+# Before we begin {.preface}
+
+You want to build a notes app. You type a note in a browser tab, and every other tab sees it at once. Each project
+gets its own notes in its own process, so a project that misbehaves cannot take the others down. And you, or an agent
+you work with, add features while the app runs: a search, an export button, a word count, without restarting
+anything.
+
+Chord gives you three things for that. **Hosts**: the processes of your app (the server, a worker per project, the
+browser tabs), connected to each other. **Objects**: the state and methods your app is made of, living on one host and
+used from any other. **Plugins**: directories of code that declare objects for each kind of host, loaded and
+reloaded while the app runs.
+
+This book builds the app in that order. Each chapter adds one concept and shows complete code.
+
+## Seven things to know
+
+:::findings
+1. **A host is one participant.** The server, each worker, each browser tab and each terminal UI is a host; hosts
+   connect over links. Tabs and terminal UIs are clients: no address, they connect to the server and ask.
+2. **An object has a type, and a type is a contract.** The contract names the object's state and methods; any host can
+   ask for an object by type and params, and Chord finds where it lives.
+3. **A facet declares, an object acts.** A facet is a plugin's code for one host kind: it says which object types this
+   host serves. The objects hold the state and do the work.
+4. **A plugin is a directory** (or a single file). A `package.json` with the plugin's name, and one file per host kind:
+   `server.ts`, `worker.ts`, `web.tsx`. It imports its host only through the app's versioned API (`@app/api/v1`).
+5. **The server builds, every host evaluates.** The plugins component builds each facet into a small script; the
+   server, workers and tabs load the scripts for their kind.
+6. **Plugins meet through types and registries.** One plugin uses another's objects through its contract, or
+   contributes to a registry another defines. Nothing else crosses between plugins.
+7. **An edit is a rollout.** Change a file, build, roll out: the server, then every worker, restart the plugin's
+   objects (running work finishes on the old code); a broken edit keeps the old code running and reports why.
+:::
+
+:::flow wide animate | How it all fits: plugins on disk are built once on the server; each host evaluates the facets of its kind; tabs and the TUI are clients that reach workers' objects through the server.
+row "On disk" muted
+box disk "plugins/notes/" "`server.ts`, `worker.ts`, `web.tsx`, `tui.ts`, `contract.ts`" muted
+box core "src/ (base code)" "`@app/api/v1`: Chord's surface, host kinds, principals" muted
+row "Server process" accent
+box comp "plugins component" "discover, build every facet, watch, roll out" accent
+box server "server host" "server facets; routes Project → workers"
+row "Clients and workers"
+box tab "client: tab or TUI" "web or tui facets, local UI objects; holds `Notes { p1 }`" blue
+box w1 "worker p1" "worker facets; serves `Notes { p1 }`"
+arrow disk -> comp "read, build"
+arrow core -> comp "host packages"
+arrow comp -> server "server scripts"
+arrow comp -> tab "web or tui scripts"
+arrow tab -> server "hold Notes { p1 }"
+arrow server -> w1 "start (worker scripts), relay"
+note "Each host loads only its own kind's facets. Plugins meet only through object types and registries."
+:::
+
+## Words used throughout
+
+A **host** is one participant of the app, made with `createHost`. A **host kind** (`Server`, `Session`) describes
+addressable hosts; an **address** (`Session({ id: "p1" })`) names one. An **object type** is a contract: `local` (used
+on its own host only) or `remote` (used from any host). An **object** is one instance of a type, per params. A
+**facet** is a plugin's declarations for one host kind. A **plugin** is a directory with a `package.json`. A
+**reference** is what you get when you ask for an object (`host.get`, `self.get`, `ctx.get`). A **document** is data an object
+stores, changed in **transactions**; a **table** holds many records with queries, in the host's **store**, and a **live query** keeps some of its rows current; a **derive** is a value computed from others; a **native** is an outside
+resource an object opens and closes. A **registry** is an
+extension point: one plugin defines it, others contribute. A **rollout** applies a build to the hosts in order.
+
+# One Host {#host lede="The smallest app: one process, one object type, one call."}
+
+Start without plugins. One host, one object that keeps notes:
+
+```ts
+import { createHost, defineFacet, defineState, local, method, obj, arr, str } from "@earendil-works/chord";
+
+const NoteList = obj({ items: arr(str()) });          // one schema, used by the contract and the document
+
+// the contract: what a Notes object offers
+const Notes = local("notes.store", {
+	version: 1,
+	params: {},                                        // one object per host: no params
+	members: {
+		list: NoteList,                               // state anyone can read and watch
+		add: method(obj({ text: str() })),            // a method: arguments checked by Chord
+	},
+});
+
+// the document the object stores (its own version: storage can change without changing the contract)
+const NotesDoc = defineState("notes", { schema: NoteList, version: 1, initial: () => ({ items: [] }) });
+
+// the facet: which types this host serves, and how to make each object
+const facet = defineFacet((host) => {
+	host.serve(Notes, (_params, self) => {
+		const doc = self.state(NotesDoc);
+		return {
+			list: doc,
+			add: async ({ text }, ctx) => self.tx(async (tx) => { (await tx.draft(doc)).items.push(text); }, ctx),
+		};
+	});
+});
+
+const server = createHost({ onError: console.error });
+await server.load([{ name: "@app/notes", facet }], ctx);
+const notes = await server.get(Notes, {}, ctx);        // a reference: live, with its state
+await notes.add({ text: "buy milk" }, ctx);
+console.log(notes.list.value);                          // { items: ["buy milk"] }
+```
+
+Four things happened. The **contract** `Notes` says what the object offers; the **document** says what it stores.
+Here they have the same shape, so one schema serves both; they are separate because they change separately (an
+object may offer a computed value or a shortened view instead of what it stores, and storage can change its shape
+without users noticing).
+The **facet** says this host serves
+`Notes`, with a **factory** that declares the object's parts: a document, and a method writing it in a transaction.
+`load` publishes the facet. `get` returns a **reference** once the object is live; its members are the contract's.
+
+The factory only declares: it is synchronous and opens nothing. Chord activates the object (loads its documents, opens
+what it asked to open) and then serves calls. That is why the same factory can run again when the code changes.
+
+**`load` comes first.** A `get`, `hold` or `registry` on a host whose `load` was not called throws `not_ready` at once
+("call `host.load` first"): it would wait for types nobody published. A client with nothing to load calls
+`load([])`. Mistakes that would otherwise look like slowness are reported through `onError` instead: a request
+waiting for a type or registry nobody serves (`unbound_long`, after 5 s; it keeps waiting until its `readyTimeout`),
+a registry with contributions and no provider (`registry_undeclared`, when `load` publishes), and a plugin name that is
+no npm name makes `load` throw.
+
+# An Object's Parts {#parts lede="Documents, tables, transactions, computed values, watching, and outside resources: the vocabulary of every factory."}
+
+A factory builds an object from a handful of parts, each declared with one call on `self`. The notes object grows to
+show all of them.
+
+**Documents** hold the object's data: `self.state(NotesDoc)` gives a handle whose `.value` is the current data. Data
+changes only in a **transaction**: `self.tx(fn, ctx)` runs `fn` with `tx`, and `await tx.draft(handle)` gives a
+mutable copy of the document's data; whatever you change on it is committed at once when `fn` returns, or not at all
+if it throws.
+
+```ts
+add: async ({ text }, ctx) => self.tx(async (tx) => {
+	const draft = await tx.draft(doc);          // the document's data, writable inside this transaction only
+	draft.items.push(text);                      // recorded as a change, committed when the function returns
+}, ctx),
+```
+
+Documents live in memory unless they are **persisted**: `defineState(..., { persist: true, checkpointWhen })` keeps
+one in the host's **store** (a SQLite file the app opens and gives to `createHost({ store })`), loaded when the
+object activates. For many records with queries, an object declares a **table**:
+
+```ts
+const NoteRows = defineTable("notes", {
+	version: 1,
+	columns: { id: str(), text: str(), at: int() },
+	key: ["id"],
+	indexes: { by_time: ["at"] },
+});
+
+host.serve(NoteStore, (_params, self) => {               // a local type with empty params: it may persist
+	const rows = self.table(NoteRows);                    // created (or migrated) when the object activates
+	const recent = query(NoteRows).orderBy((n) => n.at, "desc");
+	return {
+		add: async ({ text }, ctx) => self.tx(async (tx) => tx.put(rows, { id: uuid(), text, at: Date.now() }), ctx),
+		page: async ({ after }, ctx) => rows.page(recent, 50, ctx, { after }),   // 50 at a time, with a cursor
+	};
+});
+```
+
+Persisted data lives only in `local` objects with empty params (one per host and type), so its address never depends
+on who asked or with which params; an object with params (a view per project) reads from such a store. Writes go
+through the same transactions as documents: a note row and a document can change in one commit.
+
+A table has no watch of its own. To show rows live (the newest notes in a tab), the object declares a **live query**
+over its own table, with a limit:
+
+```ts
+const newest = self.query(rows, recent, 50);             // the 50 newest rows, a value like a document's
+return { newest, add, page };                            // a member: tabs watch it and get only the changes
+```
+
+Chord runs the query before the object goes live, and again in every commit of the object that writes `rows`, and
+sends what changed. Only the object's own tables: it is their only writer, so its commits are exactly when the rows
+can change, and a commit that writes no such table costs nothing. Each writing commit runs the query once more, at
+most the limit's rows: right for data people edit, wrong for a table written hundreds of times a second (there may be
+dragons; keep what the tab shows in a document the object writes with each change instead). The limit is required.
+
+A **derive** is a value computed from other values, recomputed whenever they change. It is how an object offers
+something it does not store:
+
+```ts
+const count = self.derive([doc], ([notes]) => notes.items.length);   // 0, 1, 2, … as notes are added
+return { list: doc, count, add };                                      // `count` can be a member like `list`
+```
+
+**Watching** is how anyone follows a value as it changes: a document handle, a derive, a reference's member. `watch`
+gives the current value, then one call per change:
+
+```ts
+const watch = await notes.count.watch(ctx);
+watch.start(async (call) => {
+	if (call.kind === "value") console.log("notes:", call.value);   // "failed" calls say a value cannot be computed now
+});
+```
+
+A **routine** is the object watching on its own behalf: `self.on(source, fn)` runs `fn` with each new value, for as
+long as the object lives (a reconciler: "whenever the notes change, rebuild the export file").
+
+A **native** is something outside Chord the object opens and must close: a file watcher, a database connection, a
+child process. `self.open(open, close)` opens it while the object activates and closes it when the object ends:
+
+```ts
+const inbox = self.open(async (ctx) => watchDirectory(inboxPath, ctx.abortSignal), (watcher) => watcher.close());
+self.onLive(async (ctx) => {                                  // a routine started once the object is live
+	for await (const file of inbox.value.files(ctx.abortSignal)) await importNote(file, ctx);
+});
+```
+
+Every live object restarts when its plugin changes; natives close (`reload`) and open again with the new code, since
+an open connection cannot be moved to new code. A first read of a table needs no native: declare it as a live query,
+not with `self.open`.
+
+**Await what you start in a root or a handler.** What is started with a context ends with it. Code outside objects
+gets its `ctx` from `host.root(fn, ctx)`, and that scope seals when `fn` returns; a handler's context ends when its
+caller cancels or its object ends. A change still waiting when its context ends is cancelled before it commits:
+
+```ts
+await server.root(async (ctx) => {
+	void notes.add({ text: "lost" }, ctx).catch(() => {});   // fn returns, the scope seals: the call's change is cancelled
+}, ctx);
+await server.root(async (ctx) => notes.add({ text: "kept" }, ctx), ctx);   // awaited: it commits
+```
+
+The cancelled change rejects, and since an empty `catch` would hide that it never happened, Chord also reports it
+through `onError` as `transaction_cancelled`, naming the object and, in its error, the scope that ended.
+
+# Several Hosts {#hosts lede="A server, a worker per project, browser tabs: how they find each other's objects."}
+
+Now give each project its own process. Declare the kinds of addressable host, and make notes a `remote` type that
+lives on its project's worker:
+
+```ts
+export const Server = hostKind("server");
+export const Project = hostKind("project", { id: str() });
+
+export const Notes = remote("notes", {
+	version: 1,
+	params: { project: str() },
+	hostAddress: ({ project }) => Project({ id: project }),   // where an object of these params lives
+	variants: { editor: { state: { list: NoteList }, methods: { add: method(obj({ text: str() })) } } },
+});
+```
+
+Two things are new. A `remote` type can be used from any host, and it has **variants**: different sets of members
+for different callers, chosen by the factory (an `editor` variant with `add`, a `reader` variant for guests without
+it). And `hostAddress` says where its objects live; it is the whole routing story.
+
+A tab asks for `Notes { project: "p1" }`. Its host computes the address,
+`Project(p1)`, and sends the request to its parent, the server. The server has a **route** for `Project`: it starts (or
+finds) the worker for `p1` and passes the request on. The worker serves `Notes`. The tab gets a reference whose state
+follows the worker's document, one frame per change.
+
+:::flow wide animate | A tab holds a project's notes: the server routes by address to the project's worker and relays, without reading the data.
+row "Clients" blue
+box tab1 "tab A" "holds Notes { project: p1 }"
+box tab2 "tab B" "holds Notes { project: p1 }"
+row "Server" accent
+box server "server" "route Project → worker"
+row "Workers" muted
+box w1 "worker p1" "serves Notes { p1 }"
+box w2 "worker p2" "serves Notes { p2 }"
+arrow tab1 -> server "hold"
+arrow tab2 -> server "hold"
+arrow server -> w1 "relay"
+:::
+
+Each host is created the same way, with what it is:
+
+```ts
+// server.ts
+const server = createHost<P>({ address: Server(), principal: { kind: "server" }, onError });
+
+// worker.ts (started by the server for one project)
+const worker = createHost<P>({ address: Project({ id }), principal: { kind: "worker", project: id }, onError });
+worker.connect(parentLink, { principal: { kind: "server" }, trusted: true }, ctx);
+
+// a browser tab: no address, it is a client
+const tab = createHost<P>({ onError });
+tab.connect(webSocketLink(new WebSocket("/chord")), { principal: { kind: "server" } }, ctx);
+```
+
+`P` is your app's type of **principal**, who is calling: an owner, a guest, the server, a worker. Links stamp it;
+a `remote` object is made per principal, so a guest can get a read-only variant of the same notes.
+
+## Who a reference acts as
+
+A reference acts as whoever made it. `host.get` and `self.get` in a `local` object act as the host; `self.get` in a
+`remote` object acts as that object's principal; **`ctx.get` in a method acts as the method's caller**. That is what
+lets a guest's call reach a worker as the guest and get the guest's variant, never more than the guest may see.
+
+It surprises one case: a server object that should act as itself towards a worker. The owner calls
+`Search.rebuildIndex`, which asks each project's worker to scan its files:
+
+```ts
+// server.ts: wrong, the worker sees the owner
+rebuildIndex: async ({ project }, ctx) => {
+	const scan = await ctx.get(IndexScan, { project });   // acts as ctx.principal: the owner, the method's caller
+	return scan.run(ctx);
+},
+
+// worker.ts: the factory serves only the server
+host.serve(IndexScan, (params, principal, self) => {
+	if (principal.kind !== "server") throw new Error("IndexScan serves the server only");   // refuses the owner
+	…
+});
+```
+
+The worker's factory gets `{ kind: "owner" }` and refuses. To act as the server, take the reference where the server
+is the maker: `self.get(IndexScan, { project })` in a `local` server object of its own (a dependency of that object,
+which acts as the host), or, in base code that has the host, a root of the server's host:
+
+```ts
+// base code: a root acts as the host (the server), not as the method's caller
+rebuildIndex: async ({ project }, ctx) =>
+	server.root(async (own) => (await own.get(IndexScan, { project })).run(own), ctx),
+```
+
+## Calls in progress
+
+There is no limit on calls in progress per link. A tab sending 200 calls at once over its socket gets all 200 run:
+at most N (256 by default, announced in the handshake) are in flight per origin, the rest wait in order in the link's
+call queue, none is refused for being too many. The bounds are that call window and the part limits on what arrives
+(sizes, not counts). An object that must limit work per caller does so in its methods, or runs the work as a job.
+
+:::note | The app kit does this wiring
+Starting workers, routing a host kind to them, the WebSocket entry and authentication are slice 10's components
+(`createWorkers`, `chord.http`). An app built with the app kit (`chord/app`, the last chapter) does not wire them:
+`startServer(...)` on the server and `startWorker(...)` in a worker's entry do.
+:::
+
+# Client Hosts {#clients lede="Browser tabs and terminal UIs are hosts too: what they can do, and what they cannot."}
+
+A browser tab and a terminal UI are hosts like the server, with one difference: they have **no address**. Nobody can
+send a request *to* a tab; a tab only connects to the server and asks for things. That is a deliberate rule: a tab
+runs on a device the server does not control, so nothing on the server ever waits for, or trusts, a tab's state.
+
+```ts
+// a browser tab (slice 11's page host will do this wiring for you)
+const tab = createHost<P>({ onError });                               // no address, no principal: a client
+tab.connect(webSocketLink(new WebSocket("/chord")), { principal: { kind: "server" } }, ctx);
+await tab.load([{ name: "@app/web", facet: webCore }, ...webFacets], ctx);
+
+const notes = tab.hold(Notes, { project: "p1" }, ctx);               // a reference at once, live soon
+(await notes.list.watch(ctx)).start(async (call) => {
+	if (call.kind === "value") render(call.value.items);              // every change, as it commits on the worker
+});
+await notes.add({ text: "from the tab" }, ctx);                        // a call: tab → server → worker
+```
+
+**Who the tab is** is not the tab's to say. The server authenticates the WebSocket when it connects (a cookie, the
+owner on loopback, a guest's share link) and stamps that principal on everything the tab asks for. The worker's
+`Notes` factory receives it and may give a guest a read-only variant. A tab cannot claim to be the owner.
+
+**What a tab serves** is only `local` types: state of this tab's UI, never shared. A draft that survives switching
+panels, a selection, a tab-local cache:
+
+```ts
+// plugins/notes/web.tsx: the web facet serves a local type, and contributes a panel
+export default defineFacet((host, self) => {
+	host.serve(NoteDraft, (_params, self) => ({ text: self.state(DraftDoc) }));   // lives in this tab only
+	self.contribute(Panels, { title: "Notes", Component: NotesPanel });
+});
+```
+
+**When the connection drops** (a phone in a tunnel, a server restart), the tab keeps its references. Their values
+stay readable, their `state` says `loading`, calls made meanwhile wait; on reconnect every reference is held again and
+gets the current value in one frame. The UI shows a banner from `ref.state`, nothing more.
+
+**A terminal UI** is the same in Node: a client host connected to the server over a WebSocket, loading the plugins'
+`tui` facets, rendering with whatever terminal library the app chose. **What a client never does**: serve a `remote`
+type, be routed to, or keep data others rely on. Data that must outlive a tab belongs in an object on the server or a
+worker.
+
+**Text in the viewer's language** is a client's job too, because two people looking at the same object may read
+different languages. A plugin writes its texts once, in a shared `messages.ts`; a client renders them in its host's
+language (the user's pick, else the device's), and objects store messages as data, never sentences (design §23,
+"Messages and languages"):
+
+```ts
+// plugins/notes/messages.ts: the first catalog types the others
+export const messages = defineMessages("notes", { en: { empty: "No notes yet" }, de: { empty: "Noch keine Notizen" } });
+// plugins/notes/web.tsx: the facet contributes its catalogs; a component renders in the page's language
+self.contribute(Translations, messages.translations);
+const { t } = useMessages(messages);                       // re-renders when the user picks another language
+// plugins/notes/worker.ts: a notice as data; every client renders it with t.render(notice)
+draft.notice = messages.message("empty");
+```
+
+## Optimistic UI
+
+A user renames a session. The call goes from the tab through the server to the session's worker, which renames it and
+reports the new title to the server's index of sessions, then answers. That round trip takes a moment, and the title
+should change at once. React's `useOptimistic` shows a value while a transition runs, and Chord's references fit it:
+
+```tsx
+// plugins/sessions/web.tsx
+function SessionName({ id }: { id: string }) {
+	const sessions = useHold(Sessions, {});                       // the server's index, which every list shows
+	const session = useHold(SessionTitle, { id });                // on the session's worker
+	const title = useWatch(sessions?.titles)?.[id] ?? "";
+	const [shown, showOptimistic] = useOptimistic(title);
+	const rename = (next: string) =>
+		startTransition(async () => {
+			showOptimistic(next);                                    // drawn at once
+			await session?.rename(next, BACKGROUND_CONTEXT);         // settles once the index has `next`
+		});
+	return <TitleField value={shown} onRename={rename} />;
+}
+```
+
+When the transition ends, React drops the optimistic value and draws `title` again. That is only right if `title` is
+already the new name by then. **Chord guarantees it:** a call settles in the page only after every change its answering
+host committed before answering is applied there, and so does every change a host that relays the answer committed
+before it forwarded it. Here the worker's own changes travel before its answer, and the server sends its index change
+for this tab before it forwards the worker's answer, even on a slow connection whose window of unacknowledged state is
+full (design §3). Without that, the answer could overtake the index change and the old title flickered back.
+
+**What it does not cover:**
+
+- Changes committed after the answer: a method that starts work and returns before it lands (a `void` call, a job, a
+  routine) answers first; the optimistic value goes and the old one shows until the change arrives.
+- Changes on a host that neither answers nor relays the answer. A server method that calls a worker and then answers
+  the tab orders only the server's own changes before its answer; what the worker changed for the tab travels on its
+  own and may come later.
+
+So the rule for a method that should feel instant: it awaits its own changes, the pushes to other hosts included (the
+worker's `rename` awaits its report to the index), and keeps them on the host that answers or relays the answer.
+
+A terminal UI does the same with its component scope: `scope.optimistic(read, reduce?)` wraps a reader and returns
+it with `add(action, call)` and `pending()`, as React's `useOptimistic`: while calls are in flight the reader shows
+`reduce(current, action)` over each action, in order (without a reducer the last action is the value), until every
+call added settles. `add` returns the call; a rejection is the caller's to handle.
+
+```ts
+const titles = scope.watch(sessions.titles);
+const [title, add] = scope.optimistic(() => titles()?.[id]);
+await add(next, session.rename(next, ctx));               // title() is `next` at once, the real one when it settles
+
+const [rows, change] = scope.optimistic(() => list() ?? [], (rows, id: string) => rows.filter((row) => row.id !== id));
+change(id, store.remove({ id }, ctx)).catch(fail);        // gone at once; back with the error if refused
+```
+
+`test/examples/63-optimistic-answers.ts` runs this with a stalled terminal client and prints what each redraw showed.
+
+# Plugins {#plugins lede="Move the code into a directory that can be added, edited and removed while the app runs."}
+
+So far the facets were part of the app's own code. A **plugin** is the same code in its own directory:
+
+```text
+plugins/notes/
+  package.json        { "name": "@app/notes" }
+  contract.ts         the Notes contract (other plugins import it)
+  worker.ts           the facet for workers: serves Notes
+  server.ts           the facet for the server: an export route
+  web.tsx             the facet for browser tabs: a notes panel
+```
+
+The plugin's name is its `package.json` name. Each file named after a **host kind** is that kind's facet, its
+default export a `defineFacet(...)`. A plugin has only the files it needs: a plugin that only adds a route has a
+`server.ts` and nothing else.
+
+```ts
+// plugins/notes/worker.ts
+import { defineFacet } from "@app/api/v1";
+import { Notes } from "./contract.ts";
+
+export default defineFacet((host) => {
+	host.serve(Notes, ({ project }, principal, self) => {
+		const doc = self.state(NotesDoc);
+		return { variant: "editor", members: { list: doc, add: async ({ text }, ctx) => /* … */ } };
+	});
+});
+```
+
+`@app/api/v1` is your app's **API**, version 1: the part of its base code plugins import, as a host package (the
+plugin's build leaves it out; every host passes its own copy in). It holds what plugins share and never reloads:
+Chord's builders re-exported (`local`, `remote`, `obj`, `str`, ...), host kinds, the principal type, a `defineFacet`
+bound to it. A plugin never imports Chord itself; the version in the path says what it was written against.
+
+# Loading Plugins {#loading lede="Two steps in two places: building a plugin into a script happens once, on the server; evaluating it happens in every process that runs it."}
+
+A plugin is source code on the server's disk: TypeScript files that import each other, import other plugins'
+contracts, import npm packages, and import things the app itself provides. None of the processes that run the plugin
+can use those files as they are. A browser tab has no file system and no TypeScript; a worker could read the files,
+but then every worker would compile every plugin again, and two workers started a minute apart could see two different
+versions. So loading a plugin is two separate steps:
+
+1. **Build**: turn each plugin facet (`notes/worker.ts`, `notes/web.tsx`) into one self-contained **script**. This
+   happens once per edit, on the server, for every host kind.
+2. **Evaluate**: run a script inside one process, which gives back the facet, ready for `host.load`. This happens in
+   every process that hosts that kind: the server for its own facets, each worker for the worker facets, each tab for
+   the web facets.
+
+The two steps need different things, and that is why the API has two calls.
+
+## Host packages: what a script leaves out
+
+Look at what `notes/worker.ts` imports:
+
+```ts
+import { defineFacet, obj, remote, Session, str } from "@app/api/v1";   // the app's API: its own part and Chord's
+import { Notes } from "./contract.ts";                                  // the plugin's own file
+import slugify from "slugify";                                          // an npm package in its dependencies
+```
+
+The last two go into the script: the plugin's own files and its npm dependencies are copied in. The first must not.
+If the script carried its own copy of the API, and with it of Chord, the worker would run two Chords: the plugin's
+`ChordError` would not be the worker's `ChordError`, and the plugin's `defineFacet` would make a facet the worker's host
+does not recognize. The plugin must see the very `Session` host kind and the very `Panels` registry the process
+already has, not a copy.
+
+Packages the process already has, and that every plugin must share, are its **host packages**. A script leaves them
+out and asks for them by name when it runs. Building therefore needs only their **names**: "do not copy `@app/api/v1`
+into this script".
+
+## Building: `createPlugins`, on the server
+
+```ts
+const plugins = createPlugins({
+	roots: [{ path: "./plugins", required: true }],      // where the plugin directories are
+	api: { name: "@app/api", versions: ["v1"] },          // the app's API and the versions it provides
+	kinds: {
+		server: { platform: "node", hostPackages: ["@app/api/v1", "@app/api/v1/server"] },
+		worker: { platform: "node", hostPackages: ["@app/api/v1", "@app/api/v1/worker"] },
+		web: { platform: "browser", hostPackages: ["@app/api/v1", "@app/api/v1/web", "react", "react/jsx-runtime"] },
+	},
+	onError,
+}, ctx);
+```
+
+`createPlugins` is the builder, and it builds for every kind, because only the server has the sources. For each kind
+it needs two facts. The **platform** says where the scripts run: a `node` script may import `node:fs`, a `browser`
+script may import a stylesheet but not `node:fs`. The **host package names** say what to leave out; they differ per
+kind, because a tab also shares React with its plugins and a worker does not, and the API's per-kind modules
+(`/v1/web`) belong to their kind only. With `api` set, the build checks every import of the API: a version the app
+does not list, another kind's module, two versions in one facet, or Chord imported directly is a build error naming
+the file and line. Nothing here runs a plugin.
+
+## Evaluating: `plugins.load`, in the process that hosts
+
+Evaluating is where the names become things. When the script runs and asks for `@app/api/v1`, someone has to hand
+it the actual module, the one this process imported when it started. Only the process itself has it:
+
+```ts
+// server.ts
+import * as api from "./api/v1/index.ts";                 // the app's API, the module plugins import as "@app/api/v1"
+import * as apiServer from "./api/v1/server.ts";
+import { serverFacet } from "./core.ts";
+
+const report = await plugins.load(server, {
+	kind: "server",                                          // evaluate the server kind's scripts
+	modules: { "@app/api/v1": api, "@app/api/v1/server": apiServer },   // this process's own instances
+	core: [{ name: "@app/core", facet: serverFacet }],       // base-code facets, loaded beside the plugins
+}, ctx);
+```
+
+`modules` is this process's answer to every host package name. The server passes its own; a worker passes its own in
+`workerMain`; a page passes its own in `startPage`. Each process has different instances, which is exactly the point:
+inside each process, plugins share that process's Chord and base code.
+
+`core` is the app's base code in facet form. It is a facet like a plugin's, but it is not a plugin: it is made in the
+process's own code, often from values only this process has (`core.workerFacet(start)` closes over a worker's start
+data and store), and it never reloads, because it defines what all plugins share. Passing it here loads it together
+with the plugins, so they are published in one step.
+
+## Why `plugins.load(host)`, not `host.load`
+
+A host has its own `load`, and `plugins.load` calls it. The host's `load` takes facets that already exist: functions
+in memory. It knows nothing about directories, builds, scripts or modules, on purpose: the same host runs in a test
+with facets imported directly, or in a Cloudflare Durable Object where plugins are bundled at deploy time and nothing
+is built or evaluated at runtime.
+
+The plugins component is the part that knows about directories. It finds the plugins, builds them, evaluates them
+with the process's modules, and then calls `host.load` with the result. It also remembers, per host, which facet each
+plugin runs, so that a later reload can hand the host its complete new plugin set, with unchanged plugins as the very
+same objects. That memory is why the host is passed to it: `plugins.load(server, …)` on the server,
+`plugins.load(worker, …)` in a worker (where `workerMain` gives it a `plugins` that only evaluates), the same call
+in every process.
+
+:::flow wide | Building on the server needs names; evaluating in each process needs that process's modules.
+row "Server: build (once per edit)" accent
+box src "plugin sources" "`notes/worker.ts`, imports `@app/api/v1`" muted
+box build "createPlugins" "copies own files and npm deps; leaves host packages out" accent
+box script "worker script" "`require(\"@app/api/v1\")` left as a name"
+row "Each worker: evaluate" blue
+box mods "the worker's modules" "its own `@app/api/v1`, its own Chord" muted
+box load "plugins.load(worker, …)" "runs the script, answers each name" blue
+box facet "the facet" "uses the worker's `Session`, the worker's `defineFacet`"
+arrow src -> build
+arrow build -> script
+arrow script -> load "shipped"
+arrow mods -> load
+arrow load -> facet
+:::
+
+## What happens, step by step
+
+:::steps | `plugins.load(server, { kind: "server", … })`
++++ Discover
+The component lists `./plugins` and reads each `package.json`. Its `name` is the plugin's name; the files named after
+a kind are its facets. A directory without a `package.json`, or with two `server` files, is reported, not loaded. Files
+at the root's top named `<name>.<kind>.ts` (`hello.server.ts`) are single-file plugins, grouped by name.
++++ Build
+For each plugin with a `server` facet it builds one script, if no current one exists. A syntax error or an import the
+rules do not allow (a path into base code, a package not in the plugin's dependencies) is a failed build with the file
+and line, never a crash.
++++ Evaluate
+The script runs. Each host package name it asks for is answered from `modules`; anything else it may not have. The
+script's default export must be a facet.
++++ Load
+`host.load` runs the setups of `core` and of every plugin facet and publishes them together. A plugin whose build,
+evaluation or setup failed is left out and listed in `report.failed` with the reason; the others load. Objects that
+need it wait until a later edit loads it.
+:::
+
+Only the server builds. Workers and clients (browser tabs, terminal UIs) only evaluate: the server builds their kinds
+too, a worker gets its scripts in its start message, a tab or a TUI gets them from the server over HTTP, and each
+evaluates them with its own modules (a worker's from `workerMain`, a page's from its base bundle).
+
+# Plugins Using Plugins {#together lede="Two ways one plugin uses another, and the one it may not."}
+
+A search plugin wants to search the notes. It **imports the contract** and asks for the object:
+
+```ts
+// plugins/search/worker.ts
+import { Notes } from "../notes/contract.ts";   // a plugin of the same root, by relative path: copied into search's script
+
+host.serve(Search, ({ project }, principal, self) => {
+	const notes = self.get(Notes, { project });   // a dependency: Search goes live once Notes is
+	const index = self.derive([notes.list], ([list]) => buildIndex(list.items));
+	return { variant: "main", members: { find: async ({ q }) => lookup(index.value, q) } };
+});
+```
+
+Which file a plugin imports decides which version of the contract it claims, so the rule is: **a plugin carries the
+contract it was written against.** Two cases:
+
+- **Plugins that change together** (the app's own, in its repository; a user's, in one root) import each other by
+  relative path, `../notes/contract.ts`: the same commit holds both sides. The file is copied into the importer's
+  script, so only contracts and other side-effect-free files belong there (a copied file may import only the API and
+  files of its own plugin). A relative path leaving the root (into base code, into another root) is a build error.
+- **Plugins from another repository** take contracts as a dependency at a fixed version, by package name:
+  `@bob/notes` (its `contract.ts`, through the package's `exports`), `@bob/notes/web` (its `contract.web.tsx`), pinned
+  in `package.json` by an npm version or a git ref (`"@bob/notes": "github:bob/notes#<commit>"`). The build inlines
+  the installed version: when Bob's notes move to contract version 2, a consumer built against version 1 keeps
+  claiming version 1, and the provider serves it through `accepts` or the consumer waits "contract mismatch", visible,
+  never silently wrong. A plugin inside a repository holding several (which lists them in its own `package.json`,
+  `"chord": { "plugins": ["./notes", "./search"] }`) is a dependency on the whole repository, imported by path into it:
+  `@bob/plugins/notes/contract.ts`.
+
+A contract file may be for one kind: `contract.web.tsx` (React components in a type, a panel's registry token) is a
+**web file**. Importing it, directly or through other files, from a facet of another kind is a build error naming
+the chain (`server.ts → view.ts → ../notes/contract.web.tsx`). The shared `contract.ts` mentions native things only
+through `import type`.
+
+`self.get` in a factory declares a dependency: Chord makes `Search` live only once `Notes` is, and if the notes
+plugin is missing, `Search` waits with a clear reason ("waiting for notes: not served here") instead of failing.
+
+The other way is a **registry**: an extension point one plugin defines and others contribute to. The app's API
+defines `Panels` in its web module, and every plugin with a UI contributes one:
+
+```tsx
+// plugins/notes/web.tsx
+import { Panels } from "@app/api/v1/web";
+export default defineFacet((host, self) => self.contribute(Panels, { title: "Notes", Component: NotesPanel }));
+```
+
+What a plugin may not do is reach into another's data. Search never reads notes' documents; it uses the `Notes`
+object's state. That rule is what lets the notes plugin change its storage without breaking search.
+
+# Changing a Plugin {#reload lede="Edit, build, roll out: how new code takes over while every tab stays connected."}
+
+You change the notes plugin: notes now have a timestamp. The watcher sees the saved file and marks the plugin dirty.
+You (or an agent) build and roll out:
+
+```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);
+```
+
+The rollout goes host by host, server first, then every running worker. On each host Chord compares the new plugin
+set with the loaded one, runs the new factories against a recording `self` to see what each object would declare, and
+then gives every object of the changed plugin its fate:
+
+| The object | What happens |
+| --- | --- |
+| live | **restarted**: running calls, and the calls they make with their `ctx`, finish on the old code; new calls wait for the new code; same documents; natives close and reopen |
+| not live (failed, parked) | **retried** on the new code |
+| its type was removed | **ended**; its users wait until something serves it again |
+
+The tab's reference stays live while the old code drains, shows `loading` for a moment, then follows the new object
+with one frame of difference. Nothing reconnects. If the edit
+is broken (a syntax error, a factory that throws), that plugin keeps its old code on that host and the report says why;
+every other plugin of the rollout applies.
+
+A tab applies a new web script the same way, without reloading the page, and the UI keeps what lives outside the
+changed plugin. The changed plugin's own components are new functions, so React mounts them anew and their `useState`
+starts over. What must survive the update (a half-typed note, a scroll position) goes into **page state**, kept by the
+tab's host under a key: `usePageState(key, initial)` from `chord/react` instead of `useState`, and
+`scope.pageState(key, initial)` on a terminal's `TuiScope` (design §21, "UI on client hosts").
+
+:::note | Versions
+A change to a contract (a new field in `Notes`'s state) gets a new `version`. A tab built with the old contract keeps
+working if the provider maps the old version (`accepts`); otherwise it waits with "version mismatch" until it reloads.
+:::
+
+# Base Code and Plugins {#base lede="What goes into the app itself, what goes into plugins, and how an app ships plugins of its own."}
+
+Every app has two kinds of code, and the line between them decides what can change while the app runs.
+
+**Base code** is the app's own program: `src/`, started by `node server.ts`. It shrinks to three things: the **API**
+(the versioned modules plugins import), the **bootstrap** (creating hosts, opening the store, components such as
+`createHttp` and `createWorkers`) and one small **start-data facet** serving process values (start data, the opened
+store) as core objects. Base code changes only with a restart: if it reloaded, the process would hold two `Panels`
+registries, and old and new plugins would no longer meet.
+
+**Plugins** are everything else: notes, search, export, a terminal, the harness, the providers of the app's core
+registries. They reload on an edit, a broken one is left out alone, and an agent can write one while the app runs.
+
+## The API, by version and by kind
+
+Plugins import their host only through the API, a version in the path:
+
+```ts
+// src/api/v1/index.ts: "@app/api/v1", for every kind
+export { defineRegistry, local, obj, remote, str } from "@earendil-works/chord";   // the Chord surface the app supports
+export { defineFacet, Project, Server } from "../../core.ts";                           // bound to the app's principal
+// src/api/v1/web.ts: "@app/api/v1/web", for pages only
+export const Panels = defineRegistry<Panel, readonly Panel[]>("app.panels", { version: 1 });
+```
+
+The app lists the versions it provides, newest first (`api: { name: "@app/api", versions: ["v2", "v1"] }`), and each
+kind's modules in `kinds.<kind>.hostPackages`. When the app changes its API in a way that breaks plugins, it adds
+`/v2` and keeps `/v1` as a thin layer over it for a while; once `/v1` goes, a plugin importing it fails to build with
+"@app/api/v1 is not available: this app provides v2", the plugin alone, the message saying what to change. One facet
+uses one version. Contracts the app promises others are re-exported in the API (`export { Notes } from
+"../../plugins/notes/contract.ts"`), so a plugin built against `/v1` keeps v1's contract files.
+
+## Plugins the app ships
+
+An app comes with plugins of its own. They follow the same rules as anyone's, in a root inside the app, next to the
+root where users and agents add theirs:
+
+```ts
+const plugins = createPlugins({
+	roots: [{ path: "./plugins", required: true }, join(dataDir, "plugins")],   // the app's own, then the user's
+	api: { name: "@app/api", versions: ["v1"] },
+	kinds,
+	onError,
+}, ctx);
+```
+
+They are built at startup like any plugin (a quarter of a second for twenty), reload like any plugin, and are left out
+alone when broken at a reload. The app's root is **required**: a plugin of it failing at startup makes
+`plugins.load` reject with a `PluginError` naming it (after the load settled), so the app stops instead of running
+without its core. A failure in the user's root is reported and the app runs on. If two roots have a plugin with the
+same name, the first root wins, and the other is reported.
+
+## Small plugins, installed plugins, tested plugins
+
+- **A single file** at a root's top is a plugin: `plugins/hello.server.ts` and `plugins/hello.web.tsx` are the plugin
+  `hello` with two facets. It has no `package.json` and imports only the API; when it needs a second file or a
+  package, it becomes the directory `hello/`, which a reload treats as the same plugin.
+- **Installing** from git or npm: `plugins.installPlugin({ git: url, ref }, root, ctx)` clones the ref (a branch, tag
+  or commit) into the root, `{ npm: name, version }` extracts the package; then its dependencies are installed. Removal
+  is deleting the directory.
+- **Testing** a plugin alone: `testPlugin("./plugins/stats", { kind: "worker", api, modules, stubs }, ctx)` builds it
+  as production does, loads it on an in-memory host beside stub facets serving what it uses, collects what it
+  contributes to registries nobody serves, and lists the contracts it waits for (`docs/plugin-authoring.md`).
+
+# The App Kit {#kit lede="startServer and startWorker: the hosts, stores, sign-in, files and plugin roots every app needs, so an app is its API, its plugins and a start script."}
+
+The chapters so far wired an app by hand: a store, a host, `createHttp`, `createWorkers`, `createPlugins`, an
+authenticator, a worker entry connecting to its parent. Every app needs the same wiring, and most of it has one right
+answer. The **app kit** (`chord/app`) is that answer, opinionated on purpose: one data directory layout, one way
+to sign in, one place for files.
+
+## A whole app
+
+The notes app of example 53 is four files of base code and two plugins:
+
+```ts
+// start.ts
+const app = await startServer<NotesPrincipal>({
+	name: "notes",                                  // the data directory: ~/.notes unless dataDir says otherwise
+	root: "./plugins",                              // the app's own plugins: a required root
+	api: { name: "@notes/app", versions: ["v1"], modules: { "@notes/app/v1": v1, "@notes/app/v1/server": v1server } },
+	kinds: { server: { platform: "node" }, worker: { platform: "node" } },
+	principal: {
+		server: { kind: "server" },
+		worker: (address) => ({ kind: "worker", project: address.key }),
+		owner: { kind: "owner" },                   // whom the owner link, the token file and pairing sign in
+	},
+	workers: [{
+		kind: Project,                              // one worker per project
+		entry: "./worker.ts",
+		start: (address) => ({ project: address.key }),
+		authorize: (principal) => principal.kind === "owner" || principal.kind === "server",
+	}],
+	onError: (error) => log(error),
+}, ctx);
+console.log(`Open ${app.ownerLink()}`);
+
+// worker.ts
+startWorker({ api: API, kinds: KINDS, onError: (error) => log(error) });
+```
+
+`startServer` creates the data directory (`server/store.sqlite`, `workers/<kind>/<address>/`, `plugins/`, `logs/`,
+`owner-token`), opens the server's store, creates the server host, HTTP, a workers component per worker kind and the
+plugins component over two roots: the app's `plugins/` and the user's `<dataDir>/plugins/`. Then it loads the server's
+plugins with the kit's own facets beside them and resolves. `startWorker` does the worker's half: the project's
+directory and store, the host at the project's address, the link to the server first, the worker's plugins.
+
+## What plugins get from the kit
+
+Plugins still import only the app's API; the API re-exports the kit's objects it offers:
+
+- `AppInfo` on the server (data directory, app name, API version, owner) and `WorkerInfo` on workers (the address and
+  the start data `start(address)` made): the **start-data objects**. Process values reach plugins only through them.
+- `Files`, one per host: `put` for small files, `begin`, `append` and `finish` for large ones, ranged `read`, `remove`
+  and a watchable `list`, stored in the host's directory with caps per host.
+- `Sessions` on the server: `issue`, `revoke`, `list`.
+
+This finishes what the previous chapter started. Base code is the API, the start script and the worker's entry. The
+providers of the app's own registries live in its required root: example 53's API declares a `Sections` registry, and
+its home plugin serves it and reads `AppInfo`, so it reloads like any other plugin.
+
+## Who may come in
+
+HTTP **denies by default**: a request without a principal gets 401 before any plugin code runs, unless the route says
+`public: true`. Someone gets a principal through a **session**: a random token, kept in the store only as a hash, sent
+as a signed cookie by a browser or as `Authorization: Bearer` by a command-line client.
+
+The first session is the owner's, the principal the app names in `principal.owner` (a variant of its own, as here, or
+one of its users). At each start the kit makes a one-time **owner link**,
+`http://127.0.0.1:8788/_chord/owner#<token>`, valid ten minutes; the start script prints it. The token is in the
+fragment, which browsers never send, so it never reaches a log: the page posts it, the kit consumes it and sets the
+owner's cookie. A command-line client on the same machine reads `<dataDir>/owner-token` (mode 0600). One on another
+machine **pairs**: it asks for a code, the owner approves the code in a signed-in browser, and the client's next poll
+returns its token (example 54).
+
+Users other than the owner come from optional plugins the app adds: `defineUsers(profile)` for accounts,
+`inviteFacet()` for invite links, `ephemeralLoginFacet()` for "pick a name and you're in".
+
+## Applying changes, moving projects
+
+The kit never reloads by itself. An edit or an install marks plugins dirty; `app.plugins.state` drives the app's
+"apply changes" button, and `app.applyChanges(ctx)` builds and rolls out to the server, then the workers.
+
+A project's data is what its worker created: its store and its files. `app.exportData(Project({ id }), path, ctx)`
+writes them as one archive (a manifest, the store's export, the files) and stops nothing: a running worker writes its
+own store at one consistent point. `app.importData(path, Project({ id: "copy" }), ctx)` makes a new project from it and
+refuses one that already has data (example 55).
+
+# Seeing a Request Across Hosts {#telemetry lede="One trace from a click in a client through the server's relay into a worker's method: adapters, carriers and spans."}
+
+A tab calls `notes.add(…)`. The call leaves the tab, the server relays it, the project's worker runs the method, the
+method commits. When it is slow, where did the time go? Each host is a different process, so no single log has the
+answer. Chord's telemetry makes the four steps one **trace**: a tree of **spans** (named, timed pieces of work), each
+host recording its own with its own **adapter**, joined by **carriers** (a few strings naming the caller's span) that
+ride on the wire with every `hold` and `call`.
+
+Give the server a store and the kit does the rest. The SQLite store (`@earendil-works/chord/telemetry-sqlite`)
+records settled spans and metrics in one file in the data directory, and the server is its only writer: every worker
+records in memory and sends its spans and metrics to the server once a second over its link, and a page that records
+(`startPage({ telemetry: true })`) sends its own every few seconds and when hidden (example 62):
+
+```ts
+// start.ts: the server, its store, and whom spans were for (default: the principal's key)
+const telemetry = await createSqliteTelemetry(await openNodeSqliteDatabase(join(dataDir, "telemetry.sqlite")));
+await startServer({ ...options, telemetry, principalAttributes: (p) => ({ "chord.principal": p.kind }) }, ctx);
+// worker.ts: nothing about telemetry (its own `principalAttributes`, if any)
+startWorker({ api, kinds, onError });
+// the web entry: the page records
+startPage({ ...options, telemetry: true });
+```
+
+A page is untrusted: the server checks each batch's every field (sizes, no control characters, ids printable ASCII),
+keeps only spans under the page's own ids, caps them per page and minute, marks them `chord.host: browser` and stamps
+them with the principal of their link. A click is a trace of its own with `host.root(fn, ctx, { trace: { name } })`.
+
+Nothing else changes in plugin code. A method's `ctx.telemetry` is its `chord.method` span, so whatever it calls or
+commits is parented under it, on its host or the next one. `ctx.trace(name, attributes, fn)` adds a span of your own:
+
+```ts
+add: async (n, ctx) => {
+	await ctx.trace("tally.check", { n }, async () => {
+		if (!Number.isSafeInteger(n) || n <= 0) throw new Error("add a positive count");
+	});
+	return store.add(n, ctx);
+},
+```
+
+The store renders the click's trace across the three hosts (the client's spans, the server's relay, the worker's
+methods and the commit, an event of the method that made it); every span of Chord names the host that recorded it
+(`chord.host`: its address key, `client` without an address), and method and call spans whom they were for
+(`chord.principal`, the host's `principalAttributes` hook):
+
+```
+tally.click
+  chord.hold chord.host="client" type="tally.counter" object="tally.counter(t1)" address.kind="tally" outcome="bound"
+    chord.relay chord.host="server" type="tally.counter" member="hold" upstream.kind="tally" outcome="ok"
+      → link to chord.resolve
+  chord.call chord.host="client" type="tally.counter" member="add" object="tally.counter(t1)" address.kind="tally" outcome="ok"
+    chord.relay chord.host="server" type="tally.counter" member="#0" upstream.kind="tally" outcome="ok"
+      chord.method chord.host="tally|t1" type="tally.counter" member="add" object="tally.counter(t1)" principal.kind="owner" chord.principal="{\"kind\":\"owner\"}" outcome="ok"
+        tally.check chord.host="tally|t1" n=3
+        chord.method chord.host="tally|t1" type="tally.store" member="add" object="tally.store" principal.kind="worker" chord.principal="{\"kind\":\"worker\",\"tally\":\"tally|t1\"}" outcome="ok"
+          · chord.commit documents=1 ops=1 rows=0 duration=1.9
+```
+
+Work shared by several requests is its own trace, linked rather than nested: the worker's start (`chord.resolve`),
+an object's activation (`chord.activate`, linked to whoever asked first). Routines and job phases are roots too; a job's
+`run` and `finish` stay under the carrier its start stored, even when a restarted worker resumes the run. Metrics
+(`chord.link.bytes`, `chord.commit.duration`, `chord.calls.in_flight`, ...) are aggregated per 10 s; ids are never their
+attributes. Without an adapter (the default), Chord starts no span and sends no carrier: a call costs what it did before.
+A script or a viewer reads the file with `openTelemetryStore(path)` (`@earendil-works/chord/telemetry-sqlite/node`),
+which opens it read-only and offers only the read interface (`findTraces`, `getTrace`, `findMetrics`).
+
+# Reference {.appendix}
+
+| Call | What it does |
+| --- | --- |
+| `createHost<P>({ address?, principal?, store?, onError })` | a host: addressable with an address, else a client |
+| `host.load([{ name, facet }], ctx)` / `host.reload(...)` | publish facets / apply a new plugin set |
+| `host.get(Type, params, ctx)` / `host.hold(...)` | a live reference / a reference at once that follows its object |
+| `local(name, { version, params, members })` / `remote(name, { version, params, hostAddress, variants })` | contracts |
+| `defineFacet((host, self) => …)`, `host.serve(Type, factory)`, `self.contribute(R, value)` | a facet |
+| factory `self`: `state`, `derive`, `get`, `registry`, `open`, `on`, `onLive`, `job`, `tx` | an object's parts |
+| `createPlugins({ roots, api, kinds, onError }, ctx)` | the plugins component |
+| `plugins.load(host, { kind, core, modules }, ctx)`, `build(names)`, `rollout(steps, built)` | load, build, roll out |
+| `plugins.installPlugin(source, root, ctx)`, `testPlugin(dir, options, ctx)` | install a plugin, test one alone |
+| `hostKind(name, params?)`, `Kind(params)` | host kinds and addresses |
+| `startServer<P>({ name, dataDir?, root?, listen?, api, kinds, principal, workers?, files?, onError }, ctx)` | an app's server, with the kit |
+| `startWorker({ api, kinds, busy?, onError })` | a worker's entry, with the kit |
+| `app.ownerLink()`, `app.applyChanges(ctx)`, `app.plugins.install(source, ctx)` | sign in, apply changes, install |
+| `app.exportData(address, path, ctx)`, `app.importData(path, address, ctx)` | move a worker's data |
+| `AppInfo`, `WorkerInfo`, `Files`, `Sessions` | the kit's objects plugins get |