@remit/mailbox-service 0.0.111 → 0.0.113

package/src/message-sync.ts

@@ -1,1963 +0,0 @@
-import type {
-	BodyPartUpsertInput,
-	IAddressRepository,
-	IEnvelopeRepository,
-	IMailboxRepository,
-	IMailboxSpecialUseRepository,
-	IMessageFlagPushRepository,
-	IMessageFlagRepository,
-	IMessageRepository,
-	IThreadMessageRepository,
-	IUnitOfWork,
-	MailboxItem,
-	ThreadMessageItem,
-} from "@remit/data-ports";
-import { storedDisplayName } from "@remit/data-ports/display-name";
-import type { JunkRoleMailboxes } from "@remit/data-ports/folder-role";
-import {
-	deriveAddressId,
-	deriveBodyPartId,
-	deriveCopyMessageId,
-	deriveEnvelopeId,
-	deriveMessageIdFromSource,
-	deriveThreadId,
-	isValidMessageId,
-} from "@remit/data-ports/id";
-import {
-	AddressRole,
-	MailboxCursorState,
-	MessageKeywordFlag,
-	MessageSystemFlag,
-	StarColor,
-} from "@remit/domain-enums";
-import pMap from "p-map";
-import type { ManagedConnectionFactory } from "./connection-factory.js";
-import {
-	confirmDepartures,
-	type DepartureVerdicts,
-	placementKey,
-	sightingContestsPlacement,
-} from "./external-move.js";
-import { guardMailboxCursor, isCursorRebuildNeeded } from "./mailbox-cursor.js";
-import {
-	type CursorRebuildRow,
-	type CursorRebuildSnapshot,
-	matchCursorRebuild,
-} from "./mailbox-cursor-rebuild.js";
-import { ROOT_PART_PATH, walkMimeStructure } from "./mime-walker.js";
-import { PassThroughUnitOfWork } from "./pass-through-unit-of-work.js";
-import type { QuarantineService } from "./quarantine.js";
-import { reconcileStaleMessage } from "./stale-message-reconcile.js";
-import {
-	advanceChangeCursor,
-	advanceUidWatermarks,
-	type ChangeCursor,
-	dropAppliedPrefix,
-	formatChangeCursor,
-	hasChangeCursor,
-	orderByModseq,
-	parseChangeCursor,
-	parseModseq,
-} from "./sync-watermarks.js";
-import type {
-	ImapAddress,
-	ImapBodyStructure,
-	ImapEnvelope,
-	ImapMailboxStatus,
-	ImapMessage,
-} from "./types.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: ImapAddress | undefined,
-): boolean => {
-	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(".");
-};
-
-export type AddressSighting = "junk" | "discarded" | "correspondent";
-
-/** The account's Junk and Trash mailboxes, resolved once per batch. */
-export interface AccountFolderRoles {
-	readonly junkMailboxId: string | null;
-	readonly trashMailboxId: string | null;
-	/**
-	 * The same two roles across every account under the config, for the
-	 * reconcile that follows a save into Junk. The address book is keyed by
-	 * config, so a predicate over an address weighs sightings from all of them —
-	 * resolving only this account withholds a sender on one and restores it on
-	 * the next.
-	 */
-	readonly configJunkRoles: JunkRoleMailboxes;
-}
-
-/**
- * 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: string,
-	roles: AccountFolderRoles,
-): AddressSighting => {
-	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: ImapAddress | undefined,
-): string => {
-	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: string | undefined,
-	fallbackMs: number,
-): { value: number; usedFallback: boolean } => {
-	if (raw !== undefined && raw !== "") {
-		const parsed = new Date(raw).getTime();
-		if (Number.isFinite(parsed)) {
-			return { value: parsed, usedFallback: false };
-		}
-	}
-	return { value: fallbackMs, usedFallback: true };
-};
-
-/**
- * @deprecated Use ManagedConnectionFactory instead
- */
-export type ImapConnectionFactory = () => {
-	connect(): Promise<void>;
-	disconnect(): Promise<void>;
-};
-
-export interface SyncLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	warn(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: SyncLogger = {
-	info: () => {},
-	warn: () => {},
-	error: () => {},
-};
-
-export interface SyncedMessage {
-	messageId: string;
-	uid: number;
-}
-
-/**
- * Per-message save outcome. `owned` is true when the row was created by this
- * sync, already belongs to the current mailbox, or was re-pointed at it by this
- * sighting; false for a collision this sync declined to follow — a virtual-copy
- * folder, or a row whose own mutation has not settled.
- */
-interface SaveMessageResult extends SyncedMessage {
-	owned: boolean;
-	/**
-	 * The sighting contested the placement the row holds and no verdict about
-	 * the source folder covered it (#1146): the source could not be asked, or
-	 * the row moved between the probe and this save. The UID holds the watermark
-	 * so the next round serves the sighting again — nothing else ever will, and
-	 * a row left mispointed until a cursor rebuild is the silent never-repair
-	 * this change exists to end.
-	 */
-	unresolvedSighting: boolean;
-}
-
-/**
- * Wrapper outcome for a single message in the batch. A `failed` outcome means
- * the save threw (and was caught) — its UID must NOT advance the watermark, so
- * the message is re-fetched and retried on the next cycle. A `saved` outcome
- * with a `null` result is a UID this round finished with but created no row
- * for: a cross-mailbox collision, a change applied to an existing row, or a
- * message quarantined instead of applied (issue #72). Its watermark advances
- * either way, because there is nothing left to retry.
- */
-type BatchOutcome =
-	| { kind: "saved"; uid: number; result: SaveMessageResult | null }
-	| { kind: "failed"; uid: number };
-
-export interface SyncMessagesResult {
-	syncedCount: number;
-	syncedMessageIds: string[];
-	syncedMessages: SyncedMessage[];
-	hasMore: boolean;
-	remainingCount: number;
-	/**
-	 * The round had work to do and moved no cursor. Nothing throws on this
-	 * path — a message that cannot be applied is caught and held back — so
-	 * without this flag a mailbox that stops syncing looks exactly like one
-	 * with nothing to sync. Callers must surface it.
-	 */
-	cursorStalled: boolean;
-}
-
-/**
- * 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: BatchOutcome[]): number[] =>
-	outcomes.flatMap((outcome) =>
-		outcome.kind === "saved" &&
-		outcome.result !== null &&
-		outcome.result.unresolvedSighting
-			? [outcome.uid]
-			: [],
-	);
-
-const emptySyncResult = (): SyncMessagesResult => ({
-	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: number[],
-	lastSyncUid: number,
-	highWaterMarkUid: number,
-): number[] => {
-	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: ImapMessage,
-): msg is ImapMessage & { envelope: ImapEnvelope } =>
-	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: string,
-	mailboxId: string,
-	msg: ImapMessage & { envelope: ImapEnvelope },
-): string =>
-	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 {
-	private log: SyncLogger;
-	private unitOfWork: IUnitOfWork;
-
-	constructor(
-		private connectionFactory: ManagedConnectionFactory,
-		private mailboxService: IMailboxRepository,
-		/**
-		 * 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.
-		 */
-		private mailboxSpecialUseService: IMailboxSpecialUseRepository,
-		private messageService: IMessageRepository,
-		envelopeService: IEnvelopeRepository,
-		addressService: IAddressRepository,
-		private threadMessageService: IThreadMessageRepository,
-		logger?: SyncLogger,
-		unitOfWork?: IUnitOfWork,
-		/**
-		 * 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.
-		 */
-		private flagPushMarkerService?: IMessageFlagPushRepository,
-		/**
-		 * 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.
-		 */
-		private messageFlagService?: IMessageFlagRepository,
-		/**
-		 * 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.
-		 */
-		private quarantineService?: QuarantineService,
-	) {
-		this.log = logger ?? noopLogger;
-		this.unitOfWork =
-			unitOfWork ??
-			new PassThroughUnitOfWork({
-				message: messageService,
-				envelope: envelopeService,
-				address: addressService,
-				threadMessage: threadMessageService,
-			});
-	}
-
-	/**
-	 * 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: string,
-		accountId: string,
-		accountConfigId: string,
-		batchSize = 50,
-	): Promise<SyncMessagesResult> {
-		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();
-		}
-
-		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) {
-			// 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: SyncedMessage[] = 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.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; reconcile via {@link
-	 *   reconcileStaleMessage} (#1283 — the exact same "gone upstream" outcome
-	 *   as a body-sync retry exhaustion finding a stale row).
-	 *
-	 * 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.
-	 */
-	private async rebuildCursor(
-		mailbox: MailboxItem,
-		accountId: string,
-		accountConfigId: string,
-		mailboxId: string,
-	): Promise<SyncMessagesResult> {
-		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: CursorRebuildSnapshot[] = 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.unitOfWork.transaction((repos) =>
-					repos.message.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.unitOfWork.transaction((repos) =>
-						repos.threadMessage.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 },
-		);
-
-		await pMap(
-			staleMessageIds,
-			(messageId) =>
-				this.unitOfWork.transaction((repos) =>
-					reconcileStaleMessage(
-						{
-							messageService: repos.message,
-							threadMessageService: repos.threadMessage,
-						},
-						accountConfigId,
-						messageId,
-					),
-				),
-			{ 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: SyncedMessage[] = 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.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.
-	 */
-	private async listExistingCursorRows(
-		accountConfigId: string,
-		mailboxId: string,
-	): Promise<CursorRebuildRow[]> {
-		const rows: CursorRebuildRow[] = [];
-		let continuationToken: string | undefined;
-
-		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 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 is a new message and takes the normal save
-	 * pipeline.
-	 *
-	 * Expunges are invisible here (CONDSTORE without QRESYNC never reports
-	 * them, RFC 7162 Section 3.1.2.1) — they remain the reconcile path's job.
-	 */
-	private async syncChangedSince(params: {
-		mailbox: MailboxItem;
-		accountId: string;
-		accountConfigId: string;
-		cursor: ChangeCursor;
-		box: { uidvalidity: number };
-		status: ImapMailboxStatus;
-		batchSize: number;
-	}): Promise<SyncMessagesResult> {
-		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: SyncedMessage[] = 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);
-
-		// 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,
-		};
-	}
-
-	/**
-	 * 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.
-	 */
-	private async tryApplyChange(
-		mailbox: MailboxItem,
-		accountId: string,
-		accountConfigId: string,
-		msg: ImapMessage,
-		roles: AccountFolderRoles,
-		departures: DepartureVerdicts,
-	): Promise<BatchOutcome> {
-		const mailboxId = mailbox.mailboxId;
-		return this.applyChange(
-			mailbox,
-			accountId,
-			accountConfigId,
-			msg,
-			roles,
-			departures,
-		)
-			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
-			.catch((error): BatchOutcome => {
-				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 };
-			});
-	}
-
-	private async applyChange(
-		mailbox: MailboxItem,
-		accountId: string,
-		accountConfigId: string,
-		msg: ImapMessage,
-		roles: AccountFolderRoles,
-		departures: DepartureVerdicts,
-	): Promise<SaveMessageResult | null> {
-		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);
-		return null;
-	}
-
-	/**
-	 * 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.
-	 */
-	private async applyServerFlags(
-		existing: ThreadMessageItem,
-		flags: string[],
-	): Promise<void> {
-		const isRead = flags.includes(MessageSystemFlag.Seen);
-		const hasStars = flags.includes(MessageSystemFlag.Flagged);
-
-		const updates: {
-			isRead?: boolean;
-			hasStars?: boolean;
-			star?: (typeof StarColor)[keyof typeof StarColor];
-		} = {};
-		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.
-	 */
-	private async setMessageFlag(
-		messageId: string,
-		flagName: string,
-		present: boolean,
-	): Promise<void> {
-		if (!this.messageFlagService) return;
-		if (present) {
-			await this.messageFlagService.addFlag(messageId, flagName);
-			return;
-		}
-		await this.messageFlagService.removeFlag(messageId, flagName);
-	}
-
-	private async hasPendingPush(
-		messageId: string,
-		flagName: string,
-	): Promise<boolean> {
-		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.
-	 */
-	private async mirrorKeywordFlag(
-		messageId: string,
-		flagName: string,
-		serverFlags: string[],
-	): Promise<void> {
-		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);
-	}
-
-	/**
-	 * Fetch a batch of messages using the managed connection.
-	 * Assumes mailbox is already open from fetchUidsToSync.
-	 */
-	private async fetchMessageBatch(uids: number[]): Promise<ImapMessage[]> {
-		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.
-	 */
-	private async folderRolesFor(
-		accountId: string,
-		accountConfigId: string,
-	): Promise<AccountFolderRoles> {
-		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.
-	 */
-	private async probeDepartures(
-		mailbox: MailboxItem,
-		accountId: string,
-		applicable: Array<ImapMessage & { envelope: ImapEnvelope }>,
-	): Promise<DepartureVerdicts> {
-		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),
-			),
-		);
-	}
-
-	private async trySaveMessage(
-		mailbox: MailboxItem,
-		accountId: string,
-		accountConfigId: string,
-		msg: ImapMessage,
-		roles: AccountFolderRoles,
-		departures: DepartureVerdicts,
-	): Promise<BatchOutcome> {
-		const mailboxId = mailbox.mailboxId;
-		return this.saveMessage(
-			mailbox,
-			accountId,
-			accountConfigId,
-			msg,
-			roles,
-			departures,
-		)
-			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
-			.catch((error): BatchOutcome => {
-				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 };
-			});
-	}
-
-	private async saveMessage(
-		mailbox: MailboxItem,
-		accountId: string,
-		accountConfigId: string,
-		msg: ImapMessage,
-		roles: AccountFolderRoles,
-		departures: DepartureVerdicts,
-	): Promise<SaveMessageResult | null> {
-		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: Array<{
-			addresses: ImapAddress[] | undefined;
-			role: (typeof AddressRole)[keyof typeof AddressRole];
-		}> = [
-			{ 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;
-
-		// One unit of work for the whole message: on Postgres these repos are
-		// transaction-bound, so the Envelope, addresses, Message, BodyParts and
-		// ThreadMessage — and the transactional-outbox rows the Message write
-		// appends — all commit together. A throw anywhere rolls the whole set
-		// back, so a failed save never strands a Message without its Envelope
-		// (#1072). Writes run in sequence: a single transaction serialises on one
-		// connection, and it lets the Envelope land before the Message, with the
-		// ThreadMessage written last so the list path never anchors on a
-		// ThreadMessage whose Message does not yet exist (#1209).
-		await this.unitOfWork.transaction(async (repos) => {
-			await repos.envelope.upsertEnvelope({
-				envelopeId,
-				messageId,
-				dateValue: sentDate,
-				dateRaw: envelope.date,
-				subject: envelope.subject,
-				messageIdValue: envelope.messageId,
-			});
-
-			for (const { addresses, role } of addressOps) {
-				await this.saveAddresses(
-					repos.address,
-					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 repos.envelope.upsertBodyParts(messageId, bodyParts);
-			}
-
-			const { item, created } = await repos.message.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 repointed =
-				contested &&
-				departures.departed.has(verdict) &&
-				!(await this.holdsCopyOf(repos.message, messageId, mailboxId));
-			if (repointed) {
-				await repos.message.updateUid(messageId, msg.uid, mailboxId);
-				await this.repointThreadMessage(
-					repos.threadMessage,
-					accountConfigId,
-					messageId,
-					mailboxId,
-					msg.uid,
-					sighting === "discarded",
-				);
-			}
-
-			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 repos.address.reconcileJunkOnlyForMessage(
-					messageId,
-					roles.configJunkRoles,
-				);
-			}
-
-			await this.createThreadForMessage(
-				repos.threadMessage,
-				messageId,
-				mailboxId,
-				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.
-	 */
-	private async holdsCopyOf(
-		messageService: IMessageRepository,
-		messageId: string,
-		mailboxId: string,
-	): Promise<boolean> {
-		const rows = await messageService.get([
-			deriveCopyMessageId(messageId, mailboxId),
-		]);
-		return rows.length > 0;
-	}
-
-	/**
-	 * Follow a re-pointed Message with the ThreadMessage row that renders it.
-	 * The listing and every folder count read that row, so leaving it behind
-	 * would show the message in the folder it just left and hide it from the one
-	 * it landed in. `isDeleted` follows the same rule the move path uses — true
-	 * in Trash, false anywhere else — so a message another client rescues out of
-	 * Trash stops being filtered out of listings.
-	 */
-	private async repointThreadMessage(
-		threadMessageService: IThreadMessageRepository,
-		accountConfigId: string,
-		messageId: string,
-		mailboxId: string,
-		uid: number,
-		isDeleted: boolean,
-	): Promise<void> {
-		const row = await threadMessageService.findByMessageId(
-			accountConfigId,
-			messageId,
-		);
-		if (row === null) return;
-		if (
-			row.mailboxId === mailboxId &&
-			row.uid === uid &&
-			row.isDeleted === isDeleted
-		) {
-			return;
-		}
-
-		await threadMessageService.update(
-			row.accountConfigId,
-			row.threadMessageId,
-			{ mailboxId, uid, isDeleted },
-			{
-				composites: {
-					mailboxId: row.mailboxId,
-					sentDate: row.sentDate,
-					isRead: row.isRead,
-					isDeleted: row.isDeleted,
-					hasStars: row.hasStars,
-					hasAttachment: row.hasAttachment,
-				},
-			},
-		);
-	}
-
-	private async saveAddresses(
-		addressService: IAddressRepository,
-		messageId: string,
-		accountConfigId: string,
-		addresses: ImapAddress[] | undefined,
-		role: (typeof AddressRole)[keyof typeof AddressRole],
-		sighting: AddressSighting,
-	) {
-		if (!addresses) return;
-
-		// Pre-compute address data with order indices, filtering valid addresses
-		const addressData: Array<{
-			localPart: string;
-			domain: string;
-			displayName: string;
-			order: number;
-		}> = [];
-
-		// 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,
-			});
-		}
-	}
-
-	/**
-	 * Create or update Thread and ThreadMessage for a synced message.
-	 *
-	 * Thread ID derivation (RFC 2822 compliant):
-	 * 1. If References header exists, use the FIRST entry as thread root
-	 *    (References format: <root> <parent1> ... <direct-parent>)
-	 * 2. Fall back to In-Reply-To if no References
-	 * 3. Fall back to Message-ID (this message is a thread root)
-	 *
-	 * This ensures proper threading even when messages arrive out of order.
-	 *
-	 * `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.
-	 */
-	private async createThreadForMessage(
-		threadMessageService: IThreadMessageRepository,
-		messageId: string,
-		mailboxId: string,
-		accountConfigId: string,
-		uid: number,
-		internalDate: number,
-		sentDate: number,
-		envelope: ImapEnvelope,
-		flags: string[],
-		category: ThreadMessageItem["category"],
-		references?: string[],
-		hasAttachment = false,
-	): Promise<void> {
-		// Determine the thread root Message-ID
-		let rootMessageIdHeader: string;
-
-		if (references && references.length > 0) {
-			// References header exists - first entry is the thread root (RFC 2822)
-			rootMessageIdHeader = references[0];
-		} else if (envelope.inReplyTo) {
-			// No References, but has In-Reply-To - use as thread root
-			// (This is a reply to a single message, which becomes the root)
-			rootMessageIdHeader = envelope.inReplyTo;
-		} else if (isValidMessageId(envelope.messageId)) {
-			// No References, no In-Reply-To - this message is a thread root
-			rootMessageIdHeader = envelope.messageId;
-		} else {
-			// No usable header (missing, empty, or a "<>" delivery-failure
-			// placeholder). Fall back to the always-present internal messageId so
-			// this message becomes a standalone thread-of-one. Distinct headerless
-			// messages keep distinct ids, so they never collide into one bogus
-			// thread, and every persisted Message gets exactly one ThreadMessage.
-			rootMessageIdHeader = messageId;
-		}
-
-		// Derive threadId from the root Message-ID (deterministic)
-		const threadId = deriveThreadId(accountConfigId, rootMessageIdHeader);
-
-		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: unknown) => {
-				// Ignore conflict errors (idempotent create)
-				if (
-					(error as { name?: string })?.name === "CreateFailedConflictError"
-				) {
-					return;
-				}
-				throw error;
-			});
-	}
-}
-
-/**
- * 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: ImapBodyStructure | undefined,
-): BodyPartUpsertInput[] => {
-	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 }
-			: {}),
-	}));
-};