pi-mono/packages/chord/docs/tutorial.md

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 handle is a caller's reference to that object, not the object itself. Several handles can reach the same object. Handles can also reach another host over a connection.

browser host                         server host
handle + subscribed rows -- link --> Todos view (owner or guest)
                                           |
                                        handle
                                           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.

const host = createHost({ 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. We use TypeBox's Type to write schemas; Type.Null() means this method takes no useful argument.

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.

const TodoLabel = local("tutorial.todos", {
	version: 1,
	input: Type.Object({ list: Type.String() }),
	members: { label: method(Type.Null(), Type.String()) },
});

A factory is a synchronous function that creates the object's behavior: 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.

const host = createHost();
host.serve(TodoLabel, ({ list }) => ({ label: () => `Todos for ${list}` }));
const result = await host.root(async (ctx) => {
	const todos = ctx.get(TodoLabel, { list: "family" });
	return todos.label(null, ctx);
});
assert.equal(result, "Todos for family");

The result is "Todos for family". ctx.get returns a handle immediately; method calls wait for the object to become live. The handle 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(null), starts its own root. 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 handle 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 declares named cells. The name rows is important: on reload, Chord matches that name to the existing cell and keeps its value.

const Todo = Type.Object({ text: Type.String(), done: Type.Boolean() });
const Rows = Type.Array(Todo);
const TodoStore = local("tutorial.todos", {
	version: 1,
	input: Type.Object({ list: Type.String() }),
	members: {
		label: method(Type.Null(), Type.String()),
		rows: Rows,
		openCount: Type.Number(),
		add: method(Type.Object({ text: Type.String() }), Type.Null()),
		finish: method(Type.Object({ index: Type.Integer() }), Type.Null()),
		reset: method(Rows, Type.Null()),
	},
});

The factory now declares a cell and a derivation. Each method receives its arguments and a context; changing the cell updates its readers and its derived count together.

const todoFactory: Factory<typeof TodoStore> = ({ list }, _principal, self) => {
	const state = self.state({ rows: cell(Rows, []) });
	const derived = self.derive({
		openCount: derivation([state.rows], (rows) => rows.filter((todo) => !todo.done).length),
	});
	return {
		label: () => `Todos for ${list}`,
		rows: state.rows,
		openCount: derived.openCount,
		add: ({ text }, ctx) => {
			state.rows.change(ctx, (draft) => {
				draft.push({ text, done: false });
			});
			return null;
		},
		finish: ({ index }, ctx) => {
			state.rows.change(ctx, (draft) => {
				const todo = draft[index];
				if (!todo) throw invalid("args", "No such todo");
				todo.done = true;
			});
			return null;
		},
		reset: (rows, ctx) => {
			state.rows.replace(ctx, rows, { diff: true });
			return null;
		},
	};
};

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.

const host = createHost({ dev: true });
host.serve(TodoStore, todoFactory);
const todos = host.get(TodoStore, { list: "family" });
await todos.ready;
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. We await ready first so that value is not a loading placeholder.

Why: Store reloadable state in cells, not closure variables. Treat cell.value, handle.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 hold is a handle's claim that keeps an object alive. self.get declares a hold 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.

const Database = local("tutorial.database", {
	version: 1,
	input: Type.Object({}),
	members: { db: opaque<{ saved: string[] }>("tutorial.database@1") },
});
const SavedTodos = local("tutorial.saved-todos", {
	version: 1,
	input: Type.Object({ list: Type.String() }),
	members: { add: method(Type.Object({ text: Type.String() }), Type.Null()) },
});
const host = createHost();
let opens = 0;
const closed = Promise.withResolvers<void>();
host.serve(Database, (_input, _principal, self) => {
	const res = self.resources({
		db: resource({
			rev: 1,
			open: async () => {
				opens++;
				return { saved: [] as string[] };
			},
			close: () => closed.resolve(),
		}),
	});
	return { db: self.expose(res.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.

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);
				return null;
			},
		};
	},
	{ linger: 0 },
);

An outside consumer holds a SavedTodos handle. We also hold Database directly so we can inspect what was saved.

const saved = host.get(SavedTodos, { list: "family" });
const database = host.get(Database, {});
await saved.ready;
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 held 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 must await readiness.

When both external handles are released, SavedTodos is disposed and releases its own database hold. With no holds left, the database closes; we wait for closed.promise to prove it. The released handle 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 hold leaves. 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 held method or read resource.value there, including during reload. Activation happens afterward. Bump a resource's rev when its configuration should be reopened. Disposal stops tasks and listeners, closes resources, then releases holds.

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 defaults to the host principal, so owner and guest views share that store. Remote view records themselves are separate per principal key.

const Todos = remote("tutorial.todo-view", {
	version: 1,
	input: Type.Object({ list: Type.String() }),
	variants: {
		viewer: { state: { rows: Rows } },
		editor: {
			state: { rows: Rows },
			methods: { add: method(Type.Object({ text: Type.String() }), Type.Null()) },
		},
	},
});

function serveViews(api: Pick<Host, "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 !== "owner" && principal !== hostPrincipal) {
			return { kind: "viewer", rows: store.rows };
		}
		return {
			kind: "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. The built-in hostPrincipal can also edit. principalKey maps identity to record identity. Real applications should use stable identity, connection provenance, and grant revision, not display names.

const host = createHost({ principalKey: (principal) => String(principal) });
host.serve(TodoStore, todoFactory);
serveViews(host);
const owner = host.get(Todos, { list: "family" }, { principal: "owner" });
const guest = host.get(Todos, { list: "family" }, { principal: "guest" });
await Promise.all([owner.ready, guest.ready]);
assert.equal(owner.kind, "editor");
assert.equal(guest.kind, "viewer");
await host.root((ctx) => owner.add({ text: "Buy milk" }, ctx), { principal: "owner" });
assert.deepEqual(guest.rows.value, [{ text: "Buy milk", done: false }]);
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. Calling the guest's add rejects with not_in_variant, even though TypeScript exposes methods from all variants on a handle. 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 records; held handles become gone. A UI watches onStatus and gets a new handle 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 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.

const server = createHost({ name: "server" });
server.serve(TodoStore, todoFactory);
serveViews(server);
const [down, up] = memoryLinkPair();
server.accept(down, { principal: "owner", kind: "client" });
const browser = createHost({ name: "browser", kind: "client", upstream: up });
const todos = browser.get(Todos, { list: "family" }, { at: "server" });
const hydrated = Promise.withResolvers<void>();
const updated = Promise.withResolvers<void>();
const stop = todos.rows.subscribe((rows) => {
	if (rows !== undefined) hydrated.resolve();
	if (rows?.length === 1) updated.resolve();
});
await todos.ready;
await hydrated.promise;
assert.deepEqual(todos.rows.value, []);
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();
assert.equal(todos.rows.value, undefined);
todos.release();

The browser sees an empty snapshot, then the new milk todo. ready means the remote handle has bound to a live object; it does not guarantee that subscribed state has arrived. That is why we separately await hydrated and updated. A remote readable starts at undefined and returns to undefined when its last subscriber leaves.

What crosses the wire: the input and consumer's contract description, the provider's shape (variant and members), method arguments and results, and subscribed state. 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.

const Activity = local("tutorial.activity", {
	version: 1,
	input: Type.Object({}),
	members: { seen: Type.Number() },
});
const host = createHost();
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 state = self.state({ seen: cell(Type.Number(), 0) });
	self.listen({
		rows: listener(todos.rows, (rows, ctx) => {
			state.seen.replace(ctx, rows?.length ?? 0);
			if (rows?.length === 1) observed.resolve();
		}),
	});
	self.tasks({
		seed: 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: state.seen };
});
const activity = host.get(Activity, {});
await activity.ready;
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 handle aborts its task and resolves stopped.

Listeners can also subscribe to a resource's event stream with listener(resource, select, fn): select gets the opened resource and returns something with subscribe. Kept subscriptions survive reload while the resource and selector remain unchanged; the callback switches to new code. A selector that captures changing configuration should get a new listener name.

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 declares what a plugin serves on one kind of host. A plugin can have server, worker, and browser facets, each installing that part of the feature.

Registrations belong to eager objects: eager means the host creates and holds the object at startup, even if no screen asks for it. That keeps our menu contribution present. Lazy objects still activate only when held.

const Actions = defineRegistry<(ctx: Ctx) => Promise<number>>("tutorial.actions");
const Menu = local("tutorial.menu", { version: 1, input: Type.Object({}) });
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 {};
				},
				{ eager: true },
			);
			click = () => api.root((ctx) => api.registry(Actions).get("addSample", ctx)!(ctx));
		},
		{ uses: [TodoStore] },
	),
};
const host = createHost();
await host.load([menuFacet, storeFacet], { awaitEager: 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 eager activation. 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 eager objects. This example explicitly defers that barrier with awaitEager: false, then awaits host.ready(). That waits for a snapshot of the host's eager holds, 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 handle, announce control readiness so its parent admits its link, and only then await host.ready(). Waiting for upstream-dependent eager 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 handle is useful precisely because callers keep it while implementations change. An epoch identifies one committed set of code and registry tables. A root keeps the epoch 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 declarations. This test deliberately pauses one caller to show what an old root sees; application methods should not pause like this.

const host = createHost();
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 = 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(null, ctx);
	entered.resolve();
	await resume.promise; // Test-only pause: pin an old caller during reload.
	return [first, await todos.label(null, ctx)];
});
await entered.promise;
const compatible = await host.reload([facet("Updated")]);
assert.deepEqual(compatible.gated, []);
assert.equal(await todos.label(null), "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 state version. This version belongs to stored cells, independently of the contract version. A migration converts an old cell value to the new representation.

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, todoFactory, {
				state: {
					version: 2,
					migrate: {
						rows: (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 handle 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 record is gated. A gate waits for calls already inside that record 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 state-version bump and a migration whose result fits the new schema. A change of meaning with the same schema, like this example, cannot be detected automatically. Real migrations must handle 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 behavior that version-1 consumers still expect.

// 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(Type.Null(), Type.String()) },
});
await host.reload([
	{
		name: "todos",
		setup: (api) =>
			api.serve(
				RenamedStore,
				(input, principal, self) => {
					const { label, ...behavior } = todoFactory(input, principal, self);
					return { ...behavior, heading: label };
				},
				{
					state: { version: 2 },
					accepts: {
						1: (current) => ({ ...current, label: current.heading }),
					},
				},
			),
	},
]);
assert.equal(await todos.label(null), "Todos for family");
const newer = host.get(RenamedStore, { list: "family" });
assert.equal(await newer.heading(null), "Todos for family");
assert.equal(todos.rows.value?.[0]?.text, "BUY MILK");

The old handle's label and the new handle's heading both return "Todos for family". Both still reach the migrated rows. The adapter maps behaviors, not handles; forwarding the existing method preserves its context. We keep state version 2 here so this code-only change does not repeat migration.

Why: Contract versions protect callers; state versions protect stored data; resource revisions 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 behavior 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.

const host = createHost({ 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);
				return null;
			},
		}));
	}),
};
await host.load([fake]);
serveViews(host);
const owner = host.get(Todos, { list: "family" }, { principal: "owner" });
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 handle 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 held through reload (9). For remote state tests, await the value you need, not just handle.ready. Always unsubscribe and close hosts; leaked holds 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 records calls rather than updating rows. Do not confuse that with persistence.

11. Keep these habits

A temporary call handle should not accidentally become a permanent hold. 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.

const host = createHost();
host.serve(TodoStore, todoFactory);
const screen = host.get(TodoStore, { list: "family" });
await screen.ready;
await host.root(async (ctx) => {
	const temporary = ctx.get(TodoStore, { list: "family" });
	await temporary.add({ text: "Keep roots short" }, ctx);
}); // The temporary handle is released here; screen still holds the store.
assert.equal(screen.openCount.value, 1);
screen.release(); // No hold remains; without persistence, disposal loses these rows.

The screen still sees count 1 after the root finishes, because it owns a separate hold. When the screen releases, no hold remains. This tutorial's cells are in memory: reload preserves a live record, 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 holds 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.
• Subscribe before expecting remote state: readiness is not snapshot hydration.
• Release handles and unsubscribe: otherwise unused objects remain held or observed.
• Bump state versions, contract versions, and resource revisions for their own changes: each protects a different boundary.
• Await eager readiness before reporting startup success: declared is not yet live.
• Keep hold 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.

import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { type Static, Type } from "typebox";
import { it, onTestFinished } from "vitest";
import {
	type Ctx,
	cell,
	createHost,
	defineFacet,
	defineRegistry,
	derivation,
	type Facet,
	type FacetApi,
	type Factory,
	forbidden,
	type Host,
	hostPrincipal,
	invalid,
	isChordError,
	listener,
	local,
	memoryLinkPair,
	method,
	opaque,
	remote,
	resource,
} from "../src/index.ts";

From packages/chord, run:

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 for the API reference and the specification for compatibility, lifetime, and reload rules, including its known limitations. If a reference disagrees with src, the current implementation wins.