@avantf/dsh-mem 0.6.0 → 0.6.2

package/lib/client.js

@@ -5346,6 +5346,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				offset: count.optional(),
 				reason: optionalText.optional(),
 				dry_run: bool.optional(),
+				store: optionalText.optional(),
 				contradiction_id: count.optional(),
 				resolution: optionalText.optional(),
 				loser_fact_id: count.optional()

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

@@ -104,12 +104,48 @@ export declare class ChunksDao {
         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).
+     */
+    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` clears the
-     * old rows first — used by reindex, where the extractor may have changed).
+     * 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;
+    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. */
@@ -127,11 +163,31 @@ export declare class ChunksDao {
      * 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, most-shared first and CAPPED (see the memory store's sibling).
+     * 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

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

@@ -0,0 +1,153 @@
+/**
+ * The DAO layer's SHARED ALGORITHMS AND CONTRACTS.
+ *
+ * DAOs are split by AGGREGATE, not by store (`docs/vector-repair-shared-flow.md` §2), and each
+ * aggregate keeps its own SQL text: replacing a readable statement with a generic
+ * table/column-parameterized builder would cost the comments' index reasoning without converging a
+ * business rule — a `count`/`get`/`delete`/`list` one-liner is a different aggregate's statement,
+ * not a fork (§4.5 "明确不收敛").
+ *
+ * What DOES get one implementation here is the part that is literally "one rule, two tables":
+ *
+ *  - the entity-candidate leg's SCORE and ORDER, plus its batch/union loop
+ *    ({@link entityCandidates} / {@link entityCandidateTail});
+ *  - the batched `UPDATE … SET entities_version = ?` ({@link setEntitiesVersionBatch});
+ *  - the short-query LIKE fallback's build/guard/double-bind protocol
+ *    ({@link likeSubstringLeg});
+ *  - the document-frequency query shape ({@link queryDocFrequency});
+ *  - the batched "entity-name bags for a row-id set" read ({@link entityBags}).
+ *
+ * Each caller still supplies its own statement (or its `FROM`/name/filter pieces), so the SQL stays
+ * at the call site while the rule lives here exactly once. No base class: every export is a free
+ * function, the style `store/common.ts` established.
+ */
+import type { Db } from '../port.js';
+/**
+ * The entity-candidate leg's ORDER contract — the tail every candidate statement ends with.
+ *
+ * The formula is the leg's own score (anchored Jaccard with a saturating union,
+ * `store/entity_leg.ts`): `shared / (queryWidth + min(total - shared, widthCap))`. Ordering by it is
+ * load-bearing, not cosmetic: `fuse` scales each leg by its maximum, and a survivor's scaled value
+ * is unchanged only when the ordering — and therefore the maximum — survives the trim. A narrower
+ * row sharing one entity can therefore outrank a wide one sharing two, and the cap keeps it.
+ * `total ASC` is only a deterministic tie-break among equal ratios, and the id makes the order total.
+ *
+ * `idColumn` is the aggregate's own id (`fa.fact_id` / `ce.chunk_id`); that, the `total` subquery's
+ * table and the filter predicates are the ONLY differences between the two statements.
+ */
+export declare function entityCandidateTail(idColumn: string): string;
+/** One call to the shared entity-candidate runner — see {@link entityCandidates}. */
+export interface EntityCandidateQuery {
+    /** The (anchor) names to match: one `IN (…)`, or one per batch when {@link batchNames}. */
+    names: readonly string[];
+    /**
+     * NULL-able filter values bound right AFTER the name list and BEFORE `queryWidth`, in the SQL's
+     * own order (both callers spell their predicates as `(? IS NULL OR …)`, so a value the filter
+     * does not use is still bound as `null`).
+     */
+    filterParams: readonly unknown[];
+    limit: number;
+    /** The query's FULL entity count (`W` in `store/entity_leg.ts`); `widthCap` is its saturating cap. */
+    queryWidth: number;
+    widthCap: number;
+    /**
+     * `true` (knowledge): run one statement per name-batch and UNION the ids, because the query can in
+     * principle carry more names than a single `IN (…)` may bind. A union of per-batch tops is NOT a
+     * top-N, so that caller must enforce its real cap on the union AFTER scoring.
+     * `false` (memory): one statement and one exact `LIMIT` — the store's names are request-bounded,
+     * so a single `LIMIT` is already the top-N and the cap argument above holds bit-for-bit.
+     */
+    batchNames: boolean;
+    /**
+     * The full statement for one placeholder list; it must project `id`, `shared`, `total` and end
+     * with {@link entityCandidateTail}.
+     */
+    sql: (placeholders: string) => string;
+}
+/**
+ * Run an entity-candidate query: bind order, batching and union are shared; the SQL is the caller's.
+ *
+ * Bind order (identical in both aggregates): `<names …>, <filterParams …>, queryWidth, widthCap, limit`.
+ */
+export declare function entityCandidates(db: Db, q: EntityCandidateQuery): number[];
+/**
+ * The batched `UPDATE … SET entities_version = ?` shared by `FactsDao` and `ChunksDao`.
+ *
+ * Only the aggregate's `table` / `idColumn` differ. Returns the summed `changes`; the knowledge
+ * caller ignores it (its method's signature returns `void`), the memory caller's `number` is
+ * unchanged.
+ */
+export declare function setEntitiesVersionBatch(db: Db, table: string, idColumn: string, ids: readonly number[], version: number): number;
+/** The per-aggregate pieces of the document-frequency query — see {@link queryDocFrequency}. */
+export interface DocFrequencyQuery {
+    /** `FROM …` with its JOINs: everything between the projection and `WHERE`. */
+    from: string;
+    /** The name expression (`e.name`, `name`), used as the alias, the IN predicate and `GROUP BY`. */
+    nameExpr: string;
+    /** A constant predicate ANDed after the IN clause; it must add NO bind parameters. */
+    where?: string;
+}
+/**
+ * Document frequency — "how many rows carry each name".
+ *
+ * Shared by `EntitiesDao.activeDocFrequency` and `ChunksDao.docFrequency`; the only difference is
+ * the population the caller's `where`/`from` describe (memory counts ACTIVE facts, knowledge has no
+ * status column and counts chunks). Only the caller's QUERY names are looked up, so this is one
+ * indexed COUNT per name rather than a corpus scan. A name absent from the map has frequency 0.
+ */
+export declare function queryDocFrequency(db: Db, names: readonly string[], q: DocFrequencyQuery): Map<string, number>;
+/** The two SQL fragments {@link likeSubstringLeg} hands back to the caller's statement builder. */
+export interface LikeSubstringFragments {
+    /** The `WHERE` predicate (OR of the term patterns). */
+    any: string;
+    /** The score expression (count of the terms the row contains), to be aliased as `rank`. */
+    count: string;
+}
+/**
+ * The SHORT-QUERY LIKE fallback shared by `FactsDao.ftsSubstringSearch` and
+ * `ChunksDao.ftsSubstringSearch`.
+ *
+ * The predicate text itself already comes from `db/tokenizer.ts#likeSubstring`; this owns the
+ * protocol AROUND it, which both copies spelled out:
+ *
+ *  1. build the fragments — empty terms yield no patterns, which means "match nothing" ⇒ `[]`;
+ *  2. `count` lands in the SELECT and `any` in the WHERE, so the SAME pattern list is bound TWICE:
+ *     once with the SELECT's placeholders, then — after the caller's filter params — with the
+ *     WHERE's;
+ *  3. `LIMIT ?` last, defaulting to `-1` (unbounded; the store bounds the leg).
+ *
+ * `ORDER BY rank DESC, <id> ASC` stays in the caller's SQL: the id column is aggregate-specific and
+ * `rank` must read the SELECT alias, so the fragments and the patterns are built once and used twice.
+ */
+export declare function likeSubstringLeg(db: Db, column: string, terms: readonly string[], buildSql: (fragments: LikeSubstringFragments) => string, filterParams?: readonly unknown[], limit?: number): {
+    id: number;
+    rank: number;
+}[];
+/** The per-aggregate SQL pieces of {@link entityBags}. */
+export interface EntityBagsQuery {
+    /** `FROM …` with its alias: `fact_entities fe` / `chunk_entities`. */
+    table: string;
+    /** The id expression, also the `WHERE … IN (…)` subject: `fe.fact_id` / `chunk_id`. */
+    keyColumn: string;
+    /** The name expression: `e.name` / `name`. */
+    nameColumn: string;
+    /** The `JOIN` that reaches the name vocabulary, for aggregates that have one (`''`/omitted for `chunk_entities`). */
+    joinEntities?: string;
+    /**
+     * The DEFAULT semantics — the one real difference between the two callers, so it is explicit:
+     *
+     *  - `true` (memory): every requested id is pre-seeded with `[]` in the REQUEST's order, so the
+     *    caller can assume `bags.get(id)` exists. Names are appended in row order after that;
+     *  - `false` (knowledge): only rows that actually carry entities appear (the caller uses `?? []`).
+     */
+    seedEmpty: boolean;
+}
+/**
+ * Batched entity-name bags for a row-id set: `Map<rowId, names>`.
+ *
+ * Shared by `EntitiesDao.bagsForFacts` and `ChunksDao.entityBags` (§4.6.3): one `IN (…)` statement
+ * per `batches()` slice, rows folded into the map in first-seen order. The SQL SHAPE is the only
+ * aggregate-specific part (`table` / `keyColumn` / `nameColumn` / `joinEntities`); the crucial
+ * `seedEmpty` difference above is the caller's to declare and stays observable.
+ */
+export declare function entityBags(db: Db, ids: readonly number[], q: EntityBagsQuery): Map<number, string[]>;

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

@@ -13,7 +13,7 @@
  * `ToolSpec.key` is typed `string` (not a literal union), so exhaustiveness cannot be checked at
  * compile time — the spec assertion is the gate.
  */
-import type { KbAddRequest } from '../mem-contract/index.js';
+import type { KbAddRequest, ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
 import type { AvantfRuntime } from './runtime.js';
 /**
  * The default page for a model-facing `kb_list`.
@@ -49,3 +49,21 @@ export declare function supportsToolKey(key: string): boolean;
  * both adapters route the throw through their structured error envelope.
  */
 export declare function dispatchToolKey(rt: AvantfRuntime, key: string, args: Record<string, unknown>): Promise<unknown>;
+/**
+ * The ONE model-facing boundary: validate against the contract spec, dispatch the key, and shape the
+ * result into the agent envelope.
+ *
+ * Every model-facing surface shares this — the DSH tool runner (`@avantf/dsh-mem`) and the MCP
+ * server — because the envelope is `ToolEnvelope`, a wire shape: an MCP caller and a DSH caller
+ * asking the same question must get the same fields. It used to live only in the plugin, so the MCP
+ * surface re-implemented it and the two could drift field by field.
+ *
+ * What stays in the CALLERS is everything AROUND the envelope: MCP's `textResult`/`isError` wrapper
+ * and the plugin's `present` view plus its Remote gateway. The Remote gateway is deliberately NOT
+ * routed through here (`mem/DESIGN.md` §239: it keeps `mem_admin`'s retention diagnostics and uses
+ * the wire error type, not `toolErr`).
+ *
+ * A validation failure answers `validationError` (named for the spec), an unknown key answers
+ * `toolErr`, and a throwing runtime call answers `toolErr` too — a raw exception never escapes.
+ */
+export declare function runToolSpec(rt: AvantfRuntime, spec: ToolSpec, args: unknown): Promise<ToolEnvelope<unknown>>;

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

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

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

@@ -17,9 +17,11 @@ export * from './config/paths.js';
 export * from './config/loader.js';
 export * from './modelBootstrap.js';
 export * from './dispatch.js';
+export * from './trustHeartbeat.js';
 export * from './runtime.js';
 export * from './store/memory.js';
 export * from './store/knowledge.js';
+export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
 export * from './store/source_picker.js';
 export * from './store/lexical.js';

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

@@ -1,4 +1,4 @@
-import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest } from '../mem-contract/index.js';
+import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest, VectorsFixReport } from '../mem-contract/index.js';
 import { type AvantfLogger, type StatsSummary } from '../mem-contract/index.js';
 import { type SemanticBackend } from '../mem-retrieval/index.js';
 import { type LoadedConfig } from './config/loader.js';
@@ -153,7 +153,7 @@ export type AdminDispatch = {
     }>): StoreResult<MemoryStore, 'vectorsDiagnose'>;
     (req: Extract<AdminRequest, {
         action: 'vectors_fix';
-    }>): StoreResult<MemoryStore, 'vectorsFix'>;
+    }>): Promise<VectorsFixReport>;
     (req: Extract<AdminRequest, {
         action: 'contradict_check';
     }>): StoreResult<MemoryStore, 'checkContradictions'>;

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

@@ -0,0 +1,121 @@
+/**
+ * The ONE entity-version sweep both stores run.
+ *
+ * `entities_version` is the stamp that says "these entity rows were produced by the CURRENT
+ * extraction rules". A rule change makes every row carrying an older stamp stale, and the only way
+ * to close that gap is to re-extract those rows' text — for memory the entity links, the triples and
+ * the HRR bundle derived from them; for knowledge the `chunk_entities` rows. That SKELETON was
+ * written twice and drifted apart in exactly the ways a copy drifts: memory had the in-flight guard,
+ * the budget clamp and the `{rebuilt, deferred, skipped}` report, while knowledge had the same
+ * selection inlined in `reindex` with no guard at all. This module is the one copy; the stores
+ * contribute a per-aggregate adapter (which rows, how to extract, what to write) and nothing else.
+ *
+ * Layering, deliberate: this is an ORCHESTRATION rule, not SQL, so it lives beside `common.ts` and
+ * `legs.ts` in `store/` — the DAO layer stays split by aggregate and keeps its own statements
+ * (`docs/vector-repair-shared-flow.md` §2 / §7).
+ *
+ * What must NOT move here: the extractor, the rows a store writes, and that store's side effects.
+ * Memory's transaction also replaces triples, moves the HRR bundle and re-queues the conflict check
+ * (both conflict legs read what the sweep rebuilt); knowledge replaces `chunk_entities` under
+ * `MAX_ENTITIES_PER_CHUNK`. Those are domain semantics, and folding them in would trade one
+ * duplicated loop for two conditional branches.
+ *
+ * @module store/entity_sweep
+ */
+/**
+ * What one bounded sweep pass did.
+ *
+ * `rebuilt` counts rows this pass re-extracted AND wrote — its batch size when it filled it. The
+ * stamp is what makes a corpus current, so a row re-extracted to the same names still counts (and is
+ * not selected again); a row whose write FAILED does not, because its old stamp survives. It is
+ * deliberately not "rows whose extraction output changed", which no caller could use: they drain a
+ * stale corpus by looping until `deferred === 0`.
+ */
+export interface EntitySweepReport {
+    /** Rows this pass re-extracted and wrote (its batch size, when it filled it and nothing failed). */
+    rebuilt: number;
+    /** Rows still carrying an older stamp after this pass. */
+    deferred: number;
+    /** Another pass was already running, so this one did nothing (`deferred` is still current). */
+    skipped: boolean;
+}
+/**
+ * Rows one sweep pass may rebuild when the caller names no budget.
+ *
+ * `MemoryStore.reindexEntities` has always defaulted to this, and the CLI passes it explicitly; it
+ * lives here so the shared loop and that public re-export cannot drift. Bounds MEMORY, not only
+ * mission: a pass selects every chosen row's text before rebuilding the first one.
+ */
+export declare const ENTITY_SWEEP_BATCH = 2000;
+/**
+ * A row the sweep may rebuild, as far as the SHARED loop is concerned.
+ *
+ * Deliberately unconstrained: the loop only routes a row from the selection to the adapter's own
+ * `extractAndWriteEntities`, so it must not name any column. Memory's row carries
+ * `{ fact_id, content }`, knowledge's `{ chunk_id, text }` — parameterizing the loop over the
+ * store's row type is what keeps those names out of the orchestration layer.
+ */
+export type EntitySweepRow = object;
+/**
+ * Per-store primitives. One adapter per aggregate, deliberately narrow.
+ *
+ * `staleEntityBatch` returns BOTH the scope's full stale count and a bounded slice in one read: the
+ * loop needs the remaining count for its report and the rows for its mission, and two queries would
+ * scan the same table twice. The two numbers must describe the same population: `total` counts every
+ * row the store's scope considers stale (memory: every ACTIVE fact; knowledge: every chunk of the
+ * sweep's domain scope), and `rows` is that population ordered by id, truncated to `limit`.
+ */
+export interface EntitySweepTarget<T extends EntitySweepRow> {
+    /**
+     * The scope's full stale count plus at most `limit` of those rows, ordered by id.
+     *
+     * `limit` is `maxPerPass`; the loop calls this once per pass. Both numbers must describe the SAME
+     * population — `total` is every stale row of the store's scope (memory: every ACTIVE fact;
+     * knowledge: every chunk of the sweep's domain), `rows` is that population truncated.
+     */
+    staleEntityBatch(limit: number): {
+        total: number;
+        rows: readonly T[];
+    };
+    /**
+     * Optional count-only read of the SAME population as {@link staleEntityBatch}'s `total`.
+     *
+     * It exists for the guard branch, which needs the current deferred count and no rows; absent, that
+     * branch falls back to `staleEntityBatch(0).total`. The loop holds the guard for the whole pass and
+     * each store is single-threaded, so the count cannot move between the two calls it makes.
+     */
+    staleEntityCount?(): number;
+    /** Re-extract one row's text and write that store's derived rows. May throw; the loop isolates. */
+    extractAndWriteEntities(row: T): Promise<void>;
+    /**
+     * Log a row this pass could not rebuild. Required, not defaulted: only the store knows which
+     * column names the row in its own logs (`fact_id` / `chunk_id`), and a shared warning cannot.
+     */
+    onRowError(row: T, error: unknown): void;
+}
+/** Everything {@link sweepVersionedEntities} needs beyond the adapter. */
+export interface EntitySweepOptions {
+    /** Rows this pass may rebuild; defaults to {@link ENTITY_SWEEP_BATCH}, clamped at 0. */
+    budget?: number;
+    /** Return `true` to stop before the next row (plugin unloading, runtime closed). */
+    shouldStop?: () => boolean;
+}
+/**
+ * Re-extract the entity rows written by older extraction rules, ONE bounded pass.
+ *
+ * The contract, in order: take the guard (an overlapping pass reports `skipped` and does nothing);
+ * read the scope's stale count and at most `maxPerPass` rows; re-extract each row through the
+ * adapter, isolating failures; report `{ rebuilt, deferred, skipped }`.
+ *
+ * Not an unbounded drain, on purpose: this is reachable from a settings-page button and a periodic
+ * heartbeat, so it must not block on a whole stale corpus. Callers that want the corpus current loop
+ * until `deferred === 0` (the CLI does).
+ *
+ * A row whose extraction or write throws is skipped, not fatal: the transaction that stamps the
+ * version never ran, so the row is still stale and the NEXT pass retries it — the same retry contract
+ * the knowledge store used per chunk. Letting the throw escape would instead abandon the rest of the
+ * batch with no report of what was done.
+ *
+ * @param guard the store's stable in-flight identity (see {@link SWEEPING})
+ */
+export declare function sweepVersionedEntities<T extends EntitySweepRow>(target: EntitySweepTarget<T>, guard: object, opts?: EntitySweepOptions): Promise<EntitySweepReport>;

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

@@ -234,3 +234,53 @@ export declare function applyOutputBudget<H extends BudgetInput>(config: Config,
  * the slice would spend the budget on hits that are about to be dropped.
  */
 export declare function hybridSearch<H extends BudgetInput>(deps: HybridDeps<H>, plan: HybridPlan): Promise<HybridResult<H>>;
+/**
+ * The search-entry fields `MemoryStore.search` and `KnowledgeStore.search` hand to the orchestrator.
+ * Both stores' option types (`SearchInput` / `KnowledgeSearchOptions`) satisfy this structurally;
+ * everything else on them (`category` / `source` / `domain` / `includeHrr` / `track` / `onResult`) is
+ * leg- or domain-specific and stays at the store.
+ */
+export interface HybridSearchEntryFields {
+    limit?: number;
+    /**
+     * Knowledge only: overrides the config-derived pool size. Memory's `SearchInput` has no such field
+     * and leaves the plan key absent (see {@link runHybridSearch}).
+     */
+    overFetch?: number;
+    maxTokens?: number;
+    queryVector?: Float32Array;
+    recordStats?: boolean;
+    floors?: FloorProfile;
+    includeScores?: boolean;
+    relaxLegs?: readonly FloorLeg[];
+    rewriteQuery?: (query: string) => string | undefined;
+}
+/**
+ * Map a store's search arguments onto {@link HybridPlan} and run {@link hybridSearch}. ONE copy.
+ *
+ * Before this, `MemoryStore.search` and `KnowledgeStore.search` carried the mapping verbatim side by
+ * side: the same field list, the same conditional spreads, the same call. That list is part of the
+ * orchestrator's contract, so an option added to one entry point and not the other would silently
+ * make the two stores query differently — the same shape of drift this module already documents
+ * (`NaN` limit, `over_fetch_factor`, unrecorded capped legs).
+ *
+ * The conditional spreads are deliberate, not cosmetic: a caller that did not pass `overFetch` /
+ * `includeScores` / `relaxLegs` / `rewriteQuery` leaves the plan key ABSENT rather than
+ * present-with-`undefined`. The orchestrator reads all four through `??` / `=== true` today, so the
+ * two are indistinguishable now — but the plan is a contract, and widening it with keys the caller
+ * never set is how "absent means default" decays into "present-undefined means set to nothing".
+ */
+export declare function runHybridSearch<H extends BudgetInput>(deps: HybridDeps<H>, query: string, fields: HybridSearchEntryFields | undefined): Promise<HybridResult<H>>;
+/**
+ * The mapping itself, separated from the call so it can be pinned directly: the contract here is
+ * the SHAPE of the plan (which keys exist), which no behavioural assertion inside `hybridSearch`
+ * could observe once every optional field is read through `??` / `=== true`.
+ */
+export declare function hybridPlanOf(query: string, fields: HybridSearchEntryFields | undefined): HybridPlan;
+/**
+ * Build a store's {@link HybridDeps} — the ONE construction site for the contract fields both stores
+ * share (`kind` / `config` / `semantic` / `legs` / `texts` / `hits` / `onReturn`). The per-store half
+ * is `parts`; the stores used to spell the whole object out twice, so a new required `HybridDeps`
+ * field was a change to remember in two places.
+ */
+export declare function makeHybridDeps<H>(kind: 'memory' | 'knowledge', config: Config, semantic: SemanticBackend, parts: Pick<HybridDeps<H>, 'legs' | 'texts' | 'hits' | 'onReturn'>): HybridDeps<H>;