@remit/backend 0.0.73 → 0.0.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.73",
+  "version": "0.0.75",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/src/handlers/folder-role-appointments.test.ts

@@ -1,12 +1,20 @@
 import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
 import type { AccountSettingItem } from "@remit/data-ports";
 import type { RoleMailboxCandidate } from "@remit/data-ports/folder-role";
-import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
+import {
+	CanonicalMailboxRole,
+	FolderAppointmentSource,
+	MailboxSpecialUse,
+} from "@remit/domain-enums";
 import {
 	CANONICAL_ROLES,
 	groupFolderAppointmentsByAccount,
 	loadFolderAppointmentsForAccount,
+	type PersistedFolderAppointment,
 	resolveFolderAppointments,
 	writeFolderRoleAppointment,
 } from "./folder-role-appointments.js";
@@ -21,6 +29,12 @@ const setting = (name: string, value: string): AccountSettingItem =>
 		updatedAt: 0,
 	}) as AccountSettingItem;
 
+const appointed = (
+	mailboxId: string,
+	lastKnownPath?: string,
+): Map<string, PersistedFolderAppointment> =>
+	new Map([[CanonicalMailboxRole.Trash, { mailboxId, lastKnownPath }]]);
+
 describe("CANONICAL_ROLES", () => {
 	it("carries every RFC 032 anchor role, Custom excluded", () => {
 		assert.deepEqual(
@@ -55,6 +69,11 @@ describe("resolveFolderAppointments", () => {
 		},
 	];
 
+	const roleIn = (
+		result: ReturnType<typeof resolveFolderAppointments>,
+		role: string,
+	) => result.find((entry) => entry.role === role);
+
 	it("carries one entry per canonical role, even when unfilled", () => {
 		const result = resolveFolderAppointments(new Map(), folders);
 		assert.deepEqual(
@@ -63,26 +82,74 @@ describe("resolveFolderAppointments", () => {
 		);
 	});
 
-	it("prefers the persisted appointment over a fresh proposal", () => {
-		const persisted = new Map([[CanonicalMailboxRole.Drafts, "mb-concepten"]]);
+	it("gives every role a source, so no surface has to infer one", () => {
+		const result = resolveFolderAppointments(new Map(), folders);
+		assert.equal(
+			result.every((entry) => entry.source !== undefined),
+			true,
+		);
+	});
+
+	it("tells a folder the user chose from one reader guessed by name", () => {
+		const persisted = new Map<string, PersistedFolderAppointment>([
+			[CanonicalMailboxRole.Drafts, { mailboxId: "mb-concepten" }],
+		]);
 		const result = resolveFolderAppointments(persisted, folders);
-		const drafts = result.find((r) => r.role === CanonicalMailboxRole.Drafts);
+		const drafts = roleIn(result, CanonicalMailboxRole.Drafts);
 		assert.equal(drafts?.mailboxId, "mb-concepten");
+		assert.equal(drafts?.source, FolderAppointmentSource.Appointed);
+
+		const proposed = resolveFolderAppointments(new Map(), folders);
+		const guess = roleIn(proposed, CanonicalMailboxRole.Drafts);
+		assert.equal(guess?.mailboxId, "mb-concepten");
+		assert.equal(guess?.source, FolderAppointmentSource.Proposed);
 	});
 
-	it("re-proposes when the persisted mailbox no longer exists", () => {
-		const persisted = new Map([
-			[CanonicalMailboxRole.Junk, "mb-deleted-long-ago"],
+	it("marks the server's own flag and the reserved INBOX name as such", () => {
+		const result = resolveFolderAppointments(new Map(), folders);
+		assert.equal(
+			roleIn(result, CanonicalMailboxRole.Junk)?.source,
+			FolderAppointmentSource.Flagged,
+		);
+		assert.equal(
+			roleIn(result, CanonicalMailboxRole.Inbox)?.source,
+			FolderAppointmentSource.Reserved,
+		);
+	});
+
+	it("surfaces a choice whose folder is gone as broken, not as absent", () => {
+		const persisted = new Map<string, PersistedFolderAppointment>([
+			[
+				CanonicalMailboxRole.Junk,
+				{ mailboxId: "mb-deleted-long-ago", lastKnownPath: "INBOX/Rommel" },
+			],
 		]);
-		const result = resolveFolderAppointments(persisted, folders);
-		const junk = result.find((r) => r.role === CanonicalMailboxRole.Junk);
+		const junk = roleIn(
+			resolveFolderAppointments(persisted, folders),
+			CanonicalMailboxRole.Junk,
+		);
+		assert.equal(junk?.source, FolderAppointmentSource.Stale);
+		assert.equal(junk?.staleAppointmentMailboxId, "mb-deleted-long-ago");
+		assert.equal(junk?.staleAppointmentPath, "INBOX/Rommel");
 		assert.equal(junk?.mailboxId, "mb-spam");
 	});
 
 	it("leaves a role unfilled when nothing persisted or proposed matches", () => {
-		const result = resolveFolderAppointments(new Map(), folders);
-		const archive = result.find((r) => r.role === CanonicalMailboxRole.Archive);
+		const archive = roleIn(
+			resolveFolderAppointments(new Map(), folders),
+			CanonicalMailboxRole.Archive,
+		);
 		assert.equal(archive?.mailboxId, undefined);
+		assert.equal(archive?.source, FolderAppointmentSource.None);
+	});
+
+	it("never reads the recorded path as evidence for the role", () => {
+		const trash = roleIn(
+			resolveFolderAppointments(appointed("mb-inbox", "Prullenbak"), folders),
+			CanonicalMailboxRole.Trash,
+		);
+		assert.equal(trash?.mailboxId, "mb-inbox");
+		assert.equal(trash?.staleAppointmentPath, undefined);
 	});
 });
 
@@ -105,11 +172,35 @@ describe("groupFolderAppointmentsByAccount", () => {
 		];
 		const grouped = groupFolderAppointmentsByAccount(settings);
 		assert.deepEqual(Object.fromEntries(grouped.get("acc-1") ?? []), {
-			[CanonicalMailboxRole.Drafts]: "mb-1",
-			[CanonicalMailboxRole.Sent]: "mb-2",
+			[CanonicalMailboxRole.Drafts]: { mailboxId: "mb-1" },
+			[CanonicalMailboxRole.Sent]: { mailboxId: "mb-2" },
 		});
 		assert.deepEqual(Object.fromEntries(grouped.get("acc-2") ?? []), {
-			[CanonicalMailboxRole.Inbox]: "mb-3",
+			[CanonicalMailboxRole.Inbox]: { mailboxId: "mb-3" },
+		});
+	});
+
+	it("attaches the recorded path to the appointment it belongs to", () => {
+		const settings = [
+			setting(
+				`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Trash}`,
+				"mb-1",
+			),
+			setting(
+				`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Trash}`,
+				"INBOX/Bak",
+			),
+			setting(
+				`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Sent}`,
+				"INBOX/Verzonden",
+			),
+		];
+		const grouped = groupFolderAppointmentsByAccount(settings);
+		assert.deepEqual(Object.fromEntries(grouped.get("acc-1") ?? []), {
+			[CanonicalMailboxRole.Trash]: {
+				mailboxId: "mb-1",
+				lastKnownPath: "INBOX/Bak",
+			},
 		});
 	});
 
@@ -128,71 +219,141 @@ describe("groupFolderAppointmentsByAccount", () => {
 		];
 		const grouped = groupFolderAppointmentsByAccount(settings);
 		assert.deepEqual(Object.fromEntries(grouped.get("acc-1") ?? []), {
-			[CanonicalMailboxRole.Drafts]: "mb-1",
+			[CanonicalMailboxRole.Drafts]: { mailboxId: "mb-1" },
 		});
 	});
 });
 
 describe("loadFolderAppointmentsForAccount", () => {
+	const readerOver = (stored: Map<string, string>) => ({
+		get: async (_accountConfigId: string, name: string) => {
+			const value = stored.get(name);
+			return value ? setting(name, value) : null;
+		},
+	});
+
 	it("reads each role's row and collects only the ones that exist", async () => {
-		const stored = new Map<string, string>([
-			[`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Sent}`, "mb-sent"],
-		]);
-		const accountSetting = {
-			get: async (_accountConfigId: string, name: string) => {
-				const value = stored.get(name);
-				return value ? setting(name, value) : null;
-			},
-		};
 		const roles = await loadFolderAppointmentsForAccount(
-			accountSetting,
+			readerOver(
+				new Map([
+					[
+						`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Sent}`,
+						"mb-sent",
+					],
+				]),
+			),
 			"cfg-1",
 			"acc-1",
 		);
 		assert.deepEqual(Object.fromEntries(roles), {
-			[CanonicalMailboxRole.Sent]: "mb-sent",
+			[CanonicalMailboxRole.Sent]: { mailboxId: "mb-sent" },
 		});
 	});
+
+	it("picks up the recorded path beside the appointment", async () => {
+		const roles = await loadFolderAppointmentsForAccount(
+			readerOver(
+				new Map([
+					[
+						`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Trash}`,
+						"mb-bak",
+					],
+					[
+						`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Trash}`,
+						"INBOX/Bak",
+					],
+				]),
+			),
+			"cfg-1",
+			"acc-1",
+		);
+		assert.deepEqual(roles.get(CanonicalMailboxRole.Trash), {
+			mailboxId: "mb-bak",
+			lastKnownPath: "INBOX/Bak",
+		});
+	});
+
+	it("drops a label left behind by an appointment that was cleared", async () => {
+		const roles = await loadFolderAppointmentsForAccount(
+			readerOver(
+				new Map([
+					[
+						`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Trash}`,
+						"INBOX/Bak",
+					],
+				]),
+			),
+			"cfg-1",
+			"acc-1",
+		);
+		assert.equal(roles.get(CanonicalMailboxRole.Trash), undefined);
+	});
 });
 
 describe("writeFolderRoleAppointment", () => {
-	it("upserts a String-valued row for a value", async () => {
-		const calls: unknown[] = [];
-		const accountSetting = {
-			upsert: async (input: unknown) => {
-				calls.push(input);
-				return input as never;
-			},
-			delete: async () => {
-				throw new Error("should not delete");
+	const recorder = () => {
+		const upserts: unknown[] = [];
+		const deletes: unknown[][] = [];
+		return {
+			upserts,
+			deletes,
+			accountSetting: {
+				upsert: async (input: unknown) => {
+					upserts.push(input);
+					return input as never;
+				},
+				delete: async (accountConfigId: string, name: string) => {
+					deletes.push([accountConfigId, name]);
+				},
 			},
 		};
+	};
+
+	it("records the path alongside the appointment", async () => {
+		const { upserts, deletes, accountSetting } = recorder();
 		await writeFolderRoleAppointment(
 			accountSetting,
 			"cfg-1",
 			"acc-1",
 			CanonicalMailboxRole.Archive,
 			"mb-archive",
+			"INBOX/Archief",
 		);
-		assert.deepEqual(calls, [
+		assert.deepEqual(upserts, [
 			{
 				accountConfigId: "cfg-1",
 				name: `FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Archive}`,
 				value: { kind: "String", value: "mb-archive" },
 			},
+			{
+				accountConfigId: "cfg-1",
+				name: `FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Archive}`,
+				value: { kind: "String", value: "INBOX/Archief" },
+			},
 		]);
+		assert.deepEqual(deletes, []);
 	});
 
-	it("deletes the row when mailboxId is null (clear)", async () => {
-		const calls: unknown[][] = [];
-		const accountSetting = {
-			upsert: async () => {
-				throw new Error("should not upsert");
-			},
-			delete: async (accountConfigId: string, name: string) => {
-				calls.push([accountConfigId, name]);
-			},
-		};
+	it("clears a path left over from the previous choice", async () => {
+		const { upserts, deletes, accountSetting } = recorder();
+		await writeFolderRoleAppointment(
+			accountSetting,
+			"cfg-1",
+			"acc-1",
+			CanonicalMailboxRole.Archive,
+			"mb-archive",
+		);
+		assert.equal(upserts.length, 1);
+		assert.deepEqual(deletes, [
+			[
+				"cfg-1",
+				`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Archive}`,
+			],
+		]);
+	});
+
+	it("deletes both rows when the appointment is cleared", async () => {
+		const { upserts, deletes, accountSetting } = recorder();
 		await writeFolderRoleAppointment(
 			accountSetting,
 			"cfg-1",
@@ -200,8 +361,78 @@ describe("writeFolderRoleAppointment", () => {
 			CanonicalMailboxRole.Archive,
 			null,
 		);
-		assert.deepEqual(calls, [
+		assert.deepEqual(upserts, []);
+		assert.deepEqual(deletes, [
 			["cfg-1", `FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Archive}`],
+			[
+				"cfg-1",
+				`FolderRoleAppointmentLabel#acc-1#${CanonicalMailboxRole.Archive}`,
+			],
+		]);
+	});
+});
+
+/**
+ * D1 of the #887 design: a folder-role appointment row means one thing — a
+ * person decided. That is what makes an appointment outrank the server's own
+ * \Trash flag, and what makes an Empty Trash on one defensible. It holds only
+ * while the row has a single author, so the author is pinned here rather than
+ * left to review.
+ */
+describe("who may write a folder-role appointment", () => {
+	const PACKAGES = fileURLToPath(new URL("../../../", import.meta.url));
+
+	const sourceFiles = (): string[] => {
+		const files: string[] = [];
+		for (const pkg of readdirSync(PACKAGES, { withFileTypes: true })) {
+			if (!pkg.isDirectory()) continue;
+			const src = join(PACKAGES, pkg.name, "src");
+			if (!existsSync(src)) continue;
+			for (const entry of readdirSync(src, { recursive: true })) {
+				const name = String(entry);
+				if (!name.endsWith(".ts") && !name.endsWith(".tsx")) continue;
+				if (name.endsWith(".test.ts") || name.endsWith(".test.tsx")) continue;
+				files.push(`${pkg.name}/src/${name}`);
+			}
+		}
+		return files;
+	};
+
+	it("is composed in three places, and nowhere else in the repo", () => {
+		const referrers = sourceFiles().filter((file) =>
+			readFileSync(join(PACKAGES, file), "utf8").includes(
+				"composeFolderRoleAppointmentName",
+			),
+		);
+		assert.deepEqual(referrers.sort(), [
+			"backend/src/handlers/folder-role-appointments.ts",
+			"data-ports/src/folder-role.ts",
+			"drizzle-service/src/repos/i4-mailbox-special-use.ts",
 		]);
 	});
+
+	it("is written by writeFolderRoleAppointment alone", () => {
+		const source = readFileSync(
+			fileURLToPath(new URL("./folder-role-appointments.ts", import.meta.url)),
+			"utf8",
+		);
+		const writer = source.slice(
+			source.indexOf("export const writeFolderRoleAppointment"),
+		);
+		const body = writer.slice(0, writer.indexOf("\n};"));
+
+		const count = (text: string, needle: string) =>
+			text.split(needle).length - 1;
+		// Without these, renaming the receiver satisfies the guard with 0 === 0.
+		assert.ok(count(body, "accountSetting.upsert(") > 0);
+		assert.ok(count(body, "accountSetting.delete(") > 0);
+		assert.equal(
+			count(source, "accountSetting.upsert("),
+			count(body, "accountSetting.upsert("),
+		);
+		assert.equal(
+			count(source, "accountSetting.delete("),
+			count(body, "accountSetting.delete("),
+		);
+	});
 });

package/src/handlers/folder-role-appointments.ts

@@ -7,24 +7,40 @@ import type {
 import {
 	CANONICAL_ROLES,
 	type CanonicalMailboxRoleValue,
+	composeFolderRoleAppointmentLabelName,
 	composeFolderRoleAppointmentName,
+	parseFolderRoleAppointmentLabelName,
 	parseFolderRoleAppointmentName,
 	type RoleMailboxCandidate,
-	resolveMailboxForRole,
+	type RoleResolution,
+	resolveRoleForAccount,
 } from "@remit/data-ports/folder-role";
+import { FolderAppointmentSource } from "@remit/domain-enums";
 
 /**
  * RFC 032 exclusive-folder-appointment (#976): a per-account role→mailbox map.
  * Each row is a `FolderRoleAppointment#<accountId>#<role>` AccountSetting (RFC
  * 032 settings tiers), so a role can never be persisted twice for one account —
  * writing it replaces whichever mailbox previously held it. This module owns
- * that persistence; the read side is `resolveMailboxForRole`
+ * that persistence; the read side is `resolveRoleForAccount`
  * (`@remit/data-ports/folder-role`), the same rule every special-folder lookup
  * in the backend and the workers goes through.
+ *
+ * A second row, `FolderRoleAppointmentLabel#<accountId>#<role>`, records the
+ * path the appointed mailbox had at the time (#887), so a folder another client
+ * later deletes can still be named back to the user. It is display only: it
+ * lives beside the appointment rather than inside it precisely so the
+ * repository that resolves roles composes one name and cannot reach the other.
  */
 
 export { CANONICAL_ROLES };
 
+/** One role's persisted appointment: the choice, plus the path it was made on. */
+export interface PersistedFolderAppointment {
+	mailboxId: string;
+	lastKnownPath?: string;
+}
+
 const stringValueOf = (item: AccountSettingItem): string | undefined => {
 	const { value } = item;
 	return value.kind === "String" ? value.value : undefined;
@@ -37,17 +53,31 @@ const stringValueOf = (item: AccountSettingItem): string | undefined => {
  */
 export const groupFolderAppointmentsByAccount = (
 	settings: AccountSettingItem[],
-): Map<string, Map<string, string>> => {
-	const byAccount = new Map<string, Map<string, string>>();
+): Map<string, Map<string, PersistedFolderAppointment>> => {
+	const byAccount = new Map<string, Map<string, PersistedFolderAppointment>>();
+
 	for (const setting of settings) {
 		const target = parseFolderRoleAppointmentName(setting.name);
 		if (!target) continue;
 		const mailboxId = stringValueOf(setting);
 		if (mailboxId === undefined) continue;
-		const roles = byAccount.get(target.accountId) ?? new Map<string, string>();
-		roles.set(target.role, mailboxId);
+		const roles =
+			byAccount.get(target.accountId) ??
+			new Map<string, PersistedFolderAppointment>();
+		roles.set(target.role, { mailboxId });
 		byAccount.set(target.accountId, roles);
 	}
+
+	for (const setting of settings) {
+		const target = parseFolderRoleAppointmentLabelName(setting.name);
+		if (!target) continue;
+		const lastKnownPath = stringValueOf(setting);
+		if (lastKnownPath === undefined) continue;
+		const appointment = byAccount.get(target.accountId)?.get(target.role);
+		if (!appointment) continue;
+		appointment.lastKnownPath = lastKnownPath;
+	}
+
 	return byAccount;
 };
 
@@ -60,19 +90,32 @@ export const loadFolderAppointmentsForAccount = async (
 	accountSetting: Pick<IAccountSettingRepository, "get">,
 	accountConfigId: string,
 	accountId: string,
-): Promise<Map<string, string>> => {
+): Promise<Map<string, PersistedFolderAppointment>> => {
 	const entries = await Promise.all(
 		CANONICAL_ROLES.map(async (role) => {
-			const item = await accountSetting.get(
+			const appointment = await accountSetting.get(
 				accountConfigId,
 				composeFolderRoleAppointmentName(accountId, role),
 			);
-			return [role, item ? stringValueOf(item) : undefined] as const;
+			const mailboxId = appointment ? stringValueOf(appointment) : undefined;
+			if (mailboxId === undefined) return [role, undefined] as const;
+
+			const label = await accountSetting.get(
+				accountConfigId,
+				composeFolderRoleAppointmentLabelName(accountId, role),
+			);
+			const lastKnownPath = label ? stringValueOf(label) : undefined;
+			return [
+				role,
+				lastKnownPath === undefined
+					? { mailboxId }
+					: { mailboxId, lastKnownPath },
+			] as const;
 		}),
 	);
-	const roles = new Map<string, string>();
-	for (const [role, mailboxId] of entries) {
-		if (mailboxId !== undefined) roles.set(role, mailboxId);
+	const roles = new Map<string, PersistedFolderAppointment>();
+	for (const [role, appointment] of entries) {
+		if (appointment) roles.set(role, appointment);
 	}
 	return roles;
 };
@@ -82,40 +125,101 @@ export const loadFolderAppointmentsForAccount = async (
  * — the role goes back to unfilled (RFC 032 settings tiers: absence is unset).
  * A value upserts it, replacing whatever mailbox the role pointed at before;
  * there is no second row a duplicate could live in.
+ *
+ * The label row moves with it, so a path recorded for a previous choice can
+ * never be shown against the current one.
  */
-export const writeFolderRoleAppointment = (
+export const writeFolderRoleAppointment = async (
 	accountSetting: Pick<IAccountSettingRepository, "upsert" | "delete">,
 	accountConfigId: string,
 	accountId: string,
 	role: CanonicalMailboxRoleValue,
 	mailboxId: string | null,
-): Promise<unknown> => {
+	lastKnownPath?: string,
+): Promise<void> => {
 	const name = composeFolderRoleAppointmentName(accountId, role);
+	const labelName = composeFolderRoleAppointmentLabelName(accountId, role);
+
 	if (mailboxId === null) {
-		return accountSetting.delete(accountConfigId, name);
+		await accountSetting.delete(accountConfigId, name);
+		await accountSetting.delete(accountConfigId, labelName);
+		return;
 	}
-	return accountSetting.upsert({
+
+	await accountSetting.upsert({
 		accountConfigId,
 		name,
 		value: { kind: "String", value: mailboxId },
 	});
+
+	if (lastKnownPath === undefined) {
+		await accountSetting.delete(accountConfigId, labelName);
+		return;
+	}
+	await accountSetting.upsert({
+		accountConfigId,
+		name: labelName,
+		value: { kind: "String", value: lastKnownPath },
+	});
+};
+
+const SOURCE_BY_KIND: Record<
+	"appointed" | "flagged" | "reserved" | "proposed",
+	FolderAppointment["source"]
+> = {
+	appointed: FolderAppointmentSource.Appointed,
+	flagged: FolderAppointmentSource.Flagged,
+	reserved: FolderAppointmentSource.Reserved,
+	proposed: FolderAppointmentSource.Proposed,
+};
+
+const toFolderAppointment = (
+	role: CanonicalMailboxRoleValue,
+	resolution: RoleResolution<RoleMailboxCandidate>,
+	lastKnownPath: string | undefined,
+): FolderAppointment => {
+	if (resolution.kind === "appointment_stale") {
+		const { fallback } = resolution;
+		return {
+			role,
+			source: FolderAppointmentSource.Stale,
+			mailboxId:
+				fallback.kind === "none" ? undefined : fallback.mailbox.mailboxId,
+			staleAppointmentMailboxId: resolution.appointedMailboxId,
+			staleAppointmentPath: lastKnownPath,
+		};
+	}
+	if (resolution.kind === "none") {
+		return { role, source: FolderAppointmentSource.None };
+	}
+	return {
+		role,
+		source: SOURCE_BY_KIND[resolution.kind],
+		mailboxId: resolution.mailbox.mailboxId,
+	};
 };
 
 /**
- * Resolve the full appointment set for one account: the user's persisted
- * choice when set (and still a real mailbox — a deleted mailbox's stale
- * appointment is treated as unfilled and re-proposed), else the server's
- * SPECIAL-USE flag, else a name proposal. Always returns one entry per
+ * Resolve the full appointment set for one account, each entry saying where it
+ * came from: the user's persisted choice when set, else the server's
+ * SPECIAL-USE flag, else the reserved INBOX name, else a name proposal. A
+ * choice naming a mailbox the account no longer holds resolves to whatever the
+ * account would have had without it, and says so — the user's decision is
+ * surfaced as broken rather than quietly discarded. Always one entry per
  * `CANONICAL_ROLES` member (RFC 032 settings tiers: total, never a sparse
- * array), so the map is never empty for a normal provider.
+ * array).
  */
 export const resolveFolderAppointments = (
-	persisted: ReadonlyMap<string, string>,
+	persisted: ReadonlyMap<string, PersistedFolderAppointment>,
 	mailboxes: readonly RoleMailboxCandidate[],
 ): FolderAppointment[] =>
 	CANONICAL_ROLES.map((role) => {
-		const found = resolveMailboxForRole(role, mailboxes, persisted.get(role));
-		return found ? { role, mailboxId: found.mailboxId } : { role };
+		const appointment = persisted.get(role);
+		return toFolderAppointment(
+			role,
+			resolveRoleForAccount(role, mailboxes, appointment?.mailboxId),
+			appointment?.lastKnownPath,
+		);
 	});
 
 /**

package/src/handlers/folder-role.ts

@@ -43,9 +43,11 @@ export const FolderRoleOperations: Record<
 		const existing = await account.get(accountId);
 		assertAccountOwnership(existing, accountConfigId, "act");
 
+		let lastKnownPath: string | undefined;
 		if (body.mailboxId) {
 			const target = await mailbox.get(accountId, body.mailboxId);
 			assertMailboxInAccount(target, accountId, "act");
+			lastKnownPath = target.fullPath;
 		}
 
 		await writeFolderRoleAppointment(
@@ -54,6 +56,7 @@ export const FolderRoleOperations: Record<
 			accountId,
 			role,
 			body.mailboxId ?? null,
+			lastKnownPath,
 		);
 
 		const [signature, overrides, folderAppointments] = await Promise.all([

package/src/handlers/mailbox.test.ts

@@ -1,8 +1,17 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { afterEach, describe, it } from "node:test";
 import type { MailboxItem } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
-import { excludeDeletingMailboxes } from "./mailbox.js";
+import { UnconfirmedTrashMailboxError } from "@remit/mailbox-service";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { deriveAccountConfigId } from "../auth.js";
+import {
+	_resetForTest,
+	type RemitClient,
+	setClient,
+} from "../service/data-client.js";
+import { excludeDeletingMailboxes, TrashOperations } from "./mailbox.js";
 
 const mailbox = (
 	over: Partial<MailboxItem> & { mailboxId: string },
@@ -32,3 +41,58 @@ describe("excludeDeletingMailboxes", () => {
 		);
 	});
 });
+
+const SUB = "cognito-sub-887";
+const ACCOUNT_ID = "acc-887";
+
+const emptyTrash = TrashOperations.TrashOperations_emptyTrash as unknown as (
+	context: Context,
+	event: APIGatewayProxyEvent,
+) => Promise<{ deletedCount: number }>;
+
+const callEmptyTrash = (
+	serviceEmptyTrash: () => Promise<{ deletedCount: number }>,
+): Promise<{ deletedCount: number }> => {
+	setClient({
+		account: {
+			get: async () => ({
+				accountId: ACCOUNT_ID,
+				accountConfigId: deriveAccountConfigId(SUB),
+			}),
+		},
+		messageMove: { emptyTrash: serviceEmptyTrash },
+	} as unknown as RemitClient);
+
+	return emptyTrash(
+		{ request: { params: { accountId: ACCOUNT_ID } } } as unknown as Context,
+		{
+			requestContext: { authorizer: { claims: { sub: SUB } } },
+		} as unknown as APIGatewayProxyEvent,
+	);
+};
+
+describe("TrashOperations_emptyTrash", () => {
+	afterEach(() => {
+		_resetForTest();
+	});
+
+	it("reports the service's count rather than one of its own", async () => {
+		// The handler resolves no folder and counts no rows: a second read would
+		// be free to disagree with the one that actually marked them.
+		const response = await callEmptyTrash(async () => ({ deletedCount: 7 }));
+
+		assert.deepEqual(response, { deletedCount: 7 });
+	});
+
+	it("lets the service's coded refusal through untouched", async () => {
+		await assert.rejects(
+			callEmptyTrash(async () => {
+				throw new UnconfirmedTrashMailboxError(ACCOUNT_ID);
+			}),
+			(error: unknown) =>
+				error instanceof UnconfirmedTrashMailboxError &&
+				error.statusCode === 409 &&
+				error.publicApiError?.details?.reason === "unconfirmed",
+		);
+	});
+});

package/src/handlers/mailbox.ts

@@ -5,7 +5,6 @@ import type {
 import type { IAccountSettingRepository, MailboxItem } from "@remit/data-ports";
 import { ForbiddenError, NotFoundError } from "@remit/data-ports/errors";
 import { MailboxSyncStatus, MessageSystemFlag } from "@remit/domain-enums";
-import { NoTrashMailboxError } from "@remit/mailbox-service";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
 import {
@@ -412,26 +411,10 @@ export const TrashOperations: Record<
 		const account = await client.account.get(accountId);
 		assertAccountOwnership(account, accountConfigId, "act");
 
-		// The same confirmed resolution `emptyTrash` expunges through, so the
-		// count reported is the count of the folder that gets emptied. It
-		// refuses rather than returning zero when no folder is appointed and
-		// none is flagged: "0 deleted" reads as success, and the user goes on
-		// believing their Trash is empty.
-		const trashMailbox =
-			await client.mailboxSpecialUse.findConfirmedTrashMailbox(accountId);
-
-		if (!trashMailbox) {
-			throw new NoTrashMailboxError(accountId);
-		}
-
-		const messages = await client.message.listAllByMailbox(
-			trashMailbox.mailboxId,
-		);
-		const deletedCount = messages.length;
-
-		// MessageMoveService handles: Message status updates + SQS event
-		await client.messageMove.emptyTrash(accountConfigId, accountId);
-
-		return { deletedCount };
+		// The service resolves Trash, marks the rows and counts them, all off one
+		// read, and refuses with a coded 409 when the role is unresolved. Counting
+		// here as well would be a second answer free to disagree with the one that
+		// acts, and "0 deleted" reads as success to a user whose Trash is untouched.
+		return client.messageMove.emptyTrash(accountConfigId, accountId);
 	},
 };