@remit/imap-worker 0.0.51 → 0.0.53

package/package.json

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

package/src/events.ts

@@ -1,3 +1,5 @@
+import type { MUTATION_EVENT_SCHEMA_VERSION } from "@remit/data-ports/mutation-events";
+
 export interface BaseEvent {
 	accountId: string;
 	eventId: string; // Idempotency key
@@ -88,6 +90,7 @@ export type MailboxManagementEvent =
  */
 export interface MessageDeleteEvent extends BaseEvent {
 	type: "MESSAGE_DELETE";
+	schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
 	messageId: string;
 	mailboxId: string;
 	mailboxPath: string;
@@ -115,8 +118,16 @@ export interface MessageMoveEvent extends BaseEvent {
  */
 export interface EmptyTrashEvent extends BaseEvent {
 	type: "EMPTY_TRASH";
+	schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
 	trashMailboxId: string;
 	trashMailboxPath: string;
+	/**
+	 * The Trash folder's UIDVALIDITY at the moment the user consented. The
+	 * handler compares it against what the SELECT serves: a path reused by a
+	 * different folder (rename plus recreate) answers with a different value,
+	 * and this is the only comparison the mutating connection cannot race.
+	 */
+	trashUidValidity: number;
 }
 
 /**

package/src/handlers/empty-trash.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { beforeEach, describe, it } from "node:test";
+import type { RoleResolution } from "@remit/data-ports/folder-role";
 import type { Logger } from "@remit/logger-lambda";
 import type { EmptyTrashEvent } from "../events.js";
 import { type EmptyTrashDeps, handleEmptyTrash } from "./empty-trash.js";
@@ -28,6 +29,14 @@ interface Connection {
 	deleteMessages: (uids: number[]) => Promise<void>;
 }
 
+interface LocalMessage {
+	messageId: string;
+	uid: number;
+	status: string;
+}
+
+type TrashMailbox = { mailboxId: string; fullPath: string };
+
 interface Harness {
 	calls: Call[];
 	account: {
@@ -37,9 +46,11 @@ interface Harness {
 	} | null;
 	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
 	mailboxError?: Error;
+	trashResolution: RoleResolution<TrashMailbox>;
 	connection: Connection;
-	localMessages: { messageId: string }[];
-	threadMessage: { accountConfigId: string; threadMessageId: string } | null;
+	localMessages: LocalMessage[];
+	threadMessage: boolean;
+	messagesWithoutListingRow: string[];
 	getConnectionCount: number;
 	disconnectCount: number;
 }
@@ -60,17 +71,45 @@ const buildConnection = (): Connection => ({
 	) as Connection["deleteMessages"],
 });
 
+const deleting = (messageId: string, uid: number): LocalMessage => ({
+	messageId,
+	uid,
+	status: "deleting",
+});
+
 const fresh = (): Harness => ({
 	calls: [],
 	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
 	mailbox: { mailboxId: "trash-mbx", uidValidity: 1, cursorState: undefined },
+	trashResolution: {
+		kind: "flagged",
+		mailbox: { mailboxId: "trash-mbx", fullPath: "Trash" },
+	},
 	connection: buildConnection(),
-	localMessages: [{ messageId: "msg-1" }, { messageId: "msg-2" }],
-	threadMessage: { accountConfigId: "cfg-1", threadMessageId: "tm-1" },
+	localMessages: [deleting("msg-1", 10), deleting("msg-2", 11)],
+	threadMessage: true,
+	messagesWithoutListingRow: [],
 	getConnectionCount: 0,
 	disconnectCount: 0,
 });
 
+// Empty Trash only flips `isDeleted` on the listing row, so its presence is how
+// the revert tells its own marks from a permanent delete's (which removes them
+// up front).
+const listingRow = (messageId: string) =>
+	h.messagesWithoutListingRow.includes(messageId) || !h.threadMessage
+		? null
+		: {
+				accountConfigId: "cfg-1",
+				threadMessageId: `tm-${messageId}`,
+				sentDate: 1_700_000_000_000,
+				mailboxId: "trash-mbx",
+				isRead: false,
+				isDeleted: true,
+				hasStars: false,
+				hasAttachment: false,
+			};
+
 const deps = (): EmptyTrashDeps =>
 	({
 		getClient: async () => ({
@@ -83,10 +122,17 @@ const deps = (): EmptyTrashDeps =>
 			message: {
 				listAllByMailbox: async () => h.localMessages,
 				delete: record("message.delete"),
+				update: record("message.update"),
 			},
 			threadMessage: {
-				findByMessageId: async () => h.threadMessage,
+				findByMessageId: async (_cfg: string, messageId: string) =>
+					listingRow(messageId),
+				findAllByMessageId: async (_cfg: string, messageId: string) => {
+					const row = listingRow(messageId);
+					return row ? [row] : [];
+				},
 				delete: record("threadMessage.delete"),
+				update: record("threadMessage.update"),
 			},
 			mailbox: {
 				get: async () => {
@@ -95,6 +141,9 @@ const deps = (): EmptyTrashDeps =>
 				},
 				update: record("mailbox.update"),
 			},
+			mailboxSpecialUse: {
+				resolveTrashRole: async () => h.trashResolution,
+			},
 			secrets: {},
 		}),
 		buildLifecycleDeps: () => ({}),
@@ -117,14 +166,31 @@ const deps = (): EmptyTrashDeps =>
 
 const event: EmptyTrashEvent = {
 	type: "EMPTY_TRASH",
+	schemaVersion: 2,
 	accountId: "acc-1",
 	trashMailboxId: "trash-mbx",
 	trashMailboxPath: "Trash",
+	trashUidValidity: 1,
 } as EmptyTrashEvent;
 
 const called = (method: string): Call[] =>
 	h.calls.filter((c) => c.method === method);
 
+const revertedMessageIds = (): string[] =>
+	called("message.update")
+		.filter(
+			(c) =>
+				(c.args[1] as { status?: string; syncStatus?: string }).status ===
+					"active" &&
+				(c.args[1] as { syncStatus?: string }).syncStatus === "synced",
+		)
+		.map((c) => c.args[0] as string);
+
+const undeletedThreadMessageIds = (): string[] =>
+	called("threadMessage.update")
+		.filter((c) => (c.args[2] as { isDeleted?: boolean }).isDeleted === false)
+		.map((c) => c.args[1] as string);
+
 describe("handleEmptyTrash", () => {
 	beforeEach(() => {
 		h = fresh();
@@ -142,21 +208,66 @@ describe("handleEmptyTrash", () => {
 		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
 	});
 
-	it("skips the IMAP expunge when the trash is already empty on the server", async () => {
+	it("keeps the local row for a uid the expunge never covered", async () => {
+		// Mail that reached Trash after the SEARCH — or a move the unordered dev
+		// queue let outrun this event — is still on the server, so deleting its
+		// rows would hide mail the user can still see in another client.
+		h.localMessages = [
+			deleting("msg-1", 10),
+			deleting("msg-2", 11),
+			{ messageId: "msg-late", uid: 12, status: "active" },
+		];
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.deepEqual(
+			called("message.delete").map((c) => c.args[0]),
+			["msg-1", "msg-2"],
+		);
+	});
+
+	it("hands every row back when another client emptied the trash first", async () => {
+		// Apple Mail got there first, so the SEARCH is empty and this expunge
+		// covers nothing. Leaving the rows `deleting` hides mail that no longer
+		// exists anywhere, with nothing left to clear the mark.
 		h.connection.search = async () => [];
 
 		await handleEmptyTrash(event, noopLog, deps());
 
 		assert.equal(called("connection.deleteMessages").length, 0);
-		assert.equal(
-			called("message.delete").length,
-			2,
-			"local rows are still cleaned up",
-		);
+		assert.equal(called("message.delete").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
+		assert.deepEqual(undeletedThreadMessageIds(), ["tm-msg-1", "tm-msg-2"]);
+	});
+
+	it("hands back what a partial sweep left when the event is redelivered", async () => {
+		// The first attempt expunged and cleaned up msg-1, then died before
+		// msg-2. On redelivery the server has nothing left to find, and msg-2
+		// would otherwise sit marked for a deletion that will never come.
+		h.localMessages = [deleting("msg-2", 11)];
+		h.connection.search = async () => [];
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(called("message.delete").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-2"]);
+	});
+
+	it("leaves a row whose listing rows another operation already removed", async () => {
+		// A permanent delete inside Trash removes its listing rows up front and
+		// marks the Message `deleting`. Reverting it here would resurrect a row
+		// that operation is about to remove.
+		h.localMessages = [deleting("msg-1", 10), deleting("msg-expunging", 12)];
+		h.messagesWithoutListingRow = ["msg-expunging"];
+		h.connection.search = async () => [];
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.deepEqual(revertedMessageIds(), ["msg-1"]);
 	});
 
 	it("deletes the message even when it has no thread row", async () => {
-		h.threadMessage = null;
+		h.threadMessage = false;
 
 		await handleEmptyTrash(event, noopLog, deps());
 
@@ -182,12 +293,10 @@ describe("handleEmptyTrash", () => {
 		await assert.rejects(handleEmptyTrash(event, noopLog, deps()), /not found/);
 	});
 
-	it("skips without opening a connection when the cursor is rebuilding", async () => {
-		h.mailbox = {
-			mailboxId: "trash-mbx",
-			uidValidity: 1,
-			cursorState: "rebuilding",
-		};
+	it("acks terminally without connecting when the Trash mailbox was deleted", async () => {
+		h.mailboxError = Object.assign(new Error("Mailbox not found: trash-mbx"), {
+			name: "NotFoundError",
+		});
 
 		await handleEmptyTrash(event, noopLog, deps());
 
@@ -195,18 +304,78 @@ describe("handleEmptyTrash", () => {
 		assert.equal(called("message.delete").length, 0);
 	});
 
-	it("acks terminally without connecting when the Trash mailbox was deleted", async () => {
-		h.mailboxError = Object.assign(new Error("Mailbox not found: trash-mbx"), {
-			name: "NotFoundError",
-		});
+	it("abandons and reverts an event minted under an unknown contract", async () => {
+		const unversioned = {
+			type: "EMPTY_TRASH",
+			accountId: "acc-1",
+			trashMailboxId: "trash-mbx",
+			trashMailboxPath: "Trash",
+		} as unknown as EmptyTrashEvent;
+
+		await handleEmptyTrash(unversioned, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0, "no connection is ever opened");
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
+		assert.deepEqual(undeletedThreadMessageIds(), ["tm-msg-1", "tm-msg-2"]);
+	});
+
+	it("abandons when the Trash role now names a different folder", async () => {
+		h.trashResolution = {
+			kind: "appointed",
+			mailbox: { mailboxId: "other-mbx", fullPath: "INBOX/Bak" },
+		};
 
 		await handleEmptyTrash(event, noopLog, deps());
 
 		assert.equal(h.getConnectionCount, 0);
-		assert.equal(called("message.delete").length, 0);
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
 	});
 
-	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
+	it("abandons when the Trash role no longer rests on confirmed evidence", async () => {
+		h.trashResolution = {
+			kind: "proposed",
+			mailbox: { mailboxId: "trash-mbx", fullPath: "Trash" },
+		};
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
+	});
+
+	it("refuses the expunge when the served UIDVALIDITY is not the one consented to", async () => {
+		// The path was reused: a third-party client renamed Trash away and made a
+		// fresh one. Same path, different folder, and nobody consented to empty it.
+		h.connection.openBox = async () => ({ uidvalidity: 77 });
+		h.mailbox = { mailboxId: "trash-mbx", uidValidity: 77 };
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
+		assert.deepEqual(undeletedThreadMessageIds(), ["tm-msg-1", "tm-msg-2"]);
+		assert.equal(h.disconnectCount, 1);
+	});
+
+	it("reverts only the rows this empty marked, never a freshly synced one", async () => {
+		h.localMessages = [
+			deleting("msg-1", 10),
+			{ messageId: "msg-arrived", uid: 12, status: "active" },
+		];
+		h.connection.openBox = async () => ({ uidvalidity: 77 });
+		h.mailbox = { mailboxId: "trash-mbx", uidValidity: 77 };
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.deepEqual(revertedMessageIds(), ["msg-1"]);
+		assert.deepEqual(undeletedThreadMessageIds(), ["tm-msg-1"]);
+	});
+
+	it("reverts the marks when openBox trips a UIDVALIDITY mismatch", async () => {
+		// The event is acked and nothing re-issues it, so leaving the folder
+		// marked `deleting` hides healthy mail until the user notices.
 		h.connection.openBox = async () => ({ uidvalidity: 999 });
 
 		await handleEmptyTrash(event, noopLog, deps());
@@ -217,9 +386,24 @@ describe("handleEmptyTrash", () => {
 			"cursor_invalid",
 		);
 		assert.equal(called("message.delete").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
 		assert.equal(h.disconnectCount, 1);
 	});
 
+	it("reverts the marks without connecting when the cursor is rebuilding", async () => {
+		h.mailbox = {
+			mailboxId: "trash-mbx",
+			uidValidity: 1,
+			cursorState: "rebuilding",
+		};
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.delete").length, 0);
+		assert.deepEqual(revertedMessageIds(), ["msg-1", "msg-2"]);
+	});
+
 	it("rethrows an unclassified IMAP error so the event is retried", async () => {
 		h.connection.search = async () => {
 			throw new Error("server exploded");

package/src/handlers/empty-trash.ts

@@ -1,4 +1,8 @@
 import { getClient } from "@remit/backend/client";
+import type { MessageItem } from "@remit/data-ports";
+import { trashMailboxAt } from "@remit/data-ports/folder-role";
+import { isCurrentSchemaVersion } from "@remit/data-ports/mutation-events";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
@@ -11,6 +15,7 @@ import type { EmptyTrashEvent } from "../events.js";
 import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+import { buildThreadMessageUndelete } from "./message-delete.js";
 
 export interface EmptyTrashDeps {
 	getClient: typeof getClient;
@@ -29,6 +34,13 @@ const defaultDeps: EmptyTrashDeps = {
 /**
  * Handle EMPTY_TRASH events.
  * Permanently deletes all messages in the Trash mailbox.
+ *
+ * The only unrecoverable mutation reader issues, so the folder's identity is
+ * confirmed here, on the connection that does the expunging: the role still
+ * names this mailbox on confirmed evidence, and the UIDVALIDITY the SELECT
+ * serves still matches the one the user consented to. Every refusal reverts
+ * the optimistic local marks and acks — a throw would stall the account's FIFO
+ * group behind an event no retry can fix (issues #287, #289, #290).
  */
 export const handleEmptyTrash = async (
 	event: EmptyTrashEvent,
@@ -47,6 +59,7 @@ export const handleEmptyTrash = async (
 		message: messageService,
 		threadMessage: threadMessageService,
 		mailbox: mailboxService,
+		mailboxSpecialUse: mailboxSpecialUseService,
 		secrets,
 	} = await getClient();
 
@@ -66,6 +79,92 @@ export const handleEmptyTrash = async (
 		return;
 	}
 
+	// `emptyTrash` marks every row in the folder `deleting` + `isDeleted` before
+	// enqueueing, so any row this expunge does not carry through is hidden from
+	// every listing with nothing else to unhide it: no sync clears it, a repeat
+	// Empty Trash skips it again, and listings filter `isDeleted`. Handing it
+	// back is right whichever way it got left behind — mail already gone from
+	// the server becomes visible and the next cursor rebuild reconciles it, and
+	// an unsettled move is rewritten by its own MESSAGE_DELETE. Not `failed`:
+	// the mail is intact, and saying otherwise about a whole folder is a lie.
+	const handBackMarkedRows = async (
+		rows: readonly { messageId: string; status: MessageItem["status"] }[],
+	): Promise<number> => {
+		let revertedCount = 0;
+		for (const message of rows) {
+			if (message.status !== MessageStatus.deleting) continue;
+
+			// Empty Trash only flips `isDeleted` on the listing rows; a permanent
+			// delete removes them up front. So a `deleting` row with no listing row
+			// was marked by some other in-flight operation, and reverting the
+			// Message under it would resurrect what that one is about to remove.
+			const threadMessages = await threadMessageService.findAllByMessageId(
+				account.accountConfigId,
+				message.messageId,
+			);
+			if (threadMessages.length === 0) continue;
+
+			await messageService.update(message.messageId, {
+				status: MessageStatus.active,
+				syncStatus: MessageSyncStatus.synced,
+			});
+			for (const threadMessage of threadMessages) {
+				const args = buildThreadMessageUndelete(threadMessage);
+				await threadMessageService.update(
+					threadMessage.accountConfigId,
+					threadMessage.threadMessageId,
+					args.set,
+					{ composites: args.composites },
+				);
+			}
+			revertedCount += 1;
+		}
+		return revertedCount;
+	};
+
+	const abandonEmptyTrash = async (
+		reason: string,
+		alert: string,
+		context: Record<string, unknown> = {},
+	): Promise<void> => {
+		log.error(
+			{ alert, accountId, trashMailboxId, trashMailboxPath, ...context },
+			reason,
+		);
+		await handBackMarkedRows(
+			await messageService.listAllByMailbox(trashMailboxId),
+		);
+	};
+
+	if (!isCurrentSchemaVersion(event.schemaVersion)) {
+		await abandonEmptyTrash(
+			"Refused to empty trash: event was minted under an unknown contract",
+			"empty_trash_unknown_schema_version",
+			{ schemaVersion: event.schemaVersion },
+		);
+		return;
+	}
+
+	// The role can be re-appointed between consent and this run, and a queued
+	// event then expunges the folder the user just stopped using as Trash.
+	// Confirmed evidence only: what the user appointed, or what the server
+	// flagged.
+	const resolution = await mailboxSpecialUseService.resolveTrashRole(accountId);
+	const trashGate = trashMailboxAt(resolution, "confirmed");
+	if (!trashGate.allowed || trashGate.mailbox.mailboxId !== trashMailboxId) {
+		await abandonEmptyTrash(
+			"Refused to empty trash: this account's Trash is no longer that folder",
+			"empty_trash_role_moved",
+			{
+				resolvedKind: resolution.kind,
+				resolvedMailboxId: trashGate.allowed
+					? trashGate.mailbox.mailboxId
+					: undefined,
+			},
+		);
+		return;
+	}
+
 	await withOAuthLifecycle(
 		buildLifecycleDeps(secrets, accountService),
 		account,
@@ -90,13 +189,14 @@ export const handleEmptyTrash = async (
 				return;
 			}
 
-			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
-			// paused never even opens a connection. Optimization only — the
-			// guardConnectionCursor openBox wrap below is the structural guarantee.
+			// A paused cursor is not a wait here: this return acks the event and
+			// nothing re-issues it, so the marks have to come back or the folder
+			// stays hidden forever. The user retries.
 			if (isCursorRebuildNeeded(mailbox.cursorState)) {
-				log.info(
-					{ accountId, mailboxId: trashMailboxId },
-					"Mailbox cursor not normal; pausing empty-trash this round",
+				await abandonEmptyTrash(
+					"Abandoned empty trash: mailbox cursor is not normal",
+					"empty_trash_cursor_paused",
+					{ cursorState: mailbox.cursorState },
 				);
 				return;
 			}
@@ -108,21 +208,34 @@ export const handleEmptyTrash = async (
 				.then(async (rawConnection) => {
 					// Guard at the openBox choke point (epic #1281 invariants 3 & 5):
 					// a fresh mismatch trips the mailbox and throws once the SELECT
-					// reveals it. Local rows stay marked for deletion and are picked
-					// up once the mailbox returns to normal.
+					// reveals it.
 					const connection = guardConnectionCursor(
 						rawConnection,
 						{ mailboxService },
 						accountId,
 						mailbox,
 					);
-					await connection.openBox(trashMailboxPath, false);
+					const boxStatus = await connection.openBox(trashMailboxPath, false);
+
+					// The path is not the folder. A third-party client that renames
+					// Trash and creates a fresh one leaves this event pointing at a
+					// path now served by a folder the user never consented to empty;
+					// UIDVALIDITY is what tells them apart (RFC 9051 2.3.1.1).
+					if (boxStatus.uidvalidity !== event.trashUidValidity) {
+						await abandonEmptyTrash(
+							"Refused to empty trash: the folder at this path is not the one the user emptied",
+							"empty_trash_uidvalidity_mismatch",
+							{
+								servedUidValidity: boxStatus.uidvalidity,
+								consentedUidValidity: event.trashUidValidity,
+							},
+						);
+						return;
+					}
 
-					// Search for all messages in Trash
 					const uids = await connection.search(["ALL"]);
 
 					if (uids.length > 0) {
-						// Delete all messages on IMAP
 						await connection.deleteMessages(uids);
 						log.info(
 							{ count: uids.length },
@@ -130,15 +243,19 @@ export const handleEmptyTrash = async (
 						);
 					}
 
-					// Delete all local messages in trash
+					// Local cleanup follows the expunge, uid by uid. What was expunged
+					// is a fact this connection observed, and only those rows go.
+					const expunged = new Set(uids);
 					const localMessages =
 						await messageService.listAllByMailbox(trashMailboxId);
+					let deletedCount = 0;
 
 					for (const message of localMessages) {
-						// Delete the Message entity
+						if (!expunged.has(message.uid)) continue;
+						deletedCount += 1;
+
 						await messageService.delete(message.messageId);
 
-						// Delete the ThreadMessage entity
 						const threadMessage = await threadMessageService.findByMessageId(
 							account.accountConfigId,
 							message.messageId,
@@ -151,20 +268,25 @@ export const handleEmptyTrash = async (
 						}
 					}
 
+					// Everything the SEARCH did not name is still marked for a deletion
+					// that will never come: mail another client already emptied, mail
+					// that reached Trash after the SEARCH, or a redelivery finishing a
+					// partial sweep. All three must come back rather than sit invisible.
+					const revertedCount = await handBackMarkedRows(
+						localMessages.filter((message) => !expunged.has(message.uid)),
+					);
+
 					log.info(
-						{ accountId, deletedCount: localMessages.length },
+						{ accountId, deletedCount, revertedCount },
 						"Trash emptied successfully",
 					);
 				})
-				.catch((error: unknown) => {
+				.catch(async (error: unknown) => {
 					if (error instanceof MailboxCursorPausedError) {
-						log.info(
-							{
-								accountId,
-								mailboxId: trashMailboxId,
-								cursorState: error.state,
-							},
-							"Mailbox cursor not normal; pausing empty-trash this round",
+						await abandonEmptyTrash(
+							"Abandoned empty trash: mailbox cursor is not normal",
+							"empty_trash_cursor_paused",
+							{ cursorState: error.state },
 						);
 						return;
 					}

package/src/handlers/message-delete.test.ts

@@ -5,6 +5,7 @@ import type { Logger } from "@remit/logger-lambda";
 import type { MessageDeleteEvent } from "../events.js";
 import {
 	buildThreadMessageTrashUpdate,
+	buildThreadMessageUndelete,
 	deleteAllThreadMessagesForMessage,
 	handleMessageDelete,
 	type MessageDeleteDeps,
@@ -113,6 +114,45 @@ describe("buildThreadMessageTrashUpdate", () => {
 	});
 });
 
+describe("buildThreadMessageUndelete", () => {
+	// Every `set` payload here is hand-written, so the three builders can drift
+	// apart silently. Undelete is the exact inverse of the trash update's
+	// deletion mark, and it must move nothing else: the mail is still in Trash
+	// at the uid the row already carries.
+
+	it("clears only the deletion mark that buildThreadMessageTrashUpdate set", () => {
+		const trashed = buildThreadMessageTrashUpdate(
+			baseThreadMessage,
+			42,
+			trashMailboxId,
+		);
+		const undelete = buildThreadMessageUndelete(baseThreadMessage);
+
+		assert.strictEqual(trashed.set.isDeleted, true);
+		assert.strictEqual(undelete.set.isDeleted, false);
+		assert.deepStrictEqual(
+			Object.keys(undelete.set),
+			["isDeleted"],
+			"undelete must not move the row's uid or mailbox",
+		);
+	});
+
+	it("carries the CURRENT row state in composites, like every other builder", () => {
+		const undelete = buildThreadMessageUndelete(baseThreadMessage);
+
+		assert.deepStrictEqual(
+			undelete.composites,
+			buildThreadMessageTrashUpdate(baseThreadMessage, 42, trashMailboxId)
+				.composites,
+		);
+		assert.strictEqual(
+			undelete.composites.isDeleted,
+			baseThreadMessage.isDeleted,
+			"composites hold the state to check against, never the new value",
+		);
+	});
+});
+
 describe("deleteAllThreadMessagesForMessage (#212)", () => {
 	// Regression for the multi-mailbox cleanup gap in #212. A single Message
 	// can have ThreadMessage rows in multiple mailboxes (e.g. INBOX + a label
@@ -221,7 +261,7 @@ interface Harness {
 	connection: Connection;
 	threadMessageUpdateError?: Error;
 	threadMessage: Record<string, unknown> | null;
-	allThreadMessages: { accountConfigId: string; threadMessageId: string }[];
+	allThreadMessages: Record<string, unknown>[];
 	getConnectionCount: number;
 	disconnectCount: number;
 }
@@ -271,8 +311,8 @@ const fresh = (): Harness => ({
 		threadMessageId: "tm-1",
 	},
 	allThreadMessages: [
-		{ accountConfigId: "cfg-1", threadMessageId: "tm-1" },
-		{ accountConfigId: "cfg-1", threadMessageId: "tm-2" },
+		{ ...baseThreadMessage, accountConfigId: "cfg-1", threadMessageId: "tm-1" },
+		{ ...baseThreadMessage, accountConfigId: "cfg-1", threadMessageId: "tm-2" },
 	],
 	getConnectionCount: 0,
 	disconnectCount: 0,
@@ -330,6 +370,7 @@ const deps = (): MessageDeleteDeps =>
 
 const moveEvent: MessageDeleteEvent = {
 	type: "MESSAGE_DELETE",
+	schemaVersion: 2,
 	accountId: "acc-1",
 	messageId: "msg-1",
 	mailboxId: "src-mbx",
@@ -342,6 +383,7 @@ const moveEvent: MessageDeleteEvent = {
 
 const permanentEvent: MessageDeleteEvent = {
 	type: "MESSAGE_DELETE",
+	schemaVersion: 2,
 	accountId: "acc-1",
 	messageId: "msg-1",
 	mailboxId: "src-mbx",
@@ -578,18 +620,89 @@ describe("handleMessageDelete", () => {
 		);
 	});
 
-	it("creates the trash mailbox and rethrows on TRYCREATE", async () => {
+	it("abandons rather than creating the destination on TRYCREATE", async () => {
+		// Creating it resurrects an empty `Trash` beside the real one, and the
+		// name-hint rule then has two folders to choose between. The picker
+		// offers the ones the account actually has.
 		h.connection.moveMessages = async () => {
 			throw new Error("TRYCREATE: no such mailbox");
 		};
 
-		await assert.rejects(
-			handleMessageDelete(moveEvent, noopLog, deps()),
-			/TRYCREATE/,
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(called("connection.createMailbox").length, 0);
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"msg-1",
+			10,
+			"src-mbx",
+		]);
+		assert.deepEqual(called("message.update")[0]?.args[1], {
+			status: "active",
+			syncStatus: "failed",
+		});
+		assert.deepEqual(called("threadMessage.update")[0]?.args[2], {
+			uid: 10,
+			mailboxId: "src-mbx",
+			isDeleted: false,
+		});
+	});
+
+	it("abandons an event minted under an unknown contract, before connecting", async () => {
+		const unversioned = {
+			...moveEvent,
+			schemaVersion: undefined,
+		} as unknown as MessageDeleteEvent;
+
+		await handleMessageDelete(unversioned, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"msg-1",
+			10,
+			"src-mbx",
+		]);
+		assert.deepEqual(called("threadMessage.update")[0]?.args[2], {
+			uid: 10,
+			mailboxId: "src-mbx",
+			isDeleted: false,
+		});
+	});
+
+	it("hands back every listing row a message has, not just the first", async () => {
+		const unversioned = {
+			...moveEvent,
+			schemaVersion: undefined,
+		} as unknown as MessageDeleteEvent;
+
+		await handleMessageDelete(unversioned, noopLog, deps());
+
+		assert.deepEqual(
+			called("threadMessage.update").map((c) => c.args[1]),
+			["tm-1", "tm-2"],
 		);
+	});
 
-		assert.equal(called("connection.createMailbox")[0]?.args[0], "Trash");
-		assert.equal(h.getConnectionCount, 2, "reconnects to create the mailbox");
+	it("finishes the removal when an abandoned delete has no listing rows left", async () => {
+		// A permanent delete removes them before it enqueues, and they cannot be
+		// rebuilt here. Restoring the Message alone leaves mail nothing can list,
+		// which is worse than either consistent state; the server copy survives
+		// and a full sync brings it back.
+		h.allThreadMessages = [];
+		const unversioned = {
+			...permanentEvent,
+			schemaVersion: undefined,
+		} as unknown as MessageDeleteEvent;
+
+		await handleMessageDelete(unversioned, noopLog, deps());
+
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.deepEqual(called("message.delete")[0]?.args, ["msg-1"]);
+		assert.equal(
+			called("message.update").length,
+			0,
+			"never leave a Message row no listing can reach",
+		);
 	});
 
 	it("marks failed and rethrows on an unclassified IMAP error", async () => {

package/src/handlers/message-delete.ts

@@ -3,6 +3,7 @@ import type {
 	IThreadMessageRepository,
 	ThreadMessageItem,
 } from "@remit/data-ports";
+import { isCurrentSchemaVersion } from "@remit/data-ports/mutation-events";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import {
@@ -109,6 +110,18 @@ export const buildThreadMessageMoveRevert = (
 	composites: currentComposites(threadMessage),
 });
 
+/**
+ * Hand a row back after an abandoned expunge. The mail never left Trash, so
+ * only the deletion mark reverts — the uid and mailbox on the row are still
+ * where the server has it.
+ */
+export const buildThreadMessageUndelete = (
+	threadMessage: ThreadMessageRowState,
+) => ({
+	set: { isDeleted: false },
+	composites: currentComposites(threadMessage),
+});
+
 export interface MessageDeleteDeps {
 	getClient: typeof getClient;
 	buildLifecycleDeps: typeof buildLifecycleDeps;
@@ -172,6 +185,75 @@ export const handleMessageDelete = async (
 		return;
 	}
 
+	// Only an operation that explicitly says so destroys mail. The event is
+	// `JSON.parse`d and cast in the queue handler with no validation, so a
+	// missing, misspelled or future field must abandon the delete — the
+	// "anything that is not move_to_trash is an expunge" inference is the same
+	// one that destroyed mail in the service, and an unrecoverable EXPUNGE is
+	// not a default. Abandoning hands the row back where the server still has
+	// it: an invisible `failed` on a row the user cannot see is the shape of
+	// the incident this whole change is about.
+	const abandonDelete = async (
+		reason: string,
+		alert: string,
+	): Promise<void> => {
+		log.error(
+			{ alert, accountId, messageId, uid, mailboxPath, operation },
+			reason,
+		);
+
+		const threadMessages = await threadMessageService.findAllByMessageId(
+			account.accountConfigId,
+			messageId,
+		);
+
+		// A permanent delete removes the listing rows before it enqueues, and
+		// they cannot be rebuilt from here — the row is denormalized off an
+		// envelope only the sync path shapes. Restoring the Message alone would
+		// leave mail nothing can list, which is the silent vanish rather than a
+		// visible failure, so the local removal finishes instead. The server copy
+		// survives (nothing was expunged) and a full sync of the mailbox brings
+		// it back. Reachable only through the rollout window, where a v1 event
+		// carries no `schemaVersion`.
+		if (threadMessages.length === 0) {
+			log.error(
+				{
+					alert: "message_delete_abandoned_after_local_cleanup",
+					accountId,
+					messageId,
+					uid,
+					mailboxPath,
+				},
+				"Abandoned delete had no listing rows left to restore; the server copy was not expunged",
+			);
+			await messageService.delete(messageId);
+			return;
+		}
+
+		await messageService.updateUid(messageId, uid, mailboxId);
+		await messageService.update(messageId, {
+			status: MessageStatus.active,
+			syncStatus: MessageSyncStatus.failed,
+		});
+		for (const threadMessage of threadMessages) {
+			const args = buildThreadMessageMoveRevert(threadMessage, uid, mailboxId);
+			await threadMessageService.update(
+				threadMessage.accountConfigId,
+				threadMessage.threadMessageId,
+				args.set,
+				{ composites: args.composites },
+			);
+		}
+	};
+
+	if (!isCurrentSchemaVersion(event.schemaVersion)) {
+		await abandonDelete(
+			"Refused to delete: event was minted under an unknown contract",
+			"message_delete_unknown_schema_version",
+		);
+		return;
+	}
+
 	await withOAuthLifecycle(
 		buildLifecycleDeps(secrets, accountService),
 		account,
@@ -223,43 +305,6 @@ export const handleMessageDelete = async (
 					);
 					await connection.openBox(mailboxPath, false);
 
-					// Only an operation that explicitly says so destroys mail. The
-					// event is `JSON.parse`d and cast in the queue handler with no
-					// validation, so a missing, misspelled or future `operation` must
-					// abandon the delete — the "anything that is not move_to_trash is
-					// an expunge" inference is the same one that destroyed mail in the
-					// service, and an unrecoverable EXPUNGE is not a default.
-					const abandonDelete = async (
-						reason: string,
-						alert: string,
-					): Promise<void> => {
-						log.error(
-							{ alert, accountId, messageId, uid, mailboxPath, operation },
-							reason,
-						);
-						await messageService.updateUid(messageId, uid, mailboxId);
-						await messageService.update(messageId, {
-							status: MessageStatus.active,
-							syncStatus: MessageSyncStatus.failed,
-						});
-						const threadMessage = await threadMessageService.findByMessageId(
-							account.accountConfigId,
-							messageId,
-						);
-						if (!threadMessage) return;
-						const args = buildThreadMessageMoveRevert(
-							threadMessage,
-							uid,
-							mailboxId,
-						);
-						await threadMessageService.update(
-							threadMessage.accountConfigId,
-							threadMessage.threadMessageId,
-							args.set,
-							{ composites: args.composites },
-						);
-					};
-
 					if (
 						operation !== "move_to_trash" &&
 						operation !== "permanent_delete"
@@ -398,16 +443,16 @@ export const handleMessageDelete = async (
 						return;
 					}
 
-					// TRYCREATE - Trash doesn't exist
+					// TRYCREATE — the destination this event names is not on the
+					// server. Creating it would resurrect an empty `Trash` beside the
+					// real one and hand the name-hint rule two folders to choose
+					// between; the folder picker offers the ones that exist instead.
 					if (errorMessage.includes("TRYCREATE") && destinationMailboxPath) {
-						log.info(
-							{ destinationMailboxPath },
-							"Trash mailbox doesn't exist, creating",
+						await abandonDelete(
+							"Refused to delete: the destination mailbox does not exist on the server",
+							"message_delete_destination_missing",
 						);
-						const connection = await scope.getConnection();
-						await connection.createMailbox(destinationMailboxPath);
-						// Re-throw to let the event be retried
-						throw error;
+						return;
 					}
 
 					// Mark as failed for other errors

package/src/handlers/message-move.test.ts

@@ -3,6 +3,7 @@ import { afterEach, before, describe, it, mock } from "node:test";
 import { getClient, type RemitClient, setClient } from "@remit/backend/client";
 import type { AccountItem, ThreadMessageItem } from "@remit/data-ports";
 import type { Logger } from "@remit/logger-lambda";
+import type { IImapConnection } from "@remit/mailbox-service";
 import type { MessageMoveEvent } from "../events.js";
 import {
 	buildThreadMessageMoveUpdate,
@@ -11,6 +12,7 @@ import {
 	handleMessageMove,
 	MESSAGE_MOVE_MAX_ATTEMPTS,
 	moveThenResync,
+	searchMailboxByMessageId,
 } from "./message-move.js";
 
 const silentLogger = (() => {
@@ -340,3 +342,85 @@ describe("handleMessageMove — the move's own pending state gates every attempt
 		assert.equal(mailboxGet.mock.calls.length, 0);
 	});
 });
+
+describe("searchMailboxByMessageId — the probe that binds a move to a UID (#912)", () => {
+	const isMessageIdCriterion = (
+		criterion: unknown,
+	): criterion is [string, string, string] =>
+		Array.isArray(criterion) &&
+		criterion.length === 3 &&
+		typeof criterion[0] === "string" &&
+		criterion[0].toUpperCase() === "HEADER" &&
+		typeof criterion[1] === "string" &&
+		criterion[1].toLowerCase() === "message-id" &&
+		typeof criterion[2] === "string";
+
+	const buildDestination = (
+		messages: Array<{ uid: number; messageIdHeader: string }>,
+	): IImapConnection => {
+		const searchAll = () => messages.map((row) => row.uid);
+		return {
+			openBox: async () => ({}) as never,
+			search: async (criteria: unknown[]) => {
+				const criterion = criteria.find(isMessageIdCriterion);
+				if (criterion === undefined) return searchAll();
+				return messages
+					.filter((row) => row.messageIdHeader === criterion[2])
+					.map((row) => row.uid);
+			},
+		} as unknown as IImapConnection;
+	};
+
+	it("asks the folder by Message-ID rather than by an interpolated string", async () => {
+		const sent: unknown[][] = [];
+		const destination = {
+			openBox: async () => ({}) as never,
+			search: async (criteria: unknown[]) => {
+				sent.push(criteria);
+				return [];
+			},
+		} as unknown as IImapConnection;
+
+		await searchMailboxByMessageId(
+			destination,
+			"Archive",
+			'<a"b@example.com>\r\nUID 1',
+		);
+
+		assert.deepStrictEqual(sent, [
+			[["HEADER", "Message-ID", '<a"b@example.com>\r\nUID 1']],
+		]);
+	});
+
+	it("answers null, not the lowest UID, when the folder holds no such message", async () => {
+		const destination = buildDestination([
+			{ uid: 11, messageIdHeader: "<stranger-a@example.com>" },
+			{ uid: 12, messageIdHeader: "<stranger-b@example.com>" },
+		]);
+
+		assert.strictEqual(
+			await searchMailboxByMessageId(
+				destination,
+				"Archive",
+				"<moved@example.com>",
+			),
+			null,
+		);
+	});
+
+	it("answers the UID of the message carrying that Message-ID", async () => {
+		const destination = buildDestination([
+			{ uid: 11, messageIdHeader: "<stranger-a@example.com>" },
+			{ uid: 12, messageIdHeader: "<moved@example.com>" },
+		]);
+
+		assert.strictEqual(
+			await searchMailboxByMessageId(
+				destination,
+				"Archive",
+				"<moved@example.com>",
+			),
+			12,
+		);
+	});
+});

package/src/handlers/message-move.ts

@@ -78,7 +78,7 @@ export const searchMailboxByMessageId = async (
 ): Promise<number | null> => {
 	await connection.openBox(mailboxPath, true);
 	const uids = await connection.search([
-		`HEADER Message-ID "${messageIdHeader}"`,
+		["HEADER", "Message-ID", messageIdHeader],
 	]);
 	return uids[0] ?? null;
 };