@remit/imap-worker 0.0.1

package/src/handlers/sync-message-body.test.ts

@@ -0,0 +1,375 @@
+import assert from "node:assert";
+import { afterEach, describe, mock, test } from "node:test";
+import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
+import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+import { getClient } from "@remit/backend/client";
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger-lambda";
+import { BodySyncService, type SyncedMessage } from "@remit/mailbox-service";
+import { mockClient } from "aws-sdk-client-mock";
+import { resetBodySyncGateCache } from "../body-sync-gate.js";
+import { __warmPoolSizeForTest } from "../connection-scope.js";
+import type { SyncMessageBodyEvent } from "../events.js";
+import {
+	BODY_SYNC_MAX_ATTEMPTS,
+	buildRetryableFailureError,
+	getBodySyncMaxAttempts,
+	resolveBatch,
+	syncMessageBody,
+} from "./sync-message-body.js";
+import { BODY_BATCH_SIZE, batchSyncedMessages } from "./sync-messages.js";
+
+const silentLogger = (() => {
+	const noop = () => {};
+	const log = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return log;
+})();
+
+const baseEvent = {
+	type: "SYNC_MESSAGE_BODY" as const,
+	accountId: "test-account-123",
+	mailboxId: "test-mailbox-456",
+	eventId: "event-789",
+	timestamp: 1700000000000,
+};
+
+describe("resolveBatch — event-shape preference", () => {
+	test("prefers the new messages[] shape and exposes the uid map", () => {
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["msg-1", "msg-2"],
+			messages: [
+				{ messageId: "msg-1", uid: 101 },
+				{ messageId: "msg-2", uid: 102 },
+			],
+		};
+
+		const { messageIds, uidByMessageId } = resolveBatch(event);
+
+		assert.deepEqual(messageIds, ["msg-1", "msg-2"]);
+		assert.ok(uidByMessageId);
+		assert.equal(uidByMessageId.get("msg-1"), 101);
+		assert.equal(uidByMessageId.get("msg-2"), 102);
+	});
+
+	test("derives messageIds from messages[] when both disagree", () => {
+		// messages[] is authoritative; a stale messageIds list must not leak in.
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["stale"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+		};
+
+		const { messageIds } = resolveBatch(event);
+
+		assert.deepEqual(messageIds, ["msg-1"]);
+	});
+
+	test("falls back to legacy messageIds[] with no uid map", () => {
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["msg-1", "msg-2", "msg-3"],
+		};
+
+		const { messageIds, uidByMessageId } = resolveBatch(event);
+
+		assert.deepEqual(messageIds, ["msg-1", "msg-2", "msg-3"]);
+		assert.equal(uidByMessageId, undefined);
+	});
+
+	test("force defaults to false when the event omits it (legacy/bulk events)", () => {
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["msg-1"],
+		};
+
+		assert.equal(resolveBatch(event).force, false);
+	});
+
+	test("force is carried from the event's read-miss re-arm cue", () => {
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["msg-1"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+			force: true,
+		};
+
+		assert.equal(resolveBatch(event).force, true);
+	});
+
+	test("empty messages[] resolves to an empty batch, not the legacy list", () => {
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			messageIds: ["should-be-ignored"],
+			messages: [],
+		};
+
+		const { messageIds, uidByMessageId } = resolveBatch(event);
+
+		assert.deepEqual(messageIds, []);
+		assert.ok(uidByMessageId);
+		assert.equal(uidByMessageId.size, 0);
+	});
+});
+
+describe("buildRetryableFailureError — the DLQ-propagation signal", () => {
+	// Genuine processing failures must propagate (issue #1270): syncMessageBody
+	// throws this while SQS redelivery budget remains, instead of swallowing the
+	// failure into a fresh re-enqueue. index.ts's SQS handler catches it and
+	// reports the record as a batch item failure, so SQS redelivers it — and
+	// once the queue's own maxReceiveCount is hit, the record dead-letters into
+	// the body-dlq (alarmed in infra/stacks/dev/stacks/remit-worker-monitoring-stack.ts).
+
+	test("names every failed message id and the current attempt", () => {
+		const error = buildRetryableFailureError(["msg-1", "msg-2"], 1);
+
+		assert.match(error.message, /msg-1/);
+		assert.match(error.message, /msg-2/);
+		assert.match(error.message, /attempt 1\/3/);
+	});
+
+	test("is a real Error instance so it propagates like any other failure", () => {
+		const error = buildRetryableFailureError(["msg-1"], 2);
+		assert.ok(error instanceof Error);
+	});
+
+	test("BODY_SYNC_MAX_ATTEMPTS matches the body queue's maxReceiveCount (3)", () => {
+		// See MAX_RECEIVE_COUNT in infra/stacks/dev/stacks/remit-queue-stack.ts.
+		assert.equal(BODY_SYNC_MAX_ATTEMPTS, 3);
+	});
+});
+
+describe("getBodySyncMaxAttempts — env-derived, CDK-injected threshold (#1270)", () => {
+	test("parses the CDK-injected env var (derived from the queue's MAX_RECEIVE_COUNT)", () => {
+		assert.equal(getBodySyncMaxAttempts({ BODY_SYNC_MAX_ATTEMPTS: "3" }), 3);
+		assert.equal(getBodySyncMaxAttempts({ BODY_SYNC_MAX_ATTEMPTS: "5" }), 5);
+	});
+
+	test("defaults to 3 when unset (local dev, unit tests) — matches the queue's own default", () => {
+		assert.equal(getBodySyncMaxAttempts({}), 3);
+	});
+
+	test("defaults to 3 on a non-numeric or non-positive value", () => {
+		assert.equal(getBodySyncMaxAttempts({ BODY_SYNC_MAX_ATTEMPTS: "nope" }), 3);
+		assert.equal(getBodySyncMaxAttempts({ BODY_SYNC_MAX_ATTEMPTS: "0" }), 3);
+		assert.equal(getBodySyncMaxAttempts({ BODY_SYNC_MAX_ATTEMPTS: "-1" }), 3);
+	});
+});
+
+describe("syncMessageBody — pause gate runs before connection reuse", () => {
+	afterEach(() => {
+		mockClient(SSMClient).reset();
+		resetBodySyncGateCache();
+	});
+
+	test("paused: acks-and-skips before borrowing a warm connection", async () => {
+		const accountId = "paused-account-zzz";
+		mockClient(SSMClient)
+			.on(GetParameterCommand)
+			.resolves({ Parameter: { Value: "false" } });
+
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			accountId,
+			messageIds: ["msg-1"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+		};
+
+		await syncMessageBody(event, silentLogger);
+
+		// Returning at the gate must not touch the warm pool (no account lookup,
+		// no IMAP connection) — proves the gate is first.
+		assert.strictEqual(
+			__warmPoolSizeForTest(accountId),
+			0,
+			"paused handler must not create a warm connection",
+		);
+	});
+});
+
+describe("syncMessageBody — DLQ propagation (integrated, #1270)", () => {
+	const accountId = "cap-account-zzz";
+	const mailboxId = "cap-mailbox-zzz";
+
+	const cappedAccount = (): AccountItem =>
+		({
+			accountId,
+			accountConfigId: "cap-acfg-zzz",
+			connectionState: "authenticated",
+			username: "cap@imap.example.com",
+			imapHost: "imap.example.com",
+			imapPort: 993,
+			imapTls: true,
+			// deserializeEncryptedPayload just needs base64-decodable strings; the
+			// mocked secrets.decrypt below never inspects the actual bytes.
+			passwordHash: JSON.stringify({
+				encryptedDek: "",
+				encryptedData: "",
+				iv: "",
+				authTag: "",
+			}),
+		}) as unknown as AccountItem;
+
+	const cappedMailbox = (): MailboxItem =>
+		({ fullPath: "INBOX" }) as unknown as MailboxItem;
+
+	afterEach(() => {
+		mock.restoreAll();
+		mockClient(SSMClient).reset();
+		mockClient(SQSClient).reset();
+		resetBodySyncGateCache();
+	});
+
+	test("below BODY_SYNC_MAX_ATTEMPTS: throws instead of re-enqueueing, so SQS redelivers the record (issue #1270)", async () => {
+		// This is the mechanism that lets a genuine processing failure ever reach
+		// the body-dlq: the handler used to swallow every failure into a fresh
+		// SQS SendMessage and always return successfully, so the queue's own
+		// maxReceiveCount/DLQ never engaged. Throwing here is what index.ts's SQS
+		// handler turns into a batchItemFailure, which SQS then redelivers.
+		mockClient(SSMClient)
+			.on(GetParameterCommand)
+			.resolves({ Parameter: { Value: "true" } });
+		const sqsMock = mockClient(SQSClient);
+
+		mock.method((await getClient()).account, "get", async () =>
+			cappedAccount(),
+		);
+		mock.method((await getClient()).mailbox, "get", async () =>
+			cappedMailbox(),
+		);
+		mock.method(
+			(await getClient()).secrets,
+			"decrypt",
+			async () => "fake-password",
+		);
+		mock.method(BodySyncService.prototype, "syncBodies", async () => ({
+			syncedCount: 0,
+			syncedMessageIds: [],
+			skippedCount: 0,
+			failedCount: 1,
+			failedMessageIds: ["msg-1"],
+		}));
+
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			accountId,
+			mailboxId,
+			messageIds: ["msg-1"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+		};
+
+		await assert.rejects(
+			() => syncMessageBody(event, silentLogger, 1),
+			(err: unknown) =>
+				err instanceof Error &&
+				/Body sync failed for 1 message/.test(err.message),
+		);
+
+		assert.equal(
+			sqsMock.commandCalls(SendMessageCommand).length,
+			0,
+			"no manual re-enqueue — SQS's own redelivery owns the retry now",
+		);
+	});
+
+	test("cursor_invalid: acks-and-skips without ever calling BodySyncService.syncBodies (#1272)", async () => {
+		// The cheap pre-check (isCursorRebuildNeeded, run before borrowing any
+		// connection — frugal, epic #1281 invariant 6) catches an already-paused
+		// mailbox before BodySyncService is ever invoked. The structural backstop
+		// for a cursor that trips *during* this call — guardConnectionCursor's
+		// openBox override — is covered directly in mailbox-cursor.test.ts.
+		mockClient(SSMClient)
+			.on(GetParameterCommand)
+			.resolves({ Parameter: { Value: "true" } });
+
+		mock.method((await getClient()).account, "get", async () =>
+			cappedAccount(),
+		);
+		mock.method((await getClient()).mailbox, "get", async () => ({
+			...cappedMailbox(),
+			mailboxId,
+			cursorState: "cursor_invalid",
+		}));
+		mock.method(
+			(await getClient()).secrets,
+			"decrypt",
+			async () => "fake-password",
+		);
+		const syncBodies = mock.method(
+			BodySyncService.prototype,
+			"syncBodies",
+			async () => {
+				throw new Error(
+					"must not be called while the mailbox cursor is paused",
+				);
+			},
+		);
+
+		const event: SyncMessageBodyEvent = {
+			...baseEvent,
+			accountId,
+			mailboxId,
+			messageIds: ["msg-1"],
+			messages: [{ messageId: "msg-1", uid: 101 }],
+		};
+
+		// Must resolve, not reject — a paused cursor is a routine, expected pause
+		// (epic #1281 invariant 3), not a fault to retry/DLQ.
+		await syncMessageBody(event, silentLogger, 1);
+
+		assert.equal(
+			syncBodies.mock.calls.length,
+			0,
+			"outbound body fetch must not run while the mailbox cursor is paused",
+		);
+	});
+});
+
+describe("batchSyncedMessages — one batch == one ranged fetch", () => {
+	const makeSynced = (count: number): SyncedMessage[] =>
+		Array.from({ length: count }, (_, i) => ({
+			messageId: `msg-${i}`,
+			uid: i + 1,
+		}));
+
+	test("batch size is raised to 200", () => {
+		assert.equal(BODY_BATCH_SIZE, 200);
+	});
+
+	test("packs up to 200 messages into a single batch", () => {
+		const batches = batchSyncedMessages(makeSynced(200));
+
+		assert.equal(batches.length, 1);
+		assert.equal(batches[0].length, 200);
+	});
+
+	test("splits 201 messages into 200 + 1", () => {
+		const batches = batchSyncedMessages(makeSynced(201));
+
+		assert.equal(batches.length, 2);
+		assert.equal(batches[0].length, 200);
+		assert.equal(batches[1].length, 1);
+	});
+
+	test("keeps messageId+uid pairs intact per batch", () => {
+		const batches = batchSyncedMessages(makeSynced(3));
+
+		assert.deepEqual(batches[0], [
+			{ messageId: "msg-0", uid: 1 },
+			{ messageId: "msg-1", uid: 2 },
+			{ messageId: "msg-2", uid: 3 },
+		]);
+	});
+
+	test("empty input yields no batches", () => {
+		assert.deepEqual(batchSyncedMessages([]), []);
+	});
+});

package/src/handlers/sync-message-body.ts

@@ -0,0 +1,337 @@
+import { getClient } from "@remit/backend/client";
+import type { Logger } from "@remit/logger-lambda";
+import { MetricUnit, metrics } from "@remit/logger-lambda";
+import {
+	BodySyncService,
+	type FilterConfig,
+	guardConnectionCursor,
+	isCursorRebuildNeeded,
+	MailboxCursorPausedError,
+	PlacementMoveService,
+	resolveExhaustedBodySyncFailures,
+} from "@remit/mailbox-service";
+import { env } from "expect-env";
+import { isAccountDeleted } from "../account-check.js";
+import { isBodySyncEnabled } from "../body-sync-gate.js";
+import {
+	borrowWarmConnection,
+	createConnectionScopeWithCredentials,
+} from "../connection-scope.js";
+import type { SyncMessageBodyEvent } from "../events.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+
+const bodySyncEnabledParameterName = env.BODY_SYNC_ENABLED_PARAMETER_NAME;
+
+/**
+ * Fallback when `BODY_SYNC_MAX_ATTEMPTS` is unset (local dev, unit tests).
+ * Matches the body queue's own `MAX_RECEIVE_COUNT` default
+ * (`infra/stacks/dev/stacks/remit-queue-stack.ts`) so an environment that
+ * never injects the var still behaves like production.
+ */
+const DEFAULT_BODY_SYNC_MAX_ATTEMPTS = 3;
+
+/**
+ * Reads the redelivery-budget-exhaustion threshold. CDK derives
+ * `BODY_SYNC_MAX_ATTEMPTS` from the body queue's own `MAX_RECEIVE_COUNT`
+ * (`remit-worker-stack.ts`) so the two constants can't drift apart — a
+ * hand-copied duplicate here previously risked the worker resolving
+ * "last attempt" on a different delivery than the queue's redrive policy
+ * actually uses (issue #1270). SQS's own `ApproximateReceiveCount` is the
+ * source of truth for how many times a record has been delivered; once it
+ * reaches this value, the current invocation is the last attempt before the
+ * queue's own redrive would DLQ the record, so retry exhaustion is resolved
+ * here (see `resolveExhaustedBodySyncFailures`) instead of letting the
+ * record dead-letter with no diagnosis.
+ */
+export const getBodySyncMaxAttempts = (
+	processEnv: NodeJS.ProcessEnv = process.env,
+): number => {
+	const raw = processEnv.BODY_SYNC_MAX_ATTEMPTS;
+	if (!raw) return DEFAULT_BODY_SYNC_MAX_ATTEMPTS;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0
+		? parsed
+		: DEFAULT_BODY_SYNC_MAX_ATTEMPTS;
+};
+
+export const BODY_SYNC_MAX_ATTEMPTS = getBodySyncMaxAttempts();
+
+/**
+ * The ordered message ids to sync, plus a uid lookup when the event carried the
+ * preferred `messages` shape. The uid map lets the body-sync service skip the
+ * per-message DDB get; legacy events (ids only) leave it undefined and the
+ * service resolves uids itself.
+ */
+export interface ResolvedBatch {
+	messageIds: string[];
+	uidByMessageId?: Map<string, number>;
+	force: boolean;
+}
+
+export const resolveBatch = (event: SyncMessageBodyEvent): ResolvedBatch => {
+	const force = event.force === true;
+	if (event.messages !== undefined) {
+		return {
+			messageIds: event.messages.map((m) => m.messageId),
+			uidByMessageId: new Map(
+				event.messages.map((m): [string, number] => [m.messageId, m.uid]),
+			),
+			force,
+		};
+	}
+	return { messageIds: event.messageIds, force };
+};
+
+/**
+ * Build the loud, structured error thrown when a batch still has failed
+ * messages and SQS redelivery budget left. Throwing (rather than swallowing
+ * into a fresh re-enqueue) is what lets a genuine processing failure reach
+ * the body-dlq once `BODY_SYNC_MAX_ATTEMPTS` is exhausted — the SQS-level
+ * redrive owns retry scheduling now, not this handler.
+ */
+export const buildRetryableFailureError = (
+	failedMessageIds: string[],
+	receiveCount: number,
+): Error =>
+	new Error(
+		`Body sync failed for ${failedMessageIds.length} message(s) ` +
+			`(attempt ${receiveCount}/${BODY_SYNC_MAX_ATTEMPTS}): ${failedMessageIds.join(", ")}`,
+	);
+
+export const syncMessageBody = async (
+	event: SyncMessageBodyEvent,
+	log: Logger,
+	receiveCount = 1,
+): Promise<void> => {
+	const { accountId, mailboxId } = event;
+
+	// Prefer the messageId+uid pairs when present (one ranged FETCH, no
+	// per-message UID lookup); fall back to the legacy id-only list otherwise.
+	const { messageIds, force } = resolveBatch(event);
+
+	log.info(
+		{
+			event: event.type,
+			accountId,
+			mailboxId,
+			messageCount: messageIds.length,
+			hasUids: event.messages !== undefined,
+			force,
+			receiveCount,
+		},
+		"Handling event",
+	);
+
+	// Pause gate stays first: ack-and-skip before touching any account/IMAP state.
+	if (!(await isBodySyncEnabled(bodySyncEnabledParameterName, log))) {
+		log.info(
+			{
+				event: event.type,
+				accountId,
+				mailboxId,
+				messageCount: messageIds.length,
+			},
+			"Body sync paused via SSM toggle, acking and skipping",
+		);
+		return;
+	}
+
+	const {
+		account: accountService,
+		mailbox: mailboxService,
+		mailboxSpecialUse: mailboxSpecialUseService,
+		message: messageService,
+		threadMessage: threadMessageService,
+		address: addressService,
+		envelope: envelopeService,
+		placementMove: markerService,
+		filter: filterService,
+		filterAnchor: filterAnchorService,
+		messageLabel: messageLabelService,
+		storage,
+		secrets,
+	} = await getClient();
+
+	const account = await accountService.get(accountId);
+	if (!account) {
+		throw new Error(`Account ${accountId} not found`);
+	}
+
+	if (isAccountDeleted(account, log)) {
+		return;
+	}
+
+	// PLACEMENT_MOVE_PUSH rides messageMgmtQueue (issue #1271) — same queue
+	// the general MessageMoveService move/delete/copy machinery uses, not a
+	// dedicated one.
+	const placementMoveQueueUrl = process.env.SQS_QUEUE_URL_MESSAGE_MGMT;
+	const placementMoveService = placementMoveQueueUrl
+		? new PlacementMoveService({
+				messageService,
+				threadMessageService,
+				markerService,
+				sqsQueueUrl: placementMoveQueueUrl,
+			})
+		: undefined;
+
+	await withOAuthLifecycle(
+		buildLifecycleDeps(secrets, accountService),
+		account,
+		log,
+		async (credentials) => {
+			const mailbox = await mailboxService.get(accountId, mailboxId);
+
+			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
+			// paused never even borrows a connection. This is an optimization only
+			// — guardConnectionCursor below is the structural guarantee, so a
+			// handler that forgot this check still cannot reach a stale UID.
+			if (isCursorRebuildNeeded(mailbox.cursorState)) {
+				log.info(
+					{ accountId, mailboxId, cursorState: mailbox.cursorState },
+					"Mailbox cursor not normal; pausing outbound body sync this round",
+				);
+				return;
+			}
+
+			// Warm reuse: borrow a live IMAP connection from the module-scoped pool
+			// (keyed by accountId) instead of dialing a fresh one per invocation. A
+			// warm container skips TCP+TLS+LOGIN+SELECT; a dead pooled connection is
+			// liveness-checked and replaced inside borrowWarmConnection.
+			const borrowed = borrowWarmConnection(accountId, () =>
+				createConnectionScopeWithCredentials(account, credentials),
+			);
+
+			// A confident, actionable placement verdict moves mail directly on
+			// body-sync. Safety lives in the verdict itself (only confident,
+			// INBOX/Junk-only) and the movedByRemit loop guard.
+			const placementConfig = placementMoveService
+				? {
+						mailboxSpecialUseService,
+						placementMoveService,
+					}
+				: undefined;
+
+			// A matched filter's actions (label upsert, exclusive move) apply on
+			// the same body-sync pass, reusing the placement mover for the move
+			// (RFC 034 Decision 3.1). Absent the placement mover there is no move
+			// path, so filters stay off — the two share the same enqueue plumbing.
+			const filterConfig: FilterConfig | undefined = placementMoveService
+				? {
+						filterService,
+						filterAnchorService,
+						messageLabelService,
+						placementMoveService,
+					}
+				: undefined;
+
+			const bodySyncService = new BodySyncService(
+				messageService,
+				storage,
+				threadMessageService,
+				addressService,
+				envelopeService,
+				log,
+				placementConfig,
+				filterConfig,
+			);
+
+			// Guard at the openBox choke point (epic #1281 invariants 3 & 5). The
+			// served UIDVALIDITY is only knowable by opening the box, which only a
+			// genuine fetch needs — BodySyncService.syncBodies skips connecting
+			// entirely when every message already has a stored body (nothing would
+			// touch a stored UID either way) — so the check fires lazily, the first
+			// time `openBox` is actually called, instead of forcing an extra open
+			// on every event.
+			const getConnectionChecked = async () =>
+				guardConnectionCursor(
+					await borrowed.getConnection(),
+					{ mailboxService },
+					accountId,
+					mailbox,
+				);
+
+			// Both the sync attempt AND the retry-exhaustion resolution below run
+			// against the SAME borrowed connection, so the mailbox stays open
+			// across the two — the connection is only released once both are done.
+			await (async () => {
+				const result = await bodySyncService.syncBodies(
+					messageIds,
+					accountId,
+					account.accountConfigId,
+					mailbox.fullPath,
+					getConnectionChecked,
+					force,
+				);
+
+				if (result.failedMessageIds.length === 0) {
+					return;
+				}
+
+				if (receiveCount < BODY_SYNC_MAX_ATTEMPTS) {
+					// Redelivery budget remains: let SQS retry the whole record
+					// naturally. Messages that already synced skip via the
+					// already-stored guard on the next attempt, so only the failed
+					// ones actually redo work. This — not a manual re-enqueue — is
+					// what lets a genuine processing failure ever reach the body-dlq.
+					throw buildRetryableFailureError(
+						result.failedMessageIds,
+						receiveCount,
+					);
+				}
+
+				// Redelivery budget exhausted: a persistent per-message failure is
+				// never a steady state (epic #1281 invariant 3). Resolve every
+				// failed id into exactly one of the two terminal outcomes instead of
+				// letting the record dead-letter with no diagnosis.
+				const { reconciledMessageIds, brokenMessageIds } =
+					await resolveExhaustedBodySyncFailures(
+						{
+							messageService,
+							threadMessageService,
+							storageService: storage,
+							log,
+						},
+						{
+							accountId,
+							accountConfigId: account.accountConfigId,
+							mailboxId,
+							mailboxPath: mailbox.fullPath,
+							failedMessageIds: result.failedMessageIds,
+							getConnection: getConnectionChecked,
+						},
+					);
+
+				if (reconciledMessageIds.length > 0) {
+					metrics.addMetric(
+						"bodySyncStaleRowReconciled",
+						MetricUnit.Count,
+						reconciledMessageIds.length,
+					);
+				}
+				if (brokenMessageIds.length > 0) {
+					metrics.addMetric(
+						"bodySyncMessageBroken",
+						MetricUnit.Count,
+						brokenMessageIds.length,
+					);
+				}
+			})()
+				.catch((error: unknown) => {
+					// Expected pause (epic #1281 invariant 3), not a fault: ack and
+					// skip rather than propagating into SQS retry/DLQ. The read stays
+					// served from whatever is already stored; the fetch resumes once
+					// the mailbox returns to normal.
+					if (error instanceof MailboxCursorPausedError) {
+						log.info(
+							{ accountId, mailboxId, cursorState: error.state },
+							"UIDVALIDITY changed; mailbox cursor tripped, pausing outbound body sync",
+						);
+						return;
+					}
+					throw error;
+				})
+				.finally(() => borrowed.release());
+		},
+	);
+};