@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/body-sync.js

@@ -0,0 +1,1204 @@
+import { PassThrough } from "node:stream";
+import { inspect } from "node:util";
+import { provisionDefaultCalendar, recordCalendarSuggestion, } from "@remit/calendar-service";
+import { isSenderMuted, } 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, } from "@remit/storage-service";
+import { 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 { FilterPipeline, } from "./filters/pipeline.js";
+import { placementOf, resolveFolderRoleMailboxes } from "./folder-placement.js";
+import { classifyPlacement, resolveSenderPlacement, } from "./heuristics/classifyPlacement.js";
+import { denormalizeMessageCategory, hasDecidedCategory, } from "./message-category.js";
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+import { isPlacementUnsettled, uidMailboxIdOf } from "./placement-settled.js";
+import { shapeFromMessageData } from "./quarantine.js";
+import { extractSearchText, extractSnippetFromEmail } from "./snippet.js";
+import { MailConnectionError } from "./types.js";
+const BODY_PART_STORE_CONCURRENCY = 4;
+/**
+ * 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 = () => {
+    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) => {
+    if (error instanceof MailConnectionError) {
+        return error.kind === "network";
+    }
+    const code = error.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) => ({
+    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) => 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) => 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, placement) => placement !== "junk" && !verdict.reasons.includes("already-moved-by-remit");
+export const toParsedBody = (parsed) => ({
+    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,
+    })),
+});
+const noopLogger = {
+    info: () => { },
+};
+export class BodySyncService {
+    messageService;
+    storageService;
+    threadMessageService;
+    addressService;
+    envelopeService;
+    syncWarningService;
+    placementConfig;
+    filterConfig;
+    quarantineConfig;
+    unsubscribeConfig;
+    calendarConfig;
+    log;
+    filterPipeline;
+    constructor(messageService, storageService, threadMessageService, addressService, envelopeService, syncWarningService, logger, placementConfig, filterConfig, quarantineConfig, unsubscribeConfig, calendarConfig) {
+        this.messageService = messageService;
+        this.storageService = storageService;
+        this.threadMessageService = threadMessageService;
+        this.addressService = addressService;
+        this.envelopeService = envelopeService;
+        this.syncWarningService = syncWarningService;
+        this.placementConfig = placementConfig;
+        this.filterConfig = filterConfig;
+        this.quarantineConfig = quarantineConfig;
+        this.unsubscribeConfig = unsubscribeConfig;
+        this.calendarConfig = calendarConfig;
+        this.log = logger ?? noopLogger;
+        this.filterPipeline = filterConfig
+            ? new FilterPipeline(filterConfig, this.log)
+            : undefined;
+    }
+    async syncBodies(messageIds, accountId, accountConfigId, folder, getConnection, force = false) {
+        const syncedMessageIds = [];
+        const syncedUids = [];
+        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();
+        // 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();
+        // 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.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.
+     */
+    async recordQuarantine(config, messageId, location, error) {
+        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));
+    }
+    buildResult(syncedMessageIds, skippedCount, failedMessageIds) {
+        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).
+     */
+    async storeStreamedBody(messageId, accountId, accountConfigId, source, placement, isReStore) {
+        const toStorage = new PassThrough();
+        const chunks = [];
+        // 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((resolve, reject) => {
+            source.on("data", (chunk) => {
+                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.
+     */
+    async applyPostStoreSteps(messageId, accountId, accountConfigId, body, bodyRef, placement, 
+    /**
+     * 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) {
+        // 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);
+        await this.messageService.setSearchText(messageId, extractSearchText(parsed));
+        // 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) {
+            await this.messageService.syncSearch([messageId]);
+            // 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;
+        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 = {
+            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, accountId, accountConfigId, folder, getConnection) {
+        const message = await this.messageService.get(messageId);
+        let body;
+        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.name,
+                        errorCode: err.Code,
+                        error: inspect(err),
+                    }, "Body storage retrieval failed (non-NoSuchKey); not falling back to IMAP");
+                    throw err;
+                }
+                this.log.debug?.({ messageId, error: err.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;
+        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",
+        };
+    }
+    async fetchFromImap(message, accountId, accountConfigId, mailboxPath, getConnection) {
+        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.
+     */
+    async reconcileGoneMessage(message, accountId, mailboxPath) {
+        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.
+     */
+    async classifyMessage(accountConfigId, parsed, placement) {
+        return classifyParsedMessage(this.addressService, accountConfigId, parsed, placement);
+    }
+    async incrementInboundCount(messageId, accountConfigId, parsed, classification) {
+        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).
+     */
+    async deriveSenderPlacementSignals(accountConfigId, fromEmail) {
+        const unknown = {
+            trust: SenderTrust.Unknown,
+            blocked: false,
+            neverSpam: false,
+            autoArchive: false,
+        };
+        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.
+     */
+    async applyUnsubscribedAutoRead(messageId, accountId, accountConfigId, parsed, storedBodyKey) {
+        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.
+     */
+    async deriveCalendarSuggestions(messageId, accountConfigId, parsed, storedBodyKey) {
+        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) => {
+            this.log.error?.({ messageId, accountConfigId, error: inspect(error) }, "Calendar suggestion derivation failed; body is stored without a card");
+        });
+    }
+    async deriveSenderUnsubscribed(accountConfigId, fromEmail) {
+        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.
+     */
+    async evaluateFilters(accountConfigId, accountId, messageId, parsed) {
+        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.
+     */
+    async resolvePlacement(messageId, accountId, accountConfigId, parsed, classification) {
+        if (!this.placementConfig)
+            return {};
+        return this.computePlacement(this.placementConfig, messageId, accountId, accountConfigId, parsed, classification).catch((error) => {
+            this.log.error?.({
+                alert: "body_sync_placement_failed",
+                messageId,
+                accountId,
+                accountConfigId,
+                errorName: error?.name,
+                error: inspect(error),
+            }, "Placement resolution failed; body already stored, continuing without placement (best-effort, non-fatal)");
+            return {};
+        });
+    }
+    async computePlacement(placementConfig, messageId, accountId, accountConfigId, parsed, classification) {
+        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 = {
+            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.
+     */
+    async resolveAutoArchive(mailboxSpecialUseService, message, accountId, autoArchive) {
+        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.
+     */
+    async storeBodyPartContents(accountConfigId, accountId, messageId, bodyParts, body, options) {
+        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, accountId, messageId, bodyStorageKey) {
+        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;
+    }
+    async storeParsedBodyCache(accountConfigId, accountId, messageId, parsed) {
+        await this.storageService.storeParsedBody({
+            accountConfigId,
+            accountId,
+            messageId,
+            parsed: toParsedBody(parsed),
+        });
+    }
+}