@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/restore-source-placement.js

@@ -0,0 +1,79 @@
+import { isNotFoundError } from "@remit/data-ports/errors";
+import { MessageStatus } from "@remit/domain-enums";
+import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+/**
+ * Put a row back on the pre-mutation source pair and hand its listing rows back
+ * with it.
+ *
+ * `status: moving` has to be cleared here or the row is stuck: a give-up that
+ * writes a sync status and returns leaves the row naming the destination with
+ * the source's uid — the pair `placementBindingOf` calls a lie and
+ * `MessagePlacementUnsettledError` refuses to act on. Nothing routine repairs it
+ * (sync does not touch `status`, and the cursor rebuild's `updateUid` runs only
+ * on a UIDVALIDITY change), so the message is undeletable and unmovable for good
+ * (issue #1005).
+ *
+ * A transition, not a plain update (imap-mutations R3): the restore is only
+ * owed while a mutation is still outstanding on the row, so the predicate is
+ * `moving` or `deleting`. A row another lane has already settled — the
+ * placement-move push runs off a standard queue and is ordered against nothing
+ * on the account's FIFO — is the winner, and dragging it back to a source it
+ * has since left is the corruption this predicate exists to refuse. The loser
+ * writes nothing at all, listing rows included, and answers `superseded`.
+ *
+ * The caller must have evidence, not an inference: this writes a placement, and
+ * a placement written on a guess binds live mail to a uid that names somebody
+ * else's message. Two kinds of caller qualify, and nothing else does.
+ *
+ * A terminal resolver reaches here from {@link isMessageGoneFromOpenMailbox}
+ * answering that the message is STILL at `sourceMailboxId`/`uid`, which makes
+ * this the server's own answer rather than a revert on ambiguity (what PR #652
+ * was pulled for).
+ *
+ * A paused-cursor caller reaches here from a `MailboxCursorPausedError` the
+ * openBox guard threw before the outbound command was issued (issue #1203), and
+ * restores the pre-mutation pair off its own event. On a FIRST delivery that is
+ * not an inference but an undo: the command provably never left, so the row is
+ * put back exactly as it was found. A redelivery cannot claim that — the
+ * earlier attempt's tagged OK can be lost with the connection — so it asks
+ * `probePausedPlacement` which folder holds the message and only reaches here
+ * once the answer rules the destination out. Either way the source mailbox is
+ * by definition awaiting a cursor rebuild, which matches its rows by Message-ID
+ * and adjudicates the uid: handing the row back is what puts it in the set the
+ * rebuild walks, since a row still naming the destination is in neither
+ * folder's.
+ *
+ * A row another path deleted while the probe was in flight has nothing left to
+ * restore, and it fails the predicate like any other row that is no longer
+ * owed one. A listing row that other path has already rewritten is its to
+ * finish; the update for it comes back `NotFoundError`, and that is a settled
+ * state here rather than a fault. Throwing on it would escape the caller's
+ * `.catch()` and cost the record its ack and its resync, which is the contract
+ * the terminal resolvers state: never re-thrown.
+ */
+export const restoreSourcePlacement = async (deps, input) => {
+    const { accountConfigId, messageId, sourceMailboxId, uid, syncStatus, abandonedMutation, } = input;
+    const skipNotFound = (error) => {
+        if (isNotFoundError(error))
+            return;
+        throw error;
+    };
+    const restored = await deps.messageService.transitionPlacement(messageId, { status: [MessageStatus.moving, MessageStatus.deleting] }, {
+        mailboxId: sourceMailboxId,
+        uid,
+        status: MessageStatus.active,
+        syncStatus,
+        abandonedMutation,
+    });
+    if (!restored)
+        return "superseded";
+    const threadMessages = input.threadMessages ??
+        (await deps.threadMessageService.findAllByMessageId(accountConfigId, messageId));
+    for (const threadMessage of threadMessages) {
+        const args = buildThreadMessageMoveRevert(threadMessage, uid, sourceMailboxId);
+        await deps.threadMessageService
+            .update(threadMessage.accountConfigId, threadMessage.threadMessageId, args.set, { composites: args.composites })
+            .catch(skipNotFound);
+    }
+    return "restored";
+};

package/dist/search-text-backfill.d.ts

@@ -0,0 +1,15 @@
+import type { IMessageRepository } from "@remit/data-ports";
+import { type StorageService } from "@remit/storage-service";
+interface SearchTextBackfillDeps {
+    messageService: Pick<IMessageRepository, "listMissingSearchText" | "setSearchText" | "syncSearch">;
+    storageService: Pick<StorageService, "retrieve">;
+}
+interface SearchTextBackfillLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+}
+interface SearchTextBackfillResult {
+    indexed: number;
+    skipped: number;
+}
+export declare const backfillSearchText: (deps: SearchTextBackfillDeps, log: SearchTextBackfillLogger) => Promise<SearchTextBackfillResult>;
+export {};

package/dist/search-text-backfill.js

@@ -0,0 +1,33 @@
+import { isStorageNotFoundError, } from "@remit/storage-service";
+import { BodyParseError, parseMessageBody } from "./body-parse.js";
+import { extractSearchText } from "./snippet.js";
+const PAGE_SIZE = 200;
+const isUnreadableBody = (error) => error instanceof BodyParseError || isStorageNotFoundError(error);
+const recordSearchText = async (deps, messageId, bodyStorageKey) => {
+    const parsed = await parseMessageBody(await deps.storageService.retrieve(bodyStorageKey));
+    await deps.messageService.setSearchText(messageId, extractSearchText(parsed));
+};
+export const backfillSearchText = async (deps, log) => {
+    const result = { indexed: 0, skipped: 0 };
+    let after = "";
+    for (;;) {
+        const page = await deps.messageService.listMissingSearchText(after, PAGE_SIZE);
+        const last = page.at(-1);
+        if (!last)
+            return result;
+        const recorded = [];
+        for (const { messageId, bodyStorageKey } of page) {
+            await recordSearchText(deps, messageId, bodyStorageKey).then(() => {
+                recorded.push(messageId);
+            }, (error) => {
+                if (!isUnreadableBody(error))
+                    throw error;
+                result.skipped++;
+                log.warn({ messageId, error }, "Search text backfill skipped an unreadable stored body");
+            });
+        }
+        await deps.messageService.syncSearch(recorded);
+        result.indexed += recorded.length;
+        after = last.messageId;
+    }
+};

package/dist/snippet.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Snippet generation utilities for email threading.
+ *
+ * Extracts preview text from email bodies by removing quoted content
+ * and normalizing whitespace.
+ */
+import type { ParsedMail } from "mailparser";
+import { type SupportedLanguage } from "./text/normalizer.js";
+/**
+ * Remove quoted reply content from email body.
+ *
+ * Stops at common quote indicators:
+ * - Lines starting with ">"
+ * - "On ... wrote:" patterns
+ * - "--- Original Message ---" separators
+ * - Outlook-style underline separators
+ */
+export declare const removeQuotedContent: (text: string) => string;
+/**
+ * Normalize subject for thread grouping and search.
+ *
+ * Processing steps:
+ * 1. Remove Re:/Fwd:/etc prefixes (multi-language support)
+ * 2. Auto-detect language or use provided language
+ * 3. Normalize with stemming and stopword removal
+ * 4. Deduplicate consecutive words
+ *
+ * Handles common prefixes across languages:
+ * - Re, Fwd, Fw (English)
+ * - Aw, Sv, Vs (German, Swedish, Danish)
+ * - Ref, Rif (Italian, Spanish)
+ * - Odp (Polish)
+ * - Ynt (Turkish)
+ * - Antw (Dutch)
+ * - Res (Portuguese)
+ *
+ * @param subject - The email subject line
+ * @param language - Optional language override (auto-detected if not provided)
+ */
+export declare const normalizeSubject: (subject: string, language?: SupportedLanguage) => string;
+/**
+ * Generate a snippet from email text content.
+ *
+ * @param text - The text content (plain text or stripped HTML)
+ * @param maxLength - Maximum snippet length (default 256)
+ * @returns Truncated snippet with ellipsis if needed
+ */
+export declare const generateSnippet: (text: string, maxLength?: number) => string;
+/**
+ * Extract text content from parsed email for snippet generation.
+ *
+ * Prefers plain text over HTML, stripping the HTML's tags when it is the only
+ * part.
+ *
+ * @param textContent - Plain text content (may be undefined)
+ * @param htmlContent - HTML content (may be undefined)
+ * @param maxLength - Maximum snippet length
+ * @returns Generated snippet or empty string
+ */
+export declare const extractSnippetFromEmail: (textContent: string | undefined, htmlContent: string | undefined, maxLength?: number) => string;
+export declare const extractSearchText: (parsed: Pick<ParsedMail, "text" | "html">) => string;

package/dist/snippet.js

@@ -0,0 +1,129 @@
+/**
+ * Snippet generation utilities for email threading.
+ *
+ * Extracts preview text from email bodies by removing quoted content
+ * and normalizing whitespace.
+ */
+import { createTextNormalizer, } from "./text/normalizer.js";
+/**
+ * Remove quoted reply content from email body.
+ *
+ * Stops at common quote indicators:
+ * - Lines starting with ">"
+ * - "On ... wrote:" patterns
+ * - "--- Original Message ---" separators
+ * - Outlook-style underline separators
+ */
+export const removeQuotedContent = (text) => {
+    const lines = text.split("\n");
+    const result = [];
+    for (const line of lines) {
+        // Stop at quote indicators
+        if (/^>/.test(line))
+            break;
+        if (/^On .+ wrote:$/i.test(line))
+            break;
+        if (/^-{3,}\s*Original Message\s*-{3,}$/i.test(line))
+            break;
+        if (/^_{3,}$/.test(line))
+            break; // Outlook separator
+        if (/^From:.*Sent:.*To:/i.test(line))
+            break; // Outlook forward header
+        result.push(line);
+    }
+    return result.join("\n");
+};
+const normalizer = createTextNormalizer();
+/**
+ * Normalize subject for thread grouping and search.
+ *
+ * Processing steps:
+ * 1. Remove Re:/Fwd:/etc prefixes (multi-language support)
+ * 2. Auto-detect language or use provided language
+ * 3. Normalize with stemming and stopword removal
+ * 4. Deduplicate consecutive words
+ *
+ * Handles common prefixes across languages:
+ * - Re, Fwd, Fw (English)
+ * - Aw, Sv, Vs (German, Swedish, Danish)
+ * - Ref, Rif (Italian, Spanish)
+ * - Odp (Polish)
+ * - Ynt (Turkish)
+ * - Antw (Dutch)
+ * - Res (Portuguese)
+ *
+ * @param subject - The email subject line
+ * @param language - Optional language override (auto-detected if not provided)
+ */
+export const normalizeSubject = (subject, language) => {
+    const SUBJECT_PREFIX_PATTERN = /^(\s*(Re|Fwd|Fw|Aw|Sv|Vs|Ref|Rif|Odp|Ynt|Antw|Res)(\[\d+\])?:\s*)+/i;
+    // Step 1: Remove prefixes
+    const withoutPrefix = subject.replace(SUBJECT_PREFIX_PATTERN, "").trim();
+    // Step 2: Auto-detect language if not provided
+    const detectedLanguage = language ?? normalizer.detectLanguage(withoutPrefix);
+    // Step 3: Normalize with stemming and stopword removal
+    return normalizer.normalize(withoutPrefix, {
+        language: detectedLanguage,
+        stem: true,
+        removeStopwords: true,
+    });
+};
+const flattenBody = (text) => removeQuotedContent(text).replace(/\s+/g, " ").trim();
+/**
+ * Generate a snippet from email text content.
+ *
+ * @param text - The text content (plain text or stripped HTML)
+ * @param maxLength - Maximum snippet length (default 256)
+ * @returns Truncated snippet with ellipsis if needed
+ */
+export const generateSnippet = (text, maxLength = 256) => {
+    const normalized = flattenBody(text);
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    // Truncate at word boundary
+    const truncated = normalized.slice(0, maxLength);
+    const lastSpace = truncated.lastIndexOf(" ");
+    // If no space found, just truncate
+    if (lastSpace === -1) {
+        return `${truncated.slice(0, maxLength - 1)}...`;
+    }
+    // Truncate at word boundary and add ellipsis
+    return `${truncated.slice(0, lastSpace)}...`;
+};
+const emailPlainText = (textContent, htmlContent) => {
+    if (textContent)
+        return textContent;
+    if (!htmlContent)
+        return "";
+    // Basic HTML tag stripping - for more robust handling, use html-to-text
+    return htmlContent
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"');
+};
+/**
+ * Extract text content from parsed email for snippet generation.
+ *
+ * Prefers plain text over HTML, stripping the HTML's tags when it is the only
+ * part.
+ *
+ * @param textContent - Plain text content (may be undefined)
+ * @param htmlContent - HTML content (may be undefined)
+ * @param maxLength - Maximum snippet length
+ * @returns Generated snippet or empty string
+ */
+export const extractSnippetFromEmail = (textContent, htmlContent, maxLength = 256) => generateSnippet(emailPlainText(textContent, htmlContent), maxLength);
+const SEARCH_TEXT_LENGTH = 524288;
+export const extractSearchText = (parsed) => {
+    const text = flattenBody(emailPlainText(parsed.text, typeof parsed.html === "string" ? parsed.html : undefined));
+    if (text.length <= SEARCH_TEXT_LENGTH)
+        return text;
+    const boundary = text.lastIndexOf(" ", SEARCH_TEXT_LENGTH);
+    return text.slice(0, boundary > 0 ? boundary : SEARCH_TEXT_LENGTH);
+};

package/dist/spam-report.d.ts

@@ -0,0 +1,86 @@
+import type { IAccountRepository, IAddressRepository, IMailboxSpecialUseRepository, IMessageRepository } from "@remit/data-ports";
+import type { FlagPushService } from "./flag-push.js";
+import type { MessageMoveService } from "./message-move.js";
+export interface SpamReportLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * The one designed, user-facing outcome of `notSpam`'s R2 wait timing out —
+ * distinct from any other failure so a caller surfacing failures to the user
+ * (the bulk handlers in packages/backend) can allowlist this specific,
+ * pre-written message instead of relaying an arbitrary thrown error's text.
+ */
+export declare class MoveNotSettledError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * The account advertises no Junk folder and has none under any conventional
+ * name, so there is nowhere to file the report. A designed, user-facing
+ * outcome — the user has to create the folder, and no amount of retrying
+ * changes that — so it carries its own text through the bulk handler's
+ * allowlist rather than being flattened to the generic retry copy.
+ */
+export declare class NoJunkMailboxError extends Error {
+    constructor();
+}
+export interface SpamReportConfig {
+    messageService: IMessageRepository;
+    addressService: IAddressRepository;
+    accountService: IAccountRepository;
+    mailboxSpecialUseService: IMailboxSpecialUseRepository;
+    messageMoveService: MessageMoveService;
+    flagPushService: FlagPushService;
+    logger?: SpamReportLogger;
+    /** How long `notSpam` waits for a still-in-flight move before giving up. */
+    moveSettleTimeoutMs?: number;
+    moveSettlePollMs?: number;
+}
+export interface SpamReportParams {
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    setBy?: string;
+}
+export declare class SpamReportService {
+    private messageService;
+    private addressService;
+    private accountService;
+    private mailboxSpecialUseService;
+    private messageMoveService;
+    private flagPushService;
+    private log;
+    private moveSettleTimeoutMs;
+    private moveSettlePollMs;
+    constructor(config: SpamReportConfig);
+    /**
+     * The sender to act on. `addressId` is derived rather than read off the
+     * envelope row so it always names the row `ensureSenderAddress` writes and
+     * the harvester writes — one derivation, one row, whatever the envelope
+     * happens to carry.
+     */
+    private resolveFromAddress;
+    /**
+     * The list form answers `[]` for a row that is not there, where the single
+     * form throws — absence is a case both callers handle, not a fault.
+     */
+    private senderIsKnown;
+    /**
+     * Blocking a sender owns the row it writes to. Harvesting is what ordinarily
+     * creates it, but a message whose harvest never landed — or whose row was
+     * taken by a cascade — still has a sender the user is entitled to block, and
+     * a missing row used to abort report-spam before the message ever reached
+     * Junk. The id is the harvester's own derivation, so this converges on the
+     * one row rather than minting a parallel one.
+     *
+     * A row that already exists is left exactly as it stands. Reporting spam is
+     * evidence about the sender, never about the account's standing record of
+     * them: an upsert here would carry whatever the upsert path does on
+     * conflict — today a display name chosen by the spammer, and any flag a
+     * later sighting-clearing rule hangs off it — into an operation that means
+     * the opposite.
+     */
+    private ensureSenderAddress;
+    reportSpam: (params: SpamReportParams) => Promise<void>;
+    notSpam: (params: SpamReportParams) => Promise<void>;
+}

package/dist/spam-report.js

@@ -0,0 +1,241 @@
+import { deriveAddressId } from "@remit/data-ports/id";
+import { AddressRole, MessageKeywordFlag } from "@remit/domain-enums";
+import { isPlacementUnsettled, waitForPlacementToSettle, } from "./placement-settled.js";
+/**
+ * The one designed, user-facing outcome of `notSpam`'s R2 wait timing out —
+ * distinct from any other failure so a caller surfacing failures to the user
+ * (the bulk handlers in packages/backend) can allowlist this specific,
+ * pre-written message instead of relaying an arbitrary thrown error's text.
+ */
+export class MoveNotSettledError extends Error {
+    constructor(messageId) {
+        super(`Message ${messageId}'s move to Junk has not settled yet; try again in a moment.`);
+        this.name = "MoveNotSettledError";
+    }
+}
+/**
+ * The account advertises no Junk folder and has none under any conventional
+ * name, so there is nowhere to file the report. A designed, user-facing
+ * outcome — the user has to create the folder, and no amount of retrying
+ * changes that — so it carries its own text through the bulk handler's
+ * allowlist rather than being flattened to the generic retry copy.
+ */
+export class NoJunkMailboxError extends Error {
+    constructor() {
+        super("This account has no Junk folder. Create one named Junk or Spam in your mail provider, then report this message again.");
+        this.name = "NoJunkMailboxError";
+    }
+}
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
+const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
+export class SpamReportService {
+    messageService;
+    addressService;
+    accountService;
+    mailboxSpecialUseService;
+    messageMoveService;
+    flagPushService;
+    log;
+    moveSettleTimeoutMs;
+    moveSettlePollMs;
+    constructor(config) {
+        this.messageService = config.messageService;
+        this.addressService = config.addressService;
+        this.accountService = config.accountService;
+        this.mailboxSpecialUseService = config.mailboxSpecialUseService;
+        this.messageMoveService = config.messageMoveService;
+        this.flagPushService = config.flagPushService;
+        this.log = config.logger ?? noopLogger;
+        this.moveSettleTimeoutMs =
+            config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
+        this.moveSettlePollMs =
+            config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
+    }
+    /**
+     * The sender to act on. `addressId` is derived rather than read off the
+     * envelope row so it always names the row `ensureSenderAddress` writes and
+     * the harvester writes — one derivation, one row, whatever the envelope
+     * happens to carry.
+     */
+    resolveFromAddress = async (accountConfigId, messageId) => {
+        const description = await this.messageService.describe(messageId);
+        const from = description.envelopeAddress.find((a) => a.addressRole === AddressRole.From);
+        if (!from) {
+            throw new Error(`Message ${messageId} has no From address to act on`);
+        }
+        return {
+            addressId: deriveAddressId(accountConfigId, from.normalizedEmail),
+            normalizedEmail: from.normalizedEmail,
+            displayName: from.displayName ?? "",
+        };
+    };
+    /**
+     * The list form answers `[]` for a row that is not there, where the single
+     * form throws — absence is a case both callers handle, not a fault.
+     */
+    senderIsKnown = async (accountConfigId, addressId) => {
+        const [known] = await this.addressService.getAddress(accountConfigId, [
+            addressId,
+        ]);
+        return known !== undefined;
+    };
+    /**
+     * Blocking a sender owns the row it writes to. Harvesting is what ordinarily
+     * creates it, but a message whose harvest never landed — or whose row was
+     * taken by a cascade — still has a sender the user is entitled to block, and
+     * a missing row used to abort report-spam before the message ever reached
+     * Junk. The id is the harvester's own derivation, so this converges on the
+     * one row rather than minting a parallel one.
+     *
+     * A row that already exists is left exactly as it stands. Reporting spam is
+     * evidence about the sender, never about the account's standing record of
+     * them: an upsert here would carry whatever the upsert path does on
+     * conflict — today a display name chosen by the spammer, and any flag a
+     * later sighting-clearing rule hangs off it — into an operation that means
+     * the opposite.
+     */
+    ensureSenderAddress = async (accountConfigId, from) => {
+        const separator = from.normalizedEmail.lastIndexOf("@");
+        const localPart = from.normalizedEmail.slice(0, separator);
+        const domain = from.normalizedEmail.slice(separator + 1);
+        if (separator < 0 || localPart.length === 0 || domain.length === 0) {
+            throw new Error(`Sender address ${from.normalizedEmail} is not a usable email address`);
+        }
+        if (await this.senderIsKnown(accountConfigId, from.addressId))
+            return;
+        await this.addressService.upsertAddress({
+            addressId: from.addressId,
+            accountConfigId,
+            localPart,
+            domain,
+            normalizedEmail: from.normalizedEmail,
+            normalizedCompound: `${from.displayName.toLowerCase()} ${from.normalizedEmail}`.trim(),
+            displayName: from.displayName,
+        });
+    };
+    reportSpam = async (params) => {
+        const { accountConfigId, accountId, messageId, setBy } = params;
+        const now = Date.now();
+        // Resolved before anything is written: with nowhere to file the report,
+        // the operation cannot happen, and a blocked sender plus a `spamReport`
+        // stamp on a message still sitting in the inbox is a report that half
+        // happened. Fail here and the press changed nothing.
+        const junkMailbox = await this.mailboxSpecialUseService.findJunkMailbox(accountId);
+        if (!junkMailbox) {
+            this.log.error({ accountId, messageId }, "No Junk mailbox for account");
+            throw new NoJunkMailboxError();
+        }
+        const from = await this.resolveFromAddress(accountConfigId, messageId);
+        const account = await this.accountService.get(accountId);
+        const isOwnAddress = from.normalizedEmail.toLowerCase() === account.email.toLowerCase();
+        if (!isOwnAddress) {
+            await this.ensureSenderAddress(accountConfigId, from);
+            await this.addressService.mergeFlags(accountConfigId, from.addressId, {
+                blocked: { value: true, setAt: now, setBy },
+            });
+        }
+        // Captured before this call writes anything: `before.spamReport` tells
+        // apart the two reasons the message can already be in Junk. If it is
+        // already set, a PREVIOUS report-spam press put it there and owns
+        // `originalMailboxId` — that value is exactly what Undo needs and must
+        // survive a repeated press. Only when it is absent is the message in
+        // Junk for some unrelated reason (a provider filter, a manual move),
+        // making any `originalMailboxId` on the row stale.
+        const before = await this.messageService.get(messageId);
+        const hadSpamReportAlready = Boolean(before.spamReport);
+        await this.messageService.update(messageId, {
+            spamReport: { reportedAt: now },
+        });
+        const alreadyInJunk = before.mailboxId === junkMailbox.mailboxId;
+        await this.messageMoveService.moveMessage(accountConfigId, messageId, junkMailbox.mailboxId, accountId);
+        if (alreadyInJunk && before.originalMailboxId && !hadSpamReportAlready) {
+            // moveMessage's same-mailbox guard no-opped — it never touches
+            // originalMailboxId, so a stale value left by some earlier, unrelated
+            // move would otherwise survive and send a later notSpam to the wrong
+            // folder. This report-spam action established no move of its own.
+            //
+            // A transition off the row this call read (imap-mutations R3): the pair
+            // being cleared belongs to a placement, and a lane that has claimed the
+            // row since keeps its own — its settle manages the pair.
+            await this.messageService.transitionPlacement(messageId, {
+                status: before.status,
+                mailboxId: before.mailboxId,
+                uid: before.uid,
+            }, { originalMailboxId: null, originalUid: null });
+        }
+        await this.flagPushService.flip({
+            accountId,
+            accountConfigId,
+            messageId,
+            mailboxId: junkMailbox.mailboxId,
+            flagName: MessageKeywordFlag.Junk,
+            operation: "add",
+        });
+        this.log.info({
+            accountId,
+            messageId,
+            addressId: from.addressId,
+            junkMailboxId: junkMailbox.mailboxId,
+            skippedBlock: isOwnAddress,
+        }, "Reported message as spam");
+    };
+    notSpam = async (params) => {
+        const { accountConfigId, accountId, messageId } = params;
+        // Unblocking a sender the account has no row for is already true, and
+        // minting one here would put an address nothing ever harvested into the
+        // address book — the withdrawal of a judgement is not a sighting.
+        const from = await this.resolveFromAddress(accountConfigId, messageId);
+        if (await this.senderIsKnown(accountConfigId, from.addressId)) {
+            await this.addressService.mergeFlags(accountConfigId, from.addressId, {
+                blocked: null,
+            });
+        }
+        const message = await this.messageService.get(messageId);
+        if (message.originalMailboxId) {
+            // Only wait on the move's settlement when there is actually a
+            // dependent write to make (the restore below) — a move in flight for
+            // an unrelated reason is not this operation's concern.
+            const settled = await waitForPlacementToSettle(this.messageService, messageId, {
+                timeoutMs: this.moveSettleTimeoutMs,
+                pollMs: this.moveSettlePollMs,
+            });
+            if (isPlacementUnsettled(settled)) {
+                throw new MoveNotSettledError(messageId);
+            }
+            await this.messageMoveService.restoreMessage(accountConfigId, messageId, accountId);
+            // Re-read, then clear against what was read. The restore just wrote a
+            // placement, so the row here is not the one above; predicating on it is
+            // what keeps this from erasing a pair some other lane is relying on
+            // (imap-mutations R3).
+            const restored = await this.messageService.get(messageId);
+            await this.messageService.transitionPlacement(messageId, {
+                status: restored.status,
+                mailboxId: restored.mailboxId,
+                uid: restored.uid,
+            }, { originalMailboxId: null, originalUid: null });
+        }
+        const current = await this.messageService.get(messageId);
+        await this.flagPushService.flip({
+            accountId,
+            accountConfigId,
+            messageId,
+            mailboxId: current.mailboxId,
+            flagName: MessageKeywordFlag.Junk,
+            operation: "remove",
+        });
+        await this.flagPushService.flip({
+            accountId,
+            accountConfigId,
+            messageId,
+            mailboxId: current.mailboxId,
+            flagName: MessageKeywordFlag.NotJunk,
+            operation: "add",
+        });
+        await this.messageService.clearSpamReport(messageId);
+        this.log.info({ accountId, messageId, addressId: from.addressId }, "Undid spam report");
+    };
+}

package/dist/sync-warning.d.ts

@@ -0,0 +1,21 @@
+import type { ISyncWarningRepository, SyncWarningItem, SyncWarningKey } from "@remit/data-ports";
+export type SyncWarningContext = Omit<SyncWarningKey, "uid" | "stage">;
+export type ServerUids = {
+    kind: "Listed";
+    uids: readonly number[];
+} | {
+    kind: "OnRequest";
+    list: () => Promise<readonly number[]>;
+} | {
+    kind: "Unlisted";
+};
+export interface SyncWarningRound {
+    failedUids: readonly number[];
+    syncedUids: readonly number[];
+    serverUids: ServerUids;
+}
+export declare class SyncWarningService {
+    private readonly repository;
+    constructor(repository: ISyncWarningRepository);
+    settle(context: SyncWarningContext, stage: SyncWarningItem["stage"], round: SyncWarningRound): Promise<void>;
+}