@remit/mailbox-service 0.0.110 → 0.0.112

package/src/message-sync.ts

@@ -8,7 +8,6 @@ import type {
 	IMessageFlagRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
-	IUnitOfWork,
 	MailboxItem,
 	ThreadMessageItem,
 } from "@remit/data-ports";
@@ -19,9 +18,11 @@ import {
 	deriveBodyPartId,
 	deriveCopyMessageId,
 	deriveEnvelopeId,
+	deriveMessageId,
 	deriveMessageIdFromSource,
 	deriveThreadId,
 	isValidMessageId,
+	wireMessageId,
 } from "@remit/data-ports/id";
 import {
 	AddressRole,
@@ -29,6 +30,7 @@ import {
 	MessageKeywordFlag,
 	MessageSystemFlag,
 	StarColor,
+	SyncWarningStage,
 } from "@remit/domain-enums";
 import pMap from "p-map";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
@@ -45,9 +47,8 @@ import {
 	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 type { SyncWarningRound, SyncWarningService } from "./sync-warning.js";
 import {
 	advanceChangeCursor,
 	advanceUidWatermarks,
@@ -59,6 +60,7 @@ import {
 	parseChangeCursor,
 	parseModseq,
 } from "./sync-watermarks.js";
+import { messageReferencesOf, parentOf, threadRootOf } from "./thread-root.js";
 import type {
 	ImapAddress,
 	ImapBodyStructure,
@@ -262,6 +264,21 @@ const unresolvedSightingUids = (outcomes: BatchOutcome[]): number[] =>
 			: [],
 	);
 
+const syncedUidsOf = (outcomes: BatchOutcome[]): number[] =>
+	outcomes.flatMap((outcome) =>
+		outcome.kind === "saved" && !outcome.result?.unresolvedSighting
+			? [outcome.uid]
+			: [],
+	);
+
+const saveFailedUidsOf = (outcomes: BatchOutcome[]): number[] =>
+	outcomes.flatMap((outcome) =>
+		outcome.kind === "failed" ? [outcome.uid] : [],
+	);
+
+const envelopeLessUidsOf = (messages: ImapMessage[]): number[] =>
+	messages.flatMap((msg) => (hasEnvelope(msg) ? [] : [msg.uid]));
+
 const emptySyncResult = (): SyncMessagesResult => ({
 	syncedCount: 0,
 	syncedMessageIds: [],
@@ -321,7 +338,6 @@ const messageIdForSighting = (
 
 export class MessageSyncService {
 	private log: SyncLogger;
-	private unitOfWork: IUnitOfWork;
 
 	constructor(
 		private connectionFactory: ManagedConnectionFactory,
@@ -334,11 +350,11 @@ export class MessageSyncService {
 		 */
 		private mailboxSpecialUseService: IMailboxSpecialUseRepository,
 		private messageService: IMessageRepository,
-		envelopeService: IEnvelopeRepository,
-		addressService: IAddressRepository,
+		private envelopeService: IEnvelopeRepository,
+		private addressService: IAddressRepository,
 		private threadMessageService: IThreadMessageRepository,
+		private syncWarningService: SyncWarningService,
 		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
@@ -360,14 +376,6 @@ export class MessageSyncService {
 		private quarantineService?: QuarantineService,
 	) {
 		this.log = logger ?? noopLogger;
-		this.unitOfWork =
-			unitOfWork ??
-			new PassThroughUnitOfWork({
-				message: messageService,
-				envelope: envelopeService,
-				address: addressService,
-				threadMessage: threadMessageService,
-			});
 	}
 
 	/**
@@ -430,6 +438,17 @@ export class MessageSyncService {
 			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({
@@ -453,6 +472,17 @@ export class MessageSyncService {
 		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
@@ -616,6 +646,12 @@ export class MessageSyncService {
 		// `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,
@@ -682,9 +718,10 @@ export class MessageSyncService {
 	 *   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).
+	 * - 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
@@ -737,9 +774,7 @@ export class MessageSyncService {
 		await pMap(
 			matched,
 			async ({ messageId, newUid, threadMessage }) => {
-				await this.unitOfWork.transaction((repos) =>
-					repos.message.updateUid(messageId, newUid, mailboxId),
-				);
+				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
@@ -747,41 +782,34 @@ export class MessageSyncService {
 				// 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,
-								},
+					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(
-			staleMessageIds,
-			(messageId) =>
-				this.unitOfWork.transaction((repos) =>
-					reconcileStaleMessage(
-						{
-							messageService: repos.message,
-							threadMessageService: repos.threadMessage,
-						},
-						accountConfigId,
-						messageId,
-					),
-				),
+			existingRows.filter((row) => stale.has(row.messageId)),
+			(row) =>
+				this.messageService.deleteIfPlacement(row.messageId, {
+					mailboxId,
+					uid: row.uid,
+				}),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
@@ -857,6 +885,15 @@ export class MessageSyncService {
 			: 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,
@@ -959,11 +996,11 @@ export class MessageSyncService {
 	 * 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.
+	 * 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.
@@ -1087,6 +1124,15 @@ export class MessageSyncService {
 		});
 		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
@@ -1153,6 +1199,24 @@ export class MessageSyncService {
 		};
 	}
 
+	private async settleHeaderWarnings(
+		accountConfigId: string,
+		mailbox: MailboxItem,
+		uidValidity: number,
+		round: SyncWarningRound,
+	): Promise<void> {
+		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
@@ -1218,7 +1282,16 @@ export class MessageSyncService {
 		}
 
 		await this.applyServerFlags(existing, msg.flags);
-		return null;
+		if (!departures.needsSave.has(messageId)) return null;
+
+		return this.saveMessage(
+			mailbox,
+			accountId,
+			accountConfigId,
+			msg,
+			roles,
+			departures,
+		);
 	}
 
 	/**
@@ -1392,6 +1465,72 @@ export class MessageSyncService {
 		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.
+	 */
+	private async restoreMissingStructure(
+		mailbox: MailboxItem,
+		accountId: string,
+		accountConfigId: string,
+		batchSize: number,
+	): Promise<boolean> {
+		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.
@@ -1555,123 +1694,129 @@ export class MessageSyncService {
 		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,
+		// 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,
-				dateValue: sentDate,
-				dateRaw: envelope.date,
-				subject: envelope.subject,
-				messageIdValue: envelope.messageId,
-			});
+				messageReferences,
+			);
+		}
 
-			for (const { addresses, role } of addressOps) {
-				await this.saveAddresses(
-					repos.address,
-					messageId,
-					accountConfigId,
-					addresses,
-					role,
-					sighting,
-				);
-			}
+		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 repos.envelope.upsertBodyParts(messageId, bodyParts);
-			}
+		// 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 repos.message.upsertWithStatus({
-				messageId,
-				mailboxId,
-				uid: msg.uid,
-				sequenceNumber: msg.seq,
-				rfc822Size: msg.size ?? 0,
-				internalDate: msg.internalDate.getTime(),
-				envelopeId,
-				rootBodyPartId,
-			});
+		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 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",
-				);
-			}
+		// 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" },
+			));
 
-			owned = created || item.mailboxId === mailboxId || repointed;
+		if (repointable && !repointed) unresolvedSighting = true;
 
-			// 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,
-				);
-			}
+		owned = created || item.mailboxId === mailboxId || repointed;
 
-			await this.createThreadForMessage(
-				repos.threadMessage,
+		// 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,
-				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,
+				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 };
 	}
@@ -1693,52 +1838,6 @@ export class MessageSyncService {
 		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,
@@ -1810,15 +1909,91 @@ export class MessageSyncService {
 	}
 
 	/**
-	 * 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)
+	 * 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.
+	 */
+	private async threadFor(
+		threadMessageService: IThreadMessageRepository,
+		messageId: string,
+		accountId: string,
+		accountConfigId: string,
+		envelope: ImapEnvelope,
+		references: string[] | undefined,
+	): Promise<string> {
+		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.
 	 *
-	 * This ensures proper threading even when messages arrive out of order.
+	 * 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.
+	 */
+	private async joinThreads(
+		threadMessageService: IThreadMessageRepository,
+		messageId: string,
+		accountId: string,
+		accountConfigId: string,
+		envelope: ImapEnvelope,
+		references: string[] | undefined,
+		threadId: string,
+	): Promise<void> {
+		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
@@ -1828,6 +2003,7 @@ export class MessageSyncService {
 		threadMessageService: IThreadMessageRepository,
 		messageId: string,
 		mailboxId: string,
+		accountId: string,
 		accountConfigId: string,
 		uid: number,
 		internalDate: number,
@@ -1838,30 +2014,14 @@ export class MessageSyncService {
 		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 threadId = await this.threadFor(
+			threadMessageService,
+			messageId,
+			accountId,
+			accountConfigId,
+			envelope,
+			references,
+		);
 
 		const isRead = flags.includes(MessageSystemFlag.Seen);
 
@@ -1920,6 +2080,16 @@ export class MessageSyncService {
 				}
 				throw error;
 			});
+
+		await this.joinThreads(
+			threadMessageService,
+			messageId,
+			accountId,
+			accountConfigId,
+			envelope,
+			references,
+			threadId,
+		);
 	}
 }