@remit/mailbox-service 0.0.91 → 0.0.93

package/package.json

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

package/src/index.ts

@@ -179,8 +179,9 @@ export {
 	validateMailboxPath,
 } from "./mailbox-management.js";
 export {
-	isFolderOffServer,
-	isMailboxNotOnServer,
+	EVERY_MAILBOX_STATE,
+	isFolderMutationInFlight,
+	isMailboxMutationInFlight,
 } from "./mailbox-presence.js";
 export {
 	type CreateMailboxQueueInput,
@@ -193,6 +194,7 @@ export {
 	type SyncAccountInfo,
 } from "./mailbox-sync.js";
 export {
+	type DeleteMessagesOutcome,
 	type DeleteOptions,
 	type MessageMoveConfig,
 	type MessageMoveLogger,
@@ -267,6 +269,12 @@ export {
 	resolveMailboxRole,
 	shapeFromMessageData,
 } from "./quarantine.js";
+export {
+	type RestoreSourcePlacementDeps,
+	type RestoreSourcePlacementInput,
+	type RestoreSourcePlacementOutcome,
+	restoreSourcePlacement,
+} from "./restore-source-placement.js";
 export {
 	extractSnippetFromEmail,
 	generateSnippet,
@@ -286,6 +294,12 @@ export {
 	type StaleMessageReconcileDeps,
 	type StaleMessageReconcileResult,
 } from "./stale-message-reconcile.js";
+export {
+	buildThreadMessageMoveRevert,
+	buildThreadMessageTrashUpdate,
+	buildThreadMessageUndelete,
+	type ThreadMessageRowState,
+} from "./thread-message-rows.js";
 export type {
 	FlatMailboxInfo,
 	IImapConnection,

package/src/mailbox-management.test.ts

@@ -1,6 +1,9 @@
 import assert from "node:assert";
 import { describe, it } from "node:test";
-import type { IMailboxRepository } from "@remit/data-ports";
+import type {
+	IMailboxRepository,
+	MailboxTransitionIntent,
+} from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import {
 	MailboxManagementService,
@@ -99,7 +102,14 @@ const boxStatus = (path: string): ImapBoxStatus => ({
 const recordingRepo = () => {
 	const updates: Array<{ mailboxId: string; patch: Record<string, unknown> }> =
 		[];
-	const repo: Pick<IMailboxRepository, "update" | "findByPathPrefix"> = {
+	const settles: Array<{
+		mailboxId: string;
+		intent: MailboxTransitionIntent;
+	}> = [];
+	const repo: Pick<
+		IMailboxRepository,
+		"update" | "transition" | "findByPathPrefix"
+	> = {
 		update: async (
 			_accountId: string,
 			mailboxId: string,
@@ -108,9 +118,17 @@ const recordingRepo = () => {
 			updates.push({ mailboxId, patch });
 			return {} as never;
 		},
+		transition: async (
+			_accountId: string,
+			mailboxId: string,
+			intent: MailboxTransitionIntent,
+		) => {
+			settles.push({ mailboxId, intent });
+			return {} as never;
+		},
 		findByPathPrefix: async () => [],
 	};
-	return { repo: repo as IMailboxRepository, updates };
+	return { repo: repo as IMailboxRepository, updates, settles };
 };
 
 const stubConnection = (
@@ -143,7 +161,7 @@ const stubConnection = (
 
 describe("MailboxManagementService.syncCreate — server path normalization", () => {
 	it("adopts the server-materialized path as the row's identity when it is prefixed", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection, opened } = stubConnection("INBOX/Notifications", [
 			"INBOX/Notifications",
 		]);
@@ -159,28 +177,28 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		assert.strictEqual(result.success, true);
 		// The mailbox is opened at the server's path, not the requested leaf.
 		assert.deepStrictEqual(opened, ["INBOX/Notifications"]);
-		assert.strictEqual(updates.length, 1);
+		assert.strictEqual(settles.length, 1);
 		// The row keeps its id and takes on the prefixed path, so the next reconcile
 		// updates it in place instead of insert+delete — every reference survives.
-		assert.strictEqual(updates[0].mailboxId, "mbx-1");
-		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles[0].mailboxId, "mbx-1");
+		assert.strictEqual(settles[0].intent.set?.fullPath, "INBOX/Notifications");
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("leaves the path untouched when the server keeps it as requested", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection } = stubConnection("Work", ["Work"]);
 		const service = new MailboxManagementService(repo);
 
 		await service.syncCreate("acc-1", "mbx-2", "Work", async () => connection);
 
-		assert.strictEqual(updates.length, 1);
-		assert.ok(!("fullPath" in updates[0].patch));
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.deepStrictEqual(settles[0].intent.set, {});
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("still adopts the server path when the fresh list cannot resolve it", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const { connection, opened } = stubConnection("INBOX/Notifications", []);
 		const service = new MailboxManagementService(repo);
 
@@ -192,13 +210,13 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		);
 
 		assert.deepStrictEqual(opened, []);
-		assert.strictEqual(updates.length, 1);
-		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.strictEqual(settles[0].intent.set?.fullPath, "INBOX/Notifications");
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
 	it("falls back to the requested path when the create result carries none", async () => {
-		const { repo, updates } = recordingRepo();
+		const { repo, settles } = recordingRepo();
 		const opened: string[] = [];
 		const subscribed: string[] = [];
 		const connection = {
@@ -234,9 +252,9 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		// A thin result never blanks fullPath — the requested path is used throughout.
 		assert.deepStrictEqual(subscribed, ["Archive"]);
 		assert.deepStrictEqual(opened, ["Archive"]);
-		assert.strictEqual(updates.length, 1);
-		assert.ok(!("fullPath" in updates[0].patch));
-		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+		assert.strictEqual(settles.length, 1);
+		assert.deepStrictEqual(settles[0].intent.set, {});
+		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 });
 

package/src/mailbox-management.ts

@@ -1,6 +1,7 @@
 import type { IMailboxRepository } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import { MailboxSyncStatus } from "@remit/domain-enums";
-import { isNotFoundError } from "./mailbox-presence.js";
+import { EVERY_MAILBOX_STATE, isNotFoundError } from "./mailbox-presence.js";
 import type { IImapConnection } from "./types.js";
 
 /**
@@ -115,6 +116,30 @@ export class MailboxManagementService {
 		this.log = logger ?? noopLogger;
 	}
 
+	/**
+	 * Write the settled state back, as the conditional write that is now the
+	 * only way to write it at all (D3). The from-set is every state because that
+	 * is what this settle decides against today — it is the unconditional write
+	 * it replaces, moved onto the door; #363 narrows it to the state its intent
+	 * recorded and gives a lost predicate its `already-settled` outcome.
+	 *
+	 * A null means the row is gone, which is what the unconditional write raised
+	 * a NotFoundError for, and what the handlers' #289-class terminal guards
+	 * classify as the user having deleted the folder mid-sync.
+	 */
+	private settle = async (
+		accountId: string,
+		mailboxId: string,
+		confirmedPath?: string,
+	): Promise<void> => {
+		const settled = await this.mailboxService.transition(accountId, mailboxId, {
+			from: EVERY_MAILBOX_STATE,
+			to: MailboxSyncStatus.synced,
+			set: confirmedPath !== undefined ? { fullPath: confirmedPath } : {},
+		});
+		if (!settled) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+	};
+
 	/**
 	 * Sync a CREATE operation to IMAP.
 	 * Called by worker after dequeuing MAILBOX_CREATE event.
@@ -149,7 +174,7 @@ export class MailboxManagementService {
 			typeof result.path === "string" && result.path.length > 0
 				? result.path
 				: path;
-		const pathUpdate = serverPath !== path ? { fullPath: serverPath } : {};
+		const confirmedPath = serverPath !== path ? serverPath : undefined;
 
 		this.log.info(
 			{ mailboxId, path, serverPath, created: result.created },
@@ -169,21 +194,24 @@ export class MailboxManagementService {
 			// Open the mailbox to get UIDVALIDITY and other status info
 			const status = await connection.openBox(serverPath, true);
 
+			// Two writes where there was one, and the settle is deliberately the
+			// second: counters are ordinary metadata and stay off the transition,
+			// whose whole point is that its write-set is the state (D3). A crash in
+			// between leaves the row `pending` with fresh counters, and the row not
+			// yet settled is what keeps the queue message unacked — the redelivery
+			// re-issues CREATE, the server answers ALREADYEXISTS, and #339's
+			// classification settles it. Settling first would be the unsafe order.
 			await this.mailboxService.update(accountId, mailboxId, {
-				...pathUpdate,
 				uidValidity: status.uidvalidity,
 				uidNext: status.uidnext,
 				messageCount: status.messages.total,
-				syncStatus: MailboxSyncStatus.synced,
 			});
+			await this.settle(accountId, mailboxId, confirmedPath);
 
 			await connection.closeBox();
 		} else {
 			// Mark as synced even if we couldn't get full info
-			await this.mailboxService.update(accountId, mailboxId, {
-				...pathUpdate,
-				syncStatus: MailboxSyncStatus.synced,
-			});
+			await this.settle(accountId, mailboxId, confirmedPath);
 		}
 
 		return { success: true };
@@ -215,11 +243,7 @@ export class MailboxManagementService {
 			"Renamed mailbox on IMAP server",
 		);
 
-		// Clear oldPath and mark as synced
-		await this.mailboxService.update(accountId, mailboxId, {
-			oldPath: undefined,
-			syncStatus: MailboxSyncStatus.synced,
-		});
+		await this.settle(accountId, mailboxId);
 
 		// The server rename is done and the row records it. The settle is repair
 		// work on top of that, so nothing it hits — the listing included — may reach
@@ -268,16 +292,17 @@ export class MailboxManagementService {
 		);
 
 		for (const descendant of descendants) {
-			if (descendant.syncStatus !== MailboxSyncStatus.pending) continue;
 			if (!onServer.has(descendant.fullPath)) continue;
-			await this.mailboxService
-				.update(accountId, descendant.mailboxId, {
-					syncStatus: MailboxSyncStatus.synced,
-				})
-				.catch((error: unknown) => {
-					if (isNotFoundError(error)) return;
-					throw error;
-				});
+			// The per-row settle of D15: `pending` is the state that carries the
+			// intent, and the predicate is on the UPDATE, so a row another client
+			// moved in between is skipped rather than overwritten. A row that is
+			// gone is skipped for free — a null is not an error here, which is what
+			// keeps a descendant deleted mid-settle out of the handler's
+			// whole-chain NotFoundError guard.
+			await this.mailboxService.transition(accountId, descendant.mailboxId, {
+				from: [MailboxSyncStatus.pending],
+				to: MailboxSyncStatus.synced,
+			});
 		}
 	};
 

package/src/mailbox-presence.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IMailboxRepository } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	isFolderMutationInFlight,
+	isMailboxMutationInFlight,
+} from "./mailbox-presence.js";
+
+const reader = (
+	get: IMailboxRepository["get"],
+): Pick<IMailboxRepository, "get"> => ({ get });
+
+describe("isFolderMutationInFlight", () => {
+	for (const [syncStatus, inFlight] of [
+		[MailboxSyncStatus.synced, false],
+		[MailboxSyncStatus.pending, true],
+		[MailboxSyncStatus.deleting, true],
+		[MailboxSyncStatus.failed, false],
+	] as const) {
+		it(`${syncStatus} is ${inFlight ? "" : "not "}a mutation in flight`, () => {
+			assert.equal(isFolderMutationInFlight({ syncStatus }), inFlight);
+		});
+	}
+
+	it("does not read failed as a folder to leave alone", () => {
+		// `failed` means the folder exists at `fullPath` and the last rename or
+		// delete intent did not land — so it holds the user's mail and syncing it
+		// is right. D7 upholds that by leaving no row at all for a create the
+		// server refused. Reading it as in-flight would stop syncing a live folder
+		// permanently and silently.
+		assert.equal(
+			isFolderMutationInFlight({ syncStatus: MailboxSyncStatus.failed }),
+			false,
+		);
+	});
+});
+
+describe("isMailboxMutationInFlight", () => {
+	it("reads the row it is given", async () => {
+		const service = reader((async () => ({
+			syncStatus: MailboxSyncStatus.deleting,
+		})) as unknown as IMailboxRepository["get"]);
+
+		assert.equal(await isMailboxMutationInFlight(service, "acc", "mbx"), true);
+	});
+
+	it("treats an absent row as in flight", async () => {
+		// The row's absence does not decide it at either end: on the way out the
+		// row is removed only after the IMAP folder is, and on the way in the row
+		// exists before the folder does.
+		const service = reader((async () => {
+			throw new NotFoundError("Mailbox not found: mbx");
+		}) as unknown as IMailboxRepository["get"]);
+
+		assert.equal(await isMailboxMutationInFlight(service, "acc", "mbx"), true);
+	});
+
+	it("rethrows a read that cannot answer", async () => {
+		// The caller uses this to classify a failure in hand; a read that fails
+		// for its own reasons must not be reported as "the folder is busy".
+		const service = reader((async () => {
+			throw new Error("connection reset by peer");
+		}) as unknown as IMailboxRepository["get"]);
+
+		await assert.rejects(
+			isMailboxMutationInFlight(service, "acc", "mbx"),
+			/connection reset by peer/,
+		);
+	});
+});

package/src/mailbox-presence.ts

@@ -5,43 +5,65 @@ export const isNotFoundError = (error: unknown): boolean =>
 	error instanceof Error && error.name === "NotFoundError";
 
 /**
- * Whether the IMAP server is not known to hold this folder — the row is gone,
- * its creation has not reached the server yet, or its deletion has been asked
- * for and not finished. Folders are written locally first and reconciled to the
- * server by the worker, so both ends of that lifecycle are states in which
- * syncing the folder can only fail.
+ * Every state a mailbox row can carry, for a transition whose caller decided
+ * against none of them.
  *
- * This is the terminal test for a sync event whose folder is not there. The
- * row's absence alone does not decide it, at either end: on the way out the row
- * is removed only after the IMAP folder is, so an event that fails against the
- * server still sees a live row for as long as that write takes; on the way in
- * the row exists before the folder does. `pending` and `deleting` are written by
- * the request itself, before the event that resolves it is enqueued, which is
- * what makes them sound proxies for presence: neither can be observed unless a
- * create has yet to land or a delete has been asked for.
+ * A transition predicate is supposed to name the state the caller read
+ * (docs/architecture/folder-rename-and-delete.md D3), and the intent recorders
+ * and settles that use this one name nothing yet: they are today's
+ * unconditional writes, moved onto the only door that can write a folder state
+ * at all. Each is narrowed to the from-set its transition-table row allows when
+ * the intents themselves land (#362, #363), which is also where a loser gets
+ * its 409.
+ */
+export const EVERY_MAILBOX_STATE = [
+	MailboxSyncStatus.synced,
+	MailboxSyncStatus.pending,
+	MailboxSyncStatus.failed,
+	MailboxSyncStatus.deleting,
+] as const;
+
+/**
+ * Whether a folder mutation is in flight, so nothing else may touch the folder
+ * over IMAP.
+ *
+ * It used to be spelled as a presence test — is the folder off the server —
+ * and that is no longer what it asks. Under D2 `fullPath` is always a path the
+ * server holds, rename target and all, so a rename-pending folder *is* on the
+ * server; what the two states share is that a worker owns the folder until its
+ * mutation settles. `pending` and `deleting` are written by the request itself,
+ * before the event that resolves it is enqueued, so neither can be observed
+ * unless a create or rename has yet to land or a delete has been asked for.
+ *
+ * This is the terminal test for a sync event whose folder is not the sync's to
+ * touch. The row's absence alone does not decide it, at either end: on the way
+ * out the row is removed only after the IMAP folder is, so an event that fails
+ * against the server still sees a live row for as long as that write takes; on
+ * the way in the row exists before the folder does.
+ *
+ * `failed` is deliberately not one of them. The invariant is that a `failed`
+ * row's folder exists at `fullPath` and the last rename or delete intent did
+ * not land — so the folder holds the user's mail and syncing it is right.
+ * D7 is what upholds that: a create the server refuses leaves no row at all,
+ * rather than a `failed` one standing for a folder that was never made. Reading
+ * `failed` as off-server would stop syncing a live folder permanently and
+ * silently, which is worse than the bounded stall it would remove.
  *
- * `failed` is deliberately not one of them, though it is the fourth state a
- * mailbox row can carry. It records that the last management operation failed
- * and says nothing about whether the folder is on the server: `handleDelete` and
- * `handleRename` set it on folders that exist and hold the user's mail, and
- * nothing ever clears it — `syncStatus` returns to `synced` only from a
- * subsequent successful create or rename, never from the sweep. Treating it as
- * off-server would stop syncing such a folder permanently and silently, which is
- * worse than the bounded stall it would remove. A `failed` row whose folder is
- * genuinely absent is reaped by the sweep's own cleanup, which runs before the
- * fan-out that would enqueue work for it.
+ * A rename-pending folder is skipped even though its `fullPath` is live. That
+ * is conservative rather than necessary (D12): it keeps this a single
+ * expression and costs a few seconds of sync for one folder.
  *
  * Mailbox management is judged differently — it is what establishes and removes
  * the folder, so it terminates on a not-found row alone.
  */
-export const isFolderOffServer = (
+export const isFolderMutationInFlight = (
 	mailbox: Pick<MailboxItem, "syncStatus">,
 ): boolean =>
 	mailbox.syncStatus === MailboxSyncStatus.pending ||
 	mailbox.syncStatus === MailboxSyncStatus.deleting;
 
-/** {@link isFolderOffServer} for a mailbox that has to be read first, an absent row included. */
-export const isMailboxNotOnServer = async (
+/** {@link isFolderMutationInFlight} for a mailbox that has to be read first, an absent row included. */
+export const isMailboxMutationInFlight = async (
 	mailboxService: Pick<IMailboxRepository, "get">,
 	accountId: string,
 	mailboxId: string,
@@ -53,5 +75,5 @@ export const isMailboxNotOnServer = async (
 			throw error;
 		});
 	if (!mailbox) return true;
-	return isFolderOffServer(mailbox);
+	return isFolderMutationInFlight(mailbox);
 };

package/src/mailbox-queue.ts

@@ -5,8 +5,11 @@ import type {
 	IMailboxRepository,
 	MailboxItem,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
+import { EVERY_MAILBOX_STATE } from "./mailbox-presence.js";
 
 /**
  * MAILBOX_CREATE event structure (matches remit-imap-worker/events.ts)
@@ -163,19 +166,32 @@ export class MailboxQueueService {
 		const mailbox = await this.mailboxService.get(accountId, mailboxId);
 		const oldPath = mailbox.fullPath;
 
-		// Update the mailbox path and set syncStatus to pending
-		const updated = await this.mailboxService.update(accountId, mailboxId, {
-			fullPath: newPath,
-			syncStatus: MailboxSyncStatus.pending,
-		});
-
-		// Update child mailbox paths
-		await this.mailboxService.renameChildPaths(
-			mailbox.accountId,
-			oldPath,
-			newPath,
-			mailbox.hierarchyDelimiter,
+		// One intent over the folder and every descendant, in one transaction:
+		// IMAP RENAME moves the subtree in one command, so a partially recorded
+		// rename is the state that produced today's phantom rows (D6). Each
+		// descendant's new path is equally absent from the server until
+		// MAILBOX_RENAME lands, so each is `pending` too — otherwise a reconcile
+		// in that window reaps it as server-deleted (#290).
+		const written = await this.mailboxService.transitionSubtree(
+			accountId,
+			mailboxId,
+			{
+				from: EVERY_MAILBOX_STATE,
+				to: MailboxSyncStatus.pending,
+				rowSet: (row) => {
+					const moved = rebaseMailboxPath(
+						row.fullPath,
+						oldPath,
+						newPath,
+						mailbox.hierarchyDelimiter,
+					);
+					return moved === undefined ? {} : { fullPath: moved };
+				},
+			},
 		);
+		if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+		const updated = written.find((row) => row.mailboxId === mailboxId);
+		if (!updated) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 
 		this.log.info({ mailboxId, oldPath, newPath }, "Renamed mailbox (local)");
 
@@ -208,9 +224,12 @@ export class MailboxQueueService {
 		const mailbox = await this.mailboxService.get(accountId, mailboxId);
 
 		// Mark as deleting (soft delete - worker will do actual delete after IMAP sync)
-		await this.mailboxService.update(accountId, mailboxId, {
-			syncStatus: MailboxSyncStatus.deleting,
-		});
+		const recorded = await this.mailboxService.transition(
+			accountId,
+			mailboxId,
+			{ from: EVERY_MAILBOX_STATE, to: MailboxSyncStatus.deleting },
+		);
+		if (!recorded) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 
 		this.log.info(
 			{ mailboxId, path: mailbox.fullPath },