@bastani/atomic 0.9.39 → 0.9.40-alpha.1

package/dist/builtin/intercom/broker/sql-known-session-store.ts

@@ -0,0 +1,129 @@
+import { type SqliteRow, validateStoragePrefix } from "@bastani/atomic/storage";
+import type {
+	IntercomBrokerStateOptions,
+	KnownSessionLookupResult,
+	KnownSessionRecordResult,
+	KnownSessionState,
+	KnownSessionStore,
+} from "./multinode-state-store.js";
+
+const STORE_NOW = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
+
+type KnownRow = SqliteRow & {
+	target_identity: string;
+	intercom_session_id: string;
+	name_json: string | null;
+	atomic_session_id: string | null;
+	group_name: string;
+	groups_json: string;
+	recipient_purpose: string | null;
+	reply_capability: string | null;
+	age_ms: number | bigint;
+};
+
+function stateFromRow(row: KnownRow): KnownSessionState {
+	return {
+		targetIdentity: row.target_identity,
+		intercomSessionId: row.intercom_session_id,
+		...(row.name_json === null ? {} : { name: JSON.parse(row.name_json) as string }),
+		...(row.atomic_session_id === null ? {} : { atomicSessionId: row.atomic_session_id }),
+		group: row.group_name,
+		groups: JSON.parse(row.groups_json) as string[],
+		...(row.recipient_purpose === null
+			? {}
+			: { recipientPurpose: row.recipient_purpose as NonNullable<KnownSessionState["recipientPurpose"]> }),
+		...(row.reply_capability === null
+			? {}
+			: { replyCapability: row.reply_capability as NonNullable<KnownSessionState["replyCapability"]> }),
+		ageMs: Number(row.age_ms),
+	};
+}
+
+/**
+ * S5 amendment (spec §14): `KnownSessionStore` on the shared storage adapter's database, table
+ * `<prefix>intercom_known_sessions`. Names are stored as JSON so any text survives; `name_key` holds the
+ * `toLowerCase` form the lookup compares.
+ */
+export async function openSqlKnownSessionStore({
+	database,
+	prefix,
+}: IntercomBrokerStateOptions): Promise<KnownSessionStore> {
+	const table = `${validateStoragePrefix(prefix)}intercom_known_sessions`;
+	await database.transaction((tx) =>
+		tx.exec(`
+			CREATE TABLE IF NOT EXISTS ${table}(
+				record_order INTEGER PRIMARY KEY AUTOINCREMENT,
+				target_identity TEXT NOT NULL UNIQUE,
+				intercom_session_id TEXT NOT NULL,
+				name_json TEXT,
+				name_key TEXT,
+				atomic_session_id TEXT,
+				group_name TEXT NOT NULL,
+				groups_json TEXT NOT NULL,
+				recipient_purpose TEXT,
+				reply_capability TEXT,
+				recorded_at INTEGER NOT NULL
+			);
+			CREATE INDEX IF NOT EXISTS ${table}_intercom_id ON ${table}(intercom_session_id);
+			CREATE INDEX IF NOT EXISTS ${table}_atomic_id ON ${table}(atomic_session_id);
+			CREATE INDEX IF NOT EXISTS ${table}_name ON ${table}(name_key);
+			CREATE INDEX IF NOT EXISTS ${table}_recorded ON ${table}(recorded_at);
+		`),
+	);
+
+	return {
+		async record(session): Promise<KnownSessionRecordResult> {
+			if (session.targetIdentity.length === 0) return { status: "invalid", reason: "empty-target-identity" };
+			if (session.intercomSessionId.length === 0) return { status: "invalid", reason: "empty-session-id" };
+			if (session.group.length === 0) return { status: "invalid", reason: "empty-group" };
+			await database.run(
+				`INSERT INTO ${table}(target_identity, intercom_session_id, name_json, name_key, atomic_session_id,
+					group_name, groups_json, recipient_purpose, reply_capability, recorded_at)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ${STORE_NOW})
+				 ON CONFLICT(target_identity) DO UPDATE SET
+					intercom_session_id = excluded.intercom_session_id,
+					name_json = excluded.name_json,
+					name_key = excluded.name_key,
+					atomic_session_id = excluded.atomic_session_id,
+					group_name = excluded.group_name,
+					groups_json = excluded.groups_json,
+					recipient_purpose = excluded.recipient_purpose,
+					reply_capability = excluded.reply_capability,
+					recorded_at = excluded.recorded_at`,
+				session.targetIdentity,
+				session.intercomSessionId,
+				session.name === undefined ? null : JSON.stringify(session.name),
+				session.name === undefined ? null : JSON.stringify(session.name.toLowerCase()),
+				session.atomicSessionId ?? null,
+				session.group,
+				JSON.stringify([...session.groups]),
+				session.recipientPurpose ?? null,
+				session.replyCapability ?? null,
+			);
+			return { status: "recorded" };
+		},
+		async lookup(target, retentionMs): Promise<KnownSessionLookupResult> {
+			if (target.length === 0) return { status: "invalid", reason: "empty-target" };
+			const rows = await database.all<KnownRow>(
+				`SELECT target_identity, intercom_session_id, name_json, atomic_session_id, group_name, groups_json,
+					recipient_purpose, reply_capability, MAX(0, ${STORE_NOW} - recorded_at) AS age_ms
+				 FROM ${table}
+				 WHERE (intercom_session_id = ? OR atomic_session_id = ? OR name_key = ?)
+					AND MAX(0, ${STORE_NOW} - recorded_at) <= ?
+				 ORDER BY record_order`,
+				target,
+				target,
+				JSON.stringify(target.toLowerCase()),
+				retentionMs,
+			);
+			return { status: "found", sessions: rows.map(stateFromRow) };
+		},
+		async prune(olderThanMs): Promise<number> {
+			const { changes } = await database.run(
+				`DELETE FROM ${table} WHERE ${STORE_NOW} - recorded_at > ?`,
+				olderThanMs,
+			);
+			return changes;
+		},
+	};
+}

package/dist/builtin/intercom/broker/sql-lease-store.ts

@@ -0,0 +1,194 @@
+import { type SqliteExecutor, type SqliteRow, validateStoragePrefix } from "@bastani/atomic/storage";
+import type {
+	BrokerLeaseStore,
+	IntercomBrokerStateOptions,
+	InvalidStateInput,
+	Lease,
+	LeaseKey,
+	LeaseKind,
+	LeaseState,
+	LeaseSubject,
+	StateStoreInvalidReason,
+} from "./multinode-state-store.js";
+
+const STORE_NOW = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
+const AGE = `MAX(0, ${STORE_NOW} - renewed_at)`;
+
+type HolderRow = SqliteRow & {
+	holder_id: string | null;
+	fencing_token: number | bigint | null;
+	last_token: number | bigint;
+	age_ms: number | bigint | null;
+};
+
+type StateRow = SqliteRow & {
+	kind: string;
+	key: string;
+	holder_id: string;
+	fencing_token: number | bigint;
+	subject_json: string;
+	age_ms: number | bigint;
+};
+
+const invalid = (reason: StateStoreInvalidReason): InvalidStateInput => ({ status: "invalid", reason });
+
+function keyOf(subject: LeaseSubject): LeaseKey {
+	return subject.kind === "broker"
+		? { kind: "broker", brokerId: subject.brokerId }
+		: { kind: "presence", targetIdentity: subject.targetIdentity };
+}
+
+function keyId(key: LeaseKey): string {
+	return key.kind === "broker" ? key.brokerId : key.targetIdentity;
+}
+
+function keyFor(kind: LeaseKind, id: string): LeaseKey {
+	return kind === "broker" ? { kind, brokerId: id } : { kind, targetIdentity: id };
+}
+
+function invalidKey(key: LeaseKey): InvalidStateInput | undefined {
+	if (keyId(key).length > 0) return undefined;
+	return invalid(key.kind === "broker" ? "empty-broker-id" : "empty-target-identity");
+}
+
+function stateFromRow(row: StateRow): LeaseState {
+	const subject: LeaseSubject = JSON.parse(row.subject_json);
+	return {
+		key: keyFor(row.kind === "broker" ? "broker" : "presence", row.key),
+		holderId: row.holder_id,
+		fencingToken: Number(row.fencing_token),
+		subject,
+		ageMs: Number(row.age_ms),
+	};
+}
+
+/** Opens the S1 lease store on the shared database's `<prefix>intercom_leases` table; the database stays open. */
+export async function openSqlBrokerLeaseStore(options: IntercomBrokerStateOptions): Promise<BrokerLeaseStore> {
+	const { database } = options;
+	const table = `${validateStoragePrefix(options.prefix)}intercom_leases`;
+	await database.exec(`
+		CREATE TABLE IF NOT EXISTS ${table}(
+			kind TEXT NOT NULL, key TEXT NOT NULL, holder_id TEXT, fencing_token INTEGER,
+			last_token INTEGER NOT NULL, subject_json TEXT, renewed_at INTEGER,
+			first_acquired_order INTEGER NOT NULL, PRIMARY KEY(kind, key)
+		)
+	`);
+
+	const holderOf = (executor: SqliteExecutor, key: LeaseKey) =>
+		executor.get<HolderRow>(
+			`SELECT holder_id, fencing_token, last_token, ${AGE} AS age_ms FROM ${table} WHERE kind = ? AND key = ?`,
+			key.kind,
+			keyId(key),
+		);
+	const stale = (row: HolderRow | undefined) =>
+		row?.holder_id === null || row?.holder_id === undefined
+			? ({ status: "stale" } as const)
+			: ({ status: "stale", currentFencingToken: Number(row.fencing_token) } as const);
+	const validLease = (lease: Lease): InvalidStateInput | undefined =>
+		invalidKey(lease.key) ?? (lease.holderId.length === 0 ? invalid("empty-holder-id") : undefined);
+	const owned = `kind = ? AND key = ? AND holder_id = ? AND fencing_token = ?`;
+	const ownedParams = (lease: Lease) => [lease.key.kind, keyId(lease.key), lease.holderId, lease.fencingToken];
+
+	return {
+		async acquire(subject, holderId, staleAfterMs) {
+			const key = keyOf(subject);
+			const bad = invalidKey(key);
+			if (bad !== undefined) return bad;
+			if (holderId.length === 0) return invalid("empty-holder-id");
+			const subjectJson = JSON.stringify(subject);
+			return database.transaction(async (tx) => {
+				const row = await holderOf(tx, key);
+				if (row === undefined) {
+					await tx.run(
+						`INSERT INTO ${table}(kind, key, holder_id, fencing_token, last_token, subject_json, renewed_at,
+							first_acquired_order)
+						VALUES (?, ?, ?, 1, 1, ?, ${STORE_NOW},
+							(SELECT COALESCE(MAX(first_acquired_order), 0) + 1 FROM ${table}))`,
+						key.kind,
+						keyId(key),
+						holderId,
+						subjectJson,
+					);
+					return { status: "acquired", lease: { key, holderId, fencingToken: 1 } } as const;
+				}
+				if (row.holder_id === holderId) {
+					await tx.run(
+						`UPDATE ${table} SET subject_json = ?, renewed_at = ${STORE_NOW} WHERE kind = ? AND key = ?`,
+						subjectJson,
+						key.kind,
+						keyId(key),
+					);
+					return {
+						status: "acquired",
+						lease: { key, holderId, fencingToken: Number(row.fencing_token) },
+					} as const;
+				}
+				if (row.holder_id !== null && Number(row.age_ms) <= staleAfterMs) {
+					return { status: "held", holderId: row.holder_id, fencingToken: Number(row.fencing_token) } as const;
+				}
+				const fencingToken = Number(row.last_token) + 1;
+				await tx.run(
+					`UPDATE ${table} SET holder_id = ?, fencing_token = ?, last_token = ?, subject_json = ?,
+						renewed_at = ${STORE_NOW} WHERE kind = ? AND key = ?`,
+					holderId,
+					fencingToken,
+					fencingToken,
+					subjectJson,
+					key.kind,
+					keyId(key),
+				);
+				return { status: "acquired", lease: { key, holderId, fencingToken } } as const;
+			});
+		},
+		async renew(lease, subject) {
+			const bad = validLease(lease);
+			if (bad !== undefined) return bad;
+			if (subject !== undefined && (subject.kind !== lease.key.kind || keyId(keyOf(subject)) !== keyId(lease.key))) {
+				return invalid("subject-key-mismatch");
+			}
+			return database.transaction(async (tx) => {
+				const { changes } =
+					subject === undefined
+						? await tx.run(`UPDATE ${table} SET renewed_at = ${STORE_NOW} WHERE ${owned}`, ...ownedParams(lease))
+						: await tx.run(
+								`UPDATE ${table} SET renewed_at = ${STORE_NOW}, subject_json = ? WHERE ${owned}`,
+								JSON.stringify(subject),
+								...ownedParams(lease),
+							);
+				return changes === 1 ? ({ status: "renewed" } as const) : stale(await holderOf(tx, lease.key));
+			});
+		},
+		async release(lease) {
+			const bad = validLease(lease);
+			if (bad !== undefined) return bad;
+			return database.transaction(async (tx) => {
+				const { changes } = await tx.run(
+					`UPDATE ${table} SET holder_id = NULL, fencing_token = NULL, subject_json = NULL, renewed_at = NULL
+					WHERE ${owned}`,
+					...ownedParams(lease),
+				);
+				return changes === 1 ? ({ status: "released" } as const) : stale(await holderOf(tx, lease.key));
+			});
+		},
+		async read(key) {
+			const bad = invalidKey(key);
+			if (bad !== undefined) return bad;
+			const row = await database.get<StateRow>(
+				`SELECT kind, key, holder_id, fencing_token, subject_json, ${AGE} AS age_ms FROM ${table}
+				WHERE kind = ? AND key = ? AND holder_id IS NOT NULL`,
+				key.kind,
+				keyId(key),
+			);
+			return row === undefined ? { status: "missing" } : { status: "found", lease: stateFromRow(row) };
+		},
+		async listLive(kind, staleAfterMs) {
+			const rows = await database.all<StateRow>(
+				`SELECT kind, key, holder_id, fencing_token, subject_json, ${AGE} AS age_ms FROM ${table}
+				WHERE kind = ? AND holder_id IS NOT NULL AND ${AGE} <= ? ORDER BY first_acquired_order`,
+				kind,
+				staleAfterMs,
+			);
+			return rows.map(stateFromRow);
+		},
+	};
+}

package/dist/builtin/intercom/broker/sql-outbox-store.ts

@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+import {
+	type SqliteExecutor,
+	type SqliteRow,
+	type SqliteValue,
+	validateStoragePrefix,
+} from "@bastani/atomic/storage";
+import type {
+	ClaimedOutboxRow,
+	InvalidStateInput,
+	IntercomBrokerStateOptions,
+	IntercomDeliveryFrame,
+	OutboxClaim,
+	OutboxClaimWriteRejection,
+	OutboxRow,
+	OutboxRowState,
+	OutboxStore,
+	StateStoreInvalidReason,
+} from "./multinode-state-store.js";
+
+const STORE_NOW = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
+const UNDELIVERED = "state IN ('queued', 'claimed')";
+
+interface OutboxRecord extends SqliteRow {
+	readonly sequence: SqliteValue;
+	readonly message_id: string;
+	readonly target_identity: string;
+	readonly origin_broker_id: string;
+	readonly digest: string;
+	readonly frame_json: string;
+	readonly state: OutboxRowState;
+	readonly claim_attempts: SqliteValue;
+	readonly claimant_id: string | null;
+	readonly claim_token: string | null;
+	/** Store-clock milliseconds since the claim was taken or renewed; null when unclaimed. */
+	readonly claim_age: SqliteValue;
+	readonly failure_reason: string | null;
+}
+
+const invalid = (reason: StateStoreInvalidReason): InvalidStateInput => ({ status: "invalid", reason });
+
+function toRow(record: OutboxRecord): OutboxRow {
+	const failureReason = record.failure_reason;
+	return {
+		sequence: Number(record.sequence),
+		messageId: record.message_id,
+		targetIdentity: record.target_identity,
+		originBrokerId: record.origin_broker_id,
+		digest: record.digest,
+		frame: JSON.parse(record.frame_json) as IntercomDeliveryFrame,
+		state: record.state,
+		claimAttempts: Number(record.claim_attempts),
+		...(failureReason === null ? {} : { failureReason: JSON.parse(failureReason) as string }),
+	};
+}
+
+const isSettled = (record: OutboxRecord): boolean => record.state === "delivered" || record.state === "failed";
+
+/**
+ * S2 outbox on the shared storage adapter's database, in `<prefix>intercom_outbox`. Every read-modify-write runs in
+ * one `BEGIN IMMEDIATE` transaction, and every age is measured on the database clock.
+ */
+export async function openSqlOutboxStore(options: IntercomBrokerStateOptions): Promise<OutboxStore> {
+	const { database } = options;
+	const table = `${validateStoragePrefix(options.prefix)}intercom_outbox`;
+	await database.exec(`
+		CREATE TABLE IF NOT EXISTS ${table}(
+			sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+			message_id TEXT NOT NULL UNIQUE,
+			target_identity TEXT NOT NULL,
+			origin_broker_id TEXT NOT NULL,
+			digest TEXT NOT NULL,
+			frame_json TEXT NOT NULL,
+			state TEXT NOT NULL CHECK (state IN ('queued', 'claimed', 'delivered', 'failed')),
+			claim_attempts INTEGER NOT NULL DEFAULT 0,
+			claimant_id TEXT,
+			claim_token TEXT,
+			claim_renewed_at INTEGER,
+			failure_reason TEXT,
+			settled_at INTEGER
+		);
+		CREATE INDEX IF NOT EXISTS ${table}_target ON ${table}(target_identity, state, sequence);
+	`);
+
+	const columns = `sequence, message_id, target_identity, origin_broker_id, digest, frame_json, state,
+		claim_attempts, claimant_id, claim_token, failure_reason,
+		CASE WHEN claim_renewed_at IS NULL THEN NULL ELSE MAX(0, ${STORE_NOW} - claim_renewed_at) END AS claim_age`;
+	const select = (executor: SqliteExecutor, messageId: string) =>
+		executor.get<OutboxRecord>(`SELECT ${columns} FROM ${table} WHERE message_id = ?`, messageId);
+	const undelivered = (executor: SqliteExecutor, targetIdentity: string) =>
+		executor.all<OutboxRecord>(
+			`SELECT ${columns} FROM ${table} WHERE target_identity = ? AND ${UNDELIVERED} ORDER BY sequence`,
+			targetIdentity,
+		);
+	const isLive = (record: OutboxRecord, staleAfterMs: number): boolean =>
+		record.claim_age !== null && Number(record.claim_age) <= staleAfterMs;
+
+	/** Runs `write` only for the row's current claim; every other case is reported as the contract requires. */
+	const withClaim = <Result>(
+		claim: OutboxClaim,
+		write: (executor: SqliteExecutor) => Promise<Result>,
+	): Promise<Result | OutboxClaimWriteRejection> => {
+		if (claim.messageId.length === 0) return Promise.resolve(invalid("empty-message-id"));
+		if (claim.claimantId.length === 0) return Promise.resolve(invalid("empty-claimant-id"));
+		return database.transaction(async (executor) => {
+			const record = await select(executor, claim.messageId);
+			if (record === undefined) return { status: "unknown" } as const;
+			if (isSettled(record)) return { status: "settled", row: toRow(record) } as const;
+			if (record.claim_token !== claim.token || record.claimant_id !== claim.claimantId) {
+				return { status: "stale" } as const;
+			}
+			return write(executor);
+		});
+	};
+
+	const settle = async (
+		executor: SqliteExecutor,
+		messageId: string,
+		state: "delivered" | "failed",
+		reason: string | null,
+	): Promise<OutboxRow> => {
+		await executor.run(
+			`UPDATE ${table} SET state = ?, failure_reason = ?, settled_at = ${STORE_NOW},
+				claimant_id = NULL, claim_token = NULL, claim_renewed_at = NULL
+			WHERE message_id = ?`,
+			state,
+			reason === null ? null : JSON.stringify(reason),
+			messageId,
+		);
+		return toRow((await select(executor, messageId))!);
+	};
+
+	return {
+		async enqueue(request) {
+			if (request.targetIdentity.length === 0) return invalid("empty-target-identity");
+			if (request.originBrokerId.length === 0) return invalid("empty-broker-id");
+			const messageId = request.frame.message.id;
+			if (messageId.length === 0) return invalid("empty-message-id");
+			const frameJson = JSON.stringify(request.frame);
+			return database.transaction(async (executor) => {
+				const existing = await select(executor, messageId);
+				if (existing !== undefined) {
+					return existing.digest === request.digest
+						? ({ status: "duplicate", row: toRow(existing) } as const)
+						: ({ status: "conflict", messageId } as const);
+				}
+				await executor.run(
+					`INSERT INTO ${table}(message_id, target_identity, origin_broker_id, digest, frame_json, state)
+					VALUES (?, ?, ?, ?, ?, 'queued')`,
+					messageId,
+					request.targetIdentity,
+					request.originBrokerId,
+					request.digest,
+					frameJson,
+				);
+				return { status: "inserted", row: toRow((await select(executor, messageId))!) } as const;
+			});
+		},
+
+		async claim(request) {
+			if (request.claimantId.length === 0) return invalid("empty-claimant-id");
+			if (request.targetIdentity.length === 0) return invalid("empty-target-identity");
+			return database.transaction(async (executor) => {
+				const records = await undelivered(executor, request.targetIdentity);
+				const other = records.find(
+					(record) =>
+						record.state === "claimed" &&
+						record.claimant_id !== request.claimantId &&
+						isLive(record, request.staleAfterMs),
+				);
+				if (other?.claimant_id) return { status: "held", claimantId: other.claimant_id } as const;
+				const rows: ClaimedOutboxRow[] = [];
+				for (const record of records) {
+					if (record.state === "claimed" && isLive(record, request.staleAfterMs)) continue;
+					const token = randomUUID();
+					await executor.run(
+						`UPDATE ${table} SET state = 'claimed', claim_attempts = claim_attempts + 1, claimant_id = ?,
+							claim_token = ?, claim_renewed_at = ${STORE_NOW}
+						WHERE message_id = ?`,
+						request.claimantId,
+						token,
+						record.message_id,
+					);
+					const row = toRow((await select(executor, record.message_id))!);
+					rows.push({
+						row,
+						claim: { messageId: row.messageId, claimantId: request.claimantId, token, attempt: row.claimAttempts },
+					});
+				}
+				return { status: "claimed", rows } as const;
+			});
+		},
+
+		renewClaim(claim) {
+			return withClaim(claim, async (executor) => {
+				await executor.run(
+					`UPDATE ${table} SET claim_renewed_at = ${STORE_NOW} WHERE message_id = ?`,
+					claim.messageId,
+				);
+				return { status: "renewed" } as const;
+			});
+		},
+
+		releaseClaim(claim) {
+			return withClaim(claim, async (executor) => {
+				await executor.run(
+					`UPDATE ${table} SET state = 'queued', claimant_id = NULL, claim_token = NULL, claim_renewed_at = NULL
+					WHERE message_id = ?`,
+					claim.messageId,
+				);
+				return { status: "released" } as const;
+			});
+		},
+
+		markDelivered(claim) {
+			return withClaim(claim, async (executor) => ({
+				status: "delivered" as const,
+				row: await settle(executor, claim.messageId, "delivered", null),
+			}));
+		},
+
+		markFailed(claim, reason) {
+			return withClaim(claim, async (executor) => ({
+				status: "failed" as const,
+				row: await settle(executor, claim.messageId, "failed", reason),
+			}));
+		},
+
+		async read(messageId) {
+			if (messageId.length === 0) return invalid("empty-message-id");
+			const record = await select(database, messageId);
+			return record === undefined ? { status: "missing" } : { status: "found", row: toRow(record) };
+		},
+
+		async listUndelivered(targetIdentity) {
+			if (targetIdentity.length === 0) return invalid("empty-target-identity");
+			return { status: "listed", rows: (await undelivered(database, targetIdentity)).map(toRow) };
+		},
+
+		async prune(settledOlderThanMs) {
+			const result = await database.run(
+				`DELETE FROM ${table}
+				WHERE state IN ('delivered', 'failed') AND MAX(0, ${STORE_NOW} - settled_at) > ?`,
+				settledOlderThanMs,
+			);
+			return result.changes;
+		},
+	};
+}

package/dist/builtin/intercom/broker/sql-pending-ask-store.ts

@@ -0,0 +1,105 @@
+import { type SqliteRow, validateStoragePrefix } from "@bastani/atomic/storage";
+import type {
+	IntercomBrokerStateOptions,
+	InvalidStateInput,
+	PendingAsk,
+	PendingAskClearResult,
+	PendingAskMatchResult,
+	PendingAskPruneResult,
+	PendingAskRecordResult,
+	PendingAskStore,
+	PendingAskTakeResult,
+	ReplyRoute,
+	StateStoreInvalidReason,
+} from "./multinode-state-store.js";
+
+type AskRow = SqliteRow & { sender_session_id: string; target_session_id: string; message_id: string };
+
+const invalid = (reason: StateStoreInvalidReason): InvalidStateInput => ({ status: "invalid", reason });
+
+function invalidAsk(ask: PendingAsk): InvalidStateInput | undefined {
+	if (ask.senderSessionId.length === 0 || ask.targetSessionId.length === 0) return invalid("empty-session-id");
+	return ask.messageId.length === 0 ? invalid("empty-message-id") : undefined;
+}
+
+function invalidRoute(route: ReplyRoute): InvalidStateInput | undefined {
+	if (route.replySenderSessionId.length === 0 || route.replyTargetSessionId.length === 0) {
+		return invalid("empty-session-id");
+	}
+	return route.replyTo.length === 0 ? invalid("empty-message-id") : undefined;
+}
+
+/** S3: `PendingAskStore` on the shared storage adapter's database, table `<prefix>intercom_pending_asks`. */
+export async function openSqlPendingAskStore({
+	database,
+	prefix,
+}: IntercomBrokerStateOptions): Promise<PendingAskStore> {
+	const table = `${validateStoragePrefix(prefix)}intercom_pending_asks`;
+	await database.transaction((tx) =>
+		tx.exec(`
+			CREATE TABLE IF NOT EXISTS ${table}(
+				"order" INTEGER PRIMARY KEY AUTOINCREMENT,
+				sender_session_id TEXT NOT NULL,
+				target_session_id TEXT NOT NULL,
+				message_id TEXT NOT NULL,
+				UNIQUE(sender_session_id, target_session_id, message_id)
+			);
+			CREATE INDEX IF NOT EXISTS ${table}_target ON ${table}(target_session_id, "order");
+		`),
+	);
+	const reverseRoute = "sender_session_id = ? AND target_session_id = ? AND message_id = ?";
+	const reverseParams = (route: ReplyRoute) =>
+		[route.replyTargetSessionId, route.replySenderSessionId, route.replyTo] as const;
+
+	return {
+		async record(ask): Promise<PendingAskRecordResult> {
+			const bad = invalidAsk(ask);
+			if (bad !== undefined) return bad;
+			const { changes } = await database.run(
+				`INSERT INTO ${table}(sender_session_id, target_session_id, message_id) VALUES (?, ?, ?)
+				 ON CONFLICT DO NOTHING`,
+				ask.senderSessionId,
+				ask.targetSessionId,
+				ask.messageId,
+			);
+			return changes === 0 ? { status: "duplicate" } : { status: "recorded" };
+		},
+		async matchesReply(route): Promise<PendingAskMatchResult> {
+			const bad = invalidRoute(route);
+			if (bad !== undefined) return bad;
+			const row = await database.get(`SELECT 1 AS found FROM ${table} WHERE ${reverseRoute}`, ...reverseParams(route));
+			return row === undefined ? { status: "no-match" } : { status: "match" };
+		},
+		async clearReply(route): Promise<PendingAskClearResult> {
+			const bad = invalidRoute(route);
+			if (bad !== undefined) return bad;
+			const { changes } = await database.run(`DELETE FROM ${table} WHERE ${reverseRoute}`, ...reverseParams(route));
+			return changes === 0 ? { status: "no-match" } : { status: "cleared" };
+		},
+		async pruneSender(senderSessionId): Promise<PendingAskPruneResult> {
+			if (senderSessionId.length === 0) return invalid("empty-session-id");
+			const { changes } = await database.run(`DELETE FROM ${table} WHERE sender_session_id = ?`, senderSessionId);
+			return { status: "pruned", removed: changes };
+		},
+		async takeForTarget(targetSessionId): Promise<PendingAskTakeResult> {
+			if (targetSessionId.length === 0) return invalid("empty-session-id");
+			const rows = await database.transaction(async (tx) => {
+				const taken = await tx.all<AskRow>(
+					`SELECT sender_session_id, target_session_id, message_id FROM ${table}
+					 WHERE target_session_id = ? ORDER BY "order"`,
+					targetSessionId,
+				);
+				await tx.run(`DELETE FROM ${table} WHERE target_session_id = ?`, targetSessionId);
+				return taken;
+			});
+			return {
+				status: "taken",
+				asks: rows.map((row) => ({
+					senderSessionId: row.sender_session_id,
+					targetSessionId: row.target_session_id,
+					messageId: row.message_id,
+				})),
+			};
+		},
+	};
+}