@wirecat/cli-core 0.505.0 → 0.507.0

package/CHANGELOG.md

@@ -7,6 +7,73 @@ shape of this file.
 
 ## Unreleased
 
+## 0.507.0 — 31.10.2026
+
+### Added
+
+- **`messages sync --json` prints its progress on stderr**, for a window to draw a bar instead of an endless one
+  (WireCat Desktop). One JSON line each, counts only — never a chat's id or title:
+  `{"event":"progress","step":"sync","chats":3,"chats_done":1,"fetched":250}`. With `--all`, one once the chat list
+  is read (`chats_done` 0), then one after each chat, those passed as already current included; for one chat, one per
+  page with `chats` and `chats_done` `null`. At most about two a second; the first and last of `--all` always come.
+  Only in machine output (`--json`, `--jsonl`, or stdout not a terminal) and not in a `--background` job's log;
+  stdout still carries the one answer. Archive services take an optional `onChat` for the same counts.
+
+### Changed — may break callers
+
+- **Needs `@wirecat/cli-base` 0.68.0** (peer range `>=0.68.0 <0.69.0`). cli-base's `Credentials` in `auto` now reads
+  a sign-in the private file holds before the keyring and keeps its refreshes there (WC-SECR-4).
+
+### Fixed
+
+- **A new OAuth sign-in moves a file sign-in back to the keyring.** `TokenStorage.write` takes `{ signIn: true }`, and
+  the keeper's `signIn` and `save` pass it: the keyring is tried again and, once it takes the sign-in, the file copy
+  is removed. A refresh stays where the sign-in is, so a locked keyring is not tried for it on every refresh.
+
+## 0.506.0 — 31.10.2026
+
+### Added
+
+- **`QueriesStore.matchingPks`, `AccountVectors.scoreMessages` and `MeaningLane`'s fourth argument `within`**, which
+  lists a filter's messages once meaning can run: together they rank a filter's own messages. `fieldsOfQuery` and
+  `meaningWords` live in `src/search/lucene/meaning-parts.ts`, shared by notes and messages.
+
+- **`MailStore.saveThreads(inputs, states?)`.** Saves several threads and sync state (`{ accountId, name, value }`,
+  as `setSyncState` saves it) in one write transaction: all of it commits or none of it does. Like
+  `EventStore.saveSlots`, it lets a sync commit a slice of work with its resume point.
+
+### Changed — may break callers
+
+- **`search messages --discover` searches by meaning when the query uses `-`, `NOT`, `OR`, groups, phrases or
+  `exact:`.** Such a query used to run strict search alone, with no meaning hits. Now its words are still matched by
+  the whole query, as strict search does (`discovery.method: "lexical-strict"`), and the messages nearest in meaning
+  to its wanted words join them; every hit found by meaning, and every reply and follow-up discovery adds, matches
+  every field of the query and every excluded word, as notes do since 0.496.0. A field joined to the words by `OR`
+  narrows nothing. A query with no word to embed (`date:today`, `Helix*`) stays strict. On the owner's store, 6
+  such queries went from 0 meaning hits to 10–17 of 20, with no hit breaking the query.
+### Fixed
+
+- **Search by meaning inside a filter ranks the filter's own messages.** With fields that hold at most 100,000
+  messages (`RANK_WITHIN_MESSAGES`), `--discover` scores every one of them that has a vector, instead of taking the
+  100 nearest messages overall and dropping those outside the filter. On the owner's store, `chat:<id>` with a chat of
+  1,000 messages went from 3 meaning candidates to 100 and from 9 hits to 20. A larger filter, or one the store
+  cannot list in one query (a preset, a pattern), keeps the old way.
+- **`--discover` works on a read-only store.** Its follow-up step created a temporary table to count rare words,
+  which a read-only connection refuses; it now counts them with a bounded query.
+- **`mail sync` no longer holds the store's one writer lock for each email in turn.** It saves fetched mail in slices of
+  50 emails, each with the resume point in the same transaction, and pauses 100 ms between slices, so `memo sync` or
+  another process next to it can take the lock instead of failing with "database is locked". A run that fails resumes
+  after the last committed slice.
+- **A long fill or rebuild in one process no longer makes another process's write fail with "database is locked".**
+  `writeBatch` pauses 2 ms after each batch it commits. Without the pause, the next batch took the lock again within
+  microseconds, and a write waiting in another process (a command run during `store rebuild` or a migration's fill)
+  could miss every gap until its 5 s wait ran out.
+- **A forgotten memory's or fact's number is never given to a new one.** SQLite gave the next row the highest id + 1,
+  so after `memories.remove` or `facts.remove` of the newest record, the next one took its number and a stale
+  `memory:N` or `fact:N` named it. A remove now keeps the highest id handed out in `store_settings`
+  (`ids.memories.highest`, `ids.facts.highest`), and new memories and facts, restored project facts included, take
+  the next id above it. No schema change.
+
 ## 0.505.0 — 31.10.2026
 
 ### Added

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

@@ -12,6 +12,7 @@ import { JOBS_QUERY, jobItems } from "../../services/job-query.js";
 import { dateWindow } from "../../services/moment.js";
 import { validateCatchUpBounds } from "../../services/search-catchup.js";
 import { applyTaskRulesSinceLastPass } from "../../services/task-rules.js";
+import { stepLines } from "../../terminal/step-lines.js";
 import { environmentOf } from "../context.js";
 import { destroysNothing, FETCH, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -41,7 +42,8 @@ export const syncCommand = (messenger) => {
         cooperative: true,
     })
         .summary("fetch and save a chat's message history")
-        .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat")
+        .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat; " +
+        'with --json, stderr carries progress lines: {"event":"progress","step":"sync","chats","chats_done","fetched"}, counts only')
         .argument("[chat]", messenger.chatArgument)
         .option("--all", `every chat, most recently active first — what search needs; the last ${ALL_SINCE} unless --since-time or --last`)
         .option("--limit <n>", `at most this many messages in this run, per chat with --all; ${fetching.maxPages * fetching.page} if not given`, wholeNumber)
@@ -139,6 +141,8 @@ export const syncCommand = (messenger) => {
         const jobs = jobsDir(messenger.app, context.env);
         const jobId = context.env[envName(messenger.app, "BACKFILL_JOB")];
         const stop = stopOnSignal(this);
+        // A background job keeps its log as it was; its progress is the job file.
+        const progress = syncProgress(stepLines(context.streams.diagnostic, !jobId && context.format !== "pretty"));
         try {
             const options = {
                 limit,
@@ -149,10 +153,13 @@ export const syncCommand = (messenger) => {
                 ...(last === undefined ? {} : { last }),
                 note: context.renderer.note,
                 stop: stop.signal,
-                onPage: (progress) => {
+                onPage: (page) => {
                     if (jobId)
-                        updateJob(jobs, jobId, { progress: { ...progress, at: new Date().toISOString() } });
+                        updateJob(jobs, jobId, { progress: { ...page, at: new Date().toISOString() } });
+                    if (chat !== undefined)
+                        progress({ chats: null, chats_done: null, fetched: page.fetched });
                 },
+                onChat: ({ chats, done, fetched }) => progress({ chats, chats_done: done, fetched }, done === 0 || done === chats),
             };
             const result = await context.withServices((services) => chat === undefined ? services.archive.fetchAll(options) : services.archive.fetch(chat, options));
             if (jobId)
@@ -197,6 +204,22 @@ export const syncCommand = (messenger) => {
         }
     });
 };
+/** At most this often a progress line, so a run of fast pages or of chats already current does not flood the window. */
+const PROGRESS_EVERY_MS = 500;
+/**
+ * `messages sync`'s progress for a window to draw a bar by: counts only, because the lines reach a desktop app and
+ * its logs — never a chat's id or title. `always` keeps the first and the last line of `--all` through the throttle.
+ */
+const syncProgress = (emit) => {
+    let last = Number.NEGATIVE_INFINITY;
+    return (counts, always = false) => {
+        const now = Date.now();
+        if (!always && now - last < PROGRESS_EVERY_MS)
+            return;
+        last = now;
+        emit({ event: "progress", step: "sync", ...counts });
+    };
+};
 /**
  * What the sync stored, through the task rules (owner, 2026-10-14). A failure is noted, never the sync's failure:
  * the messages are already kept, and the next sync's pass starts from the same stop point.

package/dist/mail/sync.js

@@ -1,3 +1,4 @@
+import { setTimeout } from "node:timers/promises";
 import { CliError } from "@wirecat/cli-base";
 import { importEngine } from "../attachments/extract.js";
 import { addressOf, FETCH_CHUNK, MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
@@ -18,6 +19,8 @@ const DAY = 86_400_000;
 const EDGE = 2 * DAY;
 /** How often a long run saves where it is, so a kill costs at most this much listing again. */
 const SAVE_EVERY_MS = 30_000;
+const SLICE_SIZE = 50;
+const SLICE_PAUSE_MS = 100;
 /** About a minute of listing; the 30-day window of the timer stays below it. */
 const RESUME_FROM = 5_000;
 export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
@@ -488,7 +491,8 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         inFolder.set(item.messageId, [...(inFolder.get(item.messageId) ?? []), Number(item.uid)]);
         uidsOf.set(folder, inFolder);
     }
-    const saveProgress = async () => {
+    const progressStates = () => {
+        const states = [];
         for (const [folder, searched] of searches) {
             if (searched.validity === undefined)
                 continue;
@@ -534,8 +538,13 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                 last: { ...thisRun, done: searched.uids.filter((uid) => within(merged, Number(uid))).length },
                 updatedAt: new Date(now()).toISOString(),
             };
-            await store.sync.setSyncState(key, resumeKey(folder), JSON.stringify(point));
+            states.push({ accountId, name: resumeKey(folder), value: JSON.stringify(point) });
         }
+        return states;
+    };
+    const saveProgress = async () => {
+        for (const { name, value } of progressStates())
+            await store.sync.setSyncState(key, name, value);
     };
     // Mail already stored is located before its UID is marked done, so a done UID always has its place.
     for (const folder of locatable) {
@@ -543,8 +552,39 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         await store.mail.setLocations(accountId, folder, searched.validity, uidsOf.get(folder) ?? new Map());
     }
     let savedAt = now();
+    // Fetched mail is saved in slices: one transaction holds the lock for a slice and carries the resume point, and the
+    // pause between slices lets another process take the lock (`await` over synchronous SQLite never yields).
+    const slice = [];
+    const flush = async (pause = false) => {
+        savedAt = now();
+        const batch = slice.splice(0);
+        if (batch.length === 0)
+            return saveProgress();
+        const ids = batch.flatMap(({ input }) => input.emails.map(({ externalId }) => externalId));
+        for (const id of ids)
+            settled.add(id);
+        try {
+            await store.mail.saveThreads(batch.map(({ input }) => input), progressStates());
+        }
+        catch (error) {
+            for (const id of ids)
+                settled.delete(id);
+            throw error;
+        }
+        for (const { done } of batch)
+            await done();
+        if (pause)
+            await setTimeout(SLICE_PAUSE_MS);
+    };
+    const enqueue = async (input, done) => {
+        slice.push({ input, done });
+        if (slice.length >= SLICE_SIZE)
+            await flush(true);
+    };
     const saveNow = async (force = false) => {
-        if (!force && now() - savedAt < SAVE_EVERY_MS)
+        if (force)
+            return flush();
+        if (now() - savedAt < SAVE_EVERY_MS)
             return;
         savedAt = now();
         await saveProgress();
@@ -560,7 +600,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     for (const { item, rule } of toRecord) {
         await stopIfAborted();
         const headers = item.headers;
-        await store.mail.saveThread({
+        const input = {
             accountId,
             externalId: item.threadId,
             now: startedAt,
@@ -588,10 +628,11 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     },
                 },
             ],
+        };
+        await enqueue(input, async () => {
+            envelopes++;
+            await tagStored(item);
         });
-        envelopes++;
-        settled.add(item.messageId);
-        await tagStored(item);
         await saveNow();
     }
     const fetchChunk = plan === undefined ? FETCH_CHUNK : (source.fetchBatch ?? FETCH_SLICE);
@@ -644,7 +685,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
             plan?.unreadable.delete(item.messageId);
             const header = mailHeadersOf(raws[index]);
             const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt }, attachments);
-            await store.mail.saveThread({
+            const input = {
                 accountId,
                 externalId: item.threadId,
                 now: startedAt,
@@ -670,13 +711,14 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                         attachments: files,
                     },
                 ],
+            };
+            await enqueue(input, async () => {
+                saved++;
+                await tagStored(item);
+                const boxes = upgraded.get(item.messageId);
+                if (boxes !== undefined)
+                    await store.mail.setMailboxes(accountId, boxes.map(envelopeBoxOf), new Map([[item.messageId, []]]), startedAt);
             });
-            saved++;
-            settled.add(item.messageId);
-            await tagStored(item);
-            const boxes = upgraded.get(item.messageId);
-            if (boxes !== undefined)
-                await store.mail.setMailboxes(accountId, boxes.map(envelopeBoxOf), new Map([[item.messageId, []]]), startedAt);
         }
         await saveNow();
     }

package/dist/oauth/keeper.js

@@ -137,13 +137,13 @@ export const tokenKeeper = (options) => {
             const extra = (await accept?.(received)) ?? undefined;
             await locked(async () => {
                 forget();
-                storage.write({ tokens: received, client, ...(extra ? { extra } : {}) });
+                storage.write({ tokens: received, client, ...(extra ? { extra } : {}) }, { signIn: true });
             });
             return { scopes: received.scopes };
         },
         save: (saved, extra) => locked(async () => {
             forget();
-            storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) });
+            storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) }, { signIn: true });
         }),
         signOut: ({ revoke = false } = {}) => locked(async () => {
             forget();

package/dist/oauth/storage.d.ts

@@ -1,4 +1,4 @@
-import { type CredentialSource, type CredentialsOptions } from "@wirecat/cli-base";
+import { type CredentialSource, type CredentialsOptions, type WriteOptions } from "@wirecat/cli-base";
 import type { OAuthClient, TokenSet } from "./provider.js";
 export interface StoredTokens {
     tokens: TokenSet;
@@ -29,7 +29,8 @@ export interface TokenStorage {
     /** Throws when the entry cannot be saved, so a sign-in fails before the browser, not after consent. */
     probe(): void;
     read(): StoredTokens | undefined;
-    write(input: Omit<EncodeInput, "previous">): void;
+    /** `signIn` moves an entry the file holds back to the keyring when it takes it (WC-SECR-4); a refresh leaves it. */
+    write(input: Omit<EncodeInput, "previous">, options?: WriteOptions): void;
     remove(): CredentialSource[];
 }
 export declare const oauthAccount: (providerId: string, profile: string) => string;

package/dist/oauth/storage.js

@@ -162,9 +162,9 @@ export const credentialStorage = (options) => {
             throw keyringFailure(error);
         }
     };
-    const save = (value) => {
+    const save = (value, writeOptions) => {
         try {
-            credentials.write(account, value);
+            credentials.write(account, value, writeOptions);
         }
         catch (error) {
             throw keyringFailure(error, value);
@@ -195,7 +195,7 @@ export const credentialStorage = (options) => {
             const value = current();
             return value === undefined ? undefined : codec.decode(value);
         },
-        write: (input) => save(codec.encode({ ...input, previous: raw(account) })),
+        write: (input, writeOptions) => save(codec.encode({ ...input, previous: raw(account) }), writeOptions),
         remove: () => {
             try {
                 return credentials.remove(account);

package/dist/search/lucene/meaning-parts.d.ts

@@ -0,0 +1,14 @@
+import type { QueryNode } from "@wirecat/cli-base/query";
+type Predicate = Extract<QueryNode, {
+    kind: "predicate";
+}>;
+/**
+ * What a hit found by meaning must still match: the query with each word it asks for taken as matched, since the
+ * meaning half stands in for those. Words it excludes, and every other field, stay. `everything` is a predicate every
+ * record of the corpus matches, as a wanted word's stand-in: an empty clause list would match nothing. `undefined`
+ * when nothing but wanted words is left, so any hit found by meaning fits.
+ */
+export declare const fieldsOfQuery: (root: QueryNode, everything: Omit<Predicate, "span">) => QueryNode | undefined;
+/** The words and phrases the query asks for, for the meaning half to embed; none it excludes, no field. */
+export declare const meaningWords: (root: QueryNode) => string;
+export {};

package/dist/search/lucene/meaning-parts.js

@@ -0,0 +1,38 @@
+const WORD_FIELDS = new Set(["text", "exact"]);
+/**
+ * What a hit found by meaning must still match: the query with each word it asks for taken as matched, since the
+ * meaning half stands in for those. Words it excludes, and every other field, stay. `everything` is a predicate every
+ * record of the corpus matches, as a wanted word's stand-in: an empty clause list would match nothing. `undefined`
+ * when nothing but wanted words is left, so any hit found by meaning fits.
+ */
+export const fieldsOfQuery = (root, everything) => {
+    let narrows = false;
+    const kept = (node) => {
+        if (node.kind === "boolean")
+            return {
+                ...node,
+                clauses: node.clauses.map(({ occur, node }) => {
+                    if (occur !== "must_not")
+                        return { occur, node: kept(node) };
+                    narrows = true;
+                    return { occur, node };
+                }),
+            };
+        if (!WORD_FIELDS.has(node.field)) {
+            narrows = true;
+            return node;
+        }
+        return { ...everything, span: node.span };
+    };
+    const fields = kept(root);
+    return narrows ? fields : undefined;
+};
+/** The words and phrases the query asks for, for the meaning half to embed; none it excludes, no field. */
+export const meaningWords = (root) => {
+    const wanted = (node) => node.kind === "boolean"
+        ? node.clauses.flatMap(({ occur, node }) => (occur === "must_not" ? [] : wanted(node)))
+        : WORD_FIELDS.has(node.field) && (node.operator === "term" || node.operator === "phrase")
+            ? [node.value]
+            : [];
+    return wanted(root).join(" ").trim();
+};

package/dist/services/archive.d.ts

@@ -39,6 +39,12 @@ export interface FetchOptions {
         chatId: string;
         oldest: number;
     }) => void;
+    /** `fetchAll` only: once the chat list is read, then after each chat, current or not; counts across every chat. */
+    onChat?: (progress: {
+        chats: number;
+        done: number;
+        fetched: number;
+    }) => void;
 }
 /** A type, not an interface: a job keeps it as a plain record. */
 export type Fetched = {

package/dist/services/archive.js

@@ -148,6 +148,8 @@ export const archiveService = (deps) => {
                 ...options,
                 catchUp: catchingUp ? (options.catchUp ?? {}) : false,
             });
+            const finished = () => options.onChat?.({ chats: chats.length, done: answer.items.length, fetched: answer.fetched });
+            finished();
             for (const chat of chats) {
                 if (options.stop.aborted || batch.stopped) {
                     answer.stopped = true;
@@ -155,6 +157,7 @@ export const archiveService = (deps) => {
                 }
                 if (await upToDate(chat)) {
                     answer.items.push({ chat: chat.id, title: chat.title, fetched: 0, complete: true, current: true });
+                    finished();
                     continue;
                 }
                 try {
@@ -183,6 +186,7 @@ export const archiveService = (deps) => {
                     const issue = batch.fail(chat.id, "history", error);
                     answer.items.push({ chat: chat.id, title: chat.title, fetched: 0, complete: false, error: issue.code, issue });
                 }
+                finished();
             }
             if (batch.failed > 0)
                 answer.batch = batch.result();

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

@@ -48,13 +48,28 @@ export interface MeaningSkipped {
  * The messages of these accounts nearest in meaning to the question, best first; or why there are none. `embedders`
  * is the search's own, when another part of it loads the same model.
  */
-export type MeaningLane = (question: string, accounts: AccountKey[], embedders?: Pick<WarmEmbedders, "get">) => Promise<{
+export type MeaningLane = (question: string, accounts: AccountKey[], embedders?: Pick<WarmEmbedders, "get">, 
+/**
+ * The store keys of a filter's own messages, to rank all of them instead of the nearest overall; `undefined` when
+ * the filter is too large. Asked only once meaning can run, so a search without the model never lists the filter.
+ */
+within?: () => Promise<number[] | undefined>) => Promise<{
     model: string;
     ranked: MeaningRanked;
     partly?: MeaningSkipped;
 } | {
     skipped: MeaningSkipped;
 }>;
+/**
+ * The most messages a filter may hold for meaning to rank every one of them that has a vector; above it, meaning
+ * takes the nearest overall and keeps those inside the filter, so a narrow filter loses some. Listing the filter costs
+ * ~2 µs a message and scoring ~22 µs a vector: on the owner's store (205k messages, 4% with vectors) a 30-day filter
+ * of 91k messages took ~0.2 s in all (cli-testing performance/search/messages-meaning-filters). Most messages have no
+ * vector, so the limit counts messages, not vectors; a store where all 100k have one would spend ~2 s.
+ */
+export declare const RANK_WITHIN_MESSAGES = 100000;
+/** What a hit not found by the query's words must match: as a search request's text or AST. */
+type Scope = Pick<SearchQuery, "text" | "ast">;
 /**
  * The query discovery searches. A question's own "?" would parse as a one-character wildcard and send it to strict
  * search (BUG-395); the colon of a time or ratio ("22:00", "1:1") would parse as a field and fail the whole search,
@@ -63,7 +78,7 @@ export type MeaningLane = (question: string, accounts: AccountKey[], embedders?:
 export declare const discoveryRequest: (asked: SearchQuery) => SearchQuery;
 export declare const searchDiscovery: (store: MessageStore, account: AccountKey, asked: SearchQuery, messenger?: Partial<Pick<MessengerTraits, "savedChatId" | "app" | "history" | "provider">>, meaning?: MeaningLane, rerank?: RerankLane) => Promise<SearchFound>;
 /** The nearest messages the question's filters allow, as hits, nearest first. */
-export declare const nearEligible: (store: MessageStore, account: AccountKey, request: SearchQuery, messenger: Partial<Pick<MessengerTraits, "savedChatId" | "app" | "history" | "provider">>, ranked: MeaningRanked, scope: string) => Promise<(FoundMessage & {
+export declare const nearEligible: (store: MessageStore, account: AccountKey, request: SearchQuery, messenger: Partial<Pick<MessengerTraits, "savedChatId" | "app" | "history" | "provider">>, ranked: MeaningRanked, scope: Scope) => Promise<(FoundMessage & {
     cosine: number;
 })[]>;
 /** What the reranker reads of a hit, as the benchmark gave it: its reply parent first, each line headed by where, who and when. */

package/dist/services/messages-discovery.js

@@ -1,7 +1,9 @@
 import { CliError } from "@wirecat/cli-base";
-import { implicitTextTerms, walkQuery } from "@wirecat/cli-base/query";
+import { implicitTextTerms, parseLucene, walkQuery } from "@wirecat/cli-base/query";
 import { parseLocator } from "../domain/locator.js";
-import { exhausted, QUERY_LIMITS } from "../search/lucene/types.js";
+import { fieldsOfQuery, meaningWords } from "../search/lucene/meaning-parts.js";
+import { validateFields } from "../search/lucene/registry.js";
+import { exhausted, MESSAGE_PARSING, QUERY_LIMITS } from "../search/lucene/types.js";
 import { planQuestion, words } from "../search/question-plan.js";
 import { searchCombined } from "./messages-combined.js";
 import { prepareLucene, searchLucene } from "./messages-search.js";
@@ -28,6 +30,25 @@ const FOLLOW_UPS_PER_HIT = 2;
 const RARE_AT = 3;
 /** Later messages read per hit before the search's filters; the latest that pass are kept. */
 const FOLLOW_UP_CANDIDATES = 20;
+/**
+ * The most messages a filter may hold for meaning to rank every one of them that has a vector; above it, meaning
+ * takes the nearest overall and keeps those inside the filter, so a narrow filter loses some. Listing the filter costs
+ * ~2 µs a message and scoring ~22 µs a vector: on the owner's store (205k messages, 4% with vectors) a 30-day filter
+ * of 91k messages took ~0.2 s in all (cli-testing performance/search/messages-meaning-filters). Most messages have no
+ * vector, so the limit counts messages, not vectors; a store where all 100k have one would spend ~2 s.
+ */
+export const RANK_WITHIN_MESSAGES = 100_000;
+/** Every message matches it: a wanted word's stand-in, and what a search with no text runs. */
+const EVERY_MESSAGE = {
+    kind: "predicate",
+    field: "date",
+    operator: "range",
+    value: "*",
+    upper: "*",
+    lower_inclusive: true,
+    upper_inclusive: true,
+};
+const scopeOf = (root) => root === undefined ? {} : { ast: { version: 1, language: "lucene-v1", root } };
 /**
  * The query discovery searches. A question's own "?" would parse as a one-character wildcard and send it to strict
  * search (BUG-395); the colon of a time or ratio ("22:00", "1:1") would parse as a field and fail the whole search,
@@ -46,20 +67,35 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
     const original = await prepareLucene(store, account, request, messenger);
     const text = request.text ?? "";
     const plan = planQuestion(text, request.ast !== undefined || !!request.exact || !!request.newest);
-    if (request.ast !== undefined || request.exact || request.newest || implicitTextTerms(text).size === 0)
+    if (request.ast !== undefined || request.exact || request.newest)
         return searchLucene(store, account, request, messenger);
     const implicit = implicitTextTerms(text);
-    if (!plan.changed &&
-        walkQuery(original.execution.root).some((node) => (node.field === "text" || node.field === "exact") &&
-            (node.operator !== "term" || node.field === "exact" || !implicit.has(node.span.start))))
+    // Explicit syntax (-, OR, NOT, groups, phrases, exact:, wildcards) keeps the whole query for the words; meaning
+    // reads only its wanted words, and its hits must still match every field and every excluded word.
+    const explicit = implicit.size === 0 ||
+        (!plan.changed &&
+            walkQuery(original.execution.root).some((node) => (node.field === "text" || node.field === "exact") &&
+                (node.operator !== "term" || node.field === "exact" || !implicit.has(node.span.start))));
+    const root = explicit
+        ? validateFields(parseLucene(text, { ...MESSAGE_PARSING, defaultField: "text" })).root
+        : undefined;
+    const question = root === undefined ? text : meaningWords(root);
+    if (!question)
         return searchLucene(store, account, request, messenger);
-    const terms = [...new Set(plan.terms.concat(plan.aliases.flatMap((alias) => words(alias.split(" -> ")[1] ?? ""))))];
+    const terms = root === undefined
+        ? [...new Set(plan.terms.concat(plan.aliases.flatMap((alias) => words(alias.split(" -> ")[1] ?? ""))))]
+        : [...new Set(words(question))];
     if (!terms.length)
         return searchLucene(store, account, request, messenger);
     if (terms.length > 64)
         exhausted("discovery terms");
+    const narrowing = root === undefined ? undefined : fieldsOfQuery(root, EVERY_MESSAGE);
+    const scope = root === undefined ? (plan.scope ? { text: plan.scope } : {}) : scopeOf(narrowing);
     // 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 within = scope.text !== undefined || scope.ast !== undefined
+        ? () => filterPks(store, account, { ...request, text: undefined, ast: undefined, ...scope }, messenger)
+        : undefined;
+    const lane = meaning ? await meaning(question, original.scopeAccounts, undefined, within) : undefined;
     let started = performance.now();
     const check = () => {
         if (request.signal?.aborted)
@@ -75,7 +111,7 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         union.set(m.locator, { ...previous, ...m, fused: (previous?.fused ?? 0) + 1 / (60 + rank + 1) });
     });
     // Natural questions use one ranked partial lookup; repeated all-word lookups cannot rescue their wording gaps.
-    for (const query of plan.changed ? [] : plan.queries) {
+    for (const query of plan.changed || root !== undefined ? [] : plan.queries) {
         check();
         const found = await searchCombined(store, account, { ...request, text: query, limit: 300 }, messenger, {
             candidateDepth: 300,
@@ -89,7 +125,7 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         truncated ||= found.hasMore || found.query.combined.truncated;
     }
     check();
-    const relaxed = `(${terms.join(" OR ")})${plan.scope ? ` ${plan.scope}` : ""}`;
+    const relaxed = root === undefined ? `(${terms.join(" OR ")})${plan.scope ? ` ${plan.scope}` : ""}` : text;
     const partialRequest = { ...request, text: relaxed, ast: undefined, limit: 300, context: 0, thread: undefined };
     const partial = await searchLucene(store, account, partialRequest, messenger);
     add(partial.items);
@@ -116,8 +152,9 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
                 request.only.some((key) => key.provider === m.provider && key.account === m.account && key.chatId === m.chatId && key.id === m.id));
             const eligible = await searchLucene(store, account, {
                 ...request,
-                text: plan.scope || undefined,
+                text: undefined,
                 ast: undefined,
+                ...scope,
                 limit: 500,
                 only,
                 context: 0,
@@ -178,7 +215,7 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         Number(parentByLocator.has(b.locator)) - Number(parentByLocator.has(a.locator)));
     let meaningCandidates = 0;
     if (lane && "ranked" in lane) {
-        const near = await nearEligible(store, account, request, messenger, lane.ranked, plan.scope);
+        const near = await nearEligible(store, account, request, messenger, lane.ranked, scope);
         meaningCandidates = near.length;
         candidates = fusedWithMeaning(candidates, near, described);
     }
@@ -228,7 +265,7 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         started += performance.now() - opening;
     }
     check();
-    const followUps = await followUpsOf(store, account, request, messenger, candidates, plan.scope);
+    const followUps = await followUpsOf(store, account, request, messenger, candidates, scope);
     const items = await Promise.all(candidates.slice(0, request.limit).map(async ({ fused: _fused, ...hit }) => {
         const later = followUps.get(hit.locator);
         const m = later?.length ? { ...hit, followUps: later } : hit;
@@ -254,14 +291,14 @@ export const searchDiscovery = async (store, account, asked, messenger = {}, mea
         query: {
             ...partial.query,
             discovery: {
-                method: "lexical-partial",
+                method: root === undefined ? "lexical-partial" : "lexical-strict",
                 candidateDepth: 300,
                 candidates: candidates.length,
                 repliesAdded: replyCount,
                 followUps: [...followUps.values()].reduce((sum, later) => sum + later.length, 0),
                 truncated,
                 terms,
-                queries: [...(plan.changed ? [] : plan.queries), relaxed],
+                queries: [...(plan.changed || root !== undefined ? [] : plan.queries), relaxed],
                 ...(lane && "ranked" in lane ? { meaning: { model: lane.model, candidates: meaningCandidates } } : {}),
                 ...(reranked ? { rerank: reranked } : {}),
             },
@@ -286,7 +323,7 @@ const followUpsOf = async (store, account, request, messenger, candidates, scope
     const out = new Map();
     if (!only.length)
         return out;
-    const eligible = await searchLucene(store, account, { ...request, text: scope || undefined, ast: undefined, limit: only.length, only, context: 0, thread: undefined }, messenger);
+    const eligible = await searchLucene(store, account, { ...request, text: undefined, ast: undefined, ...scope, limit: only.length, only, context: 0, thread: undefined }, messenger);
     const allowed = new Map(eligible.items.map((m) => [m.locator, m]));
     const shown = new Set();
     head.forEach((hit, i) => {
@@ -302,6 +339,15 @@ const followUpsOf = async (store, account, request, messenger, candidates, scope
     });
     return out;
 };
+/**
+ * The store keys of the messages a filter holds, when there are at most `RANK_WITHIN_MESSAGES`; `undefined` when more,
+ * or when only a full search could list them.
+ */
+const filterPks = async (store, account, request, messenger) => {
+    const { execution } = await prepareLucene(store, account, request, messenger);
+    const pks = await store.queries.matchingPks(execution, RANK_WITHIN_MESSAGES);
+    return pks === undefined || pks.length > RANK_WITHIN_MESSAGES ? undefined : pks;
+};
 /** The nearest messages the question's filters allow, as hits, nearest first. */
 export const nearEligible = async (store, account, request, messenger, ranked, scope) => {
     const keyOf = (one) => JSON.stringify([one.provider, one.account, one.chatId, one.id]);
@@ -311,7 +357,7 @@ export const nearEligible = async (store, account, request, messenger, ranked, s
         .map(({ provider, account, chatId, id }) => ({ provider, account, chatId, id }));
     if (!only.length)
         return [];
-    const eligible = await searchLucene(store, account, { ...request, text: scope || undefined, ast: undefined, limit: only.length, only, context: 0, thread: undefined }, messenger);
+    const eligible = await searchLucene(store, account, { ...request, text: undefined, ast: undefined, ...scope, limit: only.length, only, context: 0, thread: undefined }, messenger);
     const hits = new Map(eligible.items.map((hit) => {
         const { provider, account } = parseLocator(hit.locator);
         return [keyOf({ provider, account, chatId: hit.chatId, id: hit.id }), hit];