@remit/imap-worker 0.0.90 → 0.0.91

package/dist/handlers/message-move.js

@@ -0,0 +1,490 @@
+import { MessageMutation, MessageStatus, MessageSyncStatus, } from "@remit/domain-enums";
+import { guardConnectionCursor, isCursorRebuildNeeded, 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 { resolveExhaustedMessageMoveFailure } from "./message-move-terminal.js";
+import { probeableMessageIdHeader } from "./probe-message-id.js";
+/**
+ * Re-read both folders' counts from IMAP after a move by enqueuing the existing
+ * per-folder SYNC_MESSAGES sync. Counts are a projection of IMAP, never mutated
+ * locally — the move shifted a message between source and destination, so both
+ * folders must refresh through the one-way pipeline.
+ */
+export const emitMoveResync = async (emit, params) => {
+    const { accountId, sourceMailboxId, destinationMailboxId } = params;
+    await Promise.all([sourceMailboxId, destinationMailboxId].map((mailboxId) => emit({ type: "SYNC_MESSAGES", accountId, mailboxId })));
+};
+/**
+ * The one-folder half of {@link emitMoveResync}, for a mutation that has no
+ * destination — a permanent delete removed local rows the server still holds,
+ * and only a resync of that folder puts them back.
+ */
+export const emitMailboxResync = async (emit, params) => {
+    await emit({ type: "SYNC_MESSAGES", ...params });
+};
+/**
+ * SEARCH a mailbox for copies of a message identified by its RFC822 Message-ID
+ * header and answer the HIGHEST matching uid. Read-only (EXAMINE, not SELECT) —
+ * this is a verification probe, never a write. `null` when nothing matched.
+ *
+ * The highest uid is the freshly delivered copy only when one exists; deciding
+ * that it does is the caller's job, not this function's. Every probe in this
+ * package wants the highest: uids ascend with arrival inside a UIDVALIDITY, so a
+ * copy that has just landed outranks every copy of the same Message-ID the
+ * folder already held. Where nothing was delivered, the highest is simply the
+ * newest pre-existing copy, and a caller that has not ruled that case out binds
+ * itself to unrelated mail.
+ * One Message-ID can have several server copies in one account (a sieve
+ * `fileinto` + `keep`, a resend, a repeated COPY — `deriveCopyMessageId` reuses
+ * the row, so the second copy is a second server COPY), while `deriveMessageId`
+ * is folder-independent and gives them one local row. Taking the lowest bound
+ * the fresh copy's row to an older copy's uid and orphaned the fresh one, which
+ * a later delete or Empty Trash then expunged by the wrong uid (issue #1122).
+ *
+ * The maximum is computed rather than read off the tail: RFC 3501 leaves the
+ * order of a SEARCH response unspecified, so "last returned" is not "highest".
+ */
+export const searchMailboxForHighestMessageIdUid = async (connection, mailboxPath, messageIdHeader) => {
+    await connection.openBox(mailboxPath, true);
+    const uids = await connection.search([
+        ["HEADER", "Message-ID", messageIdHeader],
+    ]);
+    if (uids.length === 0)
+        return null;
+    return uids.reduce((highest, uid) => (uid > highest ? uid : highest));
+};
+/**
+ * Ask the server, by Message-ID, which folder holds a message whose mutation a
+ * paused cursor interrupted (issue #1203).
+ *
+ * Reached only on a redelivery, where "the command never left" has stopped
+ * being provable: the earlier attempt's tagged OK can be lost with the
+ * connection, so restoring the source pair on that assumption would write a
+ * settled placement naming a folder the server has already moved the mail out
+ * of. `message-copy.ts` asks the same question for the same reason.
+ *
+ * The SOURCE is asked first and a hit ends it, the gate `confirmTrashMoveUid`
+ * documents (#1122): where the mutation never ran, every hit at the destination
+ * is an older copy of the same Message-ID — a sieve `fileinto` + `keep`, a
+ * multi-label store, a resend — that `deriveMessageId` folds into this one local
+ * row, and binding to it hands a later delete somebody else's uid.
+ *
+ * The source's silence, however, is not the mirror image of its hit. Every
+ * caller here reaches this on a paused cursor, which means the source's
+ * UIDVALIDITY has moved and the folder may have been recreated holding nothing
+ * it held before — so "not at the source" is an answer about the folder, not
+ * about our mutation, and `at-destination` is a sighting rather than a
+ * confirmation. Callers settle it as unproven; see `settlePausedMove`.
+ *
+ * Identity, not position, is what makes this askable at all: a paused cursor
+ * means the source's UIDVALIDITY has moved, so every stored uid for it names
+ * something else, but a SEARCH by header is independent of the axis and answers
+ * the same question the cursor rebuild itself matches rows by. For that reason
+ * the caller passes the UNGUARDED connection — a `guardConnectionCursor` wrap
+ * refuses to open the mailbox at all, and it is bound to the source's snapshot
+ * anyway, so opening the destination through it would trip that mailbox too.
+ */
+export const probePausedPlacement = async (connection, input) => {
+    const { messageIdHeader, sourceMailboxPath, destinationMailboxPath } = input;
+    if (!messageIdHeader)
+        return { kind: "unprobeable" };
+    const atSource = await searchMailboxForHighestMessageIdUid(connection, sourceMailboxPath, messageIdHeader);
+    if (atSource !== null)
+        return { kind: "at-source" };
+    if (!destinationMailboxPath)
+        return { kind: "gone" };
+    const atDestination = await searchMailboxForHighestMessageIdUid(connection, destinationMailboxPath, messageIdHeader);
+    return atDestination === null
+        ? { kind: "gone" }
+        : { kind: "at-destination", uid: atDestination };
+};
+/**
+ * Resync the affected folders only once the IMAP move has resolved. A move that
+ * fails (or is retried) must not refresh counts off a move that didn't happen,
+ * so the resync is sequenced strictly after `performMove`.
+ */
+export const moveThenResync = async (performMove, resync) => {
+    await performMove();
+    await resync();
+};
+/**
+ * Build the `set` and `composites` payload for the ThreadMessage update on a
+ * MESSAGE_MOVE.
+ *
+ * The CURRENT row state goes in `composites`; the NEW values go in `set`.
+ * ElectroDB uses `composites` to run the conditional check on the existing row
+ * AND to compute the previous sort-key values needed to recompute the new ones.
+ * Passing the NEW values in `composites` makes the conditional check fail with
+ * ConditionalCheckFailedException, which ElectroDB wraps as NotFoundError, and
+ * the caller silently drops the update. Same root cause as PR #186 fixed for
+ * `flag-queue.ts`.
+ */
+export const buildThreadMessageMoveUpdate = (threadMessage, newUid, destinationMailboxId) => ({
+    set: {
+        uid: newUid,
+        mailboxId: destinationMailboxId,
+        isDeleted: false,
+    },
+    composites: {
+        sentDate: threadMessage.sentDate,
+        mailboxId: threadMessage.mailboxId,
+        isRead: threadMessage.isRead,
+        isDeleted: threadMessage.isDeleted,
+        hasStars: threadMessage.hasStars,
+        hasAttachment: threadMessage.hasAttachment,
+    },
+});
+/**
+ * Handle MESSAGE_MOVE events.
+ * Executes IMAP MOVE command and updates local state with new UID.
+ *
+ * A failing move retries on SQS redelivery until `receiveCount` reaches
+ * the `config.attempts.messageMove` budget, at which point
+ * {@link resolveExhaustedMessageMoveFailure} asks IMAP where the message
+ * actually is and settles the row into one terminal outcome (issue #655).
+ * Before that, `syncStatus: failed` marked every attempt and nothing ever
+ * settled the row, so an exhausted move sat `moving`/`failed` forever.
+ */
+export const handleMessageMove = 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, sourceMailboxId, destinationMailboxId, uid } = event;
+    log.info({
+        event: event.type,
+        accountId,
+        messageId,
+        from: sourceMailboxId,
+        to: destinationMailboxId,
+    }, "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 message row is already gone — some other reconciliation path deleted
+    // it. The move is moot; ack without touching IMAP.
+    if (!message) {
+        log.warn({ accountId, messageId }, "Skipping MESSAGE_MOVE: message row no longer exists");
+        return;
+    }
+    // This move already settled — `updateUid` cleared `status: moving` once the
+    // server confirmed it. A redelivery reaching here would MOVE a UID the
+    // source no longer holds, fail, and on exhaustion read the source's honest
+    // "gone" as grounds to reconcile away a row that is correct. There is no
+    // marker to find missing (unlike FLAG_PUSH and PLACEMENT_MOVE_PUSH), so the
+    // row's own pending marker is what stands in for one.
+    //
+    // `moving` specifically, not the shared unsettled predicate: the question is
+    // whether THIS move is still outstanding, and a row a delete has since
+    // claimed is `deleting` — work that belongs to MESSAGE_DELETE, and a state
+    // this move must not read as its own to finish.
+    if (message.status !== MessageStatus.moving) {
+        log.info({ accountId, messageId, uid: message.uid, status: message.status }, "Skipping MESSAGE_MOVE: the move already settled against confirmed IMAP state");
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        // The source 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
+        // source mailbox makes the move moot, but not the row: left `moving`, it
+        // names the destination with a uid from a folder that no longer exists,
+        // and nothing else settles it. It is reconciled away, and the destination
+        // resync re-projects the message if the MOVE did land there.
+        const source = await findMailboxRow(mailboxService, accountId, sourceMailboxId);
+        if (source.kind === "gone") {
+            const reconciled = await messageService.deleteIfPlacement(messageId, {
+                status: message.status,
+                mailboxId: message.mailboxId,
+                uid: message.uid,
+            });
+            log.warn({
+                metric: "message_move_source_gone",
+                accountId,
+                messageId,
+                mailboxId: sourceMailboxId,
+                reconciled,
+            }, "MESSAGE_MOVE not pushed: source mailbox no longer exists (deleted); stale row reconciled");
+            await emitMailboxResync(emit, {
+                accountId,
+                mailboxId: destinationMailboxId,
+            });
+            return;
+        }
+        const mailbox = source.mailbox;
+        const sourceMailboxPath = mailbox.fullPath;
+        const destination = await findMailboxRow(mailboxService, accountId, destinationMailboxId);
+        const settleMoved = async (newUid) => {
+            await messageService.updateUid(messageId, newUid, destinationMailboxId);
+            const threadMessage = await threadMessageService.findByMessageId(account.accountConfigId, messageId);
+            if (threadMessage) {
+                const args = buildThreadMessageMoveUpdate(threadMessage, newUid, destinationMailboxId);
+                await threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, args.set, { composites: args.composites });
+            }
+            log.info({
+                messageId,
+                oldUid: uid,
+                newUid,
+                destination: destinationMailboxId,
+            }, "Message moved successfully");
+        };
+        /**
+         * Put the row back on the pair it was moved off, and say so once.
+         *
+         * `metric` is the routine give-up the guard doc calls never-a-fault:
+         * the user's move was silently dropped, which is worth counting and
+         * not worth waking anyone for. `alert` is the give-up the server did
+         * not settle — the row carries `failed` and an operator adjudicates.
+         */
+        const handBackToSource = async (syncStatus, signal, reason) => {
+            const context = {
+                ...signal,
+                accountId,
+                messageId,
+                uid,
+                sourceMailboxId,
+                destinationMailboxId,
+                receiveCount,
+                reason,
+            };
+            if ("alert" in signal) {
+                log.error(context, "Move given up without a settled placement; row handed back to its source for adjudication");
+            }
+            else {
+                log.warn(context, "Move not pushed to the server; row handed back to its source");
+            }
+            await restoreSourcePlacement({ messageService, threadMessageService }, {
+                accountConfigId: account.accountConfigId,
+                messageId,
+                sourceMailboxId,
+                uid,
+                syncStatus,
+                // Every hand-back this handler makes is a move's. Naming it on
+                // the row is what stops the reading pane calling a move that
+                // gave up a failed delete (issue #1229).
+                abandonedMutation: syncStatus === MessageSyncStatus.abandoned
+                    ? MessageMutation.move
+                    : MessageMutation.none,
+            });
+        };
+        if (destination.kind === "gone") {
+            await handBackToSource(MessageSyncStatus.synced, { metric: "message_move_destination_gone" }, "destination mailbox no longer exists (deleted)");
+            await emitMailboxResync(emit, {
+                accountId,
+                mailboxId: sourceMailboxId,
+            });
+            return;
+        }
+        const destinationMailboxPath = destination.mailbox.fullPath;
+        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);
+        // A paused cursor is never acked on the optimistic row: the transition
+        // has pointed it at the destination while `uid` still names the source,
+        // and that pair strands the row for good — the cursor rebuild matches
+        // rows by `(accountConfigId, mailboxId)`, so a row naming the
+        // destination is in neither folder's set, and nothing re-enqueues a
+        // MESSAGE_MOVE (issue #1203).
+        //
+        // This move 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 below
+        // plus the source's own cursor rebuild are its repair path.
+        //
+        // Putting the row back is an undo of this product's own write only where
+        // the MOVE provably never left. `commandIssued` says what this round
+        // did; `receiveCount` adds what an earlier one may have done and lost
+        // with its connection. Inferring the first from the second is what
+        // `settlePausedDelete` got wrong — attempt 1 reaches an exhausted settle
+        // too, with the MOVE already issued.
+        const settlePausedMove = async (commandIssued) => {
+            const mayHaveIssued = commandIssued || receiveCount > 1;
+            const placement = mayHaveIssued
+                ? await probePausedPlacement(await scope.getConnection(), {
+                    messageIdHeader: await probeableMessageIdHeader(threadMessageService, account.accountConfigId, messageId),
+                    sourceMailboxPath,
+                    destinationMailboxPath,
+                })
+                : { kind: "at-source" };
+            // A sighting at the destination is not proof this move 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 that `deriveMessageId` folds
+            // into this row — settling `moved` on it points the row at mail a
+            // later permanent delete would expunge. `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) the
+            // destination — not paused, no rebuild coming — does not have.
+            const unproven = placement.kind === "at-destination" ||
+                placement.kind === "unprobeable";
+            if (unproven) {
+                await handBackToSource(MessageSyncStatus.abandoned, { alert: "message_move_paused_placement_unproven" }, placement.kind === "at-destination"
+                    ? "destination holds this Message-ID but the source's uid axis has moved, so the sighting does not prove this move 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 handBackToSource(MessageSyncStatus.synced, { metric: "message_move_dropped_on_pause" }, `source mailbox cursor paused, placement ${placement.kind}`);
+            }
+            await emitMoveResync(emit, {
+                accountId,
+                sourceMailboxId,
+                destinationMailboxId,
+            });
+        };
+        // 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: sourceMailboxId }, "Mailbox cursor not normal; pausing outbound move this round and settling the row against the server");
+            await settlePausedMove(false).finally(() => scope.release());
+            return;
+        }
+        // Flipped the instant the MOVE leaves, so every settle downstream of it
+        // knows the server was asked.
+        let commandIssued = false;
+        await scope
+            .getConnection()
+            .then((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 move stays applied locally either way.
+            const connection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, mailbox);
+            return moveThenResync(async () => {
+                // Open source mailbox (not read-only)
+                await connection.openBox(sourceMailboxPath, false);
+                // Execute IMAP MOVE
+                commandIssued = true;
+                const result = await connection.moveMessages([uid], destinationMailboxPath);
+                // Get new UID from COPYUID response. A server without UIDPLUS
+                // answers a perfectly successful MOVE with no COPYUID entry,
+                // so an empty map is UNCONFIRMED, never evidence the message
+                // is gone: the destination is asked by Message-ID before any
+                // verdict, exactly as `attemptMove` does. Marking the row
+                // `failed` and returning (the behaviour issue #655 opens on)
+                // left it `moving`/`failed` with no DLQ entry and no metric,
+                // because a handler that returns never redelivers.
+                const newUid = result.uidMap.get(uid) ??
+                    (await probeableMessageIdHeader(threadMessageService, account.accountConfigId, messageId).then((messageIdHeader) => messageIdHeader
+                        ? searchMailboxForHighestMessageIdUid(rawConnection, destinationMailboxPath, messageIdHeader)
+                        : null));
+                if (!newUid) {
+                    throw new Error(`Message move unconfirmed (no COPYUID entry, not found at ${destinationMailboxPath}) — retrying`);
+                }
+                await settleMoved(newUid);
+            }, () => emitMoveResync(emit, {
+                accountId,
+                sourceMailboxId,
+                destinationMailboxId,
+            }));
+        })
+            .catch(async (error) => {
+            if (error instanceof MailboxCursorPausedError) {
+                log.info({
+                    accountId,
+                    messageId,
+                    mailboxId: sourceMailboxId,
+                    cursorState: error.state,
+                }, "Mailbox cursor not normal; pausing outbound move this round and settling the row against the server");
+                await settlePausedMove(commandIssued);
+                return;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Handle TRYCREATE - destination doesn't exist
+            if (errorMessage.includes("TRYCREATE")) {
+                log.info({ destinationMailboxPath }, "Destination mailbox doesn't exist, creating");
+                const connection = await scope.getConnection();
+                await connection.createMailbox(destinationMailboxPath);
+                // Re-throw to let the event be retried against the folder just
+                // created. Kept unconditional past the attempt budget: the
+                // destination now exists, so the record is worth redriving from
+                // the DLQ, and the terminal resolver has nothing to settle — it
+                // would find the message exactly where it started.
+                throw error;
+            }
+            if (receiveCount < config.attempts.messageMove) {
+                // Transient move failure — expected (connections drop). No
+                // alarm; queue redelivery retries, and `failed` marks the row
+                // as unsettled meanwhile. It is not a terminal signal: only the
+                // resolver below settles anything.
+                await messageService.transitionPlacement(messageId, { status: MessageStatus.moving }, { syncStatus: MessageSyncStatus.failed });
+                throw error;
+            }
+            // Redelivery budget exhausted: resolve into exactly one of the two
+            // terminal outcomes instead of dead-lettering with no diagnosis,
+            // and never by inferring the server's state from our own failures.
+            const settled = await resolveExhaustedMessageMoveFailure({ messageService, threadMessageService, log }, {
+                placement: {
+                    status: message.status,
+                    mailboxId: message.mailboxId,
+                    uid: message.uid,
+                },
+                accountId,
+                accountConfigId: account.accountConfigId,
+                messageId,
+                sourceMailboxId,
+                uid,
+                sourceMailboxPath,
+                getConnection: getGuardedConnection,
+            }).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 this catch. The row is still settled, on the
+                // identity axis instead: `settlePausedMove` asks by Message-ID,
+                // which a UIDVALIDITY change does not invalidate.
+                if (settleError instanceof MailboxCursorPausedError) {
+                    log.info({
+                        accountId,
+                        messageId,
+                        mailboxId: sourceMailboxId,
+                        cursorState: settleError.state,
+                    }, "Mailbox cursor not normal; settling the exhausted move against the server by Message-ID");
+                    await settlePausedMove(commandIssued);
+                    return null;
+                }
+                throw settleError;
+            });
+            if (!settled)
+                return;
+            if (settled.outcome === "broken") {
+                // Terminal and never re-thrown, so the handler-outcome series
+                // records this record as a success. Counted here or it is
+                // invisible.
+                metrics.imapFailure("MESSAGE_MOVE_EXHAUSTED", "other", 1);
+                log.error({ error: errorMessage }, "Message move retry exhausted; message still exists at its source");
+            }
+            // Both verdicts end in a row the server has contradicted, so this
+            // move reconciles rather than waits (R2). RECONCILED, the local rows
+            // are gone and whichever folder actually holds the message
+            // re-projects it with the server's own UID. 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 emitMoveResync(emit, {
+                accountId,
+                sourceMailboxId,
+                destinationMailboxId,
+            });
+            // Terminal — never re-thrown, so the caller acks either way.
+        })
+            .finally(() => scope.release());
+    });
+};

package/dist/handlers/placement-move-push.d.ts

@@ -0,0 +1,62 @@
+import { type IImapConnection } from "@remit/mailbox-service";
+import type { ProcessContext } from "../context.js";
+import type { PlacementMovePushEvent } from "../events.js";
+interface MoveOutcome {
+    kind: "moved" | "not-found" | "trycreate";
+    newUid?: number;
+}
+/**
+ * Attempt the IMAP MOVE.
+ *
+ * Takes two connection handles rather than one: `sourceConnection` and
+ * `destinationConnection` wrap the SAME underlying connection but are each
+ * cursor-guarded (#1272) against their OWN mailbox — a `guardConnectionCursor`
+ * wrap binds `openBox` checks to whichever ONE mailbox snapshot it was built
+ * with, so verifying at the destination must never run through the source's
+ * guard (it would compare the destination's served UIDVALIDITY against the
+ * source's stored one and misfire).
+ *
+ * - `moved` with a `newUid` — confirmed, either via COPYUID or (see below)
+ *   an explicit destination verification.
+ * - `trycreate` — the destination mailbox doesn't exist yet; the caller
+ *   creates it and retries.
+ * - `not-found` — confirmed absent from BOTH source and destination. Only
+ *   this outcome supersedes the pending-move marker (drops it, reconciles
+ *   the row as an external delete).
+ * - Any other case throws (propagates for SQS retry, or as
+ *   `MailboxCursorPausedError` for the caller's cursor-pause handling) —
+ *   including an UNCONFIRMED move (no COPYUID, or an explicit "not
+ *   found"/NONEXISTENT from the server) whose message is still sitting at
+ *   the source. A MOVE that resolves without a uidMap entry on a
+ *   non-UIDPLUS server is a plausible SUCCESS, not evidence the message is
+ *   gone (PR #1289 review finding 2) — deleting the local row on that
+ *   ambiguity would be data loss. `not-found` is only returned once BOTH a
+ *   destination Message-ID search (when the header is known) misses AND
+ *   {@link isMessageGoneFromOpenMailbox} confirms the message absent from the
+ *   source — a FETCH returning no row does not, on its own, confirm anything.
+ */
+export declare const attemptMove: (sourceConnection: IImapConnection, destinationConnection: IImapConnection, sourceMailboxPath: string, destinationMailboxPath: string, uid: number, messageIdHeader: string | undefined) => Promise<MoveOutcome>;
+/**
+ * Handle PLACEMENT_MOVE_PUSH events (issue #1271, epic #1281). Drains ONE
+ * pending placement-move marker: resolves the UID fresh from the Message row
+ * (never trusts a captured value — invariant 1), pushes the IMAP MOVE, and
+ * clears the marker ONLY on confirmed success. Every precedence rule (epic
+ * invariant 2) is enforced here:
+ * - Pending Remit move wins on location: nothing in this handler ever
+ *   corrects `message.mailboxId` back toward the source — a resync elsewhere
+ *   (message-sync.ts) never overwrites an existing row's `mailboxId` either
+ *   (create-only-if-not-exists semantics), so the local move is never undone.
+ * - A NEWER local action superseding this marker (drop without pushing) —
+ *   see the `message.mailboxId !== marker.destinationMailboxId` check below.
+ * - An external delete supersedes the marker entirely — the `not-found`
+ *   outcome drops the marker and reconciles the stale row.
+ *
+ * Cursor-guarded (#1272, epic #1281 invariant 5): both the source and
+ * destination mailbox are checked for a non-`normal` `cursorState` before
+ * connecting, and the connection is wrapped per-mailbox via
+ * `guardConnectionCursor` so no stored UID touches the server while either
+ * mailbox's axis is being rebuilt. A trip pauses the push (routine, no
+ * alarm) — the marker stays durable and pushes again on the next event.
+ */
+export declare const handlePlacementMovePush: (event: PlacementMovePushEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;
+export {};