@wirecat/cli-core 0.486.0 → 0.488.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ shape of this file.
 
 ## Unreleased
 
+## 0.488.0 — 30.10.2026
+
+### Added
+
+- **A quick mail sync proves deletions and refreshes flags again (store version 39).** The store keeps each email's
+  place on an IMAP server (`email_locations`: folder, UIDVALIDITY, UID), saved with the email, so a run that lists only
+  UIDs and flags can tell which stored mail the server dropped and which flags changed, without reading the mail. The
+  first run on mail stored before this lists the folder once with headers to record the places; after that the folder
+  is quick. A new UIDVALIDITY drops the folder's places. New `store.mail.folderEmails`, `setLocations` and
+  `forgetLocations`, and `locations` on `EmailInput`.
+
+## 0.487.0 — 30.10.2026
+
+### Added
+
+- **A messenger can say what `reactions list` covers.** The new `reactionsListScope` option on the messenger (for
+  WhatsApp, "reactions received while this computer was syncing") adds `missing: [{ field: "reactions", why }]` to the
+  JSON answer and one line on stderr for a person: "shows only …". A messenger that sets none answers as before.
+- **Mail from a server with no cheap message id (Yandex) syncs from a listing of UID, flags, date and size.** A header
+  FETCH of 200 messages took 5 to 40 s there and often failed, so six months took hours. A `MailSource` can now answer
+  `quick: true` from `search` and give `quick` and `identify`; `syncMail` then lists only the UIDs not done, reads the
+  raw bytes of the new ones and takes the id from the Message-ID, so stored mail keeps its id and nothing stored is read
+  again. Rules and the bulk class run on the downloaded headers. A new UIDVALIDITY, other rules or `rescan` list the
+  folder with headers as before; a quick run proves no deletion and refreshes no flags of the mail it skips.
+  `mailSourceContract` checks that `quick` and `identify` agree with `list`; `fakeMailSource` takes `quick: true`.
+
 ## 0.486.0 — 30.10.2026
 
 ### Fixed

package/dist/cli/messenger/context.d.ts

@@ -84,6 +84,8 @@ export interface Messenger extends ServiceMessenger {
     pollCloseSeconds?: readonly [min: number, max: number];
     /** Whether `reactions list` shows who reacted to a message; no when unset. */
     reactionsList?: boolean;
+    /** What `reactions list` covers when it is less than everyone who reacted, as the end of "shows only …", such as "reactions received while this computer was syncing"; none when unset. */
+    reactionsListScope?: string;
     /** Whether `polls voters` lists who voted for what; no when unset. */
     pollVoters?: boolean;
     /** Whether a poll can be closed — `polls close`; yes when unset. WhatsApp's stay open. */

package/dist/cli/messenger/reactions-command.js

@@ -33,6 +33,7 @@ export const reactionsCommand = (messenger) => {
                     ...(cursor === undefined ? {} : { cursor }),
                 });
             });
+            const why = messenger.reactionsListScope === undefined ? undefined : `shows only ${messenger.reactionsListScope}`;
             renderAnswer(this, context, listOf("reactions list", {
                 items: found.items.map(reactorAnswer),
                 limit,
@@ -40,7 +41,10 @@ export const reactionsCommand = (messenger) => {
                 paging: "cursor",
                 ...(found.cursor === undefined ? {} : { cursor: found.cursor }),
                 args: { chat, message, ...(words.length > 0 ? { query: words.join(" ") } : {}) },
+                ...(why === undefined ? {} : { missing: [{ field: "reactions", why }] }),
             }), lines(({ reacted_at, person, reaction: name }) => [reacted_at, person.name ?? person.id, name].join("  ")));
+            if (why !== undefined && context.format !== "json")
+                context.renderer.note(why);
         }));
     annotate(reactions.command("add"), {
         effects: REMOTE_WRITE,

package/dist/cli/messenger/serve-relay.d.ts

@@ -45,6 +45,7 @@ export declare const serveRelay: (command: Command, messenger: Messenger) => {
         pollQuiz?: boolean;
         pollCloseSeconds?: readonly [min: number, max: number];
         reactionsList?: boolean;
+        reactionsListScope?: string;
         pollVoters?: boolean;
         pollClose?: boolean;
         pollRevote?: boolean;

package/dist/mail/attachments.d.ts

@@ -0,0 +1,15 @@
+import type { LoadEngine } from "../readers/types.js";
+import type { AttachmentInput, EmailAddress } from "../store/index.js";
+import type { Address, ParsedMail } from "./parse.js";
+import type { MailSyncResult } from "./sync.js";
+export declare const MAX_ATTACHMENT_CHARS = 200000;
+/** One chunk of raw mail is held in memory at a time. */
+export declare const FETCH_CHUNK = 50;
+export declare const addressOf: ({ email, name }: Address) => EmailAddress;
+export type AttachmentLog = NonNullable<MailSyncResult["attachments"]>;
+/** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
+export declare const readAttachments: (mail: ParsedMail, messageId: string, { loadEngine, maxAttachmentChars, at }: {
+    loadEngine: LoadEngine;
+    maxAttachmentChars: number;
+    at: number;
+}, log: AttachmentLog) => Promise<AttachmentInput[]>;

package/dist/mail/attachments.js

@@ -0,0 +1,38 @@
+import { extractText } from "../attachments/extract.js";
+export const MAX_ATTACHMENT_CHARS = 200_000;
+/** One chunk of raw mail is held in memory at a time. */
+export const FETCH_CHUNK = 50;
+export const addressOf = ({ email, name }) => ({ address: email, name });
+/** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
+export const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at }, log) => {
+    const files = [];
+    for (const [position, part] of mail.attachments.entries()) {
+        const extraction = part.bytes === null
+            ? { status: "unavailable" }
+            : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine);
+        log.push({ message: messageId, part: part.id, status: extraction.status });
+        const extracted = extraction.status === "extracted" ? extraction : undefined;
+        files.push({
+            position,
+            kind: "file",
+            mime: part.mime,
+            name: part.name,
+            title: null,
+            url: null,
+            size: part.bytes === null ? null : part.bytes.byteLength,
+            width: null,
+            height: null,
+            duration: null,
+            providerRef: { message: messageId, part: part.id },
+            localPath: null,
+            text: extracted ? extracted.text.slice(0, maxAttachmentChars) : null,
+            normalizedText: null,
+            extraction: extracted ? "text" : "failed",
+            extractor: extracted ? extracted.extractor : null,
+            extractionError: extracted ? null : extraction.status,
+            contentSha256: null,
+            extractedAt: at,
+        });
+    }
+    return files;
+};

package/dist/mail/headers.d.ts

@@ -36,6 +36,8 @@ export declare const authOf: (unfolded: string) => AuthVerdicts | undefined;
 export declare const addressesOf: (value: string | undefined) => string[];
 /** The header fields of one email, from its header text. */
 export declare const headersOf: (text: string) => MailHeaders;
+/** The header fields of a whole email, as `headersOf` reads them from a listing. */
+export declare const headersOfRaw: (raw: Uint8Array) => MailHeaders;
 /**
  * List-Id, the bulk-mail fields, Reply-To and Gmail's SPF, DKIM and DMARC verdicts of a whole email, kept on mail
  * stored in full so a rule or a sender score can be worked out from the store later. Names are lower case.

package/dist/mail/headers.js

@@ -66,15 +66,19 @@ export const headersOf = (text) => {
         ...(/^\s*multipart\/mixed\b/i.test(field(unfolded, "Content-Type") ?? "") ? { attachments: true } : {}),
     };
 };
+const headTextOf = (raw) => {
+    const bytes = Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
+    const end = [bytes.indexOf("\r\n\r\n"), bytes.indexOf("\n\n")].filter((at) => at !== -1);
+    return bytes.subarray(0, end.length ? Math.min(...end) : Math.min(bytes.length, 256 * 1024)).toString("utf8");
+};
+/** The header fields of a whole email, as `headersOf` reads them from a listing. */
+export const headersOfRaw = (raw) => headersOf(headTextOf(raw));
 /**
  * List-Id, the bulk-mail fields, Reply-To and Gmail's SPF, DKIM and DMARC verdicts of a whole email, kept on mail
  * stored in full so a rule or a sender score can be worked out from the store later. Names are lower case.
  */
 export const mailHeadersOf = (raw) => {
-    const bytes = Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
-    const end = [bytes.indexOf("\r\n\r\n"), bytes.indexOf("\n\n")].filter((at) => at !== -1);
-    const head = bytes.subarray(0, end.length ? Math.min(...end) : Math.min(bytes.length, 256 * 1024));
-    const unfolded = unfold(head.toString("utf8"));
+    const unfolded = unfold(headTextOf(raw));
     const listId = listIdOf(field(unfolded, "List-Id"));
     const precedence = field(unfolded, "Precedence")?.trim().toLowerCase();
     const [replyTo] = addressesOf(field(unfolded, "Reply-To"));

package/dist/mail/index.d.ts

@@ -12,6 +12,6 @@ export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./
 export { conditionKeys, decide, describeMatch, ENVELOPE, envelopeBox, envelopeBoxOf, type MailAction, type MailFacts, type MailRule, type MailRuleMatch, matches, sameMatch, tagsOf, } from "./rules.js";
 export { type DomainAge, FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, type Scored, type Signal, scoreGroup, WEIGHTS, } from "./score.js";
 export { DEMOTE_AT, type DomainAges, demotedSenders, type LookupResult, SCORE_VERSION, scoreSenders, } from "./sender-scores.js";
-export type { Listed, MailSource, Searched } from "./source.js";
+export type { Listed, MailSource, Quick, Searched } from "./source.js";
 export { listedOf, type StoredMail } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, type MailAccount, type MailIndexed, type MailSyncOptions, type MailSyncResult, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/locations.d.ts

@@ -0,0 +1,28 @@
+import type { FolderEmail, MessageStore } from "../store/index.js";
+import type { Quick, Searched } from "./source.js";
+/** The flags a listing shows that differ from the stored ones, by Message-ID, for mail whose UID is stored. */
+export declare const flagsToRefresh: (rows: ReadonlyMap<string, FolderEmail>, listing: readonly Quick[]) => Map<string, {
+    read?: boolean;
+    flagged?: boolean;
+}>;
+export interface LocationProof {
+    /** Each folder listed by UID: what the server searched, and the stored mail with a UID there, before this run saved. */
+    folders: ReadonlyMap<string, {
+        searched: Searched;
+        rows: readonly FolderEmail[];
+    }>;
+    /** Mail received before this is outside the window IMAP's SINCE can vouch for. */
+    windowFrom: number;
+    /** Messages this run saw in any folder: one moved to another folder is not gone. */
+    present: ReadonlySet<string>;
+    now: number;
+}
+/**
+ * A folder listed by UID proves a deletion from the UIDs it stores: mail in the window whose UID the server no
+ * longer lists is gone from that folder, and gone altogether when no other location of it is left. Nothing is
+ * changed when too many would go, as for a header listing.
+ */
+export declare const proveByLocation: (store: MessageStore, accountId: number, { folders, windowFrom, present, now }: LocationProof, refuse: (gone: number, candidates: number) => string | undefined) => Promise<{
+    deleted: number;
+    skipped?: string;
+}>;

package/dist/mail/locations.js

@@ -0,0 +1,54 @@
+/** The flags a listing shows that differ from the stored ones, by Message-ID, for mail whose UID is stored. */
+export const flagsToRefresh = (rows, listing) => {
+    const changes = new Map();
+    for (const { uid, seen, flagged } of listing) {
+        const row = rows.get(uid);
+        if (row === undefined)
+            continue;
+        const changed = {
+            ...(seen === undefined || seen === row.read ? {} : { read: seen }),
+            ...(flagged === undefined || flagged === row.flagged ? {} : { flagged }),
+        };
+        if (Object.keys(changed).length)
+            changes.set(row.externalId, changed);
+    }
+    return changes;
+};
+/**
+ * A folder listed by UID proves a deletion from the UIDs it stores: mail in the window whose UID the server no
+ * longer lists is gone from that folder, and gone altogether when no other location of it is left. Nothing is
+ * changed when too many would go, as for a header listing.
+ */
+export const proveByLocation = async (store, accountId, { folders, windowFrom, present, now }, refuse) => {
+    const candidates = new Set();
+    const lost = new Map();
+    const lostUids = new Map();
+    for (const [folder, { searched, rows }] of folders) {
+        const inWindow = new Set(searched.uids.map(Number));
+        for (const row of rows) {
+            if (row.receivedAt === null || row.receivedAt < windowFrom)
+                continue;
+            candidates.add(row.externalId);
+            if (inWindow.has(row.uid))
+                continue;
+            const entry = lost.get(row.externalId) ?? { row, locations: 0, folders: new Set() };
+            entry.locations++;
+            entry.folders.add(folder);
+            lost.set(row.externalId, entry);
+            const uids = lostUids.get(folder) ?? [];
+            uids.push(row.uid);
+            lostUids.set(folder, uids);
+        }
+    }
+    const gone = [...lost]
+        .filter(([id, entry]) => !present.has(id) && entry.locations === entry.row.locations && entry.folders.size >= entry.row.folders)
+        .map(([id]) => id);
+    const refused = refuse(gone.length, candidates.size);
+    if (refused)
+        return { deleted: 0, skipped: refused };
+    // Marked first: an interruption leaves locations that prove it again, never an email with no way to be found.
+    const deleted = gone.length ? await store.mail.markDeleted(accountId, gone, now) : 0;
+    for (const [folder, uids] of lostUids)
+        await store.mail.forgetLocations(accountId, folder, folders.get(folder).searched.validity, uids);
+    return { deleted };
+};

package/dist/mail/quick.d.ts

@@ -0,0 +1,41 @@
+import type { BudgetStop, RunBudget } from "../background/budget.js";
+import { type Ranges } from "./resume.js";
+import type { Listed, MailSource, Quick, Searched } from "./source.js";
+export declare const FETCH_SLICE = 50;
+export declare const keyOf: (folder: string, uid: string) => string;
+/** What a budgeted run carries from round to round that a quick folder also reads and writes. */
+export interface QuickPlan {
+    budget: RunBudget;
+    /** UIDs a round already asked for, `folder\0uid`. */
+    tried: Set<string>;
+    /** Messages the source could not give; asked for once more when the pass is over. */
+    failed: Set<string>;
+    unlisted: Set<string>;
+    /** Only these are asked for: the retry pass. */
+    only?: Set<string>;
+    /** Each quick folder's listing of what was not done, made once; a round takes the next newest of it. */
+    quick: Map<string, Quick[]>;
+    stopped: BudgetStop | null;
+    remaining: number;
+    asked: number;
+}
+export interface QuickRead {
+    /** Every message of the window the server listed, done or not: its flags refresh the stored mail. */
+    listing: Quick[];
+    /** Messages read and identified, with their raw bytes so the save does not read them again. */
+    read: {
+        item: Listed;
+        raw: Uint8Array;
+    }[];
+    unreadable: {
+        message: string;
+        reason: string;
+    }[];
+    /** Mail of the folder is left for a later round or run. */
+    capped: boolean;
+}
+/**
+ * One round of a folder whose server gives no cheap message id: UID, flags, date and size of what is not done, then
+ * the raw bytes of the newest of it, whose Message-ID gives the id the full listing would have given.
+ */
+export declare const readQuick: (source: MailSource & Required<Pick<MailSource, "quick" | "identify">>, since: Date, folder: string, searched: Searched, done: Ranges, max: number, plan: QuickPlan | undefined, located: ReadonlySet<string>) => Promise<QuickRead>;

package/dist/mail/quick.js

@@ -0,0 +1,76 @@
+import { headersOfRaw } from "./headers.js";
+import { within } from "./resume.js";
+export const FETCH_SLICE = 50;
+export const keyOf = (folder, uid) => `${folder}\0${uid}`;
+/**
+ * One round of a folder whose server gives no cheap message id: UID, flags, date and size of what is not done, then
+ * the raw bytes of the newest of it, whose Message-ID gives the id the full listing would have given.
+ */
+export const readQuick = async (source, since, folder, searched, done, max, plan, located) => {
+    const answer = { listing: [], read: [], unreadable: [], capped: false };
+    let items = plan?.quick.get(folder);
+    if (items === undefined) {
+        // Mail whose location is known is listed for its flags only; it is never read again.
+        const asked = searched.uids.filter((uid) => plan?.only === undefined || plan.only.has(keyOf(folder, uid)));
+        const wanted = asked.filter((uid) => !within(done, Number(uid)) && !located.has(uid));
+        if (asked.length > 0 && plan) {
+            const stop = plan.budget.take();
+            if (stop) {
+                plan.stopped = stop;
+                plan.remaining += wanted.length;
+                return { ...answer, capped: true };
+            }
+        }
+        items = asked.length === 0 ? [] : await source.quick(since, folder, { searched: { ...searched, uids: asked } });
+        if (plan !== undefined) {
+            plan.quick.set(folder, items);
+            const got = new Set(items.map(({ uid }) => uid));
+            for (const uid of wanted)
+                if (!got.has(uid)) {
+                    plan.failed.add(keyOf(folder, uid));
+                    plan.unlisted.add(keyOf(folder, uid));
+                }
+        }
+    }
+    answer.listing = items;
+    const open = items
+        .filter(({ uid }) => !within(done, Number(uid)) && !located.has(uid) && !plan?.tried.has(keyOf(folder, uid)))
+        .sort((a, b) => Number(b.uid) - Number(a.uid));
+    const slice = open.slice(0, plan === undefined ? max : (source.fetchBatch ?? FETCH_SLICE));
+    if (plan !== undefined)
+        plan.remaining += open.length - slice.length;
+    answer.capped = open.length > slice.length;
+    if (slice.length === 0)
+        return answer;
+    if (plan !== undefined) {
+        const stop = plan.budget.take();
+        if (stop) {
+            plan.stopped = stop;
+            plan.remaining += slice.length;
+            return { ...answer, capped: true };
+        }
+        for (const { uid } of slice)
+            plan.tried.add(keyOf(folder, uid));
+        plan.asked += slice.length;
+    }
+    const raws = await source.fetchRaw(slice);
+    // Every email failing is the connection or the login, not the mail: stop instead of trying the rest.
+    if (slice.length > 1 && raws.every((raw) => raw instanceof Error))
+        throw raws[0];
+    for (const [index, item] of slice.entries()) {
+        const raw = raws[index];
+        const key = keyOf(folder, item.uid);
+        if (raw === undefined || raw instanceof Error) {
+            if (plan === undefined)
+                answer.unreadable.push({ message: `uid:${folder}:${item.uid}`, reason: raw?.message ?? "not read" });
+            else {
+                plan.failed.add(key);
+                plan.unlisted.add(key);
+            }
+            continue;
+        }
+        plan?.unlisted.delete(key);
+        answer.read.push({ item: { ...item, ...source.identify(raw, item), headers: headersOfRaw(raw) }, raw });
+    }
+    return answer;
+};

package/dist/mail/resume.d.ts

@@ -30,6 +30,12 @@ export interface ResumePoint {
         total: number;
         at: string;
     };
+    /**
+     * From this date on, every stored email of the folder has its UID in `email_locations`: a listing that gives UIDs
+     * and flags is enough to refresh flags and prove deletions. Absent after an engine that did not know locations
+     * wrote the point, and then one header listing records them.
+     */
+    located?: string;
     /** What the latest run listed, whatever its window. */
     last?: {
         since: string;

package/dist/mail/retry.d.ts

@@ -0,0 +1,23 @@
+import type { LoadEngine } from "../readers/types.js";
+import type { MessageStore } from "../store/index.js";
+import type { MailSource } from "./source.js";
+import type { MailAccount, MailSyncOptions, MailSyncResult } from "./sync.js";
+/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
+export declare const RETRYABLE_ATTACHMENTS: string[];
+/**
+ * Reads again, by Gmail id, only the stored emails with an attachment a missing reader left unread: memo keeps no
+ * attachment file, so the email comes from the source again. Nothing is listed, so no deletion is proved and no
+ * resume point moves; the email keeps its stored mailboxes, flags and rule.
+ */
+export declare const retryUnread: ({ store, source, account, since, max, maxBodyChars, maxAttachmentChars, now, loadEngine, index, }: {
+    store: MessageStore;
+    source: MailSource;
+    account: MailAccount;
+    since: Date;
+    max: number;
+    maxBodyChars: number;
+    maxAttachmentChars: number;
+    now: () => number;
+    loadEngine: LoadEngine;
+    index: MailSyncOptions["index"];
+}) => Promise<MailSyncResult>;

package/dist/mail/retry.js

@@ -0,0 +1,110 @@
+import { CliError } from "@wirecat/cli-base";
+import { addressOf, FETCH_CHUNK, readAttachments } from "./attachments.js";
+import { mailFolders } from "./folders.js";
+import { mailHeadersOf } from "./headers.js";
+import { parseMail } from "./parse.js";
+/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
+export const RETRYABLE_ATTACHMENTS = ["engine-missing"];
+/**
+ * Reads again, by Gmail id, only the stored emails with an attachment a missing reader left unread: memo keeps no
+ * attachment file, so the email comes from the source again. Nothing is listed, so no deletion is proved and no
+ * resume point moves; the email keeps its stored mailboxes, flags and rule.
+ */
+export const retryUnread = async ({ store, source, account, since, max, maxBodyChars, maxAttachmentChars, now, loadEngine, index, }) => {
+    const startedAt = now();
+    const key = { provider: "email", account: account.address.toLowerCase() };
+    const find = source.find;
+    if (find === undefined)
+        throw new CliError("validation_error", "--retry-attachments reads mail again by its Gmail id; an mbox file or a plain IMAP account has none");
+    const accountId = await store.accounts.saveAccount(key, { name: account.address });
+    const wanted = (await store.mail.emailRefs({ accountId, attachmentErrors: RETRYABLE_ATTACHMENTS })).map(({ externalId }) => externalId);
+    const chosen = wanted.slice(0, max);
+    const found = new Map();
+    for (const folder of await mailFolders(account, source)) {
+        const left = chosen.filter((id) => !found.has(id));
+        if (left.length === 0)
+            break;
+        for (const item of await find(left, folder))
+            if (!found.has(item.messageId))
+                found.set(item.messageId, item);
+    }
+    const items = [...found.values()];
+    const attachments = [];
+    const unreadable = [];
+    let emails = 0;
+    let extracted = 0;
+    let stillFailed = 0;
+    for (let start = 0; start < items.length; start += FETCH_CHUNK) {
+        const chunk = items.slice(start, start + FETCH_CHUNK);
+        const raws = await source.fetchRaw(chunk);
+        for (const [index, item] of chunk.entries()) {
+            const raw = raws[index];
+            const stored = await store.mail.email(accountId, item.messageId);
+            if (stored === null)
+                continue;
+            let mail;
+            try {
+                if (raw === undefined || raw instanceof Error)
+                    throw raw ?? new Error("not read");
+                mail = await parseMail(raw, maxBodyChars);
+            }
+            catch (error) {
+                unreadable.push({ message: item.messageId, reason: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            const before = new Map(stored.attachments.map(({ position, extractionError }) => [position, extractionError]));
+            const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt }, attachments);
+            for (const file of files)
+                if (RETRYABLE_ATTACHMENTS.includes(before.get(file.position) ?? ""))
+                    if (file.extraction === "text")
+                        extracted++;
+                    else
+                        stillFailed++;
+            const header = mailHeadersOf(raw);
+            await store.mail.saveThread({
+                accountId,
+                externalId: item.threadId,
+                now: startedAt,
+                emails: [
+                    {
+                        externalId: item.messageId,
+                        subject: mail.subject,
+                        from: mail.from === null ? null : addressOf(mail.from),
+                        to: mail.to.map(addressOf),
+                        cc: mail.cc.map(addressOf),
+                        bcc: mail.bcc.map(addressOf),
+                        sentAt: null,
+                        receivedAt: Date.parse(item.receivedAt),
+                        bodyText: mail.text || null,
+                        size: item.size ?? stored.size,
+                        ...(Object.keys(header).length ? { headers: header } : {}),
+                        outgoing: mail.from === null ? null : mail.from.email === key.account,
+                        mailboxes: stored.mailboxes.map(({ externalId, name, kind }) => ({ externalId, name, kind })),
+                        ...(stored.read === null ? {} : { read: stored.read }),
+                        ...(stored.flagged === null ? {} : { flagged: stored.flagged }),
+                        metadata: stored.metadata,
+                        mailRuleId: stored.mailRuleId,
+                        attachments: files,
+                    },
+                ],
+            });
+            emails++;
+        }
+    }
+    const indexed = await index?.(store, key);
+    return {
+        account: key.account,
+        since: since.toISOString(),
+        listed: items.length,
+        saved: 0,
+        alreadyStored: 0,
+        skipped: 0,
+        envelopes: 0,
+        deleted: 0,
+        complete: wanted.length <= max && unreadable.length === 0,
+        ...(indexed === undefined ? {} : { indexed }),
+        retried: { emails, extracted, stillFailed, missing: chosen.length - items.length },
+        ...(attachments.length ? { attachments } : {}),
+        ...(unreadable.length ? { unreadable } : {}),
+    };
+};

package/dist/mail/source.d.ts

@@ -16,10 +16,17 @@ export interface Listed {
     /** Read only when asked for; absent when not asked or unreadable, so no rule applies to it. */
     headers?: MailHeaders;
 }
+/** A message as `quick` lists it: everything but the ids, which a source without a cheap one reads from the raw bytes. */
+export type Quick = Omit<Listed, "messageId" | "threadId">;
 export interface Searched {
     /** Absent when the server does not say; then no UID is trusted across runs. */
     validity?: string;
     uids: string[];
+    /**
+     * The server gives no message id without reading the message, so `list` is slow. The sync then lists with `quick`
+     * and takes the id from the raw bytes with `identify`.
+     */
+    quick?: boolean;
 }
 /** Everything the import asks of a mail client, so a transport can be replaced without touching the sync. */
 export interface MailSource {
@@ -43,6 +50,18 @@ export interface MailSource {
      * those. Absent for a file, which has no UIDs.
      */
     search?(since: Date, folder: string): Promise<Searched>;
+    /**
+     * For a folder whose `search` said `quick`: UID, flags, date and size of the given UIDs, with no envelope and no
+     * header. A UID the server does not return is left out.
+     */
+    quick?(since: Date, folder: string, options: {
+        searched: Searched;
+    }): Promise<Quick[]>;
+    /** The ids of a message read by `fetchRaw`, worked out as `list` works them out; needed wherever `quick` is. */
+    identify?(raw: Uint8Array, item: Quick): {
+        messageId: string;
+        threadId: string;
+    };
     /** A file's size and modification time, so an unchanged file read to the end is not read again. */
     stamp?(): Promise<FileStamp>;
     /**
@@ -70,5 +89,5 @@ export interface MailSource {
     /** Puts labels back on messages in `folder`, by Gmail id. */
     label?(messageIds: readonly string[], folder: string, labels: readonly string[]): Promise<void>;
     /** Each item's raw RFC 5322 bytes, in order; one that could not be read is an Error, not a failed call. */
-    fetchRaw(items: Listed[]): Promise<(Uint8Array | Error)[]>;
+    fetchRaw(items: Quick[]): Promise<(Uint8Array | Error)[]>;
 }

package/dist/mail/sync.d.ts

@@ -74,7 +74,8 @@ export interface MailSyncResult {
         missing: number;
     };
 }
-export declare const MAX_ATTACHMENT_CHARS = 200000;
+export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
+export { RETRYABLE_ATTACHMENTS } from "./retry.js";
 export interface MailSyncOptions {
     account: MailAccount;
     since: Date;
@@ -102,5 +103,3 @@ export interface MailSyncOptions {
     budget?: RunBudget;
 }
 export declare const syncMail: (source: MailSource, store: MessageStore, options: MailSyncOptions) => Promise<MailSyncResult>;
-/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
-export declare const RETRYABLE_ATTACHMENTS: string[];