@remit/mailbox-service 0.0.66 → 0.0.68

package/package.json

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

package/src/index.ts

@@ -191,6 +191,9 @@ export {
 	type MessageMoveLogger,
 	MessageMoveService,
 	NoTrashMailboxError,
+	requireTrashMailbox,
+	StaleTrashAppointmentError,
+	UnconfirmedTrashMailboxError,
 } from "./message-move.js";
 export {
 	type ParsedMessageContent,

package/src/message-delete-junk-reconcile.test.ts

@@ -8,6 +8,7 @@ import type {
 	IThreadMessageRepository,
 } from "@remit/data-ports";
 import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
+import { trashRole } from "./test-helpers/folder-roles.js";
 
 const ACCOUNT = "acc-1";
 const ACCOUNT_CONFIG = "cfg-1";
@@ -51,9 +52,11 @@ const buildWorld = (trashExists: boolean) => {
 		],
 	} as unknown as IMailboxRepository;
 
+	const trash = trashExists ? { mailboxId: TRASH, fullPath: "Trash" } : null;
+
 	const mailboxSpecialUseService = {
-		findTrashMailbox: async () =>
-			trashExists ? { mailboxId: TRASH, fullPath: "Trash" } : null,
+		findTrashMailbox: async () => trash,
+		resolveTrashRole: async () => trashRole(trash),
 	} as unknown as IMailboxSpecialUseRepository;
 
 	const addressService = {

package/src/message-delete-no-trash.test.ts

@@ -7,10 +7,12 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
+import type { RoleResolution } from "@remit/data-ports/folder-role";
 import {
 	type MessageMoveConfig,
 	MessageMoveService,
 	NoTrashMailboxError,
+	StaleTrashAppointmentError,
 } from "./message-move.js";
 
 const ACCOUNT = "acc-1";
@@ -19,13 +21,15 @@ const INBOX = "mbx-inbox";
 const TRASH = "mbx-trash";
 const MESSAGE_ID = "msg-1";
 
+type TrashMailbox = { mailboxId: string; fullPath: string };
+
 interface EnqueuedEvent {
 	operation: string;
 	destinationMailboxPath?: string;
 }
 
 const buildWorld = (
-	trash: { mailboxId: string; fullPath: string } | null,
+	trashResolution: RoleResolution<TrashMailbox>,
 	startingMailboxId = INBOX,
 ) => {
 	const patches: Array<Record<string, unknown>> = [];
@@ -74,7 +78,7 @@ const buildWorld = (
 	} as unknown as IMailboxRepository;
 
 	const mailboxSpecialUseService = {
-		findTrashMailbox: async () => trash,
+		resolveTrashRole: async () => trashResolution,
 	} as unknown as IMailboxSpecialUseRepository;
 
 	const addressService = {
@@ -102,12 +106,14 @@ const buildWorld = (
 	return { service, patches, events, message };
 };
 
+const flaggedTrash: RoleResolution<TrashMailbox> = {
+	kind: "flagged",
+	mailbox: { mailboxId: TRASH, fullPath: "INBOX/Trash" },
+};
+
 describe("delete only expunges when it was asked to", () => {
 	it("moves to a Trash the account resolves under a nested path", async () => {
-		const { service, events, message } = buildWorld({
-			mailboxId: TRASH,
-			fullPath: "INBOX/Trash",
-		});
+		const { service, events, message } = buildWorld(flaggedTrash);
 
 		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
 
@@ -120,13 +126,14 @@ describe("delete only expunges when it was asked to", () => {
 	});
 
 	it("refuses, and touches nothing, when no Trash resolves", async () => {
-		const { service, patches, events, message } = buildWorld(null);
+		const { service, patches, events, message } = buildWorld({ kind: "none" });
 
 		await assert.rejects(
 			() => service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT),
 			(error: unknown) =>
 				error instanceof NoTrashMailboxError &&
 				error.statusCode === 409 &&
+				error.publicApiError?.details?.reason === "none" &&
 				error.message.includes("no Trash folder"),
 		);
 
@@ -136,12 +143,53 @@ describe("delete only expunges when it was asked to", () => {
 		assert.equal(message.status, "active");
 	});
 
-	it("expunges only when the caller asked for a permanent delete", async () => {
-		const { service, events } = buildWorld({
-			mailboxId: TRASH,
-			fullPath: "INBOX/Trash",
+	it("refuses a stale appointment rather than filing into the fallback", async () => {
+		// #887 Done item 2: the user appointed a folder another client has since
+		// deleted. Silently filing 200 messages into the flagged folder overrides
+		// a choice they made and cannot see was lost.
+		const { service, patches, events, message } = buildWorld({
+			kind: "appointment_stale",
+			appointedMailboxId: "mbx-appointed-and-gone",
+			fallback: flaggedTrash,
+		});
+
+		await assert.rejects(
+			() => service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT),
+			(error: unknown) =>
+				error instanceof StaleTrashAppointmentError &&
+				error.statusCode === 409 &&
+				error.publicApiError?.details?.reason === "stale" &&
+				error.publicApiError?.details?.accountId === ACCOUNT,
+		);
+
+		assert.deepEqual(events, []);
+		assert.deepEqual(patches, []);
+		assert.equal(message.mailboxId, INBOX);
+		assert.equal(message.status, "active");
+	});
+
+	it("files into a Trash that resolves by name alone", async () => {
+		// A name guess is enough to move mail somewhere retrievable; only the
+		// expunge demands more (D4).
+		const { service, events, message } = buildWorld({
+			kind: "proposed",
+			mailbox: { mailboxId: TRASH, fullPath: "Trash" },
 		});
 
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
+
+		assert.deepEqual(
+			events.map((event) => event.operation),
+			["move_to_trash"],
+		);
+		assert.equal(message.mailboxId, TRASH);
+	});
+
+	it("expunges only when the caller asked for a permanent delete", async () => {
+		// fc685509: an explicit permanent delete never resolves Trash at all, so
+		// an account with none can still empty a message it selected.
+		const { service, events } = buildWorld({ kind: "none" });
+
 		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT, {
 			permanent: true,
 		});
@@ -152,9 +200,11 @@ describe("delete only expunges when it was asked to", () => {
 		);
 	});
 
-	it("expunges a message already in Trash, which the dialog asks as such", async () => {
+	it("expunges a message already inside a Trash that resolves by name", async () => {
+		// D4a: the rows were selected and the dialog named the consequence, so
+		// consent is per message. Empty Trash has no such consent and refuses.
 		const { service, events } = buildWorld(
-			{ mailboxId: TRASH, fullPath: "INBOX/Trash" },
+			{ kind: "proposed", mailbox: { mailboxId: TRASH, fullPath: "Trash" } },
 			TRASH,
 		);
 

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

@@ -15,7 +15,7 @@ import { MailboxCursorState } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
 import { MessageSyncService } from "./message-sync.js";
-import { noFolderRoles } from "./test-helpers/folder-roles.js";
+import { noFolderRoles, trashRole } from "./test-helpers/folder-roles.js";
 import type { IImapConnection, ImapMessage } from "./types.js";
 
 const stubAddressService = (): IAddressRepository =>
@@ -175,6 +175,7 @@ const buildWorld = () => {
 	// where a copy's placement row must be reachable.
 	const mailboxSpecialUseService = {
 		findTrashMailbox: async () => null,
+		resolveTrashRole: async () => trashRole(null),
 	} as unknown as IMailboxSpecialUseRepository;
 
 	const config: MessageMoveConfig = {

package/src/message-move-empty-trash.test.ts

@@ -1,8 +1,9 @@
 /**
- * Empty Trash is an EXPUNGE with no undo, so it resolves its folder through
- * `findConfirmedTrashMailbox` — what the user appointed, or what the server
- * flagged `\Trash`. The name proposal that serves every other lookup is a
- * guess, and a wrong guess here destroys mail (#837, audit #841).
+ * Empty Trash is an EXPUNGE with no undo, so it demands confirmed evidence:
+ * what the user appointed, or what the server flagged `\Trash`. The name
+ * proposal that serves every other lookup is a guess, and a wrong guess here
+ * destroys mail (#837, audit #841). Each way that evidence can be missing
+ * refuses under its own reason, so the surface can name the repair (#887).
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
@@ -13,20 +14,58 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
-import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
+import type { RoleResolution } from "@remit/data-ports/folder-role";
+import {
+	type MessageMoveConfig,
+	MessageMoveService,
+	NoTrashMailboxError,
+	StaleTrashAppointmentError,
+	UnconfirmedTrashMailboxError,
+} from "./message-move.js";
 
 const ACCOUNT = "acc-1";
 const ACCOUNT_CONFIG = "cfg-1";
 const DELETED_FOLDER = "mbx-deleted";
 const REAL_TRASH = "mbx-trash";
 
+type TrashMailbox = { mailboxId: string; fullPath: string };
+
+const appointedTrash: RoleResolution<TrashMailbox> = {
+	kind: "appointed",
+	mailbox: { mailboxId: REAL_TRASH, fullPath: "[Gmail]/Trash" },
+};
+
+// A folder merely named `Deleted` is what the name proposal returns, and the
+// confirmed gate is what this path asks for.
+const proposedDeletedFolder: RoleResolution<TrashMailbox> = {
+	kind: "proposed",
+	mailbox: { mailboxId: DELETED_FOLDER, fullPath: "Deleted" },
+};
+
+interface TrashMessage {
+	messageId: string;
+	syncStatus: string;
+}
+
+interface EnqueuedEvent {
+	type: string;
+	schemaVersion?: number;
+	trashMailboxId?: string;
+	trashUidValidity?: number;
+}
+
 const buildWorld = (
-	confirmedTrash: { mailboxId: string; fullPath: string } | null,
+	trashResolution: RoleResolution<TrashMailbox>,
+	trashContents: TrashMessage[] = [
+		{ messageId: "junk-1", syncStatus: "synced" },
+	],
 ) => {
 	const emptied: string[] = [];
-	const messagesByMailbox = new Map<string, { messageId: string }[]>([
-		[DELETED_FOLDER, [{ messageId: "keepsake-1" }]],
-		[REAL_TRASH, [{ messageId: "junk-1" }]],
+	const markedDeleting: string[] = [];
+	const events: EnqueuedEvent[] = [];
+	const messagesByMailbox = new Map<string, TrashMessage[]>([
+		[DELETED_FOLDER, [{ messageId: "keepsake-1", syncStatus: "synced" }]],
+		[REAL_TRASH, trashContents],
 	]);
 
 	const messageService = {
@@ -34,7 +73,9 @@ const buildWorld = (
 			emptied.push(mailboxId);
 			return messagesByMailbox.get(mailboxId) ?? [];
 		},
-		update: async () => {},
+		update: async (messageId: string) => {
+			markedDeleting.push(messageId);
+		},
 	} as unknown as IMessageRepository;
 
 	const threadMessageService = {
@@ -48,18 +89,17 @@ const buildWorld = (
 
 	const config: MessageMoveConfig = {
 		messageService,
-		mailboxService: {} as unknown as IMailboxRepository,
+		mailboxService: {
+			get: async (_accountId: string, mailboxId: string) => ({
+				mailboxId,
+				uidValidity: 42,
+			}),
+		} as unknown as IMailboxRepository,
 		addressService: {
 			reconcileJunkOnlyForMessage: async () => {},
 		} as unknown as IAddressRepository,
 		mailboxSpecialUseService: {
-			// A folder merely named `Deleted` is what the name proposal would
-			// return; the confirmed lookup is what this path asks for.
-			findTrashMailbox: async () => ({
-				mailboxId: DELETED_FOLDER,
-				fullPath: "Deleted",
-			}),
-			findConfirmedTrashMailbox: async () => confirmedTrash,
+			resolveTrashRole: async () => trashResolution,
 		} as unknown as IMailboxSpecialUseRepository,
 		threadMessageService,
 		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
@@ -67,18 +107,19 @@ const buildWorld = (
 
 	const service = new MessageMoveService(config);
 	(
-		service as unknown as { sqs: { send: (c: unknown) => Promise<unknown> } }
-	).sqs = { send: async () => ({}) };
+		service as unknown as {
+			enqueueEvent: (event: EnqueuedEvent) => Promise<void>;
+		}
+	).enqueueEvent = async (event) => {
+		events.push(event);
+	};
 
-	return { service, emptied };
+	return { service, emptied, markedDeleting, events };
 };
 
 describe("MessageMoveService.emptyTrash", () => {
 	it("empties the appointed Trash, never the user folder called Deleted", async () => {
-		const { service, emptied } = buildWorld({
-			mailboxId: REAL_TRASH,
-			fullPath: "[Gmail]/Trash",
-		});
+		const { service, emptied } = buildWorld(appointedTrash);
 
 		await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
 
@@ -86,15 +127,116 @@ describe("MessageMoveService.emptyTrash", () => {
 	});
 
 	it("refuses and names the remedy when no folder is appointed or flagged", async () => {
-		const { service, emptied } = buildWorld(null);
+		const { service, emptied } = buildWorld({ kind: "none" });
 
 		await assert.rejects(
 			service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT),
-			/Appoint one under Settings/,
+			(error: unknown) =>
+				error instanceof NoTrashMailboxError &&
+				error.publicApiError?.details?.reason === "none",
 		);
 
 		// Nothing was read, so nothing was marked for deletion and no expunge
 		// was enqueued: an unresolved Trash stops the operation dead.
 		assert.deepEqual(emptied, []);
 	});
+
+	it("refuses a Trash that only resolves by name, under its own reason", async () => {
+		// D18: a plausible folder nobody confirmed is a third answer, distinct
+		// from having none. The refusal is what mints the appointment.
+		const { service, emptied, markedDeleting } = buildWorld(
+			proposedDeletedFolder,
+		);
+
+		await assert.rejects(
+			service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT),
+			(error: unknown) =>
+				error instanceof UnconfirmedTrashMailboxError &&
+				error.statusCode === 409 &&
+				error.publicApiError?.details?.reason === "unconfirmed" &&
+				error.publicApiError?.details?.accountId === ACCOUNT,
+		);
+
+		assert.deepEqual(emptied, []);
+		assert.deepEqual(markedDeleting, []);
+	});
+
+	it("refuses a stale appointment rather than emptying its fallback", async () => {
+		const { service, emptied, markedDeleting } = buildWorld({
+			kind: "appointment_stale",
+			appointedMailboxId: "mbx-appointed-and-gone",
+			fallback: { kind: "flagged", mailbox: appointedTrash.mailbox },
+		});
+
+		await assert.rejects(
+			service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT),
+			(error: unknown) =>
+				error instanceof StaleTrashAppointmentError &&
+				error.publicApiError?.details?.reason === "stale",
+		);
+
+		assert.deepEqual(emptied, []);
+		assert.deepEqual(markedDeleting, []);
+	});
+
+	it("reports what it marked, from the one read that decided it", async () => {
+		const { service, markedDeleting } = buildWorld(appointedTrash, [
+			{ messageId: "junk-1", syncStatus: "synced" },
+			{ messageId: "junk-2", syncStatus: "synced" },
+			{ messageId: "junk-3", syncStatus: "synced" },
+		]);
+
+		const { deletedCount } = await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+
+		assert.equal(deletedCount, markedDeleting.length);
+		assert.equal(deletedCount, 3);
+	});
+
+	it("marks and counts a message whose move to Trash has not settled", async () => {
+		// The user saw the message in Trash and asked for the folder to be
+		// emptied. Skipping it reports a number the folder contradicts, and the
+		// queue is per-account FIFO, so the move has landed on the server before
+		// the expunge is even delivered.
+		const { service, markedDeleting } = buildWorld(appointedTrash, [
+			{ messageId: "settled-1", syncStatus: "synced" },
+			{ messageId: "still-moving-1", syncStatus: "pending" },
+		]);
+
+		const { deletedCount } = await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+
+		assert.deepEqual(markedDeleting, ["settled-1", "still-moving-1"]);
+		assert.equal(deletedCount, 2);
+	});
+
+	it("reports the same count when pressed twice before the worker runs", async () => {
+		// The rows it marked are still in that folder, so N stays true and the
+		// re-mark is idempotent. Reporting 0 the second time while still
+		// enqueuing an expunge would read as success over an untouched Trash.
+		const { service, events } = buildWorld(appointedTrash, [
+			{ messageId: "junk-1", syncStatus: "synced" },
+			{ messageId: "junk-2", syncStatus: "synced" },
+		]);
+
+		const first = await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+		const second = await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+
+		assert.equal(first.deletedCount, 2);
+		assert.equal(second.deletedCount, 2);
+		assert.deepEqual(
+			events.map((event) => event.type),
+			["EMPTY_TRASH", "EMPTY_TRASH"],
+		);
+	});
+
+	it("carries the folder's identity as it stood at consent time", async () => {
+		// The worker compares this against what its own SELECT serves. Without
+		// it the expunge would be authorised by a path, and a path is reusable.
+		const { service, events } = buildWorld(appointedTrash);
+
+		await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+
+		assert.equal(events[0]?.schemaVersion, 2);
+		assert.equal(events[0]?.trashMailboxId, REAL_TRASH);
+		assert.equal(events[0]?.trashUidValidity, 42);
+	});
 });

package/src/message-move-same-mailbox.test.ts

@@ -8,6 +8,7 @@ import type {
 	IThreadMessageRepository,
 } from "@remit/data-ports";
 import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
+import { trashRole } from "./test-helpers/folder-roles.js";
 
 const stubAddressService = (): IAddressRepository =>
 	({
@@ -66,6 +67,7 @@ const buildWorld = () => {
 
 	const mailboxSpecialUseService = {
 		findTrashMailbox: async () => null,
+		resolveTrashRole: async () => trashRole(null),
 	} as unknown as IMailboxSpecialUseRepository;
 
 	const config: MessageMoveConfig = {

package/src/message-move.ts

@@ -12,8 +12,17 @@ import type {
 	IThreadMessageRepository,
 } from "@remit/data-ports";
 import { FolderRoleUnresolvedError } from "@remit/data-ports/errors";
-import { NO_TRASH_FOLDER_REASON } from "@remit/data-ports/folder-role";
+import {
+	type FolderRoleUnresolvedReason,
+	NO_TRASH_FOLDER_REASON,
+	type RoleResolution,
+	STALE_TRASH_FOLDER_REASON,
+	type TrashAssuranceLevel,
+	trashMailboxAt,
+	UNCONFIRMED_TRASH_FOLDER_REASON,
+} from "@remit/data-ports/folder-role";
 import { deriveCopyMessageId } from "@remit/data-ports/id";
+import { MUTATION_EVENT_SCHEMA_VERSION } from "@remit/data-ports/mutation-events";
 import {
 	CanonicalMailboxRole,
 	MessageStatus,
@@ -27,6 +36,7 @@ import { createQueueProducer } from "@remit/sqs-client/producer";
  */
 interface MessageDeleteEvent {
 	type: "MESSAGE_DELETE";
+	schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
 	eventId: string;
 	timestamp: number;
 	accountId: string;
@@ -54,11 +64,14 @@ interface MessageMoveEvent {
 
 interface EmptyTrashEvent {
 	type: "EMPTY_TRASH";
+	schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
 	eventId: string;
 	timestamp: number;
 	accountId: string;
 	trashMailboxId: string;
 	trashMailboxPath: string;
+	/** The folder's UIDVALIDITY at consent time; the worker re-checks it. */
+	trashUidValidity: number;
 }
 
 interface MessageCopyEvent {
@@ -129,6 +142,74 @@ export class NoTrashMailboxError extends FolderRoleUnresolvedError {
 	}
 }
 
+/**
+ * The folder the user appointed as Trash is gone from the server. Distinct from
+ * having no Trash at all: there is a decision on file, and the repair is to
+ * point it at a folder that exists — not to let reader pick one instead.
+ */
+export class StaleTrashAppointmentError extends FolderRoleUnresolvedError {
+	name = "StaleTrashAppointmentError";
+
+	constructor(accountId: string) {
+		super(
+			STALE_TRASH_FOLDER_REASON,
+			CanonicalMailboxRole.Trash,
+			"stale",
+			accountId,
+		);
+	}
+}
+
+/**
+ * A folder resolves as Trash by its name alone. Enough to move mail into,
+ * never enough to expunge — so only the Empty Trash path raises it.
+ */
+export class UnconfirmedTrashMailboxError extends FolderRoleUnresolvedError {
+	name = "UnconfirmedTrashMailboxError";
+
+	constructor(accountId: string) {
+		super(
+			UNCONFIRMED_TRASH_FOLDER_REASON,
+			CanonicalMailboxRole.Trash,
+			"unconfirmed",
+			accountId,
+		);
+	}
+}
+
+const REFUSAL_BY_REASON: Record<
+	FolderRoleUnresolvedReason,
+	new (
+		accountId: string,
+	) => FolderRoleUnresolvedError
+> = {
+	none: NoTrashMailboxError,
+	stale: StaleTrashAppointmentError,
+	unconfirmed: UnconfirmedTrashMailboxError,
+};
+
+/** The coded 409 for one refusal reason. The only place a reason becomes an error. */
+const trashRefusal = (
+	reason: FolderRoleUnresolvedReason,
+	accountId: string,
+): FolderRoleUnresolvedError => new REFUSAL_BY_REASON[reason](accountId);
+
+/**
+ * The Trash folder a verb may act on at the assurance it demands, or the coded
+ * refusal naming which of the three reasons stopped it. Every Trash gate goes
+ * through here — the delete and the expunge — so no two of them can tell a
+ * user different things about the same account.
+ */
+export const requireTrashMailbox = <T>(
+	resolution: RoleResolution<T>,
+	level: TrashAssuranceLevel,
+	accountId: string,
+): T => {
+	const outcome = trashMailboxAt(resolution, level);
+	if (outcome.allowed) return outcome.mailbox;
+	throw trashRefusal(outcome.reason, accountId);
+};
+
 /**
  * Options for delete operations
  */
@@ -226,18 +307,23 @@ export class MessageMoveService {
 		const wantsPermanentDelete =
 			options.permanent === true || options.toTrash === false;
 
-		const trashMailbox = wantsPermanentDelete
+		const trashGate = wantsPermanentDelete
 			? null
-			: await this.mailboxSpecialUseService.findTrashMailbox(accountId);
+			: trashMailboxAt(
+					await this.mailboxSpecialUseService.resolveTrashRole(accountId),
+					"resolved",
+				);
 
-		if (!wantsPermanentDelete && !trashMailbox) {
+		if (trashGate && !trashGate.allowed) {
 			this.log.error(
-				{ accountId, messageCount: messages.length },
-				"Refused to delete: account resolves no Trash mailbox",
+				{ accountId, messageCount: messages.length, reason: trashGate.reason },
+				"Refused to delete: this account's Trash is unresolved",
 			);
-			throw new NoTrashMailboxError(accountId);
+			throw trashRefusal(trashGate.reason, accountId);
 		}
 
+		const trashMailbox = trashGate ? trashGate.mailbox : null;
+
 		// Group messages by operation type
 		const moveToTrashMessages: Array<{
 			messageId: string;
@@ -301,6 +387,7 @@ export class MessageMoveService {
 
 				events.push({
 					type: "MESSAGE_DELETE",
+					schemaVersion: MUTATION_EVENT_SCHEMA_VERSION,
 					eventId: randomUUID(),
 					timestamp: Date.now(),
 					accountId,
@@ -344,6 +431,7 @@ export class MessageMoveService {
 
 			events.push({
 				type: "MESSAGE_DELETE",
+				schemaVersion: MUTATION_EVENT_SCHEMA_VERSION,
 				eventId: randomUUID(),
 				timestamp: Date.now(),
 				accountId,
@@ -659,26 +747,39 @@ export class MessageMoveService {
 	/**
 	 * Empty the Trash mailbox: an EXPUNGE of everything in it, with no undo.
 	 *
-	 * Resolved through `findConfirmedTrashMailbox`, so the folder is the one the
-	 * user appointed or the one the server flagged \Trash — never one that
-	 * merely reads like a trash folder. A user with an ordinary folder called
-	 * `Deleted` would otherwise lose its contents permanently, and on a
-	 * `.`-delimited server the old whole-path name match resolved nothing at all
-	 * and the operation reported success over an empty count. Unresolved is a
-	 * refusal that names the remedy, not a silent no-op.
+	 * Demands confirmed evidence: the folder the user appointed or the one the
+	 * server flagged \Trash — never one that merely reads like a trash folder,
+	 * and never the fallback behind an appointment that went missing. A user
+	 * with an ordinary folder called `Deleted` would otherwise lose its contents
+	 * permanently. Each of the three ways that evidence can be absent refuses
+	 * under its own reason, so the surface can name the remedy instead of
+	 * offering a silent no-op.
+	 *
+	 * Reports the rows it marked, read once here, so the number the caller shows
+	 * a user is the number this operation acted on. Pressed twice before the
+	 * worker runs it re-marks the same rows and reports the same number: the
+	 * folder really does still hold them, and the second expunge finds nothing
+	 * to do.
 	 */
 	emptyTrash = async (
 		accountConfigId: string,
 		accountId: string,
-	): Promise<void> => {
-		const trashMailbox =
-			await this.mailboxSpecialUseService.findConfirmedTrashMailbox(accountId);
+	): Promise<{ deletedCount: number }> => {
+		const trashMailbox = requireTrashMailbox(
+			await this.mailboxSpecialUseService.resolveTrashRole(accountId),
+			"confirmed",
+			accountId,
+		);
 
-		if (!trashMailbox) {
-			throw new NoTrashMailboxError(accountId);
-		}
+		// The identity the user consented to, carried on the event so the worker
+		// can tell this folder from a different one that has since taken over its
+		// path. Read here rather than re-read there: the value at consent time is
+		// the whole point, and the stored row is rewritten by every sync.
+		const { uidValidity: trashUidValidity } = await this.mailboxService.get(
+			accountId,
+			trashMailbox.mailboxId,
+		);
 
-		// Get all messages in Trash
 		const messages = await this.messageService.listAllByMailbox(
 			trashMailbox.mailboxId,
 		);
@@ -708,14 +809,18 @@ export class MessageMoveService {
 		// Enqueue single event for worker to handle batch
 		const event: EmptyTrashEvent = {
 			type: "EMPTY_TRASH",
+			schemaVersion: MUTATION_EVENT_SCHEMA_VERSION,
 			eventId: randomUUID(),
 			timestamp: Date.now(),
 			accountId,
 			trashMailboxId: trashMailbox.mailboxId,
 			trashMailboxPath: trashMailbox.fullPath,
+			trashUidValidity,
 		};
 
 		await this.enqueueEvent(event);
+
+		return { deletedCount: messages.length };
 	};
 
 	/**

package/src/spam-report.test.ts

@@ -19,6 +19,7 @@ import {
 	NoJunkMailboxError,
 	SpamReportService,
 } from "./spam-report.js";
+import { trashRole } from "./test-helpers/folder-roles.js";
 
 const ACCOUNT = "acc-1";
 const ACCOUNT_CONFIG = "cfg-1";
@@ -233,6 +234,7 @@ const buildWorld = (
 	const mailboxSpecialUseService = {
 		findJunkMailbox: async () => junkMailbox,
 		findTrashMailbox: async () => null,
+		resolveTrashRole: async () => trashRole(null),
 	} as unknown as IMailboxSpecialUseRepository;
 
 	const mailboxService = {

package/src/test-helpers/folder-roles.ts

@@ -1,4 +1,18 @@
 import type { IMailboxSpecialUseRepository } from "@remit/data-ports";
+import type { RoleResolution } from "@remit/data-ports/folder-role";
+
+type RoleMailbox = { mailboxId: string; fullPath: string };
+
+/**
+ * The evidence-carrying answer behind `findTrashMailbox`, so a stub that names
+ * a Trash folder answers both reads consistently. A named folder stands in as
+ * server-flagged: the suites using this are testing something other than how
+ * the role was decided.
+ */
+export const trashRole = (
+	trash: RoleMailbox | null,
+): RoleResolution<RoleMailbox> =>
+	trash ? { kind: "flagged", mailbox: trash } : { kind: "none" };
 
 /**
  * A folder-role map for an account that has appointed nothing and whose server
@@ -9,23 +23,26 @@ import type { IMailboxSpecialUseRepository } from "@remit/data-ports";
 export const noFolderRoles = {
 	findJunkMailbox: async () => null,
 	findTrashMailbox: async () => null,
+	resolveTrashRole: async () => trashRole(null),
 } as unknown as IMailboxSpecialUseRepository;
 
 /** A folder-role map naming the mailboxes that hold Junk and Trash. */
 export const folderRoles = (roles: {
 	junkMailboxId?: string;
 	trashMailboxId?: string;
-}): IMailboxSpecialUseRepository =>
-	({
+}): IMailboxSpecialUseRepository => {
+	const trash = roles.trashMailboxId
+		? { mailboxId: roles.trashMailboxId, fullPath: roles.trashMailboxId }
+		: null;
+	return {
 		findJunkMailbox: async () =>
 			roles.junkMailboxId
 				? { mailboxId: roles.junkMailboxId, fullPath: roles.junkMailboxId }
 				: null,
-		findTrashMailbox: async () =>
-			roles.trashMailboxId
-				? { mailboxId: roles.trashMailboxId, fullPath: roles.trashMailboxId }
-				: null,
-	}) as unknown as IMailboxSpecialUseRepository;
+		findTrashMailbox: async () => trash,
+		resolveTrashRole: async () => trashRole(trash),
+	} as unknown as IMailboxSpecialUseRepository;
+};
 
 /** The same account, as the resolved map `saveMessage` is handed. */
 export const NO_FOLDER_ROLES = {