@remit/imap-worker 0.0.90 → 0.0.91

package/dist/handlers/message-delete.js

@@ -0,0 +1,520 @@
+import { isAcceptedSchemaVersion } from "@remit/data-ports/mutation-events";
+import { MessageMutation, MessageStatus, MessageSyncStatus, } from "@remit/domain-enums";
+import { buildThreadMessageTrashUpdate, guardConnectionCursor, isCursorRebuildNeeded, isMessageGoneFromOpenMailbox, MailboxCursorPausedError, restoreSourcePlacement, } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { emitFrom } from "../emit.js";
+import { findMailboxRow } from "../mailbox-row.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+import { resolveExhaustedMessageDeleteFailure } from "./message-delete-terminal.js";
+import { emitMailboxResync, emitMoveResync, probePausedPlacement, searchMailboxForHighestMessageIdUid, } from "./message-move.js";
+import { probeableMessageIdHeader } from "./probe-message-id.js";
+/**
+ * Delete every ThreadMessage row that points at this messageId.
+ *
+ * A single Message can have multiple ThreadMessage rows — one per mailbox
+ * the message exists in (e.g. INBOX + a label/folder copy). Permanent-delete
+ * cleanup must remove ALL of them; using `findByMessageId` (single row) leaves
+ * orphan rows in other mailboxes that then leak into their listings. See
+ * issue #212.
+ */
+export const deleteAllThreadMessagesForMessage = async (threadMessageService, accountConfigId, messageId) => {
+    const rows = await threadMessageService.findAllByMessageId(accountConfigId, messageId);
+    for (const row of rows) {
+        await threadMessageService.delete(row.accountConfigId, row.threadMessageId);
+    }
+    return rows.length;
+};
+const confirmTrashMoveUid = async (sourceConnection, destinationConnection, messageService, threadMessageService, accountConfigId, messageId, sourceMailboxPath, destinationMailboxPath, uid) => {
+    await sourceConnection.openBox(sourceMailboxPath, true);
+    if (!(await isMessageGoneFromOpenMailbox(sourceConnection, uid))) {
+        return { outcome: "still-at-source" };
+    }
+    const [message] = await messageService.get([messageId]);
+    if (!message)
+        return { outcome: "row-gone" };
+    const messageIdHeader = await probeableMessageIdHeader(threadMessageService, accountConfigId, messageId);
+    if (!messageIdHeader)
+        return { outcome: "unprobeable" };
+    const probedUid = await searchMailboxForHighestMessageIdUid(destinationConnection, destinationMailboxPath, messageIdHeader);
+    return probedUid === null
+        ? { outcome: "unconfirmed" }
+        : { outcome: "confirmed", uid: probedUid };
+};
+/**
+ * Handle MESSAGE_DELETE events.
+ * Either moves to Trash (IMAP MOVE) or permanently deletes (IMAP DELETE).
+ *
+ * A failing delete retries on redelivery until `receiveCount` reaches
+ * the `config.attempts.messageDelete` budget, at which point
+ * {@link resolveExhaustedMessageDeleteFailure} asks IMAP where the message
+ * actually is and settles the row into one terminal outcome (issue #980).
+ */
+export const handleMessageDelete = async (event, ctx, receiveCount) => {
+    const { log, pool, metrics, config } = ctx;
+    const emit = emitFrom(ctx);
+    const { account: accountService, message: messageService, threadMessage: threadMessageService, mailbox: mailboxService, secrets, } = ctx.client;
+    const { accountId, messageId, mailboxId, uid, operation, destinationMailboxId, } = event;
+    log.info({ event: event.type, accountId, messageId, mailboxId, operation }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    const [message] = await messageService.get([messageId]);
+    // The row is gone — a permanent delete that already ran, or a
+    // reconciliation path that removed it. Nothing left to delete; ack.
+    if (!message) {
+        log.warn({ accountId, messageId, operation }, "Skipping MESSAGE_DELETE: message row no longer exists");
+        return;
+    }
+    // This delete already settled. The guard asks for the state THIS delete
+    // wrote, the way MESSAGE_MOVE and MESSAGE_COPY ask for theirs: a move to
+    // Trash records `moving`, a permanent delete records `deleting`, and a row
+    // in the other one is a different mutation's work that this handler must
+    // not read as its own to finish.
+    //
+    // Without it a lost SQS acknowledgement re-runs the delete against a uid
+    // the source no longer holds, exhausts, and lets the terminal resolver
+    // read the source's honest "gone" as grounds to delete rows that are
+    // correct — taking spamReport, classificationState, category and the Undo
+    // target's `originalMailboxId` with them, none of which the resync
+    // re-projection can rebuild.
+    // An operation this build does not recognise gets no verdict here: it falls
+    // through to `abandonDelete` below, which is the designed refusal. Skipping
+    // it as "already settled" would swallow the very event the refusal exists to
+    // report.
+    const outstandingStatus = operation === "move_to_trash"
+        ? MessageStatus.moving
+        : operation === "permanent_delete"
+            ? MessageStatus.deleting
+            : undefined;
+    if (outstandingStatus !== undefined && message.status !== outstandingStatus) {
+        log.info({
+            accountId,
+            messageId,
+            operation,
+            uid: message.uid,
+            status: message.status,
+            syncStatus: message.syncStatus,
+        }, "Skipping MESSAGE_DELETE: the row no longer carries the mutation this event was enqueued for");
+        return;
+    }
+    /**
+     * Re-read the folders this delete touched. A move to trash has two; a
+     * permanent delete has only the source, and it is owed one just as much —
+     * the local rows are gone while the server copy survives, so with no resync
+     * the mail is invisible until the next scheduled sync. SYNC_MESSAGES on a
+     * mailbox whose cursor is not normal routes to the rebuild, which is what
+     * re-projects the rows this handler removed (`message-sync.ts`).
+     */
+    const emitSettleResync = async () => {
+        if (destinationMailboxId) {
+            await emitMoveResync(emit, {
+                accountId,
+                sourceMailboxId: mailboxId,
+                destinationMailboxId,
+            });
+            return;
+        }
+        await emitMailboxResync(emit, { accountId, mailboxId });
+    };
+    /**
+     * Undo the optimistic local delete, for every reason this handler has to
+     * give one up, and say so exactly once. The verdict differs — a refused
+     * event is a failure the row carries, a paused cursor is a mutation the
+     * server never heard of — but the way back is one rule, and it is the
+     * listing rows that pick it.
+     *
+     * Rows still there is the ordinary move to trash: the row goes back on the
+     * source pair, which is also the set the cursor rebuild adjudicates.
+     *
+     * No rows left is a permanent delete, which drops them at enqueue; they are
+     * denormalized off an envelope only the sync path shapes and cannot be
+     * rebuilt from here, so restoring the Message alone would leave mail nothing
+     * can list — the silent vanish rather than a visible failure. The local
+     * removal finishes instead. Nothing was expunged, so the server copy
+     * survives and the mailbox's own sync re-projects it.
+     *
+     * `alert` is a refusal or a placement the server never settled, both of
+     * which an operator adjudicates. `metric` is the routine pause the guard doc
+     * calls never-a-fault: the user's delete was silently dropped, worth
+     * counting and not worth waking anyone for. Either way `localRowsRemoved`
+     * keeps the disappearance of local mail visible.
+     */
+    const handBackDelete = async (syncStatus, signal, reason) => {
+        const threadMessages = await threadMessageService.findAllByMessageId(account.accountConfigId, messageId);
+        const localRowsRemoved = threadMessages.length === 0;
+        const context = {
+            ...signal,
+            accountId,
+            messageId,
+            uid,
+            mailboxId,
+            operation,
+            receiveCount,
+            reason,
+            localRowsRemoved,
+        };
+        const summary = localRowsRemoved
+            ? "Delete given up with no listing rows left to restore; the local row was removed and the server copy was not expunged"
+            : "Delete given up; the row was handed back to its source pair";
+        if ("alert" in signal) {
+            log.error(context, summary);
+        }
+        else {
+            log.warn(context, summary);
+        }
+        if (localRowsRemoved) {
+            // Removing the Message row is destructive and unpredicated on its own,
+            // so it is claimed first: the row is transitioned to `deleted` from a
+            // placement this delete actually owns, and removed only if that claim
+            // wins (imap-mutations R3). A row nothing is deleting — an unrecognised
+            // operation reaches this refusal on whatever the row happens to be —
+            // is left where it is rather than destroyed on the way past.
+            const claimed = await messageService.transitionPlacement(messageId, { status: [MessageStatus.moving, MessageStatus.deleting] }, { status: MessageStatus.deleted });
+            if (!claimed) {
+                log.warn({ ...context, status: message.status }, "Delete given up with no listing rows left, and no delete outstanding on the row; the local row was left alone");
+                return;
+            }
+            await messageService.delete(messageId);
+            return;
+        }
+        await restoreSourcePlacement({ messageService, threadMessageService }, {
+            accountConfigId: account.accountConfigId,
+            messageId,
+            sourceMailboxId: mailboxId,
+            uid,
+            syncStatus,
+            // Every hand-back this handler makes is a delete's, so the mutation
+            // follows the give-up rather than being passed in beside it.
+            abandonedMutation: syncStatus === MessageSyncStatus.abandoned
+                ? MessageMutation.delete
+                : MessageMutation.none,
+            threadMessages,
+        });
+    };
+    // Only an operation that explicitly says so destroys mail. The event is
+    // `JSON.parse`d and cast in the queue handler with no validation, so a
+    // missing, misspelled or future field must abandon the delete — the
+    // "anything that is not move_to_trash is an expunge" inference is the same
+    // one that destroyed mail in the service, and an unrecoverable EXPUNGE is
+    // not a default. Abandoning hands the row back where the server still has
+    // it: an invisible failure on a row the user cannot see is the shape of the
+    // incident this whole change is about. The row carries `abandoned` — the
+    // give-up value, not the transient one a redelivery follows (R3) — because
+    // the product refused something the user asked for and nothing is coming.
+    const abandonDelete = (reason, alert) => handBackDelete(MessageSyncStatus.abandoned, { alert }, reason);
+    const settleTrashMoveConfirmed = async (newUid, trashMailboxId) => {
+        await messageService.updateUid(messageId, newUid, trashMailboxId);
+        const threadMessage = await threadMessageService.findByMessageId(account.accountConfigId, messageId);
+        if (threadMessage) {
+            const args = buildThreadMessageTrashUpdate(threadMessage, newUid, trashMailboxId);
+            await threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, args.set, { composites: args.composites });
+        }
+        log.info({ messageId, newUid }, "Message moved to trash");
+    };
+    /**
+     * Settle the optimistic local delete when a paused cursor stops this round
+     * from issuing it. Acking on the optimistic row strands it: nothing
+     * re-enqueues a MESSAGE_DELETE, and the cursor rebuild matches rows by
+     * `(accountConfigId, mailboxId)`, so it never even sees a move-to-trash row
+     * that already names Trash (issue #1203).
+     *
+     * The delete therefore reconciles rather than waits (R2,
+     * docs/architecture/imap-mutations.md): the row is settled onto whichever
+     * pair the server can be shown to hold, and the resync plus the source's own
+     * cursor rebuild are its repair path.
+     *
+     * Undoing the local write claims nothing about the server only where the
+     * command provably never left. `commandIssued` says what this round did;
+     * `receiveCount` adds what an earlier one may have done and lost with its
+     * connection. `receiveCount === 1` alone is not that proof: an unprobeable
+     * confirmation reaches {@link settleExhaustedDelete} on the first attempt,
+     * with the MOVE already issued and the source already saying it no longer
+     * holds the message. Where either says the server may have been asked, it is
+     * asked again — {@link probePausedPlacement}, on the unguarded handle. A
+     * permanent delete has nothing to ask: its answer is the same either way,
+     * since the row is unlistable and goes.
+     */
+    const settlePausedDelete = async (getRawConnection, commandIssued, paths) => {
+        const mayHaveIssued = commandIssued || receiveCount > 1;
+        const destinationMailboxPath = paths.destination;
+        const isProbeableTrashMove = mayHaveIssued &&
+            operation === "move_to_trash" &&
+            destinationMailboxId !== undefined &&
+            destinationMailboxPath !== undefined;
+        const placement = isProbeableTrashMove
+            ? await probePausedPlacement(await getRawConnection(), {
+                messageIdHeader: await probeableMessageIdHeader(threadMessageService, account.accountConfigId, messageId),
+                sourceMailboxPath: paths.source,
+                destinationMailboxPath,
+            })
+            : { kind: "at-source" };
+        // A sighting in Trash is not proof this delete ran. The pause means the
+        // source's UIDVALIDITY has moved, so its "no" can be a recreated folder
+        // answering about mail it never held, and the hit can be an older copy of
+        // the same Message-ID — a sieve `fileinto` + `keep`, a resend — that
+        // `deriveMessageId` folds into this row; settling `moved` on it hands
+        // Empty Trash a stranger's uid. `unprobeable` is silence, and silence
+        // settles nothing either (the rule `message-copy.ts` already applies).
+        // Both hand the row back on the source pair carrying `failed`: that is the
+        // set the source's own cursor rebuild walks and adjudicates by Message-ID,
+        // which is the reconcile path (R2) Trash — not paused, no rebuild coming —
+        // does not have.
+        const unproven = placement.kind === "at-destination" || placement.kind === "unprobeable";
+        if (unproven) {
+            await handBackDelete(MessageSyncStatus.abandoned, { alert: "message_delete_paused_placement_unproven" }, placement.kind === "at-destination"
+                ? "the destination holds this Message-ID but the source's uid axis has moved, so the sighting does not prove this delete ran"
+                : "no Message-ID header to ask either folder with");
+        }
+        else {
+            // `gone` lands here with `at-source`: the source pair is the set the
+            // rebuild walks, and a row it cannot match against a fresh envelope
+            // snapshot is the one thing it reconciles away.
+            await handBackDelete(MessageSyncStatus.synced, { metric: "message_delete_dropped_on_pause" }, `source mailbox cursor paused, placement ${placement.kind}`);
+        }
+        await emitSettleResync();
+    };
+    const settleExhaustedDelete = async (accountConfigId, sourceMailboxPath, getConnection, settlePaused) => {
+        const settled = await resolveExhaustedMessageDeleteFailure({ messageService, threadMessageService, log }, {
+            placement: {
+                status: message.status,
+                mailboxId: message.mailboxId,
+                uid: message.uid,
+            },
+            accountId,
+            accountConfigId,
+            messageId,
+            sourceMailboxId: mailboxId,
+            uid,
+            sourceMailboxPath,
+            getConnection,
+        }).catch(async (settleError) => {
+            // The guarded probe found a mailbox whose UIDVALIDITY has moved. Nothing
+            // may be settled off a uid on a dead axis, and the pause is the routine
+            // skip `guardMailboxCursor` documents, not a fault to re-throw out of
+            // the caller's catch. The delete is still settled, on the identity axis
+            // instead: the paused settle asks by Message-ID, which a UIDVALIDITY
+            // change does not invalidate.
+            if (settleError instanceof MailboxCursorPausedError) {
+                log.info({ accountId, messageId, mailboxId, cursorState: settleError.state }, "Mailbox cursor not normal; settling the exhausted delete against the server by Message-ID");
+                await settlePaused();
+                return null;
+            }
+            throw settleError;
+        });
+        if (!settled)
+            return;
+        if (settled.outcome === "broken") {
+            metrics.imapFailure("MESSAGE_DELETE_EXHAUSTED", "other", 1);
+        }
+        // Both verdicts end in a row the server has contradicted, so this delete
+        // reconciles rather than waits (R2): whichever folder actually holds the
+        // message re-projects it with the server's own uid. RECONCILED, the local
+        // rows are gone and the resync rebuilds them. BROKEN, the row has just
+        // been put back at the source the server confirmed, and the resync is
+        // what carries any drift either folder has picked up since.
+        await emitSettleResync();
+    };
+    /**
+     * Decide what an unconfirmed move to Trash does with this delivery. The
+     * settle itself is `resolveExhaustedMessageDeleteFailure`, reached through
+     * the attempt budget in the catch below — the two verdicts handled here are
+     * the ones a redelivery could never answer.
+     */
+    const settleUnconfirmedTrashMove = async (confirmation, accountConfigId, sourceMailboxPath, getConnection, settlePaused) => {
+        const context = {
+            accountId,
+            accountConfigId,
+            messageId,
+            uid,
+            mailboxId,
+            receiveCount,
+            confirmation: confirmation.outcome,
+        };
+        if (confirmation.outcome === "row-gone") {
+            log.warn(context, "Move to trash unconfirmed and the local row is already gone; nothing left to settle");
+            return;
+        }
+        if (confirmation.outcome === "unprobeable") {
+            metrics.imapFailure("MESSAGE_DELETE_TRASH_MOVE_UNCONFIRMED", "other", 1);
+            log.info(context, "Move to trash carries no Message-ID header to probe the destination with; settling on the source's answer alone");
+            await settleExhaustedDelete(accountConfigId, sourceMailboxPath, getConnection, settlePaused);
+            return;
+        }
+        throw new Error(`Move to trash unconfirmed for message ${messageId} (attempt ${receiveCount}/${config.attempts.messageDelete})`);
+    };
+    if (!isAcceptedSchemaVersion(event.schemaVersion)) {
+        await abandonDelete("Refused to delete: event was minted under an unknown contract", "message_delete_unknown_schema_version");
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        // The folder can be deleted between enqueue and this sync, leaving a
+        // queued event pointing at a gone row. The lookup then throws
+        // NotFoundError forever, and on the account's per-group FIFO that head
+        // message stalls the whole pipeline (issues #287, #289, #290). A deleted
+        // mailbox makes the delete moot: ack with a WARN.
+        const source = await findMailboxRow(mailboxService, accountId, mailboxId);
+        if (source.kind === "gone") {
+            log.warn({ accountId, messageId, mailboxId }, "Skipping MESSAGE_DELETE: mailbox no longer exists (deleted)");
+            return;
+        }
+        const mailbox = source.mailbox;
+        const destination = operation === "move_to_trash" && destinationMailboxId !== undefined
+            ? await findMailboxRow(mailboxService, accountId, destinationMailboxId)
+            : undefined;
+        if (destination?.kind === "gone") {
+            await abandonDelete("Refused to delete: the destination mailbox no longer exists (deleted)", "message_delete_destination_gone");
+            await emitMailboxResync(emit, { accountId, mailboxId });
+            return;
+        }
+        const mailboxPath = mailbox.fullPath;
+        const destinationMailboxPath = destination?.mailbox.fullPath;
+        const paths = {
+            source: mailboxPath,
+            destination: destinationMailboxPath,
+        };
+        const scope = pool.borrow(account, credentials);
+        // The terminal resolver opens the source itself, and its answer now
+        // WRITES a placement, so it has to reach IMAP through the same
+        // UIDVALIDITY choke point every other outbound operation does. An
+        // unguarded probe on a folder that was deleted and recreated finds
+        // whatever the server has renumbered onto this uid, reads it as "still
+        // at source", and binds the row to a stranger the next permanent delete
+        // would expunge.
+        const getGuardedConnection = async () => guardConnectionCursor(await scope.getConnection(), { mailboxService }, accountId, mailbox);
+        const settlePaused = (commandIssued) => settlePausedDelete(scope.getConnection, commandIssued, paths);
+        // Flipped the instant the MOVE or the EXPUNGE leaves, so every settle
+        // downstream of it knows the server was asked.
+        let commandIssued = false;
+        // Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
+        // paused never opens a connection on a first delivery. Optimization
+        // only — the guardConnectionCursor openBox wrap below is the structural
+        // guarantee.
+        if (isCursorRebuildNeeded(mailbox.cursorState)) {
+            log.info({ accountId, messageId, mailboxId }, "Mailbox cursor not normal; pausing outbound delete this round and settling the row against the server");
+            await settlePaused(false).finally(() => scope.release());
+            return;
+        }
+        await scope
+            .getConnection()
+            .then(async (rawConnection) => {
+            // Guard at the openBox choke point (epic #1281 invariants 3 & 5):
+            // a fresh mismatch trips the mailbox and throws once the SELECT
+            // reveals it. The delete stays applied locally either way.
+            const connection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, mailbox);
+            await connection.openBox(mailboxPath, false);
+            if (operation !== "move_to_trash" &&
+                operation !== "permanent_delete") {
+                await abandonDelete("Refused to delete: event carries an unrecognized operation", "message_delete_unknown_operation");
+            }
+            else if (operation === "move_to_trash" &&
+                (!destinationMailboxPath || !destinationMailboxId)) {
+                // Defence in depth. `MessageMoveService` always sets both fields,
+                // so nothing mints such an event today; the guard exists so that
+                // a future producer that forgets one cannot reach the expunge.
+                await abandonDelete("Refused to delete: move to trash carries no destination mailbox", "message_delete_missing_destination");
+            }
+            else if (operation === "move_to_trash" &&
+                destinationMailboxPath &&
+                destinationMailboxId) {
+                // Move to Trash
+                commandIssued = true;
+                const result = await connection.moveMessages([uid], destinationMailboxPath);
+                // UIDPLUS is an extension. A server without it answers a
+                // perfectly successful MOVE with no COPYUID entry, so an empty
+                // map is UNCONFIRMED, never evidence the move failed: the server
+                // is asked before any verdict, exactly as `handleMessageMove` and
+                // `attemptMove` do (issues #979, #665). A probe the server refused
+                // says nothing either way and counts as unconfirmed.
+                const copyUid = result.uidMap.get(uid);
+                const confirmation = copyUid
+                    ? { outcome: "confirmed", uid: copyUid }
+                    : await confirmTrashMoveUid(connection, rawConnection, messageService, threadMessageService, account.accountConfigId, messageId, mailboxPath, destinationMailboxPath, uid).catch((probeError) => {
+                        log.warn({
+                            messageId,
+                            uid,
+                            mailboxPath,
+                            destinationMailboxPath,
+                            probeError,
+                        }, "Could not confirm the move to trash; keeping local rows");
+                        return { outcome: "unconfirmed" };
+                    });
+                if (confirmation.outcome === "confirmed") {
+                    await settleTrashMoveConfirmed(confirmation.uid, destinationMailboxId);
+                    return;
+                }
+                await settleUnconfirmedTrashMove(confirmation, account.accountConfigId, mailboxPath, getGuardedConnection, () => settlePaused(true));
+            }
+            else {
+                // Permanent delete — reached only by `operation === "permanent_delete"`.
+                commandIssued = true;
+                await connection.deleteMessages([uid]);
+                // Delete ThreadMessage rows BEFORE the Message row to collapse the
+                // visibility window where the inbox lists a row whose backing
+                // Message has already been deleted (see issue #212). Multi-mailbox
+                // copies are handled by the helper.
+                const threadMessagesDeleted = await deleteAllThreadMessagesForMessage(threadMessageService, account.accountConfigId, messageId);
+                // Delete local Message entity
+                await messageService.delete(messageId);
+                log.info({ messageId, threadMessagesDeleted }, "Message permanently deleted");
+            }
+        })
+            .catch(async (error) => {
+            if (error instanceof MailboxCursorPausedError) {
+                log.info({ accountId, messageId, mailboxId, cursorState: error.state }, "Mailbox cursor not normal; pausing outbound delete this round and settling the row against the server");
+                await settlePaused(commandIssued);
+                return;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Reconcile a permanent delete the server already applied (#212).
+            // The error text only nominates a candidate — the source box
+            // decides, since a landed move-to-trash reports that same text from
+            // a LOCAL lookup (#845) — and a probe that cannot answer counts as
+            // not-confirmed, leaving the original error to the rethrow below.
+            const isGoneFromSource = operation === "permanent_delete" &&
+                (errorMessage.includes("not found") ||
+                    errorMessage.includes("NONEXISTENT")) &&
+                (await scope
+                    .getConnection()
+                    .then((connection) => isMessageGoneFromOpenMailbox(connection, uid))
+                    .catch((probeError) => {
+                    log.warn({ messageId, uid, mailboxPath, probeError }, "Could not confirm whether the message is gone; keeping local rows");
+                    return false;
+                }));
+            if (isGoneFromSource) {
+                log.info({ messageId, uid }, "Message confirmed gone from IMAP, cleaning up local");
+                // Clean up local entities. Multi-mailbox copies are handled by the
+                // helper so we don't leave orphan rows (see issue #212).
+                await messageService.delete(messageId);
+                await deleteAllThreadMessagesForMessage(threadMessageService, account.accountConfigId, messageId);
+                return;
+            }
+            // TRYCREATE — the destination this event names is not on the
+            // server. Creating it would resurrect an empty `Trash` beside the
+            // real one and hand the name-hint rule two folders to choose
+            // between; the folder picker offers the ones that exist instead.
+            if (errorMessage.includes("TRYCREATE") && destinationMailboxPath) {
+                await abandonDelete("Refused to delete: the destination mailbox does not exist on the server", "message_delete_destination_missing");
+                return;
+            }
+            if (receiveCount < config.attempts.messageDelete) {
+                // Transient failure — connections drop. No alarm; redelivery
+                // retries, and `failed` marks the row unsettled meanwhile. It is
+                // not a terminal signal: only the resolver below settles anything.
+                await messageService.transitionPlacement(messageId, { status: [MessageStatus.moving, MessageStatus.deleting] }, { syncStatus: MessageSyncStatus.failed });
+                throw error;
+            }
+            // Budget exhausted. Settling here is what keeps a throwing
+            // `moveMessages` inside the ceiling: re-MOVEing a uid the source no
+            // longer holds fails identically on every redelivery, which is the
+            // failure this budget exists for.
+            await settleExhaustedDelete(account.accountConfigId, mailboxPath, getGuardedConnection, () => settlePaused(commandIssued));
+            log.error({ accountId, messageId, uid, mailboxPath, error: errorMessage }, "Delete retry exhausted; settled into a terminal outcome");
+        })
+            .finally(() => scope.release());
+    });
+};

package/{src/handlers/message-move-terminal.ts → dist/handlers/message-move-terminal.d.ts}

@@ -1,50 +1,29 @@
-import type {
-	IMessageRepository,
-	IThreadMessageRepository,
-	MessageItem,
-} from "@remit/data-ports";
-import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
-import {
-	type IImapConnection,
-	isMessageGoneFromOpenMailbox,
-	restoreSourcePlacement,
-} from "@remit/mailbox-service";
-
+import type { IMessageRepository, IThreadMessageRepository, MessageItem } from "@remit/data-ports";
+import { type IImapConnection } from "@remit/mailbox-service";
 export interface MessageMoveTerminalLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
 }
-
 export interface ResolveExhaustedMessageMoveDeps {
-	messageService: Pick<
-		IMessageRepository,
-		"deleteIfPlacement" | "transitionPlacement"
-	>;
-	threadMessageService: Pick<
-		IThreadMessageRepository,
-		"findAllByMessageId" | "deleteMany" | "update"
-	>;
-	log: MessageMoveTerminalLogger;
+    messageService: Pick<IMessageRepository, "deleteIfPlacement" | "transitionPlacement">;
+    threadMessageService: Pick<IThreadMessageRepository, "findAllByMessageId" | "deleteMany" | "update">;
+    log: MessageMoveTerminalLogger;
 }
-
 export interface ResolveExhaustedMessageMoveInput {
-	/** Where the row stood when the caller read it; the delete holds only while it still does. */
-	placement: Pick<MessageItem, "status" | "mailboxId" | "uid">;
-	accountId: string;
-	accountConfigId: string;
-	messageId: string;
-	sourceMailboxId: string;
-	uid: number;
-	sourceMailboxPath: string;
-	getConnection: () => Promise<IImapConnection>;
+    /** Where the row stood when the caller read it; the delete holds only while it still does. */
+    placement: Pick<MessageItem, "status" | "mailboxId" | "uid">;
+    accountId: string;
+    accountConfigId: string;
+    messageId: string;
+    sourceMailboxId: string;
+    uid: number;
+    sourceMailboxPath: string;
+    getConnection: () => Promise<IImapConnection>;
 }
-
 export type MessageMoveTerminalOutcome = "reconciled" | "broken";
-
 export interface ResolveExhaustedMessageMoveResult {
-	outcome: MessageMoveTerminalOutcome;
+    outcome: MessageMoveTerminalOutcome;
 }
-
 /**
  * Resolve a MESSAGE_MOVE failure that has exhausted the message queue's
  * redelivery budget into exactly one of two terminal outcomes, mirroring
@@ -95,70 +74,4 @@ export interface ResolveExhaustedMessageMoveResult {
  * reverse mistake discards the row for live mail, so the cost is paid
  * deliberately.
  */
-export const resolveExhaustedMessageMoveFailure = async (
-	deps: ResolveExhaustedMessageMoveDeps,
-	input: ResolveExhaustedMessageMoveInput,
-): Promise<ResolveExhaustedMessageMoveResult> => {
-	const {
-		accountId,
-		accountConfigId,
-		messageId,
-		sourceMailboxId,
-		uid,
-		sourceMailboxPath,
-		getConnection,
-	} = input;
-
-	const connection = await getConnection();
-	await connection.openBox(sourceMailboxPath, true);
-
-	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
-		const reconciled = await deps.messageService.deleteIfPlacement(
-			messageId,
-			input.placement,
-		);
-		deps.log.info(
-			{
-				metric: "message_move_stale_row_reconciled",
-				accountId,
-				accountConfigId,
-				messageId,
-				uid,
-				sourceMailboxPath,
-				reconciled,
-			},
-			"Message no longer at its move source after retry exhaustion (move landed server-side, or an external delete or move); stale row reconciled",
-		);
-		return { outcome: "reconciled" };
-	}
-
-	deps.log.error(
-		{
-			alert: "message_move_failed",
-			accountId,
-			accountConfigId,
-			messageId,
-			uid,
-			sourceMailboxId,
-			sourceMailboxPath,
-		},
-		"Message move could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder",
-	);
-
-	await restoreSourcePlacement(deps, {
-		accountConfigId,
-		messageId,
-		sourceMailboxId,
-		uid,
-		// The probe above just confirmed the pair, so the row is a faithful
-		// projection of the source again — and the move the user asked for did
-		// not happen, with nothing left to try it. `abandoned` is the value that
-		// says so without claiming a retry is coming (imap-mutations R3); the
-		// alert stays for the operator, and the mutation names itself so the
-		// reading pane offers the right way out (issue #1229).
-		syncStatus: MessageSyncStatus.abandoned,
-		abandonedMutation: MessageMutation.move,
-	});
-
-	return { outcome: "broken" };
-};
+export declare const resolveExhaustedMessageMoveFailure: (deps: ResolveExhaustedMessageMoveDeps, input: ResolveExhaustedMessageMoveInput) => Promise<ResolveExhaustedMessageMoveResult>;