@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * remit-mailbox-service
+ *
+ * IMAP mailbox synchronization service for Remit
+ */
+export { type AccountCredentialsDeps, type ConnectionStateValue, type CredentialResolution, encryptRefreshToken, hasStoredCredential, type MissingCredential, resolveConnectionCredentials, type StoredCredentialFields, } from "./account-credentials.js";
+export { hasChildren, isNoSelect, type ParsedAttributes, parseImapAttributes, } from "./attribute-mapper.js";
+export { BodyParseError, parseMessageBody, } from "./body-parse.js";
+export { type BodySyncFolder, type BodySyncLogger, type BodySyncRoundFolder, BodySyncService, type ConnectionGetter, extractSnippet, type FetchBodyResult, type PlacementConfig, type QuarantineConfig, type SyncBodiesResult, toParsedBody, } from "./body-sync.js";
+export { type BodySyncQueueConfig, type BodySyncQueueLogger, BodySyncQueueService, type RequestBodySyncInput, type SyncMessageBodyEvent, } from "./body-sync-queue.js";
+export { isMessageBodySyncBroken, type ResolveExhaustedBodySyncDeps, type ResolveExhaustedBodySyncInput, type ResolveExhaustedBodySyncResult, resolveExhaustedBodySyncFailures, } from "./body-sync-terminal.js";
+export { backfillClassifications, type ClassificationBackfillCheckpoint, type ClassificationBackfillCheckpointStore, type ClassificationBackfillDeps, type ClassificationBackfillLogger, type ClassificationBackfillOptions, type ClassificationBackfillProgress, type ClassificationBackfillResult, type ClassificationBackfillTotals, } from "./classification-backfill.js";
+export { classifyParsedMessage, extractPrimaryFromEmail, } from "./classify-message.js";
+export { createConnection, createConnectionFromAccount, createConnectionWithCredentials, createManagedConnectionFactory, type ManagedConnectionFactory, } from "./connection-factory.js";
+export { type ImapTestConfig, type SmtpTestConfig, type TestResult, testImapConnection, testSmtpConnection, } from "./connection-test.js";
+export { type CreatedFilter, createFilter, type FilterPage, type FilterPatch, listFilters, type NewFilter, resolveFilterUpdate, updateFilter, } from "./filter-operations.js";
+export { extractListId, normalizeListId } from "./filters/list-id.js";
+export { clauseMatches, type FilterMessage, type LiteralClauseNarrowing, literalClausesMatch, literalClauseTerms, NO_ACTION, selectMoveWinner, } from "./filters/match.js";
+export { type FilterConfig, type FilterDecision, type FilterLogger, FilterPipeline, } from "./filters/pipeline.js";
+export { type FlagPushConfig, type FlagPushEvent, type FlagPushLogger, type FlagPushOperationValue, FlagPushService, } from "./flag-push.js";
+export { type FlagPushTerminalOutcome, type ResolveExhaustedFlagPushDeps, type ResolveExhaustedFlagPushInput, type ResolveExhaustedFlagPushResult, resolveExhaustedFlagPushFailure, } from "./flag-push-terminal.js";
+export { type FlagQueueConfig, type FlagQueueLogger, FlagQueueService, type UpdateFlagsInput, type UpdateFlagsResult, } from "./flag-queue.js";
+export { type CreateFolderDeps, changeFolderPath, createFolder, type FolderPathChange, type FolderPathDeps, type FolderPathOutcome, type NewFolder, type NewFolderOutcome, ownedFolder, } from "./folder-operations.js";
+export { type FolderPlacementLookup, resolveAccountFolderPlacements, resolveFolderPlacement, } from "./folder-placement.js";
+export { classifyByHeaders, extractAuthenticity, extractAuthResult, extractHasListUnsubscribe, extractProviderSpam, type MessageAuthenticity, type MessageAuthResult, type MessageProviderSpam, } from "./heuristics/classifyByHeaders.js";
+export { classifyPlacement, type FolderPlacement, type PlacementAction, type PlacementVerdict, } from "./heuristics/classifyPlacement.js";
+export { classifyDisplayNameCorrespondence, extractOffDomainLinkDomains, extractSenderMismatch, type SenderMismatchContext, type SenderMismatchSignals, } from "./heuristics/senderMismatch.js";
+export { SOCIAL_DOMAINS } from "./heuristics/socialDomains.js";
+export { TRANSACTIONAL_DOMAINS } from "./heuristics/transactionalDomains.js";
+export { createImapFlowConnectionFromAccount, createImapFlowConnectionWithCredentials, ImapFlowConnection, } from "./imapflow-connection.js";
+export { backfillListIds, type ListIdBackfillCheckpoint, type ListIdBackfillCheckpointStore, type ListIdBackfillDeps, type ListIdBackfillLogger, type ListIdBackfillOptions, type ListIdBackfillProgress, type ListIdBackfillResult, type ListIdBackfillTotals, } from "./list-id-backfill.js";
+export { guardConnectionCursor, guardMailboxCursor, isCursorRebuildNeeded, type MailboxCursorCheck, type MailboxCursorGuardDeps, MailboxCursorPausedError, } from "./mailbox-cursor.js";
+export { type CursorRebuildMatch, type CursorRebuildMatchResult, type CursorRebuildRow, type CursorRebuildSnapshot, matchCursorRebuild, } from "./mailbox-cursor-rebuild.js";
+export { folderInFlight } from "./mailbox-intent.js";
+export { type CreateMailboxInput, type DeleteMailboxInput, type MailboxManagementLogger, MailboxManagementService, type MailboxManagementSyncResult, parseMailboxPath, type RenameMailboxInput, validateMailboxOperation, validateMailboxPath, } from "./mailbox-management.js";
+export { EVERY_MAILBOX_STATE, isFolderMutationInFlight, isMailboxMutationInFlight, } from "./mailbox-presence.js";
+export { type CreateMailboxQueueInput, type MailboxManagementEvent, type MailboxQueueConfig, type MailboxQueueLogger, MailboxQueueService, } from "./mailbox-queue.js";
+export { MailboxSyncService, type SyncAccountInfo, } from "./mailbox-sync.js";
+export { FolderGoneUpstreamError, FolderRenameSettleError, isMailboxAbsentUpstream, isMailboxPresentUpstream, isMailboxRefusedUpstream, upstreamFailureReason, } from "./mailbox-upstream.js";
+export { denormalizeMessageCategory, type MessageCategoryDenormalizeDeps, type MessageCategoryDenormalizeInput, type MessageCategoryValue, } from "./message-category.js";
+export { type DeleteMessagesOutcome, type DeleteOptions, type MessageMoveConfig, type MessageMoveLogger, type MessageMoveQueueEvent, MessageMoveService, NoTrashMailboxError, requireTrashMailbox, StaleTrashAppointmentError, UnconfirmedTrashMailboxError, } from "./message-move.js";
+export { type ParsedMessageContent, parseMessageContent, } from "./message-parser.js";
+export { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+export { type BodyPartMaterializer, type BodySyncCue, type MaterializeLogger, type MaterializeResult, materializeBodyParts, } from "./message-read.js";
+export { type ImapConnectionFactory, MessageSyncService, type SyncedMessage, type SyncMessagesResult, } from "./message-sync.js";
+export { type OrganizeJobDeps, type OrganizeJobLogger, type OrganizeJobOwner, type OrganizeJobPredicate, type OrganizeJobRequest, queueOrganizeJob, } from "./organize-job.js";
+export { type CompleteOutboxAttachmentInput, type CompleteOutboxAttachmentOutcome, type MintOutboxAttachmentInput, type MintOutboxAttachmentOutcome, OUTBOX_ATTACHMENT_MAX_COUNT, OUTBOX_ATTACHMENT_MAX_TOTAL_BYTES, type OutboxAttachmentConfig, type OutboxAttachmentRejectionDetail, type OutboxAttachmentRejectionReasonValue, type OutboxAttachmentReservation, OutboxAttachmentService, } from "./outbox-attachment.js";
+export { FALLBACK_CONTENT_TYPE, normalizeAttachmentContentType, sanitizeAttachmentFilename, } from "./outbox-attachment-filename.js";
+export { type CreateDraftInput, type OutboxQueueConfig, type OutboxQueueLogger, OutboxQueueService, type SendMessageEvent, type UpdateDraftInput, } from "./outbox-queue.js";
+export { folderInAccount, type MessageOwnershipClient, ownedAccount, ownedMessages, settledFolder, } from "./ownership.js";
+export { type PlacementMoveConfig, type PlacementMoveLogger, type PlacementMovePushEvent, PlacementMoveService, } from "./placement-move.js";
+export { type PlacementMoveTerminalOutcome, type ResolveExhaustedPlacementMoveDeps, type ResolveExhaustedPlacementMoveInput, type ResolveExhaustedPlacementMoveResult, resolveExhaustedPlacementMoveFailure, } from "./placement-move-terminal.js";
+export { carriesForeignUid, isPlacementUnsettled, type PlacementBinding, placementBindingOf, uidMailboxIdOf, } from "./placement-settled.js";
+export { type QuarantineContext, QuarantinedUids, type QuarantineFailure, type QuarantineLogger, type QuarantineMessageShape, QuarantineService, resolveMailboxRole, shapeFromMessageData, } from "./quarantine.js";
+export { type AccessMode, accept, invalid, type Refusable, type Refusal, type Refused, refuse, } from "./refusal.js";
+export { type RestoreSourcePlacementDeps, type RestoreSourcePlacementInput, type RestoreSourcePlacementOutcome, restoreSourcePlacement, } from "./restore-source-placement.js";
+export { backfillSearchText } from "./search-text-backfill.js";
+export { extractSearchText, extractSnippetFromEmail, generateSnippet, normalizeSubject, removeQuotedContent, } from "./snippet.js";
+export { MoveNotSettledError, NoJunkMailboxError, type SpamReportConfig, type SpamReportLogger, type SpamReportParams, SpamReportService, } from "./spam-report.js";
+export { type ServerUids, type SyncWarningContext, type SyncWarningRound, SyncWarningService, } from "./sync-warning.js";
+export { buildThreadMessageMoveRevert, buildThreadMessageTrashUpdate, buildThreadMessageUndelete, type ThreadMessageRowState, } from "./thread-message-rows.js";
+export type { FlatMailboxInfo, IImapConnection, ImapBoxStatus, ImapConnectionConfig, ImapConnectionState, ImapNamespace, ImapNamespaces, MailboxSyncResult, MailConnectionErrorKind, MailCredentials, } from "./types.js";
+export { MailConnectionError } from "./types.js";

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * remit-mailbox-service
+ *
+ * IMAP mailbox synchronization service for Remit
+ */
+export { encryptRefreshToken, hasStoredCredential, resolveConnectionCredentials, } from "./account-credentials.js";
+export { hasChildren, isNoSelect, parseImapAttributes, } from "./attribute-mapper.js";
+export { BodyParseError, parseMessageBody, } from "./body-parse.js";
+export { BodySyncService, extractSnippet, toParsedBody, } from "./body-sync.js";
+export { BodySyncQueueService, } from "./body-sync-queue.js";
+export { isMessageBodySyncBroken, resolveExhaustedBodySyncFailures, } from "./body-sync-terminal.js";
+export { backfillClassifications, } from "./classification-backfill.js";
+export { classifyParsedMessage, extractPrimaryFromEmail, } from "./classify-message.js";
+// Connection factory
+export { createConnection, createConnectionFromAccount, createConnectionWithCredentials, createManagedConnectionFactory, } from "./connection-factory.js";
+// Connection testing
+export { testImapConnection, testSmtpConnection, } from "./connection-test.js";
+export { createFilter, listFilters, resolveFilterUpdate, updateFilter, } from "./filter-operations.js";
+export { extractListId, normalizeListId } from "./filters/list-id.js";
+export { clauseMatches, literalClausesMatch, literalClauseTerms, NO_ACTION, selectMoveWinner, } from "./filters/match.js";
+export { FilterPipeline, } from "./filters/pipeline.js";
+export { FlagPushService, } from "./flag-push.js";
+export { resolveExhaustedFlagPushFailure, } from "./flag-push-terminal.js";
+export { FlagQueueService, } from "./flag-queue.js";
+export { changeFolderPath, createFolder, ownedFolder, } from "./folder-operations.js";
+export { resolveAccountFolderPlacements, resolveFolderPlacement, } from "./folder-placement.js";
+export { classifyByHeaders, extractAuthenticity, extractAuthResult, extractHasListUnsubscribe, extractProviderSpam, } from "./heuristics/classifyByHeaders.js";
+export { classifyPlacement, } from "./heuristics/classifyPlacement.js";
+export { classifyDisplayNameCorrespondence, extractOffDomainLinkDomains, extractSenderMismatch, } from "./heuristics/senderMismatch.js";
+export { SOCIAL_DOMAINS } from "./heuristics/socialDomains.js";
+export { TRANSACTIONAL_DOMAINS } from "./heuristics/transactionalDomains.js";
+// IMAP connection (ImapFlow-based)
+export { createImapFlowConnectionFromAccount, createImapFlowConnectionWithCredentials, ImapFlowConnection, } from "./imapflow-connection.js";
+export { backfillListIds, } from "./list-id-backfill.js";
+export { guardConnectionCursor, guardMailboxCursor, isCursorRebuildNeeded, MailboxCursorPausedError, } from "./mailbox-cursor.js";
+export { matchCursorRebuild, } from "./mailbox-cursor-rebuild.js";
+export { folderInFlight } from "./mailbox-intent.js";
+export { MailboxManagementService, parseMailboxPath, validateMailboxOperation, validateMailboxPath, } from "./mailbox-management.js";
+export { EVERY_MAILBOX_STATE, isFolderMutationInFlight, isMailboxMutationInFlight, } from "./mailbox-presence.js";
+export { MailboxQueueService, } from "./mailbox-queue.js";
+export { MailboxSyncService, } from "./mailbox-sync.js";
+export { FolderGoneUpstreamError, FolderRenameSettleError, isMailboxAbsentUpstream, isMailboxPresentUpstream, isMailboxRefusedUpstream, upstreamFailureReason, } from "./mailbox-upstream.js";
+export { denormalizeMessageCategory, } from "./message-category.js";
+export { MessageMoveService, NoTrashMailboxError, requireTrashMailbox, StaleTrashAppointmentError, UnconfirmedTrashMailboxError, } from "./message-move.js";
+export { parseMessageContent, } from "./message-parser.js";
+export { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+export { materializeBodyParts, } from "./message-read.js";
+export { MessageSyncService, } from "./message-sync.js";
+export { queueOrganizeJob, } from "./organize-job.js";
+export { OUTBOX_ATTACHMENT_MAX_COUNT, OUTBOX_ATTACHMENT_MAX_TOTAL_BYTES, OutboxAttachmentService, } from "./outbox-attachment.js";
+export { FALLBACK_CONTENT_TYPE, normalizeAttachmentContentType, sanitizeAttachmentFilename, } from "./outbox-attachment-filename.js";
+export { OutboxQueueService, } from "./outbox-queue.js";
+export { folderInAccount, ownedAccount, ownedMessages, settledFolder, } from "./ownership.js";
+export { PlacementMoveService, } from "./placement-move.js";
+export { resolveExhaustedPlacementMoveFailure, } from "./placement-move-terminal.js";
+export { carriesForeignUid, isPlacementUnsettled, placementBindingOf, uidMailboxIdOf, } from "./placement-settled.js";
+export { QuarantinedUids, QuarantineService, resolveMailboxRole, shapeFromMessageData, } from "./quarantine.js";
+export { accept, invalid, refuse, } from "./refusal.js";
+export { restoreSourcePlacement, } from "./restore-source-placement.js";
+export { backfillSearchText } from "./search-text-backfill.js";
+export { extractSearchText, extractSnippetFromEmail, generateSnippet, normalizeSubject, removeQuotedContent, } from "./snippet.js";
+export { MoveNotSettledError, NoJunkMailboxError, SpamReportService, } from "./spam-report.js";
+export { SyncWarningService, } from "./sync-warning.js";
+export { buildThreadMessageMoveRevert, buildThreadMessageTrashUpdate, buildThreadMessageUndelete, } from "./thread-message-rows.js";
+export { MailConnectionError } from "./types.js";

package/dist/list-id-backfill.d.ts

@@ -0,0 +1,83 @@
+import type { IAccountConfigRepository, IMessageRepository, IThreadMessageRepository } from "@remit/data-ports";
+import type { StorageService } from "@remit/storage-service";
+/**
+ * Where the full-corpus pass left off: the identity of the account it was
+ * working through, and the page cursor within that account. Resuming looks the
+ * account up by id and re-opens it at its saved cursor, rather than re-scanning
+ * the whole corpus from the top after an interruption. A checkpoint naming no
+ * configured account restarts the pass.
+ */
+export interface ListIdBackfillCheckpoint {
+    accountConfigId: string;
+    continuationToken?: string;
+}
+/**
+ * Persistence for {@link ListIdBackfillCheckpoint}, injected so the pass stays
+ * testable with an in-memory fake; the real entrypoint backs it with a file.
+ * `clear()` runs once the whole corpus has been scanned, so a later run starts
+ * fresh rather than reading a stale finished-run checkpoint.
+ */
+export interface ListIdBackfillCheckpointStore {
+    load(): Promise<ListIdBackfillCheckpoint | undefined>;
+    save(checkpoint: ListIdBackfillCheckpoint): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface ListIdBackfillDeps {
+    accountConfigService: Pick<IAccountConfigRepository, "listAll">;
+    threadMessageService: Pick<IThreadMessageRepository, "listByAccount" | "update">;
+    messageService: Pick<IMessageRepository, "get">;
+    storageService: Pick<StorageService, "retrieve">;
+}
+export interface ListIdBackfillLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error?(obj: Record<string, unknown>, msg: string): void;
+}
+export interface ListIdBackfillTotals {
+    scanned: number;
+    alreadySet: number;
+    skippedNoBody: number;
+    backfilled: number;
+    noListId: number;
+    failed: number;
+}
+export interface ListIdBackfillResult extends ListIdBackfillTotals {
+    failedThreadMessageIds: string[];
+}
+export interface ListIdBackfillProgress extends ListIdBackfillTotals {
+    accountConfigId: string;
+}
+export interface ListIdBackfillOptions {
+    /** Rows fetched per `listByAccount` page. */
+    batchSize?: number;
+    checkpointStore?: ListIdBackfillCheckpointStore;
+    logger?: ListIdBackfillLogger;
+    /** Called once per page, after that page's rows are settled. */
+    onProgress?: (progress: ListIdBackfillProgress) => void;
+}
+/**
+ * One-time, resumable pass that derives `ThreadMessage.listId` for rows synced
+ * before header extraction shipped (issue #263). Read-only against the stored
+ * raw source: it never opens IMAP and never touches anything but the single
+ * `listId` field.
+ *
+ * A row is a candidate when `listId` is `undefined` — written before the
+ * column existed, or written since by a path that found no `List-Id` header
+ * (body-sync only sets the field when the header is present, so "no header"
+ * and "not yet backfilled" look the same on the row; re-checking an
+ * already-correct empty row is wasted work, never a wrong answer). A
+ * candidate whose Message has no `bodyStorageKey` yet is left alone — its
+ * body was never synced, so there is nothing local to read, and the ordinary
+ * sync path will populate `listId` for it once the body lands.
+ *
+ * Chunked by `listByAccount`'s existing keyset pagination, one account at a
+ * time in account-id order, so an interrupted run and its resume walk the same
+ * sequence. A failure reading or parsing one message's
+ * stored body is contained to that message — logged, counted, and the pass
+ * continues: one unreadable object must not strand the rest of the corpus.
+ *
+ * The shape a later pass over `Message.classificationState` should take
+ * (issue #331): a one-time, resumable, storage-only sweep that selects its
+ * cohort by an explicit field, so it can be run once, deliberately, after a
+ * classifier release — rather than a re-derivation folded into every sync pass.
+ */
+export declare const backfillListIds: (deps: ListIdBackfillDeps, options?: ListIdBackfillOptions) => Promise<ListIdBackfillResult>;

package/dist/list-id-backfill.js

@@ -0,0 +1,132 @@
+import { parseMessageBody } from "./body-parse.js";
+import { extractListId } from "./filters/list-id.js";
+const DEFAULT_BATCH_SIZE = 200;
+const emptyTotals = () => ({
+    scanned: 0,
+    alreadySet: 0,
+    skippedNoBody: 0,
+    backfilled: 0,
+    noListId: 0,
+    failed: 0,
+});
+/**
+ * Read the stored raw source, derive `List-Id`, and — only when one is
+ * present — write it. Kept as its own function (rather than inline in a
+ * try/catch) so the caller can contain a failure with `.then(fulfilled,
+ * rejected)` instead of a block catch, which keeps the `try` around the one
+ * call whose failure this contains.
+ */
+const deriveAndApplyListId = async (deps, accountConfigId, row, bodyStorageKey) => {
+    const body = await deps.storageService.retrieve(bodyStorageKey);
+    const parsed = await parseMessageBody(body);
+    const listId = extractListId(parsed);
+    if (listId) {
+        await deps.threadMessageService.update(accountConfigId, row.threadMessageId, { listId }, {
+            composites: {
+                sentDate: row.sentDate,
+                mailboxId: row.mailboxId,
+                isRead: row.isRead,
+                isDeleted: row.isDeleted,
+                hasStars: row.hasStars,
+                hasAttachment: row.hasAttachment,
+            },
+        });
+    }
+    return listId;
+};
+/**
+ * One-time, resumable pass that derives `ThreadMessage.listId` for rows synced
+ * before header extraction shipped (issue #263). Read-only against the stored
+ * raw source: it never opens IMAP and never touches anything but the single
+ * `listId` field.
+ *
+ * A row is a candidate when `listId` is `undefined` — written before the
+ * column existed, or written since by a path that found no `List-Id` header
+ * (body-sync only sets the field when the header is present, so "no header"
+ * and "not yet backfilled" look the same on the row; re-checking an
+ * already-correct empty row is wasted work, never a wrong answer). A
+ * candidate whose Message has no `bodyStorageKey` yet is left alone — its
+ * body was never synced, so there is nothing local to read, and the ordinary
+ * sync path will populate `listId` for it once the body lands.
+ *
+ * Chunked by `listByAccount`'s existing keyset pagination, one account at a
+ * time in account-id order, so an interrupted run and its resume walk the same
+ * sequence. A failure reading or parsing one message's
+ * stored body is contained to that message — logged, counted, and the pass
+ * continues: one unreadable object must not strand the rest of the corpus.
+ *
+ * The shape a later pass over `Message.classificationState` should take
+ * (issue #331): a one-time, resumable, storage-only sweep that selects its
+ * cohort by an explicit field, so it can be run once, deliberately, after a
+ * classifier release — rather than a re-derivation folded into every sync pass.
+ */
+export const backfillListIds = async (deps, options = {}) => {
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const { logger, checkpointStore } = options;
+    const accounts = [...(await deps.accountConfigService.listAll())].sort((left, right) => left.accountConfigId.localeCompare(right.accountConfigId));
+    const startingCheckpoint = await checkpointStore?.load();
+    const checkpointedIndex = startingCheckpoint
+        ? accounts.findIndex((account) => account.accountConfigId === startingCheckpoint.accountConfigId)
+        : -1;
+    if (startingCheckpoint && checkpointedIndex === -1) {
+        logger?.info({ accountConfigId: startingCheckpoint.accountConfigId }, "ListId backfill checkpoint names no configured account; restarting the pass");
+    }
+    const startIndex = checkpointedIndex === -1 ? 0 : checkpointedIndex;
+    const startContinuationToken = checkpointedIndex === -1
+        ? undefined
+        : startingCheckpoint?.continuationToken;
+    const totals = emptyTotals();
+    const failedThreadMessageIds = [];
+    for (let accountIndex = startIndex; accountIndex < accounts.length; accountIndex++) {
+        const account = accounts[accountIndex];
+        let continuationToken = accountIndex === startIndex ? startContinuationToken : undefined;
+        do {
+            const page = await deps.threadMessageService.listByAccount(account.accountConfigId, { limit: batchSize, continuationToken });
+            totals.scanned += page.items.length;
+            const candidates = page.items.filter((row) => row.listId === undefined);
+            totals.alreadySet += page.items.length - candidates.length;
+            if (candidates.length > 0) {
+                const messages = await deps.messageService.get(candidates.map((row) => row.messageId));
+                const messageByMessageId = new Map(messages.map((message) => [message.messageId, message]));
+                for (const row of candidates) {
+                    const message = messageByMessageId.get(row.messageId);
+                    if (!message?.bodyStorageKey) {
+                        totals.skippedNoBody++;
+                        continue;
+                    }
+                    const outcome = await deriveAndApplyListId(deps, account.accountConfigId, row, message.bodyStorageKey).then((listId) => ({ error: null, listId }), (error) => ({ error, listId: null }));
+                    if (outcome.error !== null) {
+                        totals.failed++;
+                        failedThreadMessageIds.push(row.threadMessageId);
+                        logger?.error?.({
+                            threadMessageId: row.threadMessageId,
+                            messageId: row.messageId,
+                            error: outcome.error instanceof Error
+                                ? outcome.error.message
+                                : String(outcome.error),
+                        }, "ListId backfill failed for a message; leaving it for a later pass");
+                        continue;
+                    }
+                    if (outcome.listId) {
+                        totals.backfilled++;
+                    }
+                    else {
+                        totals.noListId++;
+                    }
+                }
+            }
+            continuationToken = page.continuationToken;
+            await checkpointStore?.save({
+                accountConfigId: account.accountConfigId,
+                continuationToken,
+            });
+            logger?.info({ accountConfigId: account.accountConfigId, ...totals }, "ListId backfill progress");
+            options.onProgress?.({
+                accountConfigId: account.accountConfigId,
+                ...totals,
+            });
+        } while (continuationToken);
+    }
+    await checkpointStore?.clear();
+    return { ...totals, failedThreadMessageIds };
+};

package/dist/mailbox-cursor-rebuild.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure matching logic for the UIDVALIDITY cursor rebuild (issue #1272).
+ *
+ * Message identity is the Message-ID header; UIDs are cursor positions on
+ * the server's axis. When UIDVALIDITY changes, the axis is gone but the
+ * data isn't — this reconciles a fresh envelope-level snapshot (UID +
+ * Message-ID + INTERNALDATE, no body fetch) against the rows already stored
+ * for the mailbox, by identity rather than by position.
+ */
+/** One server message from the cheap envelope-only rebuild FETCH. */
+export interface CursorRebuildSnapshot {
+    uid: number;
+    /** Raw RFC 822 Message-ID header; empty string when absent/unparseable. */
+    messageId: string;
+    /** INTERNALDATE in epoch milliseconds. */
+    internalDate: number;
+}
+/**
+ * ThreadMessage identity + every composite-key attribute ElectroDB needs to
+ * run a conditional update against the row (see `buildThreadMessageMoveUpdate`
+ * in `message-move.ts` for the same pattern on a normal move). Carried
+ * alongside a {@link CursorRebuildRow} purely so a match can rewrite
+ * ThreadMessage.uid together with Message.uid — matching itself never reads
+ * these fields.
+ */
+export interface CursorRebuildThreadMessageRef {
+    accountConfigId: string;
+    threadMessageId: string;
+    sentDate: number;
+    mailboxId: string;
+    isRead: boolean;
+    isDeleted: boolean;
+    hasStars: boolean;
+    hasAttachment: boolean;
+}
+/** One existing row for the mailbox, as needed to match it against a snapshot. */
+export interface CursorRebuildRow {
+    /** Our internal messageId (the Message row's primary key). */
+    messageId: string;
+    /** Raw RFC 822 Message-ID header the row was created with. */
+    messageIdHeader: string;
+    /** INTERNALDATE in epoch milliseconds. */
+    internalDate: number;
+    /** The row's currently-stored UID (on the old, invalid axis). */
+    uid: number;
+    /** Present when the caller wants a match to also rewrite ThreadMessage.uid. */
+    threadMessage?: CursorRebuildThreadMessageRef;
+}
+export interface CursorRebuildMatch {
+    messageId: string;
+    oldUid: number;
+    newUid: number;
+    /** Carried through from the matched row so the caller can rewrite
+     * ThreadMessage.uid alongside Message.uid without a second lookup. */
+    threadMessage?: CursorRebuildThreadMessageRef;
+}
+export interface CursorRebuildMatchResult {
+    /** Rows whose Message-ID matched a server message under a different UID — rewrite in place. */
+    matched: CursorRebuildMatch[];
+    /** Server UIDs with no matching row — run through normal new-message sync. */
+    newUids: number[];
+    /** Rows with no matching server message — expunged; reconcile (#1283). */
+    staleMessageIds: string[];
+}
+/**
+ * Match a fresh server snapshot against the mailbox's existing rows by
+ * Message-ID, falling back to an exact INTERNALDATE match for the (rare)
+ * messages with no usable Message-ID header on either side — mirrors the
+ * same headerless fallback `message-sync.ts` already uses for threading.
+ *
+ * Pure and side-effect free: the caller is responsible for acting on the
+ * three outcomes (rewrite / new-message sync / reconcile).
+ */
+export declare const matchCursorRebuild: (serverSnapshots: CursorRebuildSnapshot[], existingRows: CursorRebuildRow[]) => CursorRebuildMatchResult;

package/dist/mailbox-cursor-rebuild.js

@@ -0,0 +1,71 @@
+/**
+ * Pure matching logic for the UIDVALIDITY cursor rebuild (issue #1272).
+ *
+ * Message identity is the Message-ID header; UIDs are cursor positions on
+ * the server's axis. When UIDVALIDITY changes, the axis is gone but the
+ * data isn't — this reconciles a fresh envelope-level snapshot (UID +
+ * Message-ID + INTERNALDATE, no body fetch) against the rows already stored
+ * for the mailbox, by identity rather than by position.
+ */
+const pickClosestByInternalDate = (snapshot, candidates, consumed) => {
+    const available = candidates.filter((row) => !consumed.has(row.messageId));
+    if (available.length === 0)
+        return undefined;
+    if (available.length === 1)
+        return available[0];
+    return available.reduce((best, row) => Math.abs(row.internalDate - snapshot.internalDate) <
+        Math.abs(best.internalDate - snapshot.internalDate)
+        ? row
+        : best);
+};
+/**
+ * Match a fresh server snapshot against the mailbox's existing rows by
+ * Message-ID, falling back to an exact INTERNALDATE match for the (rare)
+ * messages with no usable Message-ID header on either side — mirrors the
+ * same headerless fallback `message-sync.ts` already uses for threading.
+ *
+ * Pure and side-effect free: the caller is responsible for acting on the
+ * three outcomes (rewrite / new-message sync / reconcile).
+ */
+export const matchCursorRebuild = (serverSnapshots, existingRows) => {
+    const rowsByHeader = new Map();
+    const rowsByInternalDateOnly = new Map();
+    for (const row of existingRows) {
+        if (row.messageIdHeader) {
+            const list = rowsByHeader.get(row.messageIdHeader) ?? [];
+            list.push(row);
+            rowsByHeader.set(row.messageIdHeader, list);
+        }
+        else {
+            const list = rowsByInternalDateOnly.get(row.internalDate) ?? [];
+            list.push(row);
+            rowsByInternalDateOnly.set(row.internalDate, list);
+        }
+    }
+    const consumed = new Set();
+    const matched = [];
+    const newUids = [];
+    for (const snapshot of serverSnapshots) {
+        const candidates = snapshot.messageId
+            ? (rowsByHeader.get(snapshot.messageId) ?? [])
+            : (rowsByInternalDateOnly.get(snapshot.internalDate) ?? []);
+        const row = pickClosestByInternalDate(snapshot, candidates, consumed);
+        if (!row) {
+            newUids.push(snapshot.uid);
+            continue;
+        }
+        consumed.add(row.messageId);
+        if (row.uid !== snapshot.uid) {
+            matched.push({
+                messageId: row.messageId,
+                oldUid: row.uid,
+                newUid: snapshot.uid,
+                ...(row.threadMessage ? { threadMessage: row.threadMessage } : {}),
+            });
+        }
+    }
+    const staleMessageIds = existingRows
+        .filter((row) => !consumed.has(row.messageId))
+        .map((row) => row.messageId);
+    return { matched, newUids, staleMessageIds };
+};

package/{src/mailbox-cursor.ts → dist/mailbox-cursor.d.ts}

@@ -1,7 +1,5 @@
 import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
-import { MailboxCursorState } from "@remit/domain-enums";
-import type { IImapConnection, ImapBoxStatus } from "./types.js";
-
+import type { IImapConnection } from "./types.js";
 /**
  * Detection + trip for the UIDVALIDITY cursor-integrity state machine (issue
  * #1272, epic #1281 invariant 5): `normal -> cursor_invalid -> rebuilding ->
@@ -18,18 +16,16 @@ import type { IImapConnection, ImapBoxStatus } from "./types.js";
  * UIDVALIDITY right after opening the box, before issuing any command that
  * references a stored UID.
  */
-export type MailboxCursorCheck =
-	| { ok: true }
-	| {
-			ok: false;
-			/** The state the mailbox is (now) in — always non-`normal` here. */
-			state: "cursor_invalid" | "rebuilding";
-	  };
-
+export type MailboxCursorCheck = {
+    ok: true;
+} | {
+    ok: false;
+    /** The state the mailbox is (now) in — always non-`normal` here. */
+    state: "cursor_invalid" | "rebuilding";
+};
 export interface MailboxCursorGuardDeps {
-	mailboxService: Pick<IMailboxRepository, "update">;
+    mailboxService: Pick<IMailboxRepository, "update">;
 }
-
 /**
  * `cursorState` is total per RFC 032 (defaults to `normal`) — but that default
  * only applies to rows written after this field existed. A row persisted
@@ -39,10 +35,6 @@ export interface MailboxCursorGuardDeps {
  * `normal` defensively rather than trusting the type.
  */
 type MailboxCursorStateOrLegacyAbsent = MailboxItem["cursorState"] | undefined;
-
-const isNormal = (state: MailboxCursorStateOrLegacyAbsent): boolean =>
-	state === undefined || state === MailboxCursorState.normal;
-
 /**
  * Compare a mailbox's stored UIDVALIDITY against what the server just served
  * (from an `openBox`/`STATUS` response) and act:
@@ -60,41 +52,11 @@ const isNormal = (state: MailboxCursorStateOrLegacyAbsent): boolean =>
  * (epic #1281 invariant 3), not a fault: log/metric and skip the outbound
  * operation for this round rather than throwing.
  */
-export const guardMailboxCursor = async (
-	deps: MailboxCursorGuardDeps,
-	accountId: string,
-	mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
-		cursorState: MailboxCursorStateOrLegacyAbsent;
-	},
-	servedUidValidity: number,
-): Promise<MailboxCursorCheck> => {
-	if (!isNormal(mailbox.cursorState)) {
-		return {
-			ok: false,
-			state:
-				mailbox.cursorState === MailboxCursorState.rebuilding
-					? "rebuilding"
-					: "cursor_invalid",
-		};
-	}
-
-	if (mailbox.uidValidity !== servedUidValidity) {
-		await deps.mailboxService.update(accountId, mailbox.mailboxId, {
-			cursorState: MailboxCursorState.cursor_invalid,
-		});
-		return { ok: false, state: "cursor_invalid" };
-	}
-
-	return { ok: true };
-};
-
+export declare const guardMailboxCursor: (deps: MailboxCursorGuardDeps, accountId: string, mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
+    cursorState: MailboxCursorStateOrLegacyAbsent;
+}, servedUidValidity: number) => Promise<MailboxCursorCheck>;
 /** True when a mailbox row is in either non-`normal` cursor state. */
-export const isCursorRebuildNeeded = (
-	cursorState: MailboxCursorStateOrLegacyAbsent,
-): boolean =>
-	cursorState === MailboxCursorState.cursor_invalid ||
-	cursorState === MailboxCursorState.rebuilding;
-
+export declare const isCursorRebuildNeeded: (cursorState: MailboxCursorStateOrLegacyAbsent) => boolean;
 /**
  * Thrown by the `openBox` override on a {@link guardConnectionCursor}-wrapped
  * connection when the mailbox cursor is (or just became) non-`normal`. Every
@@ -102,13 +64,10 @@ export const isCursorRebuildNeeded = (
  * guardMailboxCursor} — catch it around the outbound operation and skip
  * (ack/log/return), never let it surface as an infrastructure fault.
  */
-export class MailboxCursorPausedError extends Error {
-	constructor(readonly state: "cursor_invalid" | "rebuilding") {
-		super(`Mailbox cursor is ${state}`);
-		this.name = "MailboxCursorPausedError";
-	}
+export declare class MailboxCursorPausedError extends Error {
+    readonly state: "cursor_invalid" | "rebuilding";
+    constructor(state: "cursor_invalid" | "rebuilding");
 }
-
 /**
  * Wrap a live `IImapConnection` so its `openBox` is the single, structural
  * choke point for UIDVALIDITY cursor guarding (epic #1281 invariants 3 & 5).
@@ -134,44 +93,7 @@ export class MailboxCursorPausedError extends Error {
  * `mailbox` is a snapshot taken once by the caller (they already need it for
  * `mailboxPath`) — not re-fetched per call, so this adds no extra read.
  */
-export const guardConnectionCursor = (
-	connection: IImapConnection,
-	deps: MailboxCursorGuardDeps,
-	accountId: string,
-	mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
-		cursorState: MailboxCursorStateOrLegacyAbsent;
-	},
-): IImapConnection => {
-	const guardedOpenBox = async (
-		mailboxPath: string,
-		readOnly?: boolean,
-	): Promise<ImapBoxStatus> => {
-		if (!isNormal(mailbox.cursorState)) {
-			throw new MailboxCursorPausedError(
-				mailbox.cursorState === MailboxCursorState.rebuilding
-					? "rebuilding"
-					: "cursor_invalid",
-			);
-		}
-
-		const boxStatus = await connection.openBox(mailboxPath, readOnly);
-		const check = await guardMailboxCursor(
-			deps,
-			accountId,
-			mailbox,
-			boxStatus.uidvalidity,
-		);
-		if (!check.ok) {
-			throw new MailboxCursorPausedError(check.state);
-		}
-		return boxStatus;
-	};
-
-	return new Proxy(connection, {
-		get(target, prop, receiver) {
-			if (prop === "openBox") return guardedOpenBox;
-			const value = Reflect.get(target, prop, receiver);
-			return typeof value === "function" ? value.bind(target) : value;
-		},
-	});
-};
+export declare const guardConnectionCursor: (connection: IImapConnection, deps: MailboxCursorGuardDeps, accountId: string, mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
+    cursorState: MailboxCursorStateOrLegacyAbsent;
+}) => IImapConnection;
+export {};