@remit/mailbox-service 0.0.111 → 0.0.113

package/src/message-move.ts

@@ -1,1348 +0,0 @@
-import { randomUUID } from "node:crypto";
-import {
-	SendMessageBatchCommand,
-	SendMessageCommand,
-	type SQSClient,
-} from "@aws-sdk/client-sqs";
-import type {
-	IAddressRepository,
-	IMailboxRepository,
-	IMailboxSpecialUseRepository,
-	IMessageRepository,
-	IThreadMessageRepository,
-	MessageItem,
-} from "@remit/data-ports";
-import {
-	FolderRoleUnresolvedError,
-	MessagePlacementUnsettledError,
-} from "@remit/data-ports/errors";
-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,
-	MessageMutation,
-	MessageStatus,
-	MessageSyncStatus,
-} from "@remit/domain-enums";
-import { createQueueProducer } from "@remit/sqs-client/producer";
-import {
-	carriesForeignUid,
-	placementBindingOf,
-	waitForPlacementToSettle,
-} from "./placement-settled.js";
-
-/**
- * What a delete batch did not claim. A row whose placement changed between the
- * read that decided this delete and the mark that recorded it belongs to
- * whoever changed it (docs/architecture/imap-mutations.md R3), so this delete
- * leaves it alone — and says which, because the client removed it optimistically
- * and a row that reappears unexplained is a failure the user cannot act on.
- */
-export interface DeleteMessagesOutcome {
-	refusedMessageIds: string[];
-}
-
-/**
- * Event types for message move/delete operations.
- * These match the worker event types in remit-imap-worker/events.ts.
- */
-interface MessageDeleteEvent {
-	type: "MESSAGE_DELETE";
-	schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	messageId: string;
-	mailboxId: string;
-	mailboxPath: string;
-	uid: number;
-	operation: "move_to_trash" | "permanent_delete";
-	destinationMailboxId?: string;
-	destinationMailboxPath?: string;
-}
-
-interface MessageMoveEvent {
-	type: "MESSAGE_MOVE";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	messageId: string;
-	sourceMailboxId: string;
-	sourceMailboxPath: string;
-	destinationMailboxId: string;
-	destinationMailboxPath: string;
-	uid: number;
-}
-
-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 {
-	type: "MESSAGE_COPY";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	sourceMessageId: string;
-	newMessageId: string;
-	sourceMailboxId: string;
-	sourceMailboxPath: string;
-	destinationMailboxId: string;
-	destinationMailboxPath: string;
-	uid: number;
-}
-
-type MessageMoveQueueEvent =
-	| MessageDeleteEvent
-	| MessageMoveEvent
-	| EmptyTrashEvent
-	| MessageCopyEvent;
-
-/**
- * Logger interface
- */
-export interface MessageMoveLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-	warn?(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: MessageMoveLogger = {
-	info: () => {},
-	error: () => {},
-};
-
-/**
- * Configuration for MessageMoveService
- */
-export interface MessageMoveConfig {
-	messageService: IMessageRepository;
-	mailboxService: IMailboxRepository;
-	mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	threadMessageService: IThreadMessageRepository;
-	addressService: IAddressRepository;
-	sqsQueueUrl: string;
-	sqsEndpoint?: string;
-	logger?: MessageMoveLogger;
-	moveSettleTimeoutMs?: number;
-	moveSettlePollMs?: number;
-}
-
-const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
-const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
-
-/**
- * The account resolves no Trash folder, so a move-to-Trash delete has nowhere
- * to put the mail and an Empty Trash has nothing it may empty. A designed,
- * user-facing outcome carrying its own text and a 409 the backend returns
- * verbatim: the absence of a Trash folder is a blocker the user resolves by
- * appointing one, never a licence to expunge.
- */
-export class NoTrashMailboxError extends FolderRoleUnresolvedError {
-	name = "NoTrashMailboxError";
-
-	constructor(accountId: string) {
-		super(
-			NO_TRASH_FOLDER_REASON,
-			CanonicalMailboxRole.Trash,
-			"none",
-			accountId,
-		);
-	}
-}
-
-/**
- * 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 — raised by Empty Trash and by a delete that would
- * expunge a message already sitting in that folder.
- */
-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
- */
-export interface DeleteOptions {
-	/** Move to Trash instead of permanent delete. Default: true */
-	toTrash?: boolean;
-	/** Permanently delete even if in Trash. Default: false */
-	permanent?: boolean;
-}
-
-/**
- * Service for moving, copying, and deleting messages.
- *
- * Implements optimistic local-first pattern:
- * 1. Updates local state immediately (Message + ThreadMessage)
- * 2. Enqueues event to SQS for worker to sync to IMAP
- *
- * Following RFC 016 for message deletion and moving.
- */
-export class MessageMoveService {
-	private messageService: IMessageRepository;
-	private mailboxService: IMailboxRepository;
-	private mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	private threadMessageService: IThreadMessageRepository;
-	private addressService: IAddressRepository;
-	private sqs: SQSClient;
-	private queueUrl: string;
-	private log: MessageMoveLogger;
-	private moveSettleTimeoutMs: number;
-	private moveSettlePollMs: number;
-
-	constructor(config: MessageMoveConfig) {
-		this.messageService = config.messageService;
-		this.mailboxService = config.mailboxService;
-		this.mailboxSpecialUseService = config.mailboxSpecialUseService;
-		this.threadMessageService = config.threadMessageService;
-		this.addressService = config.addressService;
-		this.queueUrl = config.sqsQueueUrl;
-		this.log = config.logger ?? noopLogger;
-		this.moveSettleTimeoutMs =
-			config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
-		this.moveSettlePollMs =
-			config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
-
-		this.sqs = createQueueProducer({
-			queueUrl: config.sqsQueueUrl,
-			endpoint: config.sqsEndpoint,
-		});
-	}
-
-	/**
-	 * Delete a message. By default moves to Trash.
-	 *
-	 * @param messageId - Message to delete
-	 * @param accountId - Account ID
-	 * @param options - Delete options (toTrash, permanent)
-	 */
-	deleteMessage = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-		options: DeleteOptions = { toTrash: true },
-	): Promise<DeleteMessagesOutcome> =>
-		this.deleteMessages(accountConfigId, [messageId], accountId, options);
-
-	/**
-	 * Delete multiple messages using batch operations.
-	 * By default moves to Trash, unless permanent is specified or already in Trash.
-	 *
-	 * @param messageIds - Messages to delete
-	 * @param accountId - Account ID
-	 * @param options - Delete options (toTrash, permanent)
-	 */
-	deleteMessages = async (
-		accountConfigId: string,
-		messageIds: string[],
-		accountId: string,
-		options: DeleteOptions = { toTrash: true },
-	): Promise<DeleteMessagesOutcome> => {
-		if (messageIds.length === 0) return { refusedMessageIds: [] };
-
-		// Batch get all messages
-		const rows = await this.messageService.get(messageIds);
-		if (rows.length === 0) return { refusedMessageIds: [] };
-
-		// Ahead of the Trash gates below, which compare `mailboxId` against the
-		// Trash folder: an in-flight move makes that comparison answer for a
-		// folder the message has not reached.
-		const messages = await this.settledPlacements(rows, accountId);
-
-		// Get unique mailbox IDs and batch fetch mailboxes
-		const uniqueMailboxIds = [...new Set(messages.map((m) => m.mailboxId))];
-		const mailboxes = await this.mailboxService.get(
-			accountId,
-			uniqueMailboxIds,
-		);
-		const mailboxMap = new Map(mailboxes.map((m) => [m.mailboxId, m]));
-
-		// A permanent delete is only ever what the caller explicitly asked for.
-		// Everything else is a move to Trash, and a Trash folder that does not
-		// resolve blocks it — the user was asked "move to Trash?" and expunging
-		// their mail instead is unrecoverable and answers a question nobody put
-		// to them. Thrown before any local write or event, so the server and the
-		// projection are both left untouched.
-		const wantsPermanentDelete =
-			options.permanent === true || options.toTrash === false;
-
-		const trashResolution = wantsPermanentDelete
-			? null
-			: await this.mailboxSpecialUseService.resolveTrashRole(accountId);
-
-		const trashGate = trashResolution
-			? trashMailboxAt(trashResolution, "resolved")
-			: null;
-
-		if (trashGate && !trashGate.allowed) {
-			this.log.error(
-				{ accountId, messageCount: messages.length, reason: trashGate.reason },
-				"Refused to delete: this account's Trash is unresolved",
-			);
-			throw trashRefusal(trashGate.reason, accountId);
-		}
-
-		const trashMailbox = trashGate ? trashGate.mailbox : null;
-
-		// A message already sitting in the folder resolved as Trash deletes by
-		// expunging it, not by moving it — the same unrecoverable act Empty
-		// Trash performs, so it demands the same confirmed evidence. The name
-		// guess ("resolved") is enough to file mail into; it is never enough to
-		// destroy mail that is already there. Checked once, before any local
-		// write, so a batch that touches such a message is refused whole rather
-		// than partially expunged.
-		if (!wantsPermanentDelete && trashResolution && trashMailbox) {
-			const deletesInPlace = messages.some(
-				(message) => message.mailboxId === trashMailbox.mailboxId,
-			);
-
-			if (deletesInPlace) {
-				const confirmedTrashGate = trashMailboxAt(trashResolution, "confirmed");
-				if (!confirmedTrashGate.allowed) {
-					this.log.error(
-						{
-							accountId,
-							messageCount: messages.length,
-							reason: confirmedTrashGate.reason,
-						},
-						"Refused to delete: this account's Trash is not confirmed",
-					);
-					throw trashRefusal(confirmedTrashGate.reason, accountId);
-				}
-			}
-		}
-
-		// Group messages by operation type
-		type DeleteEntry = {
-			messageId: string;
-			message: { mailboxId: string; uid: number };
-			sourceMailbox: { mailboxId: string; fullPath: string };
-		};
-		const moveToTrashMessages: DeleteEntry[] = [];
-		const permanentDeleteMessages: DeleteEntry[] = [];
-
-		// Rows whose placement changed between the read above and the mark below,
-		// so this delete never claimed them. Reported rather than skipped in
-		// silence: the client removed them optimistically, and a row that
-		// reappears with nothing said is the dead-button failure again (#1229).
-		const refused: string[] = [];
-
-		for (const message of messages) {
-			const sourceMailbox = mailboxMap.get(message.mailboxId);
-			if (!sourceMailbox) {
-				// The folder lookup is scoped to one account, so a selection that
-				// spans accounts — the daily brief lists every account's mail —
-				// leaves this row's mailbox unresolved. Nothing about it was
-				// written and no event was enqueued, so it is a refusal like any
-				// other; dropping it silently answered "deleted" over a message
-				// still sitting where it was.
-				refused.push(message.messageId);
-				this.log.info(
-					{ accountId, messageId: message.messageId },
-					"Refused delete: this message's folder does not belong to this account",
-				);
-				continue;
-			}
-
-			const isInTrash =
-				trashMailbox !== null && message.mailboxId === trashMailbox.mailboxId;
-			const shouldMoveToTrash = trashMailbox !== null && !isInTrash;
-
-			const entry = {
-				messageId: message.messageId,
-				message: { mailboxId: message.mailboxId, uid: message.uid },
-				sourceMailbox: {
-					mailboxId: sourceMailbox.mailboxId,
-					fullPath: sourceMailbox.fullPath,
-				},
-			};
-
-			if (shouldMoveToTrash) {
-				moveToTrashMessages.push(entry);
-			} else {
-				permanentDeleteMessages.push(entry);
-			}
-		}
-
-		// Collect all events for batch SQS send
-		const events: MessageDeleteEvent[] = [];
-
-		// Process move to trash
-		if (trashMailbox && moveToTrashMessages.length > 0) {
-			// Every message in the batch shares the config, so its Junk and Trash
-			// folders resolve once rather than once per message.
-			const configJunkRoles =
-				await this.mailboxSpecialUseService.resolveJunkRolesForConfig(
-					accountConfigId,
-				);
-			for (const { messageId, message, sourceMailbox } of moveToTrashMessages) {
-				// The optimistic write is a transition off the row this call read
-				// (imap-mutations R3). Several folder lookups stand between the read
-				// and here, and PLACEMENT_MOVE_PUSH runs on a queue this account's
-				// FIFO group does not order, so the row can settle onto a different
-				// folder and uid in between. Writing anyway would stamp `moving` and
-				// the OLD uid over the new placement, and the event enqueued below
-				// would name a uid the source no longer holds — a delete aimed at
-				// whatever message has since taken that number.
-				const marked = await this.messageService.transitionPlacement(
-					messageId,
-					{
-						// `active`, not whatever the row was read as: a row already
-						// `moving` or `deleting` is mid-mutation, and marking it again
-						// would enqueue a second event against the same uid.
-						status: MessageStatus.active,
-						mailboxId: message.mailboxId,
-						uid: message.uid,
-					},
-					{
-						mailboxId: trashMailbox.mailboxId,
-						status: MessageStatus.moving,
-						syncStatus: MessageSyncStatus.pending,
-						abandonedMutation: MessageMutation.none,
-						originalMailboxId: sourceMailbox.mailboxId,
-						originalUid: message.uid,
-					},
-				);
-				if (!marked) {
-					refused.push(messageId);
-					this.log.info(
-						{ accountId, messageId },
-						"Refused delete: this message's placement changed after it was read",
-					);
-					continue;
-				}
-
-				// Update ThreadMessage
-				await this.updateThreadMessageForMove(
-					accountConfigId,
-					messageId,
-					trashMailbox.mailboxId,
-					true,
-				);
-
-				await this.addressService.reconcileJunkOnlyForMessage(
-					messageId,
-					configJunkRoles,
-				);
-
-				events.push({
-					type: "MESSAGE_DELETE",
-					schemaVersion: MUTATION_EVENT_SCHEMA_VERSION,
-					eventId: randomUUID(),
-					timestamp: Date.now(),
-					accountId,
-					messageId,
-					mailboxId: sourceMailbox.mailboxId,
-					mailboxPath: sourceMailbox.fullPath,
-					uid: message.uid,
-					operation: "move_to_trash",
-					destinationMailboxId: trashMailbox.mailboxId,
-					destinationMailboxPath: trashMailbox.fullPath,
-				});
-			}
-
-			this.log.info(
-				{
-					count: moveToTrashMessages.length,
-					trashMailboxId: trashMailbox.mailboxId,
-				},
-				"Moved messages to trash (local)",
-			);
-		}
-
-		// Process permanent deletes
-		for (const {
-			messageId,
-			message,
-			sourceMailbox,
-		} of permanentDeleteMessages) {
-			// A transition off the row this call read, like the trash path above
-			// (imap-mutations R3). The expunge below is aimed at a specific uid in
-			// a specific folder, so a row that has moved since the read must not be
-			// marked for it: a restore out of Trash settling in between would be
-			// overwritten with `deleting`, and the event would carry the uid Trash
-			// no longer holds.
-			const marked = await this.messageService.transitionPlacement(
-				messageId,
-				{
-					// `active` for the same reason as the trash path above: a second
-					// press on a row already `deleting` would enqueue a duplicate
-					// expunge rather than refusing.
-					status: MessageStatus.active,
-					mailboxId: message.mailboxId,
-					uid: message.uid,
-				},
-				{
-					status: MessageStatus.deleting,
-					syncStatus: MessageSyncStatus.pending,
-					abandonedMutation: MessageMutation.none,
-				},
-			);
-			if (!marked) {
-				refused.push(messageId);
-				this.log.info(
-					{ accountId, messageId },
-					"Refused permanent delete: this message's placement changed after it was read",
-				);
-				continue;
-			}
-
-			// Delete ThreadMessage rows up-front (one row per mailbox copy).
-			// The IMAP worker also deletes them once the IMAP DELETE succeeds —
-			// doing it eagerly here closes the visibility window where the inbox
-			// list shows a row whose backing Message is being deleted, leading
-			// to "Message not found: <id>" on click. See issue #212.
-			await this.deleteThreadMessagesForMessage(accountConfigId, messageId);
-
-			events.push({
-				type: "MESSAGE_DELETE",
-				schemaVersion: MUTATION_EVENT_SCHEMA_VERSION,
-				eventId: randomUUID(),
-				timestamp: Date.now(),
-				accountId,
-				messageId,
-				mailboxId: sourceMailbox.mailboxId,
-				mailboxPath: sourceMailbox.fullPath,
-				uid: message.uid,
-				operation: "permanent_delete",
-			});
-		}
-
-		if (permanentDeleteMessages.length > 0) {
-			this.log.info(
-				{ count: permanentDeleteMessages.length },
-				"Marked messages for permanent deletion (local)",
-			);
-		}
-
-		// Batch send events to SQS
-		await this.enqueueEventsBatch(events);
-
-		return { refusedMessageIds: refused };
-	};
-
-	/**
-	 * Move a message to another mailbox.
-	 *
-	 * Waits, never reconciles (imap-mutations R2): the folder and uid go to the
-	 * server as one pair, and once the worker has moved the destination's own
-	 * message at that uid there is no reference left to repair. The person is
-	 * looking at the result, so blocking for the sub-second a move takes is the
-	 * cheap half; on timeout the move refuses ahead of any local write.
-	 *
-	 * @param messageId - Message to move
-	 * @param destinationMailboxId - Destination mailbox ID
-	 * @param accountId - Account ID
-	 */
-	moveMessage = async (
-		accountConfigId: string,
-		messageId: string,
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<void> => {
-		await this.moveSettledMessage(
-			accountConfigId,
-			await this.settledPlacement(
-				await this.messageService.get(messageId),
-				accountId,
-			),
-			destinationMailboxId,
-			accountId,
-		);
-	};
-
-	private moveSettledMessage = async (
-		accountConfigId: string,
-		message: MessageItem,
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<void> => {
-		const messageId = message.messageId;
-
-		// IMAP has no same-mailbox MOVE: the server copies the message, expunges
-		// the original and hands back a fresh UID, so a request that asks for the
-		// mailbox the message is already in destroys its identity to reach the
-		// state it was already in. The requested end state holds, so there is
-		// nothing to record as pending and nothing to enqueue. The row is settled
-		// by the time this compares, so the folder it names is one the message has
-		// actually reached rather than one an in-flight move wrote optimistically.
-		if (message.mailboxId === destinationMailboxId) {
-			this.log.info(
-				{ messageId, mailboxId: destinationMailboxId },
-				"Skipping move: message is already in the destination mailbox",
-			);
-			return;
-		}
-
-		const sourceMailbox = await this.mailboxService.get(
-			accountId,
-			message.mailboxId,
-		);
-		const destinationMailbox = await this.mailboxService.get(
-			accountId,
-			destinationMailboxId,
-		);
-
-		// Check if moving to/from Trash
-		const trashMailbox =
-			await this.mailboxSpecialUseService.findTrashMailbox(accountId);
-		const isMovingToTrash = Boolean(
-			trashMailbox && destinationMailboxId === trashMailbox.mailboxId,
-		);
-		const isMovingFromTrash = Boolean(
-			trashMailbox && message.mailboxId === trashMailbox.mailboxId,
-		);
-
-		// The optimistic write is a transition off the row this call read
-		// (imap-mutations R3). Three mailbox lookups stand between the read and
-		// here, and PLACEMENT_MOVE_PUSH runs on a queue this account's FIFO group
-		// does not order, so the row can settle onto a different folder and uid in
-		// between. A blind write would stamp `moving` and the OLD uid over that
-		// placement, leaving a pair `carriesForeignUid` calls consistent, and the
-		// event below would send the worker after whatever now holds the old uid.
-		const moved = await this.messageService.transitionPlacement(
-			messageId,
-			{
-				status: MessageStatus.active,
-				mailboxId: message.mailboxId,
-				uid: message.uid,
-			},
-			{
-				mailboxId: destinationMailboxId,
-				status: MessageStatus.moving,
-				syncStatus: MessageSyncStatus.pending,
-				abandonedMutation: MessageMutation.none,
-				originalMailboxId: sourceMailbox.mailboxId,
-				originalUid: message.uid,
-			},
-		);
-		if (!moved) {
-			this.log.error(
-				{ accountId, messageId, destinationMailboxId },
-				"Refused: this message's placement changed while the move was being prepared",
-			);
-			throw new MessagePlacementUnsettledError(
-				`Message ${messageId} was not moved: something else changed where it is while this move was being prepared`,
-				accountId,
-				messageId,
-				"in_flight",
-			);
-		}
-
-		// Update ThreadMessage
-		await this.updateThreadMessageForMove(
-			accountConfigId,
-			messageId,
-			destinationMailboxId,
-			isMovingToTrash,
-		);
-
-		await this.addressService.reconcileJunkOnlyForMessage(
-			messageId,
-			await this.mailboxSpecialUseService.resolveJunkRolesForConfig(
-				accountConfigId,
-			),
-		);
-
-		// If moving FROM Trash, clear isDeleted
-		if (isMovingFromTrash) {
-			await this.updateThreadMessageDeleted(accountConfigId, messageId, false);
-		}
-
-		this.log.info(
-			{
-				messageId,
-				from: sourceMailbox.fullPath,
-				to: destinationMailbox.fullPath,
-			},
-			"Moved message (local)",
-		);
-
-		// Enqueue IMAP sync
-		const event: MessageMoveEvent = {
-			type: "MESSAGE_MOVE",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			accountId,
-			messageId,
-			sourceMailboxId: sourceMailbox.mailboxId,
-			sourceMailboxPath: sourceMailbox.fullPath,
-			destinationMailboxId,
-			destinationMailboxPath: destinationMailbox.fullPath,
-			uid: message.uid,
-		};
-
-		await this.enqueueEvent(event);
-	};
-
-	/**
-	 * Move multiple messages to another mailbox.
-	 *
-	 * @param messageIds - Messages to move
-	 * @param destinationMailboxId - Destination mailbox ID
-	 * @param accountId - Account ID
-	 */
-	moveMessages = async (
-		accountConfigId: string,
-		messageIds: string[],
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<void> => {
-		// Every row is settled before the first move is written, so the batch's
-		// wait is one row's ceiling rather than the sum across it, and a refusal
-		// lands before any part of the batch has committed.
-		const sources = await this.settledPlacements(
-			await this.messageService.get(messageIds),
-			accountId,
-		);
-
-		for (const source of sources) {
-			await this.moveSettledMessage(
-				accountConfigId,
-				source,
-				destinationMailboxId,
-				accountId,
-			);
-		}
-	};
-
-	/**
-	 * Copy a message to another mailbox.
-	 * Creates a new message record locally and enqueues IMAP COPY.
-	 *
-	 * @param messageId - Message to copy
-	 * @param destinationMailboxId - Destination mailbox ID
-	 * @param accountId - Account ID
-	 * @returns The new message ID for the copy
-	 */
-	copyMessage = async (
-		accountConfigId: string,
-		messageId: string,
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<string> => {
-		return this.copySettledMessage(
-			accountConfigId,
-			await this.settledPlacement(
-				await this.messageService.get(messageId),
-				accountId,
-			),
-			destinationMailboxId,
-			accountId,
-		);
-	};
-
-	private copySettledMessage = async (
-		accountConfigId: string,
-		sourceMessage: MessageItem,
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<string> => {
-		const messageId = sourceMessage.messageId;
-		const sourceMailbox = await this.mailboxService.get(
-			accountId,
-			sourceMessage.mailboxId,
-		);
-		const destinationMailbox = await this.mailboxService.get(
-			accountId,
-			destinationMailboxId,
-		);
-
-		// Deterministic identity for the copy: derived from the source message and
-		// the destination mailbox, so a replayed COPY event or a repeated copy
-		// resolves to the same row instead of a fresh unreachable duplicate. A
-		// random id (the prior behaviour) left rows no sync or delete could reach
-		// (issue #75).
-		const newMessageId = deriveCopyMessageId(messageId, destinationMailboxId);
-
-		// Upsert, not create: the id is deterministic, so a repeated copy or a
-		// retry after a partial failure (row written, event never delivered)
-		// re-derives the same id. create throws on the existing row and strands
-		// the copy at uid=0 with an undelivered event; upsert no-ops on the row
-		// and lets the event be re-enqueued below, keeping the operation
-		// idempotent and the copy re-drivable (issue #75).
-		await this.messageService.upsert({
-			messageId: newMessageId,
-			mailboxId: destinationMailboxId,
-			uid: 0, // Will be updated by worker after IMAP COPY
-			sequenceNumber: 0, // Will be updated by worker
-			rfc822Size: sourceMessage.rfc822Size,
-			internalDate: sourceMessage.internalDate,
-			messageIdHeader: sourceMessage.messageIdHeader,
-			envelopeId: sourceMessage.envelopeId, // Share envelope with source
-			rootBodyPartId: sourceMessage.rootBodyPartId, // Share body parts with source
-			status: MessageStatus.moving,
-			syncStatus: MessageSyncStatus.pending,
-			bodyStorageKey: sourceMessage.bodyStorageKey,
-			// The copy inherits the source's stored body, so body-sync's skip guard
-			// will never re-derive these. Carry them across or the copy is
-			// permanently `uncategorized` while its body says it is fully synced
-			// (issue #45).
-			category: sourceMessage.category,
-			// The record of whether that category was the classifier's answer travels
-			// with it (issue #331). Defaulting the copy to `NotExamined` would put a
-			// row no classifier will ever reach — its body is already stored — into
-			// the cohort a backfill selects as never examined.
-			classificationState: sourceMessage.classificationState,
-			hasListUnsubscribe: sourceMessage.hasListUnsubscribe,
-		});
-
-		// Copy ThreadMessage entry
-		const sourceThreadMessage = await this.threadMessageService.getByMessageId(
-			accountConfigId,
-			messageId,
-		);
-
-		await this.threadMessageService.create({
-			accountConfigId: sourceThreadMessage.accountConfigId,
-			threadId: sourceThreadMessage.threadId,
-			messageId: newMessageId,
-			mailboxId: destinationMailboxId,
-			uid: 0, // Will be updated by worker
-			messageIdHeader: sourceThreadMessage.messageIdHeader,
-			inReplyTo: sourceThreadMessage.inReplyTo,
-			referenceOrder: sourceThreadMessage.referenceOrder,
-			fromEmail: sourceThreadMessage.fromEmail,
-			fromName: sourceThreadMessage.fromName,
-			subject: sourceThreadMessage.subject,
-			internalDate: sourceThreadMessage.internalDate,
-			sentDate: sourceThreadMessage.sentDate,
-			isRead: sourceThreadMessage.isRead,
-			hasAttachment: sourceThreadMessage.hasAttachment,
-			star: sourceThreadMessage.star,
-			hasStars: sourceThreadMessage.hasStars,
-			isDeleted: false,
-			snippet: sourceThreadMessage.snippet,
-			category: sourceThreadMessage.category,
-			// Same reason as `category` above, and the same source row: the copy
-			// inherits a stored body, so no classifying pass ever runs over it to
-			// derive a `listId` of its own (issue #331).
-			listId: sourceThreadMessage.listId,
-		});
-
-		this.log.info(
-			{
-				sourceMessageId: messageId,
-				newMessageId,
-				from: sourceMailbox.fullPath,
-				to: destinationMailbox.fullPath,
-			},
-			"Created message copy (local)",
-		);
-
-		// Enqueue IMAP sync
-		const event: MessageCopyEvent = {
-			type: "MESSAGE_COPY",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			accountId,
-			sourceMessageId: messageId,
-			newMessageId,
-			sourceMailboxId: sourceMailbox.mailboxId,
-			sourceMailboxPath: sourceMailbox.fullPath,
-			destinationMailboxId,
-			destinationMailboxPath: destinationMailbox.fullPath,
-			uid: sourceMessage.uid,
-		};
-
-		await this.enqueueEvent(event);
-
-		return newMessageId;
-	};
-
-	/**
-	 * Copy multiple messages to another mailbox.
-	 *
-	 * @param messageIds - Messages to copy
-	 * @param destinationMailboxId - Destination mailbox ID
-	 * @param accountId - Account ID
-	 * @returns Array of new message IDs for the copies
-	 */
-	copyMessages = async (
-		accountConfigId: string,
-		messageIds: string[],
-		destinationMailboxId: string,
-		accountId: string,
-	): Promise<string[]> => {
-		// Every row is settled before the first copy is written, so the batch's
-		// wait is one row's ceiling rather than the sum across it, and a refusal
-		// lands before any part of the batch has committed.
-		const sources = await this.settledPlacements(
-			await this.messageService.get(messageIds),
-			accountId,
-		);
-
-		const newMessageIds: string[] = [];
-		for (const source of sources) {
-			newMessageIds.push(
-				await this.copySettledMessage(
-					accountConfigId,
-					source,
-					destinationMailboxId,
-					accountId,
-				),
-			);
-		}
-		return newMessageIds;
-	};
-
-	/**
-	 * Restore a message from Trash to its original mailbox.
-	 *
-	 * @param messageId - Message to restore
-	 * @param accountId - Account ID
-	 */
-	restoreMessage = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-	): Promise<void> => {
-		const message = await this.messageService.get(messageId);
-
-		if (!message.originalMailboxId) {
-			throw new Error("Message has no original mailbox to restore to");
-		}
-
-		await this.moveMessage(
-			accountConfigId,
-			messageId,
-			message.originalMailboxId,
-			accountId,
-		);
-	};
-
-	/**
-	 * Empty the Trash mailbox: an EXPUNGE of everything in it, with no undo.
-	 *
-	 * 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<{ deletedCount: number }> => {
-		const trashMailbox = requireTrashMailbox(
-			await this.mailboxSpecialUseService.resolveTrashRole(accountId),
-			"confirmed",
-			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,
-		);
-
-		const rows = await this.messageService.listAllByMailbox(
-			trashMailbox.mailboxId,
-		);
-
-		// Reconciles, never waits (imap-mutations R2). A row whose move into
-		// Trash has not settled names this folder while still carrying the SOURCE
-		// folder's uid, and marking it `deleting` overwrites the only marker that
-		// says so: its own MESSAGE_MOVE then reads the row as settled and returns
-		// without moving anything, and the worker's expunge binds that borrowed
-		// uid against whatever Trash really holds at it. Left as it stands, that
-		// move settles the row on its own, so the message is in Trash by the time
-		// the sweep reaches it and goes with the rest of this same press — only
-		// the count below is one short of what the sweep ends up removing.
-		//
-		// `carriesForeignUid`, the same predicate the sweep applies (#1217).
-		// The binding form reads `status` too, and `status` is exactly what this
-		// mark is about to overwrite, so the two halves of one gate would have
-		// disagreed the moment the mark landed.
-		const candidates = rows.filter((message) => !carriesForeignUid(message));
-
-		// Each mark is a transition off the row as it was just read
-		// (imap-mutations R3), not a blind write onto a snapshot. The rows are
-		// held by nothing between the listing and here, and PLACEMENT_MOVE_PUSH
-		// runs on a standard queue that this account's FIFO group does not order,
-		// so a row can move out from under the sweep. A lost predicate means
-		// another lane won: the row is left alone and not counted, rather than
-		// marked `deleting` for an expunge that would bind somebody else's uid.
-		const messages: MessageItem[] = [];
-		for (const message of candidates) {
-			const marked = await this.messageService.transitionPlacement(
-				message.messageId,
-				{
-					status: message.status,
-					mailboxId: message.mailboxId,
-					uid: message.uid,
-				},
-				{
-					status: MessageStatus.deleting,
-					syncStatus: MessageSyncStatus.pending,
-				},
-			);
-			if (!marked) {
-				this.log.info(
-					{ accountId, messageId: message.messageId },
-					"Empty Trash skipped a message whose placement changed while the folder was being read",
-				);
-				continue;
-			}
-			messages.push(marked);
-			await this.updateThreadMessageDeleted(
-				accountConfigId,
-				message.messageId,
-				true,
-			);
-		}
-
-		this.log.info(
-			{
-				accountId,
-				trashMailboxId: trashMailbox.mailboxId,
-				count: messages.length,
-				skipped: rows.length - messages.length,
-			},
-			"Marked all trash messages for deletion (local)",
-		);
-
-		// 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 };
-	};
-
-	private refusePlacement = (
-		message: MessageItem,
-		accountId: string,
-	): never => {
-		this.log.error(
-			{ accountId, messageId: message.messageId },
-			"Refused: this message's folder and uid do not name the same message",
-		);
-		throw new MessagePlacementUnsettledError(
-			`Message ${message.messageId} was not acted on: its folder and uid do not name the same message`,
-			accountId,
-			message.messageId,
-			"in_flight",
-		);
-	};
-
-	private settledPlacement = async (
-		message: MessageItem,
-		accountId: string,
-	): Promise<MessageItem> => {
-		if (placementBindingOf(message) === "consistent") return message;
-
-		const settled = await waitForPlacementToSettle(
-			this.messageService,
-			message.messageId,
-			{
-				timeoutMs: this.moveSettleTimeoutMs,
-				pollMs: this.moveSettlePollMs,
-			},
-		);
-		if (placementBindingOf(settled) === "consistent") return settled;
-		return this.refusePlacement(settled, accountId);
-	};
-
-	/**
-	 * Settle a whole batch before any of it is acted on, so one unsettled row
-	 * refuses the batch whole rather than leaving part of it expunged, and the
-	 * batch's total wait is one row's ceiling rather than the sum across it.
-	 */
-	private settledPlacements = async (
-		messages: MessageItem[],
-		accountId: string,
-	): Promise<MessageItem[]> =>
-		Promise.all(
-			messages.map((message) => this.settledPlacement(message, accountId)),
-		);
-
-	/**
-	 * Update ThreadMessage for move operations.
-	 * Updates mailboxId and optionally isDeleted.
-	 */
-	private updateThreadMessageForMove = async (
-		accountConfigId: string,
-		messageId: string,
-		newMailboxId: string,
-		isDeleted: boolean,
-	): Promise<void> => {
-		const threadMessage = await this.threadMessageService.getByMessageId(
-			accountConfigId,
-			messageId,
-		);
-
-		this.log.info(
-			{
-				messageId,
-				accountConfigId: threadMessage.accountConfigId,
-				threadMessageId: threadMessage.threadMessageId,
-				sentDate: threadMessage.sentDate,
-				newMailboxId,
-				isDeleted,
-			},
-			"Updating ThreadMessage for move",
-		);
-
-		await this.threadMessageService.update(
-			threadMessage.accountConfigId,
-			threadMessage.threadMessageId,
-			{ mailboxId: newMailboxId, isDeleted },
-			{
-				// Composites contain CURRENT values for condition checking
-				// ElectroDB uses these to verify the item state before updating
-				composites: {
-					mailboxId: threadMessage.mailboxId,
-					sentDate: threadMessage.sentDate,
-					isRead: threadMessage.isRead,
-					isDeleted: threadMessage.isDeleted,
-					hasStars: threadMessage.hasStars,
-					hasAttachment: threadMessage.hasAttachment,
-				},
-			},
-		);
-
-		this.log.info(
-			{
-				messageId,
-				threadMessageId: threadMessage.threadMessageId,
-				newMailboxId,
-				isDeleted,
-			},
-			"Updated ThreadMessage for move",
-		);
-	};
-
-	/**
-	 * Delete every ThreadMessage row that points at this messageId.
-	 *
-	 * A row is keyed by (threadId, messageId), so this is one row in practice —
-	 * a message filed in several folders keeps a single row, because its
-	 * messageId is derived from the Message-ID header and not from the mailbox.
-	 * The query stays a list because the key permits more than one thread per
-	 * message and nothing enforces otherwise.
-	 *
-	 * Deleting up-front in the permanent-delete optimistic step prevents stale
-	 * rows from leaking into mailbox listings while IMAP catches up (#212).
-	 */
-	private deleteThreadMessagesForMessage = async (
-		accountConfigId: string,
-		messageId: string,
-	): Promise<void> => {
-		const rows = await this.threadMessageService.findAllByMessageId(
-			accountConfigId,
-			messageId,
-		);
-		for (const row of rows) {
-			await this.threadMessageService.delete(
-				row.accountConfigId,
-				row.threadMessageId,
-			);
-		}
-		this.log.info(
-			{ messageId, deletedRows: rows.length },
-			"Deleted ThreadMessage rows for permanent-delete",
-		);
-	};
-
-	/**
-	 * Update ThreadMessage.isDeleted flag only.
-	 */
-	private updateThreadMessageDeleted = async (
-		accountConfigId: string,
-		messageId: string,
-		isDeleted: boolean,
-	): Promise<void> => {
-		const threadMessage = await this.threadMessageService.getByMessageId(
-			accountConfigId,
-			messageId,
-		);
-
-		await this.threadMessageService.update(
-			threadMessage.accountConfigId,
-			threadMessage.threadMessageId,
-			{ isDeleted },
-			{
-				// Composites contain CURRENT values for condition checking
-				composites: {
-					sentDate: threadMessage.sentDate,
-					mailboxId: threadMessage.mailboxId,
-					isRead: threadMessage.isRead,
-					isDeleted: threadMessage.isDeleted,
-					hasStars: threadMessage.hasStars,
-					hasAttachment: threadMessage.hasAttachment,
-				},
-			},
-		);
-
-		this.log.info(
-			{
-				messageId,
-				threadMessageId: threadMessage.threadMessageId,
-				isDeleted,
-			},
-			"Updated ThreadMessage.isDeleted",
-		);
-	};
-
-	/**
-	 * Enqueue a message move/delete event to SQS.
-	 *
-	 * FIFO queues require MessageGroupId; standard queues reject it. We detect
-	 * FIFO queues by the `.fifo` suffix and group by accountId so events for
-	 * different accounts can be processed in parallel.
-	 */
-	private enqueueEvent = async (
-		event: MessageMoveQueueEvent,
-	): Promise<void> => {
-		const useFifo = this.queueUrl.endsWith(".fifo");
-		await this.sqs.send(
-			new SendMessageCommand({
-				QueueUrl: this.queueUrl,
-				MessageBody: JSON.stringify(event),
-				...(useFifo && {
-					MessageGroupId: event.accountId,
-					MessageDeduplicationId: event.eventId,
-				}),
-			}),
-		);
-
-		this.log.info(
-			{ eventId: event.eventId, type: event.type },
-			"Enqueued message event",
-		);
-	};
-
-	/**
-	 * Enqueue multiple events to SQS using batch send.
-	 * SQS batch limit is 10 messages, so we chunk if needed.
-	 *
-	 * FIFO queues require MessageGroupId on each batch entry; standard queues
-	 * reject it. We detect FIFO queues by the `.fifo` suffix.
-	 */
-	private enqueueEventsBatch = async (
-		events: MessageMoveQueueEvent[],
-	): Promise<void> => {
-		if (events.length === 0) return;
-
-		const SQS_BATCH_SIZE = 10;
-		const useFifo = this.queueUrl.endsWith(".fifo");
-
-		for (let i = 0; i < events.length; i += SQS_BATCH_SIZE) {
-			const batch = events.slice(i, i + SQS_BATCH_SIZE);
-			await this.sqs.send(
-				new SendMessageBatchCommand({
-					QueueUrl: this.queueUrl,
-					Entries: batch.map((event, idx) => ({
-						Id: `${i + idx}`,
-						MessageBody: JSON.stringify(event),
-						...(useFifo && {
-							MessageGroupId: event.accountId,
-							MessageDeduplicationId: event.eventId,
-						}),
-					})),
-				}),
-			);
-		}
-
-		this.log.info({ count: events.length }, "Enqueued message events batch");
-	};
-}