@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/mailbox-management.js

@@ -0,0 +1,576 @@
+import { NotFoundError } from "@remit/data-ports/errors";
+import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { recordedByRename } from "./mailbox-intent.js";
+import { isNotFoundError } from "./mailbox-presence.js";
+import { FolderGoneUpstreamError, FolderRenameSettleError, isMailboxAbsentUpstream, } from "./mailbox-upstream.js";
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+/**
+ * Parse a mailbox path to extract name and parent path
+ */
+export const parseMailboxPath = (path, delimiter = "/") => {
+    const parts = path.split(delimiter);
+    return {
+        name: parts[parts.length - 1],
+        parent: parts.length > 1 ? parts.slice(0, -1).join(delimiter) : null,
+        depth: parts.length,
+    };
+};
+/**
+ * Validate mailbox path for invalid characters and operations
+ */
+export const validateMailboxPath = (path) => {
+    if (!path || path.trim().length === 0) {
+        throw new Error("Mailbox path cannot be empty");
+    }
+    // Check for double delimiters
+    if (path.includes("//")) {
+        throw new Error("Mailbox path cannot contain empty hierarchy levels");
+    }
+    // Check for leading/trailing delimiters
+    if (path.startsWith("/") || path.endsWith("/")) {
+        throw new Error("Mailbox path cannot start or end with hierarchy delimiter");
+    }
+};
+/**
+ * Validate that an operation can be performed on a mailbox path
+ */
+export const validateMailboxOperation = (operation, path) => {
+    if (path.toUpperCase() !== "INBOX")
+        return;
+    // A RENAME of INBOX moves its mail to the new name and leaves an empty INBOX
+    // behind — a bulk move wearing a rename's clothes, which strands the
+    // account's inbox appointment and voids the row's UID cursor (D5). The API
+    // refuses it; this is the backstop for anything that reaches the worker
+    // another way.
+    throw new Error(operation === "delete" ? "Cannot delete INBOX" : "Cannot rename INBOX");
+};
+/**
+ * Whether the server's own listing holds a path this code named.
+ *
+ * The requested string and the path the server keeps are not the same thing.
+ * Under a namespace prefix a Dovecot INBOX namespace stores `Projects` as
+ * `INBOX.Projects`, which is why the settle adopts the path ImapFlow resolved
+ * rather than the one that was asked for (D2) — and a probe comparing the raw
+ * request against the listing would read a folder that is plainly there as
+ * absent. There is no resolved path to adopt on the failure path, so the
+ * account's own prefix stands in for the normalization.
+ */
+const holdsPath = (onServer, mailbox, path) => {
+    if (onServer.has(path))
+        return true;
+    const { namespacePrefix } = mailbox;
+    if (namespacePrefix.length === 0)
+        return false;
+    if (path.startsWith(namespacePrefix))
+        return false;
+    return onServer.has(`${namespacePrefix}${path}`);
+};
+/**
+ * Service for managing mailbox operations (create, rename, delete).
+ *
+ * Implements an optimistic local-first pattern:
+ * 1. Updates are applied locally first
+ * 2. Changes are queued for IMAP sync via SQS
+ * 3. Worker processes queue and syncs to IMAP server
+ */
+export class MailboxManagementService {
+    mailboxService;
+    log;
+    constructor(mailboxService, logger) {
+        this.mailboxService = mailboxService;
+        this.log = logger ?? noopLogger;
+    }
+    /**
+     * Settle a create: `pending` with **no** recorded rename target, which is the
+     * state a create in flight is (D3, D10).
+     *
+     * The absence check is what the whole `wherePendingPath` predicate exists
+     * for. A create whose acknowledgement was lost, redelivered against a row a
+     * rename has since claimed, passes a `pending`-only guard; the CREATE
+     * collides, ImapFlow reports the collision as `{created: false}` rather than
+     * an error, and this write then strands the row `synced` with a rename
+     * target on it — the seventh combination — leaving the rename's own settle
+     * with nothing to match and the RENAME never running.
+     *
+     * A null means the row is gone or the intent moved on. The handlers'
+     * #289-class terminal guards classify the NotFoundError as the user having
+     * deleted the folder mid-sync.
+     */
+    settleCreate = async (accountId, mailboxId, confirmedPath) => {
+        const settled = await this.mailboxService.transition(accountId, mailboxId, {
+            from: [MailboxSyncStatus.pending],
+            wherePendingPath: null,
+            to: MailboxSyncStatus.synced,
+            set: confirmedPath !== undefined ? { fullPath: confirmedPath } : {},
+        });
+        if (settled)
+            return;
+        // Either the row is gone, or a rename claimed it while this create was in
+        // flight. Both resolve the job: the folder exists, and the rename is the
+        // live intent.
+        const current = await this.mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        });
+        if (!current)
+            throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "create",
+            from: current.syncStatus,
+            outcome: "superseded",
+        }, "Folder create superseded");
+    };
+    /**
+     * The rows one rename intent recorded, each with the path it settles to.
+     *
+     * The settle deliberately does not re-resolve the subtree (D15): membership
+     * changes between the intent and the settle — the sweep inserts a row,
+     * another client deletes a descendant — and an all-or-nothing settle then
+     * either throws, poisoning the account's FIFO group (#339), or resolves
+     * leaving every row `pending` forever with no route out, because `failed` is
+     * only reachable from a settle that ran.
+     *
+     * So the rows identify themselves, by the pair `recordedByRename` tests: a
+     * target at or under the rename's target is not on its own enough, because a
+     * second folder renamed under the same branch would be claimed by a rename
+     * that never touched it. A row that appeared afterwards carries no such pair
+     * and is not touched.
+     *
+     * `confirmedPath` re-prefixes each recorded target off the path the rename
+     * actually resolved to, so a normalization the requested string did not carry
+     * moves the whole branch rather than the folder alone.
+     *
+     * `delimiter` is the renamed folder's own, read from the row the caller
+     * already holds — deriving one from whatever the listing happens to contain
+     * strands every descendant when that row has gone.
+     */
+    intentCarryingRows = async (accountId, oldPath, target, confirmed, delimiter) => {
+        const pending = await this.mailboxService.findBySyncStatus(accountId, MailboxSyncStatus.pending);
+        const carrying = [];
+        for (const row of pending) {
+            if (!recordedByRename(row, oldPath, target, delimiter))
+                continue;
+            const confirmedPath = rebaseMailboxPath(row.pendingPath, target, confirmed, delimiter);
+            if (confirmedPath === undefined)
+                continue;
+            carrying.push({ row, confirmedPath });
+        }
+        return carrying;
+    };
+    /**
+     * Sync a CREATE operation to IMAP.
+     * Called by worker after dequeuing MAILBOX_CREATE event.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to create
+     * @param path - Path of the mailbox to create
+     * @param getConnection - Factory to get IMAP connection
+     * @param subscribe - Whether to subscribe after creation
+     */
+    syncCreate = async (accountId, mailboxId, path, getConnection, subscribe) => {
+        const connection = await getConnection();
+        const result = await connection.createMailbox(path);
+        // The server is free to materialize the requested path under a namespace
+        // prefix — a Dovecot INBOX namespace turns "Notifications" into
+        // "INBOX/Notifications". `mailboxCreate` reports the canonical path the
+        // server assigned; adopt it as this row's identity so the next mailbox
+        // reconcile matches it by fullPath and updates it in place, rather than
+        // inserting a fresh row for the prefixed path and deleting this one — which
+        // would strand every filter and placement that references this mailboxId.
+        // Fall back to the requested path when the result carries no usable path,
+        // so a thin result never blanks the row's fullPath to undefined.
+        const serverPath = typeof result.path === "string" && result.path.length > 0
+            ? result.path
+            : path;
+        const confirmedPath = serverPath !== path ? serverPath : undefined;
+        this.log.info({ mailboxId, path, serverPath, created: result.created }, "Created mailbox on IMAP server");
+        if (subscribe) {
+            await connection.subscribeMailbox(serverPath);
+            this.log.info({ mailboxId, path: serverPath }, "Subscribed to mailbox");
+        }
+        const holder = confirmedPath === undefined
+            ? null
+            : await this.mailboxService.findByPath(accountId, confirmedPath);
+        if (holder && holder.mailboxId !== mailboxId) {
+            await this.mailboxService.deleteMailboxWithMail(accountId, mailboxId);
+            this.log.info({
+                accountId,
+                mailboxId,
+                intent: "create",
+                path,
+                serverPath,
+                existingMailboxId: holder.mailboxId,
+                outcome: "already-exists",
+            }, "Folder already exists at the path the server resolved");
+            return {
+                success: true,
+                existing: { mailboxId: holder.mailboxId, fullPath: holder.fullPath },
+            };
+        }
+        // Refresh mailbox list to get UIDVALIDITY and other attributes
+        const mailboxes = await connection.listMailboxes();
+        const mailboxInfo = mailboxes.find((m) => m.fullPath === serverPath);
+        if (mailboxInfo) {
+            // Open the mailbox to get UIDVALIDITY and other status info
+            const status = await connection.openBox(serverPath, true);
+            // Two writes where there was one, and the settle is deliberately the
+            // second: counters are ordinary metadata and stay off the transition,
+            // whose whole point is that its write-set is the state (D3). A crash in
+            // between leaves the row `pending` with fresh counters, and the row not
+            // yet settled is what keeps the queue message unacked — the redelivery
+            // re-issues CREATE, the server answers ALREADYEXISTS, and #339's
+            // classification settles it. Settling first would be the unsafe order.
+            await this.mailboxService.update(accountId, mailboxId, {
+                uidValidity: status.uidvalidity,
+                uidNext: status.uidnext,
+                messageCount: status.messages.total,
+            });
+            await this.settleCreate(accountId, mailboxId, confirmedPath);
+            await connection.closeBox();
+        }
+        else {
+            // Mark as synced even if we couldn't get full info
+            await this.settleCreate(accountId, mailboxId, confirmedPath);
+        }
+        return { success: true };
+    };
+    /**
+     * Sync a RENAME operation to IMAP and settle the rows that recorded it (T5).
+     * Called by worker after dequeuing MAILBOX_RENAME event.
+     *
+     * Guarded on the intent, not on the event (D10): the row must still be
+     * `pending` with this event's target recorded, or the rename resolves with no
+     * IMAP call at all. That is what stops a redelivered MAILBOX_RENAME re-issuing
+     * a RENAME from a path that has already moved.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to rename
+     * @param oldPath - Path the intent was recorded against
+     * @param newPath - Target the intent recorded
+     * @param getConnection - Factory to get IMAP connection
+     */
+    syncRename = async (accountId, mailboxId, oldPath, newPath, getConnection) => {
+        const standing = await this.renameIntentStanding(accountId, mailboxId, newPath);
+        if (!standing)
+            return { success: true };
+        const connection = await getConnection();
+        const delimiter = standing.hierarchyDelimiter;
+        const confirmed = await this.issueRename(connection, standing, accountId, mailboxId, oldPath, newPath);
+        this.log.info({ accountId, mailboxId, intent: "rename", oldPath, newPath, confirmed }, "Renamed mailbox on IMAP server");
+        // The server has executed the rename. Nothing after this point may reach
+        // the caller's failure path: `failRename` would mark the rows refused for
+        // a rename that landed, and the folder would sit at `failed` offering a
+        // retry of something already done. A settle that cannot finish is wrapped
+        // so the caller can tell the two apart, and rethrown so SQS redelivers —
+        // the rows are still `pending` with their targets, so the redelivery's
+        // guard passes and the settle runs again.
+        await this.settleRenameIntent(accountId, mailboxId, oldPath, newPath, confirmed, delimiter).catch((error) => {
+            throw new FolderRenameSettleError(mailboxId, confirmed, error);
+        });
+        return {
+            success: true,
+            renamed: { oldPath, newPath: confirmed, delimiter },
+        };
+    };
+    /**
+     * Issue the RENAME and read back the path it resolved to.
+     *
+     * A `NONEXISTENT` here has three readings, and only one of them may destroy
+     * anything. Either another client deleted the folder; or this rename already
+     * landed and only its settle was lost, in which case the folder is alive at
+     * the target; or the server is saying something this code cannot classify.
+     * The listing separates the first two, and everything it cannot answer is a
+     * refused rename (T6) — a rename that failed costs the user a retry, while
+     * reading an unclear answer as a delete costs them the folder's mail.
+     *
+     * So the caller is told which of the two it is by the *kind* of error, never
+     * by re-reading the server's code: only `FolderGoneUpstreamError` removes a
+     * folder, and it is raised exactly where the listing held neither path.
+     */
+    issueRename = async (connection, standing, accountId, mailboxId, oldPath, newPath) => {
+        const result = await connection
+            .renameMailbox(oldPath, newPath)
+            .catch(async (error) => {
+            if (!isMailboxAbsentUpstream(error))
+                throw error;
+            const listed = await connection
+                .listMailboxes()
+                .catch(() => undefined);
+            // A listing that cannot be read answers nothing, so it decides
+            // nothing: the rename is refused and the folder is left alone.
+            if (!listed)
+                throw error;
+            const onServer = new Set(listed.map((mailbox) => mailbox.fullPath));
+            if (holdsPath(onServer, standing, newPath)) {
+                this.log.info({ accountId, mailboxId, intent: "rename", oldPath, newPath }, "Source folder gone and the target is on the server: this rename already landed");
+                return undefined;
+            }
+            if (holdsPath(onServer, standing, oldPath))
+                throw error;
+            throw new FolderGoneUpstreamError(mailboxId, oldPath, error);
+        });
+        // ImapFlow's own normalization of the requested path — namespace prefix
+        // applied, special names resolved, delimiter joined. IMAP's RENAME reply
+        // carries no path, so this is not the server echoing a name back and it
+        // cannot detect a server that stored a different one; adopting it is still
+        // right, because it fixes the prefix and delimiter drift the requested
+        // string carries (D2).
+        return typeof result?.newPath === "string" && result.newPath.length > 0
+            ? result.newPath
+            : newPath;
+    };
+    /**
+     * Whether the rename this event was enqueued for is still the folder's live
+     * intent. `pending` alone cannot answer it — that state covers a create in
+     * flight too — so the recorded target is half the predicate, and it is the
+     * same predicate the settling write carries, so the guard and the write
+     * cannot disagree between the read and the write.
+     */
+    renameIntentStanding = async (accountId, mailboxId, newPath) => {
+        const row = await this.mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        });
+        if (row &&
+            row.syncStatus === MailboxSyncStatus.pending &&
+            row.pendingPath === newPath) {
+            return row;
+        }
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "rename",
+            from: row?.syncStatus,
+            newPath,
+            outcome: row ? "superseded" : "already-settled",
+        }, "Skipping MAILBOX_RENAME: the recorded intent has moved on");
+        return undefined;
+    };
+    /**
+     * T5, per row (D15): each intent-carrying row adopts its own confirmed path,
+     * drops the recorded target and settles `synced`, on its own conditional
+     * write. A row another client moved in between fails its predicate and is
+     * skipped rather than overwritten; a row that is gone is skipped for free.
+     *
+     * **The named folder is written last, and that ordering is load-bearing.**
+     * The redelivery's guard reads that row and nothing else, so it is the
+     * witness for the whole settle: while it still carries the intent, a
+     * redelivery re-enters and finishes whatever the last attempt left. Settling
+     * it first would ack a run that died part-way through its descendants, and
+     * those rows would stay `pending` forever — invisible to message sync, and
+     * with no route out, because an intent may only be recorded from `synced` or
+     * `failed`, so neither a retry nor a dismissal can reach them.
+     */
+    settleRenameIntent = async (accountId, mailboxId, oldPath, target, confirmed, delimiter) => {
+        const carrying = await this.intentCarryingRows(accountId, oldPath, target, confirmed, delimiter);
+        const ordered = [
+            ...carrying.filter((entry) => entry.row.mailboxId !== mailboxId),
+            ...carrying.filter((entry) => entry.row.mailboxId === mailboxId),
+        ];
+        for (const { row, confirmedPath } of ordered) {
+            const settled = await this.mailboxService.transition(accountId, row.mailboxId, {
+                from: [MailboxSyncStatus.pending],
+                wherePendingPath: row.pendingPath,
+                to: MailboxSyncStatus.synced,
+                set: { fullPath: confirmedPath },
+            });
+            this.log.info({
+                accountId,
+                mailboxId: row.mailboxId,
+                intent: "rename",
+                from: MailboxSyncStatus.pending,
+                to: MailboxSyncStatus.synced,
+                fullPath: confirmedPath,
+                outcome: settled ? "settled" : "superseded",
+            }, "Settled renamed folder");
+        }
+    };
+    /**
+     * T6: the rename did not land, so every row that recorded it goes to
+     * `failed`, keeping its target so the client can name what the rename was
+     * aiming at and offer a retry. Nothing is restored — `fullPath` was never
+     * written, which is the whole point of recording the target instead (D2).
+     */
+    failRename = async (accountId, mailboxId, oldPath, newPath, reason) => {
+        const root = await this.mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        });
+        if (!root)
+            throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+        const carrying = await this.intentCarryingRows(accountId, oldPath, newPath, newPath, root.hierarchyDelimiter);
+        // The row is there and no row carries the intent, so this refusal has
+        // nothing to record. It must not be reported as a missing mailbox: the
+        // caller's #289-class guard reads a NotFoundError as the user having
+        // deleted the folder and acks the message, which would swallow the IMAP
+        // error that brought us here and leave the subtree `pending`. Say so and
+        // let the caller rethrow what actually failed.
+        if (carrying.length === 0) {
+            this.log.error({
+                accountId,
+                mailboxId,
+                intent: "rename",
+                from: root.syncStatus,
+                oldPath,
+                newPath,
+                outcome: "superseded",
+            }, "Refused rename recorded nothing: no row carries this intent");
+            return;
+        }
+        for (const { row } of carrying) {
+            const failed = await this.mailboxService.transition(accountId, row.mailboxId, {
+                from: [MailboxSyncStatus.pending],
+                wherePendingPath: row.pendingPath,
+                to: MailboxSyncStatus.failed,
+                set: { syncFailureReason: reason },
+            });
+            this.log.info({
+                accountId,
+                mailboxId: row.mailboxId,
+                intent: "rename",
+                from: MailboxSyncStatus.pending,
+                to: MailboxSyncStatus.failed,
+                outcome: failed ? "refused" : "superseded",
+            }, "Recorded a refused rename");
+        }
+    };
+    /**
+     * The folder the rename was to move was found gone from the server, and
+     * the target was not there either, so it was deleted by another client
+     * mid-rename (D8). Every row that recorded this rename's intent — the
+     * root and each descendant — goes with its mail, the same walk `failRename`
+     * uses: deleting the root alone strands every descendant `pending` with
+     * nothing left to revisit it, which is the orphaning bug this closes.
+     */
+    abandonRenameSubtree = async (accountId, mailboxId, oldPath, newPath) => {
+        const root = await this.mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        });
+        if (!root) {
+            this.log.info({ accountId, mailboxId, intent: "rename", outcome: "already-settled" }, "Nothing to abandon: the folder row is already gone");
+            return;
+        }
+        const carrying = await this.intentCarryingRows(accountId, oldPath, newPath, newPath, root.hierarchyDelimiter);
+        // A removal that throws part-way abandons the rest into a redelivery, and
+        // that is safe rather than merely tolerable: `deleteMailboxWithMail` is
+        // idempotent — it returns without touching anything when the row is gone,
+        // and resumes from whatever is left when it is not, because the mailbox
+        // row is removed last. The rows still standing carry the intent, so the
+        // next attempt resolves the same set and finishes it.
+        for (const { row } of carrying) {
+            await this.mailboxService.deleteMailboxWithMail(accountId, row.mailboxId);
+            this.log.info({
+                accountId,
+                mailboxId: row.mailboxId,
+                intent: "rename",
+                from: MailboxSyncStatus.pending,
+                to: "deleted",
+            }, "Source mailbox not found, deleted local folder and its mail");
+        }
+    };
+    /**
+     * Sync a DELETE operation to IMAP.
+     * Called by worker after dequeuing MAILBOX_DELETE event.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to delete
+     * @param path - Path of the mailbox to delete
+     * @param getConnection - Factory to get IMAP connection
+     */
+    syncDelete = async (accountId, mailboxId, path, getConnection) => {
+        if (!(await this.deleteIntentStanding(accountId, mailboxId))) {
+            return { success: true };
+        }
+        const connection = await getConnection();
+        await connection.deleteMailbox(path);
+        this.log.info({ accountId, mailboxId, intent: "delete", path }, "Deleted mailbox on IMAP server");
+        await this.settleDelete(accountId, mailboxId);
+        return { success: true };
+    };
+    /**
+     * Whether the delete this event was enqueued for is still the folder's live
+     * intent (D10). Anything else resolves the job with no IMAP call — never a
+     * throw, which would hold back every later job in the account's FIFO group
+     * (#339).
+     */
+    deleteIntentStanding = async (accountId, mailboxId) => {
+        const row = await this.mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return undefined;
+            throw error;
+        });
+        if (row?.syncStatus === MailboxSyncStatus.deleting)
+            return true;
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "delete",
+            from: row?.syncStatus,
+            outcome: row ? "superseded" : "already-settled",
+        }, "Skipping MAILBOX_DELETE: the recorded intent has moved on");
+        return false;
+    };
+    /**
+     * T8: the confirmed delete takes the folder's local mail with it (D8).
+     * Removing the row alone leaves every `message` and `thread_message` row
+     * keyed to a dead mailboxId — out of every reader.
+     *
+     * The removal is batched and the mailbox row goes last, so the row stays
+     * `deleting` throughout and an SQS redelivery re-enters the handler, passes
+     * the guard above, and resumes where it stopped.
+     */
+    settleDelete = async (accountId, mailboxId) => {
+        await this.mailboxService.deleteMailboxWithMail(accountId, mailboxId);
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "delete",
+            from: MailboxSyncStatus.deleting,
+            outcome: "settled",
+        }, "Removed folder and its mail");
+    };
+    /**
+     * T9: the server refused the delete. Nothing is unwound — DELETE is
+     * all-or-nothing, so `fullPath` is still what the server holds, and no rename
+     * target is written, which is how the client tells a failed delete from a
+     * failed rename.
+     */
+    failDelete = async (accountId, mailboxId, reason) => {
+        const failed = await this.mailboxService.transition(accountId, mailboxId, {
+            from: [MailboxSyncStatus.deleting],
+            to: MailboxSyncStatus.failed,
+            set: { syncFailureReason: reason },
+        });
+        if (!failed)
+            throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "delete",
+            from: MailboxSyncStatus.deleting,
+            to: MailboxSyncStatus.failed,
+            outcome: "refused",
+        }, "Recorded a refused delete");
+    };
+}

package/dist/mailbox-presence.d.ts

@@ -0,0 +1,52 @@
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+export declare const isNotFoundError: (error: unknown) => boolean;
+/**
+ * Every state a mailbox row can carry, for a transition whose caller decided
+ * against none of them.
+ *
+ * A transition predicate is supposed to name the state the caller read
+ * (docs/architecture/folder-rename-and-delete.md D3). What still uses this one
+ * is the delete path — its intent recorder and its settle are today's
+ * unconditional writes, moved onto the only door that can write a folder state
+ * at all, and #362 narrows each to the from-set its transition-table row
+ * allows, which is also where its loser gets a 409. The rename path is already
+ * narrowed: `INTENT_RECORDABLE_FROM` for the intent, and `pending` plus the
+ * recorded target for the settle.
+ */
+export declare const EVERY_MAILBOX_STATE: readonly ["synced", "pending", "failed", "deleting"];
+/**
+ * Whether a folder mutation is in flight, so nothing else may touch the folder
+ * over IMAP.
+ *
+ * It used to be spelled as a presence test — is the folder off the server —
+ * and that is no longer what it asks. Under D2 `fullPath` is always a path the
+ * server holds, rename target and all, so a rename-pending folder *is* on the
+ * server; what the two states share is that a worker owns the folder until its
+ * mutation settles. `pending` and `deleting` are written by the request itself,
+ * before the event that resolves it is enqueued, so neither can be observed
+ * unless a create or rename has yet to land or a delete has been asked for.
+ *
+ * This is the terminal test for a sync event whose folder is not the sync's to
+ * touch. The row's absence alone does not decide it, at either end: on the way
+ * out the row is removed only after the IMAP folder is, so an event that fails
+ * against the server still sees a live row for as long as that write takes; on
+ * the way in the row exists before the folder does.
+ *
+ * `failed` is deliberately not one of them. The invariant is that a `failed`
+ * row's folder exists at `fullPath` and the last rename or delete intent did
+ * not land — so the folder holds the user's mail and syncing it is right.
+ * D7 is what upholds that: a create the server refuses leaves no row at all,
+ * rather than a `failed` one standing for a folder that was never made. Reading
+ * `failed` as off-server would stop syncing a live folder permanently and
+ * silently, which is worse than the bounded stall it would remove.
+ *
+ * A rename-pending folder is skipped even though its `fullPath` is live. That
+ * is conservative rather than necessary (D12): it keeps this a single
+ * expression and costs a few seconds of sync for one folder.
+ *
+ * Mailbox management is judged differently — it is what establishes and removes
+ * the folder, so it terminates on a not-found row alone.
+ */
+export declare const isFolderMutationInFlight: (mailbox: Pick<MailboxItem, "syncStatus">) => boolean;
+/** {@link isFolderMutationInFlight} for a mailbox that has to be read first, an absent row included. */
+export declare const isMailboxMutationInFlight: (mailboxService: Pick<IMailboxRepository, "get">, accountId: string, mailboxId: string) => Promise<boolean>;