@remit/mailbox-service 0.0.92 → 0.0.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.92",
+  "version": "0.0.93",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -179,8 +179,9 @@ export {
 	validateMailboxPath,
 } from "./mailbox-management.js";
 export {
-	isFolderOffServer,
-	isMailboxNotOnServer,
+	EVERY_MAILBOX_STATE,
+	isFolderMutationInFlight,
+	isMailboxMutationInFlight,
 } from "./mailbox-presence.js";
 export {
 	type CreateMailboxQueueInput,

package/src/mailbox-management.test.ts

@@ -1,6 +1,9 @@
 import assert from "node:assert";
 import { describe, it } from "node:test";
-import type { IMailboxRepository } from "@remit/data-ports";
+import type {
+	IMailboxRepository,
+	MailboxTransitionIntent,
+} from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import {
 	MailboxManagementService,
@@ -99,7 +102,14 @@ const boxStatus = (path: string): ImapBoxStatus => ({
 const recordingRepo = () => {
 	const updates: Array<{ mailboxId: string; patch: Record<string, unknown> }> =
 		[];
-	const repo: Pick<IMailboxRepository, "update" | "findByPathPrefix"> = {
+	const settles: Array<{
+		mailboxId: string;
+		intent: MailboxTransitionIntent;
+	}> = [];
+	const repo: Pick<
+		IMailboxRepository,
+		"update" | "transition" | "findByPathPrefix"
+	> = {
 		update: async (
 			_accountId: string,
 			mailboxId: string,
@@ -108,9 +118,17 @@ const recordingRepo = () => {
 			updates.push({ mailboxId, patch });
 			return {} as never;
 		},
+		transition: async (
+			_accountId: string,
+			mailboxId: string,
+			intent: MailboxTransitionIntent,
+		) => {
+			settles.push({ mailboxId, intent });
+			return {} as never;
+		},
 		findByPathPrefix: async () => [],
 	};
-	return { repo: repo as IMailboxRepository, updates };
+	return { repo: repo as IMailboxRepository, updates, settles };
 };
 
 const stubConnection = (
@@ -143,7 +161,7 @@ const stubConnection = (
 
 describe("MailboxManagementService.syncCreate — server path normalization", () => {
 	it("adopts the server-materialized path as the row's identity when it is prefixed", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection, opened } = stubConnection("INBOX/Notifications", [
 			"INBOX/Notifications",
 		]);
@@ -159,28 +177,28 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		assert.strictEqual(result.success, true);
 		// The mailbox is opened at the server's path, not the requested leaf.
 		assert.deepStrictEqual(opened, ["INBOX/Notifications"]);
-		assert.strictEqual(updates.length, 1);
+		assert.strictEqual(settles.length, 1);
 		// The row keeps its id and takes on the prefixed path, so the next reconcile
 		// updates it in place instead of insert+delete — every reference survives.
-		assert.strictEqual(updates[0].mailboxId, "mbx-1");
-		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles[0].mailboxId, "mbx-1");
+		assert.strictEqual(settles[0].intent.set?.fullPath, "INBOX/Notifications");
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("leaves the path untouched when the server keeps it as requested", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection } = stubConnection("Work", ["Work"]);
 		const service = new MailboxManagementService(repo);
 
 		await service.syncCreate("acc-1", "mbx-2", "Work", async () => connection);
 
-		assert.strictEqual(updates.length, 1);
-		assert.ok(!("fullPath" in updates[0].patch));
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.deepStrictEqual(settles[0].intent.set, {});
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("still adopts the server path when the fresh list cannot resolve it", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection, opened } = stubConnection("INBOX/Notifications", []);
 		const service = new MailboxManagementService(repo);
 
@@ -192,13 +210,13 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		);
 
 		assert.deepStrictEqual(opened, []);
-		assert.strictEqual(updates.length, 1);
-		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.strictEqual(settles[0].intent.set?.fullPath, "INBOX/Notifications");
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("falls back to the requested path when the create result carries none", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const opened: string[] = [];
 		const subscribed: string[] = [];
 		const connection = {
@@ -234,9 +252,9 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		// A thin result never blanks fullPath — the requested path is used throughout.
 		assert.deepStrictEqual(subscribed, ["Archive"]);
 		assert.deepStrictEqual(opened, ["Archive"]);
-		assert.strictEqual(updates.length, 1);
-		assert.ok(!("fullPath" in updates[0].patch));
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.deepStrictEqual(settles[0].intent.set, {});
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 });
 

package/src/mailbox-management.ts

@@ -1,6 +1,7 @@
 import type { IMailboxRepository } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import { MailboxSyncStatus } from "@remit/domain-enums";
-import { isNotFoundError } from "./mailbox-presence.js";
+import { EVERY_MAILBOX_STATE, isNotFoundError } from "./mailbox-presence.js";
 import type { IImapConnection } from "./types.js";
 
 /**
@@ -115,6 +116,30 @@ export class MailboxManagementService {
 		this.log = logger ?? noopLogger;
 	}
 
+	/**
+	 * Write the settled state back, as the conditional write that is now the
+	 * only way to write it at all (D3). The from-set is every state because that
+	 * is what this settle decides against today — it is the unconditional write
+	 * it replaces, moved onto the door; #363 narrows it to the state its intent
+	 * recorded and gives a lost predicate its `already-settled` outcome.
+	 *
+	 * A null means the row is gone, which is what the unconditional write raised
+	 * a NotFoundError for, and what the handlers' #289-class terminal guards
+	 * classify as the user having deleted the folder mid-sync.
+	 */
+	private settle = async (
+		accountId: string,
+		mailboxId: string,
+		confirmedPath?: string,
+	): Promise<void> => {
+		const settled = await this.mailboxService.transition(accountId, mailboxId, {
+			from: EVERY_MAILBOX_STATE,
+			to: MailboxSyncStatus.synced,
+			set: confirmedPath !== undefined ? { fullPath: confirmedPath } : {},
+		});
+		if (!settled) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+	};
+
 	/**
 	 * Sync a CREATE operation to IMAP.
 	 * Called by worker after dequeuing MAILBOX_CREATE event.
@@ -149,7 +174,7 @@ export class MailboxManagementService {
 			typeof result.path === "string" && result.path.length > 0
 				? result.path
 				: path;
-		const pathUpdate = serverPath !== path ? { fullPath: serverPath } : {};
+		const confirmedPath = serverPath !== path ? serverPath : undefined;
 
 		this.log.info(
 			{ mailboxId, path, serverPath, created: result.created },
@@ -169,21 +194,24 @@ export class MailboxManagementService {
 			// Open the mailbox to get UIDVALIDITY and other status info
 			const status = await connection.openBox(serverPath, true);
 
+			// Two writes where there was one, and the settle is deliberately the
+			// second: counters are ordinary metadata and stay off the transition,
+			// whose whole point is that its write-set is the state (D3). A crash in
+			// between leaves the row `pending` with fresh counters, and the row not
+			// yet settled is what keeps the queue message unacked — the redelivery
+			// re-issues CREATE, the server answers ALREADYEXISTS, and #339's
+			// classification settles it. Settling first would be the unsafe order.
 			await this.mailboxService.update(accountId, mailboxId, {
-				...pathUpdate,
 				uidValidity: status.uidvalidity,
 				uidNext: status.uidnext,
 				messageCount: status.messages.total,
-				syncStatus: MailboxSyncStatus.synced,
 			});
+			await this.settle(accountId, mailboxId, confirmedPath);
 
 			await connection.closeBox();
 		} else {
 			// Mark as synced even if we couldn't get full info
-			await this.mailboxService.update(accountId, mailboxId, {
-				...pathUpdate,
-				syncStatus: MailboxSyncStatus.synced,
-			});
+			await this.settle(accountId, mailboxId, confirmedPath);
 		}
 
 		return { success: true };
@@ -215,11 +243,7 @@ export class MailboxManagementService {
 			"Renamed mailbox on IMAP server",
 		);
 
-		// Clear oldPath and mark as synced
-		await this.mailboxService.update(accountId, mailboxId, {
-			oldPath: undefined,
-			syncStatus: MailboxSyncStatus.synced,
-		});
+		await this.settle(accountId, mailboxId);
 
 		// The server rename is done and the row records it. The settle is repair
 		// work on top of that, so nothing it hits — the listing included — may reach
@@ -268,16 +292,17 @@ export class MailboxManagementService {
 		);
 
 		for (const descendant of descendants) {
-			if (descendant.syncStatus !== MailboxSyncStatus.pending) continue;
 			if (!onServer.has(descendant.fullPath)) continue;
-			await this.mailboxService
-				.update(accountId, descendant.mailboxId, {
-					syncStatus: MailboxSyncStatus.synced,
-				})
-				.catch((error: unknown) => {
-					if (isNotFoundError(error)) return;
-					throw error;
-				});
+			// The per-row settle of D15: `pending` is the state that carries the
+			// intent, and the predicate is on the UPDATE, so a row another client
+			// moved in between is skipped rather than overwritten. A row that is
+			// gone is skipped for free — a null is not an error here, which is what
+			// keeps a descendant deleted mid-settle out of the handler's
+			// whole-chain NotFoundError guard.
+			await this.mailboxService.transition(accountId, descendant.mailboxId, {
+				from: [MailboxSyncStatus.pending],
+				to: MailboxSyncStatus.synced,
+			});
 		}
 	};
 

package/src/mailbox-presence.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IMailboxRepository } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	isFolderMutationInFlight,
+	isMailboxMutationInFlight,
+} from "./mailbox-presence.js";
+
+const reader = (
+	get: IMailboxRepository["get"],
+): Pick<IMailboxRepository, "get"> => ({ get });
+
+describe("isFolderMutationInFlight", () => {
+	for (const [syncStatus, inFlight] of [
+		[MailboxSyncStatus.synced, false],
+		[MailboxSyncStatus.pending, true],
+		[MailboxSyncStatus.deleting, true],
+		[MailboxSyncStatus.failed, false],
+	] as const) {
+		it(`${syncStatus} is ${inFlight ? "" : "not "}a mutation in flight`, () => {
+			assert.equal(isFolderMutationInFlight({ syncStatus }), inFlight);
+		});
+	}
+
+	it("does not read failed as a folder to leave alone", () => {
+		// `failed` means the folder exists at `fullPath` and the last rename or
+		// delete intent did not land — so it holds the user's mail and syncing it
+		// is right. D7 upholds that by leaving no row at all for a create the
+		// server refused. Reading it as in-flight would stop syncing a live folder
+		// permanently and silently.
+		assert.equal(
+			isFolderMutationInFlight({ syncStatus: MailboxSyncStatus.failed }),
+			false,
+		);
+	});
+});
+
+describe("isMailboxMutationInFlight", () => {
+	it("reads the row it is given", async () => {
+		const service = reader((async () => ({
+			syncStatus: MailboxSyncStatus.deleting,
+		})) as unknown as IMailboxRepository["get"]);
+
+		assert.equal(await isMailboxMutationInFlight(service, "acc", "mbx"), true);
+	});
+
+	it("treats an absent row as in flight", async () => {
+		// The row's absence does not decide it at either end: on the way out the
+		// row is removed only after the IMAP folder is, and on the way in the row
+		// exists before the folder does.
+		const service = reader((async () => {
+			throw new NotFoundError("Mailbox not found: mbx");
+		}) as unknown as IMailboxRepository["get"]);
+
+		assert.equal(await isMailboxMutationInFlight(service, "acc", "mbx"), true);
+	});
+
+	it("rethrows a read that cannot answer", async () => {
+		// The caller uses this to classify a failure in hand; a read that fails
+		// for its own reasons must not be reported as "the folder is busy".
+		const service = reader((async () => {
+			throw new Error("connection reset by peer");
+		}) as unknown as IMailboxRepository["get"]);
+
+		await assert.rejects(
+			isMailboxMutationInFlight(service, "acc", "mbx"),
+			/connection reset by peer/,
+		);
+	});
+});

package/src/mailbox-presence.ts

@@ -5,43 +5,65 @@ export const isNotFoundError = (error: unknown): boolean =>
 	error instanceof Error && error.name === "NotFoundError";
 
 /**
- * Whether the IMAP server is not known to hold this folder — the row is gone,
- * its creation has not reached the server yet, or its deletion has been asked
- * for and not finished. Folders are written locally first and reconciled to the
- * server by the worker, so both ends of that lifecycle are states in which
- * syncing the folder can only fail.
+ * Every state a mailbox row can carry, for a transition whose caller decided
+ * against none of them.
  *
- * This is the terminal test for a sync event whose folder is not there. The
- * row's absence alone does not decide it, at either end: on the way out the row
- * is removed only after the IMAP folder is, so an event that fails against the
- * server still sees a live row for as long as that write takes; on the way in
- * the row exists before the folder does. `pending` and `deleting` are written by
- * the request itself, before the event that resolves it is enqueued, which is
- * what makes them sound proxies for presence: neither can be observed unless a
- * create has yet to land or a delete has been asked for.
+ * A transition predicate is supposed to name the state the caller read
+ * (docs/architecture/folder-rename-and-delete.md D3), and the intent recorders
+ * and settles that use this one name nothing yet: they are today's
+ * unconditional writes, moved onto the only door that can write a folder state
+ * at all. Each is narrowed to the from-set its transition-table row allows when
+ * the intents themselves land (#362, #363), which is also where a loser gets
+ * its 409.
+ */
+export const EVERY_MAILBOX_STATE = [
+	MailboxSyncStatus.synced,
+	MailboxSyncStatus.pending,
+	MailboxSyncStatus.failed,
+	MailboxSyncStatus.deleting,
+] as const;
+
+/**
+ * Whether a folder mutation is in flight, so nothing else may touch the folder
+ * over IMAP.
+ *
+ * It used to be spelled as a presence test — is the folder off the server —
+ * and that is no longer what it asks. Under D2 `fullPath` is always a path the
+ * server holds, rename target and all, so a rename-pending folder *is* on the
+ * server; what the two states share is that a worker owns the folder until its
+ * mutation settles. `pending` and `deleting` are written by the request itself,
+ * before the event that resolves it is enqueued, so neither can be observed
+ * unless a create or rename has yet to land or a delete has been asked for.
+ *
+ * This is the terminal test for a sync event whose folder is not the sync's to
+ * touch. The row's absence alone does not decide it, at either end: on the way
+ * out the row is removed only after the IMAP folder is, so an event that fails
+ * against the server still sees a live row for as long as that write takes; on
+ * the way in the row exists before the folder does.
+ *
+ * `failed` is deliberately not one of them. The invariant is that a `failed`
+ * row's folder exists at `fullPath` and the last rename or delete intent did
+ * not land — so the folder holds the user's mail and syncing it is right.
+ * D7 is what upholds that: a create the server refuses leaves no row at all,
+ * rather than a `failed` one standing for a folder that was never made. Reading
+ * `failed` as off-server would stop syncing a live folder permanently and
+ * silently, which is worse than the bounded stall it would remove.
  *
- * `failed` is deliberately not one of them, though it is the fourth state a
- * mailbox row can carry. It records that the last management operation failed
- * and says nothing about whether the folder is on the server: `handleDelete` and
- * `handleRename` set it on folders that exist and hold the user's mail, and
- * nothing ever clears it — `syncStatus` returns to `synced` only from a
- * subsequent successful create or rename, never from the sweep. Treating it as
- * off-server would stop syncing such a folder permanently and silently, which is
- * worse than the bounded stall it would remove. A `failed` row whose folder is
- * genuinely absent is reaped by the sweep's own cleanup, which runs before the
- * fan-out that would enqueue work for it.
+ * A rename-pending folder is skipped even though its `fullPath` is live. That
+ * is conservative rather than necessary (D12): it keeps this a single
+ * expression and costs a few seconds of sync for one folder.
  *
  * Mailbox management is judged differently — it is what establishes and removes
  * the folder, so it terminates on a not-found row alone.
  */
-export const isFolderOffServer = (
+export const isFolderMutationInFlight = (
 	mailbox: Pick<MailboxItem, "syncStatus">,
 ): boolean =>
 	mailbox.syncStatus === MailboxSyncStatus.pending ||
 	mailbox.syncStatus === MailboxSyncStatus.deleting;
 
-/** {@link isFolderOffServer} for a mailbox that has to be read first, an absent row included. */
-export const isMailboxNotOnServer = async (
+/** {@link isFolderMutationInFlight} for a mailbox that has to be read first, an absent row included. */
+export const isMailboxMutationInFlight = async (
 	mailboxService: Pick<IMailboxRepository, "get">,
 	accountId: string,
 	mailboxId: string,
@@ -53,5 +75,5 @@ export const isMailboxNotOnServer = async (
 			throw error;
 		});
 	if (!mailbox) return true;
-	return isFolderOffServer(mailbox);
+	return isFolderMutationInFlight(mailbox);
 };

package/src/mailbox-queue.ts

@@ -5,8 +5,11 @@ import type {
 	IMailboxRepository,
 	MailboxItem,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
+import { EVERY_MAILBOX_STATE } from "./mailbox-presence.js";
 
 /**
  * MAILBOX_CREATE event structure (matches remit-imap-worker/events.ts)
@@ -163,19 +166,32 @@ export class MailboxQueueService {
 		const mailbox = await this.mailboxService.get(accountId, mailboxId);
 		const oldPath = mailbox.fullPath;
 
-		// Update the mailbox path and set syncStatus to pending
-		const updated = await this.mailboxService.update(accountId, mailboxId, {
-			fullPath: newPath,
-			syncStatus: MailboxSyncStatus.pending,
-		});
-
-		// Update child mailbox paths
-		await this.mailboxService.renameChildPaths(
-			mailbox.accountId,
-			oldPath,
-			newPath,
-			mailbox.hierarchyDelimiter,
+		// One intent over the folder and every descendant, in one transaction:
+		// IMAP RENAME moves the subtree in one command, so a partially recorded
+		// rename is the state that produced today's phantom rows (D6). Each
+		// descendant's new path is equally absent from the server until
+		// MAILBOX_RENAME lands, so each is `pending` too — otherwise a reconcile
+		// in that window reaps it as server-deleted (#290).
+		const written = await this.mailboxService.transitionSubtree(
+			accountId,
+			mailboxId,
+			{
+				from: EVERY_MAILBOX_STATE,
+				to: MailboxSyncStatus.pending,
+				rowSet: (row) => {
+					const moved = rebaseMailboxPath(
+						row.fullPath,
+						oldPath,
+						newPath,
+						mailbox.hierarchyDelimiter,
+					);
+					return moved === undefined ? {} : { fullPath: moved };
+				},
+			},
 		);
+		if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+		const updated = written.find((row) => row.mailboxId === mailboxId);
+		if (!updated) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 
 		this.log.info({ mailboxId, oldPath, newPath }, "Renamed mailbox (local)");
 
@@ -208,9 +224,12 @@ export class MailboxQueueService {
 		const mailbox = await this.mailboxService.get(accountId, mailboxId);
 
 		// Mark as deleting (soft delete - worker will do actual delete after IMAP sync)
-		await this.mailboxService.update(accountId, mailboxId, {
-			syncStatus: MailboxSyncStatus.deleting,
-		});
+		const recorded = await this.mailboxService.transition(
+			accountId,
+			mailboxId,
+			{ from: EVERY_MAILBOX_STATE, to: MailboxSyncStatus.deleting },
+		);
+		if (!recorded) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 
 		this.log.info(
 			{ mailboxId, path: mailbox.fullPath },

package/src/mailbox-rename-intent.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { MailboxQueueService } from "./mailbox-queue.js";
+
+const row = (mailboxId: string, fullPath: string): MailboxItem =>
+	({
+		mailboxId,
+		accountId: "acc-1",
+		fullPath,
+		hierarchyDelimiter: "/",
+		syncStatus: MailboxSyncStatus.synced,
+	}) as MailboxItem;
+
+/**
+ * A repository that resolves the subtree and applies `rowSet` the way the real
+ * one does, so the paths the intent records are the paths under test.
+ */
+const store = (rows: MailboxItem[]) => {
+	const byId = new Map(rows.map((r) => [r.mailboxId, { ...r }]));
+
+	const repo: Pick<IMailboxRepository, "get" | "transitionSubtree"> = {
+		get: (async (_accountId: string, mailboxId: string) => {
+			const found = byId.get(mailboxId as string);
+			if (!found) {
+				throw Object.assign(new Error(`Mailbox not found: ${mailboxId}`), {
+					name: "NotFoundError",
+				});
+			}
+			return found;
+		}) as IMailboxRepository["get"],
+		transitionSubtree: async (_accountId, mailboxId, intent) => {
+			const root = byId.get(mailboxId);
+			if (!root) return null;
+			const prefix = `${root.fullPath}${root.hierarchyDelimiter}`;
+			const subtree = [
+				root,
+				...[...byId.values()].filter(
+					(r) => r !== root && r.fullPath.startsWith(prefix),
+				),
+			];
+			const written: MailboxItem[] = [];
+			for (const candidate of subtree) {
+				if (!intent.from.includes(candidate.syncStatus)) return null;
+				const next = {
+					...candidate,
+					...intent.rowSet(candidate),
+					syncStatus: intent.to,
+				} as MailboxItem;
+				byId.set(candidate.mailboxId, next);
+				written.push(next);
+			}
+			// The port promises no ordering beyond "the named folder first", so
+			// hand the caller the least convenient order it is allowed to return.
+			return written.reverse();
+		},
+	};
+
+	return {
+		repo: repo as IMailboxRepository,
+		pathOf: (id: string) => byId.get(id)?.fullPath,
+	};
+};
+
+const queueOver = (repo: IMailboxRepository) => {
+	const sent: string[] = [];
+	const service = new MailboxQueueService({
+		mailboxService: repo,
+		sqsQueueUrl: "http://localhost:4566/000000000000/mailbox",
+	});
+	(
+		service as unknown as {
+			sqs: {
+				send: (command: { input: { MessageBody: string } }) => Promise<void>;
+			};
+		}
+	).sqs = {
+		send: async (command) => {
+			sent.push(command.input.MessageBody);
+		},
+	};
+	return { service, sent };
+};
+
+describe("MailboxQueueService.renameMailbox — the recorded intent", () => {
+	it("records the path the RENAME will carry, `$` patterns and all", async () => {
+		// `String.prototype.replace` expands `$&`, "$`", `$'` and `$$` in the
+		// replacement, so a folder renamed to a name containing one of them was
+		// stored under a different path from the one the event carries to the
+		// server. The row and the server then disagree, and the next sweep finds
+		// no row for the real path and inserts a second one.
+		const { repo, pathOf } = store([
+			row("mbx-parent", "Work"),
+			row("mbx-child", "Work/2026"),
+		]);
+		const { service, sent } = queueOver(repo);
+
+		const renamed = await service.renameMailbox(
+			"mbx-parent",
+			"Q1$&Q2",
+			"acc-1",
+		);
+
+		assert.equal(renamed.fullPath, "Q1$&Q2");
+		assert.equal(pathOf("mbx-parent"), "Q1$&Q2");
+		assert.equal(pathOf("mbx-child"), "Q1$&Q2/2026");
+		assert.equal(
+			(JSON.parse(sent[0]) as { newPath: string }).newPath,
+			"Q1$&Q2",
+			"the event and the row name the same folder",
+		);
+	});
+
+	it("moves only what is under the renamed branch", async () => {
+		const { repo, pathOf } = store([
+			row("mbx-parent", "Work"),
+			row("mbx-lookalike", "Workshop"),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.renameMailbox("mbx-parent", "Projects", "acc-1");
+
+		assert.equal(pathOf("mbx-parent"), "Projects");
+		assert.equal(pathOf("mbx-lookalike"), "Workshop");
+	});
+
+	it("returns the folder that was asked for, not whichever row came back first", async () => {
+		const { repo } = store([
+			row("mbx-parent", "Work"),
+			row("mbx-child", "Work/2026"),
+		]);
+		const { service } = queueOver(repo);
+
+		const renamed = await service.renameMailbox(
+			"mbx-parent",
+			"Projects",
+			"acc-1",
+		);
+
+		assert.equal(renamed.mailboxId, "mbx-parent");
+	});
+});

package/src/mailbox-rename-subtree.test.ts

@@ -21,7 +21,10 @@ const row = (
 const store = (rows: MailboxItem[], vanishAfterSweep: string[] = []) => {
 	const byId = new Map(rows.map((r) => [r.mailboxId, { ...r }]));
 
-	const repo: Pick<IMailboxRepository, "update" | "findByPathPrefix"> = {
+	const repo: Pick<
+		IMailboxRepository,
+		"update" | "transition" | "findByPathPrefix"
+	> = {
 		update: async (_accountId, mailboxId, patch) => {
 			const existing = byId.get(mailboxId);
 			if (!existing) {
@@ -33,6 +36,24 @@ const store = (rows: MailboxItem[], vanishAfterSweep: string[] = []) => {
 			byId.set(mailboxId, next);
 			return next;
 		},
+		transition: async (_accountId, mailboxId, intent) => {
+			const existing = byId.get(mailboxId);
+			if (!existing) return null;
+			if (!intent.from.includes(existing.syncStatus)) return null;
+			if (
+				intent.wherePendingPath !== undefined &&
+				(intent.wherePendingPath ?? undefined) !== existing.pendingPath
+			) {
+				return null;
+			}
+			const next = {
+				...existing,
+				...intent.set,
+				syncStatus: intent.to,
+			} as MailboxItem;
+			byId.set(mailboxId, next);
+			return next;
+		},
 		findByPathPrefix: async (_accountId, pathPrefix, delimiter = "/") => {
 			const prefix = `${pathPrefix}${delimiter}`;
 			const found = [...byId.values()].filter((r) =>

package/src/mailbox-sync.test.ts

@@ -216,19 +216,23 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 		shared: [],
 	};
 
-	// The server lists only INBOX: neither user folder is on it yet.
-	const serverConnection = (): IImapConnection =>
+	// The server lists only INBOX unless a test says otherwise: neither user
+	// folder is on it yet.
+	const serverConnection = (
+		folders: Array<{ fullPath: string; attributes?: string[] }> = [
+			{ fullPath: "INBOX" },
+		],
+	): IImapConnection =>
 		({
 			getNamespaces: async () => namespaces,
-			listMailboxes: async () => [
-				{
-					fullPath: "INBOX",
-					name: "INBOX",
+			listMailboxes: async () =>
+				folders.map((folder) => ({
+					fullPath: folder.fullPath,
+					name: folder.fullPath.split("/").pop() ?? folder.fullPath,
 					delimiter: "/",
-					attributes: [],
+					attributes: folder.attributes ?? [],
 					parentPath: null,
-				},
-			],
+				})),
 			getMailboxStatus: async () => ({
 				messages: 0,
 				recent: 0,
@@ -238,6 +242,12 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 				highestModseq: "0",
 				deletedCount: 0,
 			}),
+			openBox: async () => ({
+				uidvalidity: 1,
+				uidnext: 1,
+				messages: { total: 0 },
+			}),
+			closeBox: async () => undefined,
 		}) as unknown as IImapConnection;
 
 	const buildServices = (
@@ -245,9 +255,11 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			mailboxId: string;
 			fullPath: string;
 			syncStatus?: string;
+			pendingPath?: string;
 		}>,
 	) => {
 		const deleted: string[] = [];
+		const created: Array<Record<string, unknown>> = [];
 		const mailboxService = {
 			listByAccount: async () => ({
 				items: existing.map((m) => ({
@@ -261,6 +273,7 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 					highestModseq: "0",
 					specialUse: undefined,
 					syncStatus: m.syncStatus,
+					pendingPath: m.pendingPath,
 				})),
 				continuationToken: undefined,
 			}),
@@ -268,7 +281,10 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			delete: async (_accountId: string, mailboxId: string) => {
 				deleted.push(mailboxId);
 			},
-			create: async () => ({}),
+			create: async (input: Record<string, unknown>) => {
+				created.push(input);
+				return { ...input, mailboxId: `new-${created.length}` };
+			},
 		} as unknown as IMailboxRepository;
 
 		const specialUseService = {
@@ -277,23 +293,126 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			createMany: async () => undefined,
 		} as unknown as IMailboxSpecialUseRepository;
 
-		return { mailboxService, specialUseService, deleted };
+		return { mailboxService, specialUseService, deleted, created };
 	};
 
-	it("keeps a pending folder the server has not listed yet", async () => {
-		// The folder was just created locally; MAILBOX_CREATE has not reached the
-		// server, so the LIST omits it. Deleting the row here races the create and
-		// wedges the account's mailbox-sync FIFO group for a full visibility window.
-		const { mailboxService, specialUseService, deleted } = buildServices([
-			{
-				mailboxId: "inbox",
-				fullPath: "INBOX",
-				syncStatus: MailboxSyncStatus.synced,
-			},
+	for (const syncStatus of [
+		MailboxSyncStatus.pending,
+		MailboxSyncStatus.deleting,
+	]) {
+		it(`keeps a \`${syncStatus}\` folder the server has not listed`, async () => {
+			// `pending`: the folder was just created locally and MAILBOX_CREATE has
+			// not reached the server, so the LIST omits it — deleting the row races
+			// the create and wedges the account's FIFO group for a visibility
+			// window (#290).
+			//
+			// `deleting`: the delete has landed on the server and the worker has not
+			// written back. Hard-deleting the row removes it under the client
+			// holding its id — the "Mailbox not found" of #333 — and removes it
+			// without the folder's mail, which the worker owns (D8).
+			const { mailboxService, specialUseService, deleted } = buildServices([
+				{
+					mailboxId: "inbox",
+					fullPath: "INBOX",
+					syncStatus: MailboxSyncStatus.synced,
+				},
+				{
+					mailboxId: "in-flight",
+					fullPath: "New Folder",
+					syncStatus,
+				},
+			]);
+			const service = new MailboxSyncService(
+				mailboxService,
+				specialUseService,
+				silentLogger,
+			);
+
+			const result = await service.syncMailboxes(
+				{ accountId: "acc-1" },
+				serverConnection(),
+			);
+
+			assert.deepEqual(deleted, []);
+			assert.equal(result.deleted, 0);
+		});
+
+		it(`keeps a \`${syncStatus}\` folder the server lists as \\Noselect`, async () => {
+			// A folder mid-create can transiently LIST as `\Noselect`, and the
+			// non-selectable branch deleted the row before looking at its state.
+			const { mailboxService, specialUseService, deleted } = buildServices([
+				{
+					mailboxId: "in-flight",
+					fullPath: "New Folder",
+					syncStatus,
+				},
+			]);
+			const service = new MailboxSyncService(
+				mailboxService,
+				specialUseService,
+				silentLogger,
+			);
+
+			await service.syncMailboxes(
+				{ accountId: "acc-1" },
+				serverConnection([
+					{ fullPath: "INBOX" },
+					{ fullPath: "New Folder", attributes: ["\\Noselect"] },
+				]),
+			);
+
+			assert.deepEqual(deleted, []);
+		});
+	}
+
+	it("does not insert a second row for a path a recorded rename claims", async () => {
+		// D14. `fullPath` stays the path the server held when the intent was
+		// recorded, so once the server executes RENAME the LIST returns a path no
+		// row is keyed to. Without the pendingPath index the insert branch makes a
+		// second row under a fresh mailboxId and initial-syncs the folder's mail
+		// into it, leaving the original as a permanent phantom.
+		const { mailboxService, specialUseService, deleted, created } =
+			buildServices([
+				{
+					mailboxId: "inbox",
+					fullPath: "INBOX",
+					syncStatus: MailboxSyncStatus.synced,
+				},
+				{
+					mailboxId: "renaming",
+					fullPath: "Archive/2025",
+					syncStatus: MailboxSyncStatus.pending,
+					pendingPath: "Records/2025",
+				},
+			]);
+		const service = new MailboxSyncService(
+			mailboxService,
+			specialUseService,
+			silentLogger,
+		);
+
+		const result = await service.syncMailboxes(
+			{ accountId: "acc-1" },
+			serverConnection([{ fullPath: "INBOX" }, { fullPath: "Records/2025" }]),
+		);
+
+		assert.deepEqual(created, []);
+		assert.equal(result.created, 0);
+		assert.deepEqual(deleted, []);
+	});
+
+	it("lets a failed rename's target be discovered as a folder of its own", async () => {
+		// A failed rename keeps its target so the UI can name what it was aiming
+		// at (T6), and nothing clears it until the user retries or dismisses. If
+		// the guard honoured that claim, one stuck folder would block the sweep
+		// from ever seeing a real folder another client later created at that
+		// path — permanently, and silently.
+		const { mailboxService, specialUseService, created } = buildServices([
 			{
-				mailboxId: "pending-folder",
-				fullPath: "New Folder",
-				syncStatus: MailboxSyncStatus.pending,
+				mailboxId: "stuck",
+				fullPath: "Archive/2025",
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Records/2025",
 			},
 		]);
 		const service = new MailboxSyncService(
@@ -302,13 +421,36 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			silentLogger,
 		);
 
-		const result = await service.syncMailboxes(
+		await service.syncMailboxes(
 			{ accountId: "acc-1" },
-			serverConnection(),
+			serverConnection([
+				{ fullPath: "INBOX" },
+				{ fullPath: "Archive/2025" },
+				{ fullPath: "Records/2025" },
+			]),
 		);
 
-		assert.deepEqual(deleted, []);
-		assert.equal(result.deleted, 0);
+		assert.deepEqual(
+			created.map((input) => input.fullPath),
+			["INBOX", "Records/2025"],
+		);
+	});
+
+	it("writes syncStatus synced on the row it discovers", async () => {
+		const { mailboxService, specialUseService, created } = buildServices([]);
+		const service = new MailboxSyncService(
+			mailboxService,
+			specialUseService,
+			silentLogger,
+		);
+
+		await service.syncMailboxes(
+			{ accountId: "acc-1" },
+			serverConnection([{ fullPath: "INBOX" }]),
+		);
+
+		assert.equal(created.length, 1);
+		assert.equal(created[0].syncStatus, MailboxSyncStatus.synced);
 	});
 
 	it("still deletes a synced folder that has left the server", async () => {

package/src/mailbox-sync.ts

@@ -25,7 +25,10 @@ import {
 import pMap from "p-map";
 import { isNoSelect, parseImapAttributes } from "./attribute-mapper.js";
 import { isCursorRebuildNeeded } from "./mailbox-cursor.js";
-import { isMailboxNotOnServer } from "./mailbox-presence.js";
+import {
+	isFolderMutationInFlight,
+	isMailboxMutationInFlight,
+} from "./mailbox-presence.js";
 import type {
 	FlatMailboxInfo,
 	IImapConnection,
@@ -149,6 +152,28 @@ export class MailboxSyncService {
 		const existingByPath = new Map(
 			existingMailboxes.map((m) => [m.fullPath, m]),
 		);
+		// The paths a rename is on its way to (D14). Under D2 `fullPath` stays the
+		// path the server held when the intent was recorded, so between the server
+		// executing RENAME and the settle, LIST returns a path no row is keyed to
+		// — and the insert branch below has no state guard at all. Without this it
+		// inserts a second row under a fresh mailboxId and initial-syncs the
+		// folder's mail into it, leaving the original as a permanent phantom still
+		// holding that folder's messages, filters and role appointments. No unique
+		// index on (accountId, fullPath) exists to catch it; #386 adds one.
+		//
+		// `pending` only. A failed rename keeps its target so the UI can name what
+		// it was aiming at (T6), and nothing clears it until the user retries or
+		// dismisses — so honouring a `failed` row's claim would let one stuck
+		// folder block the sweep from ever discovering a real folder another
+		// client later creates at that path.
+		const claimedByPendingRename = new Set(
+			existingMailboxes.flatMap((m) =>
+				m.syncStatus === MailboxSyncStatus.pending &&
+				m.pendingPath !== undefined
+					? [m.pendingPath]
+					: [],
+			),
+		);
 
 		// Get namespaces and mailboxes from IMAP
 		const namespaces = await connection.getNamespaces();
@@ -177,7 +202,15 @@ export class MailboxSyncService {
 					seenPaths.add(mailboxInfo.fullPath);
 					// If this mailbox exists in DB, delete it
 					const existing = existingByPath.get(mailboxInfo.fullPath);
-					if (existing) {
+					// A folder mid-create can transiently LIST as `\Noselect`, and
+					// deleting the row then races the create exactly as #290
+					// documented. The state check goes before the delete, through the
+					// same predicate the rest of the sweep asks.
+					if (existing && !isFolderMutationInFlight(existing)) {
+						// The duplicate-special-use branch below clears the special-use
+						// entries too; this one skipped them, orphaning a row per
+						// deleted mailbox.
+						await this.specialUseService.deleteByMailboxId(existing.mailboxId);
 						await this.mailboxService.delete(
 							account.accountId,
 							existing.mailboxId,
@@ -199,7 +232,7 @@ export class MailboxSyncService {
 				if (this.isDuplicateSpecialUse(mailboxInfo, claimedSpecialUse)) {
 					seenPaths.add(mailboxInfo.fullPath);
 					const existing = existingByPath.get(mailboxInfo.fullPath);
-					if (existing) {
+					if (existing && !isFolderMutationInFlight(existing)) {
 						await this.specialUseService.deleteByMailboxId(existing.mailboxId);
 						await this.mailboxService.delete(
 							account.accountId,
@@ -226,10 +259,7 @@ export class MailboxSyncService {
 					// that establishes or removes it writes its own identity back, and
 					// reading its status meanwhile is work whose only possible outcome is
 					// a failure that fails this whole account's fan-out with it.
-					if (
-						existing.syncStatus === MailboxSyncStatus.pending ||
-						existing.syncStatus === MailboxSyncStatus.deleting
-					) {
+					if (isFolderMutationInFlight(existing)) {
 						return;
 					}
 					// The folder set can change under this sweep. A delete that lands
@@ -247,7 +277,7 @@ export class MailboxSyncService {
 					).catch(async (error: unknown) => {
 						// The read only classifies the failure in hand; one that cannot
 						// answer must not replace it.
-						const gone = await isMailboxNotOnServer(
+						const gone = await isMailboxMutationInFlight(
 							this.mailboxService,
 							account.accountId,
 							existing.mailboxId,
@@ -258,7 +288,7 @@ export class MailboxSyncService {
 					if (updated) {
 						result.updated++;
 					}
-				} else {
+				} else if (!claimedByPendingRename.has(mailboxInfo.fullPath)) {
 					await this.createMailbox(
 						account.accountId,
 						mailboxInfo,
@@ -274,15 +304,20 @@ export class MailboxSyncService {
 		// Handle deleted mailboxes (exist in DB but not on server)
 		for (const existing of existingMailboxes) {
 			if (seenPaths.has(existing.fullPath)) continue;
-			// A `pending` row is a folder the user just created (or renamed) whose
-			// MAILBOX_CREATE/RENAME has not yet reached the server, so its absence
-			// from the LIST is expected, not a server-side deletion. Deleting it
-			// races the create: the row vanishes, then MAILBOX_CREATE fails with
-			// NotFoundError trying to mark it synced, and — sharing this account's
-			// mailboxes FIFO group — that un-acked failure stalls every later
-			// mailbox sync for the queue's whole visibility window (#290). Leave
-			// pending rows to the create/rename flow that owns them.
-			if (existing.syncStatus === MailboxSyncStatus.pending) continue;
+			// A row with a mutation in flight is a folder whose absence from the
+			// LIST is expected, not a server-side deletion. Deleting it races the
+			// worker: the row vanishes, then MAILBOX_CREATE fails with NotFoundError
+			// trying to mark it synced, and — sharing this account's mailboxes FIFO
+			// group — that un-acked failure stalls every later mailbox sync for the
+			// queue's whole visibility window (#290).
+			//
+			// `deleting` is here for a second reason. That window is exactly when a
+			// delete has landed on the server and the worker has not written back,
+			// so hard-deleting the row removes it under the client holding its id —
+			// the "Mailbox not found: <old id>" of #333 — and removes it without the
+			// folder's mail, which is the worker's job (D8). Leave both to the flow
+			// that owns them.
+			if (isFolderMutationInFlight(existing)) continue;
 			await this.mailboxService.delete(account.accountId, existing.mailboxId);
 			this.log.info(
 				{
@@ -456,6 +491,10 @@ export class MailboxSyncService {
 			highWaterMarkUid: 0,
 			lastMessageSyncAt: 0,
 			specialUse: parsed.specialUse.length > 0 ? parsed.specialUse : undefined,
+			// A folder the server just told us about is confirmed. The column
+			// defaults to this, so the row is right either way; the field is total
+			// now (D1) and the insert says what it means.
+			syncStatus: MailboxSyncStatus.synced,
 			// parentMailboxId would need to be resolved from parentPath
 		};