@remit/imap-worker 0.0.89 → 0.0.91

package/dist/handlers/delete-account-objects.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessContext } from "../context.js";
+import type { DeleteAccountObjectsEvent } from "../events.js";
+export declare const handleDeleteAccountObjects: (event: DeleteAccountObjectsEvent, ctx: ProcessContext, getRemainingTimeMs?: () => number) => Promise<void>;

package/dist/handlers/delete-account-objects.js

@@ -0,0 +1,35 @@
+const MIN_REMAINING_MS = 30_000;
+export const handleDeleteAccountObjects = async (event, ctx, getRemainingTimeMs) => {
+    const { log, queues, accountObjects } = ctx;
+    const { accountConfigId, continuationToken } = event;
+    const prefix = `accounts/${accountConfigId}/`;
+    log.info({ accountConfigId, prefix, hasContinuation: !!continuationToken }, "Deleting account objects from S3");
+    let currentToken = continuationToken;
+    let totalDeleted = 0;
+    while (true) {
+        // Check remaining time before starting a new page
+        if (getRemainingTimeMs && getRemainingTimeMs() < MIN_REMAINING_MS) {
+            log.info({ accountConfigId, totalDeleted, continuationToken: currentToken }, "Near timeout, re-enqueuing with continuation token");
+            await reenqueue(queues, accountConfigId, currentToken);
+            return;
+        }
+        const page = await accountObjects.list(prefix, currentToken);
+        if (page.keys.length > 0) {
+            await accountObjects.delete(page.keys);
+            totalDeleted += page.keys.length;
+        }
+        if (page.nextContinuationToken === undefined) {
+            break;
+        }
+        currentToken = page.nextContinuationToken;
+    }
+    log.info({ accountConfigId, totalDeleted }, "Finished deleting account objects");
+};
+const reenqueue = async (queues, accountConfigId, continuationToken) => {
+    const event = {
+        type: "DELETE_ACCOUNT_OBJECTS",
+        accountConfigId,
+        continuationToken,
+    };
+    await queues.messageManagement.send({ body: event });
+};

package/dist/handlers/empty-trash.d.ts

@@ -0,0 +1,14 @@
+import type { ProcessContext } from "../context.js";
+import type { EmptyTrashEvent } from "../events.js";
+/**
+ * Handle EMPTY_TRASH events.
+ * Permanently deletes all messages in the Trash mailbox.
+ *
+ * The only unrecoverable mutation reader issues, so the folder's identity is
+ * confirmed here, on the connection that does the expunging: the role still
+ * names this mailbox on confirmed evidence, and the UIDVALIDITY the SELECT
+ * serves still matches the one the user consented to. Every refusal reverts
+ * the optimistic local marks and acks — a throw would stall the account's FIFO
+ * group behind an event no retry can fix (issues #287, #289, #290).
+ */
+export declare const handleEmptyTrash: (event: EmptyTrashEvent, ctx: ProcessContext) => Promise<void>;

package/dist/handlers/empty-trash.js

@@ -0,0 +1,217 @@
+import { trashMailboxAt } from "@remit/data-ports/folder-role";
+import { isAcceptedSchemaVersion } from "@remit/data-ports/mutation-events";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { buildThreadMessageUndelete, carriesForeignUid, guardConnectionCursor, isCursorRebuildNeeded, MailboxCursorPausedError, } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { findMailboxRow } from "../mailbox-row.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+/**
+ * Handle EMPTY_TRASH events.
+ * Permanently deletes all messages in the Trash mailbox.
+ *
+ * The only unrecoverable mutation reader issues, so the folder's identity is
+ * confirmed here, on the connection that does the expunging: the role still
+ * names this mailbox on confirmed evidence, and the UIDVALIDITY the SELECT
+ * serves still matches the one the user consented to. Every refusal reverts
+ * the optimistic local marks and acks — a throw would stall the account's FIFO
+ * group behind an event no retry can fix (issues #287, #289, #290).
+ */
+export const handleEmptyTrash = async (event, ctx) => {
+    const { log, pool } = ctx;
+    const { account: accountService, message: messageService, threadMessage: threadMessageService, mailbox: mailboxService, mailboxSpecialUse: mailboxSpecialUseService, secrets, } = ctx.client;
+    const { accountId, trashMailboxId } = event;
+    log.info({ event: event.type, accountId, trashMailboxId }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    // `emptyTrash` marks every row in the folder `deleting` + `isDeleted` before
+    // enqueueing, so any row this expunge does not carry through is hidden from
+    // every listing with nothing else to unhide it: no sync clears it, a repeat
+    // Empty Trash skips it again, and listings filter `isDeleted`. Handing it
+    // back is right whichever way it got left behind — mail already gone from
+    // the server becomes visible and the next cursor rebuild reconciles it, and
+    // an unsettled move is rewritten by its own MESSAGE_DELETE. Not `failed`:
+    // the mail is intact, and saying otherwise about a whole folder is a lie.
+    const handBackMarkedRows = async (rows) => {
+        let revertedCount = 0;
+        for (const message of rows) {
+            if (message.status !== MessageStatus.deleting)
+                continue;
+            // Empty Trash only flips `isDeleted` on the listing rows; a permanent
+            // delete removes them up front. So a `deleting` row with no listing row
+            // was marked by some other in-flight operation, and reverting the
+            // Message under it would resurrect what that one is about to remove.
+            const threadMessages = await threadMessageService.findAllByMessageId(account.accountConfigId, message.messageId);
+            if (threadMessages.length === 0)
+                continue;
+            // The hand-back is a transition off the row as this sweep read it
+            // (imap-mutations R3), because the snapshot it walks holds nothing:
+            // between the listing and here another lane can settle the row onto a
+            // placement of its own, and writing `active` + `synced` over that would
+            // declare a mutation settled that nobody confirmed.
+            const restored = await messageService.transitionPlacement(message.messageId, {
+                status: MessageStatus.deleting,
+                mailboxId: message.mailboxId,
+                uid: message.uid,
+            }, {
+                status: MessageStatus.active,
+                syncStatus: MessageSyncStatus.synced,
+            });
+            if (!restored) {
+                log.info({ accountId, messageId: message.messageId }, "Empty Trash left a row alone: its placement changed after the sweep read it");
+                continue;
+            }
+            for (const threadMessage of threadMessages) {
+                const args = buildThreadMessageUndelete(threadMessage);
+                await threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, args.set, { composites: args.composites });
+            }
+            revertedCount += 1;
+        }
+        return revertedCount;
+    };
+    const abandonEmptyTrash = async (reason, alert, context = {}) => {
+        log.error({ alert, accountId, trashMailboxId, ...context }, reason);
+        await handBackMarkedRows(await messageService.listAllByMailbox(trashMailboxId));
+    };
+    if (!isAcceptedSchemaVersion(event.schemaVersion)) {
+        await abandonEmptyTrash("Refused to empty trash: event was minted under an unknown contract", "empty_trash_unknown_schema_version", { schemaVersion: event.schemaVersion });
+        return;
+    }
+    // The role can be re-appointed between consent and this run, and a queued
+    // event then expunges the folder the user just stopped using as Trash.
+    // Confirmed evidence only: what the user appointed, or what the server
+    // flagged.
+    const resolution = await mailboxSpecialUseService.resolveTrashRole(accountId);
+    const trashGate = trashMailboxAt(resolution, "confirmed");
+    if (!trashGate.allowed || trashGate.mailbox.mailboxId !== trashMailboxId) {
+        await abandonEmptyTrash("Refused to empty trash: this account's Trash is no longer that folder", "empty_trash_role_moved", {
+            resolvedKind: resolution.kind,
+            resolvedMailboxId: trashGate.allowed
+                ? trashGate.mailbox.mailboxId
+                : undefined,
+        });
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        // The Trash 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
+        // Trash makes the empty moot: ack with a WARN.
+        const trash = await findMailboxRow(mailboxService, accountId, trashMailboxId);
+        if (trash.kind === "gone") {
+            log.warn({ accountId, mailboxId: trashMailboxId }, "Skipping EMPTY_TRASH: mailbox no longer exists (deleted)");
+            return;
+        }
+        const mailbox = trash.mailbox;
+        // A paused cursor is not a wait here: this return acks the event and
+        // nothing re-issues it, so the marks have to come back or the folder
+        // stays hidden forever. The user retries.
+        if (isCursorRebuildNeeded(mailbox.cursorState)) {
+            await abandonEmptyTrash("Abandoned empty trash: mailbox cursor is not normal", "empty_trash_cursor_paused", { cursorState: mailbox.cursorState });
+            return;
+        }
+        const scope = pool.borrow(account, credentials);
+        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.
+            const connection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, mailbox);
+            const boxStatus = await connection.openBox(mailbox.fullPath, false);
+            // The path is not the folder. A third-party client that renames
+            // Trash and creates a fresh one leaves this event pointing at a
+            // path now served by a folder the user never consented to empty;
+            // UIDVALIDITY is what tells them apart (RFC 9051 2.3.1.1).
+            if (boxStatus.uidvalidity !== event.trashUidValidity) {
+                await abandonEmptyTrash("Refused to empty trash: the folder at this path is not the one the user emptied", "empty_trash_uidvalidity_mismatch", {
+                    servedUidValidity: boxStatus.uidvalidity,
+                    consentedUidValidity: event.trashUidValidity,
+                });
+                return;
+            }
+            // One read, before the expunge, decides both what is destroyed on
+            // the server and what is removed locally — so the two sets are the
+            // same set by construction and no message can be expunged that the
+            // sweep then declines to remove (issue #1230). Reading afterwards
+            // put the exclusion downstream of the destruction: a refused row
+            // had already lost its server copy, could not be refused into
+            // existence again, and nothing routine repaired it.
+            //
+            // 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, so matching it against the
+            // expunge answers for whatever Trash held at that uid — another
+            // message, deleted here in both its rows. Waiting is not open to
+            // this handler the way it is to the API-side mutators: a move on
+            // this account's own FIFO group cannot run until this returns, so
+            // the ceiling would be spent to reach the same answer. It buys
+            // nothing against the other lane either — PLACEMENT_MOVE_PUSH
+            // rides a standard queue with no group at all
+            // (`deploy/vps/queues.json`), so it is ordered against nothing
+            // here and can settle a row mid-sweep. That is why the writes
+            // below are transitions rather than snapshot writes (R3).
+            //
+            // `carriesForeignUid`, not the placement binding: the binding reads
+            // `status`, and `status` is exactly what an operation marking this
+            // folder overwrites. This is the same predicate `emptyTrash`
+            // applies before it marks anything — one gate, one answer, now
+            // asked once and honoured on both sides of the expunge.
+            const localMessages = await messageService.listAllByMailbox(trashMailboxId);
+            const sweepable = localMessages.filter((message) => !carriesForeignUid(message));
+            // A refused row spares its uid only where no row the sweep will
+            // carry claims the same number. The two cases the predicate cannot
+            // tell apart part here: a row genuinely mid-move borrows a uid that
+            // belongs to a different message in this folder, and sparing that
+            // number would strand the message that owns it; a settled row whose
+            // `originalUid` a pre-#1217 build left behind owns its uid outright,
+            // and expunging it destroys mail the sweep then refuses to remove.
+            const sweepableUids = new Set(sweepable.map((message) => message.uid));
+            const refusedUids = new Set(localMessages
+                .filter((message) => carriesForeignUid(message) && !sweepableUids.has(message.uid))
+                .map((message) => message.uid));
+            const uids = (await connection.search(["ALL"])).filter((uid) => !refusedUids.has(uid));
+            if (uids.length > 0) {
+                await connection.deleteMessages(uids);
+                log.info({ count: uids.length, refused: refusedUids.size }, "Deleted messages from IMAP trash");
+            }
+            // What was expunged is a fact this connection observed, and only
+            // those rows go.
+            const expunged = new Set(uids);
+            const swept = sweepable.filter((message) => expunged.has(message.uid));
+            const sweptIds = new Set(swept.map((message) => message.messageId));
+            const deletedCount = swept.length;
+            for (const message of swept) {
+                await messageService.delete(message.messageId);
+                const threadMessage = await threadMessageService.findByMessageId(account.accountConfigId, message.messageId);
+                if (threadMessage) {
+                    await threadMessageService.delete(threadMessage.accountConfigId, threadMessage.threadMessageId);
+                }
+            }
+            // Everything this sweep did not carry through is still marked for a
+            // deletion that will never come: mail another client already
+            // emptied, mail that reached Trash after the SEARCH, a redelivery
+            // finishing a partial sweep, and a row whose uid the sweep would
+            // not bind. All of them must come back rather than sit invisible —
+            // the last one especially, since nothing else is coming to clear
+            // its mark, and a row hidden in a folder it never left is worse
+            // than one the next sync re-projects.
+            const revertedCount = await handBackMarkedRows(localMessages.filter((message) => !sweptIds.has(message.messageId)));
+            log.info({ accountId, deletedCount, revertedCount }, "Trash emptied successfully");
+        })
+            .catch(async (error) => {
+            if (error instanceof MailboxCursorPausedError) {
+                await abandonEmptyTrash("Abandoned empty trash: mailbox cursor is not normal", "empty_trash_cursor_paused", { cursorState: error.state });
+                return;
+            }
+            throw error;
+        })
+            .finally(() => scope.release());
+    });
+};

package/dist/handlers/flag-push.d.ts

@@ -0,0 +1,38 @@
+import type { ProcessContext } from "../context.js";
+import type { FlagPushEvent } from "../events.js";
+/**
+ * How long a marker may sit deferred behind a move before it is dropped
+ * outright. A move that settles takes seconds to low minutes; one stuck past
+ * this window has almost certainly already exhausted its own retries and been
+ * resolved as broken by its own terminal resolver, so deferring further would
+ * cycle one SQS round trip per sync tick forever instead of surfacing the
+ * stall.
+ */
+export declare const FLAG_PUSH_DEFER_MAX_MS: number;
+/**
+ * Handle FLAG_PUSH events (issue #1273, epic #1281). Drains ONE pending
+ * flag-push marker: resolves the message's UID and CURRENT mailbox fresh
+ * from the Message row (never a value captured at enqueue — invariant 1),
+ * pushes the IMAP STORE (add or remove, per the marker's `operation`), and
+ * clears the marker ONLY on confirmed success.
+ *
+ * Precedence (epic invariant 2):
+ * - While pending, resync never reverts the flag — nothing in this handler
+ *   (or anywhere else) reads flags FROM IMAP back into `MessageFlag`/
+ *   `ThreadMessage` for an existing row; the only flag-state writes happen
+ *   here (confirmed push) or in `FlagQueueService` (the user's own local
+ *   flip, which already applied before this marker existed).
+ * - A later flip of the SAME field already replaced this marker (`put`) by
+ *   the time this event is processed, OR advanced it past `pending` — either
+ *   way `markerService.find` returns the CURRENT marker, so this handler
+ *   always drives the freshest intent, never a stale one.
+ * - An external delete supersedes the marker entirely — handled by
+ *   `resolveExhaustedFlagPushFailure`'s `reconciled` outcome.
+ *
+ * Cursor-guarded (#1272, epic #1281 invariant 5): the connection is wrapped
+ * via `guardConnectionCursor` around the mailbox's current `openBox` choke
+ * point, so no stored UID touches the server while the 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 or sync tick.
+ */
+export declare const handleFlagPush: (event: FlagPushEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;

package/dist/handlers/flag-push.js

@@ -0,0 +1,195 @@
+import { isNotFoundError } from "@remit/data-ports/errors";
+import { guardConnectionCursor, isCursorRebuildNeeded, isPlacementUnsettled, MailboxCursorPausedError, resolveExhaustedFlagPushFailure, } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+/**
+ * How long a marker may sit deferred behind a move before it is dropped
+ * outright. A move that settles takes seconds to low minutes; one stuck past
+ * this window has almost certainly already exhausted its own retries and been
+ * resolved as broken by its own terminal resolver, so deferring further would
+ * cycle one SQS round trip per sync tick forever instead of surfacing the
+ * stall.
+ */
+export const FLAG_PUSH_DEFER_MAX_MS = 10 * 60 * 1000;
+/**
+ * Handle FLAG_PUSH events (issue #1273, epic #1281). Drains ONE pending
+ * flag-push marker: resolves the message's UID and CURRENT mailbox fresh
+ * from the Message row (never a value captured at enqueue — invariant 1),
+ * pushes the IMAP STORE (add or remove, per the marker's `operation`), and
+ * clears the marker ONLY on confirmed success.
+ *
+ * Precedence (epic invariant 2):
+ * - While pending, resync never reverts the flag — nothing in this handler
+ *   (or anywhere else) reads flags FROM IMAP back into `MessageFlag`/
+ *   `ThreadMessage` for an existing row; the only flag-state writes happen
+ *   here (confirmed push) or in `FlagQueueService` (the user's own local
+ *   flip, which already applied before this marker existed).
+ * - A later flip of the SAME field already replaced this marker (`put`) by
+ *   the time this event is processed, OR advanced it past `pending` — either
+ *   way `markerService.find` returns the CURRENT marker, so this handler
+ *   always drives the freshest intent, never a stale one.
+ * - An external delete supersedes the marker entirely — handled by
+ *   `resolveExhaustedFlagPushFailure`'s `reconciled` outcome.
+ *
+ * Cursor-guarded (#1272, epic #1281 invariant 5): the connection is wrapped
+ * via `guardConnectionCursor` around the mailbox's current `openBox` choke
+ * point, so no stored UID touches the server while the 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 or sync tick.
+ */
+export const handleFlagPush = async (event, ctx, receiveCount) => {
+    const { log, pool, metrics, config } = ctx;
+    const { account: accountService, mailbox: mailboxService, message: messageService, threadMessage: threadMessageService, flagPush: markerService, secrets, } = ctx.client;
+    const { accountId, accountConfigId, messageId, flagName } = event;
+    const marker = await markerService.find(messageId, flagName);
+    if (!marker) {
+        log.info({ messageId, flagName, accountId }, "No pending flag-push marker (already confirmed or superseded); nothing to push");
+        return;
+    }
+    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 (body
+    // sync, placement move, a prior flag-push exhaustion) already deleted it.
+    // The marker is orphaned; drop it without touching IMAP.
+    if (!message) {
+        await markerService.delete(messageId, flagName);
+        log.info({ messageId, flagName, accountId }, "Message row no longer exists; flag-push marker dropped without pushing");
+        return;
+    }
+    // The message carries a move still in flight — `MessageMoveService`'s or
+    // `PlacementMoveService`'s local optimistic write, not yet confirmed by the
+    // server. A STORE resolved against this row addresses the destination
+    // folder at the SOURCE folder's uid: a different message (issue #496). This
+    // is the wait half of the wait-or-reconcile decision
+    // (docs/architecture/imap-mutations.md R2) — the push blocks until the move
+    // it depends on settles.
+    if (isPlacementUnsettled(message)) {
+        const deferredForMs = Date.now() - marker.createdAt;
+        if (deferredForMs > FLAG_PUSH_DEFER_MAX_MS) {
+            // The move this push was waiting on never settled within any
+            // reasonable window — deferring further would cycle one SQS round
+            // trip per sync tick forever. Drop the stale marker loudly rather
+            // than push against state nobody has confirmed.
+            await markerService.delete(messageId, flagName);
+            metrics.imapFailure("FLAG_PUSH_MOVE_NEVER_SETTLED", "other", 1);
+            log.error({
+                alert: "flag_push_move_never_settled",
+                messageId,
+                flagName,
+                accountId,
+                deferredForMs,
+            }, "Message move never settled; dropping the flag-push marker that was waiting on it");
+            return;
+        }
+        // Reset to `pending` rather than advancing: `drainPendingFlagPushes`
+        // only re-arms markers in that state, scoped by the marker's own
+        // `mailboxId` (the push destination), so the next periodic sync tick
+        // of that mailbox picks this back up once the move has settled.
+        await markerService.updateState(messageId, flagName, "pending");
+        log.info({ messageId, flagName, accountId, deferredForMs }, "Message has a move in flight; pausing outbound flag push until it settles");
+        return;
+    }
+    // The worker has picked up the event and is about to actually attempt the
+    // IMAP STORE — advance the state engine (pending/queued -> processing).
+    // Idempotent to call again on a redelivered event (a prior attempt that
+    // died mid-flight already left it here).
+    await markerService.updateState(messageId, flagName, "processing");
+    // The folder can be deleted between enqueue and this push, leaving a marker
+    // 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). The push is moot — drop the orphaned marker (as
+    // the message-gone branch above already does) and ack with a WARN.
+    const mailbox = await mailboxService
+        .get(accountId, message.mailboxId)
+        .catch((error) => {
+        if (isNotFoundError(error))
+            return null;
+        throw error;
+    });
+    if (!mailbox) {
+        await markerService.delete(messageId, flagName);
+        log.warn({ messageId, flagName, accountId, mailboxId: message.mailboxId }, "Skipping FLAG_PUSH: mailbox no longer exists (deleted); marker dropped");
+        return;
+    }
+    // Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
+    // paused never even borrows a connection. Optimization only — the
+    // guardConnectionCursor wrap below is the structural guarantee (#1272).
+    if (isCursorRebuildNeeded(mailbox.cursorState)) {
+        log.info({ messageId, flagName, accountId, cursorState: mailbox.cursorState }, "Mailbox cursor not normal; pausing outbound flag push this round");
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        const scope = pool.borrow(account, credentials);
+        await scope
+            .getConnection()
+            .then(async (rawConnection) => {
+            const connection = guardConnectionCursor(rawConnection, { mailboxService }, accountId, mailbox);
+            await connection.openBox(mailbox.fullPath, false);
+            if (marker.operation === "add") {
+                await connection.addFlags([message.uid], [flagName]);
+            }
+            else {
+                await connection.removeFlags([message.uid], [flagName]);
+            }
+            // Confirmed IMAP acknowledgement — clears ONLY here, never on
+            // attempt (the defect issue #1273 fixes).
+            await markerService.delete(messageId, flagName);
+            log.info({
+                messageId,
+                flagName,
+                accountId,
+                operation: marker.operation,
+                uid: message.uid,
+                mailboxPath: mailbox.fullPath,
+            }, "Flag push confirmed on IMAP; marker cleared");
+        })
+            .catch(async (error) => {
+            // Expected pause (epic #1281 invariant 3), not a fault: ack and
+            // skip rather than propagating into queue retry/DLQ. The marker
+            // stays durable; the push resumes once the mailbox returns to
+            // normal.
+            if (error instanceof MailboxCursorPausedError) {
+                log.info({ messageId, flagName, accountId, cursorState: error.state }, "UIDVALIDITY changed; mailbox cursor tripped, pausing outbound flag push");
+                return;
+            }
+            if (receiveCount < config.attempts.flagPush) {
+                // Transient push failure — expected (connections drop). No
+                // alarm; queue redelivery retries from the still-durable marker.
+                throw error;
+            }
+            // Redelivery budget exhausted: resolve into exactly one of the
+            // two terminal outcomes (epic invariant 3) instead of
+            // dead-lettering with no diagnosis.
+            const { outcome } = await resolveExhaustedFlagPushFailure({ markerService, messageService, log }, {
+                placement: {
+                    status: message.status,
+                    mailboxId: message.mailboxId,
+                    uid: message.uid,
+                },
+                accountId,
+                accountConfigId,
+                messageId,
+                flagName,
+                uid: message.uid,
+                mailboxPath: mailbox.fullPath,
+                getConnection: scope.getConnection,
+            });
+            if (outcome === "reconciled") {
+                return;
+            }
+            // Terminal and never re-thrown, so the handler-outcome series
+            // records this record as a success. Counted here or it is invisible.
+            metrics.imapFailure("FLAG_PUSH_EXHAUSTED", "other", 1);
+            log.error({ error: error instanceof Error ? error.message : String(error) }, "Flag push retry exhausted; message still exists at its mailbox");
+            // Terminal — never re-thrown, so the caller acks either way.
+        })
+            .finally(() => scope.release());
+    });
+};

package/dist/handlers/imported-folder.d.ts

@@ -0,0 +1,4 @@
+import type { CreateImportedFolder } from "@remit/config-transfer";
+import type { IMailboxRepository } from "@remit/data-ports";
+import type { MailboxQueueService } from "@remit/mailbox-service";
+export declare const createImportedFolder: (mailbox: Pick<IMailboxRepository, "findByPath">, queue: Pick<MailboxQueueService, "createMailbox">) => CreateImportedFolder;

package/dist/handlers/imported-folder.js

@@ -0,0 +1,23 @@
+export const createImportedFolder = (mailbox, queue) => async (accountId, folderPath) => {
+    const inbox = await mailbox.findByPath(accountId, "INBOX");
+    if (!inbox) {
+        throw new Error(`Account ${accountId} has no INBOX to take a namespace from, so "${folderPath}" cannot be created`);
+    }
+    return queue.createMailbox({
+        accountId,
+        namespaceType: inbox.namespaceType,
+        namespacePrefix: inbox.namespacePrefix,
+        hierarchyDelimiter: inbox.hierarchyDelimiter,
+        fullPath: folderPath,
+        uidValidity: 0,
+        uidNext: 1,
+        highestModseq: "0",
+        messageCount: 0,
+        unseenCount: 0,
+        deletedCount: 0,
+        totalSize: 0,
+        lastSyncUid: 0,
+        highWaterMarkUid: 0,
+        lastMessageSyncAt: 0,
+    }, accountId, true);
+};

package/dist/handlers/mailbox-management.d.ts

@@ -0,0 +1,6 @@
+import type { ProcessContext } from "../context.js";
+import type { MailboxManagementEvent } from "../events.js";
+/**
+ * Process mailbox management events
+ */
+export declare const processMailboxManagement: (event: MailboxManagementEvent, ctx: ProcessContext) => Promise<void>;