@remit/imap-worker 0.0.73 → 0.0.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.73",
+  "version": "0.0.75",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/handlers/mailbox-management.test.ts

@@ -29,10 +29,24 @@ interface Connection {
 		messages: { total: number };
 	}>;
 	closeBox: () => Promise<void>;
-	renameMailbox: (oldPath: string, newPath: string) => Promise<void>;
+	renameMailbox: (
+		oldPath: string,
+		newPath: string,
+	) => Promise<{ path: string; newPath: string }>;
 	deleteMailbox: (path: string) => Promise<void>;
 }
 
+/** The folder rows the handler reads its guards and its settle row-set from. */
+interface Row {
+	mailboxId: string;
+	accountId: string;
+	fullPath: string;
+	hierarchyDelimiter: string;
+	namespacePrefix: string;
+	syncStatus: string;
+	pendingPath?: string;
+}
+
 interface Harness {
 	calls: Call[];
 	account: {
@@ -41,17 +55,14 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	connection: Connection;
+	rows: Map<string, Row>;
 	mailboxUpdateError?: Error;
+	mailboxRowGone?: boolean;
 	disconnectCount: number;
 }
 
 let h: Harness;
 
-const notFoundError = (): Error =>
-	Object.assign(new Error("Mailbox not found: mbx-1"), {
-		name: "NotFoundError",
-	});
-
 const record =
 	(method: string) =>
 	async (...args: unknown[]) => {
@@ -71,14 +82,37 @@ const buildConnection = (): Connection => ({
 		messages: { total: 3 },
 	}),
 	closeBox: record("connection.closeBox"),
-	renameMailbox: record("connection.renameMailbox"),
+	renameMailbox: async (oldPath: string, newPath: string) => {
+		h.calls.push({
+			method: "connection.renameMailbox",
+			args: [oldPath, newPath],
+		});
+		return { path: oldPath, newPath };
+	},
 	deleteMailbox: record("connection.deleteMailbox"),
 });
 
+const row = (over: Partial<Row> & { mailboxId: string }): Row => ({
+	accountId: "acc-1",
+	fullPath: "Archive",
+	hierarchyDelimiter: "/",
+	namespacePrefix: "",
+	syncStatus: "pending",
+	...over,
+});
+
+/** The server holding neither path is what confirms the folder is gone. */
+const listsNeitherPath = (): void => {
+	h.connection.listMailboxes = async () => [{ fullPath: "Iets anders" }];
+};
+
 const fresh = (): Harness => ({
 	calls: [],
 	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
 	connection: buildConnection(),
+	// A create in flight: `pending` with no recorded rename target, which is
+	// what tells it apart from a rename in flight (D3).
+	rows: new Map([["mbx-1", row({ mailboxId: "mbx-1" })]]),
 	disconnectCount: 0,
 });
 
@@ -91,16 +125,80 @@ const deps = (): MailboxManagementDeps =>
 					return h.account;
 				},
 			},
+			accountSetting: {
+				get: async () => undefined,
+				upsert: record("accountSetting.upsert"),
+				delete: record("accountSetting.delete"),
+			},
 			mailbox: {
+				get: async (accountId: string, mailboxId: string) => {
+					h.calls.push({ method: "mailbox.get", args: [accountId, mailboxId] });
+					const found = h.mailboxRowGone
+						? undefined
+						: h.rows.get(mailboxId as string);
+					if (!found) {
+						throw Object.assign(new Error(`Mailbox not found: ${mailboxId}`), {
+							name: "NotFoundError",
+						});
+					}
+					return found;
+				},
 				update: async (...args: unknown[]) => {
 					h.calls.push({ method: "mailbox.update", args });
 					if (h.mailboxUpdateError) throw h.mailboxUpdateError;
 				},
+				// The conditional write the folder state now goes through, with the
+				// predicate honoured: a row that is gone or that somebody else moved
+				// matches nothing, so the loser gets a null rather than a throw and
+				// the handler raises the NotFoundError itself.
+				transition: async (...args: unknown[]) => {
+					h.calls.push({ method: "mailbox.transition", args });
+					if (h.mailboxRowGone) return null;
+					const mailboxId = args[1] as string;
+					const intent = args[2] as {
+						from: readonly string[];
+						wherePendingPath?: string | null;
+						to: string;
+						set?: { fullPath?: string };
+					};
+					const current = h.rows.get(mailboxId);
+					if (!current) return null;
+					if (!intent.from.includes(current.syncStatus)) return null;
+					if (
+						intent.wherePendingPath !== undefined &&
+						(intent.wherePendingPath ?? undefined) !== current.pendingPath
+					) {
+						return null;
+					}
+					const next: Row = {
+						...current,
+						...(intent.set?.fullPath !== undefined
+							? { fullPath: intent.set.fullPath }
+							: {}),
+						syncStatus: intent.to,
+					};
+					if (intent.to !== "pending" && intent.to !== "failed") {
+						next.pendingPath = undefined;
+					}
+					h.rows.set(mailboxId, next);
+					return next;
+				},
 				findByPathPrefix: async (...args: unknown[]) => {
 					h.calls.push({ method: "mailbox.findByPathPrefix", args });
 					return [];
 				},
+				findBySyncStatus: async (accountId: string, syncStatus: string) => {
+					h.calls.push({
+						method: "mailbox.findBySyncStatus",
+						args: [accountId, syncStatus],
+					});
+					if (h.mailboxRowGone) return [];
+					return [...h.rows.values()].filter(
+						(r) => r.syncStatus === syncStatus,
+					);
+				},
 				delete: record("mailbox.delete"),
+				deleteMailboxWithMail: record("mailbox.deleteMailboxWithMail"),
 			},
 			secrets: {},
 		}),
@@ -147,6 +245,17 @@ const called = (method: string): Call[] =>
 const lastUpdate = (): Record<string, unknown> =>
 	(called("mailbox.update").at(-1)?.args[2] ?? {}) as Record<string, unknown>;
 
+const lastSettle = (): {
+	to?: string;
+	set?: Record<string, unknown>;
+	wherePendingPath?: string | null;
+} =>
+	(called("mailbox.transition").at(-1)?.args[2] ?? {}) as {
+		to?: string;
+		set?: Record<string, unknown>;
+		wherePendingPath?: string | null;
+	};
+
 describe("processMailboxManagement — MAILBOX_CREATE", () => {
 	beforeEach(() => {
 		h = fresh();
@@ -160,8 +269,8 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 			uidValidity: 7,
 			uidNext: 42,
 			messageCount: 3,
-			syncStatus: "synced",
 		});
+		assert.equal(lastSettle().to, "synced");
 		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
 	});
 
@@ -183,7 +292,8 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(called("mailbox.update").length, 0);
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("treats an already-existing folder as success rather than a failure", async () => {
@@ -193,7 +303,7 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("marks the mailbox failed and rethrows on any other create error", async () => {
@@ -206,14 +316,14 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 		assert.equal(h.disconnectCount, 1);
 	});
 
 	it("acks terminally without rethrowing when the mailbox row was deleted mid-create (#289)", async () => {
-		// The status write-back throws NotFoundError because the row is gone; the
-		// create is moot and must not poison the account's FIFO.
-		h.mailboxUpdateError = notFoundError();
+		// The settle matches no row because the row is gone; the create is moot
+		// and must not poison the account's FIFO.
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
@@ -242,47 +352,117 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 	});
 });
 
+/**
+ * The rename intent a MAILBOX_RENAME is settled against: the folder keeps the
+ * path the server holds, and carries the target the intent recorded (D2).
+ */
+const recordRenameIntent = (pendingPath = "Archive 2024"): void => {
+	h.rows.set(
+		"mbx-1",
+		row({ mailboxId: "mbx-1", fullPath: "Archive", pendingPath }),
+	);
+};
+
 describe("processMailboxManagement — MAILBOX_RENAME", () => {
 	beforeEach(() => {
 		h = fresh();
+		recordRenameIntent();
 	});
 
-	it("renames on the server and clears the pending oldPath", async () => {
+	it("renames on the server and settles the row onto the confirmed path", async () => {
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
 		assert.deepEqual(called("connection.renameMailbox")[0]?.args, [
 			"Archive",
 			"Archive 2024",
 		]);
-		assert.deepEqual(lastUpdate(), {
-			oldPath: undefined,
-			syncStatus: "synced",
-		});
+		assert.equal(lastSettle().to, "synced");
+		assert.equal(lastSettle().set?.fullPath, "Archive 2024");
+	});
+
+	it("settles onto the path ImapFlow resolved, not the one that was asked for", async () => {
+		h.connection.renameMailbox = async (oldPath: string) => {
+			h.calls.push({ method: "connection.renameMailbox", args: [oldPath] });
+			return { path: oldPath, newPath: "INBOX/Archive 2024" };
+		};
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		assert.equal(lastSettle().set?.fullPath, "INBOX/Archive 2024");
 	});
 
-	it("drops the local row when the source folder is gone on the server", async () => {
+	it("takes the folder's mail with it when the source is gone on the server", async () => {
+		// The folder was deleted under us. Dropping the row on its own is the
+		// orphaning bug: its mail stays keyed to a dead mailboxId, out of every
+		// reader and still in the search index (D8).
+		listsNeitherPath();
 		h.connection.renameMailbox = async () => {
 			throw new Error("Mailbox not found");
 		};
 
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
-		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
-		assert.equal(called("mailbox.update").length, 0);
+		assert.deepEqual(called("mailbox.deleteMailboxWithMail")[0]?.args, [
+			"acc-1",
+			"mbx-1",
+		]);
+		assert.equal(called("mailbox.delete").length, 0);
 	});
 
-	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
+	it("takes every descendant's mail with it too, not just the renamed folder's", async () => {
+		// The whole subtree recorded this rename's intent (D6); dropping the
+		// root alone strands each descendant `pending` at a path the server
+		// never held, with nothing left to revisit it.
+		h.rows.set(
+			"mbx-2",
+			row({
+				mailboxId: "mbx-2",
+				fullPath: "Archive/Sub",
+				pendingPath: "Archive 2024/Sub",
+			}),
+		);
+		listsNeitherPath();
 		h.connection.renameMailbox = async () => {
-			throw new Error("server exploded");
+			throw new Error("Mailbox not found");
+		};
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		const deleted = called("mailbox.deleteMailboxWithMail").map(
+			(c) => c.args[1],
+		);
+		assert.deepEqual(new Set(deleted), new Set(["mbx-1", "mbx-2"]));
+	});
+
+	it("refuses the rename rather than deleting when the source is still on the server", async () => {
+		// The server said NONEXISTENT and its own listing still holds the folder,
+		// so it was talking about something else. Reading that as an upstream
+		// delete would destroy the folder's mail over an answer nothing confirms.
+		h.connection.renameMailbox = async () => {
+			throw new Error("Mailbox not found");
 		};
-		h.mailboxUpdateError = notFoundError();
+
+		await assert.rejects(
+			processMailboxManagement(renameEvent, noopLogger, deps()),
+			/Mailbox not found/,
+		);
+
+		assert.equal(called("mailbox.deleteMailboxWithMail").length, 0);
+		assert.equal(lastSettle().to, "failed");
+	});
+
+	it("acks terminally without connecting when the folder row is gone", async () => {
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
+		assert.equal(called("connection.renameMailbox").length, 0);
 		assert.equal(h.disconnectCount, 1, "the scope is still disconnected");
 	});
 
-	it("rolls the local path back and rethrows on any other rename error", async () => {
+	it("keeps the confirmed path and the target on a refused rename", async () => {
+		// T6. `fullPath` was never written, so there is nothing to restore; the
+		// target is kept so the client can name what the rename was aiming at.
 		h.connection.renameMailbox = async () => {
 			throw new Error("server exploded");
 		};
@@ -292,11 +472,127 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), {
-			fullPath: "Archive",
-			oldPath: undefined,
-			syncStatus: "failed",
-		});
+		assert.equal(lastSettle().to, "failed");
+		assert.equal(
+			lastSettle().set?.fullPath,
+			undefined,
+			"nothing is restored: the row never left the path the server holds",
+		);
+		assert.equal(lastSettle().wherePendingPath, "Archive 2024");
+	});
+
+	it("settles instead of deleting when NONEXISTENT means the rename already landed", async () => {
+		// A redelivery after a lost settle re-issues RENAME from a path that has
+		// moved. Reading that as an upstream delete drops the folder and its mail
+		// while the folder is alive at the target.
+		h.connection.renameMailbox = async () => {
+			throw Object.assign(new Error("Command failed"), {
+				serverResponseCode: "NONEXISTENT",
+				responseText: "Mailbox doesn't exist: Archive",
+			});
+		};
+		h.connection.listMailboxes = async () => [{ fullPath: "Archive 2024" }];
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		assert.equal(called("mailbox.deleteMailboxWithMail").length, 0);
+		assert.equal(lastSettle().to, "synced");
+		assert.equal(lastSettle().set?.fullPath, "Archive 2024");
+	});
+
+	it("rethrows a settle failure without marking the rename refused", async () => {
+		// The server executed the rename. Marking the rows failed would offer a
+		// retry of work already done, on a path the server no longer holds.
+		let settles = 0;
+		const broken = deps();
+		const inner = broken.getClient as unknown as () => Promise<
+			Record<string, unknown>
+		>;
+		broken.getClient = (async () => {
+			const client = await inner();
+			return {
+				...client,
+				mailbox: {
+					...(client.mailbox as Record<string, unknown>),
+					transition: async () => {
+						settles += 1;
+						throw new Error("database is locked");
+					},
+				},
+			};
+		}) as unknown as MailboxManagementDeps["getClient"];
+
+		await assert.rejects(
+			processMailboxManagement(renameEvent, noopLogger, broken),
+			/local settle did not finish/,
+		);
+		assert.equal(settles, 1, "the refusal path never ran a second write");
+	});
+
+	it("issues no RENAME when the row has already settled", async () => {
+		h.rows.set(
+			"mbx-1",
+			row({
+				mailboxId: "mbx-1",
+				fullPath: "Archive 2024",
+				syncStatus: "synced",
+			}),
+		);
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		assert.equal(called("connection.renameMailbox").length, 0);
+		assert.equal(called("mailbox.transition").length, 0);
+	});
+
+	it("issues no RENAME when the row is pending for a different target", async () => {
+		h.rows.set("mbx-1", row({ mailboxId: "mbx-1", pendingPath: "Archief" }));
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		assert.equal(called("connection.renameMailbox").length, 0);
+		assert.equal(called("mailbox.transition").length, 0);
+	});
+});
+
+describe("processMailboxManagement — the seventh state (#363, D3)", () => {
+	beforeEach(() => {
+		h = fresh();
+		recordRenameIntent();
+	});
+
+	/**
+	 * A settled create whose acknowledgement was lost, redelivered against a row
+	 * this rename has since claimed. A `pending`-only guard passes it; CREATE
+	 * collides and ImapFlow reports `{created: false}`, which #346 correctly
+	 * reads as success; the settle then writes `synced` with the rename target
+	 * still on the row — and the rename's own settle no longer matches, so the
+	 * RENAME never runs and nothing is ever marked failed.
+	 */
+	it("lets a redelivered create settle nothing on a row a rename has claimed", async () => {
+		await processMailboxManagement(createEvent, noopLogger, deps());
+
+		const settle = called("mailbox.transition").at(-1)?.args[2] as {
+			wherePendingPath?: string | null;
+			to?: string;
+		};
+		assert.equal(
+			settle?.wherePendingPath,
+			null,
+			"the create settle requires the row to carry no rename target",
+		);
+		assert.equal(h.rows.get("mbx-1")?.pendingPath, "Archive 2024");
+	});
+
+	it("then settles the rename normally", async () => {
+		await processMailboxManagement(createEvent, noopLogger, deps());
+		h.calls = [];
+
+		await processMailboxManagement(renameEvent, noopLogger, deps());
+
+		assert.equal(called("connection.renameMailbox").length, 1);
+		assert.equal(lastSettle().to, "synced");
+		assert.equal(lastSettle().set?.fullPath, "Archive 2024");
 	});
 });
 
@@ -329,7 +625,7 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 		assert.equal(called("mailbox.delete").length, 0);
 	});
 
@@ -343,14 +639,14 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
 	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
 		h.connection.deleteMailbox = async () => {
 			throw new Error("server exploded");
 		};
-		h.mailboxUpdateError = notFoundError();
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
@@ -381,7 +677,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(deleteEvent, noopLogger, deps()),
 		);
 		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
-		assert.equal(called("mailbox.update").length, 0);
+		assert.equal(called("mailbox.transition").length, 0);
 	});
 
 	it("still marks failed and rethrows when the server fails for any other reason", async () => {
@@ -396,7 +692,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(deleteEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
 	/**
@@ -416,7 +712,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 		await assert.doesNotReject(
 			processMailboxManagement(createEvent, noopLogger, deps()),
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("still marks failed and rethrows when a CREATE fails for any other reason", async () => {
@@ -431,10 +727,12 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(createEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
-	it("reads NONEXISTENT on a RENAME as the source folder being gone", async () => {
+	it("reads NONEXISTENT on a RENAME as the source folder being gone, mail and all", async () => {
+		recordRenameIntent();
+		listsNeitherPath();
 		h.connection.renameMailbox = async () => {
 			throw Object.assign(new Error("Command failed"), {
 				serverResponseCode: "NONEXISTENT",
@@ -445,10 +743,14 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 		await assert.doesNotReject(
 			processMailboxManagement(renameEvent, noopLogger, deps()),
 		);
-		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
+		assert.deepEqual(called("mailbox.deleteMailboxWithMail")[0]?.args, [
+			"acc-1",
+			"mbx-1",
+		]);
 	});
 
-	it("still rolls back and rethrows when a RENAME fails for any other reason", async () => {
+	it("still refuses the intent and rethrows when a RENAME fails for any other reason", async () => {
+		recordRenameIntent();
 		h.connection.renameMailbox = async () => {
 			throw Object.assign(new Error("Command failed"), {
 				serverResponseCode: "SERVERBUG",
@@ -460,6 +762,6 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(renameEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.equal(lastUpdate()?.syncStatus, "failed");
+		assert.equal(lastSettle().to, "failed");
 	});
 });

package/src/handlers/mailbox-management.ts

@@ -1,8 +1,17 @@
 import { getClient } from "@remit/backend/client";
-import { isNotFoundError } from "@remit/data-ports/errors";
+import { refreshFolderAppointmentLabels } from "@remit/backend/folder-role-labels";
+import type { IMailboxRepository } from "@remit/data-ports";
+import { isNotFoundError, NotFoundError } from "@remit/data-ports/errors";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
-import { MailboxManagementService } from "@remit/mailbox-service";
+import {
+	EVERY_MAILBOX_STATE,
+	FolderGoneUpstreamError,
+	FolderRenameSettleError,
+	isMailboxAbsentUpstream,
+	isMailboxPresentUpstream,
+	MailboxManagementService,
+} from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type {
@@ -28,42 +37,50 @@ const defaultDeps: MailboxManagementDeps = {
 	createConnectionScope: createConnectionScopeWithCredentials,
 };
 
-const stringField = (value: unknown, key: string): string => {
-	if (!(value instanceof Object)) return "";
-	const field = Reflect.get(value, key);
-	return typeof field === "string" ? field : "";
-};
-
 /**
- * Read a tagged-NO outcome out of an IMAP failure.
+ * Write the outcome of a folder operation back, as the conditional write that
+ * is the only way to write a folder's state
+ * (docs/architecture/folder-rename-and-delete.md D3).
  *
- * The two outcomes below are each a folder operation finding the server already
- * in the state it was asked for — the operation having happened, not failing.
- * Reading them as failures marks the row `failed` and rethrows, and since folder
- * management shares the account's per-account FIFO group with mailbox sync, that
- * un-acked rethrow holds back every later sync for the account.
- *
- * Both places the server can say so are read. `message` carries it when the
- * client raises the error itself; RFC 5530's response code and its text carry it
- * when the server does. ImapFlow surfaces a tagged NO as a bare "Command failed"
- * with the code on the error, which is why matching the message alone never
- * caught a real Dovecot answer.
+ * The from-set is every state because that is what this write-back decides
+ * against today — it is the unconditional write it replaces, moved onto the
+ * door. #362 narrows the delete's to the state its intent recorded. A null
+ * means the row is gone, which is the NotFoundError the whole-chain guards
+ * below classify as the user having deleted the folder mid-sync.
  */
-const saidByServer = (error: Error): string =>
-	`${error.message} ${stringField(error, "responseText")}`;
-
-/** The folder is not on the server: a delete has nothing left to do. */
-const isMailboxAbsentUpstream = (error: unknown): boolean => {
-	if (!(error instanceof Error)) return false;
-	if (stringField(error, "serverResponseCode") === "NONEXISTENT") return true;
-	return /not found|does ?n.?t exist/i.test(saidByServer(error));
+const recordOutcome = async (
+	mailboxService: Pick<IMailboxRepository, "transition">,
+	accountId: string,
+	mailboxId: string,
+	to: (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus],
+): Promise<void> => {
+	const written = await mailboxService.transition(accountId, mailboxId, {
+		from: EVERY_MAILBOX_STATE,
+		to,
+		set: {},
+	});
+	if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 };
 
-/** The folder is already on the server: a create has nothing left to do. */
-const isMailboxPresentUpstream = (error: unknown): boolean => {
-	if (!(error instanceof Error)) return false;
-	if (stringField(error, "serverResponseCode") === "ALREADYEXISTS") return true;
-	return /already exists/i.test(saidByServer(error));
+/**
+ * The outcome of a create, written against the state a create in flight is:
+ * `pending` with no recorded rename target (D3, D10). Without the absence
+ * check, a create redelivered after a lost acknowledgement settles a row a
+ * rename has since claimed and kills the rename silently.
+ */
+const recordCreateOutcome = async (
+	mailboxService: Pick<IMailboxRepository, "transition">,
+	accountId: string,
+	mailboxId: string,
+	to: (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus],
+): Promise<void> => {
+	const written = await mailboxService.transition(accountId, mailboxId, {
+		from: [MailboxSyncStatus.pending],
+		wherePendingPath: null,
+		to,
+		set: {},
+	});
+	if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 };
 
 /**
@@ -76,12 +93,13 @@ const isMailboxPresentUpstream = (error: unknown): boolean => {
  * never an unrelated missing entity that should have been retried.
  *
  * `syncCreate` and `syncDelete` hold to that by touching nothing but the target
- * row. `syncRename` also writes the renamed subtree's descendant rows, and keeps
- * the invariant by absorbing their NotFoundErrors itself: a descendant deleted
- * mid-settle never reaches these catches. Any sync method that reads or writes a
- * second entity owes the same, or these catches must be narrowed (match the
- * mailboxId / re-check existence) before a NotFoundError from elsewhere is
- * silently acked.
+ * row. `syncRename` also writes every other row that recorded the same intent,
+ * and keeps the invariant by treating a lost predicate as an outcome rather than
+ * an error: a descendant deleted mid-settle is skipped, never raised. The
+ * appointment-label refresh writes `account_setting` rows, whose reads answer
+ * absent rather than throwing. Any sync method that reads or writes a second
+ * entity owes the same, or these catches must be narrowed (match the mailboxId /
+ * re-check existence) before a NotFoundError from elsewhere is silently acked.
  */
 
 /**
@@ -158,13 +176,19 @@ const handleCreate = async (
 								{ accountId, mailboxId, path },
 								"Mailbox already exists, marking as synced",
 							);
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.synced,
-							});
+							await recordCreateOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.synced,
+							);
 						} else {
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.failed,
-							});
+							await recordCreateOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.failed,
+							);
 							throw error;
 						}
 					})
@@ -206,6 +230,7 @@ const handleRename = async (
 
 	const {
 		account: accountService,
+		accountSetting: accountSettingService,
 		mailbox: mailboxService,
 		secrets,
 	} = await getClient();
@@ -246,36 +271,91 @@ const handleRename = async (
 						newPath,
 						scope.getConnection,
 					)
-					.then((result) => {
-						if (result.success) {
-							log.info(
-								{ accountId, mailboxId, oldPath, newPath },
-								"Mailbox renamed on IMAP",
-							);
-						} else {
+					.then(async (result) => {
+						if (!result.success) {
 							log.error(
 								{ accountId, mailboxId, oldPath, newPath, error: result.error },
 								"Failed to rename mailbox on IMAP",
 							);
+							return;
 						}
+						log.info(
+							{ accountId, mailboxId, oldPath, newPath },
+							"Mailbox renamed on IMAP",
+						);
+						if (!result.renamed) return;
+						// The path recorded beside each role appointment (#887) moves with
+						// the settle, because under D2 that is the first moment the new
+						// path is one the server holds.
+						//
+						// A label is display-only and this runs after the server rename
+						// landed, so letting it fail would take the job down the failure
+						// path and mark a completed rename refused. Logged and dropped;
+						// the next appointment write records the folder's current path
+						// anyway.
+						await refreshFolderAppointmentLabels(
+							accountSettingService,
+							account.accountConfigId,
+							accountId,
+							{
+								mailboxId,
+								oldPath: result.renamed.oldPath,
+								newPath: result.renamed.newPath,
+							},
+							result.renamed.delimiter,
+						).catch((error: unknown) => {
+							log.error(
+								{ accountId, mailboxId, oldPath, newPath, error },
+								"Renamed folder settled, but its role-appointment labels did not move",
+							);
+						});
 					})
 					.catch(async (error) => {
-						// If source not found, delete local mailbox
-						if (isMailboxAbsentUpstream(error)) {
-							log.info(
-								{ accountId, mailboxId, oldPath },
-								"Source mailbox not found, deleting local",
+						// The server executed the rename and only the local settle did not
+						// finish. That is not a refused rename: marking the rows `failed`
+						// would offer a retry of work already done and leave `fullPath`
+						// naming a path the server no longer holds. Rethrow, so the
+						// redelivery finishes the settle against an intent still standing.
+						if (error instanceof FolderRenameSettleError) {
+							log.error(
+								{ accountId, mailboxId, oldPath, newPath, error },
+								"Rename landed on the server; the settle will finish on redelivery",
 							);
-							await mailboxService.delete(accountId, mailboxId);
-						} else {
-							// Rollback local rename by restoring old path
-							await mailboxService.update(accountId, mailboxId, {
-								fullPath: oldPath,
-								oldPath: undefined,
-								syncStatus: MailboxSyncStatus.failed,
-							});
 							throw error;
 						}
+						// The folder the rename was to move is confirmed gone: the
+						// server refused the RENAME as non-existent and its own listing
+						// held neither path. The rename decides that, once, where the
+						// evidence is — re-reading the response code here would make
+						// every `NONEXISTENT` this code cannot classify destroy the
+						// folder's mail. Removing the root row alone is the orphaning
+						// bug: every descendant recorded the same intent (D6) and would
+						// be left `pending` at a path that does not exist, with its mail
+						// stranded out of every reader and still in the search index
+						// (D8).
+						if (error instanceof FolderGoneUpstreamError) {
+							log.info(
+								{ accountId, mailboxId, oldPath, intent: "rename" },
+								"Source mailbox not found, deleting local folder and its mail",
+							);
+							await managementService.abandonRenameSubtree(
+								accountId,
+								mailboxId,
+								oldPath,
+								newPath,
+							);
+							return;
+						}
+						// T6. Nothing is restored — `fullPath` was never written, and
+						// each intent-carrying row keeps its target so the client can
+						// name what the rename was aiming at and offer a retry.
+						await managementService.failRename(
+							accountId,
+							mailboxId,
+							oldPath,
+							newPath,
+						);
+						throw error;
 					})
 					.finally(() => scope.disconnect());
 			} catch (error) {
@@ -370,9 +450,12 @@ const handleDelete = async (
 							error.message.includes("Cannot delete INBOX")
 						) {
 							// Restore the mailbox
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.synced,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.synced,
+							);
 							log.error(
 								{ accountId, mailboxId, path },
 								"Cannot delete INBOX, restoring mailbox",
@@ -380,9 +463,12 @@ const handleDelete = async (
 							// Don't rethrow - this is an expected error
 						} else {
 							// Restore the mailbox on other errors
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.failed,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.failed,
+							);
 							throw error;
 						}
 					})

package/src/handlers/sync-message-body.ts

@@ -6,7 +6,7 @@ import {
 	BodySyncService,
 	guardConnectionCursor,
 	isCursorRebuildNeeded,
-	isFolderOffServer,
+	isFolderMutationInFlight,
 	MailboxCursorPausedError,
 	PlacementMoveService,
 	QuarantineService,
@@ -179,10 +179,10 @@ export const syncMessageBody = async (
 			// A folder still `pending` is terminal for the same reason: the batch
 			// was cut before the folder reached the server, so there is nothing
 			// there to fetch from and no retry that changes it.
-			if (!mailbox || isFolderOffServer(mailbox)) {
+			if (!mailbox || isFolderMutationInFlight(mailbox)) {
 				log.warn(
 					{ accountId, mailboxId, eventId: event.eventId },
-					"Skipping SYNC_MESSAGE_BODY: the server does not hold this folder",
+					"Skipping SYNC_MESSAGE_BODY: a folder mutation is in flight",
 				);
 				return;
 			}

package/src/handlers/sync-messages.test.ts

@@ -320,7 +320,7 @@ describe("syncMessages — terminal handling of events for a deleted mailbox (is
 			"a deleted mailbox must short-circuit before the OAuth/connection lifecycle",
 		);
 		const skip = warns.find((w) =>
-			w.msg.includes("the server does not hold this folder"),
+			w.msg.includes("a folder mutation is in flight"),
 		);
 		assert.ok(skip, "expected a WARN naming the skipped deleted mailbox");
 		assert.equal(skip.fields.accountId, "acc-1");
@@ -371,9 +371,7 @@ describe("syncMessages — terminal handling of events for a deleted mailbox (is
 
 			assert.equal(harness.lifecycleCalls, 0);
 			assert.ok(
-				warns.find((w) =>
-					w.msg.includes("the server does not hold this folder"),
-				),
+				warns.find((w) => w.msg.includes("a folder mutation is in flight")),
 			);
 		});
 	}

package/src/handlers/sync-messages.ts

@@ -19,7 +19,7 @@ import { type Logger, recordImapFailure } from "@remit/logger-lambda";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import {
 	createManagedConnectionFactory,
-	isMailboxNotOnServer,
+	isMailboxMutationInFlight,
 	MailConnectionError,
 	type MailCredentials,
 	MessageSyncService,
@@ -133,17 +133,23 @@ export const syncMessages = async (
 		return;
 	}
 
-	// A SYNC_MESSAGES trigger can address a folder the server does not hold: the
-	// fan-out enqueues one for a folder whose own create has not landed yet, and
-	// a `hasMore` next-batch or a periodic tick outlives a folder the user
-	// deleted. Such an event can never succeed on retry, and the account's
-	// per-group FIFO ordering lets that one poison message stall the
-	// whole account's message pipeline for the full visibility window (issue
-	// #287, #339). A folder the server does not hold — not yet created, or being
-	// deleted — is an expected terminal outcome, not an infra failure: ack the
-	// event with a WARN.
+	// A SYNC_MESSAGES trigger can address a folder a mutation still owns: the
+	// fan-out enqueues one for a folder whose own create has not landed yet, a
+	// `hasMore` next-batch or a periodic tick outlives a folder the user
+	// deleted, and a rename in flight leaves the folder on the server but under
+	// the worker that is moving it. Such an event can never succeed on retry,
+	// and the account's per-group FIFO ordering lets that one poison message
+	// stall the whole account's message pipeline for the full visibility window
+	// (issue #287, #339). A folder with a create, rename or delete outstanding
+	// is an expected terminal outcome, not an infra failure: ack the event with
+	// a WARN. The rename case is conservative rather than necessary — syncing it
+	// would be safe — and keeps the guard a single expression (D12).
 	if (
-		await isMailboxNotOnServer(mailboxService, event.accountId, event.mailboxId)
+		await isMailboxMutationInFlight(
+			mailboxService,
+			event.accountId,
+			event.mailboxId,
+		)
 	) {
 		log.warn(
 			{
@@ -152,7 +158,7 @@ export const syncMessages = async (
 				eventId: event.eventId,
 				event: event.type,
 			},
-			"Skipping SYNC_MESSAGES: the server does not hold this folder",
+			"Skipping SYNC_MESSAGES: a folder mutation is in flight",
 		);
 		return;
 	}
@@ -214,7 +220,7 @@ export const syncMessages = async (
 						// never become the failure that is reported. A read that cannot answer
 						// leaves the round on the loud path below, with the real error and the
 						// state write that goes with it intact.
-						const folderIsGone = await isMailboxNotOnServer(
+						const folderIsGone = await isMailboxMutationInFlight(
 							mailboxService,
 							event.accountId,
 							event.mailboxId,