pi-roundtable 0.7.19 → 0.9.0

package/src/core/identity/principal-reads.ts

@@ -0,0 +1,38 @@
+import { type Speaker, type Tier, tierAtLeast } from "../speakers.ts";
+import { type ActorFacts, identityOf } from "./actor-facts.ts";
+import type { Principal, PrincipalRecord } from "./principal-store.ts";
+
+/** The speaker of a contact: the id the surface knows them by, their 0.8 id where they have one. */
+export const speakerOf = (
+	facts: ActorFacts,
+	principalId: string,
+	tier: Tier,
+): Speaker => ({
+	id: facts.legacyId ?? identityOf(facts),
+	name: facts.name,
+	tier,
+	principalId,
+});
+
+/** The highest of the tiers given, undefined for none. */
+export const highest = (
+	tiers: readonly (Tier | undefined)[],
+): Tier | undefined =>
+	tiers.reduce<Tier | undefined>(
+		(best, tier) =>
+			tier !== undefined && (best === undefined || tierAtLeast(tier, best))
+				? tier
+				: best,
+		undefined,
+	);
+
+/** The lower of two tiers. */
+export const lowest = (a: Tier, b: Tier): Tier => (tierAtLeast(a, b) ? b : a);
+
+/** A stored principal as the identity service shows it. */
+export const publicOf = (record: PrincipalRecord): Principal => ({
+	id: record.id,
+	displayName: record.displayName,
+	...(record.pronouns ? { pronouns: record.pronouns } : {}),
+	disabled: record.disabled,
+});

package/src/core/identity/principal-store.ts

@@ -0,0 +1,478 @@
+import type { SQL } from "bun";
+import type { Pronouns } from "../config/config.ts";
+import { IdentityError } from "../domain/errors.ts";
+import type { Tier } from "../speakers.ts";
+import { isPrincipalId, newPrincipalId } from "./ulid.ts";
+
+/** The principal the host's own turns run as: an ops report, a webhook's. It has no identity, cannot sign in, and keeps no memory. */
+export const SYSTEM_PRINCIPAL = "system";
+
+/**
+ * The provider of a 0.8 speaker id that stands for a principal of another id, linked at the
+ * upgrade; no surface reports it, so no one resolves through it.
+ */
+export const LEGACY_PROVIDER = "legacy";
+
+/** 0.8's speaker id for the owner writing through an outside agent over MCP: the primary owner. */
+export const LEGACY_REMOTE_SPEAKER = "remote-mcp";
+
+export type { Pronouns };
+
+/** A person the host serves, whichever surface they reach it through. */
+export interface Principal {
+	/** Opaque: a speaker id carried over from 0.8, or `p_<ulid>` for one made since. */
+	id: string;
+	displayName: string;
+	pronouns?: Pronouns;
+	disabled: boolean;
+}
+
+/** A principal as stored, with when it was made and when it was last seen. */
+export interface PrincipalRecord extends Principal {
+	locale?: string;
+	timeZone?: string;
+	createdAt: Date;
+	lastSeenAt?: Date;
+	/** The tier it was last seen at; it only ever lowers what a background turn may do, never grants. */
+	lastTier?: Tier;
+	/** Whether the person of its 0.8 speaker id may still claim it: only one the backfill made, until any identity is linked to it. */
+	claimable: boolean;
+}
+
+/** An identity on one provider: `discord` and a user id, `oidc:<issuer>` and a subject, `token` and a name. */
+export interface IdentityRef {
+	provider: string;
+	subject: string;
+}
+
+/**
+ * How an identity came to be linked: by the configuration, a plugin declaring it
+ * (`RoundtablePlugin.identities`), the CLI, admission on first contact, or a 0.8 speaker id claimed.
+ */
+export type LinkSource = "config" | "plugin" | "cli" | "jit" | "legacy";
+
+/** Which source a link made again by another becomes: the configuration's over all, a plugin's over the rest. */
+const LINK_RANK: Readonly<Record<LinkSource, number>> = {
+	config: 2,
+	plugin: 1,
+	cli: 0,
+	jit: 0,
+	legacy: 0,
+};
+
+export interface IdentityLink extends IdentityRef {
+	principalId: string;
+	source: LinkSource;
+	linkedAt: Date;
+}
+
+/** Where a role came from. The configuration's are synced at every boot; a CLI grant stays until the CLI revokes it. */
+export type RoleSource = "config" | "cli";
+
+export interface RoleGrant {
+	role: Tier;
+	source: RoleSource;
+	grantedAt: Date;
+}
+
+/** A principal holding a role, and where the role came from. */
+export interface RoleHolder {
+	principalId: string;
+	source: RoleSource;
+}
+
+export interface NewPrincipal {
+	/** The id to keep, for a principal carried over from 0.8; otherwise a new `p_` id is made. */
+	id?: string;
+	displayName: string;
+	pronouns?: Pronouns;
+}
+
+/** The principals, their linked identities, and their lasting roles. */
+export interface PrincipalStore {
+	get(id: string): Promise<PrincipalRecord | undefined>;
+	list(): Promise<PrincipalRecord[]>;
+	/** Refuses an id already taken, and the system principal's. */
+	create(input: NewPrincipal): Promise<PrincipalRecord>;
+	/** Changes the name or the pronouns; `pronouns: null` clears them. */
+	update(
+		id: string,
+		change: { displayName?: string; pronouns?: Pronouns | null },
+	): Promise<PrincipalRecord | undefined>;
+	/**
+	 * Links the identity to the principal; linking it again to the same one changes nothing, but
+	 * that the configuration linking it makes the link the configuration's, and a plugin linking it
+	 * makes one the CLI, a first contact, or a claim made the plugin's; to another one is refused. A
+	 * principal with any identity linked is no longer claimable, even after the identity is
+	 * unlinked, except by a plugin's link: a plugin's credential is not the person's own identity,
+	 * so it leaves their 0.8 claim to them.
+	 */
+	link(
+		principalId: string,
+		identity: IdentityRef,
+		source: LinkSource,
+	): Promise<IdentityLink>;
+	/**
+	 * The identity's link, claiming the principal for it when the identity is still unlinked and
+	 * the principal claimable and not an owner; undefined when it may not be claimed. A principal
+	 * is claimed at most once. A claim names the principal `displayName`, when given, while its
+	 * name is still its id, as the backfill names someone it knows no name of; a real name stays.
+	 */
+	claim(
+		principalId: string,
+		identity: IdentityRef,
+		displayName?: string,
+	): Promise<IdentityLink | undefined>;
+	/**
+	 * The identity's link, making a new `p_` principal for it, of `id` when given, when it is still
+	 * unlinked; however many contacts admit it at once, one principal is made.
+	 */
+	admit(
+		identity: IdentityRef,
+		displayName: string,
+		id?: string,
+	): Promise<IdentityLink>;
+	/** Whether there was a link to remove. */
+	unlink(provider: string, subject: string): Promise<boolean>;
+	identity(
+		provider: string,
+		subject: string,
+	): Promise<IdentityLink | undefined>;
+	identitiesOf(principalId: string): Promise<IdentityLink[]>;
+	/** Every link made by `source`, such as the configuration's. */
+	linksFrom(source: LinkSource): Promise<IdentityLink[]>;
+	/** Grants a lasting role. A CLI grant is kept as the CLI's even when the configuration grants the same role. */
+	grant(principalId: string, role: Tier, source: RoleSource): Promise<void>;
+	/** Revokes the role, or only the grant from `source`; whether there was one to revoke. */
+	revoke(
+		principalId: string,
+		role: Tier,
+		source?: RoleSource,
+	): Promise<boolean>;
+	rolesOf(principalId: string): Promise<RoleGrant[]>;
+	/** Every principal holding the role. */
+	holders(role: Tier): Promise<RoleHolder[]>;
+	disable(id: string): Promise<void>;
+	enable(id: string): Promise<void>;
+	/** Records that the principal was seen at `at` (default now), at this tier, or null when refused. */
+	touch(id: string, tier: Tier | null, at?: Date): Promise<void>;
+}
+
+interface PrincipalRow {
+	id: string;
+	display_name: string;
+	pronouns: Pronouns | null;
+	locale: string | null;
+	time_zone: string | null;
+	created_at: Date;
+	disabled_at: Date | null;
+	last_seen_at: Date | null;
+	last_tier: Tier | null;
+	claimable: boolean;
+}
+
+interface IdentityRow {
+	provider: string;
+	subject: string;
+	principal_id: string;
+	source: LinkSource;
+	linked_at: Date;
+}
+
+interface RoleRow {
+	role: Tier;
+	source: RoleSource;
+	granted_at: Date;
+}
+
+function principalOf(row: PrincipalRow): PrincipalRecord {
+	return {
+		id: row.id,
+		displayName: row.display_name,
+		...(row.pronouns === null ? {} : { pronouns: row.pronouns }),
+		disabled: row.disabled_at !== null,
+		...(row.locale === null ? {} : { locale: row.locale }),
+		...(row.time_zone === null ? {} : { timeZone: row.time_zone }),
+		createdAt: row.created_at,
+		...(row.last_seen_at === null ? {} : { lastSeenAt: row.last_seen_at }),
+		...(row.last_tier === null ? {} : { lastTier: row.last_tier }),
+		claimable: row.claimable,
+	};
+}
+
+function linkOf(row: IdentityRow): IdentityLink {
+	return {
+		provider: row.provider,
+		subject: row.subject,
+		principalId: row.principal_id,
+		source: row.source,
+		linkedAt: row.linked_at,
+	};
+}
+
+/** The advisory lock a first contact of this identity holds, so two contacts at once make one link. */
+const identityLock = (identity: IdentityRef) =>
+	`pi-roundtable:identity:${identity.provider}\n${identity.subject}`;
+
+/** The principal store over the `principals`, `principal_identities`, and `principal_roles` tables. */
+export class PgPrincipalStore implements PrincipalStore {
+	readonly #sql: SQL;
+
+	private constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	/** The store over the host's migrated pool. */
+	static async attach(sql: SQL): Promise<PgPrincipalStore> {
+		return new PgPrincipalStore(sql);
+	}
+
+	async get(id: string): Promise<PrincipalRecord | undefined> {
+		const rows: PrincipalRow[] = await this.#sql`
+			SELECT * FROM principals WHERE id = ${id}`;
+		const [row] = rows;
+		return row ? principalOf(row) : undefined;
+	}
+
+	async list(): Promise<PrincipalRecord[]> {
+		const rows: PrincipalRow[] = await this.#sql`
+			SELECT * FROM principals ORDER BY created_at, id`;
+		return rows.map(principalOf);
+	}
+
+	async create(input: NewPrincipal): Promise<PrincipalRecord> {
+		const id = input.id ?? newPrincipalId();
+		if (id === SYSTEM_PRINCIPAL)
+			throw new IdentityError(
+				`"${SYSTEM_PRINCIPAL}" is the host's own principal; give another id`,
+			);
+		const rows: PrincipalRow[] = await this.#sql`
+			INSERT INTO principals (id, display_name, pronouns)
+			VALUES (${id}, ${input.displayName}, ${input.pronouns ?? null})
+			ON CONFLICT (id) DO NOTHING
+			RETURNING *`;
+		const [row] = rows;
+		if (!row) throw new IdentityError(`principal ${id} already exists`);
+		return principalOf(row);
+	}
+
+	async update(
+		id: string,
+		change: { displayName?: string; pronouns?: Pronouns | null },
+	): Promise<PrincipalRecord | undefined> {
+		const keepPronouns = change.pronouns === undefined;
+		const rows: PrincipalRow[] = await this.#sql`
+			UPDATE principals SET
+				display_name = COALESCE(${change.displayName ?? null}::text, display_name),
+				pronouns = CASE WHEN ${keepPronouns}::boolean THEN pronouns ELSE ${change.pronouns ?? null}::text END
+			WHERE id = ${id}
+			RETURNING *`;
+		const [row] = rows;
+		return row ? principalOf(row) : undefined;
+	}
+
+	async link(
+		principalId: string,
+		identity: IdentityRef,
+		source: LinkSource,
+	): Promise<IdentityLink> {
+		if (principalId === SYSTEM_PRINCIPAL)
+			throw new IdentityError(
+				`the host's own principal "${SYSTEM_PRINCIPAL}" has no identities`,
+			);
+		const { provider, subject } = identity;
+		// The same lock, and the same order of writes, as a first contact's claim of this identity,
+		// so the two at once queue instead of deadlocking.
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${identityLock(identity)}, 0))`;
+			const linked: IdentityRow[] = await tx`
+				SELECT * FROM principal_identities WHERE provider = ${provider} AND subject = ${subject}`;
+			const [existing] = linked;
+			if (existing) {
+				if (existing.principal_id !== principalId)
+					throw new IdentityError(
+						`${provider}:${subject} is already linked to principal ${existing.principal_id}; unlink it first`,
+					);
+				if (LINK_RANK[source] <= LINK_RANK[existing.source])
+					return linkOf(existing);
+				// The configuration or a plugin names it now, so it is theirs to unlink.
+				const owned: IdentityRow[] = await tx`
+					UPDATE principal_identities SET source = ${source}
+					WHERE provider = ${provider} AND subject = ${subject}
+					RETURNING *`;
+				return linkOf(owned[0] ?? existing);
+			}
+			const spent =
+				source === "plugin"
+					? await tx`SELECT id FROM principals WHERE id = ${principalId}`
+					: await tx`
+						UPDATE principals SET claimable = false WHERE id = ${principalId}
+						RETURNING id`;
+			if (spent.length === 0)
+				throw new IdentityError(`there is no principal ${principalId}`);
+			const made: IdentityRow[] = await tx`
+				INSERT INTO principal_identities (provider, subject, principal_id, source)
+				VALUES (${provider}, ${subject}, ${principalId}, ${source})
+				RETURNING *`;
+			const [link] = made;
+			if (!link)
+				throw new IdentityError(`could not link ${provider}:${subject}`);
+			return linkOf(link);
+		});
+	}
+
+	async claim(
+		principalId: string,
+		identity: IdentityRef,
+		displayName?: string,
+	): Promise<IdentityLink | undefined> {
+		const name = displayName?.trim() || null;
+		const { provider, subject } = identity;
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${identityLock(identity)}, 0))`;
+			const linked: IdentityRow[] = await tx`
+				SELECT * FROM principal_identities WHERE provider = ${provider} AND subject = ${subject}`;
+			if (linked[0]) return linkOf(linked[0]);
+			// Named in the same write that spends the claim, so a claim that fails renames no one.
+			const taken = await tx`
+				UPDATE principals SET
+					claimable = false,
+					display_name = CASE WHEN display_name = id AND ${name}::text IS NOT NULL
+						THEN ${name}::text ELSE display_name END
+				WHERE id = ${principalId} AND claimable AND NOT EXISTS (
+					SELECT 1 FROM principal_roles WHERE principal_id = ${principalId} AND role = 'owner'
+				)
+				RETURNING id`;
+			if (taken.length === 0) return undefined;
+			const made: IdentityRow[] = await tx`
+				INSERT INTO principal_identities (provider, subject, principal_id, source)
+				VALUES (${provider}, ${subject}, ${principalId}, 'legacy')
+				RETURNING *`;
+			return made[0] && linkOf(made[0]);
+		});
+	}
+
+	async admit(
+		identity: IdentityRef,
+		displayName: string,
+		id = newPrincipalId(),
+	): Promise<IdentityLink> {
+		const { provider, subject } = identity;
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${identityLock(identity)}, 0))`;
+			const linked: IdentityRow[] = await tx`
+				SELECT * FROM principal_identities WHERE provider = ${provider} AND subject = ${subject}`;
+			if (linked[0]) return linkOf(linked[0]);
+			if (!isPrincipalId(id))
+				throw new IdentityError(`a new principal's id is p_<ulid>, not ${id}`);
+			await tx`INSERT INTO principals (id, display_name) VALUES (${id}, ${displayName})`;
+			const made: IdentityRow[] = await tx`
+				INSERT INTO principal_identities (provider, subject, principal_id, source)
+				VALUES (${provider}, ${subject}, ${id}, 'jit')
+				RETURNING *`;
+			const [link] = made;
+			if (!link)
+				throw new IdentityError(`could not link ${provider}:${subject}`);
+			return linkOf(link);
+		});
+	}
+
+	async unlink(provider: string, subject: string): Promise<boolean> {
+		const rows = await this.#sql`
+			DELETE FROM principal_identities WHERE provider = ${provider} AND subject = ${subject}
+			RETURNING provider`;
+		return rows.length > 0;
+	}
+
+	async identity(
+		provider: string,
+		subject: string,
+	): Promise<IdentityLink | undefined> {
+		const rows: IdentityRow[] = await this.#sql`
+			SELECT * FROM principal_identities WHERE provider = ${provider} AND subject = ${subject}`;
+		const [row] = rows;
+		return row ? linkOf(row) : undefined;
+	}
+
+	async identitiesOf(principalId: string): Promise<IdentityLink[]> {
+		const rows: IdentityRow[] = await this.#sql`
+			SELECT * FROM principal_identities WHERE principal_id = ${principalId}
+			ORDER BY provider, subject`;
+		return rows.map(linkOf);
+	}
+
+	async linksFrom(source: LinkSource): Promise<IdentityLink[]> {
+		const rows: IdentityRow[] = await this.#sql`
+			SELECT * FROM principal_identities WHERE source = ${source}
+			ORDER BY provider, subject`;
+		return rows.map(linkOf);
+	}
+
+	async grant(
+		principalId: string,
+		role: Tier,
+		source: RoleSource,
+	): Promise<void> {
+		const rows = await this.#sql`
+			INSERT INTO principal_roles (principal_id, role, source)
+			SELECT id, ${role}, ${source} FROM principals WHERE id = ${principalId}
+			ON CONFLICT (principal_id, role) DO UPDATE SET
+				source = CASE WHEN principal_roles.source = 'cli' THEN 'cli' ELSE EXCLUDED.source END
+			RETURNING role`;
+		if (rows.length === 0)
+			throw new IdentityError(`there is no principal ${principalId}`);
+	}
+
+	async revoke(
+		principalId: string,
+		role: Tier,
+		source?: RoleSource,
+	): Promise<boolean> {
+		const rows =
+			source === undefined
+				? await this.#sql`
+					DELETE FROM principal_roles WHERE principal_id = ${principalId} AND role = ${role}
+					RETURNING role`
+				: await this.#sql`
+					DELETE FROM principal_roles
+					WHERE principal_id = ${principalId} AND role = ${role} AND source = ${source}
+					RETURNING role`;
+		return rows.length > 0;
+	}
+
+	async rolesOf(principalId: string): Promise<RoleGrant[]> {
+		const rows: RoleRow[] = await this.#sql`
+			SELECT role, source, granted_at FROM principal_roles WHERE principal_id = ${principalId}
+			ORDER BY role`;
+		return rows.map((row) => ({
+			role: row.role,
+			source: row.source,
+			grantedAt: row.granted_at,
+		}));
+	}
+
+	async holders(role: Tier): Promise<RoleHolder[]> {
+		const rows: { principal_id: string; source: RoleSource }[] = await this
+			.#sql`
+			SELECT principal_id, source FROM principal_roles WHERE role = ${role}
+			ORDER BY principal_id`;
+		return rows.map((row) => ({
+			principalId: row.principal_id,
+			source: row.source,
+		}));
+	}
+
+	async disable(id: string): Promise<void> {
+		await this.#sql`
+			UPDATE principals SET disabled_at = COALESCE(disabled_at, now()) WHERE id = ${id}`;
+	}
+
+	async enable(id: string): Promise<void> {
+		await this.#sql`UPDATE principals SET disabled_at = NULL WHERE id = ${id}`;
+	}
+
+	async touch(id: string, tier: Tier | null, at = new Date()): Promise<void> {
+		await this.#sql`
+			UPDATE principals SET last_seen_at = ${at}, last_tier = ${tier} WHERE id = ${id}`;
+	}
+}

package/src/core/identity/principal-tables.ts

@@ -0,0 +1,53 @@
+import type { SQL } from "bun";
+
+/** The tables of principals, their identities, and their roles. */
+export const PRINCIPAL_TABLES = async (sql: SQL): Promise<void> => {
+	await sql`
+		CREATE TABLE IF NOT EXISTS principals (
+			id text PRIMARY KEY,
+			display_name text NOT NULL,
+			pronouns text CHECK (pronouns IN ('he', 'she', 'they')),
+			locale text,
+			time_zone text,
+			created_at timestamptz NOT NULL DEFAULT now(),
+			disabled_at timestamptz,
+			last_seen_at timestamptz,
+			last_tier text CHECK (last_tier IN ('member', 'admin', 'owner'))
+		)`;
+	await sql`
+		CREATE TABLE IF NOT EXISTS principal_identities (
+			provider text NOT NULL,
+			subject text NOT NULL,
+			principal_id text NOT NULL REFERENCES principals (id) ON DELETE CASCADE,
+			linked_at timestamptz NOT NULL DEFAULT now(),
+			source text NOT NULL CHECK (source IN ('config', 'cli', 'jit', 'legacy')),
+			PRIMARY KEY (provider, subject)
+		)`;
+	await sql`
+		CREATE INDEX IF NOT EXISTS principal_identities_principal
+		ON principal_identities (principal_id)`;
+	await sql`
+		CREATE TABLE IF NOT EXISTS principal_roles (
+			principal_id text NOT NULL REFERENCES principals (id) ON DELETE CASCADE,
+			role text NOT NULL CHECK (role IN ('member', 'admin', 'owner')),
+			source text NOT NULL CHECK (source IN ('config', 'cli')),
+			granted_at timestamptz NOT NULL DEFAULT now(),
+			PRIMARY KEY (principal_id, role)
+		)`;
+};
+
+/**
+ * Whether the person of a carried-over principal's 0.8 id may still claim it: its own migration,
+ * so a database whose principals table an earlier build made gets the column too.
+ */
+export const PRINCIPALS_CLAIMABLE = async (sql: SQL): Promise<void> => {
+	await sql`ALTER TABLE principals ADD COLUMN IF NOT EXISTS claimable boolean NOT NULL DEFAULT false`;
+};
+
+/** Links a plugin declares: their own source, beside the four the tables were made with. */
+export const PRINCIPAL_PLUGIN_LINKS = async (sql: SQL): Promise<void> => {
+	await sql`ALTER TABLE principal_identities DROP CONSTRAINT IF EXISTS principal_identities_source_check`;
+	await sql`
+		ALTER TABLE principal_identities ADD CONSTRAINT principal_identities_source_check
+		CHECK (source IN ('config', 'plugin', 'cli', 'jit', 'legacy'))`;
+};

package/src/core/identity/seen-throttle.ts

@@ -0,0 +1,57 @@
+import type { Tier } from "../speakers.ts";
+
+/** How often being seen is written for one principal, unless the tier changes. */
+const TOUCH_MS = 5 * 60_000;
+
+/** What was last written for one principal. */
+interface Seen {
+	at: number;
+	/** The tier written, null for a refusal. */
+	tier: Tier | null;
+	/** When they last came back from a refusal. */
+	back?: number;
+	/** Until when they are held at no tier for being refused and served by turns. */
+	flapping?: number;
+}
+
+/**
+ * When being seen is written for each principal: at most every `TOUCH_MS` at the same tier, at
+ * once when the tier changes, and a refusal whenever the store still holds a tier for them.
+ * Someone refused and served by turns, such as by the roles of two Discord servers, is held at
+ * no tier for `TOUCH_MS` instead of being written at every message.
+ */
+export class SeenThrottle {
+	readonly #seen = new Map<string, Seen>();
+
+	/**
+	 * Whether to write the principal as seen at `tier` now, recording it as written when so.
+	 * `stored` says the store holds what a write would leave, as far as the caller knows.
+	 */
+	take(
+		principalId: string,
+		tier: Tier | null,
+		now: number,
+		stored: boolean,
+	): boolean {
+		const last = this.#seen.get(principalId);
+		if (last && last.tier === tier && now - last.at < TOUCH_MS && stored)
+			return false;
+		if (tier !== null && last?.tier === null && now < (last.flapping ?? 0))
+			return false;
+		const back = tier !== null && last?.tier === null ? now : last?.back;
+		const flapping =
+			tier === null && back !== undefined && now - back < TOUCH_MS
+				? now + TOUCH_MS
+				: undefined;
+		const seen: Seen = { at: now, tier };
+		if (back !== undefined) seen.back = back;
+		if (flapping !== undefined) seen.flapping = flapping;
+		this.#seen.set(principalId, seen);
+		return true;
+	}
+
+	/** Forgets what was written for the principal, such as after a write that failed. */
+	forget(principalId: string): void {
+		this.#seen.delete(principalId);
+	}
+}

package/src/core/identity/ulid.ts

@@ -0,0 +1,36 @@
+/** Crockford's base 32, the alphabet of a ulid: no I, L, O, or U. */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+const PRINCIPAL_ID = /^p_[0-9A-HJKMNP-TV-Z]{26}$/;
+
+/** `count` base-32 digits of `value`, most significant first. */
+function digits(value: bigint, count: number): string {
+	let out = "";
+	let rest = value;
+	for (let i = 0; i < count; i++) {
+		out = ALPHABET.charAt(Number(rest & 31n)) + out;
+		rest >>= 5n;
+	}
+	return out;
+}
+
+/**
+ * A ulid: 48 bits of the time in milliseconds, then 80 random bits, as 26 base-32 digits, so ids
+ * made later sort after earlier ones.
+ */
+function ulid(now = Date.now()): string {
+	const random = crypto.getRandomValues(new Uint8Array(10));
+	let entropy = 0n;
+	for (const byte of random) entropy = (entropy << 8n) | BigInt(byte);
+	return digits(BigInt(now), 10) + digits(entropy, 16);
+}
+
+/** The id of a principal the host creates: `p_` and a ulid. A principal carried over from 0.8 keeps its old speaker id instead. */
+export function newPrincipalId(): string {
+	return `p_${ulid()}`;
+}
+
+/** Whether `id` has the form `newPrincipalId` makes. */
+export function isPrincipalId(id: string): boolean {
+	return PRINCIPAL_ID.test(id);
+}