@remit/mailbox-service 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/body-sync-terminal.test.ts

@@ -102,14 +102,26 @@ const buildStorageService = (
 	};
 };
 
-/** A connection whose `fetchMessages` returns a hit for every uid in `present`. */
-const buildConnection = (present: Set<number>): IImapConnection =>
+/**
+ * A connection whose `fetchMessages` returns a hit for every uid in `present`,
+ * except those in `fetchDrops` — messages the server still has and SEARCH
+ * still lists, whose FETCH row imapflow drops (#408).
+ */
+const buildConnection = (
+	present: Set<number>,
+	fetchDrops: Set<number> = new Set(),
+): IImapConnection =>
 	({
 		openBox: async () => ({}) as never,
 		fetchMessages: async (uids: number[]) =>
 			uids
-				.filter((uid) => present.has(uid))
+				.filter((uid) => present.has(uid) && !fetchDrops.has(uid))
 				.map((uid) => ({ uid }) as unknown as never),
+		search: async (criteria: unknown[]) => {
+			const [, value] = (criteria as Array<[string, string]>)[0];
+			const uid = Number(value);
+			return present.has(uid) ? [uid] : [];
+		},
 	}) as unknown as IImapConnection;
 
 describe("resolveExhaustedBodySyncFailures — the two terminal outcomes", () => {
@@ -189,6 +201,39 @@ describe("resolveExhaustedBodySyncFailures — the two terminal outcomes", () =>
 		);
 	});
 
+	it("a dropped FETCH row mid-batch is not absence: the live message keeps its rows", async () => {
+		const deletedMessages: string[] = [];
+		const deletedThreadMessages: Array<{
+			accountConfigId: string;
+			threadMessageId: string;
+		}> = [];
+		const { storageService } = buildStorageService();
+		const { log } = buildLogger();
+
+		const deps: ResolveExhaustedBodySyncDeps = {
+			messageService: buildMessageService({ m1: 1, m2: 2 }, deletedMessages),
+			threadMessageService: buildThreadMessageService(deletedThreadMessages),
+			storageService,
+			log,
+		};
+
+		// Both messages are live. The FETCH for m1 returns its row; the
+		// immediately following FETCH for m2 drops its row (#408).
+		const result = await resolveExhaustedBodySyncFailures(deps, {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			mailboxId: "mbx-1",
+			mailboxPath: "INBOX",
+			failedMessageIds: ["m1", "m2"],
+			getConnection: async () => buildConnection(new Set([1, 2]), new Set([2])),
+		});
+
+		assert.deepEqual(result.reconciledMessageIds, []);
+		assert.deepEqual(result.brokenMessageIds, ["m1", "m2"]);
+		assert.deepEqual(deletedMessages, []);
+		assert.deepEqual(deletedThreadMessages, []);
+	});
+
 	it("resolves a mixed batch into both outcomes independently", async () => {
 		const deletedMessages: string[] = [];
 		const { storageService } = buildStorageService();

package/src/body-sync-terminal.ts

@@ -1,6 +1,7 @@
 import type { IMessageRepository } from "@remit/data-ports";
 import type { StorageService } from "@remit/storage-service";
 import type { BodySyncLogger } from "./body-sync.js";
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 import {
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
@@ -84,7 +85,11 @@ const markMessageBodySyncFailed = async (
  * outcome — every failed id lands in one of the two result lists.
  *
  * 1. EXPECTED — the message no longer exists on IMAP (expunged, or a
- *    UIDVALIDITY change moved it, #1272). The stale row is deleted via
+ *    UIDVALIDITY change moved it, #1272), confirmed by
+ *    {@link isMessageGoneFromOpenMailbox}. This loop is the most exposed of
+ *    the four sites that used to read an empty FETCH as absence: it issues
+ *    back-to-back single-UID FETCHes on one connection, which is the
+ *    condition imapflow #408 drops rows under. The stale row is deleted via
  *    {@link reconcileStaleMessage} so the existing missing-row 404 path
  *    takes over. Callers should emit a metric only — this is routine, not an
  *    incident.
@@ -123,9 +128,8 @@ export const resolveExhaustedBodySyncFailures = async (
 
 	for (const messageId of failedMessageIds) {
 		const message = await deps.messageService.get(messageId);
-		const found = await connection.fetchMessages([message.uid]);
 
-		if (found.length === 0) {
+		if (await isMessageGoneFromOpenMailbox(connection, message.uid)) {
 			const { threadMessagesDeleted } = await reconcileStaleMessage(
 				deps,
 				accountConfigId,

package/src/flag-push-terminal.test.ts

@@ -33,13 +33,21 @@ const buildLogger = (): {
 	};
 };
 
-const buildConnection = (present: Set<number>): IImapConnection =>
+const buildConnection = (
+	present: Set<number>,
+	fetchDrops: Set<number> = new Set(),
+): IImapConnection =>
 	({
 		openBox: async () => ({}) as never,
 		fetchMessages: async (uids: number[]) =>
 			uids
-				.filter((uid) => present.has(uid))
+				.filter((uid) => present.has(uid) && !fetchDrops.has(uid))
 				.map((uid) => ({ uid }) as unknown as never),
+		search: async (criteria: unknown[]) => {
+			const [, value] = (criteria as Array<[string, string]>)[0];
+			const uid = Number(value);
+			return present.has(uid) ? [uid] : [];
+		},
 	}) as unknown as IImapConnection;
 
 describe("resolveExhaustedFlagPushFailure — the two terminal outcomes (mirrors #1289/#1270 for flag pushes)", () => {
@@ -104,6 +112,51 @@ describe("resolveExhaustedFlagPushFailure — the two terminal outcomes (mirrors
 		assert.ok(metricLog, "expected a routine reconciliation metric log");
 	});
 
+	it("a dropped FETCH row is not absence: the message is still in the mailbox — marker and local rows survive", async () => {
+		const markerDeletes: Array<{ messageId: string; flagName: string }> = [];
+		const { log, errors } = buildLogger();
+
+		const deps: ResolveExhaustedFlagPushDeps = {
+			markerService: {
+				delete: async (messageId: string, flagName: string) => {
+					markerDeletes.push({ messageId, flagName });
+				},
+			},
+			messageService: {
+				delete: async () => {
+					throw new Error("must not be called — the message still exists");
+				},
+			} as unknown as Pick<IMessageRepository, "delete">,
+			threadMessageService: {
+				findAllByMessageId: async () => {
+					throw new Error("must not be called — the message still exists");
+				},
+				deleteMany: async () => {
+					throw new Error("must not be called — the message still exists");
+				},
+			} as unknown as Pick<
+				IThreadMessageRepository,
+				"findAllByMessageId" | "deleteMany"
+			>,
+			log,
+		};
+
+		const result = await resolveExhaustedFlagPushFailure(deps, {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			messageId: "msg-live",
+			flagName: "\\Seen",
+			uid: 303,
+			mailboxPath: "INBOX",
+			getConnection: async () =>
+				buildConnection(new Set([303]), new Set([303])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.deepEqual(markerDeletes, []);
+		assert.ok(errors.some((e) => e.obj.alert === "flag_push_failed"));
+	});
+
 	it("BROKEN (should never happen): the message still exists — marker left in place, alert logged", async () => {
 		const markerDeletes: Array<{ messageId: string; flagName: string }> = [];
 		const { log, errors } = buildLogger();

package/src/flag-push-terminal.ts

@@ -1,4 +1,5 @@
 import type { FlagPushLogger } from "./flag-push.js";
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 import {
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,
@@ -35,10 +36,11 @@ export interface ResolveExhaustedFlagPushResult {
  * (epic #1281 invariant 3) — no third, softer outcome.
  *
  * 1. RECONCILED (expected) — the message no longer exists at its mailbox on
- *    IMAP. Per invariant 2, an external delete supersedes the marker
- *    entirely: the marker is dropped and the stale Message/ThreadMessage rows
- *    are deleted via {@link reconcileStaleMessage}. Metric only, no alarm —
- *    routine.
+ *    IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather than by a
+ *    FETCH coming back empty. Per invariant 2, an external delete supersedes
+ *    the marker entirely: the marker is dropped and the stale
+ *    Message/ThreadMessage rows are deleted via {@link reconcileStaleMessage}.
+ *    Metric only, no alarm — routine.
  * 2. BROKEN — the message still exists, but the flag push keeps failing.
  *    Broken code or a broken account, not a transient blip. The marker is
  *    left in place (not cleared) — while pending, resync never reverts the
@@ -48,6 +50,15 @@ export interface ResolveExhaustedFlagPushResult {
  *    entry for an operator alarm; never re-thrown (terminal — the caller acks
  *    either way, since retrying a stale or permanently-broken push can never
  *    succeed).
+ *
+ * An operator reading `flag_push_failed` should know one case where the
+ * message is not actually there: 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 marker stays pending and the
+ * alert stands until someone clears it. The reverse mistake deletes live
+ * mail, so the cost is paid deliberately: a stale alert is recoverable, a
+ * deleted message is not.
  */
 export const resolveExhaustedFlagPushFailure = async (
 	deps: ResolveExhaustedFlagPushDeps,
@@ -65,9 +76,8 @@ export const resolveExhaustedFlagPushFailure = async (
 
 	const connection = await getConnection();
 	await connection.openBox(mailboxPath, true);
-	const found = await connection.fetchMessages([uid]);
 
-	if (found.length === 0) {
+	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
 		await deps.markerService.delete(messageId, flagName);
 		const { threadMessagesDeleted } = await reconcileStaleMessage(
 			deps,

package/src/imapflow-connection.test.ts

@@ -112,6 +112,52 @@ const fakeMailbox = (path: string, exists: number) => ({
 	readOnly: true,
 });
 
+describe("ImapFlowConnection.search — the probe every stale-row reconcile rests on (#102)", () => {
+	const buildSearchConnection = (
+		result: unknown,
+		calls: Array<{ query: unknown; options: unknown }> = [],
+	): ImapFlowConnection => {
+		const connection = buildConnectionWithClient({
+			mailboxOpen: async (path: string) => fakeMailbox(path, 1),
+			search: async (query: unknown, options: unknown) => {
+				calls.push({ query, options });
+				return result;
+			},
+		});
+		return connection;
+	};
+
+	it("translates a UID criterion into a UID SEARCH answering UIDs, not sequence numbers", async () => {
+		const calls: Array<{ query: unknown; options: unknown }> = [];
+		const connection = buildSearchConnection([42], calls);
+		await connection.openBox("INBOX", true);
+
+		const result = await connection.search([["UID", "42"]]);
+
+		assert.deepStrictEqual(result, [42]);
+		assert.deepStrictEqual(calls, [
+			{ query: { uid: "42" }, options: { uid: true } },
+		]);
+	});
+
+	it("answers an empty array when the server matched nothing", async () => {
+		const connection = buildSearchConnection([]);
+		await connection.openBox("INBOX", true);
+
+		assert.deepStrictEqual(await connection.search([["UID", "42"]]), []);
+	});
+
+	it("throws on a failed SEARCH instead of reporting it as no matches", async () => {
+		const connection = buildSearchConnection(false);
+		await connection.openBox("INBOX", true);
+
+		await assert.rejects(
+			() => connection.search([["UID", "42"]]),
+			/SEARCH failed/,
+		);
+	});
+});
+
 describe("ImapFlowConnection.getMailboxStatus — deletedCount (#1042)", () => {
 	it("returns the SEARCH \\Deleted count alongside the STATUS counts", async () => {
 		const searchQueries: Array<Record<string, unknown>> = [];
@@ -152,7 +198,7 @@ describe("ImapFlowConnection.getMailboxStatus — deletedCount (#1042)", () => {
 				highestModseq: 0n,
 			}),
 			mailboxOpen: async (path: string) => fakeMailbox(path, 4),
-			search: async () => false,
+			search: async () => [],
 		});
 
 		const status = await connection.getMailboxStatus("INBOX");
@@ -173,7 +219,7 @@ describe("ImapFlowConnection.getMailboxStatus — deletedCount (#1042)", () => {
 				highestModseq: modseq,
 			}),
 			mailboxOpen: async (path: string) => fakeMailbox(path, 1),
-			search: async () => false,
+			search: async () => [],
 		});
 
 		const status = await connection.getMailboxStatus("INBOX");

package/src/imapflow-connection.ts

@@ -397,7 +397,15 @@ export class ImapFlowConnection {
 	};
 
 	/**
-	 * Search for messages
+	 * Search for messages, answering UIDs.
+	 *
+	 * imapflow answers a successful SEARCH with an array — empty when the
+	 * server matched nothing — and `false` when the command failed or no
+	 * mailbox was selected. Collapsing the two into `[]` makes a failed SEARCH
+	 * indistinguishable from an empty mailbox, and every caller here acts on
+	 * emptiness by deleting something: the cursor rebuild reads it as "every
+	 * local row is stale", and {@link isMessageGoneFromOpenMailbox} reads it as
+	 * "this message is gone". A failure therefore throws.
 	 */
 	search = async (criteria: unknown[]): Promise<number[]> => {
 		this.ensureConnected();
@@ -410,9 +418,8 @@ export class ImapFlowConnection {
 		const searchQuery = this.convertSearchCriteria(criteria);
 
 		const result = await this.client?.search(searchQuery, { uid: true });
-		// search can return false if no messages match, or undefined if client is null
-		if (!result) {
-			return [];
+		if (!Array.isArray(result)) {
+			throw new Error(`IMAP SEARCH failed in mailbox ${this.currentMailbox}`);
 		}
 		return result;
 	};

package/src/index.ts

@@ -167,6 +167,7 @@ export {
 	type ParsedMessageContent,
 	parseMessageContent,
 } from "./message-parser.js";
+export { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 export {
 	type ImapConnectionFactory,
 	MessageSyncService,

package/src/message-move-copy.test.ts

@@ -0,0 +1,482 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	IUnitOfWork,
+} from "@remit/data-ports";
+import { CreateFailedConflictError } from "@remit/data-ports/errors";
+import { deriveCopyMessageId, deriveMessageId } from "@remit/data-ports/id";
+import { MailboxCursorState } from "@remit/domain-enums";
+import type { ManagedConnectionFactory } from "./connection-factory.js";
+import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
+import { MessageSyncService } from "./message-sync.js";
+import type { IImapConnection, ImapMessage } from "./types.js";
+
+// A copy is a per-folder placement of the same mail. These tests pin the three
+// properties issue #75 turns on: the copy row is deterministic (idempotent), a
+// delete removes exactly the placement it targets, and neither the copy nor the
+// original leaves an unreachable row behind.
+
+const ACCOUNT = "acc-1";
+const ACCOUNT_CONFIG = "cfg-1";
+const SOURCE_MAILBOX = "mbx-inbox";
+const DEST_MAILBOX = "mbx-archive";
+const HEADER = "<abc@example.com>";
+const SOURCE_ID = deriveMessageId(ACCOUNT, HEADER);
+const THREAD_ID = "thread-1";
+
+interface ThreadRow {
+	accountConfigId: string;
+	threadMessageId: string;
+	threadId: string;
+	messageId: string;
+	mailboxId: string;
+	messageIdHeader: string;
+	isRead?: boolean;
+	hasStars?: boolean;
+}
+
+const buildWorld = () => {
+	const messages = new Map<string, Record<string, unknown>>([
+		[
+			SOURCE_ID,
+			{
+				messageId: SOURCE_ID,
+				mailboxId: SOURCE_MAILBOX,
+				uid: 42,
+				rfc822Size: 100,
+				internalDate: 1_700_000_000_000,
+				messageIdHeader: HEADER,
+				envelopeId: "env-1",
+				rootBodyPartId: "body-1",
+				bodyStorageKey: "s3://body-1",
+				category: "primary",
+				hasListUnsubscribe: false,
+			},
+		],
+	]);
+
+	const threadRows: ThreadRow[] = [
+		{
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: `tm:${THREAD_ID}::${SOURCE_ID}`,
+			threadId: THREAD_ID,
+			messageId: SOURCE_ID,
+			mailboxId: SOURCE_MAILBOX,
+			messageIdHeader: HEADER,
+			isRead: false,
+			hasStars: false,
+		},
+	];
+
+	const mailboxes = new Map<string, Record<string, unknown>>([
+		[
+			SOURCE_MAILBOX,
+			{ mailboxId: SOURCE_MAILBOX, fullPath: "INBOX", accountId: ACCOUNT },
+		],
+		[
+			DEST_MAILBOX,
+			{ mailboxId: DEST_MAILBOX, fullPath: "Archive", accountId: ACCOUNT },
+		],
+	]);
+
+	const messageService = {
+		get: async (id: string | string[]) => {
+			if (Array.isArray(id)) {
+				return id.map((i) => messages.get(i)).filter(Boolean);
+			}
+			const m = messages.get(id);
+			if (!m) throw new Error(`no message ${id}`);
+			return m;
+		},
+		// Faithful to the production repo: a duplicate messageId throws a
+		// conflict. create is NOT idempotent — only upsert is — so a copy path
+		// that relied on create swallowing the duplicate would strand the second
+		// attempt here (issue #75). The copy path uses upsert for exactly this
+		// reason.
+		create: async (input: Record<string, unknown>) => {
+			const id = input.messageId as string;
+			if (messages.has(id)) {
+				throw new CreateFailedConflictError("Message", input);
+			}
+			messages.set(id, { ...input });
+			return messages.get(id);
+		},
+		upsert: async (input: Record<string, unknown>) => {
+			const id = input.messageId as string;
+			if (!messages.has(id)) messages.set(id, { ...input });
+			return messages.get(id);
+		},
+		update: async (id: string, patch: Record<string, unknown>) => {
+			const m = messages.get(id);
+			if (m) Object.assign(m, patch);
+			return m;
+		},
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		create: async (input: Record<string, unknown>) => {
+			const threadId = input.threadId as string;
+			const messageId = input.messageId as string;
+			const existing = threadRows.find(
+				(r) => r.threadId === threadId && r.messageId === messageId,
+			);
+			if (existing) return existing;
+			const row: ThreadRow = {
+				accountConfigId: input.accountConfigId as string,
+				threadMessageId: `tm:${threadId}::${messageId}`,
+				threadId,
+				messageId,
+				mailboxId: input.mailboxId as string,
+				messageIdHeader: input.messageIdHeader as string,
+			};
+			threadRows.push(row);
+			return row;
+		},
+		getByMessageId: async (_cfg: string, messageId: string) => {
+			const row = threadRows.find((r) => r.messageId === messageId);
+			if (!row) throw new Error(`no thread message ${messageId}`);
+			return row;
+		},
+		findByMessageId: async (_cfg: string, messageId: string) =>
+			threadRows.find((r) => r.messageId === messageId) ?? null,
+		findAllByMessageId: async (_cfg: string, messageId: string) =>
+			threadRows.filter((r) => r.messageId === messageId),
+		delete: async (_cfg: string, threadMessageId: string) => {
+			const idx = threadRows.findIndex(
+				(r) => r.threadMessageId === threadMessageId,
+			);
+			if (idx >= 0) threadRows.splice(idx, 1);
+		},
+	} as unknown as IThreadMessageRepository;
+
+	const mailboxService = {
+		get: async (_acc: string, id: string | string[]) => {
+			if (Array.isArray(id)) {
+				return id.map((i) => mailboxes.get(i)).filter(Boolean);
+			}
+			return mailboxes.get(id);
+		},
+	} as unknown as IMailboxRepository;
+
+	// No Trash configured, so deleteMessages takes the permanent-delete path —
+	// the branch that eagerly removes ThreadMessage rows (issue #212), which is
+	// where a copy's placement row must be reachable.
+	const mailboxSpecialUseService = {
+		findTrashMailbox: async () => null,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const config: MessageMoveConfig = {
+		messageService,
+		mailboxService,
+		mailboxSpecialUseService,
+		threadMessageService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/message-mgmt",
+	};
+
+	const service = new MessageMoveService(config);
+	// The service builds a real SQS producer in its constructor; a unit test has
+	// no queue, so swap in a recorder.
+	const sent: unknown[] = [];
+	(
+		service as unknown as { sqs: { send: (c: unknown) => Promise<unknown> } }
+	).sqs = {
+		send: async (command: unknown) => {
+			sent.push(command);
+			return {};
+		},
+	};
+
+	return {
+		service,
+		threadRows,
+		messages,
+		sent,
+		messageService,
+		threadMessageService,
+	};
+};
+
+// A message copied into the destination folder, as IMAP later enumerates it:
+// same valid Message-ID header as the source, a real server UID. Sync derives
+// its identity from that header (folder-independent), so the id it computes is
+// the ORIGINAL's — not the copy's folder-scoped id.
+const destinationServerMessage = (uid: number): ImapMessage =>
+	({
+		uid,
+		seq: uid,
+		flags: [],
+		internalDate: new Date("2023-11-14T22:13:20Z"),
+		size: 100,
+		modseq: "510",
+		envelope: {
+			date: "Tue, 14 Nov 2023 22:13:20 +0000",
+			subject: "Hello",
+			from: [{ mailbox: "sender", host: "example.com" }],
+			sender: [],
+			replyTo: [],
+			to: [{ mailbox: "me", host: "example.com" }],
+			cc: [],
+			bcc: [],
+			inReplyTo: "",
+			messageId: HEADER,
+		},
+	}) as ImapMessage;
+
+// A MessageSyncService that reads and writes the SAME rows the copy produced,
+// so "copy then sync" is exercised against one shared world. A stored envelope
+// with a valid Message-ID takes the CHANGEDSINCE path; anything the round tries
+// to create lands in the shared maps, so a duplicate would be visible to the
+// caller's row-count assertions.
+const buildSyncOverDestination = (
+	world: ReturnType<typeof buildWorld>,
+	changed: ImapMessage[],
+) => {
+	const destMailbox = {
+		mailboxId: DEST_MAILBOX,
+		accountId: ACCOUNT,
+		fullPath: "Archive",
+		uidValidity: 100,
+		lastSyncUid: 1,
+		highWaterMarkUid: 20,
+		highestModseq: "500",
+		cursorState: MailboxCursorState.normal,
+	};
+
+	const connection = {
+		openBox: async () => ({ uidvalidity: 100, uidnext: 99 }),
+		getMailboxStatus: async () => ({
+			messages: 10,
+			recent: 0,
+			unseen: 1,
+			uidNext: 99,
+			uidValidity: 100,
+			highestModseq: "600",
+			deletedCount: 0,
+		}),
+		supportsCondstore: () => true,
+		fetchMessagesChangedSince: async () => changed,
+		search: async () => [],
+		fetchMessages: async () => [],
+		fetchEnvelopeSnapshots: async () => [],
+	} as unknown as IImapConnection;
+
+	const connectionFactory = {
+		getConnection: () => connection,
+		close: async () => {},
+	} as ManagedConnectionFactory;
+
+	const mailboxService = {
+		get: async () => destMailbox,
+		update: async () => destMailbox,
+	} as unknown as IMailboxRepository;
+
+	// A create that reaches DynamoDB would append to the shared maps, so the
+	// caller's "nothing accumulated" assertions catch a regression that mints a
+	// third row.
+	const unitOfWork: IUnitOfWork = {
+		transaction: (fn) =>
+			fn({
+				message: world.messageService,
+				envelope: {
+					upsertEnvelope: async () => undefined,
+					upsertBodyParts: async () => undefined,
+				} as unknown as IEnvelopeRepository,
+				address: {
+					upsertAddress: async () => undefined,
+					upsertEnvelopeAddress: async () => undefined,
+				} as unknown as IAddressRepository,
+				threadMessage: world.threadMessageService,
+			}),
+	};
+
+	return new MessageSyncService(
+		connectionFactory,
+		mailboxService,
+		world.messageService,
+		{} as IEnvelopeRepository,
+		{} as IAddressRepository,
+		world.threadMessageService,
+		undefined,
+		unitOfWork,
+	);
+};
+
+describe("MessageMoveService.copyMessage — deterministic per-folder identity (#75)", () => {
+	it("derives the copy id from source + destination, not at random", async () => {
+		const { service, threadRows } = buildWorld();
+
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+
+		const expected = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+		const copyRow = threadRows.find((r) => r.mailboxId === DEST_MAILBOX);
+		assert.ok(copyRow, "a placement row exists in the destination folder");
+		assert.equal(copyRow.messageId, expected);
+	});
+
+	it("a replayed copy converges on one row, no duplicate", async () => {
+		const { service, threadRows, messages } = buildWorld();
+
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+		// A replay (retried COPY event, or the user copying the same mail again)
+		// re-derives the same id. The copy path upserts, so the second write is a
+		// no-op on the existing row rather than the CreateFailedConflictError a
+		// plain create would throw — the operation is idempotent.
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+
+		const copyId = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+		assert.equal(
+			threadRows.filter((r) => r.messageId === copyId).length,
+			1,
+			"exactly one copy row after a replay",
+		);
+		assert.equal(
+			threadRows.length,
+			2,
+			"the original and one copy — nothing accumulates",
+		);
+		assert.equal(messages.has(copyId), true);
+	});
+
+	it("copy then a destination-folder sync creates no third row", async () => {
+		const world = buildWorld();
+
+		await world.service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+
+		const copyId = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+		assert.equal(world.threadRows.length, 2, "original plus one copy");
+		assert.equal(world.messages.size, 2, "original plus one copy");
+
+		// IMAP now enumerates the copied message in the destination folder. Sync
+		// derives its id from the valid Message-ID header — the folder-independent
+		// original id, not the copy's — finds the existing original row, and takes
+		// the flag-only branch. The crux of #75: no third or duplicate row.
+		const sync = buildSyncOverDestination(world, [
+			destinationServerMessage(77),
+		]);
+		const result = await sync.syncMessages(
+			DEST_MAILBOX,
+			ACCOUNT,
+			ACCOUNT_CONFIG,
+		);
+
+		assert.equal(result.syncedCount, 0, "sync created no new message");
+		assert.equal(
+			world.threadRows.length,
+			2,
+			"still original plus the copy — sync added nothing",
+		);
+		assert.equal(
+			world.messages.size,
+			2,
+			"still original plus the copy — sync added nothing",
+		);
+		assert.equal(
+			world.threadRows.filter((r) => r.messageId === copyId).length,
+			1,
+			"the copy row is untouched",
+		);
+	});
+
+	it("copy then delete of the copy removes the copy row and leaves the original", async () => {
+		const { service, threadRows } = buildWorld();
+
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+		const copyId = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [copyId], ACCOUNT, {
+			permanent: true,
+		});
+
+		assert.equal(
+			threadRows.some((r) => r.messageId === copyId),
+			false,
+			"copy row removed",
+		);
+		assert.equal(
+			threadRows.some((r) => r.messageId === SOURCE_ID),
+			true,
+			"original row survives",
+		);
+	});
+
+	it("copy then delete of the original removes the original and leaves the copy — no orphan of the wrong row", async () => {
+		const { service, threadRows } = buildWorld();
+
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+		const copyId = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [SOURCE_ID], ACCOUNT, {
+			permanent: true,
+		});
+
+		assert.equal(
+			threadRows.some((r) => r.messageId === SOURCE_ID),
+			false,
+			"original row removed",
+		);
+		assert.equal(
+			threadRows.some((r) => r.messageId === copyId),
+			true,
+			"copy row survives its own delete boundary",
+		);
+	});
+
+	it("a copy into two folders is two distinct, reachable rows", async () => {
+		const { service, threadRows } = buildWorld();
+
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			DEST_MAILBOX,
+			ACCOUNT,
+		);
+		await service.copyMessages(
+			ACCOUNT_CONFIG,
+			[SOURCE_ID],
+			SOURCE_MAILBOX,
+			ACCOUNT,
+		);
+
+		const idArchive = deriveCopyMessageId(SOURCE_ID, DEST_MAILBOX);
+		const idInbox = deriveCopyMessageId(SOURCE_ID, SOURCE_MAILBOX);
+		assert.notEqual(idArchive, idInbox);
+		assert.equal(threadRows.filter((r) => r.messageId === idArchive).length, 1);
+		assert.equal(threadRows.filter((r) => r.messageId === idInbox).length, 1);
+	});
+});

package/src/message-move.ts

@@ -10,7 +10,7 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
-import { base36uuid } from "@remit/data-ports/id";
+import { deriveCopyMessageId } from "@remit/data-ports/id";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
 
@@ -450,11 +450,20 @@ export class MessageMoveService {
 			destinationMailboxId,
 		);
 
-		// Generate new ID for the copy
-		const newMessageId = base36uuid();
-
-		// Create local copy with moving status (uid=0 until IMAP confirms)
-		await this.messageService.create({
+		// Deterministic identity for the copy: derived from the source message and
+		// the destination mailbox, so a replayed COPY event or a repeated copy
+		// resolves to the same row instead of a fresh unreachable duplicate. A
+		// random id (the prior behaviour) left rows no sync or delete could reach
+		// (issue #75).
+		const newMessageId = deriveCopyMessageId(messageId, destinationMailboxId);
+
+		// Upsert, not create: the id is deterministic, so a repeated copy or a
+		// retry after a partial failure (row written, event never delivered)
+		// re-derives the same id. create throws on the existing row and strands
+		// the copy at uid=0 with an undelivered event; upsert no-ops on the row
+		// and lets the event be re-enqueued below, keeping the operation
+		// idempotent and the copy re-drivable (issue #75).
+		await this.messageService.upsert({
 			messageId: newMessageId,
 			mailboxId: destinationMailboxId,
 			uid: 0, // Will be updated by worker after IMAP COPY

package/src/message-presence.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+import type { IImapConnection } from "./types.js";
+
+type Probe = Pick<IImapConnection, "fetchMessages" | "search">;
+
+const buildProbe = (
+	fetched: number[],
+	searched: number[],
+	searchCalls: unknown[][] = [],
+): Probe => ({
+	fetchMessages: async () => fetched.map((uid) => ({ uid }) as never),
+	search: async (criteria: unknown[]) => {
+		searchCalls.push(criteria);
+		return searched;
+	},
+});
+
+describe("isMessageGoneFromOpenMailbox", () => {
+	it("a FETCH row is proof of presence — no SEARCH needed", async () => {
+		const searchCalls: unknown[][] = [];
+		const gone = await isMessageGoneFromOpenMailbox(
+			buildProbe([7], [], searchCalls),
+			7,
+		);
+
+		assert.equal(gone, false);
+		assert.equal(searchCalls.length, 0);
+	});
+
+	it("an empty FETCH the SEARCH contradicts is a dropped row, not an absence", async () => {
+		const gone = await isMessageGoneFromOpenMailbox(buildProbe([], [7]), 7);
+
+		assert.equal(gone, false);
+	});
+
+	it("only a SEARCH that does not list the uid confirms it is gone", async () => {
+		const gone = await isMessageGoneFromOpenMailbox(buildProbe([], []), 7);
+
+		assert.equal(gone, true);
+	});
+
+	it("asks the server for the uid it is about to reconcile", async () => {
+		const searchCalls: unknown[][] = [];
+		await isMessageGoneFromOpenMailbox(buildProbe([], [], searchCalls), 42);
+
+		assert.deepEqual(searchCalls, [[["UID", "42"]]]);
+	});
+});

package/src/message-presence.ts

@@ -0,0 +1,35 @@
+import type { IImapConnection } from "./types.js";
+
+/**
+ * Whether a UID is confirmed gone from the currently open mailbox.
+ *
+ * A FETCH that yields no row is not proof of absence. imapflow drops rows on
+ * back-to-back FETCHes (#408) — the same client glitch #100 had to stop
+ * reading as authoritative on the sync path — so a transient blip returns an
+ * empty result for a message that is still on the server. Anything that
+ * deletes local rows on that reading destroys live mail.
+ *
+ * Absence is therefore confirmed with a UID SEARCH, which the server answers
+ * with a plain UID set rather than a stream of message rows, and which
+ * `placement-move-push.ts` already uses as its verification probe. Only a
+ * SEARCH that does not list the UID counts as gone; an empty FETCH the SEARCH
+ * contradicts leaves the message present, and the caller treats it as such.
+ *
+ * The absence verdict rests on an empty SEARCH meaning the server matched
+ * nothing, so `IImapConnection.search` must throw when a SEARCH fails rather
+ * than answer `[]` — an implementation that reports failure as an empty array
+ * hands this function a deletion authority it cannot tell apart from a genuine
+ * miss.
+ */
+export const isMessageGoneFromOpenMailbox = async (
+	connection: Pick<IImapConnection, "fetchMessages" | "search">,
+	uid: number,
+): Promise<boolean> => {
+	const found = await connection.fetchMessages([uid]);
+	if (found.length > 0) {
+		return false;
+	}
+
+	const matched = await connection.search([["UID", String(uid)]]);
+	return !matched.includes(uid);
+};

package/src/placement-move-terminal.test.ts

@@ -33,13 +33,21 @@ const buildLogger = (): {
 	};
 };
 
-const buildConnection = (present: Set<number>): IImapConnection =>
+const buildConnection = (
+	present: Set<number>,
+	fetchDrops: Set<number> = new Set(),
+): IImapConnection =>
 	({
 		openBox: async () => ({}) as never,
 		fetchMessages: async (uids: number[]) =>
 			uids
-				.filter((uid) => present.has(uid))
+				.filter((uid) => present.has(uid) && !fetchDrops.has(uid))
 				.map((uid) => ({ uid }) as unknown as never),
+		search: async (criteria: unknown[]) => {
+			const [, value] = (criteria as Array<[string, string]>)[0];
+			const uid = Number(value);
+			return present.has(uid) ? [uid] : [];
+		},
 	}) as unknown as IImapConnection;
 
 describe("resolveExhaustedPlacementMoveFailure — the two terminal outcomes (mirrors #1270 for placement moves)", () => {
@@ -148,6 +156,54 @@ describe("resolveExhaustedPlacementMoveFailure — the two terminal outcomes (mi
 		);
 	});
 
+	it("a dropped FETCH row is not absence: the message is still at the source — marker and local rows survive", async () => {
+		const deletedMessages: string[] = [];
+		const deletedThreadMessages: unknown[] = [];
+		const markerDeletes: string[] = [];
+		const { log, errors } = buildLogger();
+
+		const deps: ResolveExhaustedPlacementMoveDeps = {
+			markerService: {
+				delete: async (id: string) => {
+					markerDeletes.push(id);
+				},
+			},
+			messageService: {
+				delete: async (id: string) => {
+					deletedMessages.push(id);
+				},
+			} as unknown as Pick<IMessageRepository, "delete">,
+			threadMessageService: {
+				findAllByMessageId: async () => [
+					{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-live" },
+				],
+				deleteMany: async (keys: unknown[]) => {
+					deletedThreadMessages.push(...keys);
+				},
+			} as unknown as Pick<
+				IThreadMessageRepository,
+				"findAllByMessageId" | "deleteMany"
+			>,
+			log,
+		};
+
+		const result = await resolveExhaustedPlacementMoveFailure(deps, {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			messageId: "msg-live",
+			uid: 303,
+			sourceMailboxPath: "INBOX",
+			getConnection: async () =>
+				buildConnection(new Set([303]), new Set([303])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		assert.deepEqual(markerDeletes, []);
+		assert.deepEqual(deletedMessages, []);
+		assert.deepEqual(deletedThreadMessages, []);
+		assert.ok(errors.some((e) => e.obj.alert === "placement_move_failed"));
+	});
+
 	it("never throws — both outcomes are terminal, the caller always acks", async () => {
 		const { log } = buildLogger();
 		const deps: ResolveExhaustedPlacementMoveDeps = {

package/src/placement-move-terminal.ts

@@ -1,3 +1,4 @@
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 import type { PlacementMoveLogger } from "./placement-move.js";
 import {
 	reconcileStaleMessage,
@@ -33,9 +34,11 @@ export interface ResolveExhaustedPlacementMoveResult {
  * taxonomy (epic #1281 invariant 3) — no third, softer outcome.
  *
  * 1. RECONCILED (expected) — the message no longer exists at its pending-move
- *    source on IMAP. Per invariant 2, an external delete supersedes the
- *    marker entirely: the marker is dropped and the stale Message/ThreadMessage
- *    rows are deleted via {@link reconcileStaleMessage}. This is also the
+ *    source on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather
+ *    than by a FETCH coming back empty. Per invariant 2, an external delete
+ *    supersedes the marker entirely: the marker is dropped and the stale
+ *    Message/ThreadMessage rows are deleted via
+ *    {@link reconcileStaleMessage}. This is also the
  *    outcome for the (rarer, functionally indistinguishable from here) case
  *    where a foreign client moved the message elsewhere — either way, our
  *    prediction no longer holds, and the marker cannot be honoured. Metric
@@ -49,6 +52,15 @@ export interface ResolveExhaustedPlacementMoveResult {
  *    `alert`-shaped entry for an operator alarm; never re-thrown (terminal —
  *    the caller acks either way, since retrying a stale or permanently-broken
  *    move can never succeed).
+ *
+ * An operator reading `placement_move_failed` should know one case where the
+ * 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 marker stays pending and the
+ * alert stands until someone clears it. The reverse mistake deletes live
+ * mail, so the cost is paid deliberately: a stale alert is recoverable, a
+ * deleted message is not.
  */
 export const resolveExhaustedPlacementMoveFailure = async (
 	deps: ResolveExhaustedPlacementMoveDeps,
@@ -65,9 +77,8 @@ export const resolveExhaustedPlacementMoveFailure = async (
 
 	const connection = await getConnection();
 	await connection.openBox(sourceMailboxPath);
-	const found = await connection.fetchMessages([uid]);
 
-	if (found.length === 0) {
+	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
 		await deps.markerService.delete(messageId);
 		const { threadMessagesDeleted } = await reconcileStaleMessage(
 			deps,