@remit/imap-worker 0.0.67 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/handlers/message-delete-terminal.ts

@@ -8,7 +8,7 @@ import {
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
 } from "@remit/mailbox-service";
-import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export interface MessageDeleteTerminalLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -125,25 +125,12 @@ export const resolveExhaustedMessageDeleteFailure = async (
 		"Delete could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder",
 	);
 
-	await deps.messageService.updateUid(messageId, uid, sourceMailboxId);
-
-	const threadMessages = await deps.threadMessageService.findAllByMessageId(
+	await restoreSourcePlacement(deps, {
 		accountConfigId,
 		messageId,
-	);
-	for (const threadMessage of threadMessages) {
-		const args = buildThreadMessageMoveRevert(
-			threadMessage,
-			uid,
-			sourceMailboxId,
-		);
-		await deps.threadMessageService.update(
-			threadMessage.accountConfigId,
-			threadMessage.threadMessageId,
-			args.set,
-			{ composites: args.composites },
-		);
-	}
+		sourceMailboxId,
+		uid,
+	});
 
 	return { outcome: "broken" };
 };

package/src/handlers/message-delete.test.ts

@@ -303,6 +303,10 @@ interface Harness {
 	allThreadMessages: Record<string, unknown>[];
 	getConnectionCount: number;
 	disconnectCount: number;
+	// Rejections handed to `getConnection`, one per call, oldest first. A
+	// dropped connection is how the guarded openBox gets skipped on a delivery
+	// that still goes on to settle the row.
+	connectionErrors: Error[];
 }
 
 let h: Harness;
@@ -367,6 +371,7 @@ const fresh = (): Harness => ({
 	],
 	getConnectionCount: 0,
 	disconnectCount: 0,
+	connectionErrors: [],
 });
 
 const deps = (): MessageDeleteDeps =>
@@ -417,6 +422,8 @@ const deps = (): MessageDeleteDeps =>
 		createConnectionScope: () => ({
 			getConnection: async () => {
 				h.getConnectionCount += 1;
+				const failure = h.connectionErrors.shift();
+				if (failure) throw failure;
 				return h.connection;
 			},
 			disconnect: async () => {
@@ -1178,6 +1185,41 @@ describe("handleMessageDelete", () => {
 		assert.equal(called("message.updateUid").length, 0);
 	});
 
+	// The terminal resolver opens the source itself, and since #1005 its answer
+	// WRITES a placement. A folder deleted and recreated renumbers every uid, so
+	// an unguarded probe finds whatever now sits at this one, reads it as "still
+	// at source", and binds the row to a stranger the next permanent delete
+	// expunges. The dropped connection is what makes it reachable: it skips the
+	// guarded openBox on the very delivery that goes on to settle.
+	it("never settles an exhausted delete off a probe that skipped the cursor guard", async () => {
+		h.connectionErrors = [new Error("ECONNRESET")];
+		h.connection.openBox = async () => ({ uidvalidity: 999 });
+
+		await handleMessageDelete(
+			moveEvent,
+			noopLog,
+			MESSAGE_DELETE_MAX_ATTEMPTS,
+			deps(),
+		);
+
+		assert.equal(
+			called("message.updateUid").length,
+			0,
+			"a renumbered folder answers for a different message; nothing settles off it",
+		);
+		assert.equal(
+			called("message.delete").length,
+			0,
+			"and nothing is reconciled away off it either",
+		);
+		assert.equal(
+			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
+				?.cursorState,
+			"cursor_invalid",
+			"the probe trips the mailbox into a rebuild instead",
+		);
+	});
+
 	it("skips without opening a connection when the cursor is rebuilding", async () => {
 		h.mailbox = {
 			mailboxId: "src-mbx",

package/src/handlers/message-delete.ts

@@ -259,7 +259,7 @@ export const handleMessageDelete = async (
 		accountConfigId: string,
 		getConnection: () => Promise<IImapConnection>,
 	): Promise<void> => {
-		const { outcome } = await resolveExhaustedMessageDeleteFailure(
+		const settled = await resolveExhaustedMessageDeleteFailure(
 			{ messageService, threadMessageService, log },
 			{
 				accountId,
@@ -270,9 +270,25 @@ export const handleMessageDelete = async (
 				sourceMailboxPath: mailboxPath,
 				getConnection,
 			},
-		);
+		).catch((settleError: unknown) => {
+			// The guarded probe found a mailbox whose UIDVALIDITY has moved. Every
+			// stored uid for this folder now names something else, so there is
+			// nothing here that may be settled off them, and the pause is the
+			// routine skip `guardMailboxCursor` documents, not a fault to re-throw
+			// out of the caller's catch.
+			if (settleError instanceof MailboxCursorPausedError) {
+				log.info(
+					{ accountId, messageId, mailboxId, cursorState: settleError.state },
+					"Mailbox cursor not normal; leaving the exhausted delete for the cursor rebuild",
+				);
+				return null;
+			}
+			throw settleError;
+		});
 
-		if (outcome === "broken") {
+		if (!settled) return;
+
+		if (settled.outcome === "broken") {
 			recordImapFailure("MESSAGE_DELETE_EXHAUSTED", "other");
 		}
 
@@ -380,6 +396,21 @@ export const handleMessageDelete = async (
 
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
+			// The terminal resolver opens the source itself, and its answer now
+			// WRITES a placement, so it has to reach IMAP through the same
+			// UIDVALIDITY choke point every other outbound operation does. An
+			// unguarded probe on a folder that was deleted and recreated finds
+			// whatever the server has renumbered onto this uid, reads it as "still
+			// at source", and binds the row to a stranger the next permanent delete
+			// would expunge.
+			const getGuardedConnection = async (): Promise<IImapConnection> =>
+				guardConnectionCursor(
+					await scope.getConnection(),
+					{ mailboxService },
+					accountId,
+					mailbox,
+				);
+
 			await scope
 				.getConnection()
 				.then(async (rawConnection) => {
@@ -490,7 +521,7 @@ export const handleMessageDelete = async (
 						await settleUnconfirmedTrashMove(
 							confirmation,
 							account.accountConfigId,
-							scope.getConnection,
+							getGuardedConnection,
 						);
 					} else {
 						// Permanent delete — reached only by `operation === "permanent_delete"`.
@@ -594,7 +625,7 @@ export const handleMessageDelete = async (
 					// failure this budget exists for.
 					await settleExhaustedDelete(
 						account.accountConfigId,
-						scope.getConnection,
+						getGuardedConnection,
 					);
 					log.error(
 						{ accountId, messageId, uid, mailboxPath, error: errorMessage },

package/src/handlers/message-move-terminal.test.ts

@@ -4,7 +4,10 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
-import type { IImapConnection } from "@remit/mailbox-service";
+import {
+	type IImapConnection,
+	placementBindingOf,
+} from "@remit/mailbox-service";
 import {
 	type MessageMoveTerminalLogger,
 	type ResolveExhaustedMessageMoveDeps,
@@ -60,21 +63,33 @@ interface MessageRow {
 	originalUid: number;
 }
 
+interface ThreadRow {
+	accountConfigId: string;
+	threadMessageId: string;
+	mailboxId: string;
+	uid: number;
+	isDeleted: boolean;
+}
+
 /**
  * The move's pending state IS the Message row, so these fakes hold real rows
- * and the assertions read the rows back — a resolver that reverted the
- * optimistic move (PR #652's defect) would show up here as a changed row, not
- * as an uncalled mock.
+ * and the assertions read the rows back — a resolver that settled the row on
+ * anything but the server's own answer shows up here as a changed row, not as
+ * an uncalled mock. `updateUid` writes what the repository writes: the settled
+ * pair AND the `active`/`synced` that clears `moving`.
  */
 const buildRepositories = (row: MessageRow) => {
 	const messages = new Map<string, MessageRow>([[row.messageId, row]]);
-	const threadMessages = new Map<
-		string,
-		{ accountConfigId: string; threadMessageId: string }
-	>([
+	const threadMessages = new Map<string, ThreadRow>([
 		[
 			`tm-${row.messageId}`,
-			{ accountConfigId: "cfg-1", threadMessageId: `tm-${row.messageId}` },
+			{
+				accountConfigId: "cfg-1",
+				threadMessageId: `tm-${row.messageId}`,
+				mailboxId: row.mailboxId,
+				uid: row.uid,
+				isDeleted: false,
+			},
 		],
 	]);
 
@@ -89,7 +104,22 @@ const buildRepositories = (row: MessageRow) => {
 				const current = messages.get(messageId);
 				if (current) messages.set(messageId, { ...current, ...input });
 			},
-		} as unknown as Pick<IMessageRepository, "delete">,
+			updateUid: async (
+				messageId: string,
+				newUid: number,
+				newMailboxId: string,
+			) => {
+				const current = messages.get(messageId);
+				if (current)
+					messages.set(messageId, {
+						...current,
+						uid: newUid,
+						mailboxId: newMailboxId,
+						status: "active",
+						syncStatus: "synced",
+					});
+			},
+		} as unknown as Pick<IMessageRepository, "delete" | "updateUid">,
 		threadMessageService: {
 			findAllByMessageId: async () => [...threadMessages.values()],
 			deleteMany: async (
@@ -97,9 +127,18 @@ const buildRepositories = (row: MessageRow) => {
 			) => {
 				for (const key of keys) threadMessages.delete(key.threadMessageId);
 			},
+			update: async (
+				_accountConfigId: string,
+				threadMessageId: string,
+				set: Partial<ThreadRow>,
+			) => {
+				const current = threadMessages.get(threadMessageId);
+				if (current)
+					threadMessages.set(threadMessageId, { ...current, ...set });
+			},
 		} as unknown as Pick<
 			IThreadMessageRepository,
-			"findAllByMessageId" | "deleteMany"
+			"findAllByMessageId" | "deleteMany" | "update"
 		>,
 	};
 };
@@ -118,6 +157,7 @@ const input = {
 	accountId: "acc-1",
 	accountConfigId: "cfg-1",
 	messageId: "msg-1",
+	sourceMailboxId: "mbx-inbox",
 	uid: 101,
 	sourceMailboxPath: "INBOX",
 };
@@ -150,7 +190,7 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		);
 	});
 
-	it("BROKEN: the message is still at the source — the row is left EXACTLY as it stands, alarm logged, never re-thrown", async () => {
+	it("BROKEN: the message is still at the source — the row is put back on the pair the server confirmed, alarm logged, never re-thrown", async () => {
 		const repos = buildRepositories(pendingMoveRow());
 		const { log, errors } = buildLogger();
 		const deps: ResolveExhaustedMessageMoveDeps = {
@@ -165,15 +205,46 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		});
 
 		assert.equal(result.outcome, "broken");
-		assert.deepEqual(
-			repos.messages.get("msg-1"),
-			pendingMoveRow(),
-			"a move that never reached the server is never reverted locally (PR #652)",
+		assert.equal(repos.messages.get("msg-1")?.mailboxId, "mbx-inbox");
+		assert.equal(repos.messages.get("msg-1")?.uid, 101);
+		assert.equal(
+			repos.threadMessages.get("tm-msg-1")?.mailboxId,
+			"mbx-inbox",
+			"the listing row follows the message back to the folder it never left",
 		);
-		assert.equal(repos.threadMessages.size, 1);
 		assert.ok(errors.some((e) => e.obj.alert === "message_move_failed"));
 	});
 
+	// Issue #1005: only `updateUid` clears `moving`, so a give-up that returned
+	// without calling it left the row naming the destination with the source's
+	// uid — a pair `bindsForeignUid` refuses, which made the message
+	// undeletable and unmovable for good.
+	it("BROKEN: the settled row is no longer refused by the placement guard (#1005)", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		assert.equal(
+			placementBindingOf(pendingMoveRow() as never),
+			"abandoned",
+			"the row starts in the state the delete route refuses as unverified",
+		);
+
+		await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		const settled = repos.messages.get("msg-1");
+		assert.ok(settled);
+		assert.equal(placementBindingOf(settled as never), "consistent");
+		assert.equal(settled.status, "active");
+	});
+
 	it("BROKEN: an empty FETCH the SEARCH contradicts never counts as gone", async () => {
 		const repos = buildRepositories(pendingMoveRow());
 		const { log } = buildLogger();
@@ -190,7 +261,93 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		});
 
 		assert.equal(result.outcome, "broken");
-		assert.deepEqual(repos.messages.get("msg-1"), pendingMoveRow());
+		assert.equal(
+			repos.messages.get("msg-1")?.mailboxId,
+			"mbx-inbox",
+			"a message the SEARCH still lists is at the source, and the row says so",
+		);
+	});
+
+	// The resolver's contract is that it is never re-thrown, so the caller can
+	// ack the record and emit its resync. A row another path deleted while the
+	// probe was in flight has nothing left to restore, and the same NotFound
+	// wraps an ElectroDB composites miss on the listing row.
+	it("BROKEN: a row deleted underneath the probe settles instead of throwing", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const notFound = Object.assign(new Error("Message not found: msg-1"), {
+			name: "NotFoundError",
+		});
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: {
+				...repos.messageService,
+				updateUid: async () => {
+					throw notFound;
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+	});
+
+	it("BROKEN: a listing row whose composites moved on does not fail the settle", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: repos.messageService,
+			threadMessageService: {
+				...repos.threadMessageService,
+				update: async () => {
+					throw Object.assign(new Error("Thread message not found"), {
+						name: "NotFoundError",
+					});
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["threadMessageService"],
+			log,
+		};
+
+		const result = await resolveExhaustedMessageMoveFailure(deps, {
+			...input,
+			getConnection: async () => buildConnection(new Set([101])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.equal(
+			repos.messages.get("msg-1")?.mailboxId,
+			"mbx-inbox",
+			"the Message row still lands on the pair the server confirmed",
+		);
+	});
+
+	it("a repository fault that is not a missing row still propagates", async () => {
+		const repos = buildRepositories(pendingMoveRow());
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedMessageMoveDeps = {
+			messageService: {
+				...repos.messageService,
+				updateUid: async () => {
+					throw new Error("ProvisionedThroughputExceeded");
+				},
+			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],
+			threadMessageService: repos.threadMessageService,
+			log,
+		};
+
+		await assert.rejects(
+			() =>
+				resolveExhaustedMessageMoveFailure(deps, {
+					...input,
+					getConnection: async () => buildConnection(new Set([101])),
+				}),
+			/ProvisionedThroughputExceeded/,
+		);
 	});
 
 	it("an unreachable server reaches no verdict at all — the probe propagates and the row is untouched", async () => {

package/src/handlers/message-move-terminal.ts

@@ -1,9 +1,14 @@
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
 import {
 	type IImapConnection,
 	isMessageGoneFromOpenMailbox,
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
 } from "@remit/mailbox-service";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export interface MessageMoveTerminalLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -12,6 +17,11 @@ export interface MessageMoveTerminalLogger {
 
 export interface ResolveExhaustedMessageMoveDeps
 	extends StaleMessageReconcileDeps {
+	messageService: Pick<IMessageRepository, "delete" | "updateUid">;
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "deleteMany" | "update"
+	>;
 	log: MessageMoveTerminalLogger;
 }
 
@@ -19,6 +29,7 @@ export interface ResolveExhaustedMessageMoveInput {
 	accountId: string;
 	accountConfigId: string;
 	messageId: string;
+	sourceMailboxId: string;
 	uid: number;
 	sourceMailboxPath: string;
 	getConnection: () => Promise<IImapConnection>;
@@ -51,12 +62,21 @@ export interface ResolveExhaustedMessageMoveResult {
  *    server's own UID. Metric only, no alarm — routine.
  * 2. BROKEN — the message is still at the source, so the move never took
  *    effect, but it keeps failing: broken code or a broken account, not a
- *    transient blip. Local state is left exactly as it stands. Reverting the
- *    optimistic move here is what PR #652 was pulled for: the local row is the
- *    only record that this move is still owed, and a revert races a MOVE that
- *    may yet have landed. Logged with an `alert`-shaped entry for an operator
- *    alarm; never re-thrown (terminal — the caller acks either way, since
- *    retrying a permanently-broken move can never succeed).
+ *    transient blip. The row is put back where the server has just said the
+ *    message is, as `resolveExhaustedMessageDeleteFailure` does (#1098). Logged
+ *    with an `alert`-shaped entry for an operator alarm; never re-thrown
+ *    (terminal — the caller acks either way, since retrying a
+ *    permanently-broken move can never succeed).
+ *
+ *    Leaving the row `moving` is what this replaces. BROKEN is terminal, so
+ *    nothing was ever going to come back and settle it, and only `updateUid`
+ *    clears `moving` — the row kept a `mailboxId` naming the destination and a
+ *    `uid` belonging to the source, which `bindsForeignUid` refuses to act on,
+ *    leaving the message undeletable and unmovable for good (issue #1005).
+ *    Restoring the pair is not the revert-on-ambiguity PR #652 was pulled for:
+ *    the presence probe above has just answered, so this writes a placement the
+ *    server confirmed, and a MOVE that lands after all is re-projected by the
+ *    resync the caller runs.
  *
  * A server that cannot be reached at exhaustion time never reaches either
  * verdict: the probe throws and the record dead-letters with the row untouched.
@@ -66,9 +86,10 @@ export interface ResolveExhaustedMessageMoveResult {
  * message is not actually at the source: a message another client expunged
  * mid-session can answer an empty FETCH while the server still lists its UID
  * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
- * lands in BROKEN, and BROKEN is terminal — the row stays pending and the
- * alert stands until someone clears it. The reverse mistake discards the row
- * for live mail, so the cost is paid deliberately.
+ * lands in BROKEN, and BROKEN is terminal — the row is bound to a source the
+ * message has already left and the alert stands until someone clears it. The
+ * reverse mistake discards the row for live mail, so the cost is paid
+ * deliberately.
  */
 export const resolveExhaustedMessageMoveFailure = async (
 	deps: ResolveExhaustedMessageMoveDeps,
@@ -78,6 +99,7 @@ export const resolveExhaustedMessageMoveFailure = async (
 		accountId,
 		accountConfigId,
 		messageId,
+		sourceMailboxId,
 		uid,
 		sourceMailboxPath,
 		getConnection,
@@ -114,9 +136,18 @@ export const resolveExhaustedMessageMoveFailure = async (
 			accountConfigId,
 			messageId,
 			uid,
+			sourceMailboxId,
 			sourceMailboxPath,
 		},
-		"Message move could not be pushed to IMAP after retry exhaustion; message still exists at its source — local state left pending for operator investigation",
+		"Message move could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder",
 	);
+
+	await restoreSourcePlacement(deps, {
+		accountConfigId,
+		messageId,
+		sourceMailboxId,
+		uid,
+	});
+
 	return { outcome: "broken" };
 };

package/src/handlers/message-move.ts

@@ -257,6 +257,21 @@ export const handleMessageMove = async (
 
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
+			// The terminal resolver opens the source itself, and its answer now
+			// WRITES a placement, so it has to reach IMAP through the same
+			// UIDVALIDITY choke point every other outbound operation does. An
+			// unguarded probe on a folder that was deleted and recreated finds
+			// whatever the server has renumbered onto this uid, reads it as "still
+			// at source", and binds the row to a stranger the next permanent delete
+			// would expunge.
+			const getGuardedConnection = async (): Promise<IImapConnection> =>
+				guardConnectionCursor(
+					await scope.getConnection(),
+					{ mailboxService },
+					accountId,
+					mailbox,
+				);
+
 			await scope
 				.getConnection()
 				.then((rawConnection) => {
@@ -395,36 +410,62 @@ export const handleMessageMove = async (
 					// Redelivery budget exhausted: resolve into exactly one of the two
 					// terminal outcomes instead of dead-lettering with no diagnosis,
 					// and never by inferring the server's state from our own failures.
-					const { outcome } = await resolveExhaustedMessageMoveFailure(
+					const settled = await resolveExhaustedMessageMoveFailure(
 						{ messageService, threadMessageService, log },
 						{
 							accountId,
 							accountConfigId: account.accountConfigId,
 							messageId,
+							sourceMailboxId,
 							uid,
 							sourceMailboxPath,
-							getConnection: scope.getConnection,
+							getConnection: getGuardedConnection,
 						},
-					);
+					).catch((settleError: unknown) => {
+						// The guarded probe found a mailbox whose UIDVALIDITY has moved.
+						// Every stored uid for this folder now names something else, so
+						// there is nothing here that may be settled off them, and the
+						// pause is the routine skip `guardMailboxCursor` documents, not
+						// a fault to re-throw out of this catch.
+						if (settleError instanceof MailboxCursorPausedError) {
+							log.info(
+								{
+									accountId,
+									messageId,
+									mailboxId: sourceMailboxId,
+									cursorState: settleError.state,
+								},
+								"Mailbox cursor not normal; leaving the exhausted move for the cursor rebuild",
+							);
+							return null;
+						}
+						throw settleError;
+					});
 
-					if (outcome === "reconciled") {
-						// Whichever folder the message actually sits in re-projects it
-						// with the server's own UID.
-						await emitMoveResync(emitEvent, {
-							accountId,
-							sourceMailboxId,
-							destinationMailboxId,
-						});
-						return;
+					if (!settled) return;
+
+					if (settled.outcome === "broken") {
+						// Terminal and never re-thrown, so the handler-outcome series
+						// records this record as a success. Counted here or it is
+						// invisible.
+						recordImapFailure("MESSAGE_MOVE_EXHAUSTED", "other");
+						log.error(
+							{ error: errorMessage },
+							"Message move retry exhausted; message still exists at its source",
+						);
 					}
 
-					// Terminal and never re-thrown, so the handler-outcome series
-					// records this record as a success. Counted here or it is invisible.
-					recordImapFailure("MESSAGE_MOVE_EXHAUSTED", "other");
-					log.error(
-						{ error: errorMessage },
-						"Message move retry exhausted; message still exists at its source",
-					);
+					// Both verdicts end in a row the server has contradicted, so this
+					// move reconciles rather than waits (R2). RECONCILED, the local rows
+					// are gone and whichever folder actually holds the message
+					// re-projects it with the server's own UID. BROKEN, the row has just
+					// been put back at the source the server confirmed, and the resync
+					// is what carries any drift either folder has picked up since.
+					await emitMoveResync(emitEvent, {
+						accountId,
+						sourceMailboxId,
+						destinationMailboxId,
+					});
 					// Terminal — never re-thrown, so the caller acks either way.
 				})
 				.finally(() => scope.disconnect());

package/src/handlers/restore-source-placement.ts

@@ -0,0 +1,89 @@
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import { isNotFoundError } from "../is-not-found.js";
+import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+
+export interface RestoreSourcePlacementDeps {
+	messageService: Pick<IMessageRepository, "updateUid">;
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "update"
+	>;
+}
+
+export interface RestoreSourcePlacementInput {
+	accountConfigId: string;
+	messageId: string;
+	sourceMailboxId: string;
+	uid: number;
+}
+
+/**
+ * Put a row back on the source pair a presence probe has just confirmed, and
+ * hand its listing rows back with it.
+ *
+ * Only `updateUid` clears `status: moving`, so a give-up that writes
+ * `syncStatus: failed` and returns leaves the row naming the destination with
+ * the source's uid — the pair `bindsForeignUid` calls a lie and
+ * `MessagePlacementUnsettledError` refuses to act on. Nothing routine repairs
+ * it (sync does not touch `status`, and the cursor rebuild's `updateUid` runs
+ * only on a UIDVALIDITY change), so the message is undeletable and unmovable
+ * for good (issue #1005).
+ *
+ * The caller must have evidence, not an inference: this writes a placement, and
+ * a placement written on a guess binds live mail to a uid that names somebody
+ * else's message. Every caller reaches here from
+ * {@link isMessageGoneFromOpenMailbox} answering that the message is STILL at
+ * `sourceMailboxId`/`uid`, which makes this the server's own answer rather than
+ * a revert on ambiguity (what PR #652 was pulled for).
+ *
+ * A row another path deleted while the probe was in flight has nothing left to
+ * restore, and a thread row whose composites have moved on is being rewritten
+ * by that other path anyway. Both surface as `NotFoundError` — ElectroDB wraps
+ * the conditional-check miss as one — and both are settled states here, not
+ * faults. Throwing on them would escape the caller's `.catch()` and cost the
+ * record its ack and its resync, which is the contract the terminal resolvers
+ * state: never re-thrown.
+ */
+export const restoreSourcePlacement = async (
+	deps: RestoreSourcePlacementDeps,
+	input: RestoreSourcePlacementInput,
+): Promise<void> => {
+	const { accountConfigId, messageId, sourceMailboxId, uid } = input;
+
+	const skipNotFound = (error: unknown): void => {
+		if (isNotFoundError(error)) return;
+		throw error;
+	};
+
+	const messageRestored = await deps.messageService
+		.updateUid(messageId, uid, sourceMailboxId)
+		.then(() => true)
+		.catch((error: unknown) => {
+			skipNotFound(error);
+			return false;
+		});
+	if (!messageRestored) return;
+
+	const threadMessages = await deps.threadMessageService.findAllByMessageId(
+		accountConfigId,
+		messageId,
+	);
+	for (const threadMessage of threadMessages) {
+		const args = buildThreadMessageMoveRevert(
+			threadMessage,
+			uid,
+			sourceMailboxId,
+		);
+		await deps.threadMessageService
+			.update(
+				threadMessage.accountConfigId,
+				threadMessage.threadMessageId,
+				args.set,
+				{ composites: args.composites },
+			)
+			.catch(skipNotFound);
+	}
+};