@avantf/dsh-mem 0.7.0 → 0.8.0

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

@@ -1,47 +0,0 @@
-/** What the first bytes say a document is. */
-type DocumentFormat = 'pdf' | 'binary' | 'text';
-/** How text bytes were decoded. Reported so a guess is visible instead of silent. */
-type DocumentEncoding = 'utf-8' | 'utf-8-bom' | 'utf-16le' | 'utf-16be' | 'gb18030';
-/** One document's indexable text, and where it came from. */
-export interface DocumentText {
-    text: string;
-    /**
-     * `pdf` = extracted text layer; `converter` = a document format turned into Markdown (see
-     * {@link DocumentText.converter}); `text` = decoded bytes (see {@link DocumentText.encoding}).
-     */
-    via: 'text' | 'pdf' | 'converter';
-    encoding?: DocumentEncoding;
-    /** Which `@avantf/mem-convert` converter produced the body (only when `via === 'converter'`). */
-    converter?: string;
-    /** What that conversion could not carry over (dropped media, a truncated sheet, …). */
-    warnings?: string[];
-}
-/** Classify one document by its leading bytes. */
-export declare function sniffFormat(bytes: Uint8Array): {
-    format: DocumentFormat;
-    kind?: string;
-};
-/**
- * Restore the ideographs pdfjs sometimes reports as compatibility codepoints.
- *
- * Some CJK PDFs extract `⽹站` (KANGXI RADICAL NET + 站) instead of `网站` — visually identical,
- * different codepoints, so a search for the real word misses. Only those three compatibility ranges
- * are normalized: NFKC over the whole text would also rewrite full-width punctuation (，。！？),
- * which is real content and must survive verbatim.
- */
-export declare function normalizeCjkCompatibility(text: string): string;
-/**
- * The text of one document, whatever its bytes are.
- *
- * CONVERSION RUNS FIRST, before the magic-number sniff and therefore before the binary rejection.
- * docx/xlsx/html/csv are converted to Markdown here, and the order is not cosmetic: docx and xlsx
- * are ZIPs, so a sniff-first pipeline would file them under "known binary" and refuse them. A
- * document no converter claims falls through to the text/PDF/binary paths unchanged.
- *
- * @param bytes - the whole document (already bounded by the byte cap).
- * @param label - the path or URL, used verbatim in error messages and as the sniff's extension hint.
- * @throws when the document is a binary we cannot read, is not decodable, or is a PDF without a
- * text layer.
- */
-export declare function documentText(bytes: Uint8Array, label: string): Promise<DocumentText>;
-export {};

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

@@ -1,25 +0,0 @@
-/** The boundary knobs, as resolved from `knowledge.ingest`. */
-export interface IngestLimits {
-    /** Roots a local `source_uri` may be read from; empty ⇒ the process workspace. */
-    local_roots: readonly string[];
-    allow_outside_workspace: boolean;
-    allow_private_network: boolean;
-}
-/**
- * Whether a URL hostname addresses loopback / private / link-local / other
- * non-public space. Names are matched by suffix too (`*.local` mDNS, `*.internal`,
- * `*.home.arpa`), since those resolve inside the LAN by construction.
- */
-export declare function isPrivateHostname(hostname: string): boolean;
-/** Validate one `http(s)` source URL, refusing non-public targets unless opted in. */
-export declare function assertFetchableUrl(uri: string, limits: Pick<IngestLimits, 'allow_private_network'>): URL;
-/** The roots a local `source_uri` may be read from (realpath'd), defaulting to the workspace. */
-export declare function allowedLocalRoots(limits: Pick<IngestLimits, 'local_roots'>): string[];
-/**
- * Resolve a local `source_uri` to the real absolute path it names, refusing one
- * that lands outside the allowed roots.
- *
- * @returns the `realpath` — which is what the caller should BOTH read and store, so
- *   the recorded `source_uri` is exactly the file that was read.
- */
-export declare function resolveLocalSource(raw: string, limits: IngestLimits): string;

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

@@ -1,598 +0,0 @@
-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, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsFixStoreReport } from '../../mem-contract/index.js';
-import type { 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';
-import { type VectorRepairTarget } from './vector_repair.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.rewriteQuery` (方案 A test seam); default = the intent table. */
-    rewriteQuery?: (query: string) => string | undefined;
-    /** 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;
-    /** P-01: attach per-leg evidence (`scores` / `final`) to every hit. Default false. */
-    includeScores?: boolean;
-}
-/**
- * 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;
-    /** 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;
-    /**
-     * Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
-     *
-     * The guard itself lives in that module; this is only the per-store identity it keys on. It exists
-     * as a field — rather than the adapter object, which is built per call — because the guard must
-     * survive between two overlapping calls: `reindex` can be reached from a tool call and the
-     * settings-page button at once, and both would select the same stale chunks.
-     */
-    private readonly entitySweepGuard;
-    /**
-     * 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, 
-    /** 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, and say loudly what belongs to
-     * another vector space.
-     *
-     * Also detects a VECTOR-SPACE change, which the reload itself cannot see: the reload 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 reload, the count and the warning are the SHARED open-time step (`store/vector_repair.ts`),
-     * which is what turned the knowledge store from "warns about a swapped model but never repairs it"
-     * into the same automatic path memory has always had; this store's half is the row read. The
-     * manual entry stays `vectors --fix` (the vector-only repair); `kb_reindex` remains the full
-     * FTS + entities + vectors re-entry.
-     */
-    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;
-    /** 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;
-    /**
-     * This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
-     * call, the live index and the `WRITE_BATCH` transaction this store measured its way into.
-     *
-     * 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` — that
-     * is the `writeBatch` below.
-     */
-    private encodeWriteTarget;
-    /**
-     * Encode texts one at a time and persist them in `WRITE_BATCH` transactions.
-     *
-     * A failed chunk is skipped, not thrown: the rows are already committed and their old vectors
-     * evicted by the ingest path, so a throw here would leave the caller with a failed ingest and NO
-     * COUNT of what was skipped. The shortfall travels back to the tool result
-     * (`IngestResult.vectors_failed`) instead of living only in a log line.
-     */
-    private encodeAndStore;
-    /**
-     * Identity of the vector space this store currently writes into (DESIGN §20): the representation
-     * fingerprint — backend, model, width AND the backend's declared pooling/normalization/input
-     * window/model revision — so any representation change makes stored chunk vectors stale instead
-     * of silently mixing two spaces. Public so diagnostics and tests can name the space.
-     */
-    vectorSpace(): string;
-    /**
-     * Cheapest possible DETECTION of "the embedding space changed under this store": counts of
-     * persisted chunk vectors whose width or recorded space id no longer matches the one this store
-     * writes into. Reads blob LENGTHS only — never decodes — so the startup warning and the background
-     * drive can afford it at any corpus size.
-     */
-    vectorSpaceHealth(): VectorSpaceHealth;
-    /** {@link vectorSpaceHealth} plus `missing`, the third term of the repair flow's `remaining`. */
-    private vectorSpaceCounts;
-    /** Async bootstrap the semantic backend (the shared flow's explicit-fix warmup). */
-    warmupSemantic(): Promise<boolean>;
-    /**
-     * This store's half of the shared repair flow (`store/vector_repair.ts`): the primitives the flow
-     * steps. The flow itself — batch size, event-loop yield, stop / resume / no-progress rules,
-     * `semantic.auto_migrate`, the dry-run split — lives there once, for both stores.
-     */
-    vectorRepairTarget(): VectorRepairTarget;
-    /**
-     * The chunks the semantic leg cannot use (no vector / wrong width / another space). One SQL
-     * aggregate over blob lengths; `dropIds` is empty because knowledge overwrites in place.
-     */
-    private classifyRepairVectors;
-    /**
-     * Encode + persist up to `limit` chunks the semantic leg cannot use, bounded and ordered by id.
-     *
-     * It does NOT re-extract entities or rebuild FTS: that is `kb_reindex`'s job, and the whole point
-     * of the automatic repair is that the vector half can run on its own — which is exactly the
-     * objection the "known boundary" in DESIGN §20 used to raise against a background run.
-     */
-    private reencodeStaleChunks;
-    /**
-     * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
-     * `dry_run` previews every count without writing — and without loading the model, which is why
-     * the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
-     */
-    vectorsFix(dryRun?: boolean): Promise<VectorsFixStoreReport>;
-    /**
-     * ONE bounded slice of the vector-space migration: at most `batchSize` chunks are re-encoded, so
-     * the caller keeps control of the event loop between slices. This is the unit the background
-     * migration ({@link migrateVectors}) and its tests drive.
-     */
-    migrateVectorsBatch(batchSize?: number): Promise<VectorMigrationProgress>;
-    /**
-     * Drive the bounded background migration for this store until it is current, the model is
-     * unavailable, or `shouldStop()` turns true (plugin unmount / process shutdown). The loop, the
-     * `semantic.auto_migrate` switch, the no-progress rule and the store-named logging all live in the
-     * shared flow (`store/vector_repair.ts`); this is the one-store entry.
-     */
-    migrateVectors(opts?: {
-        batchSize?: number;
-        shouldStop?: () => boolean;
-        onProgress?: (progress: VectorMigrationOutcome) => void;
-    }): Promise<VectorMigrationOutcome>;
-    /**
-     * 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;
-    /**
-     * Extract one chunk's entity names, bounded by `MAX_ENTITIES_PER_CHUNK`.
-     *
-     * The bound is here, not in either caller: it is a property of what `chunk_entities` may hold for
-     * one chunk, and the ingest path and the sweep must not disagree about it.
-     */
-    private extractRowEntities;
-    /** One transaction replacing the entity rows of the given chunks (the ingest path). */
-    private replaceChunkEntities;
-    /**
-     * The per-row primitive of the shared entity sweep (`store/entity_sweep.ts`).
-     *
-     * Replaces ONE chunk's entity rows and stamps that same row with `ENTITY_EXTRACTOR_VERSION`, in one
-     * transaction. Knowledge's domain difference from memory is exactly this: memory's transaction also
-     * moves triples, the HRR bundle and the conflict queue, while a chunk has none of those — its
-     * derived state is the entity names alone.
-     *
-     * Per row, not per batch, because the sweep's contract is that a failure leaves THAT row stale and
-     * retryable: inside a batched transaction one bad extraction would roll back the whole batch, and
-     * rows it never reached would look stamped.
-     */
-    private replaceRowEntities;
-    /**
-     * 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 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;
-    /**
-     * The semantic leg's scope filter, as a `filterTopk` primitive: `undefined` when NO domain/source
-     * was asked means "keep the whole pool" — the short-circuit is preserved, so no `chunks.meta`
-     * lookup runs at all. Otherwise one batched lookup, and rows whose domain/source do not match (or
-     * whose chunk is gone) are dropped.
-     */
-    private scopeFilter;
-    /**
-     * 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.
-     *
-     * Same metric as the memory store's sibling (`store/entity_leg.ts` carries the measurement and
-     * the reasoning): anchored Jaccard with a saturating union over the query's rare entities, so a
-     * wide chunk cannot dilute the denominator and a corpus-wide word cannot drag the whole knowledge
-     * base in.
-     */
-    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[];