@remit/mailbox-service 0.0.15 → 0.0.16

package/src/message-sync.ts

@@ -36,6 +36,7 @@ import {
 } from "./mailbox-cursor-rebuild.js";
 import { ROOT_PART_PATH, walkMimeStructure } from "./mime-walker.js";
 import { PassThroughUnitOfWork } from "./pass-through-unit-of-work.js";
+import type { QuarantineService } from "./quarantine.js";
 import { reconcileStaleMessage } from "./stale-message-reconcile.js";
 import {
 	advanceChangeCursor,
@@ -146,8 +147,11 @@ interface SaveMessageResult extends SyncedMessage {
 /**
  * Wrapper outcome for a single message in the batch. A `failed` outcome means
  * the save threw (and was caught) — its UID must NOT advance the watermark, so
- * the message is re-fetched and retried on the next cycle. `null` means the
- * message carried no envelope and was intentionally skipped (nothing to retry).
+ * the message is re-fetched and retried on the next cycle. A `saved` outcome
+ * with a `null` result is a UID this round finished with but created no row
+ * for: a cross-mailbox collision, a change applied to an existing row, or a
+ * message quarantined instead of applied (issue #72). Its watermark advances
+ * either way, because there is nothing left to retry.
  */
 type BatchOutcome =
 	| { kind: "saved"; uid: number; result: SaveMessageResult | null }
@@ -224,6 +228,13 @@ export class MessageSyncService {
 		 * flip is never dismissed as redundant.
 		 */
 		private messageFlagService?: IMessageFlagRepository,
+		/**
+		 * The set of messages already set aside (issue #72). Message sync never
+		 * writes a record — only the body path can attribute a failure to the
+		 * message — but it reads the set so a uid the body path quarantined is
+		 * not re-fetched on every round.
+		 */
+		private quarantineService?: QuarantineService,
 	) {
 		this.log = logger ?? noopLogger;
 		this.unitOfWork =
@@ -309,6 +320,10 @@ export class MessageSyncService {
 			});
 		}
 
+		// One read per round, not per message (issue #72). The list is small by
+		// design — a growing one is a bug being reported, not a page to paginate.
+		const quarantined = await this.quarantineService?.load(accountConfigId);
+
 		const allUids = await connection.search(["ALL"]);
 		const uids = selectUidsToSync(allUids, lastSyncUid, highWaterMarkUid);
 		const unseenCount = status.unseen;
@@ -350,7 +365,42 @@ export class MessageSyncService {
 
 		// Process only the first batch
 		const batchUids = uids.slice(0, batchSize);
-		const messages = await this.fetchMessageBatch(batchUids);
+
+		// A quarantined UID is not fetched again, but it stays in `batchUids` so
+		// the watermark still advances over it. Filtering it out of the selection
+		// instead would hold the watermark below a message that is already
+		// durably resolved, which is the stall by another route.
+		const fetchUids = batchUids.filter(
+			(uid) => !quarantined?.has(mailboxId, box.uidvalidity, uid),
+		);
+		const messages =
+			fetchUids.length > 0 ? await this.fetchMessageBatch(fetchUids) : [];
+
+		// A UID the round could not act on. Two shapes reach here and neither is
+		// the message's fault: the FETCH returned no row at all (the connection
+		// layer drops rows imapflow yields without a usable UID or INTERNALDATE,
+		// #408, and a message can be expunged between the SEARCH and the FETCH),
+		// or it returned a row carrying no ENVELOPE, which names no message and
+		// is the same client-side glitch one field further in.
+		//
+		// They join `failedUids` rather than merely being left out of the batch.
+		// Absence alone does not hold a watermark: `advanceUidWatermarks` takes
+		// the MAX of what was applied, so a gap in the middle of a batch is
+		// stepped straight over — [23, 22, 21] with 22 missing still advances to
+		// 23 and loses 22 for good. A failure is the one thing a watermark is
+		// built to stop below.
+		const applicable = messages.filter((msg) => msg.envelope !== undefined);
+		const unusableUids = batchUids.filter(
+			(uid) =>
+				!applicable.some((msg) => msg.uid === uid) &&
+				!quarantined?.has(mailboxId, box.uidvalidity, uid),
+		);
+		if (unusableUids.length > 0) {
+			this.log.warn(
+				{ mailboxId, mailboxPath, unusableUids },
+				"FETCH returned no usable row for some requested UIDs; holding the watermark below them",
+			);
+		}
 
 		// Process messages in parallel with concurrency limit. `stopOnError` stays
 		// at its default — but each message is saved through `trySaveMessage`,
@@ -358,7 +408,7 @@ export class MessageSyncService {
 		// rejecting. So one bad message can no longer abort the whole batch (the
 		// poison pill that previously froze the mailbox, #817).
 		const outcomes = await pMap(
-			messages,
+			applicable,
 			(msg) => this.trySaveMessage(mailboxId, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
@@ -379,15 +429,16 @@ export class MessageSyncService {
 
 		// UIDs whose save threw. They must stay inside the next cycle's fetch
 		// window, so the watermark may not advance past them (no silent loss).
-		const failedUids = new Set(
-			outcomes.flatMap((o) => (o.kind === "failed" ? [o.uid] : [])),
+		const saveFailedUids = outcomes.flatMap((o) =>
+			o.kind === "failed" ? [o.uid] : [],
 		);
-		if (failedUids.size > 0) {
+		if (saveFailedUids.length > 0) {
 			this.log.warn(
-				{ mailboxId, mailboxPath, failedUids: [...failedUids] },
+				{ mailboxId, mailboxPath, failedUids: saveFailedUids },
 				"Some messages failed to save; holding watermark below them for retry",
 			);
 		}
+		const failedUids = new Set([...saveFailedUids, ...unusableUids]);
 
 		// Watermarks advance over every SUCCESSFULLY-consumed UID in the batch,
 		// independent of ownership. `selectUidsToSync` reselects work purely by UID
@@ -413,7 +464,8 @@ export class MessageSyncService {
 		// enumeration work behind and lost no message to a failed save. Seeding
 		// it earlier would switch the mailbox to CHANGEDSINCE while UIDs it has
 		// never fetched still sit below the watermark, and those messages would
-		// never be discovered.
+		// never be discovered. A UID the FETCH returned nothing usable for is in
+		// `failedUids` too: the round did not finish with it either.
 		const enumerationComplete = !hasMore && failedUids.size === 0;
 
 		await this.mailboxService.update(accountId, mailboxId, {
@@ -587,8 +639,9 @@ export class MessageSyncService {
 
 		const newMessages =
 			newUids.length > 0 ? await this.fetchMessageBatch(newUids) : [];
+		const applicable = newMessages.filter((msg) => msg.envelope !== undefined);
 		const outcomes = await pMap(
-			newMessages,
+			applicable,
 			(msg) => this.trySaveMessage(mailboxId, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
@@ -600,6 +653,31 @@ export class MessageSyncService {
 
 		const serverUids = serverSnapshots.map((s) => s.uid);
 
+		// A UID this pass could not account for, in any of the three ways it can
+		// go missing: the snapshot FETCH never returned a row for it, the
+		// message FETCH never returned one, or the row it returned carried no
+		// ENVELOPE. None of the three is the message's fault and none can be
+		// quarantined, so each has to keep the UID selectable.
+		//
+		// This matters more here than on the enumeration path, not less. The
+		// covered region is computed from `serverUids` rather than from what was
+		// applied, so a UID missing anywhere inside its span is silently inside
+		// it; and this round seeds the mod-sequence and returns the mailbox to
+		// `normal`, so the next round takes CHANGEDSINCE, which never
+		// enumerates. A UID lost here is lost for good.
+		const savedUids = new Set(applicable.map((msg) => msg.uid));
+		const snapshotUids = new Set(serverUids);
+		const unusableUids = [
+			...allUids.filter((uid) => !snapshotUids.has(uid)),
+			...newUids.filter((uid) => !savedUids.has(uid)),
+		];
+		if (unusableUids.length > 0) {
+			this.log.warn(
+				{ mailboxId, mailboxPath, unusableUids },
+				"Cursor rebuild could not account for some UIDs; holding the watermark below them",
+			);
+		}
+
 		// A new message whose save threw must stay selectable, so the forward
 		// watermark stops below it and every UID above it is re-enumerated next
 		// round. The mod-sequence seed is withheld entirely in that case: the
@@ -607,9 +685,10 @@ export class MessageSyncService {
 		// it on a UIDVALIDITY change) and the new one would sit above the
 		// message that failed, so the mailbox goes back to enumeration until a
 		// clean round seeds it.
-		const failedUids = new Set(
-			outcomes.flatMap((o) => (o.kind === "failed" ? [o.uid] : [])),
-		);
+		const failedUids = new Set([
+			...outcomes.flatMap((o) => (o.kind === "failed" ? [o.uid] : [])),
+			...unusableUids,
+		]);
 		const lowestFailure = failedUids.size
 			? Math.min(...failedUids)
 			: Number.POSITIVE_INFINITY;
@@ -756,21 +835,53 @@ export class MessageSyncService {
 		const ordered = dropAppliedPrefix(orderByModseq(changed), cursor);
 		const batch = ordered.slice(0, batchSize);
 
+		// A quarantined UID stays in `batch`, so the cursor still advances over
+		// it; only the work of re-applying it is skipped.
+		const quarantined = await this.quarantineService?.load(accountConfigId);
+		const applicable = batch.filter(
+			(msg) =>
+				!quarantined?.has(mailboxId, box.uidvalidity, msg.uid) &&
+				msg.envelope !== undefined,
+		);
+
+		// A change row carrying no ENVELOPE holds the cursor and is retried; it
+		// is never set aside. On this path the message is usually one already
+		// stored — it demonstrably had a sender, a date and a Message-ID when it
+		// was first saved — so an envelope-less row is the FETCH glitching
+		// (#408), not the message being defective. Quarantining it would filter
+		// that UID out of every later round, stopping its flag sync until a
+		// purge, and tell the user a message they can open and read "arrived
+		// without a sender". A transient glitch heals on the retry; a persistent
+		// one trips the stalled-cursor alert, which is what that alert is for.
+		const unusableUids = batch.flatMap((msg) =>
+			msg.envelope === undefined &&
+			!quarantined?.has(mailboxId, box.uidvalidity, msg.uid)
+				? [msg.uid]
+				: [],
+		);
+		if (unusableUids.length > 0) {
+			this.log.warn(
+				{ mailboxId, mailboxPath, unusableUids },
+				"Change rows carried no ENVELOPE; holding the sync cursor below them",
+			);
+		}
+
 		const outcomes = await pMap(
-			batch,
+			applicable,
 			(msg) => this.tryApplyChange(mailboxId, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
-		const failedUids = new Set(
-			outcomes.flatMap((o) => (o.kind === "failed" ? [o.uid] : [])),
+		const saveFailedUids = outcomes.flatMap((o) =>
+			o.kind === "failed" ? [o.uid] : [],
 		);
-		if (failedUids.size > 0) {
+		if (saveFailedUids.length > 0) {
 			this.log.warn(
-				{ mailboxId, mailboxPath, failedUids: [...failedUids] },
+				{ mailboxId, mailboxPath, failedUids: saveFailedUids },
 				"Some changes failed to apply; holding the sync cursor below them for retry",
 			);
 		}
+		const failedUids = new Set([...saveFailedUids, ...unusableUids]);
 
 		// Body sync only concerns messages this round created — a metadata
 		// change has no new body to fetch.
@@ -1231,6 +1342,12 @@ export class MessageSyncService {
 			order: number;
 		}> = [];
 
+		// An unusable address is dropped and the message is written anyway, and
+		// that stays deliberate under the quarantine rules (issue #72). What is
+		// lost is one envelope address, not the message: it is stored, listed and
+		// readable, and its body is untouched. Setting the whole message aside
+		// over a malformed From would take readable mail out of the mailbox to
+		// protect a display name.
 		for (let i = 0; i < addresses.length; i++) {
 			const addr = addresses[i];
 			if (!isParseableEmailAddress(addr)) continue;

package/src/quarantine.test.ts

@@ -0,0 +1,191 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IMailboxSpecialUseRepository,
+	IQuarantineRepository,
+	MessageData,
+	MessageItem,
+	QuarantineItem,
+	QuarantineUpsertInput,
+} from "@remit/data-ports";
+import {
+	QuarantinedUids,
+	QuarantineService,
+	resolveMailboxRole,
+	shapeFromMessageData,
+} from "./quarantine.js";
+
+const noopLog = { info: () => {}, warn: () => {} };
+
+const buildService = (
+	specialUse: string[] = [],
+): {
+	service: QuarantineService;
+	writes: QuarantineUpsertInput[];
+	listed: string[];
+} => {
+	const writes: QuarantineUpsertInput[] = [];
+	const listed: string[] = [];
+	const repository = {
+		listByAccountConfigId: async (accountConfigId: string) => {
+			listed.push(accountConfigId);
+			return [] as QuarantineItem[];
+		},
+		upsert: async (input: QuarantineUpsertInput) => {
+			writes.push(input);
+		},
+	} satisfies IQuarantineRepository;
+
+	const mailboxSpecialUseService = {
+		listByMailboxId: async () => specialUse.map((use) => ({ specialUse: use })),
+	} as unknown as IMailboxSpecialUseRepository;
+
+	return {
+		service: new QuarantineService(
+			repository,
+			mailboxSpecialUseService,
+			"sha-abc",
+			noopLog,
+		),
+		writes,
+		listed,
+	};
+};
+
+const context = {
+	accountId: "acct-1",
+	accountConfigId: "cfg-1",
+	mailboxId: "mbx-1",
+	mailboxPath: "INBOX",
+	uidValidity: 1_712_000_000,
+	attempts: 2,
+};
+
+const failure = {
+	stage: "BodyParse" as const,
+	code: "UnreadableBody" as const,
+	message: "the parser said no",
+};
+
+describe("QuarantineService.record", () => {
+	it("stamps the worker build, not the client's", async () => {
+		const { service, writes } = buildService();
+		await service.record(context, 40217, failure);
+		assert.equal(writes[0]?.workerVersion, "sha-abc");
+	});
+
+	it("names the message by mailbox, uidValidity and uid", async () => {
+		const { service, writes } = buildService();
+		await service.record(context, 40217, failure);
+		assert.deepEqual(
+			{
+				mailboxId: writes[0]?.mailboxId,
+				uidValidity: writes[0]?.uidValidity,
+				uid: writes[0]?.uid,
+			},
+			{ mailboxId: "mbx-1", uidValidity: 1_712_000_000, uid: 40217 },
+		);
+	});
+
+	it("supplies no quarantineId, so the random-id default is unreachable", async () => {
+		const { service, writes } = buildService();
+		await service.record(context, 40217, failure);
+		assert.ok(!("quarantineId" in (writes[0] as object)));
+	});
+
+	it("omits an absent diagnostic rather than writing a null through", async () => {
+		const { service, writes } = buildService();
+		await service.record(
+			{ ...context, mailboxPath: "Clients/Acme" },
+			1,
+			failure,
+		);
+		assert.ok(!("failurePartPath" in (writes[0] as object)));
+		assert.ok(!("mailboxRole" in (writes[0] as object)));
+	});
+
+	it("reads the folder's role off the server's SPECIAL-USE", async () => {
+		const { service, writes } = buildService(["Junk"]);
+		await service.record({ ...context, mailboxPath: "Spam" }, 1, failure);
+		assert.equal(writes[0]?.mailboxRole, "Junk");
+	});
+});
+
+describe("resolveMailboxRole", () => {
+	it("gives INBOX its role without a SPECIAL-USE flag, which it never has", () => {
+		assert.equal(resolveMailboxRole("INBOX", []), "Inbox");
+	});
+
+	it("leaves a plain folder roleless instead of inventing one", () => {
+		assert.equal(resolveMailboxRole("Clients/Acme", []), undefined);
+	});
+
+	it("drops a SPECIAL-USE that is not a canonical role", () => {
+		assert.equal(resolveMailboxRole("Priority", ["Important"]), undefined);
+	});
+});
+
+describe("QuarantinedUids", () => {
+	const entries = [
+		{ mailboxId: "mbx-1", uidValidity: 10, uid: 5 },
+	] as QuarantineItem[];
+
+	it("matches a uid on the same mailbox and UIDVALIDITY", () => {
+		assert.equal(new QuarantinedUids(entries).has("mbx-1", 10, 5), true);
+	});
+
+	it("does not match the same uid on a new UIDVALIDITY, which is a different message", () => {
+		assert.equal(new QuarantinedUids(entries).has("mbx-1", 11, 5), false);
+	});
+
+	it("does not match the same uid in another mailbox", () => {
+		assert.equal(new QuarantinedUids(entries).has("mbx-2", 10, 5), false);
+	});
+});
+
+describe("shapeFromMessageData", () => {
+	const message = {
+		rfc822Size: 2048,
+		messageIdHeader: "<xyz@example.com>",
+	} as MessageItem;
+
+	const data = {
+		bodyPart: [
+			{
+				bodyPartId: "bp-0",
+				partPath: "0",
+				mediaType: "multipart",
+				mediaSubtype: "alternative",
+				transferEncoding: "7bit",
+			},
+			{
+				bodyPartId: "bp-1",
+				partPath: "1",
+				mediaType: "text",
+				mediaSubtype: "plain",
+				transferEncoding: "quoted-printable",
+			},
+		],
+		bodyPartParameter: [
+			{
+				bodyPartId: "bp-0",
+				parameterName: "charset",
+				parameterValue: "iso-8859-1",
+			},
+		],
+	} as unknown as MessageData;
+
+	it("rebuilds the tree from the rows metadata sync already wrote", () => {
+		assert.deepEqual(shapeFromMessageData(message, data).structure, [
+			{ depth: 0, contentType: "multipart/alternative" },
+			{ depth: 1, contentType: "text/plain" },
+		]);
+	});
+
+	it("takes the root part's declared charset and encoding", () => {
+		const shape = shapeFromMessageData(message, data);
+		assert.equal(shape.charset, "iso-8859-1");
+		assert.equal(shape.transferEncoding, "7bit");
+		assert.equal(shape.contentType, "multipart/alternative");
+	});
+});

package/src/quarantine.ts

@@ -0,0 +1,228 @@
+import type {
+	IMailboxSpecialUseRepository,
+	IQuarantineRepository,
+	MessageData,
+	MessageItem,
+	QuarantineItem,
+	QuarantineMimeNodeItem,
+} from "@remit/data-ports";
+import { quarantineMessageIdHash, ROOT_PART_PATH } from "@remit/data-ports/id";
+import { CanonicalMailboxRole } from "@remit/domain-enums";
+
+type CanonicalRole = NonNullable<QuarantineItem["mailboxRole"]>;
+type FailureStage = QuarantineItem["failureStage"];
+type FailureCode = QuarantineItem["failureCode"];
+
+const CANONICAL_ROLES = new Set<string>(Object.values(CanonicalMailboxRole));
+
+/**
+ * The canonical role of the folder a quarantined message arrived in, read from
+ * the server's own RFC 6154 SPECIAL-USE declaration — the same source the
+ * appointment flow seeds from. A folder the server declares nothing about has
+ * no role, which is the normal state for a plain folder and is why the field
+ * is optional. `Important` is a SPECIAL-USE with no canonical role and drops
+ * out here rather than being invented into one.
+ */
+export const resolveMailboxRole = (
+	mailboxPath: string,
+	specialUse: readonly string[],
+): CanonicalRole | undefined => {
+	if (mailboxPath.toUpperCase() === "INBOX") return CanonicalMailboxRole.Inbox;
+	const matched = specialUse.find((use) => CANONICAL_ROLES.has(use));
+	return matched as CanonicalRole | undefined;
+};
+
+/** Everything about the quarantine that is the same for every uid in a round. */
+export interface QuarantineContext {
+	accountId: string;
+	accountConfigId: string;
+	mailboxId: string;
+	mailboxPath: string;
+	uidValidity: number;
+	/** Rounds tried before the message was set aside. */
+	attempts: number;
+}
+
+/**
+ * The repro fingerprint: what the message declared itself to be. Every field
+ * is optional-by-absence because a message can fail before its shape was read,
+ * and a required column would force the writer to invent a value or drop the
+ * record.
+ */
+export interface QuarantineMessageShape {
+	contentType?: string;
+	transferEncoding?: string;
+	charset?: string;
+	sizeBytes?: number;
+	structure: QuarantineMimeNodeItem[];
+	messageIdHash?: string;
+}
+
+export interface QuarantineFailure {
+	stage: FailureStage;
+	code: FailureCode;
+	/** Parser error text. Stored, shown on screen, never published. */
+	message: string;
+	partPath?: string;
+}
+
+const EMPTY_SHAPE: QuarantineMessageShape = { structure: [] };
+
+/**
+ * Message shape off the rows metadata sync already wrote. The body path has no
+ * FETCH result to read — it streams raw bytes — but the MIME tree it needs was
+ * walked into BodyPart rows when the message's metadata was synced, so the
+ * fingerprint comes from there rather than from re-reading headers the parser
+ * has just refused.
+ */
+export const shapeFromMessageData = (
+	message: MessageItem,
+	data: MessageData,
+): QuarantineMessageShape => {
+	const parts = [...data.bodyPart].sort((a, b) =>
+		a.partPath.localeCompare(b.partPath, "en", { numeric: true }),
+	);
+	const root = parts.find((part) => part.partPath === ROOT_PART_PATH);
+	const rootCharset = root
+		? data.bodyPartParameter.find(
+				(param) =>
+					param.bodyPartId === root.bodyPartId &&
+					param.parameterName.toLowerCase() === "charset",
+			)?.parameterValue
+		: undefined;
+
+	return {
+		...(root ? { contentType: `${root.mediaType}/${root.mediaSubtype}` } : {}),
+		...(root ? { transferEncoding: root.transferEncoding } : {}),
+		...(rootCharset ? { charset: rootCharset } : {}),
+		...(message.rfc822Size ? { sizeBytes: message.rfc822Size } : {}),
+		structure: parts.map((part) => ({
+			depth: partPathDepth(part.partPath),
+			contentType: `${part.mediaType}/${part.mediaSubtype}`,
+		})),
+		...hashOf(message.messageIdHeader),
+	};
+};
+
+const partPathDepth = (partPath: string): number =>
+	partPath === ROOT_PART_PATH ? 0 : partPath.split(".").length;
+
+const hashOf = (
+	messageIdHeader: string | undefined,
+): { messageIdHash?: string } => {
+	const messageIdHash = quarantineMessageIdHash(messageIdHeader);
+	return messageIdHash ? { messageIdHash } : {};
+};
+
+/**
+ * The set of messages already set aside, held for the duration of one sync
+ * round. A round loads it once and filters against it in memory: the list is
+ * small by design — a growing one is a bug being reported, not a page to
+ * paginate — and a lookup per message would put a query on the hot path for a
+ * state that is almost always empty.
+ */
+export class QuarantinedUids {
+	private readonly keys: ReadonlySet<string>;
+
+	constructor(entries: readonly QuarantineItem[]) {
+		this.keys = new Set(
+			entries.map((entry) =>
+				uidKey(entry.mailboxId, entry.uidValidity, entry.uid),
+			),
+		);
+	}
+
+	get size(): number {
+		return this.keys.size;
+	}
+
+	has(mailboxId: string, uidValidity: number, uid: number): boolean {
+		return this.keys.has(uidKey(mailboxId, uidValidity, uid));
+	}
+}
+
+const uidKey = (mailboxId: string, uidValidity: number, uid: number): string =>
+	`${mailboxId}:${uidValidity}:${uid}`;
+
+export interface QuarantineLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	warn(obj: Record<string, unknown>, msg: string): void;
+}
+
+/**
+ * Writes the record a message becomes when the sync path cannot apply it
+ * (issue #72), and loads the set a round filters against.
+ *
+ * Only a message defect reaches this class. Deciding that is the caller's job
+ * and it is made at exactly one kind of catch site — one narrow enough that
+ * the error can only have come from the message itself. An S3, queue or
+ * database failure propagates; writing one here would advance a cursor past
+ * mail that is fine and tell the user it was unreadable.
+ */
+export class QuarantineService {
+	constructor(
+		private readonly repository: IQuarantineRepository,
+		private readonly mailboxSpecialUseService: IMailboxSpecialUseRepository,
+		private readonly workerVersion: string,
+		private readonly log: QuarantineLogger,
+	) {}
+
+	async load(accountConfigId: string): Promise<QuarantinedUids> {
+		return new QuarantinedUids(
+			await this.repository.listByAccountConfigId(accountConfigId),
+		);
+	}
+
+	/**
+	 * Set a message aside. Resolves only once the row is durable, because the
+	 * caller's next act is to let a cursor move past this uid — and a cursor
+	 * that moves past work no record survives is the silent loss this whole
+	 * feature exists to end.
+	 */
+	async record(
+		context: QuarantineContext,
+		uid: number,
+		failure: QuarantineFailure,
+		shape: QuarantineMessageShape = EMPTY_SHAPE,
+	): Promise<void> {
+		// Resolved here rather than per round: a round almost never writes a row,
+		// so the lookup belongs on the write and not on the hot path.
+		const specialUse = await this.mailboxSpecialUseService.listByMailboxId(
+			context.mailboxId,
+		);
+		const mailboxRole = resolveMailboxRole(
+			context.mailboxPath,
+			specialUse.map((entry) => entry.specialUse),
+		);
+
+		await this.repository.upsert({
+			accountConfigId: context.accountConfigId,
+			accountId: context.accountId,
+			mailboxId: context.mailboxId,
+			uidValidity: context.uidValidity,
+			uid,
+			...(mailboxRole ? { mailboxRole } : {}),
+			mailboxPath: context.mailboxPath,
+			quarantinedAt: Date.now(),
+			attempts: context.attempts,
+			failureStage: failure.stage,
+			failureCode: failure.code,
+			failureMessage: failure.message,
+			...(failure.partPath ? { failurePartPath: failure.partPath } : {}),
+			workerVersion: this.workerVersion,
+			...shape,
+		});
+
+		this.log.warn(
+			{
+				mailboxId: context.mailboxId,
+				mailboxPath: context.mailboxPath,
+				uid,
+				uidValidity: context.uidValidity,
+				failureStage: failure.stage,
+				failureCode: failure.code,
+			},
+			"Message quarantined; cursor may advance past it",
+		);
+	}
+}