@remit/mailbox-service 0.0.112 → 0.0.114

package/dist/ownership.d.ts

@@ -0,0 +1,24 @@
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import { type AccessMode, type Refusable } from "./refusal.js";
+export declare const ownedAccount: <A extends Pick<AccountItem, "accountId" | "accountConfigId">>(account: A, accountConfigId: string, mode: AccessMode) => Refusable<A>;
+export declare const folderInAccount: <M extends Pick<MailboxItem, "mailboxId" | "accountId">>(mailbox: M, accountId: string, mode: AccessMode) => Refusable<M>;
+export declare const settledFolder: <M extends Pick<MailboxItem, "mailboxId" | "fullPath" | "syncStatus">>(target: M) => Refusable<M>;
+export interface MessageOwnershipClient {
+    message: {
+        get(messageId: string): Promise<{
+            mailboxId: string;
+        }>;
+    };
+    mailbox: {
+        get(accountId: string, mailboxIds: string[]): Promise<{
+            mailboxId: string;
+            accountId: string;
+        }[]>;
+    };
+    account: {
+        listAllByAccountConfig(accountConfigId: string): Promise<{
+            accountId: string;
+        }[]>;
+    };
+}
+export declare const ownedMessages: (client: MessageOwnershipClient, messageIds: string[], callerAccountConfigId: string, mode: AccessMode) => Promise<Refusable<string>>;

package/dist/ownership.js

@@ -0,0 +1,83 @@
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { accept, invalid, refuse, } from "./refusal.js";
+// A read refuses with NotFound so another tenant's account does not leak its
+// existence; an action names the resource already, so it is refused outright.
+export const ownedAccount = (account, accountConfigId, mode) => {
+    if (account.accountConfigId === accountConfigId)
+        return accept(account);
+    if (mode === "read") {
+        return refuse({
+            kind: "NotFound",
+            message: `Account not found: ${account.accountId}`,
+        });
+    }
+    return refuse({
+        kind: "Forbidden",
+        message: `Account ${account.accountId} not in account config`,
+    });
+};
+// Owning the account in a path proves nothing about the mailboxId beside it.
+export const folderInAccount = (mailbox, accountId, mode) => {
+    if (mailbox.accountId === accountId)
+        return accept(mailbox);
+    if (mode === "read") {
+        return refuse({
+            kind: "NotFound",
+            message: `Mailbox not found: ${mailbox.mailboxId}`,
+        });
+    }
+    return refuse({
+        kind: "Forbidden",
+        message: `Mailbox ${mailbox.mailboxId} not in account`,
+    });
+};
+const UNSETTLED_REASON = {
+    [MailboxSyncStatus.pending]: (path) => `“${path}” isn’t ready yet — the mail server hasn’t confirmed it.`,
+    [MailboxSyncStatus.deleting]: (path) => `“${path}” is being deleted.`,
+    [MailboxSyncStatus.failed]: (path) => `The last change to “${path}” failed. Retry or dismiss it first.`,
+};
+// A durable reference binds only to a folder the mail server has confirmed
+// (imap-mutations R2: wait). This is the server-side floor under the client's
+// own wait, because a script calling the API directly gets no wait at all.
+export const settledFolder = (target) => {
+    const reason = UNSETTLED_REASON[target.syncStatus];
+    if (!reason)
+        return accept(target);
+    return refuse({
+        kind: "NotSettled",
+        message: reason(target.fullPath),
+        mailboxId: target.mailboxId,
+        syncStatus: target.syncStatus,
+    });
+};
+// Messages carry no tenant, so ownership resolves through the caller's own
+// accounts: a mailbox resolves only under the account that owns it, and the
+// whole batch must land on one account because the downstream services take
+// a single accountId.
+export const ownedMessages = async (client, messageIds, callerAccountConfigId, mode) => {
+    const messages = await Promise.all(messageIds.map((id) => client.message.get(id)));
+    const mailboxIds = [...new Set(messages.map((m) => m.mailboxId))];
+    const ownedAccounts = await client.account.listAllByAccountConfig(callerAccountConfigId);
+    const accountByMailbox = new Map();
+    for (const { accountId } of ownedAccounts) {
+        const rows = await client.mailbox.get(accountId, mailboxIds);
+        for (const row of rows) {
+            accountByMailbox.set(row.mailboxId, row.accountId);
+        }
+    }
+    if (mailboxIds.some((id) => !accountByMailbox.has(id))) {
+        if (mode === "read") {
+            return refuse({ kind: "NotFound", message: "Message not found" });
+        }
+        return refuse({
+            kind: "Forbidden",
+            message: "Message not in account config",
+        });
+    }
+    const accountIds = [...new Set(accountByMailbox.values())];
+    const [accountId] = accountIds;
+    if (accountIds.length !== 1 || accountId === undefined) {
+        return invalid("All messages must belong to the same account");
+    }
+    return accept(accountId);
+};

package/dist/placement-move-terminal.d.ts

@@ -0,0 +1,67 @@
+import type { IMessageRepository, MessageItem } from "@remit/data-ports";
+import type { PlacementMoveLogger } from "./placement-move.js";
+import { type RestoreSourcePlacementDeps } from "./restore-source-placement.js";
+import type { IImapConnection } from "./types.js";
+export interface ResolveExhaustedPlacementMoveDeps {
+    messageService: Pick<IMessageRepository, "deleteIfPlacement"> & RestoreSourcePlacementDeps["messageService"];
+    threadMessageService: RestoreSourcePlacementDeps["threadMessageService"];
+    markerService: {
+        delete(messageId: string): Promise<void>;
+    };
+    log: PlacementMoveLogger;
+}
+export interface ResolveExhaustedPlacementMoveInput {
+    /** 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;
+    uid: number;
+    sourceMailboxId: string;
+    sourceMailboxPath: string;
+    getConnection: () => Promise<IImapConnection>;
+}
+export type PlacementMoveTerminalOutcome = "reconciled" | "broken";
+export interface ResolveExhaustedPlacementMoveResult {
+    outcome: PlacementMoveTerminalOutcome;
+}
+/**
+ * Resolve a PLACEMENT_MOVE_PUSH failure that has exhausted the placement-move
+ * queue's redelivery budget into exactly one of two terminal outcomes,
+ * mirroring `resolveExhaustedBodySyncFailures` (#1270) for the same failure
+ * taxonomy (epic #1281 invariant 3) — no third, softer outcome.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at its pending-move
+ *    source on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather
+ *    than by a FETCH coming back empty. Per invariant 2, an external delete
+ *    supersedes the marker entirely: the marker is dropped and the stale
+ *    Message/ThreadMessage rows are deleted via
+ *    `deleteIfPlacement`. This is also the
+ *    outcome for the (rarer, functionally indistinguishable from here) case
+ *    where a foreign client moved the message elsewhere — either way, our
+ *    prediction no longer holds, and the marker cannot be honoured. Metric
+ *    only, no alarm — routine.
+ * 2. BROKEN — the message still exists at the source, but the move keeps
+ *    failing. This indicates broken code or a broken account (issue #1271),
+ *    not a transient blip. The row is put back on the source pair the server
+ *    has just confirmed, exactly as the move and delete resolvers do, and the
+ *    marker goes with it: an auto-file whose push gave up must not leave
+ *    `moving` plus the destination folder plus the source's uid standing
+ *    forever, because that pair refuses every later delete and move with a
+ *    409, blocks the sighting repair, and nothing else clears it. The failure
+ *    is an operator's to read, so it lives in the `alert`-shaped log entry and
+ *    the alarm on it — not in a row the user's own mail is stuck behind.
+ *    Never re-thrown (terminal — the caller acks either way, since retrying a
+ *    stale or permanently-broken move can never succeed).
+ *
+ * An operator reading `placement_move_failed` should know one case where the
+ * message is not actually at the source: a message another client expunged
+ * mid-session can answer an empty FETCH while the server still lists its UID
+ * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
+ * lands in BROKEN, and BROKEN is terminal — the alert stands until someone
+ * clears it, and the row goes back to a source the message may already have
+ * left. The reverse mistake deletes live mail, so the cost is paid
+ * deliberately: a stale alert over a row the next sync re-points is
+ * recoverable, a deleted message is not.
+ */
+export declare const resolveExhaustedPlacementMoveFailure: (deps: ResolveExhaustedPlacementMoveDeps, input: ResolveExhaustedPlacementMoveInput) => Promise<ResolveExhaustedPlacementMoveResult>;

package/dist/placement-move-terminal.js

@@ -0,0 +1,88 @@
+import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+import { restoreSourcePlacement, } from "./restore-source-placement.js";
+/**
+ * Resolve a PLACEMENT_MOVE_PUSH failure that has exhausted the placement-move
+ * queue's redelivery budget into exactly one of two terminal outcomes,
+ * mirroring `resolveExhaustedBodySyncFailures` (#1270) for the same failure
+ * taxonomy (epic #1281 invariant 3) — no third, softer outcome.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at its pending-move
+ *    source on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather
+ *    than by a FETCH coming back empty. Per invariant 2, an external delete
+ *    supersedes the marker entirely: the marker is dropped and the stale
+ *    Message/ThreadMessage rows are deleted via
+ *    `deleteIfPlacement`. This is also the
+ *    outcome for the (rarer, functionally indistinguishable from here) case
+ *    where a foreign client moved the message elsewhere — either way, our
+ *    prediction no longer holds, and the marker cannot be honoured. Metric
+ *    only, no alarm — routine.
+ * 2. BROKEN — the message still exists at the source, but the move keeps
+ *    failing. This indicates broken code or a broken account (issue #1271),
+ *    not a transient blip. The row is put back on the source pair the server
+ *    has just confirmed, exactly as the move and delete resolvers do, and the
+ *    marker goes with it: an auto-file whose push gave up must not leave
+ *    `moving` plus the destination folder plus the source's uid standing
+ *    forever, because that pair refuses every later delete and move with a
+ *    409, blocks the sighting repair, and nothing else clears it. The failure
+ *    is an operator's to read, so it lives in the `alert`-shaped log entry and
+ *    the alarm on it — not in a row the user's own mail is stuck behind.
+ *    Never re-thrown (terminal — the caller acks either way, since retrying a
+ *    stale or permanently-broken move can never succeed).
+ *
+ * An operator reading `placement_move_failed` should know one case where the
+ * message is not actually at the source: a message another client expunged
+ * mid-session can answer an empty FETCH while the server still lists its UID
+ * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
+ * lands in BROKEN, and BROKEN is terminal — the alert stands until someone
+ * clears it, and the row goes back to a source the message may already have
+ * left. The reverse mistake deletes live mail, so the cost is paid
+ * deliberately: a stale alert over a row the next sync re-points is
+ * recoverable, a deleted message is not.
+ */
+export const resolveExhaustedPlacementMoveFailure = async (deps, input) => {
+    const { accountId, accountConfigId, messageId, uid, sourceMailboxId, sourceMailboxPath, getConnection, } = input;
+    const connection = await getConnection();
+    await connection.openBox(sourceMailboxPath);
+    if (await isMessageGoneFromOpenMailbox(connection, uid)) {
+        await deps.markerService.delete(messageId);
+        const reconciled = await deps.messageService.deleteIfPlacement(messageId, input.placement);
+        deps.log.info({
+            metric: "placement_move_stale_row_reconciled",
+            accountId,
+            accountConfigId,
+            messageId,
+            uid,
+            sourceMailboxPath,
+            reconciled,
+        }, "Message no longer at its pending-move source after retry exhaustion (external delete or move); marker dropped, stale row reconciled");
+        return { outcome: "reconciled" };
+    }
+    // The row first, the marker second. The marker is the operator's evidence
+    // that this move still owed IMAP a push; dropping it before the restore
+    // means a restore that throws leaves the row stuck `moving` with nothing
+    // left to say why.
+    await restoreSourcePlacement(deps, {
+        accountConfigId,
+        messageId,
+        sourceMailboxId,
+        uid,
+        // No give-up marker: this move is Remit's own classification filing, not
+        // something the user asked for, so a per-message "your move failed" would
+        // report a failure against an intent nobody formed. The alert below is the
+        // whole surface, and it is an operator's.
+        syncStatus: MessageSyncStatus.synced,
+        abandonedMutation: MessageMutation.none,
+    });
+    await deps.markerService.delete(messageId);
+    deps.log.error({
+        alert: "placement_move_failed",
+        accountId,
+        accountConfigId,
+        messageId,
+        uid,
+        sourceMailboxId,
+        sourceMailboxPath,
+    }, "Placement move could not be pushed to IMAP after retry exhaustion; message still exists at its source — row restored to the source pair, marker dropped, alert left for operator investigation");
+    return { outcome: "broken" };
+};

package/dist/placement-move.d.ts

@@ -0,0 +1,83 @@
+import type { IAddressRepository, IMailboxRepository, IMailboxSpecialUseRepository, IMessagePlacementMoveRepository, IMessageRepository, IThreadMessageRepository, QueueProducer } from "@remit/data-ports";
+/**
+ * Event the reconciler (imap-worker `handlePlacementMovePush`) drains. Carries
+ * ONLY our own message id — never a UID (epic #1281 invariant 1). The UID is
+ * resolved fresh from the Message row at push time, so the event stays valid
+ * across any amount of queue delay or an unrelated UIDVALIDITY rebuild
+ * (#1272).
+ */
+export interface PlacementMovePushEvent {
+    type: "PLACEMENT_MOVE_PUSH";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    accountConfigId: string;
+    messageId: string;
+}
+/** Whether a filing happened. `refused` names a destination outside the message's account. */
+export type PlacementMoveOutcome = "filed" | "skipped" | "refused";
+export interface PlacementMoveLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+export interface PlacementMoveConfig {
+    messageService: IMessageRepository;
+    threadMessageService: IThreadMessageRepository;
+    markerService: IMessagePlacementMoveRepository;
+    addressService: IAddressRepository;
+    /**
+     * Required, not optional: this mover carries automatic spam placement, and
+     * one built without the folder-role seam would silently leave the sender of
+     * every auto-filed spam suggestible in the compose picker.
+     */
+    mailboxSpecialUseService: IMailboxSpecialUseRepository;
+    mailboxService: Pick<IMailboxRepository, "resolveAccountId">;
+    queue: QueueProducer<PlacementMovePushEvent>;
+    logger?: PlacementMoveLogger;
+    moveSettleTimeoutMs?: number;
+    moveSettlePollMs?: number;
+}
+/**
+ * Local-first mover for a classification-driven placement move (issue #1271,
+ * epic #1281). Distinct from {@link MessageMoveService} (user-initiated
+ * moves/deletes/copies), which is untouched by this fix — the epic's UID
+ * staleness invariant (1) only applies to the NEW reconciler this class
+ * feeds; generalizing it to every move type is out of scope here.
+ *
+ * `moveMessage` matches {@link MessageMoveService.moveMessage}'s signature so
+ * `BodySyncService`'s existing rescue/demote call site and its tests need no
+ * shape changes beyond the dependency's name.
+ *
+ * Ordering is the fix: every step below (marker, ThreadMessage, Message row,
+ * SQS enqueue) completes — or the whole call rejects — BEFORE the caller
+ * (`BodySyncService.storeStreamedBody`) writes `bodyStorageKey`. A rejection
+ * here therefore always happens before the body-sync skip-guard can trip, so
+ * a retry reprocesses the message from scratch. Nothing here is swallowed —
+ * let it crash, same as any other infra failure (an SQS enqueue failure is a
+ * serious operational failure, not a routine blip: it propagates so a
+ * repeated failure reaches the alarmed message-mgmt DLQ, never absorbed).
+ *
+ * Recovery is driven by the marker's explicit state engine (`pending ->
+ * queued -> processing -> processed`, `MessagePlacementMoveState`), not by
+ * comparing the message's current location against the requested
+ * destination — that comparison alone cannot tell "already confirmed" apart
+ * from "local move landed but the enqueue never did" (the defect this issue
+ * originally fixes). A retry always re-fetches the marker and drives it
+ * forward from whichever state it is actually in.
+ */
+export declare class PlacementMoveService {
+    private messageService;
+    private threadMessageService;
+    private markerService;
+    private addressService;
+    private mailboxSpecialUseService;
+    private mailboxService;
+    private queue;
+    private log;
+    private moveSettleTimeoutMs;
+    private moveSettlePollMs;
+    constructor(config: PlacementMoveConfig);
+    moveMessage: (accountConfigId: string, messageId: string, destinationMailboxId: string, accountId: string) => Promise<PlacementMoveOutcome>;
+    private updateThreadMessageMailbox;
+    private enqueuePush;
+}

package/dist/placement-move.js

@@ -0,0 +1,216 @@
+import { randomUUID } from "node:crypto";
+import { MessageMutation, MessageStatus, MessageSyncStatus, } from "@remit/domain-enums";
+import { isPlacementUnsettled, waitForPlacementToSettle, } from "./placement-settled.js";
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
+const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
+/**
+ * Local-first mover for a classification-driven placement move (issue #1271,
+ * epic #1281). Distinct from {@link MessageMoveService} (user-initiated
+ * moves/deletes/copies), which is untouched by this fix — the epic's UID
+ * staleness invariant (1) only applies to the NEW reconciler this class
+ * feeds; generalizing it to every move type is out of scope here.
+ *
+ * `moveMessage` matches {@link MessageMoveService.moveMessage}'s signature so
+ * `BodySyncService`'s existing rescue/demote call site and its tests need no
+ * shape changes beyond the dependency's name.
+ *
+ * Ordering is the fix: every step below (marker, ThreadMessage, Message row,
+ * SQS enqueue) completes — or the whole call rejects — BEFORE the caller
+ * (`BodySyncService.storeStreamedBody`) writes `bodyStorageKey`. A rejection
+ * here therefore always happens before the body-sync skip-guard can trip, so
+ * a retry reprocesses the message from scratch. Nothing here is swallowed —
+ * let it crash, same as any other infra failure (an SQS enqueue failure is a
+ * serious operational failure, not a routine blip: it propagates so a
+ * repeated failure reaches the alarmed message-mgmt DLQ, never absorbed).
+ *
+ * Recovery is driven by the marker's explicit state engine (`pending ->
+ * queued -> processing -> processed`, `MessagePlacementMoveState`), not by
+ * comparing the message's current location against the requested
+ * destination — that comparison alone cannot tell "already confirmed" apart
+ * from "local move landed but the enqueue never did" (the defect this issue
+ * originally fixes). A retry always re-fetches the marker and drives it
+ * forward from whichever state it is actually in.
+ */
+export class PlacementMoveService {
+    messageService;
+    threadMessageService;
+    markerService;
+    addressService;
+    mailboxSpecialUseService;
+    mailboxService;
+    queue;
+    log;
+    moveSettleTimeoutMs;
+    moveSettlePollMs;
+    constructor(config) {
+        this.messageService = config.messageService;
+        this.threadMessageService = config.threadMessageService;
+        this.markerService = config.markerService;
+        this.addressService = config.addressService;
+        this.mailboxSpecialUseService = config.mailboxSpecialUseService;
+        this.mailboxService = config.mailboxService;
+        this.queue = config.queue;
+        this.log = config.logger ?? noopLogger;
+        this.moveSettleTimeoutMs =
+            config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
+        this.moveSettlePollMs =
+            config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
+    }
+    moveMessage = async (accountConfigId, messageId, destinationMailboxId, accountId) => {
+        let message = await this.messageService.get(messageId);
+        // Recovery: a marker already exists for THIS message and destination —
+        // from an earlier (possibly partially-failed) call. The marker's STATE,
+        // not a comparison against the message's current location, decides what
+        // happens next (PR #1289 review finding 1 + design amendment: an
+        // explicit pending -> queued -> processing -> processed engine).
+        const existingMarker = await this.markerService.find(messageId);
+        if (existingMarker &&
+            existingMarker.destinationMailboxId === destinationMailboxId) {
+            if (existingMarker.state === "pending") {
+                // Local move + marker already committed; only the enqueue is
+                // missing (or a further retry after the enqueue itself failed
+                // again). Drive the SAME marker forward — never re-derive the
+                // local move, which already happened.
+                await this.enqueuePush({ accountId, accountConfigId, messageId });
+                await this.markerService.updateState(messageId, "queued");
+                this.log.info({ messageId, accountId, destinationMailboxId }, "Pending marker survived an earlier enqueue failure; re-enqueued and advanced to queued");
+            }
+            // queued / processing / processed already has its own driver in
+            // flight (the SQS message, or the reconciler currently running) —
+            // nothing to do here either way.
+            return "filed";
+        }
+        // A different destination, decided while an earlier move is still
+        // unconfirmed (issue #496): the row names that move's destination but its
+        // `uid` still belongs to the folder before it, so a marker bound to the
+        // pair as it stands sends the reconciler to move the destination folder's
+        // OWN message at that uid. Wait for the earlier move to confirm and bind
+        // to the settled row (docs/architecture/imap-mutations.md R2). Blocking is
+        // cheap — a move settles in well under a second — and on timeout the
+        // dependent write is simply not made.
+        // A delete in flight is not a move to wait out: the user has asked for the
+        // message to go, and a classification filing behind it has nothing left to
+        // file. Skipping is the answer, and it is a clean one — throwing would
+        // burn the ceiling and then drive an ordinary sequence toward the DLQ.
+        if (message.status === MessageStatus.deleting) {
+            this.log.info({ messageId, accountId, destinationMailboxId }, "Placement move not applied: this message is being deleted");
+            return "skipped";
+        }
+        if (isPlacementUnsettled(message)) {
+            message = await waitForPlacementToSettle(this.messageService, messageId, {
+                timeoutMs: this.moveSettleTimeoutMs,
+                pollMs: this.moveSettlePollMs,
+            });
+            if (message.status === MessageStatus.deleting) {
+                this.log.info({ messageId, accountId, destinationMailboxId }, "Placement move not applied: a delete claimed this message while the earlier move settled");
+                return "skipped";
+            }
+            if (isPlacementUnsettled(message)) {
+                throw new Error(`Placement move for ${messageId} to ${destinationMailboxId} not applied: an earlier move has not settled`);
+            }
+        }
+        const sourceMailboxId = message.mailboxId;
+        // Genuine no-op: nothing pending for this destination, and the message
+        // is already there (a duplicate verdict recomputed after a confirmed
+        // move).
+        if (sourceMailboxId === destinationMailboxId)
+            return "skipped";
+        // IMAP has no MOVE between accounts, so a filing into a folder this
+        // account does not own would only ever be handed back.
+        if ((await this.mailboxService.resolveAccountId(destinationMailboxId)) !==
+            accountId) {
+            this.log.error({
+                alert: "placement_move_foreign_folder",
+                messageId,
+                accountId,
+                sourceMailboxId,
+                destinationMailboxId,
+            }, "Placement move refused: the destination is not a folder of this message's account");
+            return "refused";
+        }
+        // Fresh move. Strictly sequential — nothing here is parallel: the local
+        // move (marker + ThreadMessage + Message row) fully commits BEFORE the
+        // queue kick runs. `put` is idempotent and always resets `state` back to
+        // `pending`, since a fresh decision starts a new lifecycle regardless of
+        // what a stale row (different destination) held.
+        await this.markerService.put({
+            messageId,
+            accountId,
+            accountConfigId,
+            sourceMailboxId,
+            destinationMailboxId,
+        });
+        // The Message row first, the listing row after it — the order the user
+        // move and the delete already use. A transition off the row the wait above
+        // settled on (imap-mutations R3): this lane rides a standard queue that
+        // the account's FIFO group does not order, so a user's own move or delete
+        // can claim the row between that read and this write, and writing anyway
+        // would stamp Remit's classification over a folder the user just chose,
+        // with the old uid attached.
+        //
+        // Writing the listing row first meant a loser left the two disagreeing —
+        // the listing showing the classification folder while the Message row sat
+        // where the winner put it — and nothing routine reconciles that.
+        //
+        // The marker goes with the loss. It is the record that a move owes IMAP a
+        // push, and this move is not happening, so leaving it would send the
+        // reconciler after a placement nobody wrote and would inflate the folder
+        // counts it predicts.
+        const filed = await this.messageService.transitionPlacement(messageId, {
+            status: MessageStatus.active,
+            mailboxId: sourceMailboxId,
+            uid: message.uid,
+        }, {
+            mailboxId: destinationMailboxId,
+            status: MessageStatus.moving,
+            syncStatus: MessageSyncStatus.pending,
+            abandonedMutation: MessageMutation.none,
+            originalMailboxId: sourceMailboxId,
+            originalUid: message.uid,
+        });
+        if (!filed) {
+            await this.markerService.delete(messageId);
+            this.log.info({ messageId, accountId, sourceMailboxId, destinationMailboxId }, "Placement move not applied: something else claimed this message's placement first");
+            return "skipped";
+        }
+        await this.updateThreadMessageMailbox(accountConfigId, messageId, destinationMailboxId);
+        await this.addressService.reconcileJunkOnlyForMessage(messageId, await this.mailboxSpecialUseService.resolveJunkRolesForConfig(accountConfigId));
+        // The queue kick is a serious operational step, not a routine one — a
+        // failure here MUST propagate (never swallowed): the marker stays
+        // `pending`, the surrounding body-sync call fails, SQS redelivers, and
+        // a repeated failure reaches the alarmed message-mgmt DLQ. The state
+        // engine makes this *recoverable* (the recovery branch above drives a
+        // surviving `pending` marker forward on the next call) — it must never
+        // make it *quiet*.
+        await this.enqueuePush({ accountId, accountConfigId, messageId });
+        await this.markerService.updateState(messageId, "queued");
+        this.log.info({ messageId, accountId, sourceMailboxId, destinationMailboxId }, "Placement move applied locally; pending marker queued for IMAP push");
+        return "filed";
+    };
+    updateThreadMessageMailbox = async (accountConfigId, messageId, destinationMailboxId) => {
+        const threadMessage = await this.threadMessageService.getByMessageId(accountConfigId, messageId);
+        await this.threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, { mailboxId: destinationMailboxId }, {
+            composites: {
+                sentDate: threadMessage.sentDate,
+                mailboxId: threadMessage.mailboxId,
+                isRead: threadMessage.isRead,
+                isDeleted: threadMessage.isDeleted,
+                hasStars: threadMessage.hasStars,
+                hasAttachment: threadMessage.hasAttachment,
+            },
+        });
+    };
+    enqueuePush = async (params) => {
+        const event = {
+            type: "PLACEMENT_MOVE_PUSH",
+            eventId: randomUUID(),
+            timestamp: Date.now(),
+            ...params,
+        };
+        await this.queue.send({ body: event });
+    };
+}