pi-roundtable 0.7.19 → 0.9.0

package/src/core/runtime/session-scope.ts

@@ -0,0 +1,78 @@
+import { existsSync } from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { TurnConversation } from "../domain/ports.ts";
+import { archiveSessions } from "./session-archive.ts";
+
+/** The custom entry a session's history records whom it served in. */
+export const SCOPE_ENTRY = "roundtable-conversation";
+
+/** Whom a conversation serves, as a session's history records it. */
+type Scope = Pick<TurnConversation, "visibility"> & { principalId?: string };
+
+function scopeOf(conversation: Scope): TurnConversation {
+	return conversation.visibility === "private" &&
+		conversation.principalId !== undefined
+		? { visibility: "private", principalId: conversation.principalId }
+		: { visibility: "shared" };
+}
+
+/** Whether two scopes are the same: shared both, or private to the same principal. */
+export function sameScope(a: Scope, b: Scope): boolean {
+	return JSON.stringify(scopeOf(a)) === JSON.stringify(scopeOf(b));
+}
+
+/** The scope the history last recorded, or undefined when it records none, as before 0.9. */
+function recordedScope(manager: SessionManager): TurnConversation | undefined {
+	const entry = manager
+		.getEntries()
+		.findLast(
+			(entry) => entry.type === "custom" && entry.customType === SCOPE_ENTRY,
+		);
+	return entry?.type === "custom"
+		? scopeOf(entry.data as TurnConversation)
+		: undefined;
+}
+
+/**
+ * The latest history in `dir` for a session of the scope. A history recorded in another scope is
+ * archived, so the session starts with none: one person's conversation never replays for someone
+ * else, nor a private one in a shared one or the other way. A history that records no scope, as
+ * one made before 0.9, carries on. The history the session continues records its scope.
+ */
+export function scopedHistory(
+	dir: string,
+	cwd: string,
+	scope: Scope,
+): { history: SessionManager; archived: number } {
+	let history = SessionManager.continueRecent(cwd, dir);
+	const recorded = recordedScope(history);
+	let archived = 0;
+	if (recorded && !sameScope(recorded, scope)) {
+		archived = archiveSessions(dir);
+		history = SessionManager.continueRecent(cwd, dir);
+	}
+	if (!recorded || archived > 0)
+		history.appendCustomEntry(SCOPE_ENTRY, scopeOf(scope));
+	return { history, archived };
+}
+
+/** The scope the latest history in `dir` records, if any. */
+export function historyScope(
+	dir: string,
+	cwd: string,
+): TurnConversation | undefined {
+	if (!existsSync(dir)) return undefined;
+	return recordedScope(SessionManager.continueRecent(cwd, dir));
+}
+
+/**
+ * The messages of the latest history in `dir`, read without opening a session, so reading them
+ * fixes no scope; none when it was recorded in another scope than `scope`.
+ */
+export function historyMessages(dir: string, cwd: string, scope: Scope) {
+	if (!existsSync(dir)) return [];
+	const history = SessionManager.continueRecent(cwd, dir);
+	const recorded = recordedScope(history);
+	if (recorded && !sameScope(recorded, scope)) return [];
+	return history.buildSessionContext().messages;
+}

package/src/core/runtime/steerable-run.ts

@@ -1,7 +1,16 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { TurnAttachments } from "../domain/attachment.ts";
 
 export type PromptImages = NonNullable<Parameters<AgentSession["steer"]>[1]>;
 
+/** A turn's images as Pi takes them with a prompt or a steer. */
+export function promptImages(attachments: TurnAttachments): PromptImages {
+	return attachments.images.map((image) => ({
+		type: "image" as const,
+		...image,
+	}));
+}
+
 /** The part of a Pi session a steerable run drives. */
 export type SteeringSession = Pick<
 	AgentSession,

package/src/core/runtime/tool-call-scope.ts

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** The ids of the tool calls whose code is running, outermost first. */
+const calls = new AsyncLocalStorage<readonly string[]>();
+
+/**
+ * The ids of the tool calls the code asking runs within, outermost first: the call of a session
+ * part's tool, and the calls it runs within in turn, such as a worker's call inside the call that
+ * started the worker. Empty outside every such call.
+ */
+export function runningCalls(): readonly string[] {
+	return calls.getStore() ?? [];
+}
+
+/**
+ * A session part's extension whose tools each run within their call's id, so what a call starts,
+ * a task's worker among them, knows which call it serves rather than every call running at once.
+ */
+export function scopedCalls(factory: ExtensionFactory): ExtensionFactory {
+	return (pi) =>
+		factory(
+			new Proxy(pi, {
+				get(target, key) {
+					if (key === "registerTool")
+						return (tool: ToolDefinition) =>
+							target.registerTool({
+								...tool,
+								execute: (toolCallId, ...rest) =>
+									calls.run([...runningCalls(), toolCallId], () =>
+										tool.execute(toolCallId, ...rest),
+									),
+							});
+					const value: unknown = Reflect.get(target, key, target);
+					return typeof value === "function" ? value.bind(target) : value;
+				},
+			}) satisfies ExtensionAPI,
+		);
+}

package/src/core/runtime/turn-answer.ts

@@ -1,7 +1,8 @@
-import type { TurnResult } from "../domain/conversation.ts";
+import type { TranscriptEntry, TurnResult } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
 import { hasReplyFiles } from "../reply-files.ts";
 import { lastAssistant, textOf } from "../shared/session-messages.ts";
+import { TRANSCRIPT_ENTRY_CHARS } from "./runtime-types.ts";
 
 interface MessagePart {
 	type?: unknown;
@@ -20,6 +21,34 @@ type Assistant = Message & {
 const isAssistant = (message: Message): message is Assistant =>
 	message.role === "assistant";
 
+/** The answer to a turn sent without a speaker: refused, never run as the owner's by default. */
+export function unspokenTurn(): TurnResult {
+	return {
+		ok: false,
+		error: new AgentRunError(
+			"a turn needs a speaker: pass TurnRequest.speaker, the person the turn is for; for a turn started on someone's behalf, get theirs from IDENTITY.speakerFor",
+		),
+	};
+}
+
+/** The last `limit` user and assistant messages as transcript entries, each cut to its first characters. */
+export function transcriptOf(
+	messages: readonly (Message & { content?: unknown })[],
+	limit: number,
+): TranscriptEntry[] {
+	const entries: TranscriptEntry[] = [];
+	for (const message of messages) {
+		if (message.role !== "user" && message.role !== "assistant") continue;
+		const text = textOf(message.content).trim();
+		if (text)
+			entries.push({
+				role: message.role,
+				text: text.slice(0, TRANSCRIPT_ENTRY_CHARS),
+			});
+	}
+	return entries.slice(-limit);
+}
+
 /** The session's last answer, which tells the judge what a short follow-up continues. */
 export function lastReply(messages: readonly Message[]): string | undefined {
 	const last = messages.findLast(isAssistant);

package/src/core/runtime/turn-progress.ts

@@ -0,0 +1,116 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { TurnProgress } from "../domain/progress.ts";
+
+/** How long text is joined before it is sent, so a fast stream costs a few events a second. */
+export const PROGRESS_INTERVAL_MS = 250;
+/** The longest preview of a tool's arguments, ellipsis included. */
+export const PROGRESS_PREVIEW_CHARS = 80;
+
+/** One turn's progress as the runtime reports it; every method returns at once and never throws. */
+export interface ProgressReporter {
+	text(delta: string): void;
+	toolStart(id: string, tool: string, args: unknown): void;
+	toolEnd(id: string, tool: string, isError: boolean): void;
+	/** Reports a session's event: its text deltas and its tools' starts and ends, never the thinking. */
+	observe(event: AgentSessionEvent): void;
+	/** Sends the text not sent yet; nothing is sent after it. */
+	close(): void;
+}
+
+export interface ProgressReporterOptions {
+	intervalMs?: number;
+	/** Runs `run` after `ms`; returns a cancel. Replaceable in tests. */
+	setTimer?: (run: () => void, ms: number) => () => void;
+}
+
+const realTimer = (run: () => void, ms: number) => {
+	const timer = setTimeout(run, ms);
+	timer.unref?.();
+	return () => clearTimeout(timer);
+};
+
+/** One line of a tool's arguments, cut to the preview length; undefined for none. */
+export function toolPreview(args: unknown): string | undefined {
+	let text: string | undefined;
+	try {
+		text = args === undefined ? undefined : JSON.stringify(args);
+	} catch {
+		return undefined;
+	}
+	if (!text || text === "{}" || text === "[]") return undefined;
+	const line = text.replace(/\s+/g, " ");
+	return line.length > PROGRESS_PREVIEW_CHARS
+		? `${line.slice(0, PROGRESS_PREVIEW_CHARS - 1)}…`
+		: line;
+}
+
+/**
+ * Turns a session's text deltas and tool events into `TurnProgress`. Text is joined and sent at
+ * most once per interval, and always before a tool event, so the order the turn wrote in holds.
+ * A sink that throws loses that event only.
+ */
+export function progressReporter(
+	sink: (event: TurnProgress) => void,
+	options: ProgressReporterOptions = {},
+): ProgressReporter {
+	const intervalMs = options.intervalMs ?? PROGRESS_INTERVAL_MS;
+	const setTimer = options.setTimer ?? realTimer;
+	let buffered = "";
+	let cancel: (() => void) | undefined;
+	let closed = false;
+	const send = (event: TurnProgress) => {
+		try {
+			sink(event);
+		} catch {
+			// The surface's failure is its own; the turn goes on without that event.
+		}
+	};
+	const flush = () => {
+		cancel?.();
+		cancel = undefined;
+		if (buffered === "") return;
+		const delta = buffered;
+		buffered = "";
+		send({ type: "text", delta });
+	};
+	const reporter: ProgressReporter = {
+		observe(event) {
+			if (
+				event.type === "message_update" &&
+				event.assistantMessageEvent.type === "text_delta"
+			)
+				reporter.text(event.assistantMessageEvent.delta);
+			else if (event.type === "tool_execution_start")
+				reporter.toolStart(event.toolCallId, event.toolName, event.args);
+			else if (event.type === "tool_execution_end")
+				reporter.toolEnd(event.toolCallId, event.toolName, event.isError);
+		},
+		text(delta) {
+			if (closed || delta === "") return;
+			buffered += delta;
+			cancel ??= setTimer(flush, intervalMs);
+		},
+		toolStart(id, tool, args) {
+			if (closed) return;
+			flush();
+			const preview = toolPreview(args);
+			send({
+				type: "tool_start",
+				id,
+				tool,
+				...(preview === undefined ? {} : { preview }),
+			});
+		},
+		toolEnd(id, tool, isError) {
+			if (closed) return;
+			flush();
+			send({ type: "tool_end", id, tool, ok: !isError });
+		},
+		close() {
+			if (closed) return;
+			flush();
+			closed = true;
+		},
+	};
+	return reporter;
+}

package/src/core/services.ts

@@ -1,11 +1,16 @@
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
-import type { ScheduledOutcome } from "./contract/channels.ts";
+import type {
+	BackgroundRunsAs,
+	ScheduledOutcome,
+} from "./contract/channels.ts";
 import type { AgentRuntime } from "./contract/runtime.ts";
 import { type ServiceKey, serviceKey } from "./contract/services.ts";
+import type { ConversationRegistry } from "./conversations/conversation-registry.ts";
 import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
+import type { IdentityService } from "./identity/identity-service.ts";
 import type { ThinkingSetting } from "./models.ts";
 import type {
 	DelegationJob,
@@ -35,6 +40,25 @@ import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
 // interface, so an object with the same methods satisfies it without being one of the built-in
 // classes; a plugin replaces a built-in by providing its own under the same key.
 
+/**
+ * Who the host serves: its principals, the identities linked to each, and their lasting roles.
+ * Provided by the `identity` plugin, which every host registers first, so every plugin may read it.
+ */
+export const IDENTITY: ServiceKey<IdentityService> =
+	serviceKey<IdentityService>("roundtable.identity");
+/**
+ * The runtime every conversation turn runs on: the agent server's, and each turn run through
+ * `context.turns`. The `runtime` provider slot's when a plugin fills it, Pi's otherwise. Provided
+ * by the `runtime` plugin, which every host registers, with or without the agent server.
+ */
+export const RUNTIME: ServiceKey<AgentRuntime> =
+	serviceKey<AgentRuntime>("roundtable.runtime");
+/**
+ * The conversations run through `context.turns`: who each belongs to, its kind and visibility,
+ * and when it was last active, recorded at its first turn. Provided by the `conversations` plugin.
+ */
+export const CONVERSATIONS: ServiceKey<ConversationRegistry> =
+	serviceKey<ConversationRegistry>("roundtable.conversations");
 /** The agent server: its team, its directory, the runtime that runs every agent turn. Provided by the agent-server plugin. */
 export const AGENTS: ServiceKey<AgentServer> =
 	serviceKey<AgentServer>("roundtable.agents");
@@ -84,7 +108,7 @@ export interface AgentServer {
 	team: AgentTeam;
 	/** Read-only lookups of agents and groups; edits go through the team. */
 	directory: AgentDirectory;
-	/** The runtime every agent-server turn runs on: the `runtime` provider's, or Pi's when no plugin fills the slot. */
+	/** The runtime every agent-server turn runs on: the same one `RUNTIME` provides. */
 	runtime: AgentRuntime;
 	/** Decides whether the owner's reply approves the actions the assistant held for them. */
 	approvals: {
@@ -164,6 +188,16 @@ export interface AgentTeam {
 /** Scheduled turns, stored. A one-time schedule is deleted once it fires. */
 export interface ScheduleStore {
 	create(schedule: NewSchedule): Promise<Schedule>;
+	/**
+	 * Creates a schedule unless its creator already has `limit.max` of its target's schedules,
+	 * counting those whose creator id is one of `limit.creators`; resolves the count reached instead.
+	 * Two calls for one creator never count at once, so creates at once in many conversations stay
+	 * within the limit.
+	 */
+	createWithin(
+		schedule: NewSchedule,
+		limit: { creators: readonly string[]; max: number },
+	): Promise<{ created: Schedule } | { reached: number }>;
 	get(id: number): Promise<Schedule | undefined>;
 	forChannel(channel: ChannelKey): Promise<Schedule[]>;
 	all(): Promise<Schedule[]>;
@@ -194,6 +228,12 @@ export interface BackgroundTurns {
 		firedAt: Date,
 		finding?: PrecheckFinding,
 	): Promise<ScheduledOutcome>;
+	/**
+	 * Who a due schedule's turn would run as now, checked as the turn is: asked before its
+	 * precheck, which runs only for a creator who may run the turn, at the tier it would run at.
+	 * Throws when the identity service cannot tell.
+	 */
+	runsAs(schedule: Schedule): Promise<BackgroundRunsAs>;
 	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
 	runDelegated(job: DelegationJob, result: DelegationOutcome): Promise<void>;
 	/** The process's own logged error, reported to an agent in its channel as a report turn. */

package/src/core/sessions.ts

@@ -1,5 +1,7 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { PluginError } from "./errors.ts";
+import type { Principal } from "./identity/principal-store.ts";
+import type { OwnerIdentity } from "./identity.ts";
 import type { Speaker } from "./speakers.ts";
 
 /** `<surface>:<channel id>`, for example `discord:1234`. A DM is one channel. */
@@ -41,6 +43,15 @@ export interface TransientTask {
 	onFinished?(toolCalls: readonly string[]): void;
 }
 
+/**
+ * Whom a session's conversation serves, fixed when the session is made: `private` to one
+ * principal, whose name and pronouns are known when the host has a record of them, or `shared`
+ * by whoever its claim admits, as an agent's session always is.
+ */
+export type SessionConversation =
+	| { visibility: "private"; principalId: string; principal?: Principal }
+	| { visibility: "shared" };
+
 /** What one Pi session is for, as a session tool's factory sees it. */
 export interface SessionContext {
 	/** "agent" for an agent's session; otherwise the kind of conversation, which the claim that owns the channel names. */
@@ -53,6 +64,25 @@ export interface SessionContext {
 	agent?: AgentTurnScope;
 	/** Wraps a compactor so the core's compaction tiers decide when it may answer. */
 	compaction: { wrap(compactor: ExtensionFactory): ExtensionFactory };
+	/**
+	 * Whom the conversation serves, as `TurnRequest.conversation` or the host's record says when the
+	 * session is made; shared when neither says. A private conversation's tools serve its person:
+	 * their memory, their notices. A shared one's serve each turn's speaker.
+	 */
+	conversation: SessionConversation;
+	/**
+	 * Whom the session's tool descriptions address, fixed when it is made: a private conversation's
+	 * person by their name and pronouns, the primary owner exactly as 0.8 wrote them, and
+	 * `THE_SPEAKER` in a shared conversation, where each turn's prompt says who speaks.
+	 */
+	addressee: OwnerIdentity;
+	/**
+	 * Whose memory the session's turns may read: `"speaker"` (the default), as `conversation` and
+	 * each turn's speaker decide, or `"none"`, for a persona that declares it; then no memory loads.
+	 * While the running turn is one the agent server keeps out of memory (`AgentSessions.memory`),
+	 * it reads `"none"` for that turn alone.
+	 */
+	memory: "speaker" | "none";
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */

package/src/core/shared/unix-server.ts

@@ -1,5 +1,5 @@
 import { rmSync } from "node:fs";
-import type { Server } from "bun";
+import type { Server, WebSocketHandler } from "bun";
 
 /**
  * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
@@ -9,18 +9,48 @@ import type { Server } from "bun";
  */
 export function serveUnix(
 	socketPath: string,
-	fetch: (request: Request) => Response | Promise<Response>,
-	options: { error?: (error: Error) => Response | Promise<Response> } = {},
-): Server<undefined> {
+	fetch: (
+		request: Request,
+		server: Server<undefined>,
+	) => Response | Promise<Response>,
+	options?: { error?: (error: Error) => Response | Promise<Response> },
+): Server<undefined>;
+/**
+ * Serves HTTP and WebSockets on a unix socket: `websocket` serves the sockets `fetch` upgrades
+ * with `server.upgrade`, and `fetch` answers nothing for a request it upgraded.
+ */
+export function serveUnix<WebSocketData>(
+	socketPath: string,
+	fetch: (
+		request: Request,
+		server: Server<WebSocketData>,
+	) => Response | undefined | Promise<Response | undefined>,
+	options: {
+		error?: (error: Error) => Response | Promise<Response>;
+		websocket: WebSocketHandler<WebSocketData>;
+	},
+): Server<WebSocketData>;
+export function serveUnix<WebSocketData>(
+	socketPath: string,
+	fetch: (
+		request: Request,
+		server: Server<WebSocketData>,
+	) => Response | undefined | Promise<Response | undefined>,
+	options: {
+		error?: (error: Error) => Response | Promise<Response>;
+		websocket?: WebSocketHandler<WebSocketData>;
+	} = {},
+): Server<WebSocketData> {
 	rmSync(socketPath, { force: true });
 	const serveOptions = {
 		unix: socketPath,
 		idleTimeout: 0,
 		fetch,
 		...(options.error ? { error: options.error } : {}),
+		...(options.websocket ? { websocket: options.websocket } : {}),
 	};
 	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
 	return Bun.serve(
 		serveOptions as unknown as Parameters<typeof Bun.serve>[0],
-	) as Server<undefined>;
+	) as unknown as Server<WebSocketData>;
 }

package/src/core/speakers.ts

@@ -1,4 +1,8 @@
 import { freeze } from "./freeze.ts";
+import {
+	rulesOfSpeakerMap,
+	speakerPolicyOf,
+} from "./identity/access-policy.ts";
 import type { OwnerIdentity } from "./identity.ts";
 
 /** How much a speaker may do: `owner` above `admin` above `member`. */
@@ -12,9 +16,16 @@ export function tierAtLeast(tier: Tier, least: Tier): boolean {
 
 /** A person whose message starts a turn, and the tier the policy gave them. */
 export interface Speaker {
+	/** The id the surface knows them by: a Discord user id, a web chat's `oidc:<issuer>:<subject>`. */
 	id: string;
 	name: string;
 	tier: Tier;
+	/**
+	 * The principal they are, whose memory, schedules, and conversations are theirs on every
+	 * surface. For a person carried over from 0.8 it equals `id`. The identity service sets it;
+	 * whoever starts a turn for someone else takes it from `IDENTITY.speakerFor`.
+	 */
+	principalId: string;
 }
 
 /**
@@ -59,7 +70,10 @@ export function attributed(speaker: Speaker, text: string): string {
 	return `(Message from ${speaker.name}, at the ${speaker.tier} tier.)\n\n${text}`;
 }
 
-/** What a surface reports about the author of a message; the policy decides the rest. */
+/**
+ * What a surface reports about the author of a message; the policy decides the rest. The 0.8
+ * form of `ActorFacts` from the identity service, with the surface's own ids and role ids.
+ */
 export interface SpeakerFacts {
 	id: string;
 	name: string;
@@ -92,23 +106,11 @@ export interface SpeakerMap {
 	members?: TierMembers;
 }
 
-/** The policy of an operator's map; the highest tier an author qualifies for wins. */
+/**
+ * The policy of an operator's map; the highest tier an author qualifies for wins. It evaluates
+ * the access rules the map means on one surface, so it decides as the identity service's rules
+ * do; each speaker's principal is their own id, as for a person carried over from 0.8.
+ */
 export function speakerPolicy(map: SpeakerMap): SpeakerPolicy {
-	const holds = (tier: TierMembers | undefined, author: SpeakerFacts) =>
-		tier !== undefined &&
-		(tier.everyone === true ||
-			tier.users?.includes(author.id) === true ||
-			(author.roleIds ?? []).some((role) => tier.roles?.includes(role)));
-	const tierOf = (author: SpeakerFacts): Tier | undefined => {
-		if (map.owners.includes(author.id)) return "owner";
-		if (holds(map.admins, author)) return "admin";
-		if (holds(map.members, author)) return "member";
-		return undefined;
-	};
-	return {
-		resolve(author) {
-			const tier = tierOf(author);
-			return tier && { id: author.id, name: author.name, tier };
-		},
-	};
+	return speakerPolicyOf(rulesOfSpeakerMap(map));
 }

package/src/core/testing/background.ts

@@ -0,0 +1,31 @@
+import type { BackgroundRunsAs, BackgroundTurn } from "../contract/channels.ts";
+import type { Schedule } from "../modules/schedules/schedule-store.ts";
+
+/** A conversation port's `runsAs` for tests: every turn runs as its author, at its own tier. */
+export async function runsAsAuthor(
+	turn: BackgroundTurn,
+): Promise<BackgroundRunsAs> {
+	const { author, tier } = turn;
+	return {
+		speaker: {
+			id: author.id,
+			name: author.name,
+			tier,
+			principalId: author.principalId,
+		},
+	};
+}
+
+/** A scheduled runner's `runsAs` for tests: every schedule runs as its creator, at the tier it was set at. */
+export async function runsAsCreator(
+	schedule: Schedule,
+): Promise<BackgroundRunsAs> {
+	return {
+		speaker: {
+			id: schedule.createdById,
+			name: schedule.createdByName,
+			tier: schedule.createdTier,
+			principalId: schedule.createdById,
+		},
+	};
+}

package/src/core/testing/fixture-database.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SQL } from "bun";
+import { testDatabaseUrl } from "./database.ts";
+
+/** A scratch database on the test server; drop it when the test ends. */
+export interface ScratchDatabase {
+	url: string;
+	sql: SQL;
+	drop(): Promise<void>;
+}
+
+/**
+ * A new, empty database on the test server, or one loaded from a recorded fixture such as
+ * `"0.8.0"` (src/core/testing/fixtures/db-<version>.sql, written by scripts/fixture-db.ts). It
+ * needs PostgreSQL: run it under `describeDb`.
+ */
+export async function scratchDatabase(
+	fixture?: string,
+): Promise<ScratchDatabase> {
+	const name = `roundtable_scratch_${crypto.randomUUID().replaceAll("-", "")}`;
+	let url: URL;
+	try {
+		url = new URL(testDatabaseUrl);
+	} catch {
+		throw new Error(
+			`ROUNDTABLE_TEST_DATABASE_URL is not a postgres url: ${testDatabaseUrl}`,
+		);
+	}
+	url.pathname = `/${name}`;
+	const server = new SQL(testDatabaseUrl, { max: 1 });
+	await server.unsafe(`CREATE DATABASE ${name}`);
+	await server.close();
+	const sql = new SQL(url.href, { max: 4 });
+	if (fixture)
+		await sql.unsafe(
+			readFileSync(
+				join(import.meta.dir, "fixtures", `db-${fixture}.sql`),
+				"utf8",
+			),
+		);
+	return {
+		url: url.href,
+		sql,
+		drop: async () => {
+			await sql.close();
+			const admin = new SQL(testDatabaseUrl, { max: 1 });
+			try {
+				await admin.unsafe(`DROP DATABASE IF EXISTS ${name} WITH (FORCE)`);
+			} finally {
+				await admin.close();
+			}
+		},
+	};
+}