pi-roundtable 0.7.19 → 0.9.0

package/src/core/http/websocket.ts

@@ -0,0 +1,316 @@
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Logger } from "../log.ts";
+
+/**
+ * What became of one `send`: written to the connection, `"queued"` behind a client that reads
+ * slower than the route sends, or `"dropped"` because the socket is closed, or because
+ * `maxBufferedBytes` were already waiting and the socket was cut for it.
+ */
+export type WebSocketSendResult = "sent" | "queued" | "dropped";
+
+/** One socket a WebSocket route accepted, with the data its `accept` gave. */
+export interface RouteSocket<Data = unknown> {
+	readonly data: Data;
+	send(message: string | Uint8Array): WebSocketSendResult;
+	close(code?: number, reason?: string): void;
+}
+
+/** What `accept` answers: the socket's data to upgrade with, or a response that refuses it. */
+export type WebSocketAccept<Data = unknown> =
+	| { data: Data; headers?: Record<string, string> }
+	| Response;
+
+/**
+ * The WebSocket half of an HTTP route. An upgrade request on the route's path passes the Origin
+ * check, then `accept`, which authenticates it before any socket opens; other requests still
+ * reach the route's `handle`.
+ */
+export interface WebSocketRoute<Data = unknown> {
+	/**
+	 * The `Origin` values a browser may connect from, each as `scheme://host[:port]` exactly as the
+	 * browser sends it, such as `https://chat.example.com` or `chrome-extension://<id>`; a request
+	 * with another Origin, or none, is refused with 403 before `accept`. `"any"` skips the check,
+	 * for clients that are not browsers.
+	 */
+	origins: readonly string[] | "any";
+	/** Authenticates and authorizes the upgrade; a thrown error answers 500 like a failing `handle`. */
+	accept(
+		request: Request,
+	): WebSocketAccept<Data> | Promise<WebSocketAccept<Data>>;
+	/**
+	 * The largest message in bytes; a larger one closes the socket with 1009. Default 64 KiB. A
+	 * message over twice the listener's largest limit drops the connection before it is read.
+	 */
+	maxMessageBytes?: number;
+	/** At most `messages` per `perMs` from one socket; one more closes it with 1008. Default 120 a minute. */
+	rate?: { messages: number; perMs: number };
+	/**
+	 * The most bytes one socket may have waiting for a client that reads slower than the route
+	 * sends. It is checked before each `send`: a `send` that finds this many waiting returns
+	 * `"dropped"` and cuts the socket without a close frame, so the client and the route's `close`
+	 * both see 1006; one that finds fewer is sent whole, so the bytes waiting can reach this limit
+	 * plus one message. Default 1 MiB.
+	 */
+	maxBufferedBytes?: number;
+	/** The most sockets the route holds open at once; another upgrade gets 503 before `accept`. Default 256. */
+	maxConnections?: number;
+	/** What a handler returns is ignored; a promise is awaited. */
+	open?(socket: RouteSocket<Data>): unknown | Promise<unknown>;
+	/** Called per message as it arrives, without waiting for the previous call to settle. */
+	message(
+		socket: RouteSocket<Data>,
+		message: string | Uint8Array,
+	): unknown | Promise<unknown>;
+	/** Called once the socket closed, also when the listener stops (code 1001); stop waits for it. */
+	close?(
+		socket: RouteSocket<Data>,
+		code: number,
+		reason: string,
+	): unknown | Promise<unknown>;
+}
+
+export const DEFAULT_MAX_MESSAGE_BYTES = 64 * 1024;
+export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;
+const DEFAULT_MAX_CONNECTIONS = 256;
+const DEFAULT_RATE = { messages: 120, perMs: 60_000 };
+
+/** The close codes RFC 6455 names for the reasons this module closes a socket. */
+const GOING_AWAY = 1001;
+const POLICY_VIOLATION = 1008;
+const TOO_BIG = 1009;
+const INTERNAL_ERROR = 1011;
+
+/** What the server keeps on each socket: its route, the route's socket, and its rate window. */
+export interface Connection {
+	route: string;
+	websocket: WebSocketRoute;
+	data: unknown;
+	socket?: RouteSocket;
+	windowStart: number;
+	count: number;
+}
+
+/** Whether the request asks to become a WebSocket: a GET with `Upgrade: websocket`. */
+export const isUpgrade = (request: Request): boolean =>
+	request.method === "GET" &&
+	request.headers.get("upgrade")?.toLowerCase() === "websocket";
+
+/** Whether an upgrade request carries the key and the version 13 that RFC 6455 requires. */
+const completeHandshake = (request: Request): boolean =>
+	Boolean(request.headers.get("sec-websocket-key")) &&
+	request.headers.get("sec-websocket-version") === "13";
+
+const originAllowed = (route: WebSocketRoute, origin: string | null) =>
+	route.origins === "any" ||
+	(origin !== null && route.origins.includes(origin));
+
+const byteLength = (message: string | Uint8Array) =>
+	typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+
+/**
+ * Sends one message unless the route's `maxBufferedBytes` already wait; then, or when Bun drops
+ * the message, the socket is cut (1006) rather than left open with a gap in what it was sent.
+ * Bun answers 0 for an empty message it did send, and for a message it dropped.
+ */
+function send(
+	ws: ServerWebSocket<Connection>,
+	message: string | Uint8Array,
+): WebSocketSendResult {
+	if (ws.readyState !== WebSocket.OPEN) return "dropped";
+	const limit =
+		ws.data.websocket.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+	if (ws.getBufferedAmount() < limit) {
+		const status = ws.send(message);
+		if (ws.readyState !== WebSocket.OPEN) return "dropped";
+		if (status > 0 || (status === 0 && byteLength(message) === 0))
+			return "sent";
+		if (status === -1) return "queued";
+	}
+	ws.terminate();
+	return "dropped";
+}
+
+/** Resolves after `promise` settles or `ms` passes, whichever comes first. */
+async function settledWithin(promise: Promise<unknown>, ms: number) {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	await Promise.race([
+		promise,
+		new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, ms);
+		}),
+	]);
+	clearTimeout(timer);
+}
+
+/**
+ * The open sockets of one host's listeners and the handler calls still running on them. A route
+ * handler that throws or rejects closes its socket with 1011 and logs the route and listener,
+ * never the URL.
+ */
+export class SocketSet {
+	readonly #open = new Set<ServerWebSocket<Connection>>();
+	readonly #running = new Set<Promise<void>>();
+	/** Each route's open sockets plus the upgrades still in `accept`. */
+	readonly #held = new Map<WebSocketRoute, number>();
+	readonly #logger: Logger;
+
+	constructor(logger: Logger) {
+		this.#logger = logger;
+	}
+
+	/**
+	 * Upgrades a request for a WebSocket route. A handshake without a key or version 13 is 400, a
+	 * refused Origin 403, and a route at `maxConnections` 503, all before `accept`; the response
+	 * `accept` returns is sent as it is, and a throwing `accept` is passed to the caller like a
+	 * failing `handle`. Answers nothing once the socket is upgraded.
+	 */
+	async upgrade(
+		name: string,
+		websocket: WebSocketRoute,
+		request: Request,
+		server: Server<Connection>,
+	): Promise<Response | undefined> {
+		if (!completeHandshake(request))
+			return new Response("Bad Request", { status: 400 });
+		if (!originAllowed(websocket, request.headers.get("origin")))
+			return new Response("Forbidden", { status: 403 });
+		const held = this.#held.get(websocket) ?? 0;
+		if (held >= (websocket.maxConnections ?? DEFAULT_MAX_CONNECTIONS))
+			return new Response("Service Unavailable", { status: 503 });
+		// The place is taken while `accept` runs, so concurrent upgrades cannot overshoot it.
+		this.#held.set(websocket, held + 1);
+		let upgraded = false;
+		try {
+			const accepted = await websocket.accept(request);
+			if (accepted instanceof Response) return accepted;
+			const connection: Connection = {
+				route: name,
+				websocket,
+				data: accepted.data,
+				windowStart: Date.now(),
+				count: 0,
+			};
+			// Bun runs `open` inside `upgrade`, and `close` releases the place from then on.
+			upgraded = server.upgrade(request, {
+				data: connection,
+				...(accepted.headers ? { headers: accepted.headers } : {}),
+			});
+			return upgraded
+				? undefined
+				: new Response("Bad Request", { status: 400 });
+		} finally {
+			if (!upgraded) this.#release(websocket);
+		}
+	}
+
+	#release(websocket: WebSocketRoute): void {
+		const held = (this.#held.get(websocket) ?? 1) - 1;
+		if (held > 0) this.#held.set(websocket, held);
+		else this.#held.delete(websocket);
+	}
+
+	/**
+	 * The Bun handler for one listener's sockets, given its largest route limits. Bun drops a frame
+	 * over twice the message limit unread; up to there each route's own limit closes with 1009.
+	 * Bun drops a message only when the largest buffered limit already waits, which each route's
+	 * `send` checks first at its own limit, so a single message larger than any limit still goes out.
+	 */
+	handler(
+		listener: string,
+		limits: { maxMessageBytes: number; maxBufferedBytes: number },
+	): WebSocketHandler<Connection> {
+		return {
+			maxPayloadLength: limits.maxMessageBytes * 2,
+			backpressureLimit: limits.maxBufferedBytes,
+			open: (ws) => {
+				this.#open.add(ws);
+				const connection = ws.data;
+				connection.socket = {
+					data: connection.data,
+					send: (message) => send(ws, message),
+					close: (code, reason) => ws.close(code, reason),
+				};
+				const { open } = connection.websocket;
+				if (open) this.#run(ws, listener, (socket) => open(socket));
+			},
+			message: (ws, message) => {
+				const connection = ws.data;
+				const { websocket } = connection;
+				const limit = websocket.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+				if (byteLength(message) > limit) {
+					ws.close(TOO_BIG, "message too big");
+					return;
+				}
+				const rate = websocket.rate ?? DEFAULT_RATE;
+				const now = Date.now();
+				if (now - connection.windowStart >= rate.perMs) {
+					connection.windowStart = now;
+					connection.count = 0;
+				}
+				connection.count += 1;
+				if (connection.count > rate.messages) {
+					ws.close(POLICY_VIOLATION, "too many messages");
+					return;
+				}
+				this.#run(ws, listener, (socket) => websocket.message(socket, message));
+			},
+			close: (ws, code, reason) => {
+				this.#open.delete(ws);
+				this.#release(ws.data.websocket);
+				const { close } = ws.data.websocket;
+				if (close)
+					this.#run(ws, listener, (socket) => close(socket, code, reason));
+			},
+		};
+	}
+
+	/** Runs one route handler, tracked until it settles; a failure closes the socket. */
+	#run(
+		ws: ServerWebSocket<Connection>,
+		listener: string,
+		call: (socket: RouteSocket) => unknown | Promise<unknown>,
+	): Promise<void> {
+		const connection = ws.data;
+		const running = (async () => {
+			try {
+				if (connection.socket) await call(connection.socket);
+			} catch (err) {
+				this.#logger.error(
+					{ err, route: connection.route, listener },
+					"websocket handler failed",
+				);
+				ws.close(INTERNAL_ERROR, "internal error");
+			}
+		})();
+		this.#running.add(running);
+		void running.finally(() => this.#running.delete(running));
+		return running;
+	}
+
+	/** Closes every open socket with 1001, so each route's `close` runs. */
+	closeAll(): void {
+		for (const ws of this.#open) ws.close(GOING_AWAY, "server stopping");
+	}
+
+	/**
+	 * Waits, at most `timeoutMs`, until every socket has closed and every handler call has settled;
+	 * a close the server reports later, or a call it starts meanwhile, is waited for too.
+	 */
+	async drain(timeoutMs: number): Promise<void> {
+		const deadline = Date.now() + timeoutMs;
+		while (this.#open.size > 0 || this.#running.size > 0) {
+			const left = deadline - Date.now();
+			if (left <= 0) {
+				this.#logger.warn(
+					{ open: this.#open.size, running: this.#running.size },
+					"websocket handlers still running after the close timeout",
+				);
+				return;
+			}
+			await settledWithin(
+				Promise.allSettled([...this.#running]),
+				Math.min(left, 10),
+			);
+		}
+	}
+}

package/src/core/i18n/cards.ts

@@ -11,11 +11,12 @@ export function cardsEn(ctx: CatalogContext) {
 		cardStopped: "⏹️ This round was stopped.",
 		cardExpired: "⌛ Timed out with no answer.",
 		cardOwnerOnly: `Only ${ctx.assistant}'s owner can answer this card.`,
-		cardApproversNote: (minTier: string) =>
-			`-# Who can approve: ${minTier} and above`,
-		cardApproversRefusal: (minTier: string) =>
-			`This card needs ${minTier} or above to answer.`,
-		cardAskerNote: (userId: string) => `-# Who can answer: <@${userId}>`,
+		cardApproversNote: (...userIds: readonly string[]) =>
+			`-# Who can approve: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
+		cardApproversRefusal:
+			"This approval is for the speaker whose turn asked for it.",
+		cardAskerNote: (...userIds: readonly string[]) =>
+			`-# Who can answer: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "This question is for another speaker.",
 		cardInactive: `This card is no longer active (it timed out, or ${ctx.assistant} restarted); reply in text if you need to.`,
 		cardApproved: "✅ Approved to run.",
@@ -42,10 +43,11 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardStopped: "⏹️ 這一輪已停止。",
 		cardExpired: "⌛ 已逾時，沒有回答。",
 		cardOwnerOnly: `只有 ${ctx.assistant} 的擁有者能回答這張卡片。`,
-		cardApproversNote: (minTier: string) => `-# 可以核准的人：${minTier} 以上`,
-		cardApproversRefusal: (minTier: string) =>
-			`這張卡片要 ${minTier} 以上才能回答。`,
-		cardAskerNote: (userId: string) => `-# 可以回答的人：<@${userId}>`,
+		cardApproversNote: (...userIds: readonly string[]) =>
+			`-# 可以核准的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
+		cardApproversRefusal: "這張核准卡是給提出這一輪的發話者的。",
+		cardAskerNote: (...userIds: readonly string[]) =>
+			`-# 可以回答的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "這張問題是問另一位發話者的。",
 		cardInactive: `這張卡片已經失效（逾時，或 ${ctx.assistant} 重新啟動過）；需要的話直接打字回覆。`,
 		cardApproved: "✅ 已核准執行。",

package/src/core/identity/access-policy.ts

@@ -0,0 +1,227 @@
+import type { Pronouns } from "../config/config.ts";
+import { ConfigError } from "../domain/errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type {
+	SpeakerFacts,
+	SpeakerMap,
+	SpeakerPolicy,
+	Tier,
+	TierMembers,
+} from "../speakers.ts";
+import {
+	type ActorFacts,
+	identityOf,
+	parseIdentity,
+	surfaceOf,
+} from "./actor-facts.ts";
+import { SYSTEM_PRINCIPAL } from "./principal-store.ts";
+
+/** One owner the configuration names: whom they are, and the identities that are theirs. */
+export interface AccessOwner {
+	name: string;
+	pronouns?: Pronouns;
+	/** Their principal's id, such as the 0.8 `owner.id`; without it, a new `p_` principal is made at the first boot and found again by the identities after. */
+	principal?: string;
+	/** `<provider>:<subject>` strings, such as `discord:<user id>` or `token:remote-mcp`. */
+	identities: readonly string[];
+}
+
+/**
+ * Who holds a tier besides the owners: identities, roles, or everyone. Roles are written
+ * `<surface>:role:<name>`. `everyone: true` admits everyone on every surface, a list only on
+ * those surfaces.
+ */
+export interface AccessTier {
+	identities?: readonly string[];
+	roles?: readonly string[];
+	everyone?: boolean | readonly string[];
+}
+
+/** Who the host serves, and at which tier. */
+export interface AccessRules {
+	/** The owners, the first of them the primary owner. The owner tier comes only from here or the CLI, never from a role a surface reports. */
+	owners: readonly AccessOwner[];
+	admins?: AccessTier;
+	members?: AccessTier;
+	/** `admitted`: someone the rules admit gets a principal at first contact, and a 0.8 speaker claims theirs; `linked`: only identities already linked, such as by the CLI or the configuration, are served. Owners are never admitted. */
+	provisioning: "admitted" | "linked";
+	/** How many days a principal whose tier came only from the rules on contact may go unseen before their background turns are refused. */
+	backgroundStaleDays: number;
+}
+
+const holds = (
+	tier: AccessTier | undefined,
+	facts: ActorFacts,
+	surface: string,
+): boolean => {
+	if (!tier) return false;
+	const { everyone } = tier;
+	if (everyone === true) return true;
+	if (Array.isArray(everyone) && everyone.includes(surface)) return true;
+	if (tier.identities?.includes(identityOf(facts))) return true;
+	return (facts.roles ?? []).some((role) => tier.roles?.includes(role));
+};
+
+/**
+ * The tier the rules give these facts on this contact: admin, member, or none. Never owner: an
+ * owner is one by the configuration's owners or a lasting role, not by what a surface reports.
+ */
+export function factsTier(
+	rules: Pick<AccessRules, "admins" | "members">,
+	facts: ActorFacts,
+	conversation?: ChannelKey,
+): Exclude<Tier, "owner"> | undefined {
+	const surface = surfaceOf(facts, conversation);
+	if (holds(rules.admins, facts, surface)) return "admin";
+	if (holds(rules.members, facts, surface)) return "member";
+	return undefined;
+}
+
+/** The configured owner whose identities include these facts', if any. */
+export function ownerOfFacts(
+	rules: Pick<AccessRules, "owners">,
+	facts: ActorFacts,
+): AccessOwner | undefined {
+	const identity = identityOf(facts);
+	return rules.owners.find((owner) => owner.identities.includes(identity));
+}
+
+const ROLE = /^[^:]+:role:.+$/;
+
+function checkTier(tier: AccessTier | undefined, path: string): void {
+	if (!tier) return;
+	tier.identities?.forEach((identity, i) => {
+		if (!parseIdentity(identity))
+			throw new ConfigError(
+				`config ${path}.identities[${i}]: expected <provider>:<subject>, got ${JSON.stringify(identity)}. Write it like discord:<user id>; roundtable principal list prints them.`,
+			);
+	});
+	tier.roles?.forEach((role, i) => {
+		if (!ROLE.test(role))
+			throw new ConfigError(
+				`config ${path}.roles[${i}]: expected <surface>:role:<name>, got ${JSON.stringify(role)}. Write it like discord:role:<role id> or web:role:<role name>.`,
+			);
+	});
+}
+
+/** The rules, checked: identities and roles well formed, no identity or principal under two owners, no owner as the system principal. */
+export function checkAccessRules(rules: AccessRules): AccessRules {
+	const seenIdentity = new Map<string, number>();
+	const seenPrincipal = new Map<string, number>();
+	rules.owners.forEach((owner, n) => {
+		const path = `access.owners[${n}]`;
+		if (owner.principal === SYSTEM_PRINCIPAL)
+			throw new ConfigError(
+				`config ${path}.principal: "${SYSTEM_PRINCIPAL}" is the host's own principal. Give the owner's own id, or leave principal out.`,
+			);
+		if (owner.principal === undefined && owner.identities.length === 0)
+			throw new ConfigError(
+				`config ${path}: give the owner a principal id or at least one identity, so each boot finds the same principal.`,
+			);
+		if (owner.principal !== undefined) {
+			const other = seenPrincipal.get(owner.principal);
+			if (other !== undefined)
+				throw new ConfigError(
+					`config ${path}.principal: access.owners[${other}] has the same principal ${owner.principal}. Merge the two owners into one.`,
+				);
+			seenPrincipal.set(owner.principal, n);
+		}
+		owner.identities.forEach((identity, i) => {
+			if (!parseIdentity(identity))
+				throw new ConfigError(
+					`config ${path}.identities[${i}]: expected <provider>:<subject>, got ${JSON.stringify(identity)}. Write it like discord:<user id>; roundtable principal list prints them.`,
+				);
+			const other = seenIdentity.get(identity);
+			if (other !== undefined)
+				throw new ConfigError(
+					`config ${path}.identities[${i}]: ${identity} is also listed under access.owners[${other}]. An identity is one person's; keep it under one owner.`,
+				);
+			seenIdentity.set(identity, n);
+		});
+	});
+	checkTier(rules.admins, "access.admins");
+	checkTier(rules.members, "access.members");
+	if (
+		!(
+			Number.isInteger(rules.backgroundStaleDays) &&
+			rules.backgroundStaleDays > 0
+		)
+	)
+		throw new ConfigError(
+			`config access.backgroundStaleDays: expected a positive whole number of days, got ${JSON.stringify(rules.backgroundStaleDays)}.`,
+		);
+	return rules;
+}
+
+function tierOfMembers(
+	members: TierMembers | undefined,
+	provider: string,
+): AccessTier | undefined {
+	if (!members) return undefined;
+	return {
+		...(members.users
+			? { identities: members.users.map((id) => `${provider}:${id}`) }
+			: {}),
+		...(members.roles
+			? { roles: members.roles.map((role) => `${provider}:role:${role}`) }
+			: {}),
+		...(members.everyone === undefined
+			? {}
+			: { everyone: members.everyone ? [provider] : false }),
+	};
+}
+
+/**
+ * The rules a 0.8 speaker map means on one surface: its owners by id, its users as identities of
+ * that surface, its roles as that surface's roles, and `everyone` as everyone there.
+ */
+export function rulesOfSpeakerMap(
+	map: SpeakerMap,
+	provider = "discord",
+): Pick<AccessRules, "owners" | "admins" | "members"> {
+	const admins = tierOfMembers(map.admins, provider);
+	const members = tierOfMembers(map.members, provider);
+	return {
+		owners: map.owners.map((id) => ({
+			name: id,
+			principal: id,
+			identities: [`${provider}:${id}`],
+		})),
+		...(admins ? { admins } : {}),
+		...(members ? { members } : {}),
+	};
+}
+
+/**
+ * The 0.8 policy over these rules on one surface, for the code that still resolves a speaker
+ * from a surface's facts by itself: an author is an owner when one of the owners lists their
+ * identity there, and otherwise holds the tier the rules give them. Each speaker's principal is
+ * their own id, as for a person carried over from 0.8; the identity service knows the others.
+ */
+export function speakerPolicyOf(
+	rules: Pick<AccessRules, "owners" | "admins" | "members">,
+	provider = "discord",
+): SpeakerPolicy {
+	return {
+		resolve(author: SpeakerFacts) {
+			const facts: ActorFacts = {
+				provider,
+				subject: author.id,
+				name: author.name,
+				surface: provider,
+				roles: (author.roleIds ?? []).map((role) => `${provider}:role:${role}`),
+			};
+			const tier: Tier | undefined = ownerOfFacts(rules, facts)
+				? "owner"
+				: factsTier(rules, facts);
+			return (
+				tier && {
+					id: author.id,
+					name: author.name,
+					tier,
+					principalId: author.id,
+				}
+			);
+		},
+	};
+}

package/src/core/identity/actor-facts.ts

@@ -0,0 +1,65 @@
+import { parseChannelKey } from "../contract/surface.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { IdentityRef } from "./principal-store.ts";
+
+/**
+ * What a surface reports about the person behind a message or a connection; the identity
+ * service decides who they are and the tier they hold.
+ */
+export interface ActorFacts {
+	/** The identity provider: `discord`, `oidc:<base64url issuer>`, `token`, … */
+	provider: string;
+	/** The person's id at the provider. */
+	subject: string;
+	/** The name to address them by on this contact. */
+	name: string;
+	/** The roles they hold, each prefixed with its surface: `discord:role:<id>`, `web:role:<name>`. */
+	roles?: readonly string[];
+	/**
+	 * The surface they reached the host through, as `everyone` lists name it, such as `discord` or
+	 * `web`; default the conversation's surface, then the provider up to its first colon.
+	 */
+	surface?: string;
+	/** Where on the surface, such as a guild; informational. */
+	space?: string;
+	/**
+	 * The speaker id 0.8 gave this person, which a principal carried over from 0.8 has as its id:
+	 * the user id on Discord, `oidc:<issuer>:<subject>` on the web. At first contact it claims that
+	 * principal. It is also the speaker's `id`, the id the surface knows them by.
+	 */
+	legacyId?: string;
+}
+
+/** An identity as configuration and the CLI write it: `<provider>:<subject>`. */
+export function identityOf(ref: IdentityRef): string {
+	return `${ref.provider}:${ref.subject}`;
+}
+
+/**
+ * An identity string read back: the provider is the part before the first colon, and for `oidc`
+ * the issuer after it too, so `oidc:<issuer>:<subject>` is the 0.8 web speaker id. Undefined
+ * when a part is missing.
+ */
+export function parseIdentity(identity: string): IdentityRef | undefined {
+	const first = identity.indexOf(":");
+	if (first <= 0) return undefined;
+	let cut = first;
+	if (identity.slice(0, first) === "oidc") {
+		cut = identity.indexOf(":", first + 1);
+		if (cut <= first + 1) return undefined;
+	}
+	const subject = identity.slice(cut + 1);
+	if (subject === "") return undefined;
+	return { provider: identity.slice(0, cut), subject };
+}
+
+/** The surface the facts came through: their own, the conversation's, or the provider's first part. */
+export function surfaceOf(
+	facts: ActorFacts,
+	conversation?: ChannelKey,
+): string {
+	if (facts.surface) return facts.surface;
+	if (conversation) return parseChannelKey(conversation).surface;
+	const colon = facts.provider.indexOf(":");
+	return colon < 0 ? facts.provider : facts.provider.slice(0, colon);
+}