@remit/drizzle-service 0.0.87 → 0.0.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.87",
+  "version": "0.0.88",
   "description": "Drizzle ORM service over SQLite",
   "type": "module",
   "main": "src/index.ts",

package/src/mailbox-path-dedupe.sqlite.test.ts

@@ -0,0 +1,436 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import * as entities from "@remit/drizzle-sqlite-schema";
+import Database from "better-sqlite3";
+import { asc, eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import type { Db } from "./db.js";
+import {
+	PARKED_MAILBOX_ID,
+	sweepDuplicateMailboxMail,
+} from "./repair/duplicate-mailbox-mail.js";
+import { MESSAGE_REMOVED_EVENT } from "./repos/message.js";
+import { outboxTable } from "./schema/outbox.js";
+import {
+	applyMigration,
+	migrationJournal,
+} from "./test-shipped-sqlite-schema.js";
+
+const DEDUPE = "0030_mailbox_path_dedupe";
+const UNIQUE = "0031_mailbox_path_unique";
+const ACCOUNT = "acct";
+const CONFIG = "cfg";
+
+type Handle = { sqlite: Database.Database; db: Db<Record<string, unknown>> };
+
+const atPredecessor = (): Handle => {
+	const sqlite = new Database(":memory:");
+	for (const entry of migrationJournal()) {
+		if (entry.tag === DEDUPE) {
+			return {
+				sqlite,
+				db: drizzle(sqlite) as unknown as Db<Record<string, unknown>>,
+			};
+		}
+		applyMigration(sqlite, entry.tag);
+	}
+	throw new Error(`${DEDUPE} is not in the journal`);
+};
+
+const seedMailbox = async (
+	{ db }: Handle,
+	mailboxId: string,
+	fullPath: string,
+	createdAt: number,
+	over: Partial<typeof entities.mailboxes.$inferInsert> = {},
+): Promise<void> => {
+	await db.insert(entities.mailboxes).values({
+		mailboxId,
+		accountId: ACCOUNT,
+		namespacePrefix: "",
+		hierarchyDelimiter: "/",
+		fullPath,
+		uidValidity: 1,
+		uidNext: 1,
+		highestModseq: "0",
+		messageCount: 0,
+		unseenCount: 0,
+		deletedCount: 0,
+		totalSize: 0,
+		lastSyncUid: 0,
+		highWaterMarkUid: 0,
+		lastMessageSyncAt: 0,
+		createdAt,
+		updatedAt: createdAt,
+		...over,
+	});
+};
+
+const seedMessage = async (
+	{ db }: Handle,
+	messageId: string,
+	mailboxId: string,
+	uid = 1,
+): Promise<void> => {
+	await db.insert(entities.messages).values({
+		messageId,
+		mailboxId,
+		uid,
+		sequenceNumber: uid,
+		rfc822Size: 1,
+		internalDate: 0,
+		envelopeId: `env-${messageId}`,
+		rootBodyPartId: `bp-${messageId}`,
+		createdAt: 0,
+		updatedAt: 0,
+	});
+	await db.insert(entities.threadMessages).values({
+		threadMessageId: `tm-${messageId}`,
+		threadId: `thread-${messageId}`,
+		messageId,
+		accountConfigId: CONFIG,
+		mailboxId,
+		uid,
+		referenceOrder: 0,
+		internalDate: 0,
+		sentDate: 0,
+		isRead: false,
+		hasAttachment: false,
+		hasStars: false,
+		isDeleted: false,
+		createdAt: 0,
+		updatedAt: 0,
+	});
+};
+
+const seedSetting = async (
+	{ db }: Handle,
+	name: string,
+	value: typeof entities.accountSettings.$inferInsert.value,
+): Promise<void> => {
+	await db.insert(entities.accountSettings).values({
+		accountSettingId: name,
+		accountConfigId: CONFIG,
+		name,
+		value,
+		createdAt: 0,
+		updatedAt: 0,
+	});
+};
+
+const dedupe = (handle: Handle): void => {
+	applyMigration(handle.sqlite, DEDUPE);
+	applyMigration(handle.sqlite, UNIQUE);
+};
+
+const mailboxIds = async ({ db }: Handle): Promise<string[]> =>
+	(
+		await db
+			.select({ mailboxId: entities.mailboxes.mailboxId })
+			.from(entities.mailboxes)
+			.orderBy(asc(entities.mailboxes.mailboxId))
+	).map((row) => row.mailboxId);
+
+const messagesIn = async ({ db }: Handle, mailboxId: string): Promise<number> =>
+	(
+		await db
+			.select({ messageId: entities.messages.messageId })
+			.from(entities.messages)
+			.where(eq(entities.messages.mailboxId, mailboxId))
+	).length;
+
+const threadsIn = async ({ db }: Handle, mailboxId: string): Promise<number> =>
+	(
+		await db
+			.select({ messageId: entities.threadMessages.messageId })
+			.from(entities.threadMessages)
+			.where(eq(entities.threadMessages.mailboxId, mailboxId))
+	).length;
+
+const survivorCursor = async ({ db }: Handle, mailboxId: string) => {
+	const [row] = await db
+		.select({
+			lastSyncUid: entities.mailboxes.lastSyncUid,
+			highWaterMarkUid: entities.mailboxes.highWaterMarkUid,
+			highestModseq: entities.mailboxes.highestModseq,
+		})
+		.from(entities.mailboxes)
+		.where(eq(entities.mailboxes.mailboxId, mailboxId));
+	return row;
+};
+
+describe("(account_id, full_path) becomes unique", () => {
+	test("the loser's mail moves onto the survivor, so none of it is lost", async () => {
+		const handle = atPredecessor();
+		const cursor = {
+			lastSyncUid: 1,
+			highWaterMarkUid: 105,
+			highestModseq: "900",
+		};
+		await seedMailbox(handle, "a", "Archive", 1, cursor);
+		await seedMailbox(handle, "b", "Archive", 2, cursor);
+		for (let uid = 1; uid <= 100; uid++) {
+			await seedMessage(handle, `a-${uid}`, "a", uid);
+		}
+		for (let uid = 101; uid <= 105; uid++) {
+			await seedMessage(handle, `b-${uid}`, "b", uid);
+		}
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), ["a"]);
+		assert.equal(await messagesIn(handle, "a"), 105);
+		assert.equal(await threadsIn(handle, "a"), 105);
+		assert.equal(await messagesIn(handle, PARKED_MAILBOX_ID), 0);
+		assert.deepEqual(await survivorCursor(handle, "a"), cursor);
+		handle.sqlite.close();
+	});
+
+	test("what named the loser follows the survivor", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "older-empty", "INBOX/Notifications", 1);
+		await seedMailbox(handle, "with-mail", "INBOX/Notifications", 2);
+		await seedMailbox(handle, "child", "INBOX/Notifications/Old", 3);
+		await seedMailbox(handle, "elsewhere", "Receipts", 4);
+		await seedMessage(handle, "m1", "with-mail");
+		await seedMessage(handle, "copied", "elsewhere");
+		await handle.db
+			.update(entities.messages)
+			.set({ originalMailboxId: "older-empty" })
+			.where(eq(entities.messages.messageId, "copied"));
+		await handle.db
+			.update(entities.mailboxes)
+			.set({ parentMailboxId: "older-empty" })
+			.where(eq(entities.mailboxes.mailboxId, "child"));
+		await handle.db.insert(entities.filters).values({
+			filterId: "f1",
+			accountConfigId: CONFIG,
+			name: "Alerts",
+			scope: "Standing",
+			ruleChangedAt: 0,
+			actionChangedAt: 0,
+			actionMailboxId: "older-empty",
+			createdAt: 0,
+			updatedAt: 0,
+		});
+		await handle.db.insert(entities.organizeJobRequests).values({
+			organizeJobId: "job-1",
+			accountConfigId: CONFIG,
+			userId: "user",
+			actionMailboxId: "older-empty",
+			ttl: 0,
+			createdAt: 0,
+			updatedAt: 0,
+		});
+		await handle.db.insert(entities.messagePlacementMoves).values({
+			messageId: "copied",
+			accountId: ACCOUNT,
+			accountConfigId: CONFIG,
+			sourceMailboxId: "elsewhere",
+			destinationMailboxId: "older-empty",
+			createdAt: 0,
+			updatedAt: 0,
+		});
+		await seedSetting(handle, "FolderRoleAppointment#acct#Archive", {
+			kind: "String",
+			value: "older-empty",
+		});
+		await handle.db.insert(entities.mailboxFlags).values({
+			mailboxFlagId: "flag-1",
+			mailboxId: "older-empty",
+			flagName: "\\Seen",
+			isPermanent: true,
+		});
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), [
+			"child",
+			"elsewhere",
+			"with-mail",
+		]);
+		const [child] = await handle.db
+			.select({ parent: entities.mailboxes.parentMailboxId })
+			.from(entities.mailboxes)
+			.where(eq(entities.mailboxes.mailboxId, "child"));
+		assert.equal(child?.parent, "with-mail");
+		const [filter] = await handle.db.select().from(entities.filters);
+		assert.equal(filter?.actionMailboxId, "with-mail");
+		const [job] = await handle.db.select().from(entities.organizeJobRequests);
+		assert.equal(job?.actionMailboxId, "with-mail");
+		const [copied] = await handle.db
+			.select({ original: entities.messages.originalMailboxId })
+			.from(entities.messages)
+			.where(eq(entities.messages.messageId, "copied"));
+		assert.equal(copied?.original, "with-mail");
+		const [move] = await handle.db
+			.select()
+			.from(entities.messagePlacementMoves);
+		assert.equal(move?.destinationMailboxId, "with-mail");
+		const [setting] = await handle.db.select().from(entities.accountSettings);
+		assert.deepEqual(setting?.value, { kind: "String", value: "with-mail" });
+		assert.deepEqual(await handle.db.select().from(entities.mailboxFlags), []);
+		const index = (
+			handle.sqlite.prepare("PRAGMA index_list(mailbox)").all() as Array<{
+				name: string;
+				unique: number;
+			}>
+		).find((entry) => entry.name === "mailbox_by_account_full_path");
+		assert.equal(index?.unique, 1);
+		handle.sqlite.close();
+	});
+
+	test("a muted losing folder stays muted, and the survivor's own name is kept", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "survivor", "Newsletters", 1);
+		await seedMailbox(handle, "loser", "Newsletters", 2);
+		await seedSetting(handle, "MailboxMuted#loser", {
+			kind: "Muted",
+			value: true,
+		});
+		await seedSetting(handle, "MailboxDisplayName#loser", {
+			kind: "String",
+			value: "Loser name",
+		});
+		await seedSetting(handle, "MailboxDisplayName#survivor", {
+			kind: "String",
+			value: "Survivor name",
+		});
+
+		dedupe(handle);
+
+		const settings = await handle.db
+			.select({
+				name: entities.accountSettings.name,
+				value: entities.accountSettings.value,
+			})
+			.from(entities.accountSettings)
+			.orderBy(asc(entities.accountSettings.name));
+		assert.deepEqual(settings, [
+			{
+				name: "MailboxDisplayName#survivor",
+				value: { kind: "String", value: "Survivor name" },
+			},
+			{ name: "MailboxMuted#survivor", value: { kind: "Muted", value: true } },
+		]);
+		handle.sqlite.close();
+	});
+
+	test("the survivor is chosen by the mail it holds, not by message_count", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "claims-mail", "Archive", 1, {
+			messageCount: 500,
+		});
+		await seedMailbox(handle, "holds-mail", "Archive", 2);
+		await seedMessage(handle, "m1", "holds-mail", 1);
+		await seedMessage(handle, "m2", "holds-mail", 2);
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), ["holds-mail"]);
+		handle.sqlite.close();
+	});
+
+	test("with equal mail the oldest row survives", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "a-newer", "Archive", 2);
+		await seedMailbox(handle, "b-older", "Archive", 1);
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), ["b-older"]);
+		handle.sqlite.close();
+	});
+
+	test("with equal mail and age the lowest mailbox_id survives", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "b", "Archive", 1);
+		await seedMailbox(handle, "a", "Archive", 1);
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), ["a"]);
+		handle.sqlite.close();
+	});
+
+	test("mail the survivor already holds at that uid is parked, removed at boot, and re-fetched", async () => {
+		const handle = atPredecessor();
+		const cursor = {
+			lastSyncUid: 1,
+			highWaterMarkUid: 9,
+			highestModseq: "900",
+		};
+		await seedMailbox(handle, "older", "Archive", 1, cursor);
+		await seedMailbox(handle, "newer", "Archive", 2, cursor);
+		await seedMessage(handle, "kept", "older", 7);
+		await seedMessage(handle, "stale", "newer", 7);
+		await seedMessage(handle, "unrelated", "no-such-folder", 1);
+
+		dedupe(handle);
+
+		assert.deepEqual(await mailboxIds(handle), ["older"]);
+		assert.equal(await messagesIn(handle, PARKED_MAILBOX_ID), 1);
+		assert.equal(await threadsIn(handle, PARKED_MAILBOX_ID), 1);
+		assert.deepEqual(await survivorCursor(handle, "older"), {
+			lastSyncUid: 0,
+			highWaterMarkUid: 0,
+			highestModseq: "0",
+		});
+
+		const report = await sweepDuplicateMailboxMail(handle.db, "repair");
+
+		assert.deepEqual(report, {
+			mode: "repair",
+			duplicatePaths: 0,
+			parked: 1,
+			removed: 1,
+		});
+		const messages = await handle.db
+			.select({ messageId: entities.messages.messageId })
+			.from(entities.messages)
+			.orderBy(asc(entities.messages.messageId));
+		assert.deepEqual(messages, [
+			{ messageId: "kept" },
+			{ messageId: "unrelated" },
+		]);
+		const events = await handle.db
+			.select({ messageId: outboxTable.messageId, event: outboxTable.event })
+			.from(outboxTable);
+		assert.deepEqual(events, [
+			{ messageId: "stale", event: MESSAGE_REMOVED_EVENT },
+		]);
+		assert.deepEqual(await sweepDuplicateMailboxMail(handle.db, "repair"), {
+			mode: "repair",
+			duplicatePaths: 0,
+			parked: 0,
+			removed: 0,
+		});
+		handle.sqlite.close();
+	});
+
+	test("the check before migrating reports the paths the migration will merge", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "a", "Archive", 1);
+		await seedMailbox(handle, "b", "Archive", 2);
+
+		assert.deepEqual(await sweepDuplicateMailboxMail(handle.db, "check"), {
+			mode: "check",
+			duplicatePaths: 1,
+			parked: 0,
+			removed: 0,
+		});
+		handle.sqlite.close();
+	});
+
+	test("the unique index is refused without the dedupe ahead of it", async () => {
+		const handle = atPredecessor();
+		await seedMailbox(handle, "a", "Archive", 1);
+		await seedMailbox(handle, "b", "Archive", 2);
+
+		assert.throws(
+			() => applyMigration(handle.sqlite, UNIQUE),
+			/UNIQUE constraint failed/,
+		);
+		handle.sqlite.close();
+	});
+});

package/src/repair/duplicate-mailbox-mail.ts

@@ -0,0 +1,98 @@
+import { count, eq, gt, inArray } from "drizzle-orm";
+import type { Db } from "../db.js";
+import { deleteMessageSubtree } from "../repos/message.js";
+import { mailboxTable } from "../schema/i4-mailbox.js";
+import { messageTable } from "../schema/message-data.js";
+import { threadMessageTable } from "../schema/thread-message.js";
+import { messageLabelTable } from "../schema.js";
+import { runInTransaction } from "../tx.js";
+
+export const PARKED_MAILBOX_ID = "DuplicateMailboxRemoved";
+
+type DuplicateMailDb = Db<Record<string, unknown>>;
+
+export type DuplicateMailRepairMode = "check" | "repair";
+
+export type DuplicateMailReport = {
+	readonly mode: DuplicateMailRepairMode;
+	readonly duplicatePaths: number;
+	readonly parked: number;
+	readonly removed: number;
+};
+
+const BATCH_SIZE = 100;
+
+const countDuplicatePaths = async (db: DuplicateMailDb): Promise<number> => {
+	const groups = await db
+		.select({ rows: count() })
+		.from(mailboxTable)
+		.groupBy(mailboxTable.accountId, mailboxTable.fullPath)
+		.having(gt(count(), 1));
+	return groups.length;
+};
+
+const countParked = async (db: DuplicateMailDb): Promise<number> => {
+	const [row] = await db
+		.select({ parked: count() })
+		.from(messageTable)
+		.where(eq(messageTable.mailboxId, PARKED_MAILBOX_ID));
+	return row?.parked ?? 0;
+};
+
+const nextParkedBatch = async (db: DuplicateMailDb): Promise<string[]> => {
+	const rows = await db
+		.select({ messageId: messageTable.messageId })
+		.from(messageTable)
+		.where(eq(messageTable.mailboxId, PARKED_MAILBOX_ID))
+		.limit(BATCH_SIZE);
+	return rows.map((row) => row.messageId);
+};
+
+export const sweepDuplicateMailboxMail = async (
+	db: DuplicateMailDb,
+	mode: DuplicateMailRepairMode,
+): Promise<DuplicateMailReport> => {
+	const duplicatePaths = await countDuplicatePaths(db);
+	const parked = await countParked(db);
+	if (mode === "check" || parked === 0) {
+		return { mode, duplicatePaths, parked, removed: 0 };
+	}
+
+	let removed = 0;
+	for (;;) {
+		const messageIds = await nextParkedBatch(db);
+		if (messageIds.length === 0) break;
+		await runInTransaction(db, async (tx) => {
+			await deleteMessageSubtree(tx, messageIds);
+			await tx
+				.delete(threadMessageTable)
+				.where(inArray(threadMessageTable.messageId, messageIds));
+			await tx
+				.delete(messageLabelTable)
+				.where(inArray(messageLabelTable.messageId, messageIds));
+		});
+		removed += messageIds.length;
+	}
+	return { mode, duplicatePaths, parked, removed };
+};
+
+export const formatDuplicateMailReport = (
+	report: DuplicateMailReport,
+): string[] => {
+	const lines: string[] = [];
+	if (report.duplicatePaths > 0) {
+		lines.push(
+			`${report.duplicatePaths} folder path(s) held by more than one row, merged by the pending migration`,
+		);
+	}
+	if (report.parked === 0) {
+		lines.push("No message is parked by the folder dedupe");
+		return lines;
+	}
+	lines.push(
+		report.mode === "check"
+			? `${report.parked} message(s) parked by the folder dedupe, would be removed`
+			: `${report.removed} of ${report.parked} message(s) parked by the folder dedupe removed`,
+	);
+	return lines;
+};

package/src/repos/i4-account.test.ts

@@ -3,6 +3,7 @@ import { after, before, describe, test } from "node:test";
 import { createTestDb, randomId, type TestDb } from "../test-db.js";
 import { AccountRepo } from "./i4-account.js";
 import { MailboxRepo } from "./i4-mailbox.js";
+import { mailboxCreated } from "./test-helpers.js";
 
 function makeAccountInput(accountConfigId: string) {
 	return {
@@ -160,23 +161,25 @@ describe("AccountRepo", () => {
 		const account = await repo.create(makeAccountInput(accountConfigId));
 
 		const mailboxRepo = new MailboxRepo(db as never);
-		await mailboxRepo.create({
-			accountId: account.accountId,
-			namespaceType: "personal",
-			namespacePrefix: "",
-			hierarchyDelimiter: "/",
-			fullPath: "INBOX",
-			uidValidity: 1,
-			uidNext: 1,
-			highestModseq: "0",
-			messageCount: 0,
-			unseenCount: 0,
-			deletedCount: 0,
-			totalSize: 0,
-			lastSyncUid: 0,
-			highWaterMarkUid: 0,
-			lastMessageSyncAt: Date.now(),
-		});
+		mailboxCreated(
+			await mailboxRepo.create({
+				accountId: account.accountId,
+				namespaceType: "personal",
+				namespacePrefix: "",
+				hierarchyDelimiter: "/",
+				fullPath: "INBOX",
+				uidValidity: 1,
+				uidNext: 1,
+				highestModseq: "0",
+				messageCount: 0,
+				unseenCount: 0,
+				deletedCount: 0,
+				totalSize: 0,
+				lastSyncUid: 0,
+				highWaterMarkUid: 0,
+				lastMessageSyncAt: Date.now(),
+			}),
+		);
 
 		const desc = await repo.describe(account.accountId);
 		assert.equal(desc.account.length, 1);

package/src/repos/i4-mailbox-special-use.sqlite.test.ts

@@ -16,6 +16,7 @@ import { createSqliteTestDb } from "../test-db-sqlite.js";
 import { AccountSettingRepo } from "./i4-account-setting.js";
 import { MailboxRepo } from "./i4-mailbox.js";
 import { MailboxSpecialUseRepo } from "./i4-mailbox-special-use.js";
+import { mailboxCreated } from "./test-helpers.js";
 
 const makeMailboxInput = (
 	accountId: string,
@@ -103,11 +104,15 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("the appointment beats the folder the server flagged", async () => {
 		const { accountId, accountConfigId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const flagged = await mailboxes.create(makeMailboxInput(accountId, "Junk"));
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const flagged = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "Junk")),
+		);
 		await repo.create(flagged.mailboxId, "Junk");
-		const chosen = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Rubbish"),
+		const chosen = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Rubbish")),
 		);
 		await appoint(
 			accountConfigId,
@@ -126,10 +131,14 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 		// the user keeps mail in. `bin` is no longer a hint, and an appointment
 		// overrides the proposal either way.
 		const { accountId, accountConfigId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const bin = await mailboxes.create(makeMailboxInput(accountId, "Bin"));
-		const gmailTrash = await mailboxes.create(
-			makeMailboxInput(accountId, "[Gmail]/Trash"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const bin = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "Bin")),
+		);
+		const gmailTrash = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "[Gmail]/Trash")),
 		);
 
 		assert.equal(
@@ -151,9 +160,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("an appointment on a mailbox that is gone falls back rather than resolving to nothing", async () => {
 		const { accountId, accountConfigId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const archive = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Archive"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const archive = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Archive")),
 		);
 		await appoint(
 			accountConfigId,
@@ -171,12 +182,14 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 		// `Deleted` matches the name proposal, and emptying it would destroy mail
 		// the user never put in a trash folder (audit #841).
 		const { accountId, accountConfigId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const keepsakes = await mailboxes.create(
-			makeMailboxInput(accountId, "Deleted"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const keepsakes = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "Deleted")),
 		);
-		const trash = await mailboxes.create(
-			makeMailboxInput(accountId, "[Gmail]/Trash"),
+		const trash = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "[Gmail]/Trash")),
 		);
 
 		const proposal = await repo.resolveTrashRole(accountId);
@@ -201,9 +214,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 		// flagged folder both hide that; the resolution names the id the user chose
 		// so a refusal can offer the repair (#887).
 		const { accountId, accountConfigId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const flagged = await mailboxes.create(
-			makeMailboxInput(accountId, "[Gmail]/Trash"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const flagged = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "[Gmail]/Trash")),
 		);
 		await repo.create(flagged.mailboxId, "Trash");
 		const appointed = randomUUID();
@@ -237,9 +252,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("resolves an INBOX-nested Junk folder that advertises \\Junk", async () => {
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const spam = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Spam"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const spam = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Spam")),
 		);
 		await repo.create(spam.mailboxId, "Junk");
 
@@ -252,9 +269,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 		// bare names, so `INBOX/Spam` resolved to nothing on a server that
 		// advertises no \Junk.
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const spam = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Spam"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const spam = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Spam")),
 		);
 
 		const found = await repo.findJunkMailbox(accountId);
@@ -266,9 +285,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 		// whole-path rule, so `INBOX/Trash` resolved to nothing and a delete
 		// refused on an account that plainly has a Trash folder.
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const trash = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Trash"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const trash = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Trash")),
 		);
 
 		assert.equal(
@@ -286,9 +307,11 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("resolves an INBOX-nested Archive folder that advertises no special use", async () => {
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		const archive = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX/Archive"),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const archive = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Archive")),
 		);
 
 		assert.equal(
@@ -299,12 +322,14 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("splits the leaf on the account's own delimiter, not on a slash", async () => {
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX", "."));
-		const trash = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX.Trash", "."),
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX", ".")),
 		);
-		const archive = await mailboxes.create(
-			makeMailboxInput(accountId, "INBOX.Archive", "."),
+		const trash = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX.Trash", ".")),
+		);
+		const archive = mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX.Archive", ".")),
 		);
 
 		assert.equal(
@@ -319,8 +344,12 @@ describe("MailboxSpecialUseRepo role lookups (sqlite)", () => {
 
 	test("answers null when the account has no Junk folder at all", async () => {
 		const { accountId } = await makeAccount();
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX"));
-		await mailboxes.create(makeMailboxInput(accountId, "INBOX/Work"));
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		mailboxCreated(
+			await mailboxes.create(makeMailboxInput(accountId, "INBOX/Work")),
+		);
 
 		assert.equal(await repo.findJunkMailbox(accountId), null);
 	});

package/src/repos/i4-mailbox.sqlite.test.ts

@@ -11,6 +11,7 @@ import {
 	shippedTableDdl,
 } from "../test-shipped-sqlite-schema.js";
 import { MailboxRepo } from "./i4-mailbox.js";
+import { mailboxCreated } from "./test-helpers.js";
 
 function makeMailboxInput(accountId: string, fullPath = "INBOX") {
 	return {
@@ -50,10 +51,12 @@ describe("MailboxRepo (sqlite)", () => {
 		const accountId = randomUUID();
 		const modseq = "18446744073709551615";
 
-		const created = await repo.create({
-			...makeMailboxInput(accountId),
-			highestModseq: modseq,
-		});
+		const created = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId),
+				highestModseq: modseq,
+			}),
+		);
 		assert.equal(created.highestModseq, modseq);
 
 		const fetched = await repo.get(accountId, created.mailboxId);
@@ -70,8 +73,8 @@ describe("MailboxRepo (sqlite)", () => {
 
 	test("a row written without a state reads back synced (D1)", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create(
-			makeMailboxInput(accountId, "Discovered"),
+		const created = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Discovered")),
 		);
 		assert.equal(created.syncStatus, MailboxSyncStatus.synced);
 		const fetched = await repo.get(accountId, created.mailboxId);
@@ -80,7 +83,9 @@ describe("MailboxRepo (sqlite)", () => {
 
 	test("pendingPath round-trips and clears", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create(makeMailboxInput(accountId, "Archive"));
+		const created = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Archive")),
+		);
 		assert.equal(created.pendingPath, undefined);
 
 		const claimed = await repo.transition(accountId, created.mailboxId, {
@@ -102,6 +107,53 @@ describe("MailboxRepo (sqlite)", () => {
 		assert.equal(settled?.pendingPath, undefined);
 		assert.equal(settled?.fullPath, "Records");
 	});
+
+	test("a second row at a path the account holds is refused as PathTaken", async () => {
+		const accountId = randomUUID();
+		const first = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Notifications")),
+		);
+
+		const second = await repo.create(
+			makeMailboxInput(accountId, "Notifications"),
+		);
+
+		assert.deepEqual(second, { outcome: "PathTaken" });
+		assert.equal(
+			(await repo.findByPath(accountId, "Notifications"))?.mailboxId,
+			first.mailboxId,
+		);
+	});
+
+	test("another account may hold the same path", async () => {
+		const created = await repo.create(
+			makeMailboxInput(randomUUID(), "Notifications"),
+		);
+		assert.equal(created.outcome, "Created");
+	});
+
+	test("a write that moves a row onto a path another row holds is rejected", async () => {
+		const accountId = randomUUID();
+		mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "INBOX/Notifications")),
+		);
+		const recreated = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId, "Notifications"),
+				syncStatus: MailboxSyncStatus.pending,
+			}),
+		);
+
+		await assert.rejects(
+			repo.transition(accountId, recreated.mailboxId, {
+				from: [MailboxSyncStatus.pending],
+				wherePendingPath: null,
+				to: MailboxSyncStatus.synced,
+				set: { fullPath: "INBOX/Notifications" },
+			}),
+			/UNIQUE constraint failed: mailbox\.account_id, mailbox\.full_path/,
+		);
+	});
 });
 
 /**
@@ -126,6 +178,7 @@ describe("MailboxRepo (sqlite, shipped migrations)", () => {
 		applyMigration(sqlite, "0026_mailbox_sync_status_backfill");
 		applyMigration(sqlite, "0027_mailbox_sync_status_total");
 		applyMigration(sqlite, "0028_mailbox_pending_path");
+		applyMigration(sqlite, "0031_mailbox_path_unique");
 		const db = drizzle(sqlite, { schema: { mailbox: mailboxTable } });
 		repo = new MailboxRepo(db as never);
 		close = async () => {
@@ -146,10 +199,12 @@ describe("MailboxRepo (sqlite, shipped migrations)", () => {
 
 	test("reads a plain-digit cursor back as a string", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create({
-			...makeMailboxInput(accountId),
-			highestModseq: "900",
-		});
+		const created = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId),
+				highestModseq: "900",
+			}),
+		);
 
 		assert.strictEqual(created.highestModseq, "900");
 
@@ -159,10 +214,12 @@ describe("MailboxRepo (sqlite, shipped migrations)", () => {
 
 	test("keeps a resumable cursor intact", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create({
-			...makeMailboxInput(accountId, "Archive"),
-			highestModseq: "900:149",
-		});
+		const created = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId, "Archive"),
+				highestModseq: "900:149",
+			}),
+		);
 
 		const fetched = await repo.get(accountId, created.mailboxId);
 		assert.strictEqual(fetched.highestModseq, "900:149");
@@ -170,13 +227,17 @@ describe("MailboxRepo (sqlite, shipped migrations)", () => {
 
 	test("a row inserted without a state reads back synced", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create(makeMailboxInput(accountId, "Notes"));
+		const created = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Notes")),
+		);
 		assert.equal(created.syncStatus, MailboxSyncStatus.synced);
 	});
 
 	test("pendingPath round-trips and clears on the shipped shape", async () => {
 		const accountId = randomUUID();
-		const created = await repo.create(makeMailboxInput(accountId, "Receipts"));
+		const created = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Receipts")),
+		);
 
 		const claimed = await repo.transition(accountId, created.mailboxId, {
 			from: [MailboxSyncStatus.synced],
@@ -196,10 +257,12 @@ describe("MailboxRepo (sqlite, shipped migrations)", () => {
 	test("round-trips a cursor above 2^53 with its exact digits", async () => {
 		const accountId = randomUUID();
 		const modseq = "18446744073709551615";
-		const created = await repo.create({
-			...makeMailboxInput(accountId, "Sent"),
-			highestModseq: modseq,
-		});
+		const created = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId, "Sent"),
+				highestModseq: modseq,
+			}),
+		);
 
 		assert.strictEqual(created.highestModseq, modseq);
 		const fetched = await repo.get(accountId, created.mailboxId);

package/src/repos/i4-mailbox.test.ts

@@ -18,6 +18,7 @@ import { createTestDb, randomId, type TestDb } from "../test-db.js";
 import { runInTransaction } from "../tx.js";
 import { MailboxRepo } from "./i4-mailbox.js";
 import { DrizzleMessageRepository, deleteMessageSubtree } from "./message.js";
+import { mailboxCreated } from "./test-helpers.js";
 
 /** Every state a row can carry, for a transition that decides against none. */
 const EVERY_STATE = [
@@ -63,7 +64,9 @@ describe("MailboxRepo", () => {
 
 	test("create and get", async () => {
 		const accountId = randomId();
-		const mailbox = await repo.create(makeMailboxInput(accountId));
+		const mailbox = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId)),
+		);
 		assert.ok(mailbox.mailboxId);
 		assert.equal(mailbox.fullPath, "INBOX");
 
@@ -76,10 +79,12 @@ describe("MailboxRepo", () => {
 	test("highestModseq round-trips a value above 2^53 without loss (reader#9)", async () => {
 		const accountId = randomId();
 		const modseq = "18446744073709551615";
-		const created = await repo.create({
-			...makeMailboxInput(accountId),
-			highestModseq: modseq,
-		});
+		const created = mailboxCreated(
+			await repo.create({
+				...makeMailboxInput(accountId),
+				highestModseq: modseq,
+			}),
+		);
 		assert.equal(created.highestModseq, modseq);
 
 		const fetched = await repo.get(accountId, created.mailboxId);
@@ -98,8 +103,12 @@ describe("MailboxRepo", () => {
 
 	test("batchGet: WHERE id = ANY($1)", async () => {
 		const accountId = randomId();
-		const m1 = await repo.create(makeMailboxInput(accountId, "INBOX"));
-		const m2 = await repo.create(makeMailboxInput(accountId, "Sent"));
+		const m1 = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "INBOX")),
+		);
+		const m2 = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Sent")),
+		);
 
 		const results = await repo.get(accountId, [m1.mailboxId, m2.mailboxId]);
 		assert.equal(results.length, 2);
@@ -114,7 +123,9 @@ describe("MailboxRepo", () => {
 
 	test("findByPath finds existing mailbox", async () => {
 		const accountId = randomId();
-		await repo.create(makeMailboxInput(accountId, "Work/Projects"));
+		mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Work/Projects")),
+		);
 
 		const found = await repo.findByPath(accountId, "Work/Projects");
 		assert.ok(found);
@@ -145,9 +156,13 @@ describe("MailboxRepo", () => {
 
 	test("findByPathPrefix finds children", async () => {
 		const accountId = randomId();
-		await repo.create(makeMailboxInput(accountId, "Work"));
-		await repo.create(makeMailboxInput(accountId, "Work/Projects"));
-		await repo.create(makeMailboxInput(accountId, "Work/Projects/Alpha"));
+		mailboxCreated(await repo.create(makeMailboxInput(accountId, "Work")));
+		mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Work/Projects")),
+		);
+		mailboxCreated(
+			await repo.create(makeMailboxInput(accountId, "Work/Projects/Alpha")),
+		);
 
 		const children = await repo.findByPathPrefix(accountId, "Work");
 		assert.ok(children.some((m) => m.fullPath === "Work/Projects"));
@@ -161,8 +176,8 @@ describe("MailboxRepo", () => {
 
 	test("findByPathPrefix finds nothing in a flat namespace", async () => {
 		const accountId = randomId();
-		await repo.create(makeMailboxInput(accountId, "Work"));
-		await repo.create(makeMailboxInput(accountId, "Workshop"));
+		mailboxCreated(await repo.create(makeMailboxInput(accountId, "Work")));
+		mailboxCreated(await repo.create(makeMailboxInput(accountId, "Workshop")));
 
 		assert.deepEqual(await repo.findByPathPrefix(accountId, "Work", ""), []);
 	});
@@ -170,7 +185,9 @@ describe("MailboxRepo", () => {
 	test("cross-tenant: get refuses a foreign account", async () => {
 		const accountId = randomId();
 		const other = randomId();
-		const mailbox = await repo.create(makeMailboxInput(accountId));
+		const mailbox = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId)),
+		);
 
 		await assert.rejects(
 			() => repo.get(other, mailbox.mailboxId),
@@ -186,7 +203,9 @@ describe("MailboxRepo", () => {
 	test("cross-tenant: update refuses a foreign account and leaves the row unchanged", async () => {
 		const accountId = randomId();
 		const other = randomId();
-		const mailbox = await repo.create(makeMailboxInput(accountId));
+		const mailbox = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId)),
+		);
 
 		await assert.rejects(
 			() => repo.update(other, mailbox.mailboxId, { messageCount: 99 }),
@@ -201,7 +220,9 @@ describe("MailboxRepo", () => {
 	test("cross-tenant: delete is a no-op for a foreign account", async () => {
 		const accountId = randomId();
 		const other = randomId();
-		const mailbox = await repo.create(makeMailboxInput(accountId));
+		const mailbox = mailboxCreated(
+			await repo.create(makeMailboxInput(accountId)),
+		);
 
 		await repo.delete(other, mailbox.mailboxId);
 		const still = await repo.get(accountId, mailbox.mailboxId);
@@ -213,8 +234,8 @@ describe("MailboxRepo", () => {
 	test("cross-tenant: deleteMany only removes ids owned by the tenant", async () => {
 		const accountA = randomId();
 		const accountB = randomId();
-		const a = await repo.create(makeMailboxInput(accountA));
-		const b = await repo.create(makeMailboxInput(accountB));
+		const a = mailboxCreated(await repo.create(makeMailboxInput(accountA)));
+		const b = mailboxCreated(await repo.create(makeMailboxInput(accountB)));
 
 		await repo.deleteMany(accountA, [a.mailboxId, b.mailboxId]);
 
@@ -231,7 +252,9 @@ describe("MailboxRepo", () => {
 	describe("transition — the conditional write (D3)", () => {
 		test("an accepted from-state applies the new state and the set fields", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Archive"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Archive")),
+			);
 
 			const written = await repo.transition(accountId, mailbox.mailboxId, {
 				from: [MailboxSyncStatus.synced, MailboxSyncStatus.failed],
@@ -246,7 +269,9 @@ describe("MailboxRepo", () => {
 
 		test("a state outside `from` writes nothing and leaves the row byte-identical", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Work"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Work")),
+			);
 			const before = await repo.get(accountId, mailbox.mailboxId);
 
 			const lost = await repo.transition(accountId, mailbox.mailboxId, {
@@ -271,7 +296,9 @@ describe("MailboxRepo", () => {
 
 		test("wherePendingPath as a string matches only that target", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Bills"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Bills")),
+			);
 			await repo.transition(accountId, mailbox.mailboxId, {
 				from: [MailboxSyncStatus.synced],
 				to: MailboxSyncStatus.pending,
@@ -302,7 +329,9 @@ describe("MailboxRepo", () => {
 			// `synced` with the rename target still on it, and the rename then
 			// never runs and is never marked failed.
 			const accountId = randomId();
-			const claimed = await repo.create(makeMailboxInput(accountId, "Notes"));
+			const claimed = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Notes")),
+			);
 			await repo.transition(accountId, claimed.mailboxId, {
 				from: [MailboxSyncStatus.synced],
 				to: MailboxSyncStatus.pending,
@@ -320,10 +349,12 @@ describe("MailboxRepo", () => {
 			assert.equal(still.syncStatus, MailboxSyncStatus.pending);
 			assert.equal(still.pendingPath, "Journal");
 
-			const creating = await repo.create({
-				...makeMailboxInput(accountId, "Fresh"),
-				syncStatus: MailboxSyncStatus.pending,
-			});
+			const creating = mailboxCreated(
+				await repo.create({
+					...makeMailboxInput(accountId, "Fresh"),
+					syncStatus: MailboxSyncStatus.pending,
+				}),
+			);
 			const settled = await repo.transition(accountId, creating.mailboxId, {
 				from: [MailboxSyncStatus.pending],
 				wherePendingPath: null,
@@ -334,7 +365,9 @@ describe("MailboxRepo", () => {
 
 		test("omitting wherePendingPath predicates on syncStatus alone", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Old"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Old")),
+			);
 			await repo.transition(accountId, mailbox.mailboxId, {
 				from: [MailboxSyncStatus.synced],
 				to: MailboxSyncStatus.pending,
@@ -355,7 +388,9 @@ describe("MailboxRepo", () => {
 			// rename target on it is what strands a folder whose rename then never
 			// runs and is never marked failed.
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Trips"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Trips")),
+			);
 
 			for (const to of EVERY_STATE) {
 				const written = await repo.transition(accountId, mailbox.mailboxId, {
@@ -380,7 +415,9 @@ describe("MailboxRepo", () => {
 
 		test("two overlapping transitions with the same from: exactly one wins", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Races"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Races")),
+			);
 
 			const outcomes = await Promise.all([
 				repo.transition(accountId, mailbox.mailboxId, {
@@ -398,7 +435,9 @@ describe("MailboxRepo", () => {
 
 		test("cross-tenant: a foreign account transitions nothing", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Private"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Private")),
+			);
 
 			assert.equal(
 				await repo.transition(randomId(), mailbox.mailboxId, {
@@ -416,10 +455,14 @@ describe("MailboxRepo", () => {
 
 	describe("transitionSubtree — the intent, all-or-nothing (D6)", () => {
 		const seedSubtree = async (accountId: string) => ({
-			parent: await repo.create(makeMailboxInput(accountId, "Work")),
-			child: await repo.create(makeMailboxInput(accountId, "Work/Projects")),
-			grandchild: await repo.create(
-				makeMailboxInput(accountId, "Work/Projects/Alpha"),
+			parent: mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Work")),
+			),
+			child: mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Work/Projects")),
+			),
+			grandchild: mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Work/Projects/Alpha")),
 			),
 		});
 
@@ -568,8 +611,12 @@ describe("MailboxRepo", () => {
 
 		test("removes the folder, its mail and its own child rows, and nothing else's", async () => {
 			const accountId = randomId();
-			const doomed = await repo.create(makeMailboxInput(accountId, "Receipts"));
-			const spared = await repo.create(makeMailboxInput(accountId, "Keep"));
+			const doomed = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Receipts")),
+			);
+			const spared = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Keep")),
+			);
 			const doomedMessage = await seedMessage(doomed.mailboxId, 1);
 			const sparedMessage = await seedMessage(spared.mailboxId, 1);
 			await db.insert(mailboxSpecialUseTable).values({
@@ -636,7 +683,9 @@ describe("MailboxRepo", () => {
 			// delete is the outcome the design rules out. This is the test that
 			// stops a future refactor doing it.
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Bound"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Bound")),
+			);
 			const filterId = randomId();
 			await db.insert(filterTable).values({
 				filterId,
@@ -662,7 +711,9 @@ describe("MailboxRepo", () => {
 
 		test("re-running after a partial removal completes", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Resume"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Resume")),
+			);
 			const first = await seedMessage(mailbox.mailboxId, 1);
 			await seedMessage(mailbox.mailboxId, 2);
 
@@ -691,7 +742,9 @@ describe("MailboxRepo", () => {
 
 		test("cross-tenant: a foreign account removes neither the row nor its mail", async () => {
 			const accountId = randomId();
-			const mailbox = await repo.create(makeMailboxInput(accountId, "Mine"));
+			const mailbox = mailboxCreated(
+				await repo.create(makeMailboxInput(accountId, "Mine")),
+			);
 			await seedMessage(mailbox.mailboxId, 1);
 
 			await repo.deleteMailboxWithMail(randomId(), mailbox.mailboxId);

package/src/repos/i4-mailbox.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type {
 	CreateMailboxInput,
+	CreateMailboxResult,
 	IMailboxRepository,
 	MailboxItem,
 	MailboxStatePredicate,
@@ -128,7 +129,7 @@ export function rowToMailbox(
 export class MailboxRepo implements IMailboxRepository {
 	constructor(private db: DB) {}
 
-	async create(input: CreateMailboxInput): Promise<MailboxItem> {
+	async create(input: CreateMailboxInput): Promise<CreateMailboxResult> {
 		const now = Date.now();
 		const [row] = await this.db
 			.insert(mailboxTable)
@@ -160,8 +161,12 @@ export class MailboxRepo implements IMailboxRepository {
 				createdAt: now,
 				updatedAt: now,
 			})
+			.onConflictDoNothing({
+				target: [mailboxTable.accountId, mailboxTable.fullPath],
+			})
 			.returning();
-		return rowToMailbox(row);
+		if (!row) return { outcome: "PathTaken" };
+		return { outcome: "Created", mailbox: rowToMailbox(row) };
 	}
 
 	async get(accountId: string, mailboxId: string): Promise<MailboxItem>;
@@ -444,7 +449,13 @@ export class MailboxRepo implements IMailboxRepository {
 	): Promise<MailboxItem> {
 		const existing = await this.findByPath(accountId, fullPath);
 		if (existing) return existing;
-		return this.create({ accountId, fullPath, ...defaults });
+		const created = await this.create({ accountId, fullPath, ...defaults });
+		if (created.outcome === "Created") return created.mailbox;
+		const winner = await this.findByPath(accountId, fullPath);
+		if (!winner) {
+			throw new NotFoundError(`Mailbox not found at path: ${fullPath}`);
+		}
+		return winner;
 	}
 
 	async findByPathPrefix(

package/src/repos/test-helpers.ts

@@ -1,3 +1,4 @@
+import type { CreateMailboxResult, MailboxItem } from "@remit/data-ports";
 import type Database from "better-sqlite3";
 import type { Db } from "../db.js";
 import {
@@ -20,3 +21,10 @@ export async function createTestDb(): Promise<{
 	const { db, sqlite, close } = await createSqliteTestDb(messageDataSchema);
 	return { db, sqlite, stop: close };
 }
+
+export const mailboxCreated = (result: CreateMailboxResult): MailboxItem => {
+	if (result.outcome !== "Created") {
+		throw new Error("The account already has a folder at that path");
+	}
+	return result.mailbox;
+};