@wirecat/cli-core 0.546.0 → 0.548.0

package/dist/cli/messenger/history-query.d.ts

@@ -9,14 +9,20 @@ export declare const historyQuery: (messenger: {
 }) => import("@wirecat/cli-base/query").QueryRegistry;
 declare const COMMENTS_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
 export { COMMENTS_QUERY };
-type Start = Pick<ListWindow, "before" | "beforeTime" | "after">;
+type Start = Pick<ListWindow, "before" | "beforeTime" | "after" | "until">;
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export declare const cursorOf: (start: Start, edge: {
     first?: string;
     last?: string;
 }) => string | undefined;
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export declare const historyWindow: (words: QueryWords, cursor: string | undefined, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => Omit<ListWindow, "limit">;
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export declare const resumeQuery: (words: QueryWords, command: string, registry?: import("@wirecat/cli-base/query").QueryRegistry) => string | undefined;

package/dist/cli/messenger/history-query.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
-import { dateEndpoint, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
-import { listQuery, nativeField, nativeTerms, typedQuery } from "../list-query.js";
+import { dateRange, defineQuery, queryError, timezoneOf } from "@wirecat/cli-base/query";
+import { listQuery, nativeField, nativeTermLists, typedQuery } from "../list-query.js";
 /** What a chat's history can be read by: where it starts, and one topic. */
 export const HISTORY_QUERY = defineQuery({
     entity: "message",
@@ -36,52 +36,108 @@ const COMMENTS_QUERY = defineQuery({
 });
 export { COMMENTS_QUERY };
 /**
- * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. Ids are
- * opaque, so only the first colon splits it.
+ * Where the last page stopped and which way it read: `before:<id>` goes on back, `after:<id>` forward. A window's end
+ * travels as `~<epoch ms>`, so a resumed read stops where the first one would have. Ids are opaque, so only the first
+ * colon splits it.
  */
 export const cursorOf = (start, edge) => {
     const forward = start.after !== undefined;
     const id = forward ? edge.last : edge.first;
-    return id === undefined ? undefined : `${forward ? "after" : "before"}:${id}`;
+    if (id === undefined)
+        return undefined;
+    const end = forward && start.until !== undefined ? `~${start.until}` : "";
+    return `${forward ? "after" : "before"}:${id}${end}`;
 };
 const isId = (value) => value !== "" && !/[\s\p{Cc}]/u.test(value);
 const fromCursor = (cursor) => {
     const at = cursor.indexOf(":");
-    const [way, id] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const [way, rest] = at < 0 ? [cursor, ""] : [cursor.slice(0, at), cursor.slice(at + 1)];
+    const ended = way === "after" ? /^(.*)~(\d+)$/u.exec(rest) : null;
+    const id = ended ? ended[1] : rest;
     if (!isId(id) || (way !== "before" && way !== "after"))
         throw new CliError("validation_error", `--cursor takes what page.next gave, before:<id> or after:<id> — not "${cursor}"`);
-    return way === "before" ? { before: id } : { after: { id } };
+    if (way === "before")
+        return { before: id };
+    return { after: { id }, ...(ended ? { until: Number(ended[2]) } : {}) };
 };
-const startOf = (term, command) => {
+/** A term's lower and upper bound; a date's as moments in the zone, an exclusive end 1 ms inside. */
+const boundsOf = (term, command) => {
     const context = { command };
-    const older = term.value === "*" && term.upper !== undefined && term.upper !== "*";
-    const newer = term.value !== "*" && (term.upper === undefined || term.upper === "*");
-    if (older === newer)
-        queryError("query.unsupported-operator", term.span, `${term.field} takes one side: ${term.field}< or ${term.field}>`, context);
-    if (term.field === "id")
-        return older ? { before: term.upper } : { after: { id: term.value } };
-    const bound = older ? term.upper : term.value;
-    const inclusive = (older ? term.upper_inclusive : term.lower_inclusive) ?? true;
-    const { time } = dateEndpoint(bound, timezoneOf(), older ? "upper" : "lower", inclusive, term.span);
-    if (time === undefined)
-        queryError("query.invalid-date", term.span, `${bound} is not a time`, context);
-    return older ? { beforeTime: time } : { after: { time } };
+    const hasLower = term.value !== "*";
+    const hasUpper = term.upper !== undefined && term.upper !== "*";
+    const span = term.span;
+    if (term.field === "id") {
+        if (hasLower === hasUpper)
+            queryError("query.unsupported-operator", span, "id takes one side: id< or id>", context);
+        return hasLower
+            ? { lower: { start: { after: { id: term.value } }, span, date: false } }
+            : { upper: { start: { before: term.upper }, span, date: false } };
+    }
+    if (!hasLower && !hasUpper)
+        queryError("query.unsupported-operator", span, `${term.field} needs a start, an end or both`, context);
+    const range = dateRange(term.value, term.upper ?? "*", term.lower_inclusive ?? true, term.upper_inclusive ?? true, timezoneOf(), span);
+    if ((hasLower && range.lower === undefined) || (hasUpper && range.upper === undefined))
+        queryError("query.invalid-date", span, "that is not a time", context);
+    return {
+        // The messenger and the store read strictly after a start, so an inclusive one moves 1 ms back.
+        ...(range.lower === undefined
+            ? {}
+            : { lower: { start: { after: { time: range.lower - (range.lower_inclusive ? 1 : 0) } }, span, date: true } }),
+        ...(range.upper === undefined
+            ? {}
+            : { upper: { start: { until: range.upper - (range.upper_inclusive ? 0 : 1) }, span, date: true } }),
+    };
 };
-/** A list reads one way from one place: the query or the cursor names at most one starting point. */
+/**
+ * The window the query names. A start reads forward from it, oldest first, and stops at an end; an end alone reads
+ * back from it, newest page first.
+ */
+const windowOf = (terms, command) => {
+    const context = { command };
+    const lowers = [];
+    const uppers = [];
+    for (const term of terms) {
+        const { lower, upper } = boundsOf(term, command);
+        if (lower)
+            lowers.push(lower);
+        if (upper)
+            uppers.push(upper);
+    }
+    const [lower, extraLower] = lowers;
+    const [upper, extraUpper] = uppers;
+    if (extraLower)
+        queryError("query.unsupported-placement", extraLower.span, "the window has one start", context);
+    if (extraUpper)
+        queryError("query.unsupported-placement", extraUpper.span, "the window has one end", context);
+    if (lower && upper && !upper.date)
+        queryError("query.unsupported-placement", upper.span, "a window from a start ends at a date: date<…", context);
+    if (lower)
+        return { ...lower.start, ...upper?.start };
+    if (upper?.start.until !== undefined)
+        return { beforeTime: upper.start.until + 1 };
+    return upper?.start ?? {};
+};
+/** A list reads one way from one place: the query or the cursor names at most one window. */
 export const historyWindow = (words, cursor, command, registry = HISTORY_QUERY) => {
-    const terms = [...nativeTerms(listQuery(typedQuery(words), registry, command), command).values()];
-    const starts = terms
-        .filter((term) => term.field !== "topic" && term.field !== "starred")
-        .map((term) => startOf(term, command));
-    if (cursor !== undefined)
-        starts.push(fromCursor(cursor));
-    if (starts.length > 1)
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const bounds = [...(terms.get("date") ?? []), ...(terms.get("id") ?? [])];
+    const start = windowOf(bounds, command);
+    if (cursor !== undefined && bounds.length > 0)
         throw new CliError("validation_error", "the query and --cursor name two starting points; give one of them");
-    const topic = terms.find((term) => term.field === "topic")?.value;
-    const starred = terms.find((term) => term.field === "starred")?.value.toLowerCase();
+    const topic = terms.get("topic")?.[0]?.value;
+    const starred = terms.get("starred")?.[0]?.value.toLowerCase();
     return {
-        ...starts[0],
+        ...(cursor === undefined ? start : fromCursor(cursor)),
         ...(topic === undefined ? {} : { threadId: topic }),
         ...(starred === undefined ? {} : { starred: starred === "true" }),
     };
 };
+/**
+ * The query `page.next` reruns with its cursor: the topic and the stars, never the bounds, which the cursor carries
+ * and which would name a second starting point beside it.
+ */
+export const resumeQuery = (words, command, registry = HISTORY_QUERY) => {
+    const terms = nativeTermLists(listQuery(typedQuery(words), registry, command), command, ["date", "id"]);
+    const kept = ["topic", "starred"].flatMap((field) => terms.get(field)?.map((term) => `${field}:${term.value}`) ?? []);
+    return kept.length > 0 ? kept.join(" ") : undefined;
+};

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

@@ -12,6 +12,7 @@ import { modelWith, spoken } from "../../speech/hearing.js";
 import { REMOTE_READ } from "../effects.js";
 import { itemOf, listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
+import { withOptionHints } from "../option-hints.js";
 import { positiveCount } from "../paging.js";
 import { syncCommand } from "./backfill-command.js";
 import { messengerContext } from "./context.js";
@@ -19,7 +20,7 @@ import { linksCommand } from "./conversations-command.js";
 import { downloadSubcommand } from "./download-command.js";
 import { heardItems, hearForCommand, hearingMissing, MODEL_OPTION, spokenItems, TRANSCRIBE_OPTION, } from "./hearing-command.js";
 import { historyLimitGaps } from "./history-gaps.js";
-import { cursorOf, historyQuery, historyWindow } from "./history-query.js";
+import { cursorOf, historyQuery, historyWindow, resumeQuery } from "./history-query.js";
 import { hideNever } from "./lacks.js";
 import { threadAnswer } from "./message-answers.js";
 import { messageItem, messageItems, viewOf } from "./message-items.js";
@@ -36,6 +37,8 @@ import { sendCommand } from "./messages-send-command.js";
 import { coverageGaps } from "./search-answers.js";
 import { threadOptions, threadRequest } from "./thread-options.js";
 import { transcribeSubcommand } from "./transcribe-command.js";
+const WINDOW_EXAMPLE = "date>=2026-10-01 date<2026-10-20";
+const TIME_FLAGS = ["--since", "--since-time", "--until", "--until-time", "--after-time", "--before-time"];
 /** `messages`: reading, and sending through the guard. A CLI may add its own subcommands. */
 export const messagesCommand = (messenger) => {
     const messages = new Command("messages").description("read and send messages");
@@ -51,8 +54,8 @@ export const messagesCommand = (messenger) => {
         .addHelpText("after", queryHelp(history))
         .argument("<chat>", messenger.chatArgument)
         .argument("[query...]", `${messenger.topics === false
-        ? "where to start: id<42, date>2026-10-01"
-        : "where to start and which topic: id<42, date>2026-10-01, topic:12"}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
+        ? `where to start or which window: id<42, ${WINDOW_EXAMPLE}`
+        : `where to start or which window, and which topic: id<42, ${WINDOW_EXAMPLE}, topic:12`}${messenger.messageStars === true ? "; starred:true keeps the ones you starred" : ""}`)
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it")
         .option(...TRANSCRIBE_OPTION)
@@ -73,6 +76,8 @@ export const messagesCommand = (messenger) => {
         const next = page.hasMore
             ? cursorOf(window, { first: page.items[0]?.id, last: page.items.at(-1)?.id })
             : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages list", history);
+        const queryArg = typed ? { query: typed } : {};
         // Offline, the store is the whole answer: say how much of the chat it holds. Online the messenger is read.
         const gaps = context.settings.offline
             ? await context.withStore(async (store, account) => {
@@ -88,13 +93,14 @@ export const messagesCommand = (messenger) => {
             has_more: page.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, ...queryArg },
             next: gaps.next,
             missing: [...hearingMissing(hearing, transcribe === true), ...gaps.missing],
             ...(gaps.missing.length > 0 ? { meta: { complete: false } } : {}),
         }), () => renderMessages(spokenItems(page.items, hearing), viewOf(context, messenger)));
     });
     annotate(list, { output: { entity: "message" }, query: history });
+    withOptionHints(list, Object.fromEntries(TIME_FLAGS.map((flag) => [flag, `messages list reads a window by its query: '${WINDOW_EXAMPLE}'`])));
     const readWindow = async (command, chat, message, window) => {
         const context = messengerContext(command, messenger);
         const { found, reader } = await context.withServices(async (services) => ({

package/dist/cli/messenger/messages-comments-command.js

@@ -7,7 +7,7 @@ import { listOf, renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
-import { COMMENTS_QUERY, cursorOf, historyWindow } from "./history-query.js";
+import { COMMENTS_QUERY, cursorOf, historyWindow, resumeQuery } from "./history-query.js";
 import { messageItems, viewOf } from "./message-items.js";
 export const commentsCommand = (messenger) => {
     const otherPosts = messenger.readsComments === true && messenger.channelComments === false;
@@ -42,13 +42,15 @@ export const commentsCommand = (messenger) => {
             reader: await services.messages.reader(),
         }));
         const next = found.hasMore ? cursorOf(window, { first: found.items[0]?.id }) : undefined;
+        const typed = next === undefined ? query.join(" ") : resumeQuery(query, "messages comments", COMMENTS_QUERY);
+        const queryArg = typed ? { query: typed } : {};
         renderAnswer(this, context, listOf("messages comments", {
             items: messageItems(found.items, reader),
             limit,
             has_more: found.hasMore,
             paging: "cursor",
             ...(next === undefined ? {} : { cursor: next }),
-            args: { chat, post, ...(query.length > 0 ? { query: query.join(" ") } : {}) },
+            args: { chat, post, ...queryArg },
         }), () => renderMessages(found.items, viewOf(context, messenger)));
     });
     return annotate(command, { output: { entity: "message" }, query: COMMENTS_QUERY });

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
+    error?: undefined;
     path: string;
     exists: boolean;
-    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/option-hints.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export declare const withOptionHints: (command: Command, hints: Readonly<Record<string, string>>) => Command;

package/dist/cli/option-hints.js

@@ -0,0 +1,15 @@
+/**
+ * A flag a command does not take, but an agent is likely to type, fails with what to type instead rather than
+ * commander's bare "unknown option".
+ */
+export const withOptionHints = (command, hints) => {
+    const unknown = command;
+    const fallback = unknown.unknownOption.bind(command);
+    unknown.unknownOption = (flag) => {
+        const hint = hints[flag.split("=")[0]];
+        if (hint === undefined)
+            return fallback(flag);
+        return command.error(`unknown option '${flag}' — ${hint}`, { code: "commander.unknownOption" });
+    };
+    return command;
+};

package/dist/errors/reasons.js

@@ -110,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"],
     [
@@ -145,6 +149,14 @@ 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"),

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;