@wirecat/cli-core 0.545.0 → 0.547.0

package/dist/errors/reasons.js

@@ -29,6 +29,8 @@ const SIGN_IN = [
     ["oauth.revoke-failed", "outcome_unknown", "the provider did not confirm the revoke"],
     ["oauth.invalid", "authentication_error", "the saved sign-in cannot be read"],
     ["oauth.not-saved", "configuration_error", "the sign-in cannot be saved or read where it is kept"],
+    ["sign-in.client-file-open", "configuration_error", "other users of this computer can read the client file"],
+    ["sign-in.client-file-invalid", "configuration_error", "the file is not a Desktop app OAuth client JSON"],
 ];
 const OTHERS = [
     ["model.offline", "permission_error", "downloading a model needs the network; --offline was requested"],
@@ -78,6 +80,17 @@ const OTHERS = [
     validation("ics.too-many", "the file holds more events than one import sends"),
     validation("ics.too-large", "the file is larger than one import reads"),
     ["calendar.read-only", "permission_error", "the calendar takes no new events from this account"],
+    validation("feed.address-invalid", "a feed address is an http, https or webcal URL with no user or password in it"),
+    validation("feed.duplicate", "this profile follows a feed at this address already"),
+    validation("feed.not-a-feed", "the calendar is not a feed this profile follows"),
+    validation("feed.too-large", "the feed is larger than one sync reads"),
+    validation("feed.redirect-refused", "the feed sent the request on to an address that is not https"),
+    ["feed.no-address", "configuration_error", "the feed's address is no longer kept on this computer"],
+    ["feed.refused", "provider_error", "the feed's server refused the request"],
+    ["feed.gone", "not_found", "the feed's server has no feed at this address any more"],
+    ["feed.timeout", "timeout", "the feed's server did not answer in time"],
+    ["feed.unreachable", "network_error", "the feed's server could not be reached"],
+    validation("busy.feed", "a feed calendar has no busy times to ask; read its events with events list"),
     ["calendar.unsynced", "not_found", "the calendar account has no synced calendar in the store"],
     ["calendar.sync-incomplete", "not_found", "a synced calendar's sync never finished or is mid-round"],
     ["calendar.no-upcoming", "not_found", "no upcoming meeting with other attendees is stored for this account"],
@@ -97,7 +110,11 @@ const OTHERS = [
     ["search.server-failed", "provider_unavailable", "the server did not answer a search"],
     ["search.server-timeout", "timeout", "the server did not answer within --server-time"],
     ["search.server-capped", "outcome_unknown", "the server found more than one search reads, or a branch was not sent"],
-    ["search.server-too-large", "outcome_unknown", "a message the server found is too large to download during a search"],
+    [
+        "search.server-partial",
+        "outcome_unknown",
+        "a message the server found was stored without its attachments; the next sync reads it whole",
+    ],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
     [
@@ -132,7 +149,20 @@ const OTHERS = [
     validation("name.taken", "the name is already used"),
     validation("period.ambiguous", "the period can be read more than one way"),
     validation("proposal.wrong-state", "the proposal is not in a state that allows this"),
+    validation("proposal.reason-required", "an agent deciding for the owner gives a reason"),
+    validation("proposal.decider-required", "a decision names who decides: the owner or an agent with a reason"),
+    validation("proposal.ids", "the proposal ids cannot be read"),
+    ["proposal.own", "permission_error", "an agent never decides its own proposal"],
+    ["proposal.owner-only", "permission_error", "only the owner decides this proposal"],
+    ["proposals.agent-decisions-off", "permission_error", "agent decisions are turned off; the owner decides"],
+    ["proposal.unknown-kind", "not_found", "no registered proposal kind holds this id"],
+    validation("relationship.exists", "a confirmed relationship already links them"),
     validation("ranking.invalid", "the ranking is not valid"),
+    validation("ref.malformed", "the reference has a known kind but not its shape"),
+    validation("ref.unknown-kind", "the text names no kind of reference"),
+    validation("ref.wrong-kind", "the reference names another kind of thing than the argument takes"),
+    validation("ref.wrong-provider", "the reference belongs to another messenger; open it with that CLI"),
+    validation("ref.wrong-account", "the reference belongs to another account than this profile's"),
     validation("selection.changed", "the stored selection changed meanwhile"),
     validation("selection.invalid", "the selection is not valid"),
     validation("search.kind", "the saved search belongs to another kind of search: messages or meetings"),

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, type Kind, kindIn, k
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";
 export type { RankingComponent, RankingInput, RankingMeasure, RankingOptions, RankingTarget, RankingWeights, ScorePreset, } from "./domain/rankings-options.js";
 export { rankingOptions } from "./domain/rankings-options.js";
-export { canonicalReference, formatReference, parseReference, type Reference } from "./domain/references.js";
+export { canonicalReference, formatReference, looksLikeReference, parseReference, REF_KINDS, type Reference, type RefKindName, type RefKindSpec, } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES, type TagType } from "./domain/tags.js";
 export { type AppErrors, DETAILS as CORE_DETAILS, failureContext, REASONS as CORE_REASONS } from "./errors/reasons.js";
 export { canonicalMeetingReference, formatMeetingReference, type MeetingReference, parseMeetingReference, } from "./meetings/index.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";
-export { canonicalReference, formatReference, parseReference } from "./domain/references.js";
+export { canonicalReference, formatReference, looksLikeReference, parseReference, REF_KINDS, } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES } from "./domain/tags.js";
 export { DETAILS as CORE_DETAILS, failureContext, REASONS as CORE_REASONS } from "./errors/reasons.js";
 export { canonicalMeetingReference, formatMeetingReference, parseMeetingReference, } from "./meetings/index.js";

package/dist/mail/cli/index.js

@@ -74,11 +74,11 @@ const serverIssues = (server) => {
         ...FAILED[reason],
         source: "server",
     }));
-    const tooLarge = server.tooLarge
-        ? [{ code: "outcome_unknown", reason: "search.server-too-large", source: "server" }]
+    const partial = server.partial
+        ? [{ code: "outcome_unknown", reason: "search.server-partial", source: "server" }]
         : [];
-    return failed.length || tooLarge.length
-        ? [...failed, ...tooLarge]
+    return failed.length || partial.length
+        ? [...failed, ...partial]
         : [{ code: "outcome_unknown", reason: "search.server-capped", source: "server" }];
 };
 const searchCommand = (mail) => {

package/dist/mail/index.d.ts

@@ -7,6 +7,7 @@ export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHead
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
+export { PARTIAL, type PartialOutcome } from "./partial.js";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST_RULE } from "./probe.js";
 export { type MailFolderProgress, mailProgress } from "./progress.js";
@@ -21,5 +22,6 @@ export { DEMOTE_AT, type DomainAges, demotedSenders, type LookupResult, SCORE_VE
 export { type MailCriteria, mailCriteriaOf, narrows } from "./server-query.js";
 export { type MailServerAccess, type MailServerRequest, searchMailServer } from "./server-search.js";
 export type { Listed, MailSource, Quick, Searched } from "./source.js";
+export { SEARCH_REFUSED, searchRefused } 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/index.js

@@ -7,6 +7,7 @@ export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
+export { PARTIAL } from "./partial.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
 export { mailProgress } from "./progress.js";
@@ -20,5 +21,6 @@ export { FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, scoreGroup, WEIGHT
 export { DEMOTE_AT, demotedSenders, SCORE_VERSION, scoreSenders, } from "./sender-scores.js";
 export { mailCriteriaOf, narrows } from "./server-query.js";
 export { searchMailServer } from "./server-search.js";
+export { SEARCH_REFUSED, searchRefused } from "./source.js";
 export { listedOf } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/partial.d.ts

@@ -0,0 +1,34 @@
+import type { BudgetStop } from "../background/budget.js";
+import type { LoadEngine } from "../readers/types.js";
+import type { MessageStore } from "../store/index.js";
+import type { MailSource } from "./source.js";
+/** The `emails.metadata` key of an email stored from its first bytes: `{ bytes }` read of its `size`. */
+export declare const PARTIAL = "partial";
+/** How many partial emails one sync reads whole at most; the rest wait for the next run. */
+export declare const PARTIAL_PER_RUN = 100;
+export interface PartialOutcome {
+    /** Read whole this run, the mark cleared. */
+    completed: number;
+    /** Still partial after this run. */
+    left: number;
+}
+/**
+ * Reads whole the emails a server search stored from their first bytes, so the archive holds their attachments too.
+ * Sync never reads stored mail again, so without this step a partial email would stay partial. Gmail's are found by
+ * their id; elsewhere at a stored location, trusted only when the bytes read there carry the stored id.
+ */
+export declare const completePartial: ({ store, source, accountId, address, folders, maxBodyChars, maxAttachmentChars, loadEngine, now, take, signal, }: {
+    store: MessageStore;
+    source: MailSource;
+    accountId: number;
+    address: string;
+    /** Where Gmail's are looked for by id; asked only when a partial email is there to read. */
+    folders: () => Promise<readonly string[]>;
+    maxBodyChars: number;
+    maxAttachmentChars: number;
+    loadEngine: LoadEngine;
+    now: number;
+    /** A budgeted run's next request, or why there is none. */
+    take?: () => BudgetStop | null;
+    signal?: AbortSignal;
+}) => Promise<PartialOutcome>;

package/dist/mail/partial.js

@@ -0,0 +1,94 @@
+import { FETCH_CHUNK, readAttachments } from "./attachments.js";
+import { parsedEmail } from "./email-input.js";
+import { mailHeadersOf } from "./headers.js";
+import { parseMail } from "./parse.js";
+/** The `emails.metadata` key of an email stored from its first bytes: `{ bytes }` read of its `size`. */
+export const PARTIAL = "partial";
+/** How many partial emails one sync reads whole at most; the rest wait for the next run. */
+export const PARTIAL_PER_RUN = 100;
+/**
+ * Reads whole the emails a server search stored from their first bytes, so the archive holds their attachments too.
+ * Sync never reads stored mail again, so without this step a partial email would stay partial. Gmail's are found by
+ * their id; elsewhere at a stored location, trusted only when the bytes read there carry the stored id.
+ */
+export const completePartial = async ({ store, source, accountId, address, folders, maxBodyChars, maxAttachmentChars, loadEngine, now, take, signal, }) => {
+    const { emails, total } = await store.mail.partialEmails(accountId, PARTIAL_PER_RUN);
+    if (emails.length === 0)
+        return { completed: 0, left: 0 };
+    const byId = new Map(emails.map((email) => [email.externalId, email]));
+    const items = new Map();
+    if (source.find) {
+        for (const folder of await folders()) {
+            const left = emails.filter((email) => !items.has(email)).map(({ externalId }) => externalId);
+            if (left.length === 0)
+                break;
+            if (take?.())
+                return { completed: 0, left: total };
+            for (const found of await source.find(left, folder)) {
+                const email = byId.get(found.messageId);
+                if (email && !items.has(email))
+                    items.set(email, found);
+            }
+        }
+    }
+    else if (source.identify)
+        for (const email of emails) {
+            const place = email.locations[0];
+            if (place)
+                items.set(email, {
+                    uid: String(place.uid),
+                    folder: place.folder,
+                    receivedAt: new Date(email.receivedAt ?? 0).toISOString(),
+                });
+        }
+    let completed = 0;
+    const wanted = [...items];
+    for (let start = 0; start < wanted.length; start += FETCH_CHUNK) {
+        if (signal?.aborted || take?.())
+            break;
+        const chunk = wanted.slice(start, start + FETCH_CHUNK);
+        let raws;
+        try {
+            raws = await source.fetchRaw(chunk.map(([, item]) => item));
+        }
+        catch {
+            // A partial email stays readable as it is; the next run tries again.
+            break;
+        }
+        const attachments = [];
+        for (const [index, [email, item]] of chunk.entries()) {
+            const raw = raws[index];
+            if (!(raw instanceof Uint8Array))
+                continue;
+            // A UID means another message after a UIDVALIDITY change; only the stored id proves it is this one.
+            if (!source.find && source.identify?.(raw, item).messageId !== email.externalId)
+                continue;
+            try {
+                const mail = await parseMail(raw, maxBodyChars);
+                const files = await readAttachments(mail, email.externalId, { loadEngine, maxAttachmentChars, at: now, ...(signal ? { signal } : {}) }, attachments);
+                const { [PARTIAL]: _partial, ...metadata } = email.metadata ?? {};
+                const whole = { ...item, messageId: email.externalId, threadId: email.threadExternalId };
+                await store.mail.saveThread({
+                    accountId,
+                    externalId: email.threadExternalId,
+                    now,
+                    emails: [
+                        {
+                            ...parsedEmail(mail, whole, mailHeadersOf(raw), address),
+                            receivedAt: email.receivedAt,
+                            size: raw.byteLength,
+                            metadata,
+                            attachments: files,
+                        },
+                    ],
+                });
+                completed++;
+            }
+            catch {
+                if (signal?.aborted)
+                    break;
+            }
+        }
+    }
+    return { completed, left: total - completed };
+};

package/dist/mail/server-search.js

@@ -9,6 +9,7 @@ import { parsedEmail } from "./email-input.js";
 import { factsOf } from "./facts.js";
 import { mailHeadersOf } from "./headers.js";
 import { parseMail } from "./parse.js";
+import { PARTIAL } from "./partial.js";
 import { storedMailRules } from "./rule-stored.js";
 import { ruleTagger, settleRuleTags } from "./rule-tags.js";
 import { decide, tagsOf } from "./rules.js";
@@ -84,6 +85,7 @@ export const searchMailServer = async (store, mailbox, access, request) => {
     const ruled = new Map();
     const inputs = [];
     const saved = [];
+    let cutShort = 0;
     let opening;
     let openFailure;
     let unsupported = false;
@@ -146,17 +148,12 @@ export const searchMailServer = async (store, mailbox, access, request) => {
             sources.set(sourceKey(item.threadId, item.messageId), held ? "both" : "server");
             if (held)
                 continue;
-            // A big message would hold the connection and the parser past the bound; sync reads it whole later.
-            if ((item.size ?? 0) > SERVER_BOUNDS.maxMessageBytes) {
-                report.tooLarge = (report.tooLarge ?? 0) + 1;
-                report.complete = false;
-                sources.delete(sourceKey(item.threadId, item.messageId));
-                continue;
-            }
             fresh.push(item);
             ruled.set(item, { ruleId: rule?.id ?? null, tags: tagsOf(rules, facts(item)) });
         }
-        const raws = fresh.length && open ? await source.fetchRaw(fresh) : [];
+        // A big message would hold the connection and the parser past the bound: its first bytes carry the text.
+        const bytes = SERVER_BOUNDS.textBytes;
+        const raws = fresh.length && open ? await source.fetchRaw(fresh, { bytes }) : [];
         // Parsing and reading attachments stay inside the bound: after it, nothing more is read or kept.
         const now = Date.now();
         for (const [index, item] of fresh.entries()) {
@@ -166,8 +163,12 @@ export const searchMailServer = async (store, mailbox, access, request) => {
             try {
                 if (raw === undefined || raw instanceof Error)
                     throw raw ?? new Error("not read");
+                const cut = raw.byteLength >= bytes && (item.size === undefined || item.size > raw.byteLength);
                 const mail = await parseMail(raw);
-                const files = await readAttachments(mail, item.messageId, { loadEngine: importEngine, maxAttachmentChars: MAX_ATTACHMENT_CHARS, at: now, signal: stop }, []);
+                // An attachment cut short is not the file: none is kept until the sync reads the whole message.
+                const files = cut
+                    ? []
+                    : await readAttachments(mail, item.messageId, { loadEngine: importEngine, maxAttachmentChars: MAX_ATTACHMENT_CHARS, at: now, signal: stop }, []);
                 if (!open)
                     return;
                 const folder = item.folder;
@@ -189,12 +190,15 @@ export const searchMailServer = async (store, mailbox, access, request) => {
                                 : { locations: [{ folder, uidvalidity: validity, uid: Number(item.uid) }] }),
                             ...(item.seen === undefined ? {} : { read: item.seen }),
                             ...(item.flagged === undefined ? {} : { flagged: item.flagged }),
+                            ...(cut ? { metadata: { [PARTIAL]: { bytes: raw.byteLength } } } : {}),
                             mailRuleId: ruled.get(item)?.ruleId ?? null,
                             attachments: files,
                         },
                     ],
                 });
                 saved.push(item);
+                if (cut)
+                    cutShort++;
             }
             catch {
                 sources.delete(sourceKey(item.threadId, item.messageId));
@@ -248,6 +252,10 @@ export const searchMailServer = async (store, mailbox, access, request) => {
     }
     await settleRuleTags(store, accountId, rules, tagger.outcome());
     report.new = inputs.length;
+    if (cutShort) {
+        report.partial = cutShort;
+        report.complete = false;
+    }
     report.returned = sources.size;
     return { report, sources };
 };

package/dist/mail/source.d.ts

@@ -1,6 +1,12 @@
 import type { MailHeaders } from "./headers.js";
 import type { FileStamp } from "./resume.js";
 import type { MailCriteria } from "./server-query.js";
+/**
+ * The reason of the CliError `search`, `query` and `present` throw when the server answers SEARCH with NO or BAD:
+ * read as "nothing found", it would look like an empty folder and prove its stored mail deleted.
+ */
+export declare const SEARCH_REFUSED = "mail.search-refused";
+export declare const searchRefused: (error: unknown) => boolean;
 export interface Listed {
     uid: string;
     /** Gmail's own ids: the same in every folder, and they survive a UID reset. */
@@ -94,6 +100,11 @@ export interface MailSource {
     present?(uids: readonly string[], folder: string): Promise<string[]>;
     /** 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: Quick[]): Promise<(Uint8Array | Error)[]>;
+    /**
+     * Each item's raw RFC 5322 bytes, in order; one that could not be read is an Error, not a failed call. With
+     * `bytes`, at most the first `bytes` of each: a message cut short comes back shorter than its `size`.
+     */
+    fetchRaw(items: Quick[], options?: {
+        bytes?: number;
+    }): Promise<(Uint8Array | Error)[]>;
 }

package/dist/mail/source.js

@@ -1 +1,7 @@
-export {};
+import { CliError } from "@wirecat/cli-base";
+/**
+ * The reason of the CliError `search`, `query` and `present` throw when the server answers SEARCH with NO or BAD:
+ * read as "nothing found", it would look like an empty folder and prove its stored mail deleted.
+ */
+export const SEARCH_REFUSED = "mail.search-refused";
+export const searchRefused = (error) => error instanceof CliError && error.details.reason === SEARCH_REFUSED;

package/dist/mail/sync-types.d.ts

@@ -0,0 +1,112 @@
+import type { BudgetStop, RunBudget } from "../background/budget.js";
+import type { LoadEngine } from "../readers/types.js";
+import type { AccountKey, MessageStore } from "../store/index.js";
+import type { PartialOutcome } from "./partial.js";
+import type { TagOutcome } from "./rule-tags.js";
+import type { MailRule } from "./rules.js";
+import type { DomainAge } from "./score.js";
+export interface MailAccount {
+    /** The mailbox address: the store's account id. */
+    address: string;
+    mode?: "gmail" | "imap" | "mbox";
+    folders?: string[];
+    rules?: MailRule[];
+}
+/** What an index step reports, as memo's embedding does; the sync only passes it on. */
+export interface MailIndexed {
+    chats: number;
+    chunks: number;
+    left: boolean;
+    notEmbedded?: unknown;
+}
+export interface MailSyncResult {
+    account: string;
+    since: string;
+    listed: number;
+    saved: number;
+    alreadyStored: number;
+    /** New emails a skip rule kept out: never read, never stored. */
+    skipped: number;
+    /** New emails an envelope rule recorded: sender, date, size and labels, never their text. */
+    envelopes: number;
+    deleted: number;
+    /** False when `max` stopped the run before every new message was read; the next run continues. */
+    complete: boolean;
+    /** `partial`: a budgeted run stopped before the whole window was read; the next run goes on. */
+    state?: "partial" | "complete";
+    /** Why a budgeted run stopped early: its request budget, its deadline, or a cancel. */
+    stopped?: BudgetStop;
+    /** Messages of the window this run did not get to read: left by a budget, or by `max`. */
+    remaining?: number;
+    /** Requests a budgeted run spent. */
+    requests?: number;
+    /** Emails that could not be read or parsed; they are tried again next run. */
+    unreadable?: {
+        message: string;
+        reason: string;
+    }[];
+    /** Why stored messages missing at the source were left alone, when they were. */
+    deletionsSkipped?: string;
+    /** Folders whose server refused SEARCH: left unread, so the run is partial and proves no deletion. */
+    refusedFolders?: string[];
+    /** "resumed": only mail not done before was listed; "full": every message in the window was. */
+    pass?: "full" | "resumed";
+    indexed?: MailIndexed;
+    coverage?: {
+        folders: string[];
+        since: string;
+        until: string;
+        state: "window" | "partial";
+        identity: string;
+    };
+    attachments?: {
+        message: string;
+        part: number;
+        status: string;
+    }[];
+    /** Rule tags put on mail as an existing label the store pointed to. */
+    tagsReused?: TagOutcome["reused"];
+    /** Rule tags the store refused with nothing to reuse; that mail is stored untagged. */
+    tagsSkipped?: TagOutcome["skipped"];
+    /** Emails a server search stored from their first bytes, read whole this run, and those still partial. */
+    partial?: PartialOutcome;
+    /** `--retry-attachments`: emails read again for attachments a missing reader left unread. */
+    retried?: {
+        emails: number;
+        extracted: number;
+        stillFailed: number;
+        missing: number;
+    };
+}
+export interface MailSyncOptions {
+    account: MailAccount;
+    since: Date;
+    max?: number;
+    maxBodyChars?: number;
+    maxAttachmentChars?: number;
+    now?: () => number;
+    /** Domain registration dates already known, for the sender score a rule asks for. */
+    ages?: ReadonlyMap<string, DomainAge>;
+    loadEngine?: LoadEngine;
+    retryAttachments?: boolean;
+    /** List every message in the window, not only those an earlier run left: proves deletions, refreshes labels. */
+    rescan?: boolean;
+    /** `false` for a spot read, like the copy of a sent message: the run leaves the saved coverage as the last full run set it. */
+    saveCoverage?: boolean;
+    /** A window smaller than this is listed whole every run: it costs seconds and keeps flags and deletions current. */
+    resumeFrom?: number;
+    /** Runs after the mail is saved, so chats and mail still waiting for vectors are indexed; its answer is `indexed`. */
+    index?: (store: MessageStore, key: AccountKey) => Promise<MailIndexed>;
+    /** Stops between batches of emails, after saving the resume point. */
+    signal?: AbortSignal;
+    /**
+     * Makes the run budgeted: it reads the window in rounds, one request of the budget per call to the source, saves
+     * after each, stops when the budget says so and answers `state: "partial"`. A message the source could not give
+     * is tried once more at the end of the run and, if it still fails, left for the next one. `max` defaults to no limit.
+     */
+    budget?: RunBudget;
+    /** Pauses before a round is read again after the store was locked; tests pass one that does not wait. */
+    wait?: (ms: number) => Promise<void>;
+    /** `false` for a spot read: emails a server search stored from their first bytes are not read whole this run. */
+    completePartial?: boolean;
+}

package/dist/mail/sync-types.js

@@ -0,0 +1 @@
+export {};

package/dist/mail/sync.d.ts

@@ -1,109 +1,7 @@
-import type { BudgetStop, RunBudget } from "../background/budget.js";
-import type { LoadEngine } from "../readers/types.js";
-import type { AccountKey, MessageStore } from "../store/index.js";
-import { type TagOutcome } from "./rule-tags.js";
-import { type MailRule } from "./rules.js";
-import type { DomainAge } from "./score.js";
-import type { MailSource } from "./source.js";
-export interface MailAccount {
-    /** The mailbox address: the store's account id. */
-    address: string;
-    mode?: "gmail" | "imap" | "mbox";
-    folders?: string[];
-    rules?: MailRule[];
-}
-/** What an index step reports, as memo's embedding does; the sync only passes it on. */
-export interface MailIndexed {
-    chats: number;
-    chunks: number;
-    left: boolean;
-    notEmbedded?: unknown;
-}
-export interface MailSyncResult {
-    account: string;
-    since: string;
-    listed: number;
-    saved: number;
-    alreadyStored: number;
-    /** New emails a skip rule kept out: never read, never stored. */
-    skipped: number;
-    /** New emails an envelope rule recorded: sender, date, size and labels, never their text. */
-    envelopes: number;
-    deleted: number;
-    /** False when `max` stopped the run before every new message was read; the next run continues. */
-    complete: boolean;
-    /** `partial`: a budgeted run stopped before the whole window was read; the next run goes on. */
-    state?: "partial" | "complete";
-    /** Why a budgeted run stopped early: its request budget, its deadline, or a cancel. */
-    stopped?: BudgetStop;
-    /** Messages of the window this run did not get to read: left by a budget, or by `max`. */
-    remaining?: number;
-    /** Requests a budgeted run spent. */
-    requests?: number;
-    /** Emails that could not be read or parsed; they are tried again next run. */
-    unreadable?: {
-        message: string;
-        reason: string;
-    }[];
-    /** Why stored messages missing at the source were left alone, when they were. */
-    deletionsSkipped?: string;
-    /** "resumed": only mail not done before was listed; "full": every message in the window was. */
-    pass?: "full" | "resumed";
-    indexed?: MailIndexed;
-    coverage?: {
-        folders: string[];
-        since: string;
-        until: string;
-        state: "window" | "partial";
-        identity: string;
-    };
-    attachments?: {
-        message: string;
-        part: number;
-        status: string;
-    }[];
-    /** Rule tags put on mail as an existing label the store pointed to. */
-    tagsReused?: TagOutcome["reused"];
-    /** Rule tags the store refused with nothing to reuse; that mail is stored untagged. */
-    tagsSkipped?: TagOutcome["skipped"];
-    /** `--retry-attachments`: emails read again for attachments a missing reader left unread. */
-    retried?: {
-        emails: number;
-        extracted: number;
-        stillFailed: number;
-        missing: number;
-    };
-}
+import type { MessageStore } from "../store/index.js";
+import { type MailSource } from "./source.js";
+import type { MailSyncOptions, MailSyncResult } from "./sync-types.js";
+export type { MailAccount, MailIndexed, MailSyncOptions, MailSyncResult } from "./sync-types.js";
 export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
 export { RETRYABLE_ATTACHMENTS } from "./retry.js";
-export interface MailSyncOptions {
-    account: MailAccount;
-    since: Date;
-    max?: number;
-    maxBodyChars?: number;
-    maxAttachmentChars?: number;
-    now?: () => number;
-    /** Domain registration dates already known, for the sender score a rule asks for. */
-    ages?: ReadonlyMap<string, DomainAge>;
-    loadEngine?: LoadEngine;
-    retryAttachments?: boolean;
-    /** List every message in the window, not only those an earlier run left: proves deletions, refreshes labels. */
-    rescan?: boolean;
-    /** `false` for a spot read, like the copy of a sent message: the run leaves the saved coverage as the last full run set it. */
-    saveCoverage?: boolean;
-    /** A window smaller than this is listed whole every run: it costs seconds and keeps flags and deletions current. */
-    resumeFrom?: number;
-    /** Runs after the mail is saved, so chats and mail still waiting for vectors are indexed; its answer is `indexed`. */
-    index?: (store: MessageStore, key: AccountKey) => Promise<MailIndexed>;
-    /** Stops between batches of emails, after saving the resume point. */
-    signal?: AbortSignal;
-    /**
-     * Makes the run budgeted: it reads the window in rounds, one request of the budget per call to the source, saves
-     * after each, stops when the budget says so and answers `state: "partial"`. A message the source could not give
-     * is tried once more at the end of the run and, if it still fails, left for the next one. `max` defaults to no limit.
-     */
-    budget?: RunBudget;
-    /** Pauses before a round is read again after the store was locked; tests pass one that does not wait. */
-    wait?: (ms: number) => Promise<void>;
-}
 export declare const syncMail: (source: MailSource, store: MessageStore, options: MailSyncOptions) => Promise<MailSyncResult>;