@wirecat/cli-core 0.434.0 → 0.436.0

package/dist/services/messages-discovery.js

@@ -8,7 +8,17 @@ import { prepareLucene, searchLucene } from "./messages-search.js";
 /** How many of the messages nearest in meaning join the fusion: the benchmark's pool (performance/search/evidence-pipeline). */
 export const MEANING_DEPTH = 100;
 const RRF_K = 60;
-export const searchDiscovery = async (store, account, asked, messenger = {}, meaning) => {
+/** How many of discovery's first hits the reranker reads, and its share of their order: the benchmark's winner. */
+export const RERANK_DEPTH = 50;
+const RERANK_WEIGHT = 0.7;
+/** Pairs scored between two looks at the clock. */
+const RERANK_CHUNK = 5;
+/**
+ * Scoring has its own clock, not the word search's 2 s: 50 pairs are bounded work, and BGE on WebAssembly takes
+ * ~7–10 s of it (cli-testing performance/search/evidence-pipeline, "In Core").
+ */
+export const RERANK_MILLISECONDS = 15_000;
+export const searchDiscovery = async (store, account, asked, messenger = {}, meaning, rerank) => {
     // A question's own "?" would parse as a one-character wildcard and send it to strict search (BUG-395).
     const request = asked.ast !== undefined || asked.exact || !asked.text
         ? asked
@@ -30,7 +40,7 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         exhausted("discovery terms");
     // Before the clock starts: loading the model alone takes about a second of the word search's budget.
     const lane = meaning ? await meaning(text, original.scopeAccounts) : undefined;
-    const started = performance.now();
+    let started = performance.now();
     const check = () => {
         if (request.signal?.aborted)
             throw new CliError("validation_error", "search was aborted", { reason: "query.aborted", complete: false });
@@ -152,6 +162,51 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         meaningCandidates = near.length;
         candidates = fusedWithMeaning(candidates, near, described);
     }
+    let reranked;
+    let rerankSkipped;
+    if (rerank && candidates.length > 1) {
+        const opening = performance.now();
+        const reranker = await rerank();
+        if ("skipped" in reranker)
+            rerankSkipped = reranker.skipped;
+        else {
+            const scoring = performance.now();
+            try {
+                const head = candidates.slice(0, RERANK_DEPTH);
+                // Telegram keeps only the id a reply answers: the parent is read from the store.
+                const parents = await Promise.all(head.map(async (m) => parentByLocator.get(m.locator) ??
+                    m.replyTo ??
+                    (m.replyToId === undefined
+                        ? undefined
+                        : await store.messages.message(accountOfHit(m), m.replyToId, { chatId: m.chatId }))));
+                const passages = head.map((m, i) => pairInput(m, parents[i]));
+                let scores = [];
+                let chunk = 0;
+                while (scores.length < passages.length) {
+                    if (request.signal?.aborted)
+                        throw new CliError("validation_error", "search was aborted", { reason: "query.aborted", complete: false });
+                    const now = performance.now();
+                    if (now + chunk > scoring + RERANK_MILLISECONDS)
+                        break;
+                    scores = scores.concat(await reranker.score(text, passages.slice(scores.length, scores.length + RERANK_CHUNK)));
+                    chunk = performance.now() - now;
+                }
+                if (scores.length < passages.length || performance.now() > scoring + RERANK_MILLISECONDS) {
+                    // A part of the hits rescored cannot be mixed with the rest.
+                    rerankSkipped = { reason: "scoring would take longer than it may", model: reranker.model };
+                }
+                else {
+                    candidates = mixedWithReranker(head, scores).concat(candidates.slice(RERANK_DEPTH));
+                    reranked = { model: reranker.model, scored: head.length };
+                }
+            }
+            finally {
+                await reranker.done();
+            }
+        }
+        // Loading and scoring are not the word search's time, as loading is not for meaning.
+        started += performance.now() - opening;
+    }
     check();
     const items = await Promise.all(candidates.slice(0, request.limit).map(async ({ fused: _fused, ...m }) => {
         if (!request.context)
@@ -184,14 +239,16 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
                 terms,
                 queries: [...(plan.changed ? [] : plan.queries), relaxed],
                 ...(lane && "ranked" in lane ? { meaning: { model: lane.model, candidates: meaningCandidates } } : {}),
+                ...(reranked ? { rerank: reranked } : {}),
             },
         },
+        ...(rerankSkipped ? { rerankSkipped } : {}),
         ...(lane && "skipped" in lane ? { meaningSkipped: lane.skipped } : {}),
         ...(lane && "partly" in lane && lane.partly ? { meaningSkipped: lane.partly } : {}),
     };
 };
 /** The nearest messages the question's filters allow, as hits, nearest first. */
-const nearEligible = async (store, account, request, messenger, ranked, scope) => {
+export const nearEligible = async (store, account, request, messenger, ranked, scope) => {
     const keyOf = (one) => JSON.stringify([one.provider, one.account, one.chatId, one.id]);
     const only = ranked
         .slice(0, MEANING_DEPTH)
@@ -232,3 +289,31 @@ const fusedWithMeaning = (words, near, described) => {
     });
     return [...merged.values()].sort((a, b) => b.rrf - a.rrf).map(({ hit, rrf }) => ({ ...hit, score: rrf }));
 };
+const pairInput = (hit, parent) => {
+    const line = (m) => `[${hit.chatTitle ?? hit.chatId} · ${m.senderName ?? "unknown"} · ${m.timestamp?.slice(0, 10) ?? "undated"}] ${m.text}`;
+    return (parent ? [parent, hit] : [hit]).map(line).join("\n");
+};
+const accountOfHit = (hit) => {
+    const { provider, account } = parseLocator(hit.locator);
+    return { provider, account };
+};
+const scaled = (values) => {
+    const low = values.reduce((a, b) => Math.min(a, b), Number.POSITIVE_INFINITY);
+    const span = values.reduce((a, b) => Math.max(a, b), Number.NEGATIVE_INFINITY) - low;
+    return values.map((value) => (span ? (value - low) / span : 1));
+};
+/**
+ * The benchmark's winning mix: discovery's score and the reranker's, each scaled to 0–1 over the hits it read,
+ * weighed 0.3 and 0.7. `score` keeps discovery's own; the reranker's is beside it.
+ */
+const mixedWithReranker = (head, scores) => {
+    const fused = scaled(head.map((m) => m.score ?? 0));
+    const read = scaled(scores);
+    return head
+        .map((m, i) => ({
+        hit: m.discovery ? { ...m, discovery: { ...m.discovery, rerankerScore: scores[i] } } : m,
+        mixed: (1 - RERANK_WEIGHT) * fused[i] + RERANK_WEIGHT * read[i],
+    }))
+        .sort((a, b) => b.mixed - a.mixed)
+        .map(({ hit }) => hit);
+};

package/dist/services/messages-meaning.d.ts

@@ -1,7 +1,8 @@
 import type { ServiceDeps } from "./deps.js";
+import { type ModelDeps } from "./embeddings-maintenance.js";
 import { type MeaningLane } from "./messages-discovery.js";
 /**
  * Discovery's meaning half: the default local model over each message's own vector. It runs only when the model is
  * on disk and vectors exist — never a download, never a remote model — and any failure leaves the words alone.
  */
-export declare const meaningLane: (deps: ServiceDeps) => MeaningLane;
+export declare const meaningLane: (deps: ModelDeps & Pick<ServiceDeps, "store">) => MeaningLane;

package/dist/services/messages-meaning.js

@@ -6,7 +6,7 @@ import { plainWords } from "./pictures.js";
  * Discovery's meaning half: the default local model over each message's own vector. It runs only when the model is
  * on disk and vectors exist — never a download, never a remote model — and any failure leaves the words alone.
  */
-export const meaningLane = (deps) => async (question, accounts) => {
+export const meaningLane = (deps) => async (question, accounts, shared) => {
     const target = embeddingTarget(deps, DEFAULT_TEXT_MODEL);
     const skipped = (reason, step) => ({
         skipped: { reason, model: target.id, ...(step ? { step } : {}) },
@@ -24,7 +24,7 @@ export const meaningLane = (deps) => async (question, accounts) => {
     try {
         const ranked = [];
         if (words) {
-            await withEmbedder(deps, target, DEFAULT_TEXT_MODEL, {}, async (embedder) => {
+            const lookUp = async (embedder) => {
                 const [query] = await embedder.embed([words], "query");
                 for (const one of ready) {
                     const near = await store.vectors.nearestMessages(one, {
@@ -35,7 +35,11 @@ export const meaningLane = (deps) => async (question, accounts) => {
                     for (const { chatId, messageId, score } of near)
                         ranked.push({ ...one, chatId, id: messageId, score });
                 }
-            });
+            };
+            if (shared && !deps.embedders)
+                await lookUp(await shared.get(target.key, () => target.open()));
+            else
+                await withEmbedder(deps, target, DEFAULT_TEXT_MODEL, {}, lookUp);
         }
         return {
             model: target.id,

package/dist/services/messages-rerank.d.ts

@@ -0,0 +1,7 @@
+import type { ServiceDeps } from "./deps.js";
+import type { RerankLane } from "./messages-discovery.js";
+/**
+ * Discovery's last step: the reranker reads the question with each of the first hits. It runs only when the model
+ * is on disk — never a download, never a remote model — and any failure leaves discovery's order alone.
+ */
+export declare const rerankLane: (deps: ServiceDeps) => RerankLane | undefined;

package/dist/services/messages-rerank.js

@@ -0,0 +1,42 @@
+import { defaultThreads, isTextModelInstalled, textModelsDirectory } from "../embeddings/embed.js";
+import { DEFAULT_RERANK_MODEL, rerankModel } from "../embeddings/models.js";
+import { plainWords } from "./pictures.js";
+/**
+ * Discovery's last step: the reranker reads the question with each of the first hits. It runs only when the model
+ * is on disk — never a download, never a remote model — and any failure leaves discovery's order alone.
+ */
+export const rerankLane = (deps) => {
+    const choice = deps.reranker ?? DEFAULT_RERANK_MODEL;
+    if (choice === "off")
+        return undefined;
+    return async () => {
+        const model = rerankModel(choice);
+        const directory = textModelsDirectory(deps.env);
+        if (!isTextModelInstalled(model, directory))
+            return { skipped: { reason: `${model.id} is not downloaded`, step: "models.download", model: model.id } };
+        try {
+            const warm = deps.embedders;
+            const reranker = warm
+                ? await warm.reranker(`rerank:${model.id}`, async () => (await import("../embeddings/process.js")).openRerankerProcess(model, directory, {
+                    threads: defaultThreads(),
+                }))
+                : await (await import("../embeddings/rerank.js")).openReranker(model, directory);
+            return {
+                model: model.id,
+                score: (question, passages) => reranker.score(plainWords(question), passages),
+                done: async () => {
+                    if (!warm)
+                        await reranker.close();
+                },
+            };
+        }
+        catch (error) {
+            return {
+                skipped: {
+                    reason: `${model.id} failed: ${error instanceof Error ? error.message : String(error)}`,
+                    model: model.id,
+                },
+            };
+        }
+    };
+};

package/dist/services/messages-search.d.ts

@@ -20,6 +20,11 @@ export interface QueryMetadata {
             model: string;
             candidates: number;
         };
+        /** Present when the reranker reordered the first hits: the model, and how many it read. */
+        rerank?: {
+            model: string;
+            scored: number;
+        };
     };
     version: 1;
     fieldsVersion: number;

package/dist/services/messages.d.ts

@@ -7,7 +7,7 @@ import { type Operated } from "../sends/guarded.js";
 import type { PermissionKey } from "../sends/permissions.js";
 import type { AccountKey, ChatCompleteness, MatchPlace, StoredHit } from "../store/store.js";
 import { type ServiceDeps } from "./deps.js";
-import type { MeaningSkipped } from "./messages-discovery.js";
+import type { MeaningSkipped, RerankSkipped } from "./messages-discovery.js";
 import type { MessageStats, QueryMetadata, SearchCoverage, StatsGrouping } from "./messages-search.js";
 import type { PictureHit } from "./pictures.js";
 import { type SearchAllFound, type SearchAllRequest } from "./search-all.js";
@@ -82,6 +82,8 @@ export type FoundMessage = StoredHit & {
         parent?: string;
         /** Only when meaning was searched too: which of the two lists found it. */
         foundBy?: ("words" | "meaning")[];
+        /** Only when the reranker read it: the cross-encoder's own score, higher is better. */
+        rerankerScore?: number;
     };
     match?: "words" | "beginnings" | "corrected";
     /** The garbled spellings a `corrected` hit's transcript holds, per query word. */
@@ -118,9 +120,11 @@ export interface SearchFound extends Page<FoundMessage> {
     }[];
     /** Per chat of the page: how much of its history the store holds. */
     completeness: (ChatCompleteness & AccountKey)[];
-    /** `false` while the word index is being built. */
     /** `--discover` searched by words alone: why meaning was not searched, and the step that would enable it. */
     meaningSkipped?: MeaningSkipped;
+    /** `--discover` kept its own order: why the reranker did not read the hits, and the step that would let it. */
+    rerankSkipped?: RerankSkipped;
+    /** `false` while the word index is being built. */
     wordsReady: boolean;
     /** The same for the stems, in strict search: `false` until a stemmed search may run. */
     stemsReady?: boolean;

package/dist/services/messages.js

@@ -13,6 +13,7 @@ import { crossAccount, fromStore, PUSHED } from "./deps.js";
 import { readChatId, storedChatId } from "./message-resolution.js";
 import { accountOf, keyOf, searchStore, statsStore, topUp } from "./messages-archive-search.js";
 import { meaningLane } from "./messages-meaning.js";
+import { rerankLane } from "./messages-rerank.js";
 import { searchAll } from "./search-all.js";
 import { searchAllWithMeetings, } from "./search-all-meetings.js";
 import { searchRecordOf } from "./search-record.js";
@@ -32,7 +33,7 @@ export const messagesService = (deps) => {
                 return { ...account, chatId, id };
             })
             : undefined;
-        const found = await searchStore(store, account, only ? { ...query, only } : query, deps.messenger, query.discover && query.kind !== "mail" ? meaningLane(deps) : undefined);
+        const found = await searchStore(store, account, only ? { ...query, only } : query, deps.messenger, query.discover && query.kind !== "mail" ? meaningLane(deps) : undefined, query.discover && query.kind !== "mail" ? rerankLane(deps) : undefined);
         return { found, server };
     };
     const unifiedMessages = (store, account) => async (query) => {
@@ -243,8 +244,8 @@ export const messagesService = (deps) => {
                 return withServer(withRefresh(found, refreshed), account, server);
             });
         },
-        searchAll: (request) => inStore((store, account) => searchAll(store, account, request, deps.messenger, unifiedMessages(store, account))),
-        searchAllWithMeetings: (request) => inStore((store, account) => searchAllWithMeetings(store, account, request, deps.messenger, unifiedMessages(store, account))),
+        searchAll: (request) => inStore((store, account) => searchAll(store, account, request, deps.messenger, unifiedMessages(store, account), meaningLane(deps))),
+        searchAllWithMeetings: (request) => inStore((store, account) => searchAllWithMeetings(store, account, request, deps.messenger, unifiedMessages(store, account), meaningLane(deps))),
         stats: (query) => inStore(async (store, account) => {
             const refreshed = await refreshSearch(deps, query);
             const stats = await statsStore(store, account, query, deps.messenger);

package/dist/services/model-downloads.d.ts

@@ -1,4 +1,4 @@
-import { type TextModel } from "../embeddings/models.js";
+import { type RerankModel, type TextModel } from "../embeddings/models.js";
 import { type ImageModel } from "../images/picture/models.js";
 export interface ModelDownloadOptions {
     env: NodeJS.ProcessEnv;
@@ -16,5 +16,7 @@ export interface DownloadedModel<M> {
 export declare const downloadTextModel: (id: string, { env, progress, acceptTerms }: ModelDownloadOptions & {
     acceptTerms?: boolean;
 }) => Promise<DownloadedModel<TextModel>>;
+/** A reranker, the same way as {@link downloadTextModel}, into the same folder. */
+export declare const downloadRerankModel: (id: string, { env, progress }: ModelDownloadOptions) => Promise<DownloadedModel<RerankModel>>;
 /** The picture model, the same way as {@link downloadTextModel}. */
 export declare const downloadImageModel: (id: string, { env, progress }: ModelDownloadOptions) => Promise<DownloadedModel<ImageModel>>;

package/dist/services/model-downloads.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { isTextModelInstalled, placedText, textModelsDirectory } from "../embeddings/embed.js";
-import { textModel } from "../embeddings/models.js";
+import { rerankModel, textModel } from "../embeddings/models.js";
 import { imageModel, imageModelsDirectory, isImageModelInstalled, placedImage, } from "../images/picture/models.js";
 import { installFiles, megabytes } from "../speech/install.js";
 const bytesOf = (model) => model.files.reduce((sum, file) => sum + file.bytes, 0);
@@ -31,6 +31,25 @@ export const downloadTextModel = async (id, { env, progress = () => { }, acceptT
     }
     return { model, directory };
 };
+/** A reranker, the same way as {@link downloadTextModel}, into the same folder. */
+export const downloadRerankModel = async (id, { env, progress = () => { } }) => {
+    const model = rerankModel(id);
+    const directory = textModelsDirectory(env);
+    if (!isTextModelInstalled(model, directory)) {
+        progress(`${model.id}: ${megabytes(bytesOf(model))} from Hugging Face`);
+        await installFiles(placedText(model, directory), { progress });
+    }
+    progress(`${model.id}: loading it once to check it works`);
+    const { openReranker } = await import("../embeddings/rerank.js");
+    const reranker = await openReranker(model, directory);
+    try {
+        await reranker.score("check", ["check"]);
+    }
+    finally {
+        await reranker.close();
+    }
+    return { model, directory };
+};
 /** The picture model, the same way as {@link downloadTextModel}. */
 export const downloadImageModel = async (id, { env, progress = () => { } }) => {
     const model = imageModel(id);

package/dist/services/notes-search.d.ts

@@ -1,3 +1,4 @@
+import { type WarmEmbedders } from "../embeddings/embed.js";
 import type { PictureEmbedder } from "../images/picture/embedder.js";
 import type { AppIdentity } from "../ports/app.js";
 import { type SkippedSource } from "../search/account-list.js";
@@ -45,12 +46,14 @@ export declare const embedMail: (store: MessageStore, options?: NotesEmbedOption
     command?: string;
 }) => Promise<NotesEmbedded>;
 /** Notes nearest in meaning to the query, best first; only notes already embedded can be found. */
-export declare const nearestNotes: (store: MessageStore, query: string, { model: choice, limit, folderIds, withInternal, source, env, threads, command, }: Omit<NotesEmbedOptions, "maxChunks"> & {
+export declare const nearestNotes: (store: MessageStore, query: string, { model: choice, limit, folderIds, withInternal, source, env, threads, command, embedders, }: Omit<NotesEmbedOptions, "maxChunks"> & {
     limit: number;
     folderIds?: string[];
     withInternal?: boolean;
     source?: Note["source"];
     command?: string;
+    /** The search's own, when another part of it loads the same model. */
+    embedders?: Pick<WarmEmbedders, "get">;
 }) => Promise<NearestNote[]>;
 export interface FoundNote {
     kind?: "document" | "note";
@@ -119,6 +122,8 @@ export interface NotesQuery {
     env?: NodeJS.ProcessEnv;
     /** The tool's command, named in the hint when the model is missing. */
     command?: string;
+    /** The search's own models, when another part of it loads the same one. */
+    embedders?: Pick<WarmEmbedders, "get">;
     /** Adds `pictures`, the documents whose picture the plain words describe, beside the hits. English words. */
     pictures?: boolean;
     pictureLimit?: number;
@@ -139,7 +144,7 @@ export declare const noteSourceOfQuery: (query: string) => {
  * `search notes`: words and stems, and meaning when the local model is there, merged by reciprocal rank;
  * each hit says which half found it, and the answer lists what the notes found link to.
  */
-export declare const searchNotes: (store: MessageStore, query: string, { limit, offset, tag, filter: expression, folderIds, withInternal, source: given, exact, timezone, env, command, pictures: withPictures, pictureLimit, pictureEmbedder, }?: NotesQuery) => Promise<NotesFound>;
+export declare const searchNotes: (store: MessageStore, query: string, { limit, offset, tag, filter: expression, folderIds, withInternal, source: given, exact, timezone, env, command, embedders, pictures: withPictures, pictureLimit, pictureEmbedder, }?: NotesQuery) => Promise<NotesFound>;
 /** What `notes:internal` and `notes:<folder id>` ask of the store: one query, so a page of it is one page. */
 export declare const notesScopeOf: (accounts: readonly AccountKey[]) => Pick<NotesQuery, "folderIds" | "withInternal" | "source">;
 export interface NotesFoundOf extends NotesFound {

package/dist/services/notes-search.js

@@ -64,7 +64,9 @@ const localModel = (choice, env, command) => {
         });
     return { model, directory, key: vectorModelKey(model) };
 };
-const withLocal = async (model, directory, threads, work) => {
+const withLocal = async (model, directory, threads, work, shared) => {
+    if (shared)
+        return work(await shared.get(vectorModelKey(model), () => openEmbedder(model, directory, { threads: threads ?? defaultThreads() })));
     const embedder = await openEmbedder(model, directory, { threads: threads ?? defaultThreads() });
     try {
         return await work(embedder);
@@ -105,7 +107,7 @@ export const embedNotes = (store, options = {}) => embedChunks(store, store.note
 /** Embeds mail's chunks as notes' are embedded: same model and key, so search by meaning reads both. */
 export const embedMail = (store, options = {}) => embedChunks(store, store.mail, options);
 /** Notes nearest in meaning to the query, best first; only notes already embedded can be found. */
-export const nearestNotes = async (store, query, { model: choice, limit, folderIds, withInternal, source, env, threads, command, }) => {
+export const nearestNotes = async (store, query, { model: choice, limit, folderIds, withInternal, source, env, threads, command, embedders, }) => {
     if (!query.trim())
         throw new CliError("validation_error", "say what to find in the notes");
     const { model, directory, key } = localModel(choice, env, command);
@@ -116,7 +118,7 @@ export const nearestNotes = async (store, query, { model: choice, limit, folderI
     };
     if (!(await store.notes.embedded(key, scope)))
         throw new CliError("not_found", `nothing searched here has vectors of ${model.id} yet, so only words were matched`);
-    const [vector] = await withLocal(model, directory, threads, (embedder) => embedder.embed([query], "query"));
+    const [vector] = await withLocal(model, directory, threads, (embedder) => embedder.embed([query], "query"), embedders);
     const floor = meaningFloor(key);
     const nearest = await store.notes.nearest(key, vector, {
         limit,
@@ -214,7 +216,7 @@ export const noteSourceOfQuery = (query) => {
  * `search notes`: words and stems, and meaning when the local model is there, merged by reciprocal rank;
  * each hit says which half found it, and the answer lists what the notes found link to.
  */
-export const searchNotes = async (store, query, { limit = 20, offset = 0, tag, filter: expression, folderIds, withInternal, source: given, exact = false, timezone, env, command, pictures: withPictures = false, pictureLimit = 5, pictureEmbedder, } = {}) => {
+export const searchNotes = async (store, query, { limit = 20, offset = 0, tag, filter: expression, folderIds, withInternal, source: given, exact = false, timezone, env, command, embedders, pictures: withPictures = false, pictureLimit = 5, pictureEmbedder, } = {}) => {
     const typed = noteSourceOfQuery(query);
     const source = given ?? typed.source;
     const words = typed.source !== undefined && typed.source === source ? typed.rest : query;
@@ -239,6 +241,7 @@ export const searchNotes = async (store, query, { limit = 20, offset = 0, tag, f
                 limit: Math.max(window, CANDIDATES),
                 command,
                 ...(env === undefined ? {} : { env }),
+                ...(embedders === undefined ? {} : { embedders }),
                 ...(folderIds === undefined ? {} : { folderIds }),
                 ...(withInternal ? { withInternal: true } : {}),
                 ...(source === undefined ? {} : { source }),

package/dist/services/search-all-meetings.d.ts

@@ -1,6 +1,7 @@
 import type { SearchHit } from "../meetings/index.js";
 import type { AccountKey, MessageStore } from "../store/store.js";
 import type { SearchFound, SearchQuery } from "./messages.js";
+import type { MeaningLane } from "./messages-discovery.js";
 import { type SearchAllFound, type SearchAllItem, type SearchAllMessenger, type SearchAllRequest, type Skipped } from "./search-all.js";
 export declare const RESOURCES_SEARCHED_WITH_MEETINGS: readonly ["messages", "mail", "notes", "meetings"];
 export type ResourceWithMeetings = (typeof RESOURCES_SEARCHED_WITH_MEETINGS)[number];
@@ -54,7 +55,7 @@ export interface SearchAllIncludingMeetingsFound extends Omit<SearchAllFound, "i
     meetings?: MeetingSearchCoverage;
 }
 /** Opt-in fusion of the existing unified ranking and one explicitly scoped meeting archive. */
-export declare const searchAllIncludingMeetings: (store: MessageStore, account: AccountKey, request: SearchAllIncludingMeetingsRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>) => Promise<SearchAllIncludingMeetingsFound>;
+export declare const searchAllIncludingMeetings: (store: MessageStore, account: AccountKey, request: SearchAllIncludingMeetingsRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>, meaning?: MeaningLane) => Promise<SearchAllIncludingMeetingsFound>;
 export interface SearchAllWithMeetingsRequest extends Omit<SearchAllIncludingMeetingsRequest, "meetingAccount"> {
     /**
      * `--source`: each kind reads the accounts the list names of it and a kind it names none of is skipped.
@@ -65,4 +66,4 @@ export interface SearchAllWithMeetingsRequest extends Omit<SearchAllIncludingMee
 /** Meetings have no index to search every account at once, so they are read only when named. */
 export declare const MEETINGS_UNNAMED = "meetings are searched only when --source names a meeting account, zoom or meetings";
 /** `search all`: every kind but meetings, unless `--source` names a meeting account. */
-export declare const searchAllWithMeetings: (store: MessageStore, account: AccountKey, request: SearchAllWithMeetingsRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>) => Promise<SearchAllIncludingMeetingsFound>;
+export declare const searchAllWithMeetings: (store: MessageStore, account: AccountKey, request: SearchAllWithMeetingsRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>, meaning?: MeaningLane) => Promise<SearchAllIncludingMeetingsFound>;

package/dist/services/search-all-meetings.js

@@ -124,7 +124,7 @@ const collectMeetings = async (store, account, request, query) => {
     return collected;
 };
 /** Opt-in fusion of the existing unified ranking and one explicitly scoped meeting archive. */
-export const searchAllIncludingMeetings = async (store, account, request, messenger = {}, searchMessages) => {
+export const searchAllIncludingMeetings = async (store, account, request, messenger = {}, searchMessages, meaning) => {
     whole(request.limit, 1, 1000, "limit");
     if (request.maxMeetings !== "all")
         whole(request.maxMeetings ?? 100, 1, Number.MAX_SAFE_INTEGER, "maxMeetings");
@@ -142,14 +142,14 @@ export const searchAllIncludingMeetings = async (store, account, request, messen
     cancelled(request.signal);
     const others = { ...request, only: only.filter((one) => one !== "meetings") };
     if (!only.includes("meetings")) {
-        const found = await searchAll(store, account, others, messenger, searchMessages);
+        const found = await searchAll(store, account, others, messenger, searchMessages, meaning);
         cancelled(request.signal);
         return found;
     }
     // Meetings rank with the rest, so a later page is the same merge read deeper, then cut.
     const offset = request.offset ?? 0;
     const window = offset + request.limit;
-    const legacy = await searchAll(store, account, { ...others, offset: 0, limit: window }, messenger, searchMessages);
+    const legacy = await searchAll(store, account, { ...others, offset: 0, limit: window }, messenger, searchMessages, meaning);
     cancelled(request.signal);
     const compiled = meetingQuery(request.text, request.exact);
     if ("reason" in compiled)
@@ -207,15 +207,15 @@ export const searchAllIncludingMeetings = async (store, account, request, messen
 /** Meetings have no index to search every account at once, so they are read only when named. */
 export const MEETINGS_UNNAMED = "meetings are searched only when --source names a meeting account, zoom or meetings";
 /** `search all`: every kind but meetings, unless `--source` names a meeting account. */
-export const searchAllWithMeetings = async (store, account, request, messenger = {}, searchMessages) => {
+export const searchAllWithMeetings = async (store, account, request, messenger = {}, searchMessages, meaning) => {
     if (request.source !== undefined)
-        return searchAllOfSource(store, account, request.source, request, messenger, searchMessages);
+        return searchAllOfSource(store, account, request.source, request, messenger, searchMessages, meaning);
     const only = request.only ?? RESOURCES_SEARCHED_WITH_MEETINGS;
     if (only.length === 1 && only[0] === "meetings")
         throw new CliError("validation_error", `--only meetings: ${MEETINGS_UNNAMED}`);
     if (request.maxMeetings !== undefined)
         throw new CliError("validation_error", `--max-meetings: ${MEETINGS_UNNAMED}`);
-    const found = await searchAll(store, account, { ...request, only: only.filter((resource) => resource !== "meetings") }, messenger, searchMessages);
+    const found = await searchAll(store, account, { ...request, only: only.filter((resource) => resource !== "meetings") }, messenger, searchMessages, meaning);
     return only.includes("meetings")
         ? {
             ...found,
@@ -235,7 +235,7 @@ const holdingMeetings = async (store, named) => {
     }
     return holding.length ? holding : named;
 };
-const searchAllOfSource = async (store, account, source, request, messenger, searchMessages) => {
+const searchAllOfSource = async (store, account, source, request, messenger, searchMessages, meaning) => {
     const only = request.only ?? RESOURCES_SEARCHED_WITH_MEETINGS;
     const entries = entriesOfList(source, await listContextOf(store, account, messenger.app));
     const { skipped } = fitting(entries, only, "search all", (kind) => `--only leaves ${kind} out`);
@@ -263,7 +263,7 @@ const searchAllOfSource = async (store, account, source, request, messenger, sea
         only: read,
         scope: { messages: named("messages"), mail: named("mail"), notes: named("notes") },
         ...(meetings[0] ? { meetingAccount: meetings[0] } : {}),
-    }, messenger, searchMessages);
+    }, messenger, searchMessages, meaning);
     const unnamed = only
         .filter((resource) => !read.includes(resource))
         .map((resource) => ({ resource, code: "not_found", reason: `--source names no ${resource} account` }));

package/dist/services/search-all.d.ts

@@ -3,6 +3,7 @@ import type { MailFields } from "../domain/models.js";
 import type { MessengerTraits } from "../ports/traits.js";
 import type { AccountKey, MessageStore } from "../store/store.js";
 import type { SearchFound, SearchQuery } from "./messages.js";
+import { type MeaningLane, type MeaningSkipped } from "./messages-discovery.js";
 import type { Backend, ServerOptions, ServerSearched } from "./server-search.js";
 export declare const RESOURCES_SEARCHED: readonly ["messages", "mail", "notes"];
 export type SearchedResource = (typeof RESOURCES_SEARCHED)[number];
@@ -62,6 +63,11 @@ export interface SearchAllFound {
         by: "words" | "words and meaning";
         meaningSkipped?: string;
     };
+    /** How the messages were searched, when they were; never by meaning with `exact` or the server alone. */
+    messages?: {
+        by: "words" | "words and meaning";
+        meaningSkipped?: MeaningSkipped;
+    };
     /** The messenger's server step for messages, as `search messages` reports it. */
     server?: ServerSearched;
 }
@@ -93,4 +99,4 @@ export type SearchAllMessenger = Partial<Pick<MessengerTraits, "savedChatId" | "
  * server, as `search messages` asks it — each list best first, merged by reciprocal rank so no
  * resource's own scores have to be compared with another's.
  */
-export declare const searchAll: (store: MessageStore, account: AccountKey, request: SearchAllRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>) => Promise<SearchAllFound>;
+export declare const searchAll: (store: MessageStore, account: AccountKey, request: SearchAllRequest, messenger?: SearchAllMessenger, searchMessages?: (query: SearchQuery) => Promise<SearchFound>, meaning?: MeaningLane) => Promise<SearchAllFound>;