@remit/mailbox-service 0.0.76 → 0.0.77

package/package.json

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

package/src/message-delete-unsettled-placement.test.ts

@@ -0,0 +1,386 @@
+/**
+ * Issue #845 item 3. While a move is in flight the Message row names the
+ * destination folder but still carries the SOURCE folder's uid, so a delete
+ * that binds the pair as it stands sends the worker to expunge the destination
+ * folder's own message at that uid — an unrelated message, destroyed for good.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IAddressRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import { MessagePlacementUnsettledError } from "@remit/data-ports/errors";
+import type { RoleResolution } from "@remit/data-ports/folder-role";
+import { MessageMoveService } from "./message-move.js";
+
+const ACCOUNT = "acc-1";
+const ACCOUNT_CONFIG = "cfg-1";
+const INBOX = "mbx-inbox";
+const ARCHIVE = "mbx-archive";
+const TRASH = "mbx-trash";
+
+const MOVING_ID = "msg-moving";
+const SETTLED_ID = "msg-settled";
+const STRANDED_ID = "msg-stranded";
+const COPY_ID = "msg-copy";
+
+const INBOX_UID = 42;
+const ARCHIVE_UID = 907;
+const SETTLED_UID = 11;
+
+type TrashMailbox = { mailboxId: string; fullPath: string };
+
+const flaggedTrash: RoleResolution<TrashMailbox> = {
+	kind: "flagged",
+	mailbox: { mailboxId: TRASH, fullPath: "INBOX/Trash" },
+};
+
+interface CapturedEvent {
+	type: string;
+	messageId?: string;
+	operation?: string;
+	mailboxId?: string;
+	mailboxPath?: string;
+	uid?: number;
+	sourceMailboxPath?: string;
+}
+
+const mailboxes = [
+	{ mailboxId: INBOX, fullPath: "INBOX", accountId: ACCOUNT },
+	{ mailboxId: ARCHIVE, fullPath: "Archive", accountId: ACCOUNT },
+	{ mailboxId: TRASH, fullPath: "INBOX/Trash", accountId: ACCOUNT },
+];
+
+/** A row mid-move: Archive is already written, the uid is still INBOX's. */
+const movingRow = () => ({
+	messageId: MOVING_ID,
+	mailboxId: ARCHIVE,
+	uid: INBOX_UID,
+	status: "moving",
+	syncStatus: "pending",
+	originalMailboxId: INBOX,
+	originalUid: INBOX_UID,
+});
+
+/** The same row after the trash-move handler gave up without confirming. */
+const strandedRow = () => ({
+	...movingRow(),
+	messageId: STRANDED_ID,
+	syncStatus: "failed",
+});
+
+/** An ordinary settled row. */
+const settledRow = () => ({
+	messageId: SETTLED_ID,
+	mailboxId: INBOX,
+	uid: SETTLED_UID,
+	status: "active",
+	syncStatus: "synced",
+});
+
+/**
+ * A freshly copied row: `moving` until COPYUID lands, with no server-side uid
+ * at all and no move behind it. Its uid is not ready; it does not name anyone.
+ */
+const freshCopyRow = () => ({
+	messageId: COPY_ID,
+	mailboxId: ARCHIVE,
+	uid: 0,
+	status: "moving",
+	syncStatus: "pending",
+});
+
+const buildWorld = (seed: Array<Record<string, unknown>>) => {
+	const patches: Array<{ messageId: string; patch: Record<string, unknown> }> =
+		[];
+	const events: CapturedEvent[] = [];
+	const rows = new Map<string, Record<string, unknown>>(
+		seed.map((row): [string, Record<string, unknown>] => [
+			String(row.messageId),
+			row,
+		]),
+	);
+
+	const settle = (messageId: string) => {
+		Object.assign(rows.get(messageId) ?? {}, {
+			uid: ARCHIVE_UID,
+			status: "active",
+			syncStatus: "synced",
+		});
+	};
+
+	const messageService = {
+		get: async (ids: string | string[]) =>
+			Array.isArray(ids)
+				? ids.flatMap((id) => {
+						const row = rows.get(id);
+						return row ? [row] : [];
+					})
+				: rows.get(ids),
+		update: async (id: string, patch: Record<string, unknown>) => {
+			patches.push({ messageId: id, patch });
+			return Object.assign(rows.get(id) ?? {}, patch);
+		},
+		updateForMove: async (id: string, patch: Record<string, unknown>) => {
+			patches.push({ messageId: id, patch });
+			return Object.assign(rows.get(id) ?? {}, patch);
+		},
+		upsert: async (row: Record<string, unknown>) => row,
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => [],
+		getByMessageId: async (_cfg: string, messageId: string) => ({
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: `tm-${messageId}`,
+			messageId,
+			threadId: "thr-1",
+			mailboxId: rows.get(messageId)?.mailboxId,
+			sentDate: 1,
+			isRead: false,
+			isDeleted: false,
+			hasStars: false,
+			hasAttachment: false,
+		}),
+		create: async () => {},
+		update: async () => {},
+		delete: async () => {},
+	} as unknown as IThreadMessageRepository;
+
+	const mailboxService = {
+		get: async (_accountId: string, ids: string | string[]) =>
+			Array.isArray(ids)
+				? mailboxes.filter((mailbox) => ids.includes(mailbox.mailboxId))
+				: mailboxes.find((mailbox) => mailbox.mailboxId === ids),
+	} as unknown as IMailboxRepository;
+
+	const mailboxSpecialUseService = {
+		resolveTrashRole: async () => flaggedTrash,
+		findTrashMailbox: async () => flaggedTrash.mailbox,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const addressService = {
+		reconcileJunkOnlyForMessage: async () => {},
+	} as unknown as IAddressRepository;
+
+	const service = new MessageMoveService({
+		messageService,
+		mailboxService,
+		mailboxSpecialUseService,
+		threadMessageService,
+		addressService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
+		moveSettleTimeoutMs: 200,
+		moveSettlePollMs: 10,
+	});
+
+	const stubs = service as unknown as {
+		enqueueEventsBatch: (batch: CapturedEvent[]) => Promise<void>;
+		enqueueEvent: (event: CapturedEvent) => Promise<void>;
+	};
+	stubs.enqueueEventsBatch = async (batch) => {
+		events.push(...batch);
+	};
+	stubs.enqueueEvent = async (event) => {
+		events.push(event);
+	};
+
+	return { service, patches, events, rows, settle };
+};
+
+describe("a delete never binds the folder/uid pair of an in-flight move (#845.3)", () => {
+	it("binds the confirmed pair once the move settles", async () => {
+		const { service, events, settle } = buildWorld([movingRow()]);
+
+		setTimeout(() => settle(MOVING_ID), 30);
+		await service.deleteMessages(ACCOUNT_CONFIG, [MOVING_ID], ACCOUNT);
+
+		assert.equal(events.length, 1);
+		assert.equal(events[0].operation, "move_to_trash");
+		assert.equal(
+			events[0].mailboxPath,
+			"Archive",
+			"the folder the confirmed move left the message in",
+		);
+		assert.equal(
+			events[0].uid,
+			ARCHIVE_UID,
+			"and that folder's own uid, never the source folder's",
+		);
+	});
+
+	it("refuses the delete, and touches nothing, when the move never settles", async () => {
+		const { service, patches, events, rows } = buildWorld([movingRow()]);
+
+		await assert.rejects(
+			() => service.deleteMessages(ACCOUNT_CONFIG, [MOVING_ID], ACCOUNT),
+			(error: unknown) =>
+				error instanceof MessagePlacementUnsettledError &&
+				error.statusCode === 409 &&
+				error.publicApiError?.code === "message_placement_unsettled" &&
+				error.publicApiError?.details?.messageId === MOVING_ID &&
+				error.publicApiError?.details?.accountId === ACCOUNT &&
+				error.publicApiError?.details?.reason === "in_flight",
+		);
+
+		assert.deepEqual(events, [], "nothing was enqueued");
+		assert.deepEqual(patches, [], "and no local write was made");
+		assert.equal(rows.get(MOVING_ID)?.uid, INBOX_UID);
+	});
+
+	it("expunges no part of a mixed batch when one row is in flight", async () => {
+		// All-or-nothing: the settled row is deletable on its own, and would be
+		// expunged first by a per-row gate. One unverifiable pair refuses the
+		// batch it arrived in.
+		const { service, patches, events } = buildWorld([
+			settledRow(),
+			movingRow(),
+		]);
+
+		await assert.rejects(
+			() =>
+				service.deleteMessages(
+					ACCOUNT_CONFIG,
+					[SETTLED_ID, MOVING_ID],
+					ACCOUNT,
+					{ permanent: true },
+				),
+			MessagePlacementUnsettledError,
+		);
+
+		assert.deepEqual(
+			events,
+			[],
+			"the settled row was not expunged alongside the refusal",
+		);
+		assert.deepEqual(patches, []);
+	});
+
+	it("deletes the whole batch once the in-flight row settles", async () => {
+		const { service, events, settle } = buildWorld([settledRow(), movingRow()]);
+
+		setTimeout(() => settle(MOVING_ID), 30);
+		await service.deleteMessages(
+			ACCOUNT_CONFIG,
+			[SETTLED_ID, MOVING_ID],
+			ACCOUNT,
+			{ permanent: true },
+		);
+
+		assert.deepEqual(
+			events.map((event) => [event.messageId, event.uid]).sort(),
+			[
+				[MOVING_ID, ARCHIVE_UID],
+				[SETTLED_ID, SETTLED_UID],
+			].sort(),
+		);
+	});
+
+	it("waits one row's ceiling for a batch, not one per row", async () => {
+		// The gate is concurrent. Three in-flight rows that never settle must
+		// refuse at roughly one ceiling — a sequential gate would spend three,
+		// and at the client's 100-id chunk cap that is a gateway timeout.
+		const rows = [movingRow(), movingRow(), movingRow()].map((row, index) => ({
+			...row,
+			messageId: `${MOVING_ID}-${index}`,
+		}));
+		const { service } = buildWorld(rows);
+
+		const startedAt = Date.now();
+		await assert.rejects(
+			() =>
+				service.deleteMessages(
+					ACCOUNT_CONFIG,
+					rows.map((row) => row.messageId),
+					ACCOUNT,
+					{ permanent: true },
+				),
+			MessagePlacementUnsettledError,
+		);
+
+		assert.ok(
+			Date.now() - startedAt < 500,
+			"three rows refused within one 200ms ceiling, not three",
+		);
+	});
+});
+
+describe("the gate refuses only a uid that names somebody else (#845.3)", () => {
+	it("deletes a freshly copied row rather than waiting on it", async () => {
+		// A copy is `moving` with no server-side uid yet. That uid is not ready,
+		// which is not the same as naming another folder's message, and the
+		// delete of a copy is an ordinary flow that must not stall or refuse.
+		const { service, events } = buildWorld([freshCopyRow()]);
+
+		const startedAt = Date.now();
+		await service.deleteMessages(ACCOUNT_CONFIG, [COPY_ID], ACCOUNT, {
+			permanent: true,
+		});
+
+		assert.equal(events.length, 1);
+		assert.equal(events[0].operation, "permanent_delete");
+		assert.ok(Date.now() - startedAt < 100, "and never entered the wait");
+	});
+
+	it("refuses a row stranded by a move that gave up, without spending the ceiling", async () => {
+		// `syncStatus: failed` with `status: moving` is the shape every handler's
+		// give-up path leaves behind, and only `updateUid` clears it. The pair is
+		// still a lie, so the delete is still refused — but under a reason whose
+		// remedy is a resync, and without a wait that could never succeed.
+		const { service, events } = buildWorld([strandedRow()]);
+
+		const startedAt = Date.now();
+		await assert.rejects(
+			() => service.deleteMessages(ACCOUNT_CONFIG, [STRANDED_ID], ACCOUNT),
+			(error: unknown) =>
+				error instanceof MessagePlacementUnsettledError &&
+				error.publicApiError?.details?.reason === "unverified",
+		);
+
+		assert.deepEqual(events, []);
+		assert.ok(Date.now() - startedAt < 100, "refused without waiting");
+	});
+});
+
+describe("a copy binds the same pair and takes the same gate (#845.3)", () => {
+	it("copies from the confirmed pair once the move settles", async () => {
+		const { service, events, settle } = buildWorld([movingRow()]);
+
+		setTimeout(() => settle(MOVING_ID), 30);
+		await service.copyMessage(ACCOUNT_CONFIG, MOVING_ID, INBOX, ACCOUNT);
+
+		assert.equal(events.length, 1);
+		assert.equal(events[0].type, "MESSAGE_COPY");
+		assert.equal(events[0].sourceMailboxPath, "Archive");
+		assert.equal(events[0].uid, ARCHIVE_UID);
+	});
+
+	it("writes no part of a batch copy when one row is in flight", async () => {
+		// The gate runs over the whole batch before the first upsert, so a
+		// refusal cannot leave copies already committed and enqueued.
+		const { service, events } = buildWorld([settledRow(), movingRow()]);
+
+		const startedAt = Date.now();
+		await assert.rejects(
+			() =>
+				service.copyMessages(
+					ACCOUNT_CONFIG,
+					[SETTLED_ID, MOVING_ID],
+					TRASH,
+					ACCOUNT,
+				),
+			MessagePlacementUnsettledError,
+		);
+
+		assert.deepEqual(events, [], "no copy was enqueued");
+		assert.ok(
+			Date.now() - startedAt < 500,
+			"and the batch spent one ceiling, not one per row",
+		);
+	});
+});

package/src/message-move.ts

@@ -10,8 +10,12 @@ import type {
 	IMailboxSpecialUseRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
+	MessageItem,
 } from "@remit/data-ports";
-import { FolderRoleUnresolvedError } from "@remit/data-ports/errors";
+import {
+	FolderRoleUnresolvedError,
+	MessagePlacementUnsettledError,
+} from "@remit/data-ports/errors";
 import {
 	type FolderRoleUnresolvedReason,
 	NO_TRASH_FOLDER_REASON,
@@ -29,6 +33,11 @@ import {
 	MessageSyncStatus,
 } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
+import {
+	type PlacementBinding,
+	placementBindingOf,
+	waitForPlacementToSettle,
+} from "./placement-settled.js";
 
 /**
  * Event types for message move/delete operations.
@@ -120,8 +129,13 @@ export interface MessageMoveConfig {
 	sqsQueueUrl: string;
 	sqsEndpoint?: string;
 	logger?: MessageMoveLogger;
+	moveSettleTimeoutMs?: number;
+	moveSettlePollMs?: number;
 }
 
+const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
+const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
+
 /**
  * The account resolves no Trash folder, so a move-to-Trash delete has nowhere
  * to put the mail and an Empty Trash has nothing it may empty. A designed,
@@ -239,6 +253,8 @@ export class MessageMoveService {
 	private sqs: SQSClient;
 	private queueUrl: string;
 	private log: MessageMoveLogger;
+	private moveSettleTimeoutMs: number;
+	private moveSettlePollMs: number;
 
 	constructor(config: MessageMoveConfig) {
 		this.messageService = config.messageService;
@@ -248,6 +264,10 @@ export class MessageMoveService {
 		this.addressService = config.addressService;
 		this.queueUrl = config.sqsQueueUrl;
 		this.log = config.logger ?? noopLogger;
+		this.moveSettleTimeoutMs =
+			config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
+		this.moveSettlePollMs =
+			config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
 
 		this.sqs = createQueueProducer({
 			queueUrl: config.sqsQueueUrl,
@@ -288,8 +308,13 @@ export class MessageMoveService {
 		if (messageIds.length === 0) return;
 
 		// Batch get all messages
-		const messages = await this.messageService.get(messageIds);
-		if (messages.length === 0) return;
+		const rows = await this.messageService.get(messageIds);
+		if (rows.length === 0) return;
+
+		// Ahead of the Trash gates below, which compare `mailboxId` against the
+		// Trash folder: an in-flight move makes that comparison answer for a
+		// folder the message has not reached.
+		const messages = await this.settledPlacements(rows, accountId);
 
 		// Get unique mailbox IDs and batch fetch mailboxes
 		const uniqueMailboxIds = [...new Set(messages.map((m) => m.mailboxId))];
@@ -633,7 +658,24 @@ export class MessageMoveService {
 		destinationMailboxId: string,
 		accountId: string,
 	): Promise<string> => {
-		const sourceMessage = await this.messageService.get(messageId);
+		return this.copySettledMessage(
+			accountConfigId,
+			await this.settledPlacement(
+				await this.messageService.get(messageId),
+				accountId,
+			),
+			destinationMailboxId,
+			accountId,
+		);
+	};
+
+	private copySettledMessage = async (
+		accountConfigId: string,
+		sourceMessage: MessageItem,
+		destinationMailboxId: string,
+		accountId: string,
+	): Promise<string> => {
+		const messageId = sourceMessage.messageId;
 		const sourceMailbox = await this.mailboxService.get(
 			accountId,
 			sourceMessage.mailboxId,
@@ -750,15 +792,24 @@ export class MessageMoveService {
 		destinationMailboxId: string,
 		accountId: string,
 	): Promise<string[]> => {
+		// Every row is settled before the first copy is written, so the batch's
+		// wait is one row's ceiling rather than the sum across it, and a refusal
+		// lands before any part of the batch has committed.
+		const sources = await this.settledPlacements(
+			await this.messageService.get(messageIds),
+			accountId,
+		);
+
 		const newMessageIds: string[] = [];
-		for (const messageId of messageIds) {
-			const newId = await this.copyMessage(
-				accountConfigId,
-				messageId,
-				destinationMailboxId,
-				accountId,
+		for (const source of sources) {
+			newMessageIds.push(
+				await this.copySettledMessage(
+					accountConfigId,
+					source,
+					destinationMailboxId,
+					accountId,
+				),
 			);
-			newMessageIds.push(newId);
 		}
 		return newMessageIds;
 	};
@@ -867,6 +918,61 @@ export class MessageMoveService {
 		return { deletedCount: messages.length };
 	};
 
+	private refusePlacement = (
+		message: MessageItem,
+		accountId: string,
+		binding: Exclude<PlacementBinding, "consistent">,
+	): never => {
+		this.log.error(
+			{ accountId, messageId: message.messageId, binding },
+			"Refused: this message's folder and uid do not name the same message",
+		);
+		throw new MessagePlacementUnsettledError(
+			`Message ${message.messageId} was not acted on: its folder and uid do not name the same message`,
+			accountId,
+			message.messageId,
+			binding === "abandoned" ? "unverified" : "in_flight",
+		);
+	};
+
+	private settledPlacement = async (
+		message: MessageItem,
+		accountId: string,
+	): Promise<MessageItem> => {
+		const binding = placementBindingOf(message);
+		if (binding === "consistent") return message;
+
+		// An abandoned move is never coming back, so the ceiling would be spent
+		// only to reach the same answer.
+		if (binding === "abandoned")
+			return this.refusePlacement(message, accountId, binding);
+
+		const settled = await waitForPlacementToSettle(
+			this.messageService,
+			message.messageId,
+			{
+				timeoutMs: this.moveSettleTimeoutMs,
+				pollMs: this.moveSettlePollMs,
+			},
+		);
+		const settledBinding = placementBindingOf(settled);
+		if (settledBinding === "consistent") return settled;
+		return this.refusePlacement(settled, accountId, settledBinding);
+	};
+
+	/**
+	 * Settle a whole batch before any of it is acted on, so one unsettled row
+	 * refuses the batch whole rather than leaving part of it expunged, and the
+	 * batch's total wait is one row's ceiling rather than the sum across it.
+	 */
+	private settledPlacements = async (
+		messages: MessageItem[],
+		accountId: string,
+	): Promise<MessageItem[]> =>
+		Promise.all(
+			messages.map((message) => this.settledPlacement(message, accountId)),
+		);
+
 	/**
 	 * Update ThreadMessage for move operations.
 	 * Updates mailboxId and optionally isDeleted.

package/src/placement-settled.ts

@@ -1,5 +1,5 @@
 import type { MessageItem } from "@remit/data-ports";
-import { MessageStatus } from "@remit/domain-enums";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 
 /**
  * Whether the message row's placement is still an unconfirmed local write
@@ -19,6 +19,55 @@ export const isPlacementUnsettled = (
 	message: Pick<MessageItem, "status">,
 ): boolean => message.status === MessageStatus.moving;
 
+/**
+ * Whether the row's `uid` belongs to a folder other than the one `mailboxId`
+ * names — the state that makes the pair a lie rather than merely incomplete.
+ *
+ * `updateForMove` is the only writer of this shape: it points the row at the
+ * destination and records the pre-move pair, leaving `uid` untouched until the
+ * server confirms and `updateUid` replaces it. A row with no `originalUid` was
+ * never moved, so its uid names nothing but itself — a freshly copied row is
+ * `moving` with `uid: 0` until COPYUID lands, which is a uid that is not ready,
+ * not a uid that names somebody else's message.
+ */
+export const bindsForeignUid = (
+	message: Pick<
+		MessageItem,
+		"status" | "mailboxId" | "uid" | "originalMailboxId" | "originalUid"
+	>,
+): boolean =>
+	isPlacementUnsettled(message) &&
+	message.originalUid !== undefined &&
+	message.originalUid === message.uid &&
+	message.originalMailboxId !== undefined &&
+	message.originalMailboxId !== message.mailboxId;
+
+/**
+ * `in_flight` — a mover is still working on the row, so waiting resolves it.
+ * `abandoned` — the mover gave up without confirming (`syncStatus: failed`,
+ * written by every handler's give-up path while `status` stays `moving`, since
+ * only `updateUid` clears it). Nothing routine settles such a row, so waiting
+ * on one is a wait that never ends, and the pair stays a lie either way.
+ */
+export type PlacementBinding = "consistent" | "in_flight" | "abandoned";
+
+export const placementBindingOf = (
+	message: Pick<
+		MessageItem,
+		| "status"
+		| "syncStatus"
+		| "mailboxId"
+		| "uid"
+		| "originalMailboxId"
+		| "originalUid"
+	>,
+): PlacementBinding => {
+	if (!bindsForeignUid(message)) return "consistent";
+	return message.syncStatus === MessageSyncStatus.failed
+		? "abandoned"
+		: "in_flight";
+};
+
 export interface PlacementSettleOptions {
 	timeoutMs: number;
 	pollMs: number;

package/src/spam-report.ts

@@ -3,16 +3,15 @@ import type {
 	IAddressRepository,
 	IMailboxSpecialUseRepository,
 	IMessageRepository,
-	MessageItem,
 } from "@remit/data-ports";
 import { deriveAddressId } from "@remit/data-ports/id";
-import {
-	AddressRole,
-	MessageKeywordFlag,
-	MessageStatus,
-} from "@remit/domain-enums";
+import { AddressRole, MessageKeywordFlag } from "@remit/domain-enums";
 import type { FlagPushService } from "./flag-push.js";
 import type { MessageMoveService } from "./message-move.js";
+import {
+	isPlacementUnsettled,
+	waitForPlacementToSettle,
+} from "./placement-settled.js";
 
 export interface SpamReportLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -185,31 +184,6 @@ export class SpamReportService {
 		});
 	};
 
-	/**
-	 * R2 wait (docs/architecture/imap-mutations.md): `notSpam`'s restore is a
-	 * dependent write against report-spam's own move — enqueuing it while that
-	 * move is still in flight (`status === moving`) would carry the message's
-	 * pre-move `uid` (only a CONFIRMED move updates it, via `updateUid`) and
-	 * risk acting on the wrong server-side message once both moves are
-	 * in-flight at once. Cheap to block per the doc's default guidance: a move
-	 * ordinarily settles in well under a second. On timeout the dependent
-	 * write is not made — the caller is told to retry, and retrying is safe
-	 * (this whole flow is idempotent).
-	 */
-	private waitForMoveToSettle = async (
-		messageId: string,
-	): Promise<MessageItem> => {
-		const deadline = Date.now() + this.moveSettleTimeoutMs;
-		let message = await this.messageService.get(messageId);
-		while (message.status === MessageStatus.moving && Date.now() < deadline) {
-			await new Promise((resolve) =>
-				setTimeout(resolve, this.moveSettlePollMs),
-			);
-			message = await this.messageService.get(messageId);
-		}
-		return message;
-	};
-
 	reportSpam = async (params: SpamReportParams): Promise<void> => {
 		const { accountConfigId, accountId, messageId, setBy } = params;
 		const now = Date.now();
@@ -308,8 +282,15 @@ export class SpamReportService {
 			// Only wait on the move's settlement when there is actually a
 			// dependent write to make (the restore below) — a move in flight for
 			// an unrelated reason is not this operation's concern.
-			const settled = await this.waitForMoveToSettle(messageId);
-			if (settled.status === MessageStatus.moving) {
+			const settled = await waitForPlacementToSettle(
+				this.messageService,
+				messageId,
+				{
+					timeoutMs: this.moveSettleTimeoutMs,
+					pollMs: this.moveSettlePollMs,
+				},
+			);
+			if (isPlacementUnsettled(settled)) {
 				throw new MoveNotSettledError(messageId);
 			}