@remit/mailbox-service 0.0.112 → 0.0.114

package/dist/message-move.js

@@ -0,0 +1,858 @@
+import { randomUUID } from "node:crypto";
+import { QUEUE_BATCH_LIMIT, } from "@remit/data-ports";
+import { FolderRoleUnresolvedError, MessagePlacementUnsettledError, } from "@remit/data-ports/errors";
+import { NO_TRASH_FOLDER_REASON, STALE_TRASH_FOLDER_REASON, 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 { carriesForeignUid, placementBindingOf, waitForPlacementToSettle, } from "./placement-settled.js";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
+/** Undo every write whose event never left, then fail with the queue's error. */
+const handBackThenThrow = async (fault, handBacks) => {
+    const undoFaults = [];
+    for (const handBack of handBacks) {
+        await handBack().catch((undoFault) => {
+            undoFaults.push(undoFault);
+        });
+    }
+    if (undoFaults.length > 0) {
+        throw new AggregateError([fault, ...undoFaults], "The queue refused the event, and handing the local write back failed too");
+    }
+    throw fault;
+};
+const queueMessage = (event) => ({
+    body: event,
+    groupId: event.accountId,
+    deduplicationId: event.eventId,
+});
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+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) {
+        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) {
+        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) {
+        super(UNCONFIRMED_TRASH_FOLDER_REASON, CanonicalMailboxRole.Trash, "unconfirmed", accountId);
+    }
+}
+const REFUSAL_BY_REASON = {
+    none: NoTrashMailboxError,
+    stale: StaleTrashAppointmentError,
+    unconfirmed: UnconfirmedTrashMailboxError,
+};
+/** The coded 409 for one refusal reason. The only place a reason becomes an error. */
+const trashRefusal = (reason, accountId) => 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 = (resolution, level, accountId) => {
+    const outcome = trashMailboxAt(resolution, level);
+    if (outcome.allowed)
+        return outcome.mailbox;
+    throw trashRefusal(outcome.reason, accountId);
+};
+/**
+ * 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 {
+    messageService;
+    mailboxService;
+    mailboxSpecialUseService;
+    threadMessageService;
+    addressService;
+    queue;
+    log;
+    moveSettleTimeoutMs;
+    moveSettlePollMs;
+    constructor(config) {
+        this.messageService = config.messageService;
+        this.mailboxService = config.mailboxService;
+        this.mailboxSpecialUseService = config.mailboxSpecialUseService;
+        this.threadMessageService = config.threadMessageService;
+        this.addressService = config.addressService;
+        this.queue = config.queue;
+        this.log = config.logger ?? noopLogger;
+        this.moveSettleTimeoutMs =
+            config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
+        this.moveSettlePollMs =
+            config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
+    }
+    /**
+     * 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, messageId, accountId, options = { toTrash: true }) => 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, messageIds, accountId, options = { toTrash: true }) => {
+        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);
+                }
+            }
+        }
+        const moveToTrashMessages = [];
+        const permanentDeleteMessages = [];
+        // 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 = [];
+        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 = [];
+        // 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({
+                    event: {
+                        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,
+                    },
+                    handBack: () => this.handBackUnsentMove(accountConfigId, messageId, sourceMailbox.mailboxId, message.uid),
+                });
+            }
+            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({
+                event: {
+                    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",
+                },
+                // The listing rows went above, so the local removal finishes, as the
+                // worker's `handBackDelete` does; the folder's next sync re-projects it.
+                handBack: async () => {
+                    const claimed = await this.messageService.transitionPlacement(messageId, {
+                        status: MessageStatus.deleting,
+                        mailboxId: message.mailboxId,
+                        uid: message.uid,
+                    }, { status: MessageStatus.deleted });
+                    if (claimed)
+                        await this.messageService.delete(messageId);
+                },
+            });
+        }
+        if (permanentDeleteMessages.length > 0) {
+            this.log.info({ count: permanentDeleteMessages.length }, "Marked messages for permanent deletion (local)");
+        }
+        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, messageId, destinationMailboxId, accountId) => {
+        await this.moveSettledMessage(accountConfigId, await this.settledPlacement(await this.messageService.get(messageId), accountId), destinationMailboxId, accountId);
+    };
+    moveSettledMessage = async (accountConfigId, message, destinationMailboxId, accountId) => {
+        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 = {
+            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, () => this.handBackUnsentMove(accountConfigId, messageId, sourceMailbox.mailboxId, message.uid));
+    };
+    /**
+     * Move multiple messages to another mailbox.
+     *
+     * @param messageIds - Messages to move
+     * @param destinationMailboxId - Destination mailbox ID
+     * @param accountId - Account ID
+     */
+    moveMessages = async (accountConfigId, messageIds, destinationMailboxId, accountId) => {
+        // 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, messageId, destinationMailboxId, accountId) => {
+        return this.copySettledMessage(accountConfigId, await this.settledPlacement(await this.messageService.get(messageId), accountId), destinationMailboxId, accountId);
+    };
+    copySettledMessage = async (accountConfigId, sourceMessage, destinationMailboxId, accountId) => {
+        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).
+        const copyRow = await this.messageService.upsertWithStatus({
+            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,
+            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,
+        });
+        await this.messageService.copySearchText(messageId, newMessageId);
+        // Copy ThreadMessage entry
+        const sourceThreadMessage = await this.threadMessageService.getByMessageId(accountConfigId, messageId);
+        const copyListing = 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 = {
+            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, async () => {
+            await this.threadMessageService.deleteMany([
+                {
+                    accountConfigId: copyListing.accountConfigId,
+                    threadMessageId: copyListing.threadMessageId,
+                },
+            ]);
+            if (!copyRow.created)
+                return;
+            await this.messageService.deleteIfPlacement(newMessageId, {
+                status: MessageStatus.moving,
+                mailboxId: destinationMailboxId,
+                uid: 0,
+            });
+        });
+        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, messageIds, destinationMailboxId, accountId) => {
+        // 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 = [];
+        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, messageId, accountId) => {
+        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, accountId) => {
+        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 = [];
+        const undo = [];
+        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);
+            const wasDeleted = await this.updateThreadMessageDeleted(accountConfigId, message.messageId, true);
+            undo.push(async () => {
+                const restored = await this.messageService.transitionPlacement(message.messageId, {
+                    status: MessageStatus.deleting,
+                    mailboxId: message.mailboxId,
+                    uid: message.uid,
+                }, { status: message.status, syncStatus: message.syncStatus });
+                if (restored && !wasDeleted) {
+                    await this.updateThreadMessageDeleted(accountConfigId, message.messageId, false);
+                }
+            });
+        }
+        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 = {
+            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, async () => {
+            for (const restore of undo)
+                await restore();
+        });
+        return { deletedCount: messages.length };
+    };
+    refusePlacement = (message, accountId) => {
+        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");
+    };
+    settledPlacement = async (message, accountId) => {
+        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.
+     */
+    settledPlacements = async (messages, accountId) => Promise.all(messages.map((message) => this.settledPlacement(message, accountId)));
+    /**
+     * Update ThreadMessage for move operations.
+     * Updates mailboxId and optionally isDeleted.
+     */
+    updateThreadMessageForMove = async (accountConfigId, messageId, newMailboxId, isDeleted) => {
+        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).
+     */
+    deleteThreadMessagesForMessage = async (accountConfigId, messageId) => {
+        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.
+     */
+    updateThreadMessageDeleted = async (accountConfigId, messageId, isDeleted) => {
+        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");
+        return threadMessage.isDeleted;
+    };
+    /**
+     * Enqueue a message move/delete event, grouped by accountId so events for
+     * different accounts can be processed in parallel.
+     */
+    enqueueEvent = async (event, handBack) => {
+        await this.queue
+            .send(queueMessage(event))
+            .catch((fault) => handBackThenThrow(fault, [handBack]));
+        this.log.info({ eventId: event.eventId, type: event.type }, "Enqueued message event");
+    };
+    /**
+     * Enqueue multiple events in batches of at most {@link QUEUE_BATCH_LIMIT}.
+     */
+    enqueueEventsBatch = async (events) => {
+        const enqueued = await this.sendEventsBatch(events);
+        if (enqueued.outcome === "sent")
+            return;
+        await handBackThenThrow(enqueued.fault, enqueued.unsent.map(({ handBack }) => handBack));
+    };
+    // A batch send can succeed while refusing some of its entries.
+    sendEventsBatch = async (events) => {
+        for (let i = 0; i < events.length; i += QUEUE_BATCH_LIMIT) {
+            const batch = events.slice(i, i + QUEUE_BATCH_LIMIT);
+            const sent = await this.queue
+                .sendBatch(batch.map(({ event }) => queueMessage(event)))
+                .then((result) => ({ refused: result.refused }), (fault) => ({ fault }));
+            if ("fault" in sent) {
+                return {
+                    outcome: "unsent",
+                    unsent: events.slice(i),
+                    fault: sent.fault,
+                };
+            }
+            if (sent.refused.size > 0) {
+                const refused = batch.filter((_, idx) => sent.refused.has(idx));
+                return {
+                    outcome: "unsent",
+                    unsent: [...refused, ...events.slice(i + QUEUE_BATCH_LIMIT)],
+                    fault: new Error(`The queue refused ${refused.length} of ${events.length} delete event(s)`),
+                };
+            }
+        }
+        if (events.length > 0) {
+            this.log.info({ count: events.length }, "Enqueued message events batch");
+        }
+        return { outcome: "sent" };
+    };
+    handBackUnsentMove = async (accountConfigId, messageId, sourceMailboxId, uid) => {
+        await restoreSourcePlacement({
+            messageService: this.messageService,
+            threadMessageService: this.threadMessageService,
+        }, {
+            accountConfigId,
+            messageId,
+            sourceMailboxId,
+            uid,
+            syncStatus: MessageSyncStatus.synced,
+            abandonedMutation: MessageMutation.none,
+        });
+        await this.addressService.reconcileJunkOnlyForMessage(messageId, await this.mailboxSpecialUseService.resolveJunkRolesForConfig(accountConfigId));
+    };
+}