@remit/imap-worker 0.0.74 → 0.0.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.74",
+  "version": "0.0.76",
   "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,6 +55,7 @@ interface Harness {
 		deletedAt?: number;
 	} | null;
 	connection: Connection;
+	rows: Map<string, Row>;
 	mailboxUpdateError?: Error;
 	mailboxRowGone?: boolean;
 	disconnectCount: number;
@@ -48,11 +63,6 @@ interface Harness {
 
 let h: Harness;
 
-const notFoundError = (): Error =>
-	Object.assign(new Error("Mailbox not found: mbx-1"), {
-		name: "NotFoundError",
-	});
-
 const record =
 	(method: string) =>
 	async (...args: unknown[]) => {
@@ -72,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,
 });
 
@@ -92,23 +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: a row
-				// that is gone matches nothing, so the loser gets a null rather
-				// than a throw and the handler raises the NotFoundError itself.
+				// 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 });
-					return h.mailboxRowGone ? null : {};
+					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: {},
 		}),
@@ -155,10 +245,15 @@ 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> } =>
+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", () => {
@@ -257,12 +352,24 @@ 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 settles the row", 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, [
@@ -270,31 +377,92 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 			"Archive 2024",
 		]);
 		assert.equal(lastSettle().to, "synced");
+		assert.equal(lastSettle().set?.fullPath, "Archive 2024");
 	});
 
-	it("drops the local row when the source folder is gone on the server", async () => {
+	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("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.transition").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");
 		};
+
+		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");
 		};
@@ -305,41 +473,180 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 		);
 
 		assert.equal(lastSettle().to, "failed");
-		assert.equal(lastSettle().set?.fullPath, "Archive");
+		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");
+	});
+});
+
+/** The delete intent a MAILBOX_DELETE is settled against. */
+const recordDeleteIntent = (): void => {
+	h.rows.set(
+		"mbx-1",
+		row({ mailboxId: "mbx-1", fullPath: "Archive", syncStatus: "deleting" }),
+	);
+};
+
 describe("processMailboxManagement — MAILBOX_DELETE", () => {
 	beforeEach(() => {
 		h = fresh();
+		recordDeleteIntent();
 	});
 
-	it("deletes on the server and drops the local row", async () => {
+	it("deletes on the server and takes the folder's mail with it", async () => {
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
 		assert.equal(called("connection.deleteMailbox")[0]?.args[0], "Archive");
-		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
+		assert.deepEqual(called("mailbox.deleteMailboxWithMail")[0]?.args, [
+			"acc-1",
+			"mbx-1",
+		]);
+		assert.equal(
+			called("mailbox.delete").length,
+			0,
+			"the bare row delete is what orphaned the folder's mail",
+		);
 	});
 
-	it("drops the local row when the folder is already gone on the server", async () => {
+	it("removes the folder's mail when the folder is already gone on the server", async () => {
 		h.connection.deleteMailbox = async () => {
 			throw new Error("Mailbox not found");
 		};
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
-		assert.equal(called("mailbox.delete").length, 1);
+		assert.equal(called("mailbox.deleteMailboxWithMail").length, 1);
 	});
 
-	it("restores the mailbox and swallows the error when the server refuses to delete INBOX", async () => {
+	it("marks the delete failed rather than synced when the server refuses INBOX", async () => {
+		// The API refuses a delete of INBOX, so this backstop is unreachable from
+		// it. Reached another way, the honest outcome is `failed`: the folder was
+		// never deleted, and nothing was undone.
 		h.connection.deleteMailbox = async () => {
 			throw new Error("Cannot delete INBOX");
 		};
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
-		assert.equal(lastSettle().to, "synced");
-		assert.equal(called("mailbox.delete").length, 0);
+		assert.equal(lastSettle().to, "failed");
+		assert.equal(called("mailbox.deleteMailboxWithMail").length, 0);
 	});
 
 	it("marks the mailbox failed and rethrows on any other delete error", async () => {
@@ -355,14 +662,21 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 		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");
-		};
+	it("issues no DELETE when the row is not deleting", async () => {
+		h.rows.set("mbx-1", row({ mailboxId: "mbx-1", syncStatus: "synced" }));
+
+		await processMailboxManagement(deleteEvent, noopLogger, deps());
+
+		assert.equal(called("connection.deleteMailbox").length, 0);
+		assert.equal(called("mailbox.deleteMailboxWithMail").length, 0);
+	});
+
+	it("acks terminally without connecting when the folder row is gone", async () => {
 		h.mailboxRowGone = true;
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
+		assert.equal(called("connection.deleteMailbox").length, 0);
 		assert.equal(h.disconnectCount, 1, "the scope is still disconnected");
 	});
 });
@@ -378,7 +692,8 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 	 * only the message treated an already-absent folder as a failure: the row was
 	 * marked failed and the event left poisoning the account's queue.
 	 */
-	it("treats it as the delete already having happened, and drops the local row", async () => {
+	it("treats it as the delete already having happened, mail and all", async () => {
+		recordDeleteIntent();
 		h.connection.deleteMailbox = async () => {
 			throw Object.assign(new Error("Command failed"), {
 				serverResponseCode: "NONEXISTENT",
@@ -389,11 +704,15 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 		await assert.doesNotReject(
 			processMailboxManagement(deleteEvent, noopLogger, deps()),
 		);
-		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
+		assert.deepEqual(called("mailbox.deleteMailboxWithMail")[0]?.args, [
+			"acc-1",
+			"mbx-1",
+		]);
 		assert.equal(called("mailbox.transition").length, 0);
 	});
 
 	it("still marks failed and rethrows when the server fails for any other reason", async () => {
+		recordDeleteIntent();
 		h.connection.deleteMailbox = async () => {
 			throw Object.assign(new Error("Command failed"), {
 				serverResponseCode: "SERVERBUG",
@@ -443,7 +762,9 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 		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",
@@ -454,10 +775,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",

package/src/handlers/mailbox-management.ts

@@ -1,10 +1,14 @@
 import { getClient } from "@remit/backend/client";
+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 {
-	EVERY_MAILBOX_STATE,
+	FolderGoneUpstreamError,
+	FolderRenameSettleError,
+	isMailboxAbsentUpstream,
+	isMailboxPresentUpstream,
 	MailboxManagementService,
 } from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
@@ -32,74 +36,27 @@ 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.
- *
- * 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 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 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));
-};
-
-/**
- * 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 from-set is every state because that is what these write-backs decide
- * against today — they are the unconditional writes they replace, moved onto
- * the door. #363 narrows each to the state its intent recorded, and gives a
- * lost predicate its `superseded` outcome. 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 recordOutcome = async (
+const recordCreateOutcome = async (
 	mailboxService: Pick<IMailboxRepository, "transition">,
 	accountId: string,
 	mailboxId: string,
 	to: (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus],
-	confirmedPath?: string,
 ): Promise<void> => {
 	const written = await mailboxService.transition(accountId, mailboxId, {
-		from: EVERY_MAILBOX_STATE,
+		from: [MailboxSyncStatus.pending],
+		wherePendingPath: null,
 		to,
-		// `failed` keeps whatever rename target the row carries, so the UI can
-		// name what the rename was aiming at (T6); every other outcome drops it,
-		// which the transition does on its own.
-		set: confirmedPath !== undefined ? { fullPath: confirmedPath } : {},
+		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));
-};
-
 /**
  * Pinned invariant for the whole-chain terminal guards below.
  *
@@ -110,12 +67,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.
  */
 
 /**
@@ -192,14 +150,14 @@ const handleCreate = async (
 								{ accountId, mailboxId, path },
 								"Mailbox already exists, marking as synced",
 							);
-							await recordOutcome(
+							await recordCreateOutcome(
 								mailboxService,
 								accountId,
 								mailboxId,
 								MailboxSyncStatus.synced,
 							);
 						} else {
-							await recordOutcome(
+							await recordCreateOutcome(
 								mailboxService,
 								accountId,
 								mailboxId,
@@ -246,6 +204,7 @@ const handleRename = async (
 
 	const {
 		account: accountService,
+		accountSetting: accountSettingService,
 		mailbox: mailboxService,
 		secrets,
 	} = await getClient();
@@ -286,38 +245,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)) {
+						// 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",
+							);
+							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 },
-								"Source mailbox not found, deleting local",
+								{ accountId, mailboxId, oldPath, intent: "rename" },
+								"Source mailbox not found, deleting local folder and its mail",
 							);
-							await mailboxService.delete(accountId, mailboxId);
-						} else {
-							// Rollback local rename by restoring old path
-							await recordOutcome(
-								mailboxService,
+							await managementService.abandonRenameSubtree(
 								accountId,
 								mailboxId,
-								MailboxSyncStatus.failed,
 								oldPath,
+								newPath,
 							);
-							throw error;
+							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) {
@@ -400,37 +412,32 @@ const handleDelete = async (
 						}
 					})
 					.catch(async (error) => {
-						// If mailbox not found, it's already deleted (idempotent)
+						// The folder is already gone from the server, so the delete has
+						// happened. Its mail still goes with it (D8), which is the whole
+						// point of the settle.
 						if (isMailboxAbsentUpstream(error)) {
 							log.info(
-								{ accountId, mailboxId, path },
-								"Mailbox not found on IMAP, deleting local",
+								{ accountId, mailboxId, path, intent: "delete" },
+								"Mailbox not found on IMAP, removing the local folder and its mail",
 							);
-							await mailboxService.delete(accountId, mailboxId);
-						} else if (
-							error instanceof Error &&
-							error.message.includes("Cannot delete INBOX")
-						) {
-							// Restore the mailbox
-							await recordOutcome(
-								mailboxService,
-								accountId,
-								mailboxId,
-								MailboxSyncStatus.synced,
-							);
-							log.error(
-								{ accountId, mailboxId, path },
-								"Cannot delete INBOX, restoring mailbox",
-							);
-							// Don't rethrow - this is an expected error
+							await managementService.settleDelete(accountId, mailboxId);
 						} else {
-							// Restore the mailbox on other errors
-							await recordOutcome(
-								mailboxService,
-								accountId,
-								mailboxId,
-								MailboxSyncStatus.failed,
-							);
+							// T9, INBOX included. The API refuses a delete of INBOX, so the
+							// worker's backstop is unreachable from it; if something else
+							// reaches it, the honest outcome is `failed`, not `synced` —
+							// the folder was never deleted and nothing was undone.
+							await managementService.failDelete(accountId, mailboxId);
+							if (
+								error instanceof Error &&
+								error.message.includes("Cannot delete INBOX")
+							) {
+								log.error(
+									{ accountId, mailboxId, path, intent: "delete" },
+									"Cannot delete INBOX",
+								);
+								// Don't rethrow — no retry can make this succeed.
+								return;
+							}
 							throw error;
 						}
 					})