@remit/mailbox-service 0.0.112 → 0.0.113

package/src/body-sync.ts

@@ -1,1891 +0,0 @@
-import { PassThrough, type Readable } from "node:stream";
-import { inspect } from "node:util";
-import {
-	provisionDefaultCalendar,
-	recordCalendarSuggestion,
-} from "@remit/calendar-service";
-import {
-	type BodyPartItem,
-	type IAddressRepository,
-	type ICalendarStore,
-	type ICalendarSuggestionRepository,
-	type IEnvelopeRepository,
-	type IFilterRepository,
-	type IMailboxSpecialUseRepository,
-	type IMessageRepository,
-	type IThreadMessageRepository,
-	isSenderMuted,
-	type MessageItem,
-	type ThreadMessageItem,
-	type UpdateMessageInput,
-} from "@remit/data-ports";
-import {
-	MessageGoneFromServerError,
-	MessagePlacementUnsettledError,
-	NotFoundError,
-} from "@remit/data-ports/errors";
-import { deriveAddressId, deriveBodyPartId } from "@remit/data-ports/id";
-import { isEncapsulatedMessage } from "@remit/data-ports/message-parts";
-import { isBulkSender } from "@remit/data-ports/wellknown";
-import {
-	FilterState,
-	MessageClassificationState,
-	PlacementAction,
-	PlacementConfidence,
-	QuarantineFailureStage,
-	SenderTrust,
-	SyncWarningStage,
-} from "@remit/domain-enums";
-import {
-	isStorageNotFoundError,
-	type ParsedBody,
-	type StorageService,
-} from "@remit/storage-service";
-import { type ParsedMail, simpleParser } from "mailparser";
-import pMap from "p-map";
-import { BodyParseError, parseMessageBody } from "./body-parse.js";
-import {
-	mapMessagePartsToContent,
-	parsePartSource,
-} from "./body-part-mapper.js";
-import { calendarParts } from "./calendar-parts.js";
-import {
-	classifyParsedMessage,
-	extractPrimaryFromEmail,
-} from "./classify-message.js";
-
-import { extractListId } from "./filters/list-id.js";
-import type { FilterMessage } from "./filters/match.js";
-import {
-	type FilterConfig,
-	type FilterDecision,
-	FilterPipeline,
-} from "./filters/pipeline.js";
-import type { FlagQueueService } from "./flag-queue.js";
-import { placementOf, resolveFolderRoleMailboxes } from "./folder-placement.js";
-import {
-	classifyPlacement,
-	type FolderPlacement,
-	type PlacementVerdict,
-	resolveSenderPlacement,
-} from "./heuristics/classifyPlacement.js";
-import {
-	denormalizeMessageCategory,
-	hasDecidedCategory,
-} from "./message-category.js";
-import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
-import type { PlacementMoveService } from "./placement-move.js";
-import { isPlacementUnsettled, uidMailboxIdOf } from "./placement-settled.js";
-import { type QuarantineService, shapeFromMessageData } from "./quarantine.js";
-import { extractSnippetFromEmail } from "./snippet.js";
-import type { SyncWarningService } from "./sync-warning.js";
-import { type IImapConnection, MailConnectionError } from "./types.js";
-
-const BODY_PART_STORE_CONCURRENCY = 4;
-
-type MessagePlacementVerdict = NonNullable<
-	UpdateMessageInput["placementVerdict"]
->;
-
-type MessageFilterMove = NonNullable<UpdateMessageInput["filterMove"]>;
-
-type ThreadMessageCategory = ThreadMessageItem["category"];
-
-/**
- * Outcome of {@link BodySyncService.resolvePlacement}: the audit `verdict` to
- * persist on the Message (present whenever Remit decided to act, i.e. action
- * != leave), and the IMAP `move` to enqueue (present only for a confident,
- * actionable verdict). An unsure verdict carries a `verdict` but no `move`.
- */
-interface PlacementOutcome {
-	verdict?: MessagePlacementVerdict;
-	move?: { destinationMailboxId: string; destinationPath: string };
-	placementDecidedAt?: number;
-}
-
-/**
- * Whether the body-sync hot path defers per-part S3 objects. Each MIME leaf is
- * its own PutObject, so during bulk sync these per-part writes dominate S3 write
- * count and cost. With deferral ON a synced message writes only `body.eml` +
- * `parsed.json.gz` (2 writes); the per-part objects are materialized lazily on
- * the first `contentUrl` read via {@link BodySyncService.ensureBodyPartsStored}.
- *
- * Default ON (cost savings). Set `DEFER_BODY_PARTS=false`/`0`/`off` to restore
- * the original eager per-part writes — a safe, reversible escape hatch.
- */
-export const isBodyPartDeferralEnabled = (): boolean => {
-	const raw = process.env.DEFER_BODY_PARTS;
-	if (raw === undefined) return true;
-	const normalized = raw.trim().toLowerCase();
-	return normalized !== "false" && normalized !== "0" && normalized !== "off";
-};
-
-/**
- * Sentinel object written under a message's parts prefix once lazy
- * materialization has stored EVERY leaf. The read path checks it first with a
- * single HEAD and early-returns, skipping the body.eml GET, the MIME re-parse,
- * and the per-leaf HEADs on every warm re-open.
- *
- * Deliberately an S3-only marker (no Message-row flag). A leading dot keeps it
- * out of any real IMAP section path (those are dot-separated digits).
- */
-const MATERIALIZED_SENTINEL_PART_PATH = ".materialized";
-
-/**
- * The sentinel for a message carrying a forwarded message. Those parts were
- * once stored under a layout in which the forwarded message's root overwrote
- * its own row, so a `.materialized` written then vouches for objects at the
- * wrong paths. Its own name makes every such message materialize once more,
- * overwriting what is there; no other message is touched.
- */
-const MATERIALIZED_SENTINEL_V2_PART_PATH = ".materialized.2";
-
-/**
- * A mid-stream socket drop during the ranged body fetch surfaces as a typed
- * `MailConnectionError` (the connection layer classifies imapflow's
- * `EConnectionClosed`/`NoConnection`). Detect by type/code, never by message
- * text — the underlying library strings vary.
- */
-const isConnectionDrop = (error: unknown): boolean => {
-	if (error instanceof MailConnectionError) {
-		return error.kind === "network";
-	}
-	const code = (error as { code?: string }).code;
-	return code === "EConnectionClosed" || code === "NoConnection";
-};
-
-/**
- * Project a parsed message onto the fields a filter matches against (RFC 034) —
- * the literal-clause targets. Kept
- * separate from `ParsedMail` so {@link FilterPipeline} stays parser-agnostic.
- */
-const toFilterMessage = (parsed: ParsedMail): FilterMessage => ({
-	from: extractPrimaryFromEmail(parsed) ?? "",
-	fromName: parsed.from?.value?.[0]?.name ?? "",
-	subject: parsed.subject ?? "",
-	text: parsed.text ?? "",
-	listId: extractListId(parsed),
-});
-
-const SNIPPET_LENGTH = 256;
-
-/**
- * The snippet the list row shows, from whichever body part carries text.
- * Exported for the classification backfill (issue #1197), which denormalizes
- * the same fields the body-store path does, from the same bytes.
- */
-export const extractSnippet = (parsed: ParsedMail): string =>
-	extractSnippetFromEmail(
-		parsed.text,
-		typeof parsed.html === "string" ? parsed.html : undefined,
-		SNIPPET_LENGTH,
-	);
-
-/**
- * Issue #499: whether a completed body-sync pass has already stored this
- * message's body. `bodyStorageKey` is written last, once every derivation of
- * that pass has run, so its presence means that pass finished.
- *
- * Key presence, and nothing more. What the classifier decided is
- * `Message.category`; whether it ran at all is `Message.classificationState`.
- * Neither is inferred from here — the field this reads is the storage fact.
- *
- * The re-fetch paths that re-enter with the key already set (`syncBodies(...,
- * force: true)` and `fetchAndGetBody`'s `NoSuchKey` fallback) are re-stores
- * that skip the derivations entirely (issue #1011), so this guard is what
- * keeps a first store that lands on an already-stored row from re-deciding
- * anything.
- */
-const hasStoredBody = (bodyStorageKey: string | undefined): boolean =>
-	Boolean(bodyStorageKey);
-
-/**
- * Issue #398: `flags.autoArchive` is a filing preference relative to the Inbox.
- * A `leave` verdict reaches it for two unrelated reasons and only one of them
- * means "nothing confident to say":
- *
- * - `already-moved-by-remit` is {@link classifyPlacement}'s guard against
- *   re-deciding a settled placement, and auto-archive is a re-decision. It
- *   fires on messages Remit itself placed, or that a user moved back
- *   afterwards.
- * - A message already in Junk gets an unsure `leave` whatever the sender's
- *   `blocked` flag says, since the demote branch only fires outside Junk.
- *   Moving mail out of Junk is a rescue, which this file reserves for a
- *   confident signal plus sender trust.
- */
-const autoArchiveApplies = (
-	verdict: PlacementVerdict,
-	placement: FolderPlacement,
-): boolean =>
-	placement !== "junk" && !verdict.reasons.includes("already-moved-by-remit");
-
-export const toParsedBody = (parsed: ParsedMail): ParsedBody => ({
-	text: parsed.text ?? null,
-	html: typeof parsed.html === "string" ? parsed.html : null,
-	attachments: (parsed.attachments ?? []).map((a) => ({
-		filename: a.filename ?? null,
-		contentType: a.contentType,
-		contentDisposition: a.contentDisposition ?? null,
-		contentId: a.contentId ?? null,
-		size: a.size,
-	})),
-});
-
-export interface BodySyncLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	debug?(obj: Record<string, unknown>, msg: string): void;
-	warn?(obj: Record<string, unknown>, msg: string): void;
-	error?(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: BodySyncLogger = {
-	info: () => {},
-};
-
-export interface SyncBodiesResult {
-	syncedCount: number;
-	syncedMessageIds: string[];
-	skippedCount: number;
-	failedCount: number;
-	failedMessageIds: string[];
-}
-
-export interface FetchBodyResult {
-	text: string | null;
-	html: string | null;
-	storedAt: string;
-}
-
-export interface StoreBodyPartContentsResult {
-	stored: number;
-}
-
-export type ConnectionGetter = () => Promise<IImapConnection>;
-
-export interface BodySyncFolder {
-	mailboxId: string;
-	fullPath: string;
-	placement: FolderPlacement;
-}
-
-export interface BodySyncRoundFolder extends BodySyncFolder {
-	uidValidity: number;
-}
-
-export interface PlacementConfig {
-	mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	/**
-	 * Local-first mover for a confident placement verdict (issue #1271). Same
-	 * `moveMessage(accountConfigId, messageId, destinationMailboxId, accountId)`
-	 * signature as the general-purpose `MessageMoveService` it replaced here,
-	 * but backed by a pending-move marker + its own reconciler queue instead of
-	 * the general MESSAGE_MOVE event (see `placement-move.ts`).
-	 */
-	placementMoveService: PlacementMoveService;
-}
-
-/**
- * What body sync needs to set a message aside (issue #72). The mailbox facts
- * are supplied by the caller because they are properties of the round, not of
- * any one message.
- */
-export interface QuarantineConfig {
-	quarantineService: QuarantineService;
-	mailboxId: string;
-	/**
-	 * The mailbox's stored UIDVALIDITY. Taken from the mailbox row rather than
-	 * from the open box because a round whose two disagree is paused by the
-	 * cursor guard before it reaches any UID.
-	 */
-	uidValidity: number;
-	/** Redeliveries of this batch so far, so the record says how hard we tried. */
-	attempts: number;
-}
-
-/**
- * What body sync needs to auto-mark-read a message from an unsubscribed
- * sender (issue #302, RFC 039 Decision 3). Reuses the same
- * `FlagQueueService.markAsRead` a manual mark-as-read already goes through —
- * local `\Seen` + `ThreadMessage.isRead` + a durable pending IMAP flag-push
- * marker — so this fires the same round-trip, not a second primitive.
- */
-export interface UnsubscribeConfig {
-	flagQueueService: FlagQueueService;
-}
-
-/**
- * What body sync needs to offer a mail's invitation as a card (issue #1033).
- *
- * The calendar store is here to provision the account's default collection on
- * first use, through the one function every other caller provisions with. That
- * is not bookkeeping: an invitation whose DTSTART names no zone is RFC 5545
- * floating time, and reading it anywhere but where the user's calendar lives
- * shows the meeting at the wrong hour. Without a collection there is no zone
- * to read it in, and every such event silently lands in UTC.
- *
- * `filterService` is read to honour `dismiss{muteSender:true}`: a sender the
- * user muted gets no card at all.
- */
-export interface CalendarSuggestionConfig {
-	calendarSuggestionService: ICalendarSuggestionRepository;
-	calendarStore: ICalendarStore;
-	filterService: Pick<IFilterRepository, "listByAccountAndState">;
-}
-
-export class BodySyncService {
-	private log: BodySyncLogger;
-	private readonly filterPipeline?: FilterPipeline;
-
-	constructor(
-		private messageService: IMessageRepository,
-		private storageService: StorageService,
-		private threadMessageService: IThreadMessageRepository,
-		private addressService: IAddressRepository,
-		private envelopeService: IEnvelopeRepository,
-		private readonly syncWarningService: SyncWarningService,
-		logger?: BodySyncLogger,
-		private readonly placementConfig?: PlacementConfig,
-		private readonly filterConfig?: FilterConfig,
-		private readonly quarantineConfig?: QuarantineConfig,
-		private readonly unsubscribeConfig?: UnsubscribeConfig,
-		private readonly calendarConfig?: CalendarSuggestionConfig,
-	) {
-		this.log = logger ?? noopLogger;
-		this.filterPipeline = filterConfig
-			? new FilterPipeline(filterConfig, this.log)
-			: undefined;
-	}
-
-	async syncBodies(
-		messageIds: string[],
-		accountId: string,
-		accountConfigId: string,
-		folder: BodySyncRoundFolder,
-		getConnection: ConnectionGetter,
-		force = false,
-	): Promise<SyncBodiesResult> {
-		const syncedMessageIds: string[] = [];
-		const syncedUids: number[] = [];
-		let skippedCount = 0;
-		const location = {
-			accountId,
-			accountConfigId,
-			mailboxPath: folder.fullPath,
-		};
-
-		// Resolve every message up front so we can issue ONE ranged FETCH for the
-		// whole batch (the desktop-client pattern) instead of a SELECT + download
-		// per message. Messages whose body is already stored are skipped here and
-		// never hit the wire — UNLESS `force` is set, in which case every message
-		// is re-fetched regardless of `bodyStorageKey` (the read-miss cue already
-		// confirmed the stored object is gone). `pending` maps each UID to its
-		// messageId so we can match FETCH rows back and re-enqueue any UID the
-		// server never returns.
-		const pending = new Map<number, string>();
-		// Message IDs in this batch whose row already carried `bodyStorageKey`
-		// when `force` re-added them to `pending`: a forced re-fetch of an
-		// already-stored body is a re-store (issue #1011) — bytes only, no
-		// decision re-run. A message with no stored body inside a forced batch
-		// is still a first store and takes the full decision pass.
-		const reStoredMessageIds = new Set<string>();
-
-		// One read per round, not per message (issue #72). The list is small by
-		// design and almost always empty, so a lookup per message would put a
-		// query on the hot path for a state that is nearly never set.
-		const quarantined =
-			await this.quarantineConfig?.quarantineService.load(accountConfigId);
-
-		const rows = new Map(
-			(await this.messageService.get(messageIds)).map((row) => [
-				row.messageId,
-				row,
-			]),
-		);
-
-		for (const messageId of messageIds) {
-			const message = rows.get(messageId);
-
-			// A row deleted since the batch was cut, or moved out of this folder
-			// for good, has no uid here; its new uid would fetch another message.
-			if (!message || uidMailboxIdOf(message) !== folder.mailboxId) {
-				skippedCount++;
-				continue;
-			}
-
-			// A quarantined message has no stored body, so nothing else here would
-			// stop it being fetched and re-parsed on every redelivery, forever.
-			if (
-				this.quarantineConfig &&
-				quarantined?.has(
-					this.quarantineConfig.mailboxId,
-					this.quarantineConfig.uidValidity,
-					message.uid,
-				)
-			) {
-				this.log.debug?.(
-					{ messageId, uid: message.uid },
-					"Message is quarantined, skipping",
-				);
-				skippedCount++;
-				continue;
-			}
-
-			// The body is stored, so there is nothing to fetch (issue #331). This
-			// used to re-read those bytes from storage to re-derive a category,
-			// keyed on `category === uncategorized` — which is also the classifier's
-			// own "nothing to say", so a message it declined cost one storage read
-			// and two writes on every pass, forever, for the same answer. What the
-			// classifier did is now recorded as `classificationState`, so a sync
-			// pass never has to guess it from the row, and the cohort it has not
-			// reached is selectable by a backfill instead of re-derived here.
-			if (hasStoredBody(message.bodyStorageKey) && !force) {
-				this.log.debug?.({ messageId }, "Body already stored, skipping");
-				skippedCount++;
-				continue;
-			}
-			if (message.bodyStorageKey) reStoredMessageIds.add(messageId);
-			pending.set(message.uid, messageId);
-		}
-
-		if (pending.size === 0) {
-			return this.buildResult(syncedMessageIds, skippedCount, []);
-		}
-
-		const connection = await getConnection();
-		// Single SELECT for the whole batch. openBox is idempotent, so a warm
-		// connection already on this mailbox skips the SELECT entirely.
-		await connection.openBox(folder.fullPath);
-
-		let connectionLost = false;
-		try {
-			for await (const { uid, source } of connection.fetchMessageBodies([
-				...pending.keys(),
-			])) {
-				const messageId = pending.get(uid);
-				if (!messageId) {
-					// A UID we didn't ask for — drain the stream so the connection
-					// stays usable, then ignore it.
-					source.resume();
-					continue;
-				}
-				try {
-					await this.storeStreamedBody(
-						messageId,
-						accountId,
-						accountConfigId,
-						source,
-						folder.placement,
-						reStoredMessageIds.has(messageId),
-					);
-				} catch (error) {
-					// The one error in this frame that is the message's own fault. It
-					// reaches here from the parse call and nowhere else, so the S3, DB
-					// and queue work this same frame wraps cannot be mistaken for it.
-					// The row is durable before the UID leaves `pending`, so the
-					// message is never let go of unrecorded.
-					if (error instanceof BodyParseError && this.quarantineConfig) {
-						await this.recordQuarantine(
-							this.quarantineConfig,
-							messageId,
-							location,
-							error,
-						);
-						pending.delete(uid);
-						skippedCount++;
-						source.resume();
-						continue;
-					}
-
-					// Anything else is our own storage, database or queue failing. It
-					// aborts the batch, which redelivers whole; what stored skips.
-					throw error;
-				}
-				pending.delete(uid);
-				syncedMessageIds.push(messageId);
-				syncedUids.push(uid);
-			}
-		} catch (error) {
-			this.log.error?.(
-				{ error: (error as Error).message },
-				"Body fetch stream failed",
-			);
-			// Fail-fast: a dropped connection mid-stream leaves every not-yet-yielded
-			// UID in `pending`; they fall through to failedMessageIds and re-enqueue.
-			// Any other error is a real fault — let it crash.
-			if (!isConnectionDrop(error)) {
-				throw error;
-			}
-			connectionLost = true;
-			this.log.info?.(
-				{ remainingCount: pending.size },
-				"Connection lost, aborting batch",
-			);
-		}
-
-		// Anything still pending was never yielded (mid-stream drop or a UID the
-		// server silently omitted) — re-enqueue it.
-		const failedMessageIds = [...pending.values()];
-
-		await this.syncWarningService.settle(
-			{
-				accountConfigId,
-				accountId,
-				mailboxId: folder.mailboxId,
-				uidValidity: folder.uidValidity,
-			},
-			SyncWarningStage.Body,
-			{
-				failedUids: [...pending.keys()],
-				syncedUids,
-				serverUids: { kind: "Unlisted" },
-			},
-		);
-
-		this.log.info(
-			{
-				synced: syncedMessageIds.length,
-				skipped: skippedCount,
-				failed: failedMessageIds.length,
-				total: messageIds.length,
-				aborted: connectionLost,
-			},
-			"Body sync complete",
-		);
-
-		return this.buildResult(syncedMessageIds, skippedCount, failedMessageIds);
-	}
-
-	/**
-	 * Set a message aside because its body will not parse (issue #72). The
-	 * fingerprint comes from the BodyPart rows metadata sync already wrote: the
-	 * body path streams raw bytes and has no FETCH result to read.
-	 */
-	private async recordQuarantine(
-		config: QuarantineConfig,
-		messageId: string,
-		location: {
-			accountId: string;
-			accountConfigId: string;
-			mailboxPath: string;
-		},
-		error: BodyParseError,
-	): Promise<void> {
-		const message = await this.messageService.get(messageId);
-		const messageData = await this.envelopeService.getMessageData(messageId);
-		const threadMessage = await this.threadMessageService.findByMessageId(
-			location.accountConfigId,
-			messageId,
-		);
-
-		await config.quarantineService.record(
-			{
-				accountId: location.accountId,
-				accountConfigId: location.accountConfigId,
-				mailboxId: config.mailboxId,
-				mailboxPath: location.mailboxPath,
-				uidValidity: config.uidValidity,
-				attempts: config.attempts,
-			},
-			message.uid,
-			{
-				stage: QuarantineFailureStage.BodyParse,
-				code: error.failureCode,
-				message: error.message,
-			},
-			shapeFromMessageData(
-				message,
-				messageData,
-				threadMessage?.messageIdHeader,
-			),
-		);
-	}
-
-	private buildResult(
-		syncedMessageIds: string[],
-		skippedCount: number,
-		failedMessageIds: string[],
-	): SyncBodiesResult {
-		return {
-			syncedCount: syncedMessageIds.length,
-			syncedMessageIds,
-			skippedCount,
-			failedCount: failedMessageIds.length,
-			failedMessageIds,
-		};
-	}
-
-	/**
-	 * Stream one message body straight to storage while teeing the bytes into a
-	 * buffer for the parse-dependent steps (snippet, classification, parsed-body
-	 * cache, per-part objects). The S3 upload never sees a whole-body concat —
-	 * the storage service streams it — but mailparser still needs the full bytes,
-	 * so we collect them in parallel. Later issues move parsing off the hot path.
-	 *
-	 * `isReStore` marks a re-fetch of a message whose row already carried
-	 * `bodyStorageKey` (the `force` re-arm in {@link syncBodies}): the
-	 * post-store steps then re-materialize the body artifacts without
-	 * re-running any decision (issue #1011).
-	 */
-	private async storeStreamedBody(
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		source: Readable,
-		placement: FolderPlacement,
-		isReStore: boolean,
-	): Promise<void> {
-		const toStorage = new PassThrough();
-		const chunks: Buffer[] = [];
-
-		// Tee the source: bytes flow to storage as a stream (no whole-body concat
-		// on the upload path) while we also collect them for the parse-dependent
-		// steps below, which still need the full body for mailparser. The store
-		// and the tee are awaited together so neither rejection is orphaned.
-		const tee = new Promise<void>((resolve, reject) => {
-			source.on("data", (chunk: Buffer) => {
-				chunks.push(chunk);
-				toStorage.write(chunk);
-			});
-			source.on("end", () => {
-				toStorage.end();
-				resolve();
-			});
-			source.on("error", (err) => {
-				toStorage.destroy(err);
-				reject(err);
-			});
-		});
-
-		const [ref] = await Promise.all([
-			this.storageService.storeMessageBodyStream({
-				accountConfigId,
-				accountId,
-				messageId,
-				content: toStorage,
-			}),
-			tee,
-		]);
-
-		const body = Buffer.concat(chunks);
-
-		await this.applyPostStoreSteps(
-			messageId,
-			accountId,
-			accountConfigId,
-			body,
-			{
-				uri: ref.uri,
-			},
-			placement,
-			isReStore,
-		);
-	}
-
-	/**
-	 * The steps every synced body must go through regardless of which path
-	 * fetched it first — the sync path ({@link storeStreamedBody}) and the
-	 * read-path backfill ({@link fetchAndGetBody}) both call this instead of
-	 * duplicating (and drifting on) their own subset. Before issue #1271,
-	 * `fetchAndGetBody` skipped classification/placement entirely — a message
-	 * materialized by a read got different treatment than one synced in bulk.
-	 *
-	 * Order matters for two independent reasons, both load-bearing:
-	 * 1. The parsed-body cache must be durable before `bodyStorageKey` (the
-	 *    skip-guard signal) — see the comment on the write below.
-	 * 2. A placement move — local mailboxId change, pending marker, IMAP-push
-	 *    enqueue (`PlacementMoveService.moveMessage`, issue #1271) — must
-	 *    complete, or fully fail, BEFORE `bodyStorageKey` is written. That
-	 *    failure is never swallowed: if it throws, `bodyStorageKey` is not yet
-	 *    durable, so a retry reprocesses the message from scratch (marker
-	 *    included) instead of the skip-guard stranding a `movedByRemit` flag
-	 *    with no marker behind it — the defect this issue fixes.
-	 *
-	 * Returns the parsed mail so callers that already need it (both do) don't
-	 * pay for mailparser twice.
-	 */
-	private async applyPostStoreSteps(
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		body: Buffer,
-		bodyRef: { uri: string },
-		placement: FolderPlacement,
-		/**
-		 * Whether this call is a re-store of an already-classified message
-		 * rather than a first store. The two re-entrant paths (`force: true`
-		 * in `syncBodies`, and `fetchAndGetBody`'s `NoSuchKey` IMAP fallback) are
-		 * both body-only re-fetches: a body re-sync fetches and stores bytes and
-		 * runs no decision logic (issue #1011). When `isReStore` is true the
-		 * placement/filter/category machinery is skipped entirely and the
-		 * message's existing category is carried forward unchanged.
-		 */
-		isReStore: boolean,
-	): Promise<ParsedMail> {
-		// The one operation on this path that can fail because of how the message
-		// is built. Its own try block lives in `parseMessageBody`, so this frame —
-		// which also wraps the S3 body write, the parsed-body cache, the placement
-		// move, the label writes and the counter update — can tell the two apart
-		// and quarantine only this one (issue #72). The ThreadMessage write these
-		// feed happens later, alongside the Message write (see below), once the
-		// write-once category is decided.
-		const parsed = await parseMessageBody(body);
-
-		// Body-only re-fetch (issue #1011): the decision pass already ran when
-		// this message's body first landed, so a re-store re-materializes only
-		// the body-derived artifacts — parsed cache, body parts, the storage
-		// key — and re-decides nothing: no classification, placement, filters,
-		// labels, read state, and no second engagement-counter increment.
-		// Skipping the decisions here is what lets the write-once fields stay
-		// safe without per-derivation re-entrancy guards.
-		if (isReStore) {
-			// Same ordering rule as the first-store path below: the parsed-body
-			// cache must be durable before `bodyStorageKey` — the skip-guard
-			// signal — is written, so a failure here requeues the message and
-			// the retry genuinely re-attempts the artifact writes.
-			await this.storeParsedBodyCache(
-				accountConfigId,
-				accountId,
-				messageId,
-				parsed,
-			);
-			if (!isBodyPartDeferralEnabled()) {
-				await this.storeBodyPartContents(
-					accountConfigId,
-					accountId,
-					messageId,
-					await this.envelopeService.listBodyParts(messageId),
-					body,
-				);
-			}
-			await this.messageService.update(messageId, {
-				bodyStorageKey: bodyRef.uri,
-			});
-			this.log.info(
-				{ messageId, storageKey: bodyRef.uri },
-				"Body re-stored without re-running decisions",
-			);
-			return parsed;
-		}
-
-		const snippet = extractSnippet(parsed);
-		const listId = extractListId(parsed);
-
-		// Compute the header classification once, folding in the sender's
-		// `flags.category` override when one applies (issue #299). The derived
-		// fields are folded into the single Message update below — they are NOT
-		// written here.
-		const classification = await this.classifyMessage(
-			accountConfigId,
-			parsed,
-			placement,
-		);
-
-		// Decide the placement move from the in-memory classification before the
-		// write, so its `movedByRemit` flag and audit verdict join the same
-		// UpdateItem. The verdict is recorded whenever Remit decided to act
-		// (action != leave); the move is enqueued only for a confident,
-		// actionable verdict.
-		const resolved = await this.resolvePlacement(
-			messageId,
-			accountId,
-			accountConfigId,
-			parsed,
-			classification,
-		);
-
-		// Index-time filter pass (RFC 034). Isolated the same way placement is —
-		// FilterPipeline.evaluate swallows any read/decision failure and returns
-		// no actions, so a schema-drifted filter query never fails the body store.
-		// The DECISION is computed here; the applies below are unswallowed.
-		const filterDecision = await this.evaluateFilters(
-			accountConfigId,
-			accountId,
-			messageId,
-			parsed,
-		);
-
-		// Store the parsed-body cache BEFORE persisting bodyStorageKey. The skip
-		// guard in syncBodies treats a stored bodyStorageKey as "fully synced",
-		// so if we wrote it first and the parsed-cache write then failed, the
-		// requeued retry would skip the message — leaving parsedBody null forever.
-		// A parsed-cache failure here throws and propagates before bodyStorageKey
-		// is written, so the requeued message genuinely re-attempts the parsed
-		// write.
-		await this.storeParsedBodyCache(
-			accountConfigId,
-			accountId,
-			messageId,
-			parsed,
-		);
-
-		// Per-part S3 objects dominate S3 writes during bulk sync. When deferral
-		// is enabled we skip them here; they are materialized lazily on the first
-		// `contentUrl` read (see ensureBodyPartsStored), keeping bulk sync at 2
-		// writes/message (body.eml + parsed.json.gz).
-		if (!isBodyPartDeferralEnabled()) {
-			await this.storeBodyPartContents(
-				accountConfigId,
-				accountId,
-				messageId,
-				await this.envelopeService.listBodyParts(messageId),
-				body,
-			);
-		}
-
-		// Local-first move (issue #1271): local mailboxId change + pending marker +
-		// IMAP-push enqueue via PlacementMoveService, UNSWALLOWED — a throw here
-		// propagates before bodyStorageKey is written (see the method doc above),
-		// so a genuine SQS/DDB write failure requeues the message rather than being
-		// absorbed. A matched filter's move is exclusive and outranks the
-		// classifier's placement move (RFC 034 Decision 3.1) — an explicit user
-		// rule wins the single mailbox a message occupies — so at most one move is
-		// enqueued. A non-confident/leave verdict with no filter move is a no-op.
-		let filterMove: MessageFilterMove | undefined;
-		let filterMoved = false;
-		if (filterDecision.move) {
-			const destinationMailboxId = filterDecision.move.destinationMailboxId;
-			// Capture the source mailbox BEFORE the move rewrites mailboxId, so the
-			// auto-moved badge can name where the filter took the message from and
-			// offer an undo back to it (issue #223). Snapshotted into the marker
-			// rather than read from `originalMailboxId` at derive time, which a
-			// later user move would overwrite — the filter's source must survive an
-			// undo to stay derivable. A redelivery after a failed enqueue finds
-			// the move already applied locally, so the source is the folder the
-			// uid still names, not the one the row now points at.
-			const sourceMailboxId = uidMailboxIdOf(
-				await this.messageService.get(messageId),
-			);
-			const filed = await this.filterConfig?.placementMoveService.moveMessage(
-				accountConfigId,
-				messageId,
-				destinationMailboxId,
-				accountId,
-			);
-			// A filter matches by content, not location: a message delivered
-			// straight into the destination (a server-side rule) or already filed
-			// there matches but was not moved by Remit. `moveMessage` no-ops in that
-			// case; record neither the marker nor `movedByRemit`, so the badge never
-			// claims a move that did not happen and its Undo is never a no-op.
-			if (sourceMailboxId !== destinationMailboxId && filed !== "refused") {
-				filterMoved = true;
-				filterMove = {
-					filterId: filterDecision.move.filterId,
-					sourceMailboxId,
-					destinationMailboxId,
-					decidedAt: Date.now(),
-				};
-			}
-		} else if (resolved.move) {
-			await this.placementConfig?.placementMoveService.moveMessage(
-				accountConfigId,
-				messageId,
-				resolved.move.destinationMailboxId,
-				accountId,
-			);
-		}
-
-		// Additive label actions (RFC 034 Decision 3.1): every matching filter's
-		// label applies. The deterministic MessageLabel upsert is idempotent, so a
-		// requeue after a later failure re-applies safely; UNSWALLOWED, so a DDB
-		// write failure propagates before bodyStorageKey is written.
-		for (const label of filterDecision.labels) {
-			await this.filterConfig?.messageLabelService.apply({
-				messageId,
-				labelId: label.labelId,
-				accountConfigId,
-				appliedByFilterId: label.filterId,
-			});
-		}
-
-		// Read once for the two write-once guards below — the auto-read decision
-		// and the category carry-forward. Taken here rather than earlier because
-		// nothing between this point and the Message update writes either field;
-		// the moves above touch `mailboxId` only.
-		const existingMessage = await this.messageService.get(messageId);
-
-		// `flags.unsubscribed` (issue #302, RFC 039 Decision 3): auto-mark-read,
-		// reusing the same FlagQueueService.markAsRead round-trip a manual
-		// mark-as-read goes through — idempotent on a retry (flipFlag no-ops when
-		// the message is already \Seen), so a failure here safely re-fires on the
-		// next attempt rather than being lost behind the bodyStorageKey skip guard.
-		await this.applyUnsubscribedAutoRead(
-			messageId,
-			accountId,
-			accountConfigId,
-			parsed,
-			existingMessage.bodyStorageKey,
-		);
-
-		await this.deriveCalendarSuggestions(
-			messageId,
-			accountConfigId,
-			parsed,
-			existingMessage.bodyStorageKey,
-		);
-
-		const moved = Boolean(resolved.move || filterMoved);
-
-		// ONE Message UpdateItem per synced message: bodyStorageKey + every
-		// classification/derived field + the move flag + the audit verdict,
-		// collapsed into a single write.
-		// The flag is folded in only when a move WAS applied (by the classifier or
-		// a filter); the verdict is folded in whenever Remit decided to act.
-		// Written LAST so bodyStorageKey — the skip-guard signal — is only durable
-		// once the parsed cache AND the move (when any) are.
-		//
-		// `category` is RFC 034 D3.1's write-once field (RFC 030's message-list
-		// GSI sort key depends on it never churning). The re-entrant re-store
-		// paths (issue #1011) return before this write; the carry-forward keeps
-		// the field write-once even when a first store lands on a row that
-		// already carries a real category — a previously-decided category wins
-		// over the just-recomputed one. It likewise protects a `flags.category`
-		// override (issue #299): recomputing would let a *later* override silently
-		// rewrite a category already decided, which is exactly the churn RFC
-		// 030's GSI-safety argument forbids.
-		//
-		// `resolved.placementDecidedAt` (issue #383) is only ever present on
-		// the pass that first decided it: the re-store paths skip placement
-		// entirely (issue #1011), so `computePlacement` is reached only on a
-		// first store.
-		const finalCategory = hasDecidedCategory(existingMessage.category)
-			? existingMessage.category
-			: classification.category;
-
-		// Thread-list denormalization, using the same write-once category as the
-		// Message update below — the two rows must never disagree on category.
-		await denormalizeMessageCategory(
-			{ threadMessageService: this.threadMessageService },
-			accountConfigId,
-			messageId,
-			{ category: finalCategory, snippet, listId },
-		);
-
-		// `classificationState` records that the classifier ran, in the same
-		// UpdateItem as the answer it gave (issue #331). Without it `uncategorized`
-		// carries two meanings at once — not reached yet, and reached with nothing
-		// to say — and only one of them should ever be looked at again.
-		const update: UpdateMessageInput = {
-			bodyStorageKey: bodyRef.uri,
-			...classification,
-			category: finalCategory,
-			classificationState: MessageClassificationState.Examined,
-			...(moved ? { movedByRemit: true } : {}),
-			...(resolved.verdict ? { placementVerdict: resolved.verdict } : {}),
-			...(filterMove ? { filterMove } : {}),
-			...(resolved.placementDecidedAt
-				? { placementDecidedAt: resolved.placementDecidedAt }
-				: {}),
-		};
-		await this.messageService.update(messageId, update);
-		this.log.info({ messageId, storageKey: bodyRef.uri }, "Body stored");
-
-		// From-Address engagement counter (Address entity, not Message).
-		await this.incrementInboundCount(
-			messageId,
-			accountConfigId,
-			parsed,
-			classification,
-		);
-
-		return parsed;
-	}
-
-	/**
-	 * Fetch a single message body, store it, and return the parsed content.
-	 *
-	 * If the body is already stored, retrieves it from storage.
-	 * Otherwise fetches from IMAP, stores it, and returns the parsed content.
-	 *
-	 * @param messageId - The message ID to fetch
-	 * @param accountId - The account ID (for storage path)
-	 * @param accountConfigId - The account config ID (for thread updates)
-	 * @param folder - The IMAP mailbox path and its folder placement
-	 * @param getConnection - Function to get a (lazy) IMAP connection
-	 * @returns Parsed text and HTML content
-	 */
-	async fetchAndGetBody(
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		folder: BodySyncFolder,
-		getConnection: ConnectionGetter,
-	): Promise<FetchBodyResult> {
-		const message = await this.messageService.get(messageId);
-
-		let body: Buffer;
-		let needsStore = false;
-
-		if (message.bodyStorageKey) {
-			// Body already stored, try to retrieve from storage
-			this.log.debug?.({ messageId }, "Retrieving body from storage");
-			try {
-				body = await this.storageService.retrieve(message.bodyStorageKey);
-			} catch (err) {
-				// Only a genuinely-missing object (NoSuchKey) is a safe IMAP
-				// fallback — that's the cross-environment / never-stored case.
-				// A permission/infra error (AccessDenied, throttle) must NOT be
-				// masked as a missing object: let it crash so it's observable.
-				if (!isStorageNotFoundError(err)) {
-					this.log.error?.(
-						{
-							messageId,
-							storageKey: message.bodyStorageKey,
-							errorName: (err as { name?: string }).name,
-							errorCode: (err as { Code?: string }).Code,
-							error: inspect(err),
-						},
-						"Body storage retrieval failed (non-NoSuchKey); not falling back to IMAP",
-					);
-					throw err;
-				}
-				this.log.debug?.(
-					{ messageId, error: (err as Error).message },
-					"Body object missing (NoSuchKey), falling back to IMAP",
-				);
-				needsStore = true;
-				body = await this.fetchFromImap(
-					message,
-					accountId,
-					accountConfigId,
-					folder.fullPath,
-					getConnection,
-				);
-			}
-		} else {
-			// Fetch from IMAP and store
-			needsStore = true;
-			body = await this.fetchFromImap(
-				message,
-				accountId,
-				accountConfigId,
-				folder.fullPath,
-				getConnection,
-			);
-		}
-
-		let parsed: ParsedMail;
-
-		if (needsStore) {
-			const ref = await this.storageService.storeMessageBody({
-				accountConfigId,
-				accountId,
-				messageId,
-				content: body,
-			});
-
-			// Same shared step the sync path (storeStreamedBody) runs — issue
-			// #1271 unified the two body paths so classification/placement no
-			// longer depends on which one fetched the body first. A store from
-			// here is a re-store exactly when the row already claimed a stored
-			// body — the NoSuchKey fallback above; a row with no bodyStorageKey is
-			// a genuine first store and takes the full decision pass.
-			parsed = await this.applyPostStoreSteps(
-				messageId,
-				accountId,
-				accountConfigId,
-				body,
-				{ uri: ref.uri },
-				folder.placement,
-				message.bodyStorageKey != null,
-			);
-		} else {
-			parsed = await simpleParser(body);
-		}
-
-		return {
-			text: parsed.text ?? null,
-			html: typeof parsed.html === "string" ? parsed.html : null,
-			storedAt: message.bodyStorageKey ?? "newly-stored",
-		};
-	}
-
-	private async fetchFromImap(
-		message: MessageItem,
-		accountId: string,
-		accountConfigId: string,
-		mailboxPath: string,
-		getConnection: ConnectionGetter,
-	): Promise<Buffer> {
-		const { uid } = message;
-		this.log.debug?.({ uid }, "Fetching body from IMAP");
-		const connection = await getConnection();
-		await connection.openBox(mailboxPath);
-		const body = await connection.fetchMessageBody(uid);
-		if (body) return body;
-
-		if (!(await isMessageGoneFromOpenMailbox(connection, uid))) {
-			throw new Error(
-				`IMAP FETCH returned no source for UID ${uid} in ${mailboxPath}, which the server still lists`,
-			);
-		}
-
-		return this.reconcileGoneMessage(message, accountId, mailboxPath);
-	}
-
-	/**
-	 * The server no longer holds the message at the row's UID. A row with our
-	 * own move or delete in flight belongs to that mutation (409). A settled row
-	 * is removed with its thread entries, but only while its placement still
-	 * matches what was read (imap-mutations R3); losing that predicate is a 409
-	 * like any other lost placement transition.
-	 */
-	private async reconcileGoneMessage(
-		message: MessageItem,
-		accountId: string,
-		mailboxPath: string,
-	): Promise<never> {
-		const { messageId, uid } = message;
-		if (isPlacementUnsettled(message)) {
-			throw new MessagePlacementUnsettledError(
-				`Message ${messageId} is not at its UID while a move or delete is in flight`,
-				accountId,
-				messageId,
-				"in_flight",
-			);
-		}
-
-		const reconciled = await this.messageService.deleteIfPlacement(messageId, {
-			status: message.status,
-			mailboxId: message.mailboxId,
-			uid,
-		});
-
-		if (!reconciled) {
-			throw new MessagePlacementUnsettledError(
-				`Message ${messageId} changed placement while its absence from ${mailboxPath} was being reconciled`,
-				accountId,
-				messageId,
-				"in_flight",
-			);
-		}
-
-		this.log.info(
-			{
-				metric: "message_gone_stale_row_reconciled",
-				messageId,
-				uid,
-				mailboxPath,
-			},
-			"Message no longer on the mail server (expunged or moved by another client); stale row reconciled",
-		);
-		throw new MessageGoneFromServerError(messageId);
-	}
-
-	/**
-	 * Header classification, with the sender's `Address.flags.category`
-	 * override (issue #299, RFC 039 Decision 3) substituted for the
-	 * header-derived category when one is set. Shared with the classification
-	 * backfill (issue #1197) as {@link classifyParsedMessage}, so the one-time
-	 * pass and the body-store path can never classify the same bytes
-	 * differently.
-	 */
-	private async classifyMessage(
-		accountConfigId: string,
-		parsed: ParsedMail,
-		placement: FolderPlacement,
-	): Promise<UpdateMessageInput & { category: ThreadMessageCategory }> {
-		return classifyParsedMessage(
-			this.addressService,
-			accountConfigId,
-			parsed,
-			placement,
-		);
-	}
-
-	private async incrementInboundCount(
-		messageId: string,
-		accountConfigId: string,
-		parsed: ParsedMail,
-		classification: UpdateMessageInput,
-	): Promise<void> {
-		const fromEmail = extractPrimaryFromEmail(parsed);
-		if (!fromEmail) {
-			this.log.debug?.(
-				{ messageId },
-				"No From address; skipping inbound counter",
-			);
-			return;
-		}
-
-		const addressId = deriveAddressId(accountConfigId, fromEmail);
-		const bulk = isBulkSender(
-			classification.category,
-			classification.hasListUnsubscribe ?? false,
-		);
-		await this.addressService.incrementInboundCount(
-			accountConfigId,
-			addressId,
-			Date.now(),
-			bulk,
-		);
-	}
-
-	/**
-	 * The per-sender signals {@link computePlacement} needs, from ONE `Address`
-	 * fetch (RFC 039 Decision 3/3a, issue #300): the trust reads exactly as
-	 * `deriveSenderTrust` always did — `vip → wellknown → unknown`, untouched by
-	 * `blocked` — plus `blocked`/`autoArchive` off the same row. `trustSetAt` is
-	 * the `setAt` of whichever flag produced the trust value, needed by
-	 * {@link resolveSenderPlacement}'s tie-break; it stays local to placement and
-	 * never reaches `deriveSenderTrust`'s own contract (the trust badge).
-	 */
-	private async deriveSenderPlacementSignals(
-		accountConfigId: string,
-		fromEmail: string,
-	): Promise<{
-		trust: (typeof SenderTrust)[keyof typeof SenderTrust];
-		trustSetAt?: number;
-		blocked: boolean;
-		blockedSetAt?: number;
-		neverSpam: boolean;
-		autoArchive: boolean;
-	}> {
-		const unknown = {
-			trust: SenderTrust.Unknown,
-			blocked: false,
-			neverSpam: false,
-			autoArchive: false,
-		} as const;
-		try {
-			const addressId = deriveAddressId(accountConfigId, fromEmail);
-			const address = await this.addressService.getAddress(
-				accountConfigId,
-				addressId,
-			);
-			const flags = address.flags;
-			if (flags?.vip?.value === true) {
-				return {
-					trust: SenderTrust.Vip,
-					trustSetAt: flags.vip.setAt,
-					blocked: flags.blocked?.value === true,
-					blockedSetAt: flags.blocked?.setAt,
-					neverSpam: flags.neverSpam?.value === true,
-					autoArchive: flags.autoArchive?.value === true,
-				};
-			}
-			if (flags?.wellknown?.value === true) {
-				return {
-					trust: SenderTrust.Wellknown,
-					trustSetAt: flags.wellknown.setAt,
-					blocked: flags.blocked?.value === true,
-					blockedSetAt: flags.blocked?.setAt,
-					neverSpam: flags.neverSpam?.value === true,
-					autoArchive: flags.autoArchive?.value === true,
-				};
-			}
-			return {
-				...unknown,
-				blocked: flags?.blocked?.value === true,
-				blockedSetAt: flags?.blocked?.setAt,
-				neverSpam: flags?.neverSpam?.value === true,
-				autoArchive: flags?.autoArchive?.value === true,
-			};
-		} catch (err) {
-			// A genuinely-absent address means "no signals". Any other failure
-			// (AccessDenied, throttle, infra) must NOT be silently downgraded — let
-			// it crash so the placement decision isn't made on bad data.
-			if (!(err instanceof NotFoundError)) throw err;
-		}
-		return unknown;
-	}
-
-	/**
-	 * `flags.unsubscribed` (issue #302, RFC 039 Decision 3): "auto-mark-read
-	 * until sender stops" — fires on every new message from that sender for as
-	 * long as the flag stays set, per the flag's own doc comment; there is no
-	 * separate expiry mechanism, and no caching of the decision beyond this
-	 * per-message `Address` read. A no-op when body sync was built without an
-	 * {@link UnsubscribeConfig} or the message carries no `From` address.
-	 *
-	 * Write-once per message (issue #499), like the `category` and placement
-	 * derivations alongside it: read state is applied on the pass that first
-	 * classifies a message and never re-decided. A user who marks such a message
-	 * unread afterwards owns it — a re-entrant pass over an already-classified
-	 * body would otherwise silently undo that.
-	 */
-	private async applyUnsubscribedAutoRead(
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		parsed: ParsedMail,
-		storedBodyKey: string | undefined,
-	): Promise<void> {
-		if (!this.unsubscribeConfig) return;
-		if (hasStoredBody(storedBodyKey)) return;
-
-		const fromEmail = extractPrimaryFromEmail(parsed);
-		if (!fromEmail) return;
-
-		const unsubscribed = await this.deriveSenderUnsubscribed(
-			accountConfigId,
-			fromEmail,
-		);
-		if (!unsubscribed) return;
-
-		await this.unsubscribeConfig.flagQueueService.markAsRead(
-			accountConfigId,
-			messageId,
-			accountId,
-		);
-	}
-
-	/**
-	 * Offer what a message's `text/calendar` parts propose, as cards beside the
-	 * message (issue #1033). Nothing here reaches a calendar: a suggestion is
-	 * written `Pending` and waits for a person, and a `METHOD:CANCEL` is a card
-	 * of its own rather than a withdrawal of an event the user added.
-	 *
-	 * Write-once per message, like the `category`, placement and read-state
-	 * derivations alongside it (issues #499, #1011): a card is offered on the
-	 * pass that first classifies a message — the same moment the account's
-	 * filters run — and never again. The two re-entrant paths a forced body
-	 * re-sync goes through (`fetchAndGetBody`'s `NoSuchKey` fallback,
-	 * `syncBodies(..., force: true)`) reach this with `bodyStorageKey` already
-	 * set, and re-offering there would resurrect a card the user dismissed.
-	 *
-	 * Isolated the same way placement and filters are: a card is auxiliary to
-	 * storing the mail, which is already durable by the time this runs. A
-	 * repository failure here is logged loudly with the messageId rather than
-	 * failing a body store that otherwise succeeded.
-	 */
-	private async deriveCalendarSuggestions(
-		messageId: string,
-		accountConfigId: string,
-		parsed: ParsedMail,
-		storedBodyKey: string | undefined,
-	): Promise<void> {
-		if (!this.calendarConfig) return;
-		if (hasStoredBody(storedBodyKey)) return;
-
-		const parts = calendarParts(parsed);
-		if (parts.length === 0) return;
-
-		const { calendarStore, calendarSuggestionService, filterService } =
-			this.calendarConfig;
-
-		await Promise.resolve()
-			.then(async () => {
-				// `dismiss{muteSender:true}` wrote a standing rule naming this
-				// sender. Honouring it here is what makes that button do anything:
-				// the index-time filter pipeline skips a rule with no label and no
-				// move, so this is the only reader such a rule has.
-				const sender = extractPrimaryFromEmail(parsed);
-				if (sender) {
-					const active = await filterService.listByAccountAndState(
-						accountConfigId,
-						FilterState.Active,
-					);
-					if (isSenderMuted(active, sender)) {
-						this.log.debug?.(
-							{ messageId, sender },
-							"Sender is muted; offering no calendar suggestion",
-						);
-						return;
-					}
-				}
-
-				// Provisioned rather than looked up, through the one function every
-				// caller provisions with. A missing collection has no timezone, and
-				// a floating DTSTART read in UTC puts the meeting hours from where
-				// the organizer meant it. Idempotent: the id is derived, so a second
-				// first use returns the collection the first one made.
-				const collection = await provisionDefaultCalendar(
-					calendarStore,
-					accountConfigId,
-				);
-				for (const part of parts) {
-					const recorded = await recordCalendarSuggestion(
-						calendarSuggestionService,
-						{
-							accountConfigId,
-							messageId,
-							bodyPartId: deriveBodyPartId(messageId, part.partPath),
-							source: part.source,
-							icalData: part.icalData,
-							timezone: collection.timezone,
-						},
-					);
-					if (!recorded.ok) {
-						this.log.info(
-							{
-								messageId,
-								partPath: part.partPath,
-								code: recorded.error.code,
-								reason: recorded.error.message,
-							},
-							"Message carries iCalendar this cannot read; no suggestion offered",
-						);
-					}
-				}
-			})
-			.catch((error: unknown) => {
-				this.log.error?.(
-					{ messageId, accountConfigId, error: inspect(error) },
-					"Calendar suggestion derivation failed; body is stored without a card",
-				);
-			});
-	}
-
-	private async deriveSenderUnsubscribed(
-		accountConfigId: string,
-		fromEmail: string,
-	): Promise<boolean> {
-		try {
-			const addressId = deriveAddressId(accountConfigId, fromEmail);
-			const address = await this.addressService.getAddress(
-				accountConfigId,
-				addressId,
-			);
-			return address.flags?.unsubscribed?.value === true;
-		} catch (err) {
-			// A genuinely-absent address means "not unsubscribed". Any other
-			// failure (AccessDenied, throttle, infra) must NOT be silently
-			// downgraded — let it crash so the read-state decision isn't made on
-			// bad data.
-			if (!(err instanceof NotFoundError)) throw err;
-			return false;
-		}
-	}
-
-	/**
-	 * Evaluate the account's active filters against a synced message (RFC 034),
-	 * BEFORE the single Message update — so a filter's `movedByRemit` flag joins
-	 * that same UpdateItem. Returns the actions to apply (labels + at most one
-	 * move); the caller applies them. A no-op returning no actions when no
-	 * {@link FilterConfig} is wired.
-	 *
-	 * Isolation lives in {@link FilterPipeline.evaluate}: this read/decision phase
-	 * never fails the body store (the #1246 placement precedent). The applies of
-	 * the returned decision are the caller's and are deliberately unswallowed.
-	 */
-	private async evaluateFilters(
-		accountConfigId: string,
-		accountId: string,
-		messageId: string,
-		parsed: ParsedMail,
-	): Promise<FilterDecision> {
-		if (!this.filterPipeline) return { labels: [] };
-		return this.filterPipeline.evaluate(
-			accountConfigId,
-			accountId,
-			messageId,
-			toFilterMessage(parsed),
-		);
-	}
-
-	/**
-	 * Resolve the placement decision for a message, BEFORE the single Message
-	 * update — so both the `movedByRemit` flag and the audit verdict join that
-	 * one UpdateItem instead of a second mutation. Drives both directions (junk → inbox rescue,
-	 * inbox → junk demote) off the pure {@link classifyPlacement} verdict.
-	 *
-	 * Returns a {@link PlacementOutcome}: a `verdict` to persist whenever Remit
-	 * decided to act (action != leave), confident and unsure alike, so the
-	 * distribution is queryable on the message; a `move` to enqueue only for a
-	 * confident verdict; and `placementDecidedAt` whenever a verdict — including
-	 * "leave" — was genuinely computed (issue #383), so a re-entrant call short-
-	 * circuits instead of re-deciding a placement the user may have since
-	 * overridden by hand.
-	 *
-	 * Always logs a structured verdict line for confident, actionable verdicts so
-	 * the real distribution is observable on a live mailbox.
-	 *
-	 * The verdict reads the just-computed classification rather than a persisted
-	 * row, since those fields are not written until the single update. Placement
-	 * is auxiliary to the body store — the primary artifact (body.eml) is already
-	 * durable by the time this runs — so a failure here (e.g. a placement-repo
-	 * query erroring on a schema-drifted DB) is caught and logged loudly with an
-	 * alertable field instead of failing the surrounding message store. The empty
-	 * {@link PlacementOutcome} means "no action", whether Remit genuinely decided
-	 * to leave the message alone or placement itself failed; the alert log is
-	 * what distinguishes the latter, and neither case marks the message decided.
-	 */
-	private async resolvePlacement(
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		parsed: ParsedMail,
-		classification: UpdateMessageInput,
-	): Promise<PlacementOutcome> {
-		if (!this.placementConfig) return {};
-		return this.computePlacement(
-			this.placementConfig,
-			messageId,
-			accountId,
-			accountConfigId,
-			parsed,
-			classification,
-		).catch((error: unknown) => {
-			this.log.error?.(
-				{
-					alert: "body_sync_placement_failed",
-					messageId,
-					accountId,
-					accountConfigId,
-					errorName: (error as { name?: string })?.name,
-					error: inspect(error),
-				},
-				"Placement resolution failed; body already stored, continuing without placement (best-effort, non-fatal)",
-			);
-			return {};
-		});
-	}
-
-	private async computePlacement(
-		placementConfig: PlacementConfig,
-		messageId: string,
-		accountId: string,
-		accountConfigId: string,
-		parsed: ParsedMail,
-		classification: UpdateMessageInput,
-	): Promise<PlacementOutcome> {
-		const { mailboxSpecialUseService } = placementConfig;
-
-		const message = await this.messageService.get(messageId);
-
-		// Issue #383 / #1011: placement still runs once per message (RFC 039
-		// Non-goals), but the once-per-message guarantee now comes from the
-		// caller rather than a guard here — the re-store paths
-		// (`fetchAndGetBody`'s `NoSuchKey` fallback, `syncBodies(..., force:
-		// true)`) skip the decision steps entirely, so only the pass that first
-		// stores a body ever reaches this method.
-
-		const roleMailboxes = await resolveFolderRoleMailboxes(
-			mailboxSpecialUseService,
-			accountId,
-		);
-		const { junkMailbox, inboxMailbox } = roleMailboxes;
-		const placement = placementOf(message.mailboxId, roleMailboxes);
-
-		const fromEmail = extractPrimaryFromEmail(parsed);
-		const signals = fromEmail
-			? await this.deriveSenderPlacementSignals(accountConfigId, fromEmail)
-			: {
-					trust: SenderTrust.Unknown,
-					blocked: false,
-					neverSpam: false,
-					autoArchive: false,
-				};
-
-		const { senderTrust, senderOverride } = resolveSenderPlacement(
-			{ trust: signals.trust, setAt: signals.trustSetAt },
-			{ blocked: signals.blocked, setAt: signals.blockedSetAt },
-			signals.neverSpam,
-		);
-
-		// The verdict needs the classification signals (providerSpam,
-		// authResult, authenticity) that this body-sync pass just derived; the
-		// stored row does not carry them yet, so overlay them onto the message.
-		const candidate = { ...message, ...classification };
-		const verdict = classifyPlacement(
-			candidate,
-			placement,
-			senderTrust,
-			senderOverride,
-		);
-
-		// A `leave` verdict — including "nothing confident to say" — carries no
-		// audit record of its own. `flags.autoArchive` (issue #300) is a distinct,
-		// lower-priority filing preference: it only files a message away when
-		// `blocked`/DKIM/DMARC had nothing to say, never overriding a confident
-		// junk/inbox verdict computed above. Still marked decided (issue #383):
-		// "leave" is itself a verdict, not "not yet evaluated".
-		if (verdict.action === "leave") {
-			const outcome = autoArchiveApplies(verdict, placement)
-				? await this.resolveAutoArchive(
-						mailboxSpecialUseService,
-						message,
-						accountId,
-						signals.autoArchive,
-					)
-				: {};
-			return { ...outcome, placementDecidedAt: Date.now() };
-		}
-
-		// Audit verdict — recorded for every actionable verdict (both
-		// confidences), so the distribution is queryable on the message.
-		// Independent of whether a move is enqueued.
-		const audit: MessagePlacementVerdict = {
-			action:
-				verdict.action === "move-to-inbox"
-					? PlacementAction.MoveToInbox
-					: PlacementAction.MoveToJunk,
-			confidence:
-				verdict.confidence === "confident"
-					? PlacementConfidence.Confident
-					: PlacementConfidence.Unsure,
-			fromPlacement: placement,
-			reasons: verdict.reasons,
-			dryRun: false,
-			decidedAt: Date.now(),
-		};
-
-		// Only a confident verdict moves mail. An unsure verdict is recorded
-		// but never enqueues a move.
-		if (verdict.confidence !== "confident") {
-			return { verdict: audit, placementDecidedAt: audit.decidedAt };
-		}
-
-		const target =
-			verdict.action === "move-to-inbox" ? inboxMailbox : junkMailbox;
-		if (!target) return { verdict: audit, placementDecidedAt: audit.decidedAt };
-
-		// Structured verdict line — emitted for confident, actionable verdicts
-		// so the real verdict distribution is observable on a live mailbox.
-		this.log.info(
-			{
-				messageId,
-				accountId,
-				placement,
-				action: verdict.action,
-				confidence: verdict.confidence,
-				reasons: verdict.reasons,
-				destinationMailboxId: target.mailboxId,
-			},
-			"Placement verdict",
-		);
-
-		return {
-			verdict: audit,
-			move: {
-				destinationMailboxId: target.mailboxId,
-				destinationPath: target.fullPath,
-			},
-			placementDecidedAt: audit.decidedAt,
-		};
-	}
-
-	/**
-	 * `flags.autoArchive` (issue #300, RFC 039 Decision 3): file a message
-	 * straight to Archive, skipping Inbox. Only reached from
-	 * {@link computePlacement} when {@link classifyPlacement} had no confident
-	 * junk/inbox verdict of its own — `blocked`/DKIM/DMARC always take priority
-	 * over this filing preference — and only for the `leave` verdicts
-	 * {@link autoArchiveApplies} admits.
-	 *
-	 * No {@link MessagePlacementVerdict} is recorded: `PlacementAction` (the
-	 * audit enum) has only `MoveToInbox`/`MoveToJunk` — issue #300 is scoped to
-	 * no TypeSpec change, so an archive move carries no audit verdict, same as
-	 * a matched filter's move. The move itself reuses the same
-	 * `placementMoveService.moveMessage` path as every other confident move.
-	 *
-	 * Idempotent the same way {@link classifyPlacement}'s own branches are: a
-	 * message already sitting in Archive is left alone, not moved again.
-	 */
-	private async resolveAutoArchive(
-		mailboxSpecialUseService: IMailboxSpecialUseRepository,
-		message: MessageItem,
-		accountId: string,
-		autoArchive: boolean,
-	): Promise<PlacementOutcome> {
-		if (!autoArchive) return {};
-
-		const archiveMailbox =
-			await mailboxSpecialUseService.findArchiveMailbox(accountId);
-		if (!archiveMailbox || message.mailboxId === archiveMailbox.mailboxId) {
-			return {};
-		}
-
-		this.log.info(
-			{
-				messageId: message.messageId,
-				accountId,
-				destinationMailboxId: archiveMailbox.mailboxId,
-			},
-			"Auto-archive verdict",
-		);
-
-		return {
-			move: {
-				destinationMailboxId: archiveMailbox.mailboxId,
-				destinationPath: archiveMailbox.fullPath,
-			},
-		};
-	}
-
-	// The old `enqueuePlacementMove` (best-effort, catch-and-log) lived here.
-	// Issue #1271: it ran AFTER `bodyStorageKey` was already durable, so a
-	// failure was swallowed to avoid stranding the message behind the
-	// body-sync skip guard — but that meant `movedByRemit` could be true with
-	// no record the move ever reached IMAP. Replaced by the unswallowed call
-	// inside `applyPostStoreSteps`, sequenced BEFORE `bodyStorageKey` is
-	// written, backed by `PlacementMoveService`'s pending-move marker.
-
-	/**
-	 * Persist one S3 object per non-multipart leaf so the SPA can resolve
-	 * `BodyPartResponse.contentUrl` (#298). Keys follow the layout
-	 * `accounts/{accountConfigId}/{accountId}/messages/{messageId}/parts/{partPath}`
-	 * so they line up with the URL shape `derive/contentUrl.ts` emits.
-	 *
-	 * The mapper is total (#395 PR B): every leaf gets a `BodyPartContentPair`,
-	 * possibly with a zero-byte content for leaves that have no source bytes
-	 * (genuinely empty parts, or pathological inputs the positional fallback
-	 * couldn't pair). No try/catch is needed; the only failure surface here is
-	 * an S3 write itself, which `pMap` surfaces directly.
-	 *
-	 * If `listBodyParts` returns an empty list (e.g. a legacy message synced
-	 * before #133 populated BodyPart rows), this is a no-op.
-	 */
-	private async storeBodyPartContents(
-		accountConfigId: string,
-		accountId: string,
-		messageId: string,
-		bodyParts: readonly BodyPartItem[],
-		body: Buffer,
-		options?: { skipExisting?: boolean },
-	): Promise<StoreBodyPartContentsResult> {
-		if (bodyParts.length === 0) {
-			this.log.debug?.(
-				{ messageId },
-				"No BodyPart rows; skipping per-part storage",
-			);
-			return { stored: 0 };
-		}
-
-		const log = this.log;
-		// A parse of its own: classification and the snippet, which search reads,
-		// need an inline forwarded message's text, which `ignoreEmbedded` keeps out.
-		const pairs = await mapMessagePartsToContent(
-			bodyParts,
-			await parsePartSource(body),
-			{
-				messageId,
-				logger:
-					log.warn || log.debug
-						? {
-								warn: (obj, msg) => {
-									log.warn?.(obj, msg);
-								},
-								debug: (obj, msg) => {
-									log.debug?.(obj, msg);
-								},
-							}
-						: undefined,
-			},
-		);
-
-		if (pairs.length === 0) {
-			return { stored: 0 };
-		}
-
-		let stored = 0;
-		await pMap(
-			pairs,
-			async (entry) => {
-				if (
-					options?.skipExisting &&
-					(await this.storageService.bodyPartExists(
-						accountConfigId,
-						accountId,
-						messageId,
-						entry.partPath,
-					))
-				) {
-					return;
-				}
-				await this.storageService.storeBodyPart({
-					accountConfigId,
-					accountId,
-					messageId,
-					partPath: entry.partPath,
-					content: entry.content,
-					contentType: entry.contentType,
-				});
-				stored++;
-			},
-			{ concurrency: BODY_PART_STORE_CONCURRENCY },
-		);
-
-		this.log.info(
-			{ messageId, partCount: pairs.length, stored },
-			"Body parts stored",
-		);
-
-		return { stored };
-	}
-
-	/**
-	 * Lazily materialize the per-part S3 objects for an already-synced message
-	 * whose parts were deferred during bulk sync (DEFER_BODY_PARTS).
-	 *
-	 * Called from the read path (the API `describeMessage` handler) before the
-	 * SPA fetches any `contentUrl`: the part bytes are served directly from S3 by
-	 * CloudFront with no Lambda in the request path, so a missing object would
-	 * surface to the SPA as a hard "body-missing" failure. Generating the parts
-	 * here — re-parsing the stored `body.eml` with the same `mapBodyPartsToContent`
-	 * logic body-sync uses — guarantees every `contentUrl` resolves, while bulk
-	 * sync stays at 2 writes/message.
-	 *
-	 * Idempotent: skips any leaf already on S3, so repeat reads cost only HEAD
-	 * checks, and a re-read after a partial failure fills the gaps. Requires the
-	 * message body to be stored (`bodyStorageKey`); callers gate on that.
-	 *
-	 * Warm-open fast path: a single HEAD on the `.materialized` sentinel
-	 * short-circuits the whole pass — no body.eml GET, no MIME re-parse, no
-	 * per-leaf HEADs. The sentinel is written only after every leaf is confirmed
-	 * stored, so its presence guarantees all `contentUrl`s resolve.
-	 */
-	async ensureBodyPartsStored(
-		accountConfigId: string,
-		accountId: string,
-		messageId: string,
-		bodyStorageKey: string,
-	): Promise<StoreBodyPartContentsResult> {
-		const bodyParts = await this.envelopeService.listBodyParts(messageId);
-		const carriesMessage = bodyParts.some(isEncapsulatedMessage);
-		const sentinel = carriesMessage
-			? MATERIALIZED_SENTINEL_V2_PART_PATH
-			: MATERIALIZED_SENTINEL_PART_PATH;
-		if (
-			await this.storageService.bodyPartExists(
-				accountConfigId,
-				accountId,
-				messageId,
-				sentinel,
-			)
-		) {
-			this.log.debug?.(
-				{ messageId },
-				"Body parts already materialized (sentinel hit); skipping",
-			);
-			return { stored: 0 };
-		}
-
-		const body = await this.storageService.retrieve(bodyStorageKey);
-		const result = await this.storeBodyPartContents(
-			accountConfigId,
-			accountId,
-			messageId,
-			bodyParts,
-			body,
-			{ skipExisting: !carriesMessage },
-		);
-
-		// Reaching here means storeBodyPartContents resolved — `pMap` rejects on
-		// any single failed write, so every leaf is now durably on S3. Drop the
-		// sentinel so subsequent opens take the HEAD-only fast path above.
-		await this.storageService.storeBodyPart({
-			accountConfigId,
-			accountId,
-			messageId,
-			partPath: sentinel,
-			content: Buffer.alloc(0),
-		});
-
-		return result;
-	}
-
-	private async storeParsedBodyCache(
-		accountConfigId: string,
-		accountId: string,
-		messageId: string,
-		parsed: ParsedMail,
-	): Promise<void> {
-		await this.storageService.storeParsedBody({
-			accountConfigId,
-			accountId,
-			messageId,
-			parsed: toParsedBody(parsed),
-		});
-	}
-}