@earendil-works/chord 1.5.0 → 1.5.1

package/docs/tutorial.md

@@ -1,932 +0,0 @@
-# Build a shared todo list with Chord
-
-## 1. What problem does Chord solve?
-
-A todo list has data, operations on that data, and several people looking at it.
-You could hand-write object creation, subscription cleanup, messages between
-processes, and code replacement. Chord connects these pieces for you.
-
-A **host** is the runtime that owns objects. An **object** combines state with
-methods at an address, such as “the family todo list.” A **reference** is a caller's
-reference to that object, not the object itself. Several references can reach the
-same object. References can also reach another host over a connection.
-
-```text
-browser host                         server host
-ref + subscribed rows -- link --> Todos view (owner or guest)
-                                           |
-                                        ref
-                                           v
-                                   TodoStore: rows + methods
-```
-
-We will start inside one host, add observable state, then share it with a
-browser. Finally we will add background work, plugins, and hot reload.
-**Live state** means subscribers receive new values when data changes, without
-asking for it again.
-
-<!-- example:01 -->
-```ts
-const host = createHost({ self: "server", name: "todo-server" });
-assert.equal(host.name, "todo-server");
-await host.close();
-```
-
-The assertion passes: the host's name is `todo-server`. Creating a host does
-not create a todo object, start a server socket, or persist data. `close()`
-shuts down its objects and connections.
-
-> **Tip:** These are executable TypeScript examples, using assertions to show
-> results. Shared imports are at the end. Later sections reuse earlier contracts
-> and functions, but each section's test starts with fresh hosts. Test-only
-> cleanup closes hosts even when an assertion fails; snippets omit that cleanup.
-
-## 2. Your first object
-
-Before callers can use an object, they need to agree on its name and members.
-That agreement is a **contract**: a runtime value that also gives TypeScript its
-types. A **schema** describes a value's shape: plain JSON Schema, which we write
-with the builders of `@earendil-works/pi-schema` (`obj`, `str`, `num`, ...;
-`{ open: true }` lets an object carry fields it does not name).
-`method(args, result)` declares a method by its argument and result schemas:
-`method()` takes no arguments and returns nothing, and
-`method(undefined, str())`, used below, takes no arguments and returns a string.
-
-Start with a label for a named list. `local` means only code inside this host
-can reach it. The input `{ list: "family" }` identifies which list we want;
-it is not an argument to `label`.
-
-<!-- example:02-contract -->
-```ts
-const TodoLabel = local("tutorial.todos", {
-	version: 1,
-	input: obj({ list: str() }, { open: true }),
-	members: { label: method(undefined, str()) },
-});
-```
-
-A **factory** is a synchronous function that creates the object's implementation:
-the methods and state callers will see. `serve` registers a contract and its
-factory. Registration alone does not activate this lazy object; the first
-`get` does.
-
-A **root** is one short tree of calls, such as the work for a button click.
-`host.root` starts it. Its **context**, called `ctx`, carries cancellation,
-caller identity, and the code version for nested calls. Pass it to methods you
-call from that root.
-
-<!-- example:02-call -->
-```ts
-const host = createHost({ self: "server" });
-host.serve(TodoLabel, ({ list }) => ({ label: () => `Todos for ${list}` }));
-const result = await host.root(async (ctx) => {
-	const todos = await ctx.get(TodoLabel, { list: "family" });
-	return todos.label(ctx);
-});
-assert.equal(result, "Todos for family");
-```
-
-The result is `"Todos for family"`. `await ctx.get` resolves once the object is
-live (and, as we will see, has its state). The reference acquired through
-`ctx.get` is released when this root ends. We never receive the factory's
-returned object directly. A standalone call without `ctx`, such as
-`todos.label()`, starts its own root. A method without arguments takes only
-the context: `todos.label(ctx)`; its implementation is `(ctx) => …`. Inside a root or method, pass the
-existing `ctx` so nested calls stay in the same call tree.
-
-The factory may also receive `principal` (who is asking) and `self` (the
-object's declaration API). We did not need them yet.
-
-> **Why:** The reference separates callers from implementations. Later, replacing
-> code will not require replacing every caller's reference.
-
-## 3. Give the list live state
-
-A label is not a todo list. We need rows that can change, and a count that always
-agrees with them. A **cell** owns an observable JSON value. A **derivation**
-computes another observable value from cells or other readable sources.
-
-Extend the contract with `rows`, `openCount`, and editing methods. State
-members describe values, not methods. This adds members at contract version 1;
-older callers that only need `label` still have everything they need.
-
-`self.state(name, schema, initial)` declares a cell and returns it. The name
-`rows` is important: on reload, Chord matches that name to the existing cell and
-keeps its value. `self.derive(sources, fn)` declares a derivation; it has no
-name, because it holds nothing a reload must keep.
-
-<!-- example:03-contract -->
-```ts
-const Todo = obj({ text: str(), done: bool() }, { open: true });
-const Rows = arr(Todo);
-const TodoStore = local("tutorial.todos", {
-	version: 1,
-	input: obj({ list: str() }, { open: true }),
-	members: {
-		label: method(undefined, str()),
-		rows: Rows,
-		openCount: num(),
-		add: method(obj({ text: str() }, { open: true })),
-		finish: method(obj({ index: int() }, { open: true })),
-		reset: method(Rows),
-	},
-});
-```
-
-The factory now declares a cell and a derivation. It is wrapped in `todoStore`,
-which takes the cell's options (section 9 raises its version); for now
-`todoFactory` uses the defaults. Each method receives its arguments and a
-context; changing the cell updates its readers and its derived count together.
-`add`, `finish` and `reset` declare no result, so they return nothing.
-
-<!-- example:03-factory -->
-```ts
-/** The store's factory; `options` versions its rows (section 9). */
-const todoStore =
-	(options?: StateOptions<Static<typeof Rows>>): Factory<typeof TodoStore> =>
-	({ list }, _principal, self) => {
-		const rows = self.state("rows", Rows, [], options);
-		const openCount = self.derive([rows], (todos) => todos.filter((todo) => !todo.done).length);
-		return {
-			label: () => `Todos for ${list}`,
-			rows,
-			openCount,
-			add: ({ text }, ctx) => {
-				rows.change(ctx, (draft) => {
-					draft.push({ text, done: false });
-				});
-			},
-			finish: ({ index }, ctx) => {
-				rows.change(ctx, (draft) => {
-					const todo = draft[index];
-					if (!todo) throw invalid("args", "No such todo");
-					todo.done = true;
-				});
-			},
-			reset: (next, ctx) => {
-				rows.replace(ctx, next, { diff: true });
-			},
-		};
-	};
-const todoFactory = todoStore();
-```
-
-`change(ctx, fn)` gives `fn` a temporary mutable **draft**. Here `add`
-pushes a row and `finish` changes one field. The draft is discarded if the
-callback throws. The callback must be synchronous.
-
-`replace(ctx, value)` replaces the whole value. We use it for resetting a
-list we own completely. `{ diff: true }` asks Chord to publish just the
-structural changes. Without that option, replacement diffs automatically when
-the new value shares containers at the same keys with the old one; unrelated
-values normally publish a whole-value replacement. Either way, subscribers
-receive the same resulting value.
-
-<!-- example:03-call -->
-```ts
-const host = createHost({ self: "server", dev: true });
-host.serve(TodoStore, todoFactory);
-const todos = await host.get(TodoStore, { list: "family" });
-const counts: (number | undefined)[] = [];
-const stop = todos.openCount.subscribe((value) => counts.push(value));
-await host.root(async (ctx) => {
-	await todos.add({ text: "Buy milk" }, ctx);
-	await todos.finish({ index: 0 }, ctx);
-	await todos.reset([], ctx);
-});
-assert.deepEqual(counts, [0, 1, 0]);
-assert.deepEqual(todos.rows.value, []);
-stop();
-todos.release();
-```
-
-The count subscriber sees `0, 1, 0`: initially empty, one unfinished todo,
-then no unfinished todos. Resetting to empty does not add another count
-notification because the derived count is still zero. The final rows are `[]`.
-`subscribe` calls back immediately with the current value and returns an
-unsubscribe function. The awaited `get` makes sure there is a value: a reference
-you hold is live, with its state.
-
-> **Why:** Store reloadable state in cells, not closure variables. Treat
-> `cell.value`, `ref.rows.value`, and subscriber values as immutable.
-> Only mutate drafts inside `change`; do not keep a draft for later use.
-> A derivation runs synchronously, so use it for projections, not database work.
-
-## 4. Let objects use objects and resources
-
-Saving a todo may require both the list and a database connection. A
-**reference** keeps the object it refers to alive. `self.get` declares a
-reference owned by this object; it lasts longer than a single method call.
-
-A **resource** is something the runtime opens and later closes, such as a
-database connection. Its `open` may be asynchronous even though the factory
-must be synchronous. The example database is deliberately fake: it just saves
-strings in memory.
-
-`opaque<T>("name@version")` describes a native, host-only member. It is not
-JSON state and cannot be sent over a link. `self.expose` connects that member
-to a declared resource, without reading the resource during the factory.
-
-<!-- example:04-database -->
-```ts
-const Database = local("tutorial.database", {
-	version: 1,
-	input: obj({}, { open: true }),
-	members: { db: opaque<{ saved: string[] }>("tutorial.database@1") },
-});
-const SavedTodos = local("tutorial.saved-todos", {
-	version: 1,
-	input: obj({ list: str() }, { open: true }),
-	members: { add: method(obj({ text: str() }, { open: true })) },
-});
-const host = createHost({ self: "server" });
-let opens = 0;
-const closed = Promise.withResolvers<void>();
-host.serve(Database, (_input, _principal, self) => {
-	const db = self.resource("db", {
-		version: 1,
-		open: async () => {
-			opens++;
-			return { saved: [] as string[] };
-		},
-		close: () => closed.resolve(),
-	});
-	return { db: self.expose(db) };
-});
-```
-
-The factory returns an exposed marker, not an opened connection. Chord runs
-`open` after declarations finish. The promise named `closed` lets the test
-observe eventual cleanup.
-
-Now declare `SavedTodos` as an object that holds both the store and the database.
-Its editing method uses these dependencies only after activation.
-
-<!-- example:04-saving -->
-```ts
-host.serve(TodoStore, todoFactory);
-host.serve(
-	SavedTodos,
-	({ list }, _principal, self) => {
-		const database = self.get(Database, {});
-		const todos = self.get(TodoStore, { list });
-		return {
-			add: async ({ text }, ctx) => {
-				database.db!.saved.push(text);
-				await todos.add({ text }, ctx);
-			},
-		};
-	},
-	{ linger: 0 },
-);
-```
-
-An outside consumer holds a `SavedTodos` reference. We also hold `Database`
-directly so we can inspect what was saved.
-
-<!-- example:04-call -->
-```ts
-const saved = await host.get(SavedTodos, { list: "family" });
-const database = await host.get(Database, {});
-await host.root((ctx) => saved.add({ text: "Buy milk" }, ctx));
-assert.deepEqual(database.db!.saved, ["Buy milk"]);
-assert.equal(opens, 1);
-const statuses: string[] = [];
-saved.onStatus((status) => statuses.push(status));
-database.release();
-saved.release();
-await closed.promise;
-assert.equal(saved.status, "released");
-assert.ok(statuses.includes("released"));
-```
-
-After the method, the fake database contains `["Buy milk"]`. It opened once,
-even though two objects referenced it. `SavedTodos` and `Database` become live
-only after their resources and declared dependencies are ready. That is why
-`database.db!` is safe inside this live object's method: activation has
-already established that dependency. An outside caller awaits its `get`.
-
-When both external references are released, `SavedTodos` is disposed and
-releases its own database reference. With no references left, the database closes; we
-wait for `closed.promise` to prove it. The released reference stays
-`released`, and `onStatus` reports that transition. `onStatus` watches
-changes; unlike state subscription, it does not deliver an initial status.
-
-`linger` is a delay in milliseconds after the last reference is released. Zero disposes
-without a grace period; a positive value can avoid reopening an expensive
-resource when a screen is briefly hidden. Linger is not persistence.
-
-> **Tip:** A factory only declares dependencies. Never call a referenced object's method or
-> read `resource.value` there, including during reload. Activation happens
-> afterward. Bump a resource's `version` when its configuration should be reopened.
-> Disposal stops tasks and listeners, closes resources, then releases references.
-
-## 5. Who is asking? One store, two views
-
-Owners may add todos; guests may only read them. A **principal** is the
-application-defined identity of a caller. A **variant** is a named set of
-members a remote object offers to that principal. It lets the UI discover
-whether an editing method is available.
-
-Do not create a separate data cell for each viewer: their lists would diverge.
-Instead, each view holds the same host-local `TodoStore` and exposes its rows.
-`self.get` acts as the host's own principal, so owner and guest views share
-that store. Remote view objects themselves are separate per principal key.
-A remote contract also says where its objects live: `host: hostNamed("server")`
-puts every `Todos` object on the host named `server`. Section 6 uses that.
-
-<!-- example:05-views -->
-```ts
-const Todos = remote("tutorial.todo-view", {
-	version: 1,
-	input: obj({ list: str() }, { open: true }),
-	host: hostNamed("server"),
-	variants: {
-		viewer: { state: { rows: Rows } },
-		editor: {
-			state: { rows: Rows },
-			methods: { add: method(obj({ text: str() }, { open: true })) },
-		},
-	},
-});
-
-/** Who may ask: the owner, a guest, or the server's own code. */
-type Principal = "owner" | "guest" | "server";
-
-function serveViews(api: Pick<Host<Principal>, "serve">): void {
-	api.serve(Todos, ({ list }, principal, self) => {
-		if (list !== "family") throw forbidden("This list is not shared");
-		const store = self.get(TodoStore, { list });
-		if (principal === "guest") {
-			return { variant: "viewer", rows: store.rows };
-		}
-		return {
-			variant: "editor",
-			rows: store.rows,
-			add: ({ text }, ctx) => {
-				if (text.trim().length === 0) throw invalid("args", "A todo needs text");
-				return store.add({ text }, ctx);
-			},
-		};
-	});
-}
-```
-
-Here principals are the strings `"owner"` and `"guest"`, assigned by
-trusted application code, and `"server"`, the host's own code: every host is
-created with `self`, the principal its own roots and objects act as. Chord
-invents no principals. The `Principal` type parameter of `createHost` and
-`Host` makes `principal` in the factory that type, so TypeScript checks the
-comparisons. `principalKey` maps identity to object identity. Real
-applications should use stable identity, connection provenance, and grant
-revision, not display names.
-
-<!-- example:05-call -->
-```ts
-const host = createHost<Principal>({ name: "server", self: "server", principalKey: (principal) => principal });
-host.serve(TodoStore, todoFactory);
-serveViews(host);
-const owner = await host.get(Todos, { list: "family" }, { principal: "owner" });
-const guest = await host.get(Todos, { list: "family" }, { principal: "guest" });
-assert.ok(owner.variant === "editor"); // narrows the reference to the editor variant
-assert.equal(guest.variant, "viewer");
-await host.root((ctx) => owner.add({ text: "Buy milk" }, ctx), { principal: "owner" });
-assert.deepEqual(guest.rows.value, [{ text: "Buy milk", done: false }]);
-// @ts-expect-error A viewer has no add: TypeScript refuses it, and so does the provider.
-await assert.rejects(guest.add({ text: "Not allowed" }), (error) => isChordError(error, "not_in_variant"));
-await assert.rejects(owner.add({ text: " " }), (error) => isChordError(error, "invalid"));
-```
-
-The owner gets `editor`; the guest gets `viewer`. Both see the same milk
-todo. A reference is typed as the union of its variants: `add` is reachable only
-after narrowing on `variant` (`assert.ok(owner.variant === "editor")` does that).
-The guest's `add` is refused by TypeScript, and, called anyway, rejects with
-`not_in_variant`. Whitespace-only text
-rejects with `invalid`: it is a string, as the schema demands, but it breaks a
-rule only the method knows. Use `invalid` for bad input and `forbidden` only
-for callers who may not do something.
-
-> **Why:** A variant is not all of authorization. The factory checks which
-> list may be opened; the method checks the operation's arguments. Production
-> code must also enforce grants that can change. Use
-> `host.invalidatePrincipal(match)` to revoke matching objects; held references
-> become `gone`. A UI watches `onStatus` and gets a new reference when appropriate.
-> Guest-provided names or message text must never establish identity.
-
-## 6. Reach the list from another process
-
-A browser cannot call a host-only contract. `remote` contracts describe only
-schema-checked state and methods that can travel as JSON. Our `Todos` view is
-remote; the underlying `TodoStore` and database stay local. A caller never
-names a host: `browser.get(Todos, …)` goes to `server` because the contract
-says so, and the server refuses to serve, or to be asked for, a type it is not
-the place of. A type that lives on one host per session says
-`host: hostFamily("session:", "session")`: its input's `session` field picks
-the host (`{ session: "S1" }` lives on `session:S1`).
-
-A **link** carries ordered messages between hosts. A memory link runs both ends
-in one test process, but uses the remote protocol. The accepting host stamps
-the caller's principal from its authenticator, not from method arguments or a
-client's claimed identity. The connecting side names the principal its parent's
-own requests act as (`upstream: { link, principal }`, or `connect(link, {
-principal })`).
-
-<!-- example:06 -->
-```ts
-const server = createHost<Principal>({ self: "server", name: "server" });
-server.serve(TodoStore, todoFactory);
-serveViews(server);
-const [down, up] = memoryLinkPair();
-server.accept(down, { principal: "owner", kind: "client" });
-const browser = createHost({
-	self: "browser",
-	name: "browser",
-	kind: "client",
-	upstream: { link: up, principal: "server" },
-});
-const todos = await browser.get(Todos, { list: "family" });
-assert.ok(todos.variant === "editor");
-assert.deepEqual(todos.rows.value, []);
-const updated = Promise.withResolvers<void>();
-const stop = todos.rows.subscribe((rows) => {
-	if (rows.length === 1) updated.resolve();
-});
-await browser.root((ctx) => todos.add({ text: "Buy milk" }, ctx));
-await updated.promise;
-assert.deepEqual(todos.rows.value, [{ text: "Buy milk", done: false }]);
-// Deliberately bypass TypeScript to simulate a malformed caller.
-await assert.rejects(todos.add({ text: 123 } as never), (error) => isChordError(error, "invalid"));
-stop();
-// A held reference keeps its state without listeners.
-assert.deepEqual(todos.rows.value, [{ text: "Buy milk", done: false }]);
-todos.release();
-```
-
-The browser sees an empty snapshot, then the new milk todo. `ready` means
-the remote reference has bound to a live object **and** has its state: every
-state member of its variant has a snapshot. A held reference stays subscribed,
-with or without listeners, until it is released.
-
-What crosses the wire: the input and consumer's contract description, the
-provider's shape (variant and members), method arguments and results, and the
-state of the reference's variant. State starts with a **snapshot**, the whole current value;
-subsequent **deltas** describe changes. Rebinds and reloads can send a
-`reset`, a fresh whole value. Functions, resource connections, and cell
-instances do not cross the wire.
-
-The deliberate bad argument rejects with `invalid`. Remote arguments,
-results, and outgoing state are validated at the provider boundary. Local
-methods do not get per-call schema validation; they still need app-level checks.
-`dev: true` additionally checks cell writes while developing.
-
-> **Tip:** Replace `memoryLinkPair` with `webSocketLink` for a WebSocket or
-> `ipcLink` for a child-process IPC channel; object contracts stay the same.
-> Those adapters wrap an existing connection, not an authenticator. Configure
-> `accept` with an authenticated principal. A browser is `kind: "client"`;
-> a trusted child host is accepted with `kind: "host"` and its configured name.
-
-## 7. React to changes and run background work
-
-Not all work comes from method calls. The app may update an activity indicator
-when rows change, or run a background reminder. A **listener** reacts to an
-observable source. A **task** is background execution owned by an object,
-which is aborted when the object is disposed or its code is reloaded.
-
-Our activity object mirrors the row count. Its task inserts a sample todo,
-then waits for shutdown. The promises make those events deterministic in a
-test; they are not stored application state.
-
-<!-- example:07 -->
-```ts
-const Activity = local("tutorial.activity", {
-	version: 1,
-	input: obj({}, { open: true }),
-	members: { seen: num() },
-});
-const host = createHost({ self: "server" });
-host.serve(TodoStore, todoFactory);
-const observed = Promise.withResolvers<void>();
-const seeded = Promise.withResolvers<void>();
-const stopped = Promise.withResolvers<void>();
-host.serve(Activity, (_input, _principal, self) => {
-	const todos = self.get(TodoStore, { list: "family" });
-	const seen = self.state("seen", num(), 0);
-	self.on("rows", todos.rows, (rows, ctx) => {
-		seen.replace(ctx, rows?.length ?? 0);
-		if (rows?.length === 1) observed.resolve();
-	});
-	self.task(async (ctx) => {
-		await todos.add({ text: "Review the list" }, ctx);
-		seeded.resolve();
-		await new Promise<void>((resolve) => {
-			if (ctx.signal.aborted) resolve();
-			else ctx.signal.addEventListener("abort", () => resolve(), { once: true });
-		});
-		stopped.resolve();
-	});
-	return { seen };
-});
-const activity = await host.get(Activity, {});
-await Promise.all([seeded.promise, observed.promise]);
-assert.equal(activity.seen.value, 1);
-activity.release();
-await stopped.promise;
-```
-
-The final `seen` is `1`. Each listener event receives a fresh root's
-`ctx`; its write belongs to that short call tree. A task is not one enormous
-root: Chord method calls made with its task context start fresh short roots.
-We pass that context into `todos.add` so cancellation follows the task.
-Releasing the activity reference aborts its task and resolves `stopped`.
-
-`self.on(name, source, handler)` declares a listener; `self.task(fn)` a task.
-A listener on state, like `rows` here, gets the current value when it starts,
-then every change. It gets the current value again whenever a reload replaced
-its source (a derivation is new at every reload), so its handler must
-reconcile (`seen` is set from the rows, not counted up). Listeners can also
-subscribe to a resource's event stream with `self.on(name, resource, select,
-handler)`: `select` gets the opened resource and returns something with
-`subscribe`; an event stream delivers no current value. Kept subscriptions
-survive reload while the resource and selector remain unchanged; the handler
-switches to new code. A selector that captures changing configuration should
-get a new listener name. Tasks have no names: a reload restarts them all.
-
-> **Why:** Do not wait for a person, sleep for minutes, or run an endless loop
-> inside a method. That pins a root and can block state migration. Store a
-> pending request in a cell and answer in another call, or use a task that obeys
-> `ctx.signal`. Never retain a completed method's `ctx` for background work.
-
-## 8. Package features as plugins
-
-Now a plugin can contribute a menu action without editing a central switch.
-A **registry** is a named table of contributions. A **facet** is a plugin's code
-for one kind of host: it serves object types. A plugin can have server, worker, and browser
-facets, each installing that part of the feature.
-
-Registrations belong to objects of **lifetime `"host"`**: the host creates such
-an object when its facet loads and keeps it until the host closes, even if no
-screen asks for it. That keeps our menu contribution present. Objects of the
-default lifetime, `"referenced"`, are still created only when referenced.
-
-<!-- example:08 -->
-```ts
-const Actions = defineRegistry<(ctx: Ctx) => Promise<number>>("tutorial.actions");
-const Menu = local("tutorial.menu", { version: 1, input: obj({}, { open: true }) });
-let click: (() => Promise<number>) | undefined;
-const storeFacet: Facet = {
-	name: "todo-store",
-	...defineFacet((api) => api.serve(TodoStore, todoFactory)),
-};
-const menuFacet: Facet = {
-	name: "todo-menu",
-	...defineFacet(
-		(api) => {
-			api.serve(
-				Menu,
-				(_input, _principal, self) => {
-					const todos = self.get(TodoStore, { list: "family" });
-					self.register(Actions, {
-						addSample: async (ctx) => {
-							await todos.add({ text: "Try plugins" }, ctx);
-							return todos.openCount.value;
-						},
-					});
-					return {};
-				},
-				{ lifetime: "host" },
-			);
-			click = () => api.root((ctx) => api.registry(Actions).get("addSample", ctx)!(ctx));
-		},
-		{ uses: [TodoStore] },
-	),
-};
-const host = createHost({ self: "server" });
-await host.load([menuFacet, storeFacet], { awaitHostObjects: false });
-await host.ready();
-assert.equal(await click!(), 1);
-assert.equal(host.registry(Actions).table().size, 1);
-```
-
-Clicking returns `1`, and the registry has one entry. The menu's dependency
-can come from a later facet in the load batch: `load` installs the whole
-batch before waiting for host objects to activate. The facet declares `uses` so
-reload can also check the contract it consumes.
-
-The facet API supplies `serve`, `name`, `root`, and `registry`.
-Our ordinary UI callback uses its saved `api.root`, not a process-global
-host. Looking up a registry entry with `ctx` uses the table belonging to that
-root's code version. Without `ctx`, lookup uses the current table. Duplicate
-keys fail by default; `subscribe` can bridge tables to an imperative consumer.
-
-Normally use `await host.load(facets)` (or `await host.install(facet)`),
-which waits for those host objects. This example explicitly defers that barrier
-with `awaitHostObjects: false`, then awaits `host.ready()`. That waits for a
-snapshot of the host's objects, not for task completion or later loads.
-Failures reject the readiness promise; abandoning startup requires closing the
-host, because installation is not a rollback transaction.
-
-> **Tip:** Use deferred readiness only when needed. A worker may have to await
-> an independent local bootstrap reference, announce control readiness so its
-> parent admits its link, and only then await `host.ready()`. Waiting for
-> upstream-dependent host objects before admission would deadlock.
-
-For real plugin files, default-export `defineFacet(...)`. Node hosts configure
-`createHost({ loader: nodeLoader })`, with `nodeLoader` imported from
-`@earendil-works/chord/node`, then pass module URLs to `load` and `reload`.
-The in-memory facet objects here avoid filesystem setup. Built-in facets are
-trusted in-process code, not a sandbox; the current Node loader keeps old module
-copies in memory, so repeated loading has that limitation.
-
-## 9. Change running code without losing the list
-
-A reference is useful precisely because callers keep it while implementations
-change. An **code version** identifies one committed set of code and registry tables.
-A root keeps the code version it started with. New roots use the latest one.
-
-### Compatible code change: no waiting
-
-Give the same named facet a new factory. It changes the label but keeps the
-cell declaration. This test deliberately pauses one caller to show what an
-old root sees; application methods should not pause like this.
-
-<!-- example:09-compatible -->
-```ts
-const host = createHost({ self: "server" });
-const facet = (label: string): Facet => ({
-	name: "todos",
-	setup: (api) =>
-		api.serve(TodoStore, (input, principal, self) => ({
-			...todoFactory(input, principal, self),
-			label: () => label,
-		})),
-});
-await host.load([facet("Original")]);
-const todos = await host.get(TodoStore, { list: "family" });
-await todos.add({ text: "Buy milk" });
-const entered = Promise.withResolvers<void>();
-const resume = Promise.withResolvers<void>();
-const oldRoot = host.root(async (ctx) => {
-	const first = await todos.label(ctx);
-	entered.resolve();
-	await resume.promise; // Test-only pause: pin an old caller during reload.
-	return [first, await todos.label(ctx)];
-});
-await entered.promise;
-const compatible = await host.reload([facet("Updated")]);
-assert.deepEqual(compatible.gated, []);
-assert.equal(await todos.label(), "Updated");
-resume.resolve();
-assert.deepEqual(await oldRoot, ["Original", "Original"]);
-assert.equal(todos.rows.value?.[0]?.text, "Buy milk");
-```
-
-Reload commits while the old root is paused: `gated` is empty. New calls see
-`"Updated"`; the resumed old root sees `"Original"` twice. The milk row
-survives. Compatible code changes do not wait for that old root to finish.
-
-### State change: bump its version and migrate
-
-Suppose a new policy converts existing todo text to uppercase. The schema is
-unchanged, but the data's meaning changes. We still bump the cell's **state
-version** (`self.state`'s `version` option, default 1). It belongs to one cell,
-independently of the contract version. A **migration** (`migrate`) converts an
-old value of that cell to the new representation.
-
-<!-- example:09-migrate -->
-```ts
-const events: string[] = [];
-const stopEvents = todos.rows.events((event) => events.push(event.type));
-const migrated = await host.reload([
-	{
-		name: "todos",
-		setup: (api) =>
-			api.serve(
-				TodoStore,
-				todoStore({
-					version: 2,
-					migrate: (old, from) => {
-						assert.equal(from, 1);
-						return (old as Static<typeof Rows>).map((todo) => ({ ...todo, text: todo.text.toUpperCase() }));
-					},
-				}),
-			),
-	},
-]);
-assert.equal(migrated.gated.length, 1);
-assert.deepEqual(todos.rows.value, [{ text: "BUY MILK", done: false }]);
-assert.deepEqual(events, ["snap", "reset"]);
-stopEvents();
-```
-
-The migration receives the old rows and their state version, `1`. It returns
-new rows; the reference now reads `[{ text: "BUY MILK", done: false }]`.
-Subscribers get a `reset` event containing the migrated value. The event
-assertion sees an initial `snap`, then that `reset`.
-One object is gated. A **gate** waits for calls already inside that object to
-finish before migrating a private copy, validating it, and committing. Old
-roots that had not entered it cannot later use old code over migrated data:
-they get `upgrade_conflict` and should retry in a new root.
-
-Changing a cell's schema also requires a version bump, and a migration unless
-the old value already fits the new schema. A change of meaning with the same schema,
-like this example, cannot be detected automatically. Real migrations must
-reference each stored version they support, not assume every installation is
-exactly one version behind.
-
-### Contract change: keep an adapter for old callers
-
-Rename `label` to `heading`. That is a breaking contract change, so use
-contract version 2. The provider's `accepts[1]` adapter builds the implementation
-that version-1 consumers still expect.
-
-<!-- example:09-contract -->
-```ts
-// Remove label from the new provider's contract: it is now called heading.
-const { label: _label, ...members } = TodoStore.def.members;
-const RenamedStore = local("tutorial.todos", {
-	version: 2,
-	input: TodoStore.def.input,
-	members: { ...members, heading: method(undefined, str()) },
-});
-await host.reload([
-	{
-		name: "todos",
-		setup: (api) =>
-			api.serve(
-				RenamedStore,
-				(input, principal, self) => {
-					const { label, ...implementation } = todoStore({ version: 2 })(input, principal, self);
-					return { ...implementation, heading: label };
-				},
-				{
-					accepts: {
-						1: (current) => ({ ...current, label: current.heading }),
-					},
-				},
-			),
-	},
-]);
-assert.equal(await todos.label(), "Todos for family");
-const newer = await host.get(RenamedStore, { list: "family" });
-assert.equal(await newer.heading(), "Todos for family");
-assert.equal(todos.rows.value?.[0]?.text, "BUY MILK");
-```
-
-The old reference's `label` and the new reference's `heading` both return
-`"Todos for family"`. Both still reach the migrated rows. The adapter maps
-implementations, not references; forwarding the existing method preserves its context.
-We keep the cell at version 2 here so this code-only change does not repeat
-migration.
-
-> **Why:** Contract versions protect callers; state versions protect stored
-> data; resource versions control reopening. Do not use one number for all
-> three. Additive compatible contracts can keep their version; breaking shape
-> or meaning changes need a contract bump and adapters for old consumers.
-> Reload prepares candidates first; preparation failure leaves the old code
-> running. A migration gate that misses its deadline aborts rather than
-> switching data underneath active old code.
-
-## 10. Test the objects, not a whole deployment
-
-Most implementation needs only a bare host. Use real factories for state tests, and a
-fake facet when you want to test delegation without a real database or service.
-Here the fake records what the editing view sends to the store.
-
-<!-- example:10 -->
-```ts
-const host = createHost<Principal>({ name: "server", self: "server", dev: true });
-const received: string[] = [];
-const fake: Facet = {
-	name: "fake-store",
-	...defineFacet((api: FacetApi) => {
-		api.serve(TodoStore, (input, principal, self) => ({
-			...todoFactory(input, principal, self),
-			add: ({ text }) => {
-				received.push(text);
-			},
-		}));
-	}),
-};
-await host.load([fake]);
-serveViews(host);
-const owner = await host.get(Todos, { list: "family" }, { principal: "owner" });
-assert.ok(owner.variant === "editor");
-await owner.add({ text: "Test delegation" });
-assert.deepEqual(received, ["Test delegation"]);
-await assert.rejects(owner.add({ text: "" }), (error) => isChordError(error, "invalid"));
-owner.release();
-await assert.rejects(owner.add({ text: "Too late" }), (error) => isChordError(error, "released"));
-```
-
-The fake received `["Test delegation"]`. Empty text failed before reaching
-the fake. The released reference rejects further calls with `released`.
-`isChordError(error, code)` checks a stable error code; avoid testing only a
-message's wording.
-
-Our other tests exercise the real cells (section 3), resource cleanup (4),
-principal variants (5), a client over a memory link (6), and callers kept through
-reload (9). After an awaited `get` the state is there; for later changes, await
-the value you need. Always unsubscribe and close hosts; leaked references can hide
-lifetime bugs or leave background tasks running.
-
-> **Tip:** A fake must honor the contract it serves. This fake delegates all
-> ordinary members to `todoFactory` and replaces only `add`; it deliberately
-> objects calls rather than updating rows. Do not confuse that with persistence.
-
-## 11. Keep these habits
-
-A temporary call reference should not accidentally become a permanent one. A
-screen should not lose its data merely because a button click finishes. Use
-`ctx.get` for the first lifetime and `host.get` for the second.
-
-<!-- example:11 -->
-```ts
-const host = createHost({ self: "server" });
-host.serve(TodoStore, todoFactory);
-const screen = await host.get(TodoStore, { list: "family" });
-await host.root(async (ctx) => {
-	const temporary = await ctx.get(TodoStore, { list: "family" });
-	await temporary.add({ text: "Keep roots short" }, ctx);
-}); // The temporary reference is released here; screen still holds the store.
-assert.equal(screen.openCount.value, 1);
-screen.release(); // No reference remains; without persistence, disposal loses these rows.
-```
-
-The screen still sees count `1` after the root finishes, because it owns a
-separate reference. When the screen releases it, no reference remains. This tutorial's cells
-are in memory: reload preserves a live object, but disposal or process restart
-loses its rows. Real persistence belongs in a database resource, with an
-explicit load/save policy.
-
-### Checklist and common mistakes
-
-- Keep reloadable state in cells, not closure variables: factories rerun.
-- Change drafts, not published values: mutation outside cells bypasses updates.
-- Use `change` for field edits and `replace` for owned snapshots: replacing
-  can erase fields your code does not know about.
-- Declare dependencies in a synchronous factory, not during methods: activation
-  and reload need a complete declaration list.
-- Use `ctx.get` for temporary method dependencies: their references end with the call.
-- Pass `ctx` into nested calls: cancellation and code versions must stay together.
-- Keep roots short and tasks cancellable: migration and shutdown need work to settle.
-- Check grants and arguments, not just variants: available methods are not a full policy.
-- Stamp principals at trusted ingress, not from client payloads: names are not identities.
-- Await `get` before reading state: a reference you hold is live and hydrated, a
-  loading one (`host.hold`) throws `not_ready`.
-- Release references and unsubscribe: otherwise unused objects remain referenced or observed.
-- Bump state versions, contract versions, and resource versions for their own changes:
-  each protects a different boundary.
-- Await host object readiness before reporting startup success: declared is not yet live.
-- Keep reference dependencies acyclic: an object cannot wait for itself through another object.
-
-### Imports and running the examples
-
-These are the shared imports from `test/tutorial.test.ts`. The relative
-path is correct from that test directory; applications import the same names
-from `@earendil-works/chord`. `assert` expresses expected values; `it` and
-`onTestFinished` come from the test runner; `readFileSync` is used by the
-tutorial's source-matching check, not by the application.
-
-<!-- example:imports -->
-```ts
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { arr, bool, int, num, obj, type Static, str } from "@earendil-works/pi-schema";
-import { it, onTestFinished } from "vitest";
-import {
-	type Ctx,
-	createHost,
-	defineFacet,
-	defineRegistry,
-	type Facet,
-	type FacetApi,
-	type Factory,
-	forbidden,
-	type Host,
-	hostNamed,
-	invalid,
-	isChordError,
-	local,
-	memoryLinkPair,
-	method,
-	opaque,
-	remote,
-	type StateOptions,
-} from "../src/index.ts";
-```
-
-From `packages/chord`, run:
-
-```sh
-node ../../node_modules/vitest/dist/cli.js --run test/tutorial.test.ts
-```
-
-There is one test per numbered section. Every TypeScript block is matched
-against its runnable source, so changing either copy without the other fails a
-test. The test harness adds teardown and drift checks; it never uses a real
-database, network service, or provider API.
-
-Next read [the usage guide](guide.md) for the API reference and
-[the specification](spec.md) for compatibility, lifetime, and reload
-rules, including its known limitations. If a reference disagrees with
-`src`, the current implementation wins.