@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/message-sync.js

@@ -0,0 +1,1358 @@
+import { storedDisplayName } from "@remit/data-ports/display-name";
+import { deriveAddressId, deriveBodyPartId, deriveCopyMessageId, deriveEnvelopeId, deriveMessageId, deriveMessageIdFromSource, deriveThreadId, isValidMessageId, wireMessageId, } from "@remit/data-ports/id";
+import { AddressRole, MailboxCursorState, MessageKeywordFlag, MessageSystemFlag, StarColor, SyncWarningStage, } from "@remit/domain-enums";
+import pMap from "p-map";
+import { confirmDepartures, placementKey, sightingContestsPlacement, } from "./external-move.js";
+import { guardMailboxCursor, isCursorRebuildNeeded } from "./mailbox-cursor.js";
+import { matchCursorRebuild, } from "./mailbox-cursor-rebuild.js";
+import { ROOT_PART_PATH, walkMimeStructure } from "./mime-walker.js";
+import { advanceChangeCursor, advanceUidWatermarks, dropAppliedPrefix, formatChangeCursor, hasChangeCursor, orderByModseq, parseChangeCursor, parseModseq, } from "./sync-watermarks.js";
+import { messageReferencesOf, parentOf, threadRootOf } from "./thread-root.js";
+const MESSAGE_SAVE_CONCURRENCY = 10;
+// Some IMAP servers (e.g. Hostnet) emit these literal placeholders in the
+// ENVELOPE when they cannot parse a From header, instead of leaving the
+// address parts empty.
+const HOSTNET_MISSING_MAILBOX = "missing_mailbox";
+const HOSTNET_MISSING_DOMAIN = "missing_domain";
+/**
+ * A From address is only usable when it looks like a real mailbox: both parts
+ * present, neither is a known "could not parse" sentinel, and the host carries
+ * an actual domain (at least one dot). Detect this structurally so a fabricated
+ * string like `missing_mailbox@missing_domain` is never persisted as a sender.
+ */
+export const isParseableEmailAddress = (address) => {
+    if (!address)
+        return false;
+    const mailbox = address.mailbox?.trim();
+    const host = address.host?.trim();
+    if (!mailbox || !host)
+        return false;
+    if (mailbox === HOSTNET_MISSING_MAILBOX || host === HOSTNET_MISSING_DOMAIN) {
+        return false;
+    }
+    return host.includes(".");
+};
+/**
+ * What a sighting of an address in this mailbox is worth. Junk withholds the
+ * sender from autocomplete (#822), Trash decides nothing either way, and
+ * anywhere else is a correspondent.
+ *
+ * Decided by mailbox IDENTITY against the account's resolved roles, not by the
+ * folder's flag and name: a role belongs to exactly one folder (RFC 032), and
+ * the folder it belongs to is whichever one the user appointed. Reading the
+ * name here meant a second folder called `Spam` also withheld its senders,
+ * while the folder the user actually appointed harvested every spammer in it as
+ * a correspondent (#837).
+ */
+export const addressSightingIn = (mailboxId, roles) => {
+    if (roles.junkMailboxId !== null && mailboxId === roles.junkMailboxId) {
+        return "junk";
+    }
+    if (roles.trashMailboxId !== null && mailboxId === roles.trashMailboxId) {
+        return "discarded";
+    }
+    return "correspondent";
+};
+/**
+ * The name an envelope carries for an address, as it should be stored: any
+ * claim to be some other address removed (issue #826), the rest of the name
+ * kept. Refused wherever a name lands — the address book, the envelope the
+ * message header renders, and the sender label on the thread row.
+ */
+export const harvestedDisplayName = (address) => {
+    if (!address?.name)
+        return "";
+    return storedDisplayName(address.name, `${address.mailbox}@${address.host}`);
+};
+/**
+ * Parse an external `Date:` header into an epoch-millisecond integer.
+ *
+ * The IMAP envelope `date` is a raw RFC 2822 header copied verbatim from the
+ * message. It can be missing, malformed, or in a format `Date` cannot parse —
+ * `new Date(raw).getTime()` then yields `NaN`. `NaN` is not a valid integer
+ * and ElectroDB rejects it, which previously threw on the envelope upsert and
+ * (because the batch aborted on the first rejection) stalled the whole mailbox.
+ *
+ * When the header is unparseable we fall back to `fallbackMs` — the IMAP
+ * server's own INTERNALDATE receive time, always a valid integer. The raw
+ * header is preserved separately in `dateRaw`, so nothing is lost.
+ */
+export const parseHeaderDate = (raw, fallbackMs) => {
+    if (raw !== undefined && raw !== "") {
+        const parsed = new Date(raw).getTime();
+        if (Number.isFinite(parsed)) {
+            return { value: parsed, usedFallback: false };
+        }
+    }
+    return { value: fallbackMs, usedFallback: true };
+};
+const noopLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * The UIDs of this batch's undecided sightings (#1146). They join `failedUids`
+ * for the same reason a save that threw does: the watermark is the only thing
+ * that brings a UID back, and a sighting the round could not settle has to come
+ * back. A round that keeps failing to settle one trips the stalled-cursor alert,
+ * which is the surface for a source folder that has become unaskable.
+ */
+const unresolvedSightingUids = (outcomes) => outcomes.flatMap((outcome) => outcome.kind === "saved" &&
+    outcome.result !== null &&
+    outcome.result.unresolvedSighting
+    ? [outcome.uid]
+    : []);
+const syncedUidsOf = (outcomes) => outcomes.flatMap((outcome) => outcome.kind === "saved" && !outcome.result?.unresolvedSighting
+    ? [outcome.uid]
+    : []);
+const saveFailedUidsOf = (outcomes) => outcomes.flatMap((outcome) => outcome.kind === "failed" ? [outcome.uid] : []);
+const envelopeLessUidsOf = (messages) => messages.flatMap((msg) => (hasEnvelope(msg) ? [] : [msg.uid]));
+const emptySyncResult = () => ({
+    syncedCount: 0,
+    syncedMessageIds: [],
+    syncedMessages: [],
+    hasMore: false,
+    remainingCount: 0,
+    cursorStalled: false,
+});
+/**
+ * Pick the UIDs a full-enumeration round should sync, newest first.
+ *
+ * 1. New messages: UIDs above the forward watermark.
+ * 2. Backfill: UIDs below the lowest one synced so far.
+ * 3. A mailbox with no watermarks at all syncs everything.
+ */
+export const selectUidsToSync = (allUids, lastSyncUid, highWaterMarkUid) => {
+    const newUids = allUids.filter((uid) => uid > highWaterMarkUid);
+    const backfillUids = lastSyncUid > 1 ? allUids.filter((uid) => uid < lastSyncUid) : [];
+    const isFreshSync = highWaterMarkUid === 0 && lastSyncUid === 0;
+    const uidsToSync = isFreshSync ? [...allUids] : [...newUids, ...backfillUids];
+    return uidsToSync.sort((a, b) => b - a);
+};
+/** A FETCH row that names a message: everything downstream needs the envelope. */
+const hasEnvelope = (msg) => msg.envelope !== undefined;
+/**
+ * The row identity a sighting resolves to. Folder-independent whenever the
+ * message carries a usable `Message-ID` header, which is what lets the same
+ * mail in two of an account's folders meet on one row.
+ */
+const messageIdForSighting = (accountId, mailboxId, msg) => deriveMessageIdFromSource(accountId, {
+    messageId: msg.envelope.messageId,
+    uid: msg.uid,
+    mailboxId,
+    date: msg.envelope.date,
+    subject: msg.envelope.subject,
+    fromMailbox: msg.envelope.from?.[0]?.mailbox,
+    fromHost: msg.envelope.from?.[0]?.host,
+});
+export class MessageSyncService {
+    connectionFactory;
+    mailboxService;
+    mailboxSpecialUseService;
+    messageService;
+    envelopeService;
+    addressService;
+    threadMessageService;
+    syncWarningService;
+    flagPushMarkerService;
+    messageFlagService;
+    quarantineService;
+    log;
+    constructor(connectionFactory, mailboxService, 
+    /**
+     * The account’s folder-role map. Required, not optional: which folder
+     * holds the Junk role decides whether a sighting withholds its sender
+     * from autocomplete, and a construction without it would quietly harvest
+     * spammers as correspondents.
+     */
+    mailboxSpecialUseService, messageService, envelopeService, addressService, threadMessageService, syncWarningService, logger, 
+    /**
+     * Pending outbound flag-push markers (#1273). Supplied, an inbound
+     * metadata change never overwrites a local flip that IMAP has not been
+     * told about yet; omitted, the server always wins.
+     */
+    flagPushMarkerService, 
+    /**
+     * The canonical flag record. Supplied, an inbound metadata change lands
+     * on the same record the outbound flip path reads, so a user's next
+     * flip is never dismissed as redundant.
+     */
+    messageFlagService, 
+    /**
+     * The set of messages already set aside (issue #72). Message sync never
+     * writes a record — only the body path can attribute a failure to the
+     * message — but it reads the set so a uid the body path quarantined is
+     * not re-fetched on every round.
+     */
+    quarantineService) {
+        this.connectionFactory = connectionFactory;
+        this.mailboxService = mailboxService;
+        this.mailboxSpecialUseService = mailboxSpecialUseService;
+        this.messageService = messageService;
+        this.envelopeService = envelopeService;
+        this.addressService = addressService;
+        this.threadMessageService = threadMessageService;
+        this.syncWarningService = syncWarningService;
+        this.flagPushMarkerService = flagPushMarkerService;
+        this.messageFlagService = messageFlagService;
+        this.quarantineService = quarantineService;
+        this.log = logger ?? noopLogger;
+    }
+    /**
+     * Sync ONE batch of messages for a mailbox using newest-first strategy.
+     *
+     * Uses dual-watermark tracking:
+     * - highWaterMarkUid: highest UID ever seen (detects new messages)
+     * - lastSyncUid: lowest UID processed (tracks backfill progress)
+     *
+     * Returns hasMore=true if there are more messages to sync. The caller
+     * should re-enqueue another sync event to continue processing.
+     *
+     * @param mailboxId - The database mailbox ID
+     * @param accountId - The account ID (scopes message/thread identity)
+     * @param accountConfigId - The account config ID (used for address linking)
+     * @param batchSize - Number of messages to process per batch
+     */
+    async syncMessages(mailboxId, accountId, accountConfigId, batchSize = 50) {
+        const mailbox = await this.mailboxService.get(accountId, mailboxId);
+        const mailboxPath = mailbox.fullPath;
+        // A mailbox whose cursor is already invalid (or a rebuild that crashed
+        // mid-way, #1272) never falls through to the normal watermark-based sync
+        // below — stored UIDs on that axis are not trustworthy. The rebuild is a
+        // variant of sync, not a special wipe path, so it runs here under the
+        // same mailbox lock the caller already holds.
+        if (isCursorRebuildNeeded(mailbox.cursorState)) {
+            return this.rebuildCursor(mailbox, accountId, accountConfigId, mailboxId);
+        }
+        const lastSyncUid = mailbox.lastSyncUid || 0;
+        const highWaterMarkUid = mailbox.highWaterMarkUid || 0;
+        const connection = this.connectionFactory.getConnection();
+        const box = await connection.openBox(mailboxPath);
+        const status = await connection.getMailboxStatus(mailboxPath);
+        // Detection: the served UIDVALIDITY may have changed since it was last
+        // stored, even though this mailbox was `normal` a moment ago. Trip the
+        // cursor and pause — every stored watermark, the mod-sequence included,
+        // is meaningless on the new axis, so nothing below may be acted on this
+        // round (epic #1281 invariants 3 and 5). The rebuild that follows is
+        // where the mod-sequence is reseeded from the new axis.
+        const cursorCheck = await guardMailboxCursor({ mailboxService: this.mailboxService }, accountId, mailbox, box.uidvalidity);
+        if (!cursorCheck.ok) {
+            this.log.warn({ mailboxId, mailboxPath, cursorState: cursorCheck.state }, "UIDVALIDITY changed; mailbox cursor tripped, pausing outbound sync this round");
+            return emptySyncResult();
+        }
+        if (await this.restoreMissingStructure(mailbox, accountId, accountConfigId, batchSize)) {
+            await connection.openBox(mailboxPath);
+        }
+        const cursor = parseChangeCursor(mailbox.highestModseq);
+        if (hasChangeCursor(cursor) && connection.supportsCondstore()) {
+            return this.syncChangedSince({
+                mailbox,
+                accountId,
+                accountConfigId,
+                cursor,
+                box,
+                status,
+                batchSize,
+            });
+        }
+        // One read per round, not per message (issue #72). The list is small by
+        // design — a growing one is a bug being reported, not a page to paginate.
+        const quarantined = await this.quarantineService?.load(accountConfigId);
+        const allUids = await connection.search(["ALL"]);
+        const uids = selectUidsToSync(allUids, lastSyncUid, highWaterMarkUid);
+        const unseenCount = status.unseen;
+        const deletedCount = status.deletedCount;
+        if (uids.length === 0) {
+            await this.settleHeaderWarnings(accountConfigId, mailbox, box.uidvalidity, {
+                failedUids: [],
+                syncedUids: [],
+                serverUids: { kind: "Listed", uids: allUids },
+            });
+            // Nothing left to enumerate: the folder is fully covered on this
+            // UIDVALIDITY axis, which is the one moment a mod-sequence watermark
+            // can be seeded without hiding unsynced history behind it. From the
+            // next round on, this mailbox takes the CHANGEDSINCE path above.
+            await this.mailboxService.update(accountId, mailboxId, {
+                lastMessageSyncAt: Date.now(),
+                uidValidity: box.uidvalidity,
+                messageCount: status.messages,
+                highestModseq: status.highestModseq,
+                unseenCount,
+                deletedCount,
+            });
+            this.log.info({
+                mailboxId,
+                mailboxPath,
+                total: 0,
+                messageCount: status.messages,
+                unseenCount,
+                highestModseq: status.highestModseq,
+            }, "No new messages to sync");
+            return emptySyncResult();
+        }
+        const totalBatches = Math.ceil(uids.length / batchSize);
+        this.log.info({ mailboxId, mailboxPath, total: uids.length, batches: totalBatches }, "Starting message sync batch (newest first)");
+        // Process only the first batch
+        const batchUids = uids.slice(0, batchSize);
+        // A quarantined UID is not fetched again, but it stays in `batchUids` so
+        // the watermark still advances over it. Filtering it out of the selection
+        // instead would hold the watermark below a message that is already
+        // durably resolved, which is the stall by another route.
+        const fetchUids = batchUids.filter((uid) => !quarantined?.has(mailboxId, box.uidvalidity, uid));
+        const messages = fetchUids.length > 0 ? await this.fetchMessageBatch(fetchUids) : [];
+        // A UID the round could not act on. Two shapes reach here and neither is
+        // the message's fault: the FETCH returned no row at all (the connection
+        // layer drops rows imapflow yields without a usable UID or INTERNALDATE,
+        // #408, and a message can be expunged between the SEARCH and the FETCH),
+        // or it returned a row carrying no ENVELOPE, which names no message and
+        // is the same client-side glitch one field further in.
+        //
+        // They join `failedUids` rather than merely being left out of the batch.
+        // Absence alone does not hold a watermark: `advanceUidWatermarks` takes
+        // the MAX of what was applied, so a gap in the middle of a batch is
+        // stepped straight over — [23, 22, 21] with 22 missing still advances to
+        // 23 and loses 22 for good. A failure is the one thing a watermark is
+        // built to stop below.
+        const applicable = messages.filter(hasEnvelope);
+        const unusableUids = batchUids.filter((uid) => !applicable.some((msg) => msg.uid === uid) &&
+            !quarantined?.has(mailboxId, box.uidvalidity, uid));
+        if (unusableUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, unusableUids }, "FETCH returned no usable row for some requested UIDs; holding the watermark below them");
+        }
+        // Process messages in parallel with concurrency limit. `stopOnError` stays
+        // at its default — but each message is saved through `trySaveMessage`,
+        // which catches its own error and reports a `failed` outcome instead of
+        // rejecting. So one bad message can no longer abort the whole batch (the
+        // poison pill that previously froze the mailbox, #817).
+        const roles = await this.folderRolesFor(accountId, accountConfigId);
+        const departures = await this.probeDepartures(mailbox, accountId, applicable);
+        const outcomes = await pMap(applicable, (msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg, roles, departures), { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        // Body-sync set: only rows created or owned by THIS mailbox. A residual
+        // cross-mailbox collision (same deterministic messageId already owned by a
+        // different mailbox) must not push a foreign-owned messageId into
+        // syncedMessageIds, or body-sync would FETCH against the wrong mailbox's UID.
+        const ownedResults = outcomes.flatMap((o) => o.kind === "saved" && o.result !== null && o.result.owned
+            ? [o.result]
+            : []);
+        const syncedMessages = ownedResults.map(({ messageId, uid }) => ({ messageId, uid }));
+        const syncedMessageIds = syncedMessages.map((m) => m.messageId);
+        // UIDs whose save threw. They must stay inside the next cycle's fetch
+        // window, so the watermark may not advance past them (no silent loss).
+        const saveFailedUids = outcomes.flatMap((o) => o.kind === "failed" ? [o.uid] : []);
+        if (saveFailedUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, failedUids: saveFailedUids }, "Some messages failed to save; holding watermark below them for retry");
+        }
+        const unresolvedUids = unresolvedSightingUids(outcomes);
+        if (unresolvedUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, unresolvedUids }, "Some sightings reached no verdict about the folder their row points at; holding the watermark below them");
+        }
+        const failedUids = new Set([
+            ...saveFailedUids,
+            ...unusableUids,
+            ...unresolvedUids,
+        ]);
+        // Watermarks advance over every SUCCESSFULLY-consumed UID in the batch,
+        // independent of ownership. `selectUidsToSync` reselects work purely by UID
+        // vs watermark (there is no per-UID processed set), so a foreign-owned UID
+        // that did not advance the watermark would be re-fetched every cycle
+        // forever. The same Message-ID legitimately appears in several of one
+        // account's mailboxes (Gmail All Mail + INBOX/labels), so cross-mailbox
+        // conflicts are routine; excluding them from body-sync is correct, stalling
+        // forward sync is not. Failures are what a watermark may never pass —
+        // see `advanceUidWatermarks`.
+        const { highWaterMarkUid: newHighWaterMark, lastSyncUid: newLastSyncUid } = advanceUidWatermarks({
+            batchUids,
+            failedUids,
+            lastSyncUid,
+            highWaterMarkUid,
+        });
+        const remainingCount = uids.length - batchUids.length;
+        const hasMore = remainingCount > 0;
+        // The mod-sequence watermark is seeded only by a round that leaves no
+        // enumeration work behind and lost no message to a failed save. Seeding
+        // it earlier would switch the mailbox to CHANGEDSINCE while UIDs it has
+        // never fetched still sit below the watermark, and those messages would
+        // never be discovered. A UID the FETCH returned nothing usable for is in
+        // `failedUids` too: the round did not finish with it either.
+        const enumerationComplete = !hasMore && failedUids.size === 0;
+        await this.settleHeaderWarnings(accountConfigId, mailbox, box.uidvalidity, {
+            failedUids: [...saveFailedUids, ...envelopeLessUidsOf(messages)],
+            syncedUids: syncedUidsOf(outcomes),
+            serverUids: { kind: "Listed", uids: allUids },
+        });
+        await this.mailboxService.update(accountId, mailboxId, {
+            lastSyncUid: newLastSyncUid,
+            highWaterMarkUid: newHighWaterMark,
+            lastMessageSyncAt: Date.now(),
+            uidValidity: box.uidvalidity,
+            messageCount: status.messages,
+            ...(enumerationComplete ? { highestModseq: status.highestModseq } : {}),
+            unseenCount,
+            deletedCount,
+        });
+        // Same stall condition as the CHANGEDSINCE round, on the UID axis: work
+        // selected, nothing moved, and the next round will select exactly the
+        // same work. No error surfaces on its own — every failure here is caught
+        // and held back — so this is the only signal that the mailbox is stuck.
+        const stalled = newHighWaterMark === highWaterMarkUid && newLastSyncUid === lastSyncUid;
+        if (stalled) {
+            this.log.error({
+                alert: "message_sync_cursor_stalled",
+                mailboxId,
+                mailboxPath,
+                accountId,
+                pendingUids: uids.length,
+                failedUids: [...failedUids],
+            }, "Message sync watermarks did not advance while UIDs were pending; this mailbox stops syncing until they do");
+        }
+        this.log.info({
+            batch: 1,
+            totalBatches,
+            batchSize: messages.length,
+            synced: syncedMessageIds.length,
+            total: uids.length,
+            remaining: remainingCount,
+            hasMore,
+            highWaterMarkUid: newHighWaterMark,
+            lastSyncUid: newLastSyncUid,
+        }, "Batch complete");
+        return {
+            syncedCount: syncedMessageIds.length,
+            syncedMessageIds,
+            syncedMessages,
+            hasMore,
+            remainingCount,
+            cursorStalled: stalled,
+        };
+    }
+    /**
+     * Re-key a mailbox's stored UIDs against a new UIDVALIDITY axis (#1272).
+     *
+     * One envelope-level pass (UID + Message-ID + INTERNALDATE, no body
+     * fetches — {@link matchCursorRebuild}) matched against the rows already
+     * stored for this mailbox:
+     * - Match → rewrite the row's UID mapping in place; bodies and threads are
+     *   untouched.
+     * - Server message with no row → normal new-message sync (the same
+     *   `trySaveMessage` pipeline the regular batch sync uses).
+     * - Row with no counterpart → expunged; removed through `deleteIfPlacement`
+     *   on the uid the rebuild read (#1283 — the exact same "gone upstream"
+     *   outcome as a body-sync retry exhaustion finding a stale row), so a row
+     *   a move re-pointed in the meantime is left alone.
+     *
+     * Idempotent by construction: re-entering mid-rebuild (crash recovery —
+     * the mailbox was left `rebuilding`) simply redoes the same match/rewrite
+     * pass, which converges on the same result. `cursorState` is stamped
+     * `rebuilding` before any write and only cleared to `normal` after the
+     * watermarks are rebuilt, so a crash anywhere in between leaves the
+     * mailbox paused rather than falling back to the stale axis.
+     */
+    async rebuildCursor(mailbox, accountId, accountConfigId, mailboxId) {
+        const mailboxPath = mailbox.fullPath;
+        await this.mailboxService.update(accountId, mailboxId, {
+            cursorState: MailboxCursorState.rebuilding,
+        });
+        const connection = this.connectionFactory.getConnection();
+        const box = await connection.openBox(mailboxPath);
+        // Read before the pass, never after: a message arriving while the
+        // rebuild runs is absent from the snapshot below, and a HIGHESTMODSEQ
+        // read afterwards would already sit above that arrival's mod-sequence —
+        // seeding it would close the mailbox over a message it never stored.
+        const status = await connection.getMailboxStatus(mailboxPath);
+        const allUids = await connection.search(["ALL"]);
+        const snapshots = await connection.fetchEnvelopeSnapshots(allUids);
+        const serverSnapshots = snapshots.map((s) => ({
+            uid: s.uid,
+            messageId: s.messageId,
+            internalDate: s.internalDate.getTime(),
+        }));
+        const existingRows = await this.listExistingCursorRows(accountConfigId, mailboxId);
+        const { matched, newUids, staleMessageIds } = matchCursorRebuild(serverSnapshots, existingRows);
+        // Bounded concurrency (mirrors MESSAGE_SAVE_CONCURRENCY below) — a
+        // sequential loop over a large mailbox's full match set risked the
+        // Lambda timeout on its own, independent of the fetch-size question
+        // (#1272 review, non-blocking finding).
+        await pMap(matched, async ({ messageId, newUid, threadMessage }) => {
+            await this.messageService.updateUid(messageId, newUid, mailboxId);
+            // Rewrite the denormalized ThreadMessage.uid alongside Message.uid —
+            // a normal move keeps both in sync (see buildThreadMessageMoveUpdate
+            // in message-move.ts), and the rebuild must too, or a resumed
+            // rebuild re-emits a no-op rewrite forever (listExistingCursorRows
+            // reads uid from ThreadMessage) and any reader of the list
+            // projection sees a stale UID.
+            if (threadMessage) {
+                await this.threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, { uid: newUid }, {
+                    composites: {
+                        sentDate: threadMessage.sentDate,
+                        mailboxId: threadMessage.mailboxId,
+                        isRead: threadMessage.isRead,
+                        isDeleted: threadMessage.isDeleted,
+                        hasStars: threadMessage.hasStars,
+                        hasAttachment: threadMessage.hasAttachment,
+                    },
+                });
+            }
+        }, { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        const stale = new Set(staleMessageIds);
+        await pMap(existingRows.filter((row) => stale.has(row.messageId)), (row) => this.messageService.deleteIfPlacement(row.messageId, {
+            mailboxId,
+            uid: row.uid,
+        }), { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        const newMessages = newUids.length > 0 ? await this.fetchMessageBatch(newUids) : [];
+        const applicable = newMessages.filter(hasEnvelope);
+        const roles = await this.folderRolesFor(accountId, accountConfigId);
+        const departures = await this.probeDepartures(mailbox, accountId, applicable);
+        const outcomes = await pMap(applicable, (msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg, roles, departures), { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        const syncedMessages = outcomes.flatMap((o) => o.kind === "saved" && o.result !== null && o.result.owned
+            ? [{ messageId: o.result.messageId, uid: o.result.uid }]
+            : []);
+        const serverUids = serverSnapshots.map((s) => s.uid);
+        // A UID this pass could not account for, in any of the three ways it can
+        // go missing: the snapshot FETCH never returned a row for it, the
+        // message FETCH never returned one, or the row it returned carried no
+        // ENVELOPE. None of the three is the message's fault and none can be
+        // quarantined, so each has to keep the UID selectable.
+        //
+        // This matters more here than on the enumeration path, not less. The
+        // covered region is computed from `serverUids` rather than from what was
+        // applied, so a UID missing anywhere inside its span is silently inside
+        // it; and this round seeds the mod-sequence and returns the mailbox to
+        // `normal`, so the next round takes CHANGEDSINCE, which never
+        // enumerates. A UID lost here is lost for good.
+        const savedUids = new Set(applicable.map((msg) => msg.uid));
+        const snapshotUids = new Set(serverUids);
+        const unusableUids = [
+            ...allUids.filter((uid) => !snapshotUids.has(uid)),
+            ...newUids.filter((uid) => !savedUids.has(uid)),
+        ];
+        if (unusableUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, unusableUids }, "Cursor rebuild could not account for some UIDs; holding the watermark below them");
+        }
+        // A new message whose save threw must stay selectable, so the forward
+        // watermark stops below it and every UID above it is re-enumerated next
+        // round. The mod-sequence seed is withheld entirely in that case: the
+        // old value is meaningless on this axis (RFC 7162 requires discarding
+        // it on a UIDVALIDITY change) and the new one would sit above the
+        // message that failed, so the mailbox goes back to enumeration until a
+        // clean round seeds it.
+        const failedUids = new Set([
+            ...outcomes.flatMap((o) => (o.kind === "failed" ? [o.uid] : [])),
+            ...unusableUids,
+            ...unresolvedSightingUids(outcomes),
+        ]);
+        const lowestFailure = failedUids.size
+            ? Math.min(...failedUids)
+            : Number.POSITIVE_INFINITY;
+        const coveredUids = serverUids.filter((uid) => uid < lowestFailure);
+        await this.settleHeaderWarnings(accountConfigId, mailbox, box.uidvalidity, {
+            failedUids: [
+                ...saveFailedUidsOf(outcomes),
+                ...envelopeLessUidsOf(newMessages),
+            ],
+            syncedUids: syncedUidsOf(outcomes),
+            serverUids: { kind: "Listed", uids: allUids },
+        });
+        await this.mailboxService.update(accountId, mailboxId, {
+            cursorState: MailboxCursorState.normal,
+            uidValidity: box.uidvalidity,
+            highWaterMarkUid: coveredUids.length > 0 ? Math.max(...coveredUids) : 0,
+            lastSyncUid: serverUids.length > 0 ? Math.min(...serverUids) : 0,
+            highestModseq: failedUids.size === 0 ? status.highestModseq : "0",
+            lastMessageSyncAt: Date.now(),
+            messageCount: status.messages,
+            unseenCount: status.unseen,
+            deletedCount: status.deletedCount,
+        });
+        this.log.info({
+            mailboxId,
+            mailboxPath,
+            matched: matched.length,
+            newMessages: syncedMessages.length,
+            stale: staleMessageIds.length,
+        }, "Mailbox cursor rebuild complete; returned to normal");
+        return {
+            syncedCount: syncedMessages.length,
+            syncedMessageIds: syncedMessages.map((m) => m.messageId),
+            syncedMessages,
+            hasMore: false,
+            remainingCount: 0,
+            cursorStalled: false,
+        };
+    }
+    /**
+     * Page through every ThreadMessage row for this mailbox, projecting just
+     * the fields {@link matchCursorRebuild} needs. ThreadMessage (not
+     * Message) is the read source: it already denormalizes `messageIdHeader`
+     * and `internalDate` alongside `uid`, so this needs no per-row Envelope
+     * lookup.
+     */
+    async listExistingCursorRows(accountConfigId, mailboxId) {
+        const rows = [];
+        let continuationToken;
+        do {
+            const result = await this.threadMessageService.listByMailbox(accountConfigId, mailboxId, {
+                continuationToken,
+                attributes: [
+                    "messageId",
+                    "messageIdHeader",
+                    "internalDate",
+                    "uid",
+                    "accountConfigId",
+                    "threadMessageId",
+                    "sentDate",
+                    "mailboxId",
+                    "isRead",
+                    "isDeleted",
+                    "hasStars",
+                    "hasAttachment",
+                ],
+            });
+            for (const row of result.items) {
+                rows.push({
+                    messageId: row.messageId,
+                    messageIdHeader: row.messageIdHeader ?? "",
+                    internalDate: row.internalDate,
+                    uid: row.uid,
+                    // Carried so a match can also rewrite ThreadMessage.uid (a normal
+                    // move keeps both in sync — the rebuild must too, or #1271's
+                    // push-time UID resolution can read a stale projection).
+                    threadMessage: {
+                        accountConfigId: row.accountConfigId,
+                        threadMessageId: row.threadMessageId,
+                        sentDate: row.sentDate,
+                        mailboxId: row.mailboxId,
+                        isRead: row.isRead,
+                        isDeleted: row.isDeleted,
+                        hasStars: row.hasStars,
+                        hasAttachment: row.hasAttachment,
+                    },
+                });
+            }
+            continuationToken = result.continuationToken;
+        } while (continuationToken);
+        return rows;
+    }
+    /**
+     * One CHANGEDSINCE round (issue #20).
+     *
+     * A single `FETCH ... (CHANGEDSINCE <modseq>)` over the whole UID space
+     * returns both the messages that arrived and the messages whose metadata
+     * changed since the stored watermark, so a flag flipped on another client
+     * is picked up without enumerating the folder. Rows already present in
+     * this folder take the metadata path — the envelope, body structure and
+     * addresses are immutable, so re-writing them for a read-state change would
+     * be pure waste; everything else, a row another client moved here from a
+     * folder it points at included, takes the normal save pipeline (#1386).
+     *
+     * Expunges are invisible here (CONDSTORE without QRESYNC never reports
+     * them, RFC 7162 Section 3.1.2.1) — they remain the reconcile path's job.
+     */
+    async syncChangedSince(params) {
+        const { mailbox, accountId, accountConfigId, cursor, box, status, batchSize, } = params;
+        const mailboxId = mailbox.mailboxId;
+        const mailboxPath = mailbox.fullPath;
+        const connection = this.connectionFactory.getConnection();
+        // Ask from the last COMPLETE mod-sequence, so a group left part-applied
+        // by an earlier round is served again in full; its applied members are
+        // then dropped by position, without a lookup.
+        const changed = await connection.fetchMessagesChangedSince(cursor.modseq);
+        const ordered = dropAppliedPrefix(orderByModseq(changed), cursor);
+        const batch = ordered.slice(0, batchSize);
+        // A quarantined UID stays in `batch`, so the cursor still advances over
+        // it; only the work of re-applying it is skipped.
+        const quarantined = await this.quarantineService?.load(accountConfigId);
+        const applicable = batch
+            .filter((msg) => !quarantined?.has(mailboxId, box.uidvalidity, msg.uid))
+            .filter(hasEnvelope);
+        // A change row carrying no ENVELOPE holds the cursor and is retried; it
+        // is never set aside. On this path the message is usually one already
+        // stored — it demonstrably had a sender, a date and a Message-ID when it
+        // was first saved — so an envelope-less row is the FETCH glitching
+        // (#408), not the message being defective. Quarantining it would filter
+        // that UID out of every later round, stopping its flag sync until a
+        // purge, and tell the user a message they can open and read "arrived
+        // without a sender". A transient glitch heals on the retry; a persistent
+        // one trips the stalled-cursor alert, which is what that alert is for.
+        const unusableUids = batch.flatMap((msg) => msg.envelope === undefined &&
+            !quarantined?.has(mailboxId, box.uidvalidity, msg.uid)
+            ? [msg.uid]
+            : []);
+        if (unusableUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, unusableUids }, "Change rows carried no ENVELOPE; holding the sync cursor below them");
+        }
+        const roles = await this.folderRolesFor(accountId, accountConfigId);
+        const departures = await this.probeDepartures(mailbox, accountId, applicable);
+        const outcomes = await pMap(applicable, (msg) => this.tryApplyChange(mailbox, accountId, accountConfigId, msg, roles, departures), { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        const saveFailedUids = outcomes.flatMap((o) => o.kind === "failed" ? [o.uid] : []);
+        if (saveFailedUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, failedUids: saveFailedUids }, "Some changes failed to apply; holding the sync cursor below them for retry");
+        }
+        const unresolvedUids = unresolvedSightingUids(outcomes);
+        if (unresolvedUids.length > 0) {
+            this.log.warn({ mailboxId, mailboxPath, unresolvedUids }, "Some sightings reached no verdict about the folder their row points at; holding the sync cursor below them");
+        }
+        const failedUids = new Set([
+            ...saveFailedUids,
+            ...unusableUids,
+            ...unresolvedUids,
+        ]);
+        // Body sync only concerns messages this round created — a metadata
+        // change has no new body to fetch.
+        const syncedMessages = outcomes.flatMap((o) => o.kind === "saved" && o.result !== null && o.result.owned
+            ? [{ messageId: o.result.messageId, uid: o.result.uid }]
+            : []);
+        const syncedMessageIds = syncedMessages.map((m) => m.messageId);
+        const { cursor: nextCursor, hasMore } = advanceChangeCursor({
+            cursor,
+            serverModseq: parseModseq(status.highestModseq),
+            ordered,
+            batch,
+            failedUids,
+        });
+        const highestModseq = formatChangeCursor(nextCursor);
+        await this.settleHeaderWarnings(accountConfigId, mailbox, box.uidvalidity, {
+            failedUids: [...saveFailedUids, ...unusableUids],
+            syncedUids: syncedUidsOf(outcomes),
+            serverUids: {
+                kind: "OnRequest",
+                list: () => connection.search(["ALL"]),
+            },
+        });
+        // The UID watermark obeys the same clamp as the enumeration path even
+        // though the cursor governs retries here: a mailbox that later falls
+        // back to enumeration must not find a failed UID already behind its
+        // forward watermark.
+        const { highWaterMarkUid: newHighWaterMark } = advanceUidWatermarks({
+            batchUids: batch.map((msg) => msg.uid),
+            failedUids,
+            lastSyncUid: mailbox.lastSyncUid || 0,
+            highWaterMarkUid: mailbox.highWaterMarkUid || 0,
+        });
+        await this.mailboxService.update(accountId, mailboxId, {
+            highestModseq,
+            highWaterMarkUid: newHighWaterMark,
+            lastMessageSyncAt: Date.now(),
+            uidValidity: box.uidvalidity,
+            messageCount: status.messages,
+            unseenCount: status.unseen,
+            deletedCount: status.deletedCount,
+        });
+        // A round that had work to do and moved nothing is stalled: the same
+        // fetch will return the same set forever, and the set only grows as the
+        // mailbox keeps changing. Nothing above this call fails, so nothing else
+        // would ever notice — the queue message is acked either way.
+        const stalled = ordered.length > 0 && highestModseq === mailbox.highestModseq;
+        if (stalled) {
+            this.log.error({
+                alert: "message_sync_cursor_stalled",
+                mailboxId,
+                mailboxPath,
+                accountId,
+                cursor: highestModseq,
+                pendingChanges: ordered.length,
+                failedUids: [...failedUids],
+            }, "Message sync cursor did not advance while changes were pending; this mailbox stops seeing changes until it does");
+        }
+        this.log.info({
+            mailboxId,
+            mailboxPath,
+            changed: ordered.length,
+            applied: batch.length,
+            created: syncedMessageIds.length,
+            fromCursor: formatChangeCursor(cursor),
+            cursor: highestModseq,
+            hasMore,
+        }, "CHANGEDSINCE round complete");
+        return {
+            syncedCount: syncedMessageIds.length,
+            syncedMessageIds,
+            syncedMessages,
+            hasMore,
+            remainingCount: ordered.length - batch.length,
+            cursorStalled: stalled,
+        };
+    }
+    async settleHeaderWarnings(accountConfigId, mailbox, uidValidity, round) {
+        await this.syncWarningService.settle({
+            accountConfigId,
+            accountId: mailbox.accountId,
+            mailboxId: mailbox.mailboxId,
+            uidValidity,
+        }, SyncWarningStage.Header, round);
+    }
+    /**
+     * Apply one message from a CHANGEDSINCE result without ever rejecting —
+     * same contract as {@link trySaveMessage}, so a single unapplicable change
+     * holds the watermark back instead of failing the round.
+     */
+    async tryApplyChange(mailbox, accountId, accountConfigId, msg, roles, departures) {
+        const mailboxId = mailbox.mailboxId;
+        return this.applyChange(mailbox, accountId, accountConfigId, msg, roles, departures)
+            .then((result) => ({ kind: "saved", uid: msg.uid, result }))
+            .catch((error) => {
+            this.log.warn({
+                mailboxId,
+                uid: msg.uid,
+                messageId: msg.envelope?.messageId,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Failed to apply message change; will retry on next sync");
+            return { kind: "failed", uid: msg.uid };
+        });
+    }
+    async applyChange(mailbox, accountId, accountConfigId, msg, roles, departures) {
+        if (!hasEnvelope(msg))
+            return null;
+        const messageId = messageIdForSighting(accountId, mailbox.mailboxId, msg);
+        const existing = await this.threadMessageService.findByMessageId(accountConfigId, messageId);
+        if (!existing) {
+            return this.saveMessage(mailbox, accountId, accountConfigId, msg, roles, departures);
+        }
+        await this.applyServerFlags(existing, msg.flags);
+        if (!departures.needsSave.has(messageId))
+            return null;
+        return this.saveMessage(mailbox, accountId, accountConfigId, msg, roles, departures);
+    }
+    /**
+     * Bring a stored row's read and star state, and the $Junk/$NotJunk
+     * keywords on the canonical MessageFlag record, in line with the
+     * server's flags.
+     *
+     * A field with a pending outbound push is left alone: the user flipped it
+     * locally, IMAP has not been told yet, and the server's answer is
+     * therefore known-stale for that field. Writing it back would revert the
+     * flip in front of the user and then push the reverted value.
+     */
+    async applyServerFlags(existing, flags) {
+        const isRead = flags.includes(MessageSystemFlag.Seen);
+        const hasStars = flags.includes(MessageSystemFlag.Flagged);
+        const updates = {};
+        if (existing.isRead !== isRead &&
+            !(await this.hasPendingPush(existing.messageId, MessageSystemFlag.Seen))) {
+            updates.isRead = isRead;
+        }
+        if (existing.hasStars !== hasStars &&
+            !(await this.hasPendingPush(existing.messageId, MessageSystemFlag.Flagged))) {
+            updates.hasStars = hasStars;
+            // `hasStars` is the boolean of record and `star` its presentation
+            // colour; the two may never disagree (#58). A star cleared upstream
+            // loses its colour; one set upstream takes the standard colour unless
+            // the row already carries a real one the user chose.
+            if (!hasStars) {
+                updates.star = StarColor.None;
+            }
+            else if (existing.star === undefined ||
+                existing.star === StarColor.None) {
+                updates.star = StarColor.Yellow;
+            }
+        }
+        await this.mirrorKeywordFlag(existing.messageId, MessageKeywordFlag.Junk, flags);
+        await this.mirrorKeywordFlag(existing.messageId, MessageKeywordFlag.NotJunk, flags);
+        if (Object.keys(updates).length === 0)
+            return;
+        // MessageFlag is the canonical flag record — `FlagQueueService` reads it
+        // to decide whether a user's flip is redundant, and the API answers
+        // read/starred from it. Writing only the denormalized row would leave
+        // the two disagreeing, and the next local flip would be dismissed as
+        // already-in-state: a click that does nothing.
+        //
+        // Canonical record first, projection second — the same order the local
+        // flip path uses. A crash between the two leaves the pair inconsistent
+        // exactly as a crashed local flip would, and the round's watermark has
+        // not moved, so the next round re-fetches the message and re-applies
+        // both writes (each is idempotent).
+        if (updates.isRead !== undefined) {
+            await this.setMessageFlag(existing.messageId, MessageSystemFlag.Seen, updates.isRead);
+        }
+        if (updates.hasStars !== undefined) {
+            await this.setMessageFlag(existing.messageId, MessageSystemFlag.Flagged, updates.hasStars);
+        }
+        await this.threadMessageService.update(existing.accountConfigId, existing.threadMessageId, updates, {
+            // The CURRENT values of every sort-key attribute: ElectroDB uses
+            // them for the conditional check on the existing row and to
+            // recompute the new keys. Passing the new value here would fail
+            // that check and silently drop the update (see FlagQueueService).
+            composites: {
+                sentDate: existing.sentDate,
+                mailboxId: existing.mailboxId,
+                isRead: existing.isRead,
+                isDeleted: existing.isDeleted,
+                hasStars: existing.hasStars,
+                hasAttachment: existing.hasAttachment,
+            },
+        });
+        this.log.info({
+            messageId: existing.messageId,
+            threadMessageId: existing.threadMessageId,
+            ...updates,
+        }, "Applied server flag state from CHANGEDSINCE");
+    }
+    /**
+     * Set or clear one flag on the canonical record. Both repository calls are
+     * idempotent, so a re-applied change is a no-op rather than a conflict.
+     */
+    async setMessageFlag(messageId, flagName, present) {
+        if (!this.messageFlagService)
+            return;
+        if (present) {
+            await this.messageFlagService.addFlag(messageId, flagName);
+            return;
+        }
+        await this.messageFlagService.removeFlag(messageId, flagName);
+    }
+    async hasPendingPush(messageId, flagName) {
+        if (!this.flagPushMarkerService)
+            return false;
+        const marker = await this.flagPushMarkerService.find(messageId, flagName);
+        return marker !== null;
+    }
+    /**
+     * Mirror one RFC 5788 keyword ($Junk / $NotJunk) from the server into the
+     * canonical MessageFlag record, guarded the same way as the system flags:
+     * a pending local push wins over the server's known-stale answer.
+     *
+     * This mailbox is never remit-only — Apple Mail or another IMAP client is
+     * routinely connected too — so the keyword is message state, nothing
+     * more. It never reaches the Address model: reading another client's
+     * keyword as a standing rule about the sender is the exact fight this
+     * mirror must not pick.
+     */
+    async mirrorKeywordFlag(messageId, flagName, serverFlags) {
+        if (!this.messageFlagService)
+            return;
+        if (await this.hasPendingPush(messageId, flagName))
+            return;
+        const present = serverFlags.includes(flagName);
+        const hasFlag = await this.messageFlagService.hasFlag(messageId, flagName);
+        if (hasFlag === present)
+            return;
+        await this.setMessageFlag(messageId, flagName, present);
+    }
+    /**
+     * Messages the forwarded-message repair queued — their part rows dropped,
+     * the lost row only on the mail server — are fetched again by UID and saved
+     * through the same path as any other sighting, which writes their parts. No
+     * watermark moves: these UIDs are already behind them. Each leaves the queue
+     * once saved or once the server returns no usable row for it, whatever
+     * parts came back; only a failed save keeps it for the next round. Resolves
+     * `true` when it touched the connection, which the probe of departures may
+     * have left on another folder.
+     */
+    async restoreMissingStructure(mailbox, accountId, accountConfigId, batchSize) {
+        const queued = await this.envelopeService.listQueuedStructureRefetches(mailbox.mailboxId, batchSize);
+        if (queued.length === 0)
+            return false;
+        const applicable = (await this.fetchMessageBatch(queued.map(({ uid }) => uid))).filter(hasEnvelope);
+        const roles = await this.folderRolesFor(accountId, accountConfigId);
+        const departures = await this.probeDepartures(mailbox, accountId, applicable);
+        const outcomes = await pMap(applicable, (msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg, roles, departures), { concurrency: MESSAGE_SAVE_CONCURRENCY });
+        const failedUids = new Set(outcomes.flatMap((outcome) => outcome.kind === "failed" ? [outcome.uid] : []));
+        await this.envelopeService.clearStructureRefetches(queued
+            .filter(({ uid }) => !failedUids.has(uid))
+            .map(({ messageId }) => messageId));
+        this.log.info({
+            mailboxId: mailbox.mailboxId,
+            requested: queued.length,
+            saved: outcomes.length - failedUids.size,
+            failed: failedUids.size,
+        }, "Re-read the structure of messages the forwarded-message repair queued");
+        return true;
+    }
+    /**
+     * Fetch a batch of messages using the managed connection.
+     * Assumes mailbox is already open from fetchUidsToSync.
+     */
+    async fetchMessageBatch(uids) {
+        const connection = this.connectionFactory.getConnection();
+        return await connection.fetchMessages(uids);
+    }
+    /**
+     * Save a single message without ever rejecting. Any error is caught and
+     * reported as a `failed` outcome so it cannot abort the surrounding `pMap`
+     * batch — the failed UID is held back from the watermark and retried next
+     * cycle. This is the guardrail that stops a single unsaveable message from
+     * permanently freezing the mailbox (#817).
+     */
+    /**
+     * Which folders hold Junk and Trash for this account, resolved once per
+     * batch rather than per message: the lookup reads an appointment row and
+     * the account’s mailbox list, and every message in a batch shares both.
+     */
+    async folderRolesFor(accountId, accountConfigId) {
+        const [junk, trash, configJunkRoles] = await Promise.all([
+            this.mailboxSpecialUseService.findJunkMailbox(accountId),
+            this.mailboxSpecialUseService.findTrashMailbox(accountId),
+            this.mailboxSpecialUseService.resolveJunkRolesForConfig(accountConfigId),
+        ]);
+        return {
+            junkMailboxId: junk?.mailboxId ?? null,
+            trashMailboxId: trash?.mailboxId ?? null,
+            configJunkRoles,
+        };
+    }
+    /**
+     * Ask the folders this batch's rows point at whether they still hold them
+     * (#1146).
+     *
+     * Between the batch FETCH and the save pass, in all three rounds, and in that
+     * position on purpose. It SELECTs another folder on the one connection this
+     * sync has, so it may not run while this mailbox's own fetches are still
+     * outstanding; and the save pass has to have the answer already, because the
+     * transaction that re-points a row is where the answer is spent. Nothing
+     * after the save pass touches IMAP, so leaving another folder selected costs
+     * the round nothing.
+     */
+    async probeDepartures(mailbox, accountId, applicable) {
+        return confirmDepartures({
+            connection: this.connectionFactory.getConnection(),
+            mailboxService: this.mailboxService,
+            messageService: this.messageService,
+            log: this.log,
+        }, accountId, mailbox, applicable.map((msg) => messageIdForSighting(accountId, mailbox.mailboxId, msg)));
+    }
+    async trySaveMessage(mailbox, accountId, accountConfigId, msg, roles, departures) {
+        const mailboxId = mailbox.mailboxId;
+        return this.saveMessage(mailbox, accountId, accountConfigId, msg, roles, departures)
+            .then((result) => ({ kind: "saved", uid: msg.uid, result }))
+            .catch((error) => {
+            this.log.warn({
+                mailboxId,
+                uid: msg.uid,
+                messageId: msg.envelope?.messageId,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Failed to save message; will retry on next sync");
+            return { kind: "failed", uid: msg.uid };
+        });
+    }
+    async saveMessage(mailbox, accountId, accountConfigId, msg, roles, departures) {
+        if (!hasEnvelope(msg))
+            return null;
+        const mailboxId = mailbox.mailboxId;
+        const sighting = addressSightingIn(mailboxId, roles);
+        // Store envelope to preserve narrowing in closures
+        const envelope = msg.envelope;
+        const messageId = messageIdForSighting(accountId, mailboxId, msg);
+        const envelopeId = deriveEnvelopeId(messageId);
+        const rootBodyPartId = deriveBodyPartId(messageId, ROOT_PART_PATH);
+        const internalDateMs = msg.internalDate.getTime();
+        const { value: sentDate, usedFallback: dateFellBack } = parseHeaderDate(envelope.date, internalDateMs);
+        if (dateFellBack) {
+            this.log.warn({
+                mailboxId,
+                messageId,
+                uid: msg.uid,
+                dateRaw: envelope.date,
+            }, "Unparseable Date header; fell back to IMAP internalDate");
+        }
+        // Prepare all address save operations
+        const addressOps = [
+            { addresses: envelope.from, role: AddressRole.From },
+            { addresses: envelope.sender, role: AddressRole.Sender },
+            { addresses: envelope.replyTo, role: AddressRole.ReplyTo },
+            { addresses: envelope.to, role: AddressRole.To },
+            { addresses: envelope.cc, role: AddressRole.Cc },
+            { addresses: envelope.bcc, role: AddressRole.Bcc },
+        ];
+        const bodyParts = buildBodyPartUpserts(msg.bodyStructure);
+        const hasAttachment = bodyParts.some((p) => !p.isMultipart && p.disposition === "attachment");
+        // Ownership of this messageId by the current mailbox: the row was created
+        // by this call, or an existing row already belongs to this mailbox. A
+        // conflict whose stored row points at a different mailbox is foreign-owned
+        // and must not feed this mailbox's watermark / body-sync (#634).
+        let owned = false;
+        let unresolvedSighting = false;
+        // Every write below is an idempotent upsert keyed on a derived id, so a
+        // save that fails part-way is repaired by the next round repeating it: the
+        // UID's watermark only moves once the save returns. The order is the
+        // guarantee a reader gets in between: the Envelope lands before the
+        // Message (#1072), and the ThreadMessage is written last so the list path
+        // never anchors on a ThreadMessage whose Message does not yet exist
+        // (#1209).
+        await this.envelopeService.upsertEnvelope({
+            envelopeId,
+            messageId,
+            dateValue: sentDate,
+            dateRaw: envelope.date,
+            subject: envelope.subject,
+            messageIdValue: envelope.messageId,
+        });
+        const messageReferences = messageReferencesOf(envelope, msg.references);
+        if (messageReferences.length > 0) {
+            await this.envelopeService.replaceMessageReferences(messageId, messageReferences);
+        }
+        for (const { addresses, role } of addressOps) {
+            await this.saveAddresses(this.addressService, messageId, accountConfigId, addresses, role, sighting);
+        }
+        // IMAP returns BODYSTRUCTURE in the same FETCH that returns the
+        // envelope, so persisting BodyParts here is "free" — no extra round-trip.
+        if (bodyParts.length > 0) {
+            await this.envelopeService.upsertBodyParts(messageId, bodyParts);
+        }
+        const { item, created } = await this.messageService.upsertWithStatus({
+            messageId,
+            mailboxId,
+            uid: msg.uid,
+            sequenceNumber: msg.seq,
+            rfc822Size: msg.size ?? 0,
+            internalDate: msg.internalDate.getTime(),
+            envelopeId,
+            rootBodyPartId,
+        });
+        // The server has just named this folder and this UID for a message the
+        // database holds under another folder. `upsertWithStatus` left the row
+        // alone, so the pointer is repaired here — mailbox and UID together,
+        // because a UID only means anything inside the folder that issued it.
+        //
+        // Only when the message has really left the folder the row points at
+        // (#1146). A sighting alone does not say that: a Gmail label, a Sieve
+        // `fileinto` beside a `keep` and an echoed Sent copy all put the same
+        // message in a second real folder while the first still holds it, and
+        // following those took the mail out of the Inbox. `confirmDepartures`
+        // asked the source before this batch was saved, and its verdict names
+        // the placement it was reached for — so a row that has moved since
+        // matches nothing, and `unresolvedSighting` holds this UID back for
+        // the next round rather than repairing the row against a stale answer.
+        const contested = !created && sightingContestsPlacement(mailbox, item);
+        const verdict = placementKey(messageId, item.mailboxId, item.uid);
+        unresolvedSighting = contested && !departures.settled.has(verdict);
+        const repointable = contested &&
+            departures.departed.has(verdict) &&
+            !(await this.holdsCopyOf(this.messageService, messageId, mailboxId));
+        // A user move landing between the read above and this write wins: the
+        // re-point names the placement it read, writes nothing when the row has
+        // moved since, and the UID waits for the next round.
+        const repointed = repointable &&
+            (await this.messageService.repointIfPlacement(messageId, { status: item.status, mailboxId: item.mailboxId, uid: item.uid }, { mailboxId, uid: msg.uid, isDeleted: sighting === "discarded" }));
+        if (repointable && !repointed)
+            unresolvedSighting = true;
+        owned = created || item.mailboxId === mailboxId || repointed;
+        // Withholding reads the pointer, so it is re-derived whenever the
+        // pointer could have changed the answer: a save into Junk, and a
+        // re-point in either direction. The reconcile both applies and lifts,
+        // so a sender whose only mail was moved out of Junk is restored by the
+        // same call that would have withheld them (#859).
+        if (sighting === "junk" || repointed) {
+            await this.addressService.reconcileJunkOnlyForMessage(messageId, roles.configJunkRoles);
+        }
+        await this.createThreadForMessage(this.threadMessageService, messageId, mailboxId, accountId, accountConfigId, msg.uid, msg.internalDate.getTime(), sentDate, envelope, msg.flags, 
+        // The category of the Message this same save just wrote. A new
+        // message is `uncategorized` until body-sync classifies it; a row
+        // created for a Message that is ALREADY classified takes the decided
+        // value rather than sitting stale forever behind a body-sync pass that
+        // will skip it. That happens on thread-root drift — the same message
+        // re-saved under different `References` mints a second threadId and so
+        // a second row — not on a second mailbox, which resolves to the row
+        // that already exists (issue #320).
+        item.category, msg.references, hasAttachment);
+        return { messageId, uid: msg.uid, owned, unresolvedSighting };
+    }
+    /**
+     * Whether this folder already holds a copy the user made of this message
+     * (#75). A copy is a second row under its own derived id, so the sighting is
+     * that copy standing where it was put — the original has not moved, and
+     * following it would take the mail out of the folder the user copied it from.
+     */
+    async holdsCopyOf(messageService, messageId, mailboxId) {
+        const rows = await messageService.get([
+            deriveCopyMessageId(messageId, mailboxId),
+        ]);
+        return rows.length > 0;
+    }
+    async saveAddresses(addressService, messageId, accountConfigId, addresses, role, sighting) {
+        if (!addresses)
+            return;
+        // Pre-compute address data with order indices, filtering valid addresses
+        const addressData = [];
+        // An unusable address is dropped and the message is written anyway, and
+        // that stays deliberate under the quarantine rules (issue #72). What is
+        // lost is one envelope address, not the message: it is stored, listed and
+        // readable, and its body is untouched. Setting the whole message aside
+        // over a malformed From would take readable mail out of the mailbox to
+        // protect a display name.
+        for (let i = 0; i < addresses.length; i++) {
+            const addr = addresses[i];
+            if (!isParseableEmailAddress(addr))
+                continue;
+            addressData.push({
+                localPart: addr.mailbox,
+                domain: addr.host,
+                displayName: harvestedDisplayName(addr),
+                order: i,
+            });
+        }
+        for (const { localPart, domain, displayName, order } of addressData) {
+            const normalizedEmail = `${localPart}@${domain}`.toLowerCase();
+            const normalizedCompound = `${displayName.toLowerCase()} ${normalizedEmail}`.trim();
+            const addressId = deriveAddressId(accountConfigId, normalizedEmail);
+            const addressInput = {
+                addressId,
+                accountConfigId,
+                localPart,
+                domain,
+                normalizedEmail,
+                normalizedCompound,
+                displayName,
+            };
+            if (sighting === "junk") {
+                await addressService.upsertJunkAddress(addressInput);
+            }
+            else if (sighting === "discarded") {
+                await addressService.upsertAddress(addressInput);
+            }
+            else {
+                await addressService.upsertCorrespondentAddress(addressInput);
+            }
+            await addressService.upsertEnvelopeAddress({
+                messageId,
+                addressId,
+                displayName,
+                normalizedEmail,
+                addressRole: role,
+                addressOrder: order,
+            });
+        }
+    }
+    /**
+     * The thread a synced message files under. A message keeps the thread it is
+     * already stored in; a reply joins the thread its parent is stored in;
+     * otherwise the thread is derived from the root `threadRootOf` names.
+     */
+    async threadFor(threadMessageService, messageId, accountId, accountConfigId, envelope, references) {
+        const own = await threadMessageService.findByMessageId(accountConfigId, messageId);
+        if (own)
+            return own.threadId;
+        const parent = parentOf(envelope, references);
+        const parentRow = parent
+            ? await threadMessageService.findByMessageId(accountConfigId, deriveMessageId(accountId, parent))
+            : null;
+        return (parentRow?.threadId ??
+            deriveThreadId(accountConfigId, threadRootOf(envelope, references, messageId)));
+    }
+    /**
+     * Joins the rows written on either side of a parent and its reply, after
+     * this message's own row exists. Replies that arrived before this message,
+     * and so were keyed on its own id, follow it into its thread; and a reply
+     * whose parent was saved while it was being saved follows the parent, but
+     * only from the thread it derived for itself — a thread it joined or was
+     * already stored in is left as it is.
+     *
+     * Both checks run after the create, so of a parent and a reply saved
+     * concurrently at least one sees the other's row: neither is left in a
+     * thread of its own.
+     */
+    async joinThreads(threadMessageService, messageId, accountId, accountConfigId, envelope, references, threadId) {
+        if (isValidMessageId(envelope.messageId)) {
+            await threadMessageService.rekeyThread(accountConfigId, deriveThreadId(accountConfigId, wireMessageId(envelope.messageId)), threadId);
+        }
+        const parent = parentOf(envelope, references);
+        if (!parent)
+            return;
+        const derived = deriveThreadId(accountConfigId, threadRootOf(envelope, references, messageId));
+        if (threadId !== derived)
+            return;
+        const parentRow = await threadMessageService.findByMessageId(accountConfigId, deriveMessageId(accountId, parent));
+        if (!parentRow || parentRow.threadId === threadId)
+            return;
+        await threadMessageService.rekeyThread(accountConfigId, threadId, parentRow.threadId);
+    }
+    /**
+     * Create the ThreadMessage for a synced message, then join it to its
+     * parent and replies.
+     *
+     * `category` is the value the caller already holds from the Message it just
+     * wrote, so the row starts out agreeing with it rather than defaulting to
+     * `uncategorized` behind an already-classified message.
+     */
+    async createThreadForMessage(threadMessageService, messageId, mailboxId, accountId, accountConfigId, uid, internalDate, sentDate, envelope, flags, category, references, hasAttachment = false) {
+        const threadId = await this.threadFor(threadMessageService, messageId, accountId, accountConfigId, envelope, references);
+        const isRead = flags.includes(MessageSystemFlag.Seen);
+        // The server's \Flagged keyword is the star. Mail flagged in another
+        // client must arrive starred, so carry it through on create rather than
+        // defaulting every row to unstarred. Both comparisons go through the
+        // generated members, which carry the wire spelling (reader#65) and are
+        // the same values the flag-push markers are keyed by — one source of
+        // truth for the wire flag and the record of it.
+        const hasStars = flags.includes(MessageSystemFlag.Flagged);
+        // Extract sender info. When the server could not parse the From address,
+        // omit fromEmail rather than persist a fabricated string — a display name
+        // may still be present and useful, so keep it. This is the sender label the
+        // message list shows and the search index tokenizes, so it takes the same
+        // guard as the address book (issue #826).
+        const fromAddr = envelope.from?.[0];
+        const fromEmail = isParseableEmailAddress(fromAddr)
+            ? `${fromAddr?.mailbox}@${fromAddr?.host}`.toLowerCase()
+            : undefined;
+        const fromName = harvestedDisplayName(fromAddr) || undefined;
+        // Calculate reference order (position in the thread chain)
+        // references.length gives the position since References = [root, parent1, parent2, ...]
+        const referenceOrder = references?.length ?? (envelope.inReplyTo ? 1 : 0);
+        // Create ThreadMessage linking message to thread
+        await threadMessageService
+            .create({
+            threadId,
+            messageId,
+            accountConfigId,
+            mailboxId,
+            uid,
+            messageIdHeader: envelope.messageId,
+            inReplyTo: envelope.inReplyTo,
+            referenceOrder,
+            fromEmail,
+            fromName,
+            subject: envelope.subject,
+            internalDate,
+            sentDate,
+            isRead,
+            isDeleted: false,
+            hasAttachment,
+            hasStars,
+            star: hasStars ? StarColor.Yellow : StarColor.None,
+            category,
+        })
+            .catch((error) => {
+            // Ignore conflict errors (idempotent create)
+            if (error?.name === "CreateFailedConflictError") {
+                return;
+            }
+            throw error;
+        });
+        await this.joinThreads(threadMessageService, messageId, accountId, accountConfigId, envelope, references, threadId);
+    }
+}
+/**
+ * Translate the IMAP BODYSTRUCTURE for a single message into a list of
+ * `BodyPartUpsertInput`s ready for `EnvelopeService.upsertBodyParts`.
+ * Returns an empty list when the server didn't return BODYSTRUCTURE
+ * (some unusual messages, or older test fixtures).
+ */
+const buildBodyPartUpserts = (bodyStructure) => {
+    if (!bodyStructure)
+        return [];
+    return walkMimeStructure(bodyStructure).map((part) => ({
+        partPath: part.partPath,
+        parentPartPath: part.parentPartPath,
+        mediaType: part.mediaType,
+        mediaSubtype: part.mediaSubtype,
+        transferEncoding: part.transferEncoding,
+        sizeOctets: part.sizeOctets,
+        isMultipart: part.isMultipart,
+        parameters: part.parameters,
+        ...(part.contentId !== undefined ? { contentId: part.contentId } : {}),
+        ...(part.contentDescription !== undefined
+            ? { contentDescription: part.contentDescription }
+            : {}),
+        ...(part.lineCount !== undefined ? { lineCount: part.lineCount } : {}),
+        ...(part.md5Hash !== undefined ? { md5Hash: part.md5Hash } : {}),
+        ...(part.disposition !== undefined
+            ? { disposition: part.disposition }
+            : {}),
+        ...(part.dispositionFilename !== undefined
+            ? { dispositionFilename: part.dispositionFilename }
+            : {}),
+        ...(part.language !== undefined ? { language: part.language } : {}),
+        ...(part.location !== undefined ? { location: part.location } : {}),
+        ...(part.multipartSubtype !== undefined
+            ? { multipartSubtype: part.multipartSubtype }
+            : {}),
+    }));
+};