@avantf/dsh-mem 0.3.0 → 0.4.0

package/lib/engine/mem/store/knowledge.d.ts

@@ -0,0 +1,483 @@
+import { type AvantfLogger, type Config, type DocumentDetail, type DocumentSummary, type DomainCatalog, type FloorProfile, type ImportResult, type IngestResult, type KbConflictReport, type KbIngestConflict, type KbSyncReport, type KnowledgeConfig, type RecallHit, type ReindexReport } from '../../mem-contract/index.js';
+import type { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import { type LexicalProbe } from './lexical.js';
+import { type FloorLeg } from './floors.js';
+import { type HybridResult } from './hybrid.js';
+/** Options for {@link KnowledgeStore.search}. */
+export interface KnowledgeSearchOptions {
+    domain?: string;
+    source?: string;
+    limit?: number;
+    /** Overrides the config-derived fusion pool size; never smaller than `limit`. */
+    overFetch?: number;
+    /**
+     * Pre-encoded query vector, when the caller already has one — the cross-store router encodes a
+     * query ONCE and hands the same vector to both stores. Not verified, so it must come from the
+     * same backend.
+     */
+    queryVector?: Float32Array;
+    /** Per-call output token budget; `0` = unlimited, omitted = `retriever.max_output_tokens`. */
+    maxTokens?: number;
+    /**
+     * Relevance-floor profile: omitted = the default policy (configured floors, plus one relaxed pass
+     * if they empty the result — see `MemoryStore`'s `SearchInput.floors`), `'strict'` = no fallback,
+     * `'loose'` = the relaxed floors outright. The cross-store router passes a profile explicitly for
+     * each pass, because only the MERGED result can decide whether relaxing is warranted.
+     */
+    floors?: FloorProfile;
+    /**
+     * Which legs a `'loose'` pass may lower (see `store/floors.ts`; same contract as
+     * `SearchInput.relaxLegs`). Internal: the cross-store router pins the MERGED strict pass's
+     * dropping legs on its second call.
+     */
+    relaxLegs?: readonly FloorLeg[];
+    /** See `SearchInput.recordStats`: the cross-store router records the merged query once. */
+    recordStats?: boolean;
+    /**
+     * Receives the full `HybridResult` (floors, per-leg floor drops, used tokens) after the search.
+     *
+     * `search` answers with the hits only, because that is what its callers want; the cross-store
+     * router still has to fold THIS store's floor drops into the one merged `kb_query` result, and a
+     * store-level "last result" field would race two concurrent queries.
+     */
+    onResult?: (result: HybridResult<RecallHit>) => void;
+}
+/**
+ * One identity a write will land on: the title it will use, the resolved local path it would read
+ * (absent for text/URL), and — when the identity is taken — the document already sitting on it.
+ */
+export interface IngestTarget {
+    title: string;
+    path?: string;
+    existing?: KbIngestConflict;
+}
+/**
+ * What the plan stage resolved, with NO file content read and NO network touched (see
+ * {@link KnowledgeStore.ingestRequest}). A directory is expanded to its ingestable FILES here, so
+ * the `existing` test uses the basename identity `importPaths` actually writes.
+ */
+export interface IngestPlan {
+    kind: 'text' | 'url' | 'file' | 'paths';
+    /** The pasted body (kind `text`). */
+    text?: string;
+    /** The URL, or the `realpath` of the local file (kinds `url`/`file`). */
+    uri?: string;
+    /** The caller's paths (kind `paths`), for the replace dispatch through `importPaths`. */
+    paths?: string[];
+    /** Every ingestable file the request expands to. */
+    files: string[];
+    /** Files a directory walk refused by format (reported by a batch import). */
+    skipped: string[];
+    targets: IngestTarget[];
+}
+/** One ingestion request, whichever field it came from. `overwrite` only matters in replace mode. */
+export interface IngestRequest {
+    text?: string;
+    source_uri?: string;
+    paths?: string[];
+    domain: string;
+    source?: string;
+    title?: string;
+    overwrite?: boolean;
+}
+/** The two runtime faces of {@link KnowledgeStore.ingestRequest}. */
+export type IngestMode = 'add' | 'replace';
+export declare class KnowledgeStore {
+    private readonly semantic;
+    private readonly vstore;
+    private readonly reranker;
+    /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
+    private readonly domainConfigPath;
+    private readonly logger?;
+    private readonly db;
+    /**
+     * The tokenizer `doc_chunks_fts` was ACTUALLY built with, read from the database at open.
+     *
+     * Not `resolveFtsTokenizer()`: `CREATE VIRTUAL TABLE IF NOT EXISTS` never rebuilds an existing
+     * table, so a database created under another SQLite build keeps the tokenizer it was born with,
+     * and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
+     */
+    private readonly ftsTokenizer;
+    private readonly config;
+    private readonly kbConfig;
+    /** All SQL for this store lives behind these (DESIGN §19). */
+    private readonly docs;
+    private readonly chunks;
+    /** The editable `.md` copy of every document (`knowledge.docs.dir`). */
+    private readonly docFiles;
+    /** > 0 while a batch (directory import) is writing: commits and baseline refreshes wait. */
+    private deferCorpusWrites;
+    /**
+     * Per-file stamps (`path → mtimeMs:size`) and the file-set they were taken from, so a reconcile
+     * can ask "what changed?" for the price of one `stat` per document instead of reading and
+     * hashing the whole corpus. `null` = no baseline yet.
+     */
+    private corpusStamps;
+    private corpusFileSet;
+    /** Version control for the corpus (`knowledge.git`); a failure here is never fatal. */
+    private readonly corpusGit;
+    /**
+     * The LIVE domain allowlist — seeded at boot from `knowledge.domains` ∪ the library's existing
+     * domains, then kept in step with the store config by {@link addDomain}. The config itself is
+     * read once at startup (layer ③ of `loader.ts`), so a freshly added domain must land HERE or the
+     * very next write would refuse it until a restart.
+     */
+    private readonly allowedDomains;
+    /** Whether the config allowlist is active (non-empty); `false` = `domains: []` = no restriction. */
+    private readonly domainsRestricted;
+    constructor(dbPath: string, config: Config, kbConfig: KnowledgeConfig, semantic: SemanticBackend, vstore: VectorStore, reranker: Reranker, 
+    /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
+    domainConfigPath: string, logger?: AvantfLogger | undefined);
+    /**
+     * Rebuild the in-memory vstore from persisted chunk vectors.
+     *
+     * Also detects a VECTOR-SPACE change, which the reload itself cannot see: `reloadVectorIndex`
+     * checks the width, and a different model at the same width produces dim-valid vectors that are
+     * then ranked against the current query's — two spaces mixed in one index, with no error anywhere.
+     * The memory store always said something about this; the knowledge store did not, so a model swap
+     * degraded every semantic query here until someone happened to run `kb_reindex`.
+     */
+    private reloadIndex;
+    /**
+     * The write-side domain allowlist AND the 知识页 picker's data, in one place: the configured
+     * `knowledge.domains` allowlist ∪ the domains already present in `documents` ∪ the domains added
+     * through {@link addDomain} this session.
+     *
+     * `restricted: false` means the allowlist is EXPLICITLY empty (`domains: []`), the documented
+     * "no restriction" value. The union half is not a compatibility layer: without it, narrowing
+     * the allowlist would make every existing document un-re-ingestable, and the picker would offer
+     * a name the store then refuses.
+     */
+    domainCatalog(): DomainCatalog;
+    /** Refuse a `domain` outside the allowlist, naming every value that IS allowed. */
+    private assertDomainAllowed;
+    /**
+     * Add one domain to the live allowlist AND to the store config's `domains` list.
+     *
+     * The UI-only path (`kbAddDomain`) — deliberately NOT an agent tool: the asymmetry is the point,
+     * because an autonomous writer is exactly where domain sprawl would come from. The store owns the
+     * rules (trim / reject path separators / treat an existing name as a selection) so both halves
+     * agree, and it REFUSES while the allowlist is `[]` ("no restriction"): appending to an unfettered
+     * list would silently turn it into a restricted one.
+     */
+    addDomain(raw: string): DomainCatalog;
+    /**
+     * The shared ingestion entry: **① plan → ② classify → ③ dispatch**, in that fixed order.
+     *
+     * Stage ① resolves the domain allowlist, insists on one of `text`/`source_uri`/`paths`, derives
+     * the identity every target will be written under, and looks each one up — using the SAME
+     * {@link classifySource} the source picker uses, so the type (text / URL / local file / directory)
+     * is decided once. Stage ① MUST NOT read a file or touch the network: identity only needs
+     * `realpath`/`stat`/`readdir` plus the body of a pasted `text`, which the caller already holds. That
+     * is what makes "conflict before read" observable (a colliding `source_uri` answers with the
+     * collision even when the URL is unreachable or the file is a binary the reader would refuse).
+     *
+     * Stage ③ dispatches on the plan: `ingest` / `ingestUri` / `importPaths`. Those keep their
+     * replace-by-identity semantics; this entry only puts the plan in front of them.
+     *
+     * The two modes are the two public faces:
+     *  - `add` (`rt.kbAdd`, the model's `kb_add`): never replaces. A single collision throws an
+     *    actionable Chinese error; a batch collision is per-file (see `importNew`), because one
+     *    existing file in a 100-file import must not fail the other 99.
+     *  - `replace` (`rt.kb`, the UI/CLI): a collision comes back as a {@link KbConflictReport} and
+     *    writes NOTHING unless the caller confirmed with `overwrite: true`; then it re-runs the whole
+     *    request. All-or-nothing, so a partial write can never sit behind a confirmation dialog.
+     */
+    ingestRequest(req: IngestRequest, mode: IngestMode): Promise<IngestResult | ImportResult | KbConflictReport>;
+    /**
+     * Stage ①/②: resolve the request to its targets without reading anything.
+     *
+     * `paths` wins over `text`, which wins over `source_uri` — the same precedence the old
+     * `kb_add`/`rt.kb` split applied, kept so a call that sends two fields means the same thing.
+     */
+    private planIngest;
+    /** One target's identity plus whatever document already owns it. */
+    private target;
+    private planText;
+    private planUri;
+    /**
+     * A batch request: each caller path is classified (file or directory) and a directory is WALKED
+     * for its ingestable files. Only the walk filters by extension — an explicitly named file is taken
+     * as given, exactly like `importPaths`. Target identity is each FILE's `basename`, which is the
+     * identity `importPaths` actually writes (never the directory name).
+     */
+    private planPaths;
+    /** Stage ③, add mode: refuse a single collision, and split a batch's collisions into `failed`. */
+    private runAdd;
+    /**
+     * Batch add: the plan already knows which targets exist, so those are reported in `failed` (with
+     * the actionable text) and only the NEW files are handed to `importPaths`. Passing the expanded
+     * file list — not the caller's directories — is what keeps a walk from re-writing a colliding
+     * file; the walk's own `skipped` list is carried over because explicit files are never filtered.
+     */
+    private importNew;
+    /** Stage ③, replace mode (the caller confirmed, or nothing collided). */
+    private runReplace;
+    /** The machine-readable "nothing was written; confirm to overwrite" answer (UI + CLI). */
+    private conflictReport;
+    /**
+     * Add one document from TEXT, and never replace an existing one.
+     *
+     * This is the PASTE entry point of the add-only face, and the distinction is the whole point:
+     * `ingest` is replace-by-identity (what `ingestUri`, `importPaths`, `sync`'s re-ingest and `adopt`
+     * need), while a paste that lands on an existing identity is an ADD mistake — the user meant to
+     * save a new note, not to overwrite the one already filed. So this refuses instead of writing
+     * anything, naming the document it collided with (its `doc_id`, title and managed file) so the
+     * caller can choose a different title or edit that file.
+     */
+    ingestNew(text: string, domain: string, source?: string, title?: string): Promise<IngestResult>;
+    /**
+     * Ingest one document: chunk (paragraph/heading aware), persist chunks + entities,
+     * then encode vectors. Fully awaited — when ingest resolves, the document is
+     * searchable through every path (FTS, entity, semantic).
+     */
+    ingest(text: string, domain: string, source?: string, title?: string, sourceUri?: string, encoding?: string, 
+    /** What the automatic git commit should say this was (`adopt` = recovered from an overwrite). */
+    gitAction?: 'ingest' | 'sync' | 'adopt', 
+    /** The converter that produced `text` (absent for text/PDF and for a body re-read from disk). */
+    converter?: string, 
+    /** What that conversion could not carry over. */
+    warnings?: string[]): Promise<IngestResult>;
+    /** Materialize one document's editable copy; returns the `file` / `file_error` result fields. */
+    private writeManagedFile;
+    /** Batched eviction from the live vector index (removeMany when the backend supports it). */
+    private evictVectors;
+    /** The resolved ingestion boundary (see `ingest_guard.ts`). */
+    private get ingestLimits();
+    /**
+     * Ingest from a source URI (DESIGN D5): local file paths (workspace files are the
+     * priority source) are read from disk; `http(s)` URIs are fetched. The URI itself
+     * is NEVER stored as the document body — that was the old broken behavior.
+     *
+     * Both paths are bounded BEFORE materializing the content (the `MAX_DOC_CHARS`
+     * guard inside `ingest` can only run once the whole body is already in memory),
+     * and both are checked against the ingestion boundary: a local path must resolve
+     * inside the allowed roots and a URL must not address private space (see
+     * `ingest_guard.ts`).
+     *
+     * The URL-vs-path decision goes through the store's ONE classifier ({@link classifySource}, the
+     * same one the source picker and the plan stage use) — a second `^https?://` test here would be a
+     * second answer to "what is this string".
+     */
+    ingestUri(uri: string, domain: string, source?: string, title?: string): Promise<IngestResult>;
+    /**
+     * Extract entities per chunk (persisted) and encode/persist chunk vectors.
+     *
+     * Returns how many chunks did NOT get a vector, so the caller can put it in the tool result. A
+     * missing model counts every chunk that had no reusable vector: the document is still searchable by
+     * text and entity, but not semantically, and "入库成功 N 段" must not imply otherwise.
+     */
+    private indexChunks;
+    /**
+     * The doc's stored vectors that still APPLY, keyed by content hash (see {@link vectorReusable}).
+     *
+     * Called inside the ingest transaction, before the replace: two chunks with the same text are one
+     * hash, and the first row wins — the reuse is only a cache lookup, so a duplicate entry cannot be
+     * distinguished from a hit and need not be.
+     */
+    private reusableByHash;
+    /**
+     * Write back the vectors a re-ingest can reuse, and report which rows still need the model.
+     *
+     * A row is only reused when the lookup misses nothing: any row whose write fails, or whose text has
+     * no reusable vector, comes back in `remaining` and is encoded as before — so the reuse path cannot
+     * leave a chunk unindexed that the plain path would have indexed.
+     */
+    private writeReusedVectors;
+    /**
+     * Encode texts ONE AT A TIME, writing every `WRITE_BATCH` vectors in one transaction.
+     *
+     * The model call is deliberately NOT batched, and that is a MEASURED decision, not an omission:
+     * a batched forward pass pads each item to the longest in its group, and real chunks span 53–550
+     * characters (median 303). On 299 real chunks: serial 31.2 ms/text, batched in document order
+     * 55.7 ms/text (1.79x SLOWER), batched after sorting by length 31.9 ms/text (a wash). Batching
+     * only pays for SHORT homogeneous texts, which chunks are not — so the review's "batch the
+     * encode" suggestion was tested and rejected. `LocalBgeBackend.encodeBatch` remains correct (and
+     * length-sorted) for callers whose texts suit it.
+     *
+     * What DID pay off is the write side: one commit per `WRITE_BATCH` chunks instead of one per
+     * chunk (measured 14.2 µs/row vs 2.2 µs/row), and the transaction never spans an `await`.
+     */
+    private encodeAndStore;
+    /**
+     * Identity of the vector space this store currently writes into (DESIGN §20): a change of
+     * backend, model or width makes every stored chunk vector stale, and the whole point of
+     * recording it is that such a change is DETECTED instead of silently mixing two spaces.
+     */
+    private vectorSpace;
+    /**
+     * A stored vector is reusable when it exists, matches the space, and its text is unchanged.
+     *
+     * The three checks answer different questions, and the hash is deliberately the RAREST of them
+     * to fire (see `db/hash.ts`): `ingest` replaces chunks rather than editing their text, so a
+     * re-ingested change is caught by the missing vector, and a rule change by `entities_version`.
+     * The hash is what catches a text mutation that skipped the ingest path entirely — without it
+     * the store would keep serving a vector for text it no longer holds.
+     */
+    private vectorReusable;
+    /** One transaction replacing the entity rows of the given chunks (shared by ingest + reindex). */
+    private replaceChunkEntities;
+    /**
+     * Ingest local files/directories. Every path goes through the SAME boundary as
+     * `ingestUri` — a bare `kb_import` on `~/.ssh` would otherwise be the exact
+     * exfiltration hole the `source_uri` guard closes.
+     *
+     * Failure split: a caller-supplied path that is missing or out of bounds THROWS
+     * (validating the arguments up front, and the operator needs to know), while a file
+     * reached by walking a directory is reported in `failed` — the previous `catch {}`
+     * dropped those silently, so "imported 60 of 100 files" was indistinguishable from
+     * a complete import.
+     */
+    importPaths(paths: string[], domain: string, source?: string): Promise<ImportResult>;
+    /**
+     * One corpus commit + one baseline refresh, unless a batch is in flight.
+     *
+     * Every owned write calls this; `deferCorpusWrites` is what turns N writes into 1 commit during
+     * an import. Never throws (`GitRepo` swallows), and the baseline refresh is a no-op until one
+     * exists.
+     */
+    private commitCorpus;
+    list(domain?: string, source?: string, limit?: number, offset?: number): DocumentSummary[];
+    detail(docId: number): DocumentDetail | null;
+    remove(docId: number): boolean;
+    /**
+     * The managed path for a document ROW the caller already holds — skips the `docs.get` that
+     * `docFilePath` does, which matters because `kb_list` needs a path for every row it renders.
+     */
+    docFilePathOf(doc: {
+        doc_id: number;
+        domain: string;
+        source: string;
+        title: string;
+    }): string;
+    /** The managed file this document owns (whether or not it exists yet), or `null` for a missing doc. */
+    docFilePath(docId: number): string | null;
+    /**
+     * Reconcile the managed files with what the KB indexed (DESIGN: knowledge maintenance).
+     *
+     * `dryRun` answers "what changed?" without touching the index — that is what the 知识 tab's list
+     * uses to mark documents whose file was edited. Otherwise every STALE document is re-ingested
+     * from its file body, which replaces its chunks and re-encodes its vectors (the document keeps
+     * its `doc_id`: identity is `domain → source → title`, and the file records the same one).
+     *
+     * `missing` documents are reported, never invented: a file that was deleted by hand leaves the
+     * indexed copy alone until the user deletes the document itself. `orphans` are managed files no
+     * document claims — leftovers from a row deleted outside `remove` — and are only reported.
+     */
+    /**
+     * Stat-only reconcile check: which managed files look changed since the last call, and whether
+     * the file SET changed (a new or vanished `.md` — an orphan or a restore).
+     *
+     * Nothing here reads a file, so the common answer ("nothing changed") costs one `stat` per
+     * document. A stamp is a TRIGGER, not a judgement: the caller re-ingests through `sync`, which
+     * hashes the body and decides. The first call only seeds the baseline and reports nothing —
+     * use `sync` once at startup if a process may have been down while the corpus changed.
+     *
+     * ASYNC because one `stat` per document is exactly the cost that has to leave the event loop to
+     * something else once in a while: at 10k documents the walk blocked the host for >0.1 s per trip
+     * (measured — performance review §7.5 / P7), and this runs after every tool result behind a 2 s
+     * throttle. The baseline is still taken ATOMICALLY at the end, so a caller sees the same
+     * all-or-nothing update as before.
+     */
+    corpusDrift(): Promise<{
+        changed: number[];
+        missing: number[];
+        fileSetChanged: boolean;
+    }>;
+    /**
+     * Re-take the baseline after a write this store made ITSELF.
+     *
+     * Without this, every `ingest` would look like an external edit on the next drift check and cost
+     * a redundant (if harmless) sync; with it, only edits from OUTSIDE the store are reported. Cheap:
+     * one `stat` per document, no reads. A no-op until a baseline exists.
+     */
+    private noteCorpusWrite;
+    /**
+     * Take back a file that lost its frontmatter, when the caller explicitly asks for it.
+     *
+     * Cheap refusals, all of them deliberate: a file that CLAIMS another document is a collision and
+     * is left alone; an EMPTY body is refused because `ingest` has no lower bound (`chunkText('')`
+     * returns no chunks), so adopting one would silently replace a good document with nothing.
+     */
+    private adoptUnclaimed;
+    sync(opts?: {
+        docId?: number;
+        dryRun?: boolean;
+        adopt?: boolean;
+    }): Promise<KbSyncReport>;
+    /**
+     * Rebuild the read model: FTS, per-chunk entities, and vectors — incrementally.
+     *
+     * `domain` scopes the rebuild to one knowledge domain. One corpus SELECT feeds both legs, and
+     * each row is skipped when its derivation is provably still valid (same text digest, same
+     * vector space, same extractor version). Without that, the only way to know whether a chunk
+     * needed mission was to redo the mission: an ONNX forward pass plus a jieba pass per chunk over the
+     * whole corpus, every time.
+     *
+     * `dryRun` answers "how much would this cost?" without writing anything — including without
+     * the FTS rebuild, which is a write.
+     */
+    reindex(domain?: string, opts?: {
+        dryRun?: boolean;
+    }): Promise<ReindexReport>;
+    close(): void;
+    count(): {
+        documents: number;
+        chunks: number;
+    };
+    /** Chunk search over the knowledge corpus (semantic + FTS + entity, joint fusion). */
+    search(query: string, opts?: KnowledgeSearchOptions): Promise<RecallHit[]>;
+    /**
+     * This store's half of the shared orchestration (`store/hybrid.ts`): the legs, the chunk-row load
+     * and the chunk→hit mapping.
+     *
+     * The limit normalization, the over-fetch factor, the leg cap, the capped-leg counter, the
+     * degraded weights, the rerank and the output budget all live there now. They used to be copied
+     * here, and every fix landed on the memory side only — a `NaN` limit reached this store's SQL and
+     * took the whole cross-store query down with it, `retriever.over_fetch_factor` meant something
+     * different per store, and a capped knowledge leg was invisible to the health counters.
+     */
+    private hybridDeps;
+    /**
+     * The knowledge legs: semantic, FTS, and entity overlap against the entities extracted AT INGEST
+     * time (`chunk_entities`) — no corpus scan.
+     *
+     * Same cap as the memory store: fusion keeps `overFetch` entries, so a leg that returns the whole
+     * matching corpus only makes `fuse` normalize and sort it (see `MemoryStore.searchLegs`).
+     */
+    private searchLegs;
+    /** The texts of a candidate set, for the per-row FTS floor (one batched query). */
+    private chunkTexts;
+    /**
+     * Semantic leg. `queryVector` short-circuits the encode when the caller already
+     * encoded this exact query (the cross-store router does, for both stores at once); `onVector`
+     * publishes the vector this leg actually used, so the relaxed retry pass can reuse it instead of
+     * re-encoding (performance review §7.7 / P8).
+     */
+    private semanticPath;
+    /**
+     * Sync relevance probe for the plugin's conditional hint (DESIGN §12). Same contract as
+     * `MemoryStore.lexicalProbe` — see `store/lexical.ts`.
+     */
+    lexicalProbe(text: string, stopAt?: number): LexicalProbe;
+    private ftsPath;
+    /** Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan. */
+    private jaccardPath;
+}
+export interface Chunk {
+    text: string;
+    headingsPath: string;
+    /** Inclusive start offset in the source text. */
+    start: number;
+    /** Exclusive end offset in the source text. */
+    end: number;
+}
+/**
+ * Paragraph + heading aware chunking (DESIGN §8): markdown headings open a new
+ * block and maintain a headings stack; blank lines separate blocks; blocks are
+ * packed greedily up to `chunkSize`; oversized blocks are hard-split with
+ * `overlap`; consecutive chunks finally share `overlap` characters of context.
+ * Offsets always refer to the ORIGINAL text so `source_ref`/char positions stay
+ * faithful for provenance.
+ */
+export declare function chunkText(text: string, chunkSize?: number, overlap?: number): Chunk[];

package/lib/engine/mem/store/lexical.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The sync relevance probe behind the plugin's conditional hints (DESIGN §12).
+ *
+ * WHY THIS IS LEXICAL, AND WHY IT MUST BE SYNC. The hint has to be in place *before* the step's
+ * prompt is assembled — `dsh-agent-loop`'s `preStep` calls `systemPrompt.assemble()` immediately
+ * after the message is admitted, and the section/context provider that renders the hint is
+ * SYNCHRONOUS (it cannot await). Of the retrieval legs, only the FTS one is synchronous: the
+ * semantic leg needs an `encode()`, and a warm encode is ~10–20 ms, which loses the race and lands
+ * the hint one step late — i.e. after the model already decided whether to call a tool. So the
+ * gate is a lexical one, and paraphrase-style questions score 0 here. That is the accepted trade:
+ * it stays SILENT when unsure, and the always-on usage sections remain the fallback that tells the
+ * model to query anyway.
+ *
+ * THE BAR, AND HOW IT WAS MEASURED. Terms are latin/digit words of >= 5 chars plus every CJK
+ * 3-gram (the FTS tables are trigram-tokenised, so a 2-char CJK term cannot be expressed and a
+ * whitespace split leaves a whole Chinese sentence as ONE token — a single OR'd trigram query for
+ * such a sentence matches incidentally and its bm25 rank is *not* discriminative: measured
+ * -3.14 for an unrelated question vs -2.12 for a genuine one-word `cgroup` query). Counting how
+ * many DISTINCT terms each store actually holds separates cleanly instead. Measured on the live
+ * stores, 10 probes: the three genuinely-covered questions scored 6, 6 and 2 (`cgroup v2 的内存保护…`,
+ * its question form, `MGLRU 是怎么回收页面的`), the seven uncovered ones scored 0 or 1 — including
+ * an English question that matched common words — it scored 3 matched terms with a 4-char floor
+ * (`unit`, `test`, `this`, `for`) and only 1 once the floor was 5 (`write`), so the floor alone
+ * would not have saved it; BOTH the floor and the two-term bar are load-bearing. Hence
+ * `matched >= 2`, with the margin between 2 and 1 rather than a tuned threshold inside a
+ * continuum. A single-word query (`cgroup`) scores 1 and stays silent on purpose: one term is not
+ * evidence.
+ */
+/** How many of an input's terms a store holds. `terms === 0` means the input had nothing to test. */
+export interface LexicalProbe {
+    terms: number;
+    matched: number;
+}
+/**
+ * Which stores hold something relevant — the ONE answer the plugin's hint layer consumes.
+ *
+ * A boolean on purpose: `kb_query` retrieves from BOTH stores, so the hint only has to decide
+ * "worth mentioning or not". Which store matched is nobody's business downstream — and asking for
+ * it cost a distinction the probe would have to keep alive in two places.
+ */
+export type RelevanceHit = boolean;
+/**
+ * The distinct terms of `text` that the FTS tables can express.
+ *
+ * Exported for the store probes and for the tests that pin the measured behaviour above; the
+ * caller runs one `LIMIT 1` MATCH per term and counts the hits.
+ */
+export declare function relevanceTerms(text: string, cap?: number): string[];
+/**
+ * The gate itself: is this store worth telling the model about?
+ *
+ * Two distinct terms is the measured bar (see the module comment). Deliberately not "at least one"
+ * — a single hit is what a common word produces — and deliberately not a score threshold, because
+ * bm25 sums over OR'd terms and therefore rewards a long question for merely containing many
+ * 3-grams.
+ */
+export declare function looksRelevant(probe: LexicalProbe): boolean;
+/**
+ * Count how many of `text`'s terms ONE store holds.
+ *
+ * The loop both stores used to carry verbatim. `holds` is handed the raw TERM, not a built MATCH
+ * expression: turning a term into a query depends on the tokenizer the store's FTS table was actually
+ * built with (see `db/tokenizer.ts`), which is the store's business, not this module's. Each store
+ * asks its own table with `LIMIT 1` — the question is whether a term exists at all, not where it ranks. `stopAt` lets a caller that only asks "≥ 2?" stop early (`relevance()` does, and the prompt
+ * path is synchronous); the default keeps an exact count for the calibration recorded above.
+ */
+export declare function probeTerms(text: string, holds: (term: string) => boolean, stopAt?: number): LexicalProbe;