@avantf/dsh-mem 0.7.0 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@avantf/dsh-mem",
-  "version": "0.7.0",
-  "description": "avantf-mem DSH native Cordis plugin: host service + tools + RPC + client tabs 记忆/知识",
+  "version": "0.8.0",
+  "description": "avantf-mem DSH native Cordis plugin: host service + memory tools + RPC + client 记忆 tab",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -42,6 +42,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.0",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
@@ -52,6 +53,9 @@
     "@deepseek-ai/cordis": {
       "optional": true
     },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-system-prompt": {
       "optional": true
     },
@@ -67,8 +71,6 @@
   },
   "dependencies": {
     "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
-    "exceljs": "^4.4.0",
-    "unpdf": "^1.8.1",
     "yaml": "^2.5.0"
   },
   "optionalDependencies": {
@@ -78,10 +80,9 @@
   },
   "devDependencies": {
     "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
-    "@avantf/mem": "0.7.0",
-    "@avantf/mem-contract": "0.7.0",
-    "@avantf/mem-convert": "0.7.0",
-    "@avantf/mem-provision": "0.7.0",
+    "@avantf/mem": "0.8.0",
+    "@avantf/mem-contract": "0.8.0",
+    "@avantf/mem-provision": "0.8.0",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "lightningcss": "^1.32.0",
@@ -98,16 +99,16 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@gitee.com:ffeng86/dsh-plugins.git",
-    "directory": "mem/packages/plugin"
+    "url": "git@gitee.com:ffeng86/dsh-mem.git",
+    "directory": "packages/plugin"
   },
   "author": "qunqi.ff",
   "scripts": {
-    "build": "node ../../scripts/link-dsh.mjs && node ../../scripts/link-envinit.mjs && tsc -p tsconfig.json && node ../../scripts/copy-envinit-bootstrap.mjs && node ../../scripts/carry-engine-types.mjs && tsdown",
+    "build": "node ../../../build/scripts/link-base.mjs && node ../../scripts/link-dsh.mjs && node ../../scripts/link-envinit.mjs && tsc -p tsconfig.json && node ../../scripts/copy-envinit-bootstrap.mjs && node ../../scripts/carry-engine-types.mjs && tsdown",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
-    "typecheck": "node ../../scripts/link-dsh.mjs && tsc -p tsconfig.test.json",
-    "test": "vitest run",
-    "test:dsh": "vitest run --config vitest.dsh.config.ts"
+    "typecheck": "node ../../../build/scripts/link-base.mjs && node ../../scripts/link-dsh.mjs && tsc -p tsconfig.test.json",
+    "test": "node ../../../build/scripts/link-base.mjs && node ../../scripts/link-envinit.mjs && vitest run",
+    "test:dsh": "node ../../../build/scripts/link-base.mjs && vitest run --config vitest.dsh.config.ts"
   }
 }

package/lib/engine/mem/config/domains.d.ts

@@ -1,20 +0,0 @@
-/**
- * Append one 知识域 to the STORE config's top-level `domains` allowlist
- * (`~/.avantf/configs/knowledge.yaml`, layer ③ of `loader.ts`) and return the new list.
- *
- * This is the write half of the UI-only `kbAddDomain` path, so the user adds a domain once in the
- * 知识 tab instead of hand-editing YAML. It writes to the STORE config rather than the common one:
- * `knowledge.domains` is resolved from layer ③ (the file the loader parses with
- * `KnowledgeConfigSchema`), and a second source of truth would make "where do I change it?" a
- * question again.
- *
- * `parseDocument` + `toString` (never `parse`/`stringify`): the comments in that file are the
- * documentation for the keys around them, and a round-trip that drops them quietly turns a
- * documented config into a bare list. When `domains` is already a sequence the node is mutated IN
- * PLACE (`seq.add`), which keeps the comments attached to the key and its items; a missing key is
- * created.
- *
- * The write is temp file + atomic rename, the same shape as the managed document copy
- * (`doc_files.ts`): a crash mid-write must not leave a truncated config the next boot cannot parse.
- */
-export declare function addKnowledgeDomain(configPath: string, domain: string): string[];

package/lib/engine/mem/db/dao/chunks.d.ts

@@ -1,231 +0,0 @@
-/**
- * `doc_chunks` + `chunk_entities` + the `doc_chunks_fts` index — the knowledge read model.
- *
- * Every id list here is batched (`batches()`): candidate sets are derived from the CORPUS
- * (entity overlap, semantic top-k), not from the request, so a plain `IN (…)` would trip
- * SQLite's bind-parameter cap on a large store. That failure is silent on the search path
- * (it just drops a leg), which is exactly what batching prevents.
- */
-import type { DocumentChunk } from '../../../mem-contract/index.js';
-import type { Db } from '../port.js';
-/** One chunk to persist, in document order (`idx` is the position, not the array index). */
-interface ChunkInsert {
-    idx: number;
-    text: string;
-    headingsPath: string;
-    sourceRef: string;
-    charStart: number;
-    charEnd: number;
-}
-/**
- * A chunk plus the state of everything DERIVED from it (DESIGN §20).
- *
- * `content_hash` says which text the derivations were built from, `embedding_model` which
- * vector space they live in, `entities_version` which extraction rules produced the entity
- * rows. `reindex` decides per row what actually needs redoing from these; without them it has
- * to assume every row is stale and pay for the whole corpus.
- */
-export interface ChunkStateRow {
-    chunk_id: number;
-    text: string;
-    content_hash: string | null;
-    embedding_model: string | null;
-    entities_version: number | null;
-    /** `1` when a non-NULL vector blob is stored (SQLite has no boolean). */
-    has_vector: number;
-}
-/** A persisted chunk with the entity names extracted at ingest time. */
-interface ChunkEntityRow {
-    chunk_id: number;
-    names: readonly string[];
-}
-/** A search hit row: chunk body plus the owning document's identity. */
-export interface ChunkHitRow {
-    chunk_id: number;
-    text: string;
-    source_ref: string;
-    domain: string;
-    source: string;
-    created_at: string | null;
-    updated_at: string | null;
-}
-export declare class ChunksDao {
-    private readonly db;
-    constructor(db: Db);
-    idsForDoc(docId: number): number[];
-    /** Re-ingest replaces the chunk set wholesale (entities/FTS follow via cascade/triggers). */
-    deleteForDoc(docId: number): void;
-    /** Insert the doc's chunks in one statement per chunk; returns the new ids in order. */
-    insertMany(docId: number, chunks: readonly ChunkInsert[]): number[];
-    /** Chunk bodies by id (entity extraction + vector encoding after ingest). */
-    texts(ids: readonly number[]): {
-        chunk_id: number;
-        text: string;
-    }[];
-    /** Chunk rows for the catalog detail view, in document order (`DocumentDetail.chunks`). */
-    rowsForDoc(docId: number): DocumentChunk[];
-    /** Persist a chunk vector together with the vector space it belongs to. */
-    setVector(chunkId: number, bytes: Buffer, embeddingModel: string): void;
-    /**
-     * The doc's chunks WITH their stored vectors — the reuse index for a re-ingest.
-     *
-     * A re-ingest deletes and re-inserts every chunk (new ids), so without this the only way to keep a
-     * vector is to re-encode the same text; `vectorReusable` already knows how to tell "unchanged", but
-     * only `reindex` could use it. Read BEFORE the replace, inside its transaction.
-     */
-    vectorStateForDoc(docId: number): (ChunkStateRow & {
-        vec: Buffer | null;
-    })[];
-    /**
-     * Write a batch of vectors in ONE transaction.
-     *
-     * `setVector` is autocommit: each chunk costs a commit (measured 14.2 µs/row against 2.2 µs in a
-     * transaction, and on a WAL database every commit appends its dirty pages). Callers encode in
-     * batches anyway, so this is the same loop with the boundary moved out — and the transaction
-     * NEVER spans an `await` (the caller encodes first, then calls this).
-     */
-    setVectors(rows: readonly {
-        chunk_id: number;
-        bytes: Buffer;
-        embeddingModel: string;
-    }[]): void;
-    /** Record which extraction rules produced a chunk's entity rows (see `ENTITY_EXTRACTOR_VERSION`). */
-    setEntitiesVersion(ids: readonly number[], version: number): void;
-    /** Every persisted chunk vector, for rebuilding the in-memory index at open. */
-    /**
-     * Every persisted chunk vector, with the space it was written in.
-     *
-     * `embedding_model` is selected too (not just the bytes) so a reload can DETECT a model swap: a
-     * dim-valid vector from another space is still ranked, and without this the two spaces would mix
-     * in one index silently — the memory side had the check, the knowledge side did not.
-     */
-    vectorRows(): {
-        id: number;
-        vec: Buffer;
-        embedding_model: string | null;
-    }[];
-    /**
-     * Vector-space health of the WHOLE chunk corpus, by kind, WITHOUT decoding a single blob.
-     *
-     * The same two counts the open-time warning reports (`stale` = wrong width, `space_stale` = same
-     * width but another recorded space — `embedding_model IS NOT` is null-safe, so a row with no
-     * recorded space counts as foreign exactly like the JS comparison in `reloadIndex`) plus `missing`
-     * (no vector at all), which is the third reason the semantic leg cannot use a chunk.
-     *
-     * This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
-     * re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
-     * not).
-     *
-     * The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
-     * this projection is bound to it by the cross assertions in
-     * `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
-     * migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
-     * changes: the mirror is checked, not shared.
-     */
-    vectorSpaceCounts(space: string, expectedBytes: number): {
-        stale: number;
-        space_stale: number;
-        missing: number;
-    };
-    /** Chunks with no persisted vector — the repair flow's `missing` term in `remaining`. */
-    countMissingVectors(): number;
-    /**
-     * Chunks the semantic leg cannot use (no vector / wrong width / another space), bounded and
-     * ordered by id — the repair flow's encode source.
-     *
-     * The content-hash check `vectorReusable` adds is deliberately NOT here: a chunk whose vector is
-     * in the current space is usable even if its text was edited behind the store's back, and that
-     * (rarer) case belongs to `kb_reindex`, which re-derives every leg. Repairing the SPACE must not
-     * pay a jieba/hash pass over the corpus to find rows the space change did not touch.
-     */
-    staleVectorRows(space: string, expectedBytes: number, limit: number): {
-        chunk_id: number;
-        text: string;
-    }[];
-    count(): number;
-    /**
-     * Replace the entity rows of the given chunks in one transaction.
-     *
-     * `replace` is REQUIRED, not defaulted: `true` clears the old rows first (the entity sweep, where
-     * the extractor may have changed), `false` is the ingest path, where the chunk ids are freshly
-     * inserted and an absent old row set. A default would let one caller silently inherit the other's
-     * semantics — an extra `DELETE` per chunk on ingest, or an append-on-top-of-stale sweep.
-     */
-    replaceEntities(rows: readonly ChunkEntityRow[], replace: boolean): void;
-    /** Batched entity bags: `Map<chunkId, names>` (ids with none are absent). */
-    entityBags(ids: readonly number[]): Map<number, string[]>;
-    /** Chunk body + owning-document identity for the fused candidate ids. */
-    hits(ids: readonly number[]): ChunkHitRow[];
-    /** `(chunk_id, domain, source)` for the semantic top-k, to apply the domain/source filter. */
-    meta(ids: readonly number[]): {
-        chunk_id: number;
-        domain: string;
-        source: string;
-    }[];
-    /**
-     * Corpus rows for the rebuild legs, optionally scoped to one domain, together with the state
-     * of their derivations. This is the `reindex` source: the caller compares `content_hash` /
-     * `embedding_model` / `entities_version` against what it is about to produce and only pays
-     * for the rows that are actually out of date (DESIGN §20).
-     */
-    corpusState(domain?: string): ChunkStateRow[];
-    /**
-     * Chunk rows whose `chunk_entities` were produced by OLDER extraction rules — the entity sweep's
-     * selection, bounded and ordered by id.
-     *
-     * `COALESCE(entities_version, 0) < :version`, not `entities_version != :version`: the column is
-     * NULLABLE on purpose (a row written before the derived-state columns existed must look stale
-     * exactly once and be adopted by the first rebuild — see `ChunkStateRow`), and a bare `<` would
-     * evaluate to NULL for those rows and let them hide from the sweep forever.
-     *
-     * The predicate is index-served in id order (`doc_chunks` is keyed by `chunk_id`), so the LIMIT
-     * bounds what is READ, not only what is rebuilt — the same property `FactsDao.staleEntityRows`
-     * documents for the memory side.
-     */
-    chunkEntityRows(version: number, limit: number, domain?: string): {
-        chunk_id: number;
-        text: string;
-    }[];
-    /** How many chunks still carry entity rows from older rules — the sweep's `deferred` source. */
-    countStaleEntityChunks(version: number, domain?: string): number;
-    /** Rebuild the FTS index from the content table (write-path maintenance). */
-    rebuildFts(): void;
-    /** Active chunks sharing at least one entity name with the query (jaccard candidate set). */
-    /**
-     * Entity-overlap candidates, highest-score first and CAPPED (see the memory store's sibling;
-     * the score/order tail itself lives in `./shared.js#entityCandidateTail`).
-     *
-     * `limit` is applied per name-batch and the batches are unioned, so the result is bounded by
-     * `limit x ceil(names/batch)` — corpus-independent, which is what this query can promise. The
-     * caller is expected to enforce the real `cap` on the union AFTER scoring it (it re-computes the
-     * true Jaccard in JS): a union of per-batch tops is not a top-N, and a leg that returns more than
-     * the cap makes `scores.size === legCap` — the "was this leg trimmed" signal — report the opposite
-     * of the truth. (The memory store's sibling does not batch, so its single `LIMIT` is already exact.)
-     */
-    candidatesByEntityNames(names: readonly string[], domain: string | undefined, source: string | undefined, limit: number, queryWidth: number, widthCap: number): number[];
-    /**
-     * How many chunks carry each name — the knowledge side of the entity leg's document frequency.
-     *
-     * Mirrors `EntitiesDao.activeDocFrequency`: only the caller's query names are looked up. There is
-     * no status column to filter on (see `candidatesByEntityNames`), so "document frequency" is over
-     * all chunks, which is the population the leg ranks.
-     */
-    docFrequency(names: readonly string[]): Map<string, number>;
-    /** FTS leg (`bm25` rank; negated by the caller so higher = better). */
-    ftsSearch(ftsQuery: string, domain?: string, source?: string, limit?: number): {
-        id: number;
-        rank: number;
-    }[];
-    /**
-     * The knowledge store's SHORT-QUERY fallback leg — the sibling of `FactsDao.ftsSubstringSearch`
-     * (see it for the score/tie/verify notes; the predicate itself is shared through
-     * `db/tokenizer.ts#likeSubstring`). It reads `doc_chunks` directly rather than the external-content
-     * FTS table: no index can serve a two-character pattern anyway, and the `documents` join is where
-     * the domain/source filter lives.
-     */
-    ftsSubstringSearch(terms: readonly string[], domain?: string, source?: string, limit?: number): {
-        id: number;
-        rank: number;
-    }[];
-}
-export {};

package/lib/engine/mem/db/dao/documents.d.ts

@@ -1,51 +0,0 @@
-/**
- * `documents` — the knowledge corpus identity table (`domain → source → title`).
- *
- * Identity is the `(domain, source, title)` unique key, so `upsert` is `INSERT OR IGNORE`
- * followed by a lookup: a re-ingest of the same document must land on the SAME `doc_id`
- * (chunks are replaced under it), never create a second row.
- */
-import type { Db } from '../port.js';
-import type { DocumentRecord, DocumentSummary } from '../../../mem-contract/index.js';
-/**
- * The stored document rows. The PAYLOAD shapes live in the contract (`kb list`/`kb detail` return
- * them verbatim, and the settings page imports them), so these are aliases rather than a second
- * declaration — a column added here without the contract would be a type error, not a silent
- * extra field on the wire.
- */
-type DocumentRow = DocumentSummary;
-type DocumentDetailRow = DocumentRecord;
-export declare class DocumentsDao {
-    private readonly db;
-    constructor(db: Db);
-    /** Idempotent upsert by the unique key; returns the existing or newly created id. */
-    upsert(domain: string, source: string, title: string, sourceUri?: string): number;
-    /**
-     * One row by the unique identity `(domain, source, title)`, or `null` when no such document
-     * exists. Walks the `UNIQUE(domain, source, title)` index — the add-only guard's existence test.
-     */
-    find(domain: string, source: string, title: string): DocumentRow | null;
-    /**
-     * Bump `updated_at` and record the URI that was actually read. `COALESCE` keeps the
-     * previous URI when this ingest did not come from one (plain text has none).
-     */
-    touch(docId: number, sourceUri?: string): void;
-    /**
-     * Catalog page: newest first, optionally scoped to one domain and/or source.
-     *
-     * `limit`/`offset` page it for the UI (which renders one page at a time); omitting `limit` keeps
-     * the historical "everything" behavior the CLI and MCP surfaces expect.
-     */
-    list(domain?: string, source?: string, limit?: number, offset?: number): DocumentRow[];
-    get(docId: number): DocumentDetailRow | null;
-    /**
-     * The distinct domains the library already holds, sorted. This is the "already in the library"
-     * half of the domain allowlist: a name in use must stay usable (and selectable) even when the
-     * configured allowlist would not have accepted it as a NEW domain.
-     */
-    domains(): string[];
-    /** `true` when a document was actually deleted (cascades chunks/entities/FTS). */
-    remove(docId: number): boolean;
-    count(): number;
-}
-export {};

package/lib/engine/mem/db/hash.d.ts

@@ -1,2 +0,0 @@
-/** Stable content digest (sha1: change detection, not security). */
-export declare function contentHash(text: string): string;

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

@@ -1,17 +0,0 @@
-import { type OpenedStore, type StoreSchema } from './store.js';
-/** Knowledge DB schema: documents under `domain → source`, split into chunks. */
-export declare const KNOWLEDGE_DDL: string[];
-/**
- * The external-content FTS5 table, created separately so the tokenizer can be
- * chosen at open time (same DESIGN §16 mitigation as the memory store).
- */
-export declare function chunksFtsTableDdl(tokenizer: string): string;
-/**
- * Ordered schema steps. Step 1 is the base schema and MUST stay idempotent: a database
- * created before this mechanism existed reports `user_version = 0` while already holding it.
- */
-export declare const KNOWLEDGE_SCHEMA: StoreSchema;
-/** Open (or create) the knowledge DB, bringing its schema up to the current version. */
-export declare function openKnowledgeDb(path: string): OpenedStore['db'];
-/** Open and report which migrations ran (tests, and any explicit upgrade path). */
-export declare function openKnowledgeStore(path: string): OpenedStore;

package/lib/engine/mem/eval/index.d.ts

@@ -1,4 +0,0 @@
-export * from './metrics.js';
-export * from './loader.js';
-export * from './runner.js';
-export * from './write_metrics.js';

package/lib/engine/mem/git.d.ts

@@ -1,73 +0,0 @@
-import type { AvantfLogger } from '../mem-contract/index.js';
-/**
- * A reusable git wrapper for the stores' on-disk artifacts.
- *
- * It is deliberately root-agnostic: the knowledge corpus (`knowledge.docs.dir`, the default root)
- * is one use, and "share a whole store" is another — point `root` at `~/.avantf/knowledge` or
- * `~/.avantf` and pass an `ignore` list so the databases stay out of the history. The caller owns
- * WHAT is versioned; this owns HOW, and nothing else in the codebase needs to know git exists.
- *
- * THREE PROPERTIES ARE LOAD-BEARING, and they are why this is not just `execFileSync` at each
- * call site:
- *
- *  - **It never throws.** Every caller writes here AFTER its real mission is durable (the row is
- *    committed, the document is indexed). A missing `git`, a locked index, or an unwritable repo
- *    must not turn a successful operation into a failed one — so failures are warned and swallowed,
- *    the same rule `IngestResult.file_error` follows for the managed file itself.
- *  - **It is always recognisable as automatic, and never invents an identity.** Every commit
- *    carries the `Automatic: avantf-mem` trailer. When the machine has an identity the commit is
- *    authored with it (the repo is the user's, and they may commit in it by hand — attributing
- *    their machine's mission to a bot by default would be the wrong kind of surprise); when it has
- *    NONE, the repo gets a LOCAL bot identity rather than failing or writing to the user's GLOBAL
- *    config, which is what lets the commit happen at all.
- *  - **It never commits an empty change.** `git status --porcelain` gates the commit, because
- *    `git add` + `git commit` with nothing staged fails, and a store write that changed nothing
- *    (a re-ingest of identical text) is common.
- */
-type GitMode = 'auto' | 'off';
-interface GitRepoOptions {
-    /** The directory this repo tracks. `init`/`commit` no-op when it does not exist. */
-    root: string;
-    /** `auto` (default) = create the repo on first commit; `off` = never invoke git at all. */
-    mode?: GitMode;
-    /**
-     * Patterns written to `.gitignore` when the repo is CREATED. An existing `.gitignore` is left
-     * alone. Only matters when `root` is broader than a text directory — e.g. pointing at a store
-     * directory brings the SQLite files with it, and those must never enter the history.
-     */
-    ignore?: readonly string[];
-    /** Committer used when the machine has no identity. Defaults to the avantf bot. */
-    identity?: {
-        name: string;
-        email: string;
-    };
-    logger?: AvantfLogger;
-    timeoutMs?: number;
-}
-export declare class GitRepo {
-    readonly root: string;
-    private readonly mode;
-    private readonly ignore;
-    private readonly identity;
-    private readonly logger?;
-    private readonly timeoutMs;
-    constructor(options: GitRepoOptions);
-    /** Whether git is in play at all (a disabled repo does nothing, silently and by design). */
-    get enabled(): boolean;
-    /**
-     * Create the repository if it is not one yet (writing `.gitignore` when it does). Idempotent and
-     * never throws; returns whether a repository exists afterwards.
-     */
-    init(): boolean;
-    /** Stage and commit whatever changed under `root`. No-op when nothing did. Never throws. */
-    commit(message: string): void;
-    /** Commit subjects, newest first. `[]` when git is off, absent, or the repo has no commits. */
-    history(limit?: number): string[];
-    /** Current branch, or `null` when unavailable (never throws — this is diagnostics only). */
-    branch(): string | null;
-    private ensureIdentity;
-    private writeIgnore;
-    private warn;
-    private git;
-}
-export {};

package/lib/engine/mem/router.d.ts

@@ -1,51 +0,0 @@
-import { type RecallHit, type RecallResult, type RetrievalFloorDrops } from '../mem-contract/index.js';
-interface CrossQueryOptions {
-    limit?: number;
-    kind?: 'all' | 'fact' | 'doc_chunk';
-    domain?: string;
-    source?: string;
-    /**
-     * Token budget for the merged result; `0` = unlimited, omitted = the caller already bounded
-     * the legs (the runtime lifts the per-store budgets for the pool and bounds the OUTCOME here,
-     * because fusion can reorder which entries deserve the text).
-     */
-    maxTokens?: number;
-    /**
-     * The knowledge leg's floor report. `KnowledgeStore.search` answers with hits only, so the
-     * runtime hands its captured `HybridResult` drops here; the memory side already arrives on
-     * `memory.dropped_by_floor`. Without this, the merged result would report only half the floors.
-     */
-    kbDroppedByFloor?: RetrievalFloorDrops;
-}
-/** The memory search result the router derives degradation/weights from. */
-type CrossQueryMemory = Pick<RecallResult, 'hits' | 'degraded' | 'weights' | 'floors' | 'dropped_by_floor'>;
-/**
- * Joint min-max normalization over the MERGED pool — the rule the cross-store score
- * contract is defined by (DESIGN §7).
- *
- * Degenerate case (every candidate carries the same score — including a pool of one):
- * the raw score is KEPT. A collapsed range encodes no ranking information, so rescaling
- * it would invent a "perfect match" out of an absolute fused score that may say
- * otherwise. `minMaxNormalize` maps the same case to 1 instead, which is right there
- * because it only ever feeds a relative weighted sum inside ONE fusion path; the two
- * differ deliberately rather than by oversight.
- *
- * Returns COPIES: the inputs are the stores' own result objects, and callers still
- * read their original scores.
- */
-export declare function normalizeMergedScores<T extends {
-    score: number;
-}>(pool: T[]): T[];
-/**
- * Cross-retrieval router: merge memory + knowledge hits, joint min-max normalize
- * the final fused scores over the *combined* pool (so the two stores' scores are
- * comparable), then rank by score.
- *
- * Degradation and weights are inherited from the memory search result rather
- * than hardcoded: both stores share the same semantic adapter, so
- * `memory.degraded`/`memory.weights` already describe whether the semantic leg
- * ran. Reporting a fixed `degraded: true` here made every `kb_query` look
- * degraded even when embeddings were live.
- */
-export declare function crossQuery(memory: CrossQueryMemory, kb: RecallHit[], opts?: CrossQueryOptions): RecallResult;
-export {};

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

@@ -1,125 +0,0 @@
-/** The frontmatter a managed file carries; `content_hash` is the body AS INGESTED. */
-interface DocFileMeta {
-    doc_id: number;
-    domain: string;
-    source: string;
-    title: string;
-    source_uri: string | null;
-    ingested_at: string;
-    content_hash: string;
-    /**
-     * The `@avantf/mem-convert` converter that produced the body, when the source was converted
-     * (absent for text and PDF, and for every file written before this field existed — readers must
-     * treat it as optional, which is why it is not `null`).
-     */
-    converter?: string;
-}
-/** One managed file as the file system sees it now. */
-interface DocFileState {
-    path: string;
-    stale: boolean;
-    missing: boolean;
-}
-/** A parsed managed file: frontmatter (possibly partial — a hand-written file may omit it) + body. */
-interface ParsedDocFile {
-    meta: Partial<DocFileMeta>;
-    body: string;
-}
-/** One path segment, made safe and human-readable; `fallback` covers names that sanitize away. */
-export declare function sanitizeSegment(raw: string, fallback: string): string;
-/**
- * A stable title for a body that arrived as TEXT (a paste), where there is no file name to borrow.
- *
- * Pasted text has no `source_uri` to name it after, and `source` defaults to the same value for
- * every paste — so without this, every untitled paste into one domain collapsed onto one identity
- * and the second ingest silently replaced the first. The rule: the first Markdown ATX heading,
- * else the first non-empty line with its block markers stripped.
- *
- * Fenced code is stepped over in BOTH halves: `#include` is not a heading, and a fence opener is
- * not a title. `MAX_SEGMENT` is the same cap the file name uses, so a long line cannot produce a
- * title the managed path has to truncate differently. Empty input falls back to `untitled`, and the
- * result depends only on the text (same body → same title), which is what keeps a re-paste
- * landing on the SAME identity instead of quietly creating a sibling every time.
- */
-export declare function deriveDocTitle(text: string): string;
-/** sha256 of a document body — the staleness key. */
-export declare function bodyHash(body: string): string;
-/**
- * Render one managed file: frontmatter (JSON-encoded values, so any title/URI survives) + body.
- *
- * The body is written VERBATIM — no trailing newline is added. `content_hash` records the ingested
- * text, and `state` compares it against the file's body, so anything this function normalizes
- * would make every document read as edited the moment it was written.
- *
- * An `undefined` value is OMITTED rather than rendered: JSON.stringify(undefined) is the bare token
- * `undefined`, which the tolerant parser would then hand back as the string "undefined". Optional
- * keys (today: `converter`) therefore simply do not appear for the documents that lack them.
- */
-export declare function renderDocFile(meta: DocFileMeta, body: string): string;
-/**
- * Split one managed file into frontmatter and body.
- *
- * Deliberately tolerant: a file without frontmatter (or with a hand-mangled one) is ALL body —
- * the user's content is never thrown away because a header key is missing, and the caller decides
- * what an unknown `doc_id` means.
- */
-export declare function parseDocFile(text: string): ParsedDocFile;
-/**
- * The managed document directory.
- *
- * Paths are `<root>/<domain>/<source>/<title>.md`, sanitized per segment. Collisions resolve by
- * asking the EXISTING file who it belongs to: a file whose frontmatter names another `doc_id` is
- * left alone and this document takes the `<title>~<doc_id>.md` variant. Without that check two
- * documents that sanitize to the same name would take turns clobbering each other.
- */
-export declare class DocFiles {
-    private readonly root;
-    constructor(root: string);
-    /** The directory holding one document's file (created on write, not here). */
-    dirFor(domain: string, source: string): string;
-    /**
-     * The file NAME for a title, minus the directory: a title that is already a Markdown file name
-     * (`kb ingest --uri notes.md` names the document after the file) must not become `notes.md.md`.
-     */
-    fileName(title: string, suffix?: string): string;
-    /** The base path for a title (before collision handling). */
-    basePath(domain: string, source: string, title: string): string;
-    /**
-     * The file this document owns: the base path, or its `~<doc_id>` variant when the base path is
-     * taken by a DIFFERENT document. Purely derived — no state is written to answer this.
-     */
-    pathFor(docId: number, domain: string, source: string, title: string): string;
-    /** Write the managed file for one document (atomic: temp file + rename). Returns its path. */
-    write(meta: DocFileMeta, body: string): string;
-    /** Parse one managed file, or `null` when it does not exist. */
-    read(path: string): ParsedDocFile | null;
-    /**
-     * A cheap per-file stamp — `mtimeMs:size`, no reads — or `null` when the file is absent.
-     *
-     * This is a TRIGGER, never a judgement: same-second edits, coarse filesystem timestamps and
-     * `cp -p` can all leave it unchanged, so a matching stamp means "probably unchanged" and only
-     * `state()` (which hashes the body) decides. The point is that the common case costs one `stat`
-     * per file instead of reading and hashing every file in the corpus.
-     */
-    stamp(path: string): string | null;
-    /** Every `.md` path under the root. A directory walk WITHOUT reads — no frontmatter, no hashing. */
-    listPaths(): string[];
-    /** Is this document's file there, and does it still match what was ingested? */
-    state(docId: number, domain: string, source: string, title: string): DocFileState;
-    /** Delete this document's file. `false` when there was nothing to delete. */
-    remove(docId: number, domain: string, source: string, title: string): boolean;
-    /**
-     * Every `.md` under the root, with the `doc_id` its frontmatter names (when it names one).
-     * Used to report orphans — files left behind by a document that no longer exists.
-     *
-     * ASYNC and batched: the walk itself is an async recursive `readdir` (a `readdirSync` gathers
-     * every entry in one ~41 ms call at 10k files), and the per-file parse is a `read` — at 10k
-     * documents that is a second full read of the corpus on top of `sync`'s staleness pass, and it
-     * used to be one uninterrupted synchronous block (performance review §7.5 / P6).
-     */
-    scan(): Promise<{
-        path: string;
-        doc_id?: number;
-    }[]>;
-}
-export {};