feat(chord): Chord v2 slice 8, registries and host.root

Registries: shared tokens (defineRegistry), one provider per host (host.serve(R, { compose, accepts })),
contributions from facets and host-lifetime objects, plain values or followed Chord watchables, a table
sorted by plugin, lazy compose in the batch that changed the table, failures left out and reported with
the last good value kept; self.registry as a declared dependency, host.registry outside objects, older
readers mapped by accepts[old].value; keyedEntries and orderedEntries. Native sources: self.writable,
registry values and ref.state. self.retryOn wakes failed objects on registry values. host.root gives code
outside objects a call scope sealed at settle, abort and host.close.

Durable: registryReader(value, context); a Session close ends synchronous observers failed
("session closed"), watches still end ended.

packages/durable/test/examples/37-harness-registry.ts

@@ -0,0 +1,172 @@
+// A Durable harness in Chord objects, p3's pattern (Chord v2 slice 8): the object that opens Durable on the host's store
+// takes its extensions from a Chord registry (`registryReader`), so any plugin extends the harness by contributing an
+// extension; and it contributes its Harness to a second registry, through which another object follows its views
+// (`self.follow`). When that Harness's Session closes, the follower fails and follows the next Harness, woken by its
+// contribution (`self.retryOn`).
+// Run from packages/durable:
+//   node --conditions=source --experimental-strip-types test/examples/37-harness-registry.ts
+
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import {
+	arr,
+	createHost,
+	defineFacet,
+	defineRegistry,
+	local,
+	method,
+	type Native,
+	openStore,
+	type RegistryTable,
+	sqliteBackend,
+	str,
+} from "@earendil-works/chord/next";
+import { openNodeSqliteDatabase } from "@earendil-works/chord/sqlite/node";
+import { createModels } from "@earendil-works/pi-ai";
+import {
+	createRegistry,
+	defineExtension,
+	defineTask,
+	type Extension,
+	Harness,
+	type RegistrySnapshot,
+	ROOT_CONVERSATION_ID,
+	registryReader,
+} from "../../src/index.ts";
+import { StoreStorage } from "../../src/storage/store/index.ts";
+
+const context = BACKGROUND_CONTEXT;
+
+// 1. The core's registries: extensions in, Durable's registry snapshot out; and the Harness, for other objects.
+const Extensions = defineRegistry<Extension, RegistrySnapshot>("example.extensions", { version: 1 });
+const Harnesses = defineRegistry<Native<Harness>, Harness | undefined>("example.harnesses", { version: 1 });
+
+/** Builds Durable's snapshot without throwing: an extension Durable refuses (a task name taken) is reported, left out. */
+function snapshotOf(
+	table: RegistryTable<Extension>,
+	report: (conflict: { message: string; plugins: string[] }) => void,
+) {
+	const registry = createRegistry();
+	for (const { value, plugin } of table) {
+		try {
+			registry.install(value);
+		} catch (error) {
+			report({ message: (error as Error).message, plugins: [plugin] });
+		}
+	}
+	return registry.snapshot();
+}
+
+const Core = local("example.harness", {
+	version: 1,
+	params: {},
+	members: { greet: method(undefined, str()), close: method() },
+});
+const Transcript = local("example.transcript", { version: 1, params: {}, members: { kinds: arr(str()) } });
+
+// 2. The core facet: the harness object opens Durable on the store with its extensions read from the registry.
+const store = await openStore(sqliteBackend(await openNodeSqliteDatabase(":memory:")), context);
+const core = defineFacet((host) => {
+	host.serve(Extensions, { compose: (table, { report }) => snapshotOf(table, report) });
+	host.serve(Harnesses, { compose: (table) => table.at(-1)?.value.value });
+	host.serve(Core, (_, self) => {
+		// A declared dependency: the object activates (and opens Durable) once the registry has a value.
+		const extensions = self.registry(Extensions);
+		const harness = self.open(
+			async (open) => {
+				const opened = await Harness.open(
+					await StoreStorage.open(store, Core.name, open),
+					{ models: createModels(), registry: registryReader(extensions, open) },
+					open,
+				);
+				await opened.root(open);
+				return opened;
+			},
+			(h, _reason, close) => h.close(close),
+		);
+		self.contribute(Harnesses, harness);
+		// Following its own task graph, the object fails with its Session (S1), and its retry opens the next Harness.
+		self.follow((observer, ctx) => harness.value.observeTaskGraph(observer, ctx));
+		return {
+			greet: async (ctx) => {
+				// The composed snapshot, read at use: is the task's extension installed?
+				if (extensions.value.task(Greet.definition.name) === undefined) return "no greeter installed";
+				const root = await harness.value.conversation(ROOT_CONVERSATION_ID, ctx);
+				const id = await root!.commit(
+					(tx) => tx.createTask(Greet, undefined, { ownership: { kind: "conversation" } }),
+					ctx,
+				);
+				harness.value.resume();
+				return JSON.stringify((await harness.value.waitForTask(id, ctx)).state.outcome);
+			},
+			close: async (ctx) => {
+				await harness.value.close(ctx);
+				return null;
+			},
+		};
+	});
+	// 3. Another object follows the harness's conversation view through the registry.
+	host.serve(Transcript, (_, self) => {
+		const harness = self.registry(Harnesses);
+		self.retryOn(harness);
+		const view = self.follow(async (observer, ctx) =>
+			harness.value?.observeConversation(ROOT_CONVERSATION_ID, observer, ctx),
+		);
+		return { kinds: self.derive([view], ([v]) => v.entries.map((entry) => entry.kind)) };
+	});
+});
+
+// 4. Two plugins contribute extensions with the same task name, which Durable refuses: the first by plugin name
+//    (copycat) is installed, the other reported.
+const Greet = defineTask<undefined, { phase: "run" }, string>({
+	name: "example.greet",
+	version: 1,
+	initial: () => ({ phase: "run" }),
+	phases: {
+		run: async (_task, runtime, taskContext) => {
+			await runtime.commit(async (tx) => {
+				await tx.appendEntry(ROOT_CONVERSATION_ID, { kind: "example.greeted", data: {} });
+				return { status: "terminal", outcome: { status: "completed", result: "hello" } };
+			}, taskContext);
+		},
+	},
+	abort: async () => {},
+});
+const greeter = defineFacet((_, self) =>
+	self.contribute(Extensions, defineExtension({ name: "greeter", tasks: [Greet] })),
+);
+const copycat = defineFacet((_, self) =>
+	self.contribute(Extensions, defineExtension({ name: "copycat", tasks: [Greet] })),
+);
+
+const host = createHost({
+	store,
+	onError: (error) => console.log("onError:", error.kind, error.kind === "registry_conflict" ? error.message : ""),
+});
+await host.load(
+	[
+		{ name: "@example/core", facet: core },
+		{ name: "@example/greeter", facet: greeter },
+		{ name: "@example/copycat", facet: copycat },
+	],
+	context,
+);
+
+// 5. The task comes from a contributed extension; the transcript object sees its entry. (It failed once at start, before
+//    the harness object contributed its Harness: `activation_failed`, then the contribution woke it.)
+const harness = host.hold(Core, {}, context);
+const transcript = host.hold(Transcript, {}, context);
+console.log("greet:", await harness.greet(context));
+await new Promise((resolve) => setTimeout(resolve, 10));
+console.log("transcript:", transcript.kinds.value);
+
+// 6. The Session closes: both objects fail; a retry of the harness object opens the next Harness (on the same store:
+//    the transcript is still there), whose contribution wakes the follower.
+await harness.close(context).catch((error: Error) => console.log("close:", error.message));
+await new Promise((resolve) => setTimeout(resolve, 10));
+console.log("transcript after the close:", transcript.state.value.kind);
+harness.retry();
+await new Promise((resolve) => setTimeout(resolve, 50));
+console.log("transcript after the retry:", transcript.state.value.kind, transcript.kinds.value);
+
+await host.close(context);
+await store.close(context);

packages/durable/test/harness-observers.test.ts

@@ -124,8 +124,11 @@ describe("observeConversation and observeTaskGraph", () => {
 		await root.commit((tx) => tx.appendEntry(root.id, { kind: "note", data: {} }), context);
 		expect(view.calls).toHaveLength(1);
 		await watch.stop();
+		const graphWatch = await harness.watchTaskGraph(context);
 		await harness.close(context);
-		expect(graph.calls).toEqual([{ end: { kind: "ended" } }]);
+		// S1: a Session close fails an observer (it may follow the next Session); a watch ends `ended`.
+		expect(graph.calls).toEqual([{ end: { kind: "failed", error: new Error("session closed") } }]);
+		expect(await graphWatch.closed).toEqual({ kind: "ended" });
 	});
 
 	it("end with the error that failed the Harness", async () => {

packages/durable/test/harness-registry-reader.test.ts

@@ -0,0 +1,198 @@
+import { BACKGROUND_CONTEXT as context } from "@earendil-works/chord/context";
+import {
+	arr,
+	createHost,
+	defineFacet,
+	defineRegistry,
+	type FacetHost,
+	local,
+	method,
+	type Native,
+	type RegistryTable,
+	str,
+} from "@earendil-works/chord/next";
+import { createModels } from "@earendil-works/pi-ai/models";
+import { describe, expect, it } from "vitest";
+import {
+	createRegistry,
+	defineExtension,
+	defineTask,
+	type Extension,
+	Harness,
+	MemoryStorage,
+	type RegistrySnapshot,
+	ROOT_CONVERSATION_ID,
+	registryReader,
+} from "../src/index.ts";
+
+/** p3's pattern: the extensions registry composes Durable's snapshot, leaving out an extension Durable refuses. */
+const Extensions = defineRegistry<Extension, RegistrySnapshot>("app.harness.extensions", { version: 1 });
+
+function compose(table: RegistryTable<Extension>, report: (conflict: { message: string; plugins: string[] }) => void) {
+	const registry = createRegistry();
+	for (const { value, plugin } of table) {
+		try {
+			registry.install(value);
+		} catch (error) {
+			report({ message: (error as Error).message, plugins: [plugin] });
+		}
+	}
+	return registry.snapshot();
+}
+
+const Done = defineTask<undefined, { phase: "run" }, null>({
+	name: "app.done",
+	version: 1,
+	initial: () => ({ phase: "run" }),
+	phases: {
+		run: async (_task, runtime, taskContext) => {
+			await runtime.commit(
+				() => ({ status: "terminal", outcome: { status: "completed", result: null } }),
+				taskContext,
+			);
+		},
+	},
+	abort: async () => {},
+});
+
+/** A host-lifetime object contributing an extension it replaces with `install` (one with the task `app.done`). */
+const Plugin = local("app.plugin", { version: 1, params: {}, members: { install: method() } });
+
+function serve(host: FacetHost): void {
+	host.serve(Extensions, { compose: (table, { report }) => compose(table, report) });
+	host.serve(Plugin, (_, self) => {
+		const extension = self.writable<Extension>(defineExtension({ name: "app.plugin" }));
+		self.contribute(Extensions, extension);
+		return {
+			install: async () => {
+				extension.set(defineExtension({ name: "app.plugin", tasks: [Done] }));
+				return null;
+			},
+		};
+	});
+}
+
+describe("registryReader", () => {
+	it("reads the composed snapshot; a listener is called synchronously, inside the batch that composed", async () => {
+		const host = createHost({ onError: () => {} });
+		await host.load([{ name: "@app/core", facet: defineFacet(serve) }], context);
+		const value = await host.registry(Extensions, context);
+		const reader = registryReader(value, context);
+		expect(reader.snapshot().extension("app.plugin")?.tasks).toBeUndefined();
+		const calls: string[] = [];
+		const unsubscribe = reader.subscribe(() => {
+			// Inside Chord's batch: a Chord call here is refused, so a listener only wakes its scheduler.
+			try {
+				value.observe({ advance: () => {}, end: () => {} }, context);
+				calls.push("outside");
+			} catch (error) {
+				calls.push((error as { reason?: string }).reason ?? "other");
+			}
+		});
+		const plugin = await host.get(Plugin, {}, context);
+		await plugin.install(context);
+		expect(calls).toEqual(["reentrant"]);
+		expect(reader.snapshot().task("app.done")).toBe(Done);
+		unsubscribe();
+		await host.close(context);
+	});
+
+	it("wakes a Harness's scheduler: a task blocked on its missing definition runs once a contribution brings it", async () => {
+		const host = createHost({ onError: () => {} });
+		await host.load([{ name: "@app/core", facet: defineFacet(serve) }], context);
+		const harness = await Harness.open(
+			new MemoryStorage(),
+			{ models: createModels(), registry: registryReader(await host.registry(Extensions, context), context) },
+			context,
+		);
+		harness.resume();
+		const root = await harness.root(context);
+		const id = await root.commit(
+			(tx) => tx.createTask(Done, undefined, { ownership: { kind: "conversation" } }),
+			context,
+		);
+		const done = harness.waitForTask(id, context);
+		await new Promise((resolve) => setTimeout(resolve, 10));
+		await (await host.get(Plugin, {}, context)).install(context);
+		expect((await done).state.outcome).toEqual({ status: "completed", result: null });
+		await harness.close(context);
+		await host.close(context);
+	});
+});
+
+/** p3's pattern for Durable's views from other objects: the object that opens Durable contributes its Harness. */
+const Harnesses = defineRegistry<Native<Harness>, Harness | undefined>("app.harnesses", { version: 1 });
+
+/** Opens a Harness (a new one per attempt), contributes it, and follows its task graph: its Session closing fails it. */
+const Durable = local("app.durable", { version: 1, params: {}, members: { close: method(), write: method(str()) } });
+
+/** Follows the root conversation's entry kinds through the contributed Harness, from another object. */
+const Viewer = local("app.viewer", { version: 1, params: {}, members: { kinds: arr(str()) } });
+
+function serveViews(host: FacetHost): void {
+	host.serve(Harnesses, { compose: (table) => table.at(-1)?.value.value });
+	host.serve(Durable, (_, self) => {
+		const harness = self.open(
+			async (open) => {
+				const opened = await Harness.open(
+					new MemoryStorage(),
+					{ models: createModels(), registry: createRegistry() },
+					open,
+				);
+				await opened.root(open);
+				return opened;
+			},
+			(h, _reason, close) => h.close(close),
+		);
+		self.contribute(Harnesses, harness);
+		self.follow((observer, ctx) => harness.value.observeTaskGraph(observer, ctx));
+		return {
+			close: async (ctx) => {
+				await harness.value.close(ctx);
+				return null;
+			},
+			write: async (kind, ctx) => {
+				const root = await harness.value.conversation(ROOT_CONVERSATION_ID, ctx);
+				await root!.submit({ type: "write", entry: { kind } }, ctx);
+				return null;
+			},
+		};
+	});
+	host.serve(Viewer, (_, self) => {
+		const harness = self.registry(Harnesses);
+		self.retryOn(harness);
+		const view = self.follow(async (observer, ctx) =>
+			harness.value === undefined
+				? undefined
+				: harness.value.observeConversation(ROOT_CONVERSATION_ID, observer, ctx),
+		);
+		return { kinds: self.derive([view], ([v]) => v.entries.map((entry) => entry.kind)) };
+	});
+}
+
+describe("Durable's views from other objects (slice 8 §5, S1)", () => {
+	it("a follower of a contributed Harness fails when that Harness's Session closes, and follows the next one", async () => {
+		const host = createHost({ onError: () => {} });
+		await host.load([{ name: "@app/core", facet: defineFacet(serveViews) }], context);
+		const durable = host.hold(Durable, {}, context);
+		const viewer = host.hold(Viewer, {}, context);
+		await new Promise((resolve) => setTimeout(resolve, 10));
+		await durable.write("app.first", context);
+		await new Promise((resolve) => setTimeout(resolve, 10));
+		expect(viewer.kinds.value).toContain("app.first");
+		// The Session closes: both followers fail `transient` (S1); a retry opens the next Harness, whose contribution
+		// wakes the viewer (`retryOn`), which follows it.
+		// The call is cut off by its object's failure: the Session's close fails the object that opened it.
+		await expect(durable.close(context)).rejects.toThrow("session closed");
+		await new Promise((resolve) => setTimeout(resolve, 10));
+		expect(viewer.state.value).toMatchObject({ kind: "failed", cause: { kind: "transient" } });
+		durable.retry();
+		await new Promise((resolve) => setTimeout(resolve, 50));
+		expect(viewer.state.value).toEqual({ kind: "live" });
+		expect(viewer.kinds.value).not.toContain("app.first");
+		await durable.write("app.second", context);
+		await new Promise((resolve) => setTimeout(resolve, 10));
+		expect(viewer.kinds.value).toContain("app.second");
+		await host.close(context);
+	});
+});

packages/durable/test/session-observers.test.ts

@@ -173,13 +173,31 @@ describe("observeDoc", () => {
 		expect(calls).toEqual([]);
 	});
 
-	it("ends once when the Session closes", async () => {
+	it("ends once when the Session closes, `failed` (S1: an adapter follows the next Session), a watch `ended`", async () => {
 		const { storage, session } = open();
 		await add(session);
 		const { calls, observer } = recorder(storage);
 		await session.observeDoc(SessionCounter, observer, context);
+		const watch = (await session.watchDoc(SessionCounter, context))!;
 		await session.close(context);
-		expect(calls).toEqual([{ end: { kind: "ended" } }]);
+		expect(calls).toEqual([{ end: { kind: "failed", error: new Error("session closed") } }]);
+		expect(await watch.closed).toEqual({ kind: "ended" });
+	});
+
+	it("ends each close's observers with an error of that close, not one shared by every Session", async () => {
+		const errors: unknown[] = [];
+		for (let i = 0; i < 2; i++) {
+			const { session } = open();
+			await add(session);
+			await session.observeDoc(
+				SessionCounter,
+				{ advance: () => {}, end: (end) => errors.push(end.kind === "failed" ? end.error : end) },
+				context,
+			);
+			await session.close(context);
+		}
+		expect(errors).toEqual([new Error("session closed"), new Error("session closed")]);
+		expect(errors[0]).not.toBe(errors[1]);
 	});
 
 	it("ends with the error that failed the Session", async () => {
@@ -368,14 +386,18 @@ describe("observeCommits", () => {
 		return { calls, observer };
 	}
 
-	it("gets every stored commit, then `ended` once the Session closed, after its last publication", async () => {
+	it("gets every stored commit, then `failed` once the Session closed (S1), after its last publication", async () => {
 		const { session } = open();
 		const { calls, observer } = commits();
 		session.observeCommits(observer);
 		await add(session);
 		await add(session);
 		await session.close(context);
-		expect(calls).toEqual([{ seq: expect.any(Number) }, { seq: expect.any(Number) }, { end: { kind: "ended" } }]);
+		expect(calls).toEqual([
+			{ seq: expect.any(Number) },
+			{ seq: expect.any(Number) },
+			{ end: { kind: "failed", error: new Error("session closed") } },
+		]);
 	});
 
 	it("ends `failed` with the error that failed the Session", async () => {