@avantf/dsh-mem 0.3.1 → 0.4.0

package/lib/engine/mem-retrieval/adapters/hnswlib.d.ts

@@ -0,0 +1,174 @@
+import type { VectorStore } from '../interfaces.js';
+/**
+ * Search-time beam width, when the config does not say otherwise.
+ *
+ * hnswlib defaults `ef` to the value passed to `initIndex` (10 here), and that default is a
+ * QUALITY CLIFF rather than a neutral choice. Measured through this adapter (2000 random unit
+ * vectors, dim 512, true top-10 as ground truth):
+ *
+ *     ef   10     64     128    256    400
+ *     R@10 0.45   0.78   0.93   1.00   1.00
+ *     ms   0.10   0.36   0.53   0.74   0.90
+ *
+ * Recall falls as the corpus grows (at n=8000, R@50 was 0.89 even at `ef = 400`), and random
+ * vectors are the WORST case — real embeddings cluster, so production recall is higher than
+ * these numbers. 256 keeps the small/medium corpora exact without giving up the speedup; the
+ * knob is `vectorStore.hnswlib_ef_search`.
+ */
+export declare const DEFAULT_EF_SEARCH = 256;
+/**
+ * `hnswlib` — real ANN backend via `hnswlib-node` (cosine space, HierarchicalNSW).
+ * Uses the stable v2 string-space + initIndex + Array API. Wraps every native call
+ * in a try/catch and falls back to the in-memory brute-force store so the plugin
+ * never crashes on a pathological native binding — and a fallback that is TAKEN is
+ * always logged, because "never crashes" must not become "silently returns nothing".
+ */
+export declare class HnswlibVectorStore implements VectorStore {
+    readonly name = "hnswlib";
+    readonly dim: number;
+    private lib;
+    private fallback;
+    private readonly vectors;
+    /**
+     * The beam width in effect, and the index it was applied to: `ef` is in force on `efOn`.
+     *
+     * The index is part of the key, not just the number. `reindex()` and `rebuild()` REPLACE the
+     * native index, and a replacement starts at hnswlib's own default `ef` (10), so a bare number
+     * would compare equal and skip the re-apply — silently dropping ANN recall to ~0.44 of the
+     * true top-k after any batch eviction, which is the cliff this whole knob exists to avoid.
+     */
+    private efOn;
+    private ef;
+    private readonly efSearch;
+    /**
+     * Elements in the native graph, INCLUDING the ones `markDelete` has tombstoned.
+     *
+     * The live set is `vectors` (authoritative for `count`/`fetch`), so the number of dead points is
+     * `graphElements - vectors.size` — a derived quantity rather than a set of ids, because the graph
+     * OUTLIVES the process: a snapshot restored from disk already contains every dead point earlier
+     * sessions created, and a per-session `Set` could not see them (measured across 4 sessions of
+     * 100 evictions: live 1200→800 while the graph stayed at 1200, with the counter reading 100).
+     *
+     * Bookkeeping: a snapshot restore reads `getIdsList().length`; a build from rows sets it to the
+     * row count; `add` increments it only when the id was NOT already in the graph (an update in
+     * place, which also un-deletes a tombstone, does not grow the graph).
+     */
+    private graphElements;
+    /** Snapshot path PREFIX (set by the owning store via {@link attachPersistence}); see `snapshotPath`. */
+    private cachePath;
+    /** Something changed since the snapshot was written. */
+    private dirty;
+    private restores;
+    private rebuilds;
+    constructor(dim: number, efSearch?: number);
+    add(id: number, vec: Float32Array): void;
+    /** Whether the real hnswlib native index is active (false = brute-force fallback). */
+    get native(): boolean;
+    /**
+     * Counters a caller (test, benchmark, diagnostics) can assert on without guessing from timing:
+     * `restores` = snapshots loaded, `rebuilds` = full native builds, `tombstones` = pending deletes.
+     */
+    stats(): {
+        live: number;
+        tombstones: number;
+        graphElements: number;
+        restores: number;
+        rebuilds: number;
+        native: boolean;
+    };
+    /** Point the native index at an on-disk snapshot (see {@link VectorStore.attachPersistence}). */
+    attachPersistence(path: string): void;
+    /**
+     * The snapshot file for a row set: `prefix.<fingerprint>.hnsw`.
+     *
+     * Putting the fingerprint in the NAME is what makes the commit atomic. The previous shape wrote
+     * two files (index, then a JSON sidecar with the fingerprint) and validated the sidecar against
+     * the CURRENT rows — so an interleaved pair `(index_B, meta_A)` could describe two different
+     * corpora and still pass the check (the metadata was never bound to the graph it accompanied).
+     * With one file there is nothing to desynchronize: a snapshot either exists under the name of the
+     * row set it was built from, or it does not exist at all.
+     */
+    private snapshotPath;
+    /**
+     * Widen the search beam, skipping the native call only when this exact width is already in
+     * force on THIS index (see {@link efOn}).
+     */
+    private setEf;
+    private rebuildFallback;
+    topk(vec: Float32Array, k: number): {
+        id: number;
+        score: number;
+    }[];
+    fetch(ids: number[]): Map<number, Float32Array>;
+    remove(id: number): void;
+    /**
+     * Batch removal via TOMBSTONES — O(k), not O(N).
+     *
+     * `markDelete` excludes a label from `searchKnn` without touching the graph (measured: 1000
+     * tombstones = 0.19 ms on an 8000-vector index, against 1.3 s for the rebuild this used to
+     * do). Deleted points are still traversed and still occupy space, so {@link maybeCompact}
+     * rebuilds once tombstones become a meaningful fraction of the corpus.
+     */
+    removeMany(ids: number[]): void;
+    /**
+     * Rebuild once the dead points are worth a full pass (see {@link COMPACT_RATIO}).
+     *
+     * The count is DERIVED from the graph, so it includes what earlier sessions left behind: that is
+     * what makes accumulation across CLI invocations self-correcting instead of monotonic.
+     */
+    private maybeCompact;
+    /**
+     * Recreate the serving index (native when possible) from the tracked vectors.
+     *
+     * Public because it is the "compact now" operation: it drops every tombstone and leaves a
+     * clean graph. Called by `maybeCompact()` and by `rebuild()`'s failure paths.
+     */
+    compact(): void;
+    /** Recreate the serving index (native when possible) from the tracked vectors. */
+    private reindex;
+    count(): number;
+    /**
+     * Build from the store's rows, reusing the on-disk snapshot when it provably describes them.
+     *
+     * The snapshot check is a FINGERPRINT over the live ids plus the count, not just a count: a
+     * session that evicted three facts and added three others has the same count with different
+     * contents, and loading that would silently serve vectors that no longer exist. The path
+     * carries the vector space (see `attachPersistence`), so a model/dim swap cannot load at all.
+     */
+    rebuild(rows: Iterable<{
+        id: number;
+        vec: Float32Array;
+    }>): void;
+    /** Persist pending state (called on shutdown); a no-op without a cache path or change. */
+    flush(): void;
+    /**
+     * Load the snapshot that describes EXACTLY these rows, if it exists.
+     *
+     * There is no validity check to get wrong: the file is named by the fingerprint of the row set
+     * it was built from, so a snapshot for a different corpus is a different file (and simply will
+     * not be found). That is the whole reason the fingerprint moved into the name.
+     *
+     * `allowReplaceDeleted` is deliberately FALSE: with it enabled, `addPoint` on a label that the
+     * snapshot recorded as deleted throws ("Can't use addPoint to update deleted elements if
+     * replacement of deleted elements is enabled"), which would break the very first re-add of an
+     * archived-then-restored fact. Verified against the binding; deleted entries stay excluded from
+     * `searchKnn` either way.
+     */
+    private restore;
+    /** Live rows, as `fingerprintOf` wants them. */
+    private liveRows;
+    /**
+     * Write the native graph, atomically: a temp file plus `rename`, so a reader (the other
+     * process sharing this data home) sees either the old snapshot or the complete new one.
+     * Best-effort by design — a failing cache must never fail a write that already hit the DB.
+     */
+    private persist;
+    /**
+     * Delete snapshots for OTHER row sets of this store (best-effort).
+     *
+     * They can never be loaded again — the name IS the fingerprint — so keeping them only leaks disk.
+     * A concurrent process may have just written one; unlinking an open file is safe on POSIX, and
+     * the worst case is that the other process rebuilds next start.
+     */
+    private dropStaleSnapshots;
+}

package/lib/engine/mem-retrieval/adapters/local_bge.d.ts

@@ -0,0 +1,121 @@
+import type { SemanticBackend } from '../interfaces.js';
+/**
+ * The injected pipeline surface: one text OR an array of texts in, a tensor out.
+ *
+ * The array form matters: transformers.js runs a batch through the model in one call (its own
+ * per-call overhead — session dispatch, tokenizer batching — is amortized), while a serial loop of
+ * single-text calls pays it per chunk. `dims` is the tensor shape (`[n, dim]`); the single-text
+ * form may omit it.
+ */
+export type PipelineFn = (text: string | string[], opts?: Record<string, unknown>) => Promise<{
+    data: Float32Array | number[];
+    dims?: number[];
+}>;
+/** The slice of the transformers.js module this project reads and configures. */
+export type TransformersModule = {
+    env?: Record<string, unknown>;
+    pipeline?: (task: string, model: string) => Promise<unknown>;
+};
+/** Injectable seam: tests supply a fake pipeline instead of the transformers.js import. */
+export type PipeFactory = (model: string, env: ModelEnv) => Promise<PipelineFn>;
+export interface ModelEnv {
+    /** Mirror host for model downloads (default domestic). */
+    mirror: string;
+    /** Local cache dir for downloaded weights. */
+    cacheDir: string;
+    /** Whether to auto-download on warmup. */
+    autoDownload: boolean;
+    /**
+     * Upper bound on tokens handed to the model; `0`/unset = auto (the loaded model's declared
+     * window). Past the window transformers.js truncates SILENTLY, so the adapter bounds the
+     * text first and logs it once (`text_budget.ts`).
+     */
+    maxInputTokens?: number;
+    /**
+     * Do NOT warm in the constructor: the first `encode()` / `encodeBatch()` warms lazily.
+     *
+     * Set when something ELSE owns the model root and will put the files there asynchronously — the
+     * DSH plugin does, because the family framework fetches the model as a background item. Warming
+     * in the constructor would race that install and let this process fetch its own copy; the caller
+     * warms explicitly once the item settles. Unset (the CLI / MCP / every direct construction) keeps
+     * the eager constructor warm.
+     */
+    deferWarm?: boolean;
+}
+/**
+ * Local BGE embedder via `@huggingface/transformers` (transformers.js, ONNX).
+ * Lazily imports the package; `warmUp()` (async, idempotent) sets the mirror +
+ * cache dir, then triggers a model load/download. Until warmup completes,
+ * `isAvailable()` is false and the retrieval pipeline stays degraded.
+ *
+ * A warmup that fails is not final: `ensureWarm()` lets observing call sites
+ * retry it cheaply (see `warm_gate.ts`), so a transient mirror outage does not
+ * degrade a long-lived host until the next restart.
+ */
+export declare class LocalBgeBackend implements SemanticBackend {
+    readonly name = "local_bge";
+    readonly dim: number;
+    private _available;
+    private _pipe;
+    private _warming;
+    private _dimWarned;
+    private _lengthWarned;
+    private _window;
+    private readonly configuredMax;
+    private readonly model;
+    private readonly env;
+    private readonly pipeFactory;
+    private readonly gate;
+    constructor(model: string, dim: number, env?: Partial<ModelEnv>, pipeFactory?: PipeFactory);
+    isAvailable(): boolean;
+    /**
+     * Fire-and-forget retry for call sites that only observe availability. No-op
+     * while the model is ready or an attempt is already in flight; otherwise
+     * throttled by {@link WarmGate}.
+     */
+    ensureWarm(): void;
+    /** Idempotent warmup: configure transformers.js env and load/download the model. */
+    warmUp(): Promise<void>;
+    private _doWarmup;
+    /** Tell the operator whether the failure is recoverable in-process. */
+    private retryHint;
+    /**
+     * The model's usable input window, resolved once per process: an explicit
+     * `semantic.max_input_tokens` cap clamped to the loaded tokenizer's declared
+     * `model_max_length`, or the declared window itself when the config says "auto" (0).
+     */
+    private window;
+    /**
+     * Bound `text` to the window BEFORE it reaches transformers.js.
+     *
+     * This is the only place the guard can live: the feature-extraction pipeline's `_call`
+     * accepts `{pooling, normalize, quantize, precision}` and nothing else, so `max_length`
+     * cannot be raised or lowered from the call site — past `model_max_length` the tokenizer
+     * truncates and says nothing.
+     */
+    private bound;
+    encode(text: string): Promise<Float32Array>;
+    /**
+     * Encode several texts in ONE model call.
+     *
+     * This used to be a serial loop over `encode()`, and production code never called it — so
+     * ingest paid the per-call overhead once per chunk (measured: the dominant cost of `kb ingest`,
+     * 33.7 ms/chunk at 450 characters). Every text is bounded individually first (the window
+     * belongs to the model, not to the batch), and a failed batch falls back to per-text calls so
+     * an injected single-string pipeline (tests) and a memory-bound real batch both keep working.
+     */
+    encodeBatch(texts: string[]): Promise<Float32Array[]>;
+    /** One model call for a length-homogeneous group; falls back to per-text calls on failure. */
+    private encodeGroup;
+}
+/**
+ * Apply this project's cache/mirror policy to transformers.js.
+ *
+ * `mod.env` is PROCESS-GLOBAL and last-writer-wins: the embedder and the reranker are two adapters
+ * over ONE module, so whichever warms second decides what both see. Setting the keys from a single
+ * place is what keeps the two from disagreeing — the reranker used to set `allowLocalModels` on its
+ * own, which reads as a policy difference between the adapters and was really an accident of which
+ * file got edited last. `allowLocalModels` is already the library default; it is stated here so the
+ * policy is explicit rather than inherited, and identical for both adapters.
+ */
+export declare function applyModelEnv(mod: TransformersModule, env: ModelEnv): void;

package/lib/engine/mem-retrieval/adapters/local_numpy.d.ts

@@ -0,0 +1,28 @@
+import type { VectorStore } from '../interfaces.js';
+/**
+ * `local_numpy` — in-memory brute-force vector store.
+ * Default / dev backend; persists via the caller (the store DB owns the vectors).
+ * The fallback every backend without a real adapter resolves to; `hnswlib` is the implemented ANN
+ * store, while `faiss`/`pgvector`/`qdrant` warn and land here.
+ */
+export declare class LocalNumpyVectorStore implements VectorStore {
+    readonly name = "local_numpy";
+    readonly dim: number;
+    private readonly vectors;
+    constructor(dim: number);
+    add(id: number, vec: Float32Array): void;
+    topk(vec: Float32Array, k: number): {
+        id: number;
+        score: number;
+    }[];
+    fetch(ids: number[]): Map<number, Float32Array>;
+    remove(id: number): void;
+    removeMany(ids: number[]): void;
+    count(): number;
+    /** Iterate all stored (id, vector) pairs — used by `auto` to migrate to an ANN backend. */
+    entries(): IterableIterator<[number, Float32Array]>;
+    rebuild(rows: Iterable<{
+        id: number;
+        vec: Float32Array;
+    }>): void;
+}

package/lib/engine/mem-retrieval/adapters/local_reranker.d.ts

@@ -0,0 +1,52 @@
+import type { Reranker } from '../interfaces.js';
+import { type ModelEnv } from './local_bge.js';
+/** One text-classification result: transformers.js yields `{label, score}`; tolerate a raw `{data}` tensor too. */
+type ClassifyResult = {
+    label?: string;
+    score?: number;
+    data?: number[];
+};
+/** The injected pipeline surface: a batch of (query, document) pairs in, scores out. */
+export type ClassifyFn = (inputs: [string, string][], opts?: Record<string, unknown>) => Promise<ClassifyResult[]>;
+/** Injectable seam: tests supply a fake classifier instead of the transformers.js import. */
+export type RerankerPipeFactory = (model: string, env: ModelEnv) => Promise<ClassifyFn>;
+/** Never hand the classifier a degenerate document; below this the score is meaningless. */
+export declare const MIN_DOC_TOKENS = 16;
+/**
+ * Local cross-encoder reranker via `@huggingface/transformers` (`bge-reranker`).
+ * Lazily imported; `warmUp()` configures the mirror/cache and triggers a load.
+ * Degrades to identity order when the package/model is not available.
+ *
+ * Like {@link LocalBgeBackend}, a failed warmup is retryable through
+ * `ensureWarm()` rather than being final until the next restart.
+ */
+export declare class LocalReranker implements Reranker {
+    readonly name = "bge_reranker";
+    private _available;
+    private _pipe;
+    private _warming;
+    private _lengthWarned;
+    private _window;
+    private readonly configuredMax;
+    private readonly model;
+    private readonly env;
+    private readonly pipeFactory;
+    private readonly gate;
+    constructor(model: string, env?: Partial<ModelEnv>, pipeFactory?: RerankerPipeFactory);
+    isAvailable(): boolean;
+    /** Fire-and-forget retry for call sites that only observe availability (see `warm_gate.ts`). */
+    ensureWarm(): void;
+    warmUp(): Promise<void>;
+    private _doWarmup;
+    private window;
+    /**
+     * Bound one document for a pair, given how much of the window the query already spends.
+     * Returns the document text unchanged when it fits.
+     */
+    private boundDocument;
+    rerank(query: string, candidates: {
+        id: number;
+        text: string;
+    }[]): Promise<number[]>;
+}
+export {};

package/lib/engine/mem-retrieval/adapters/none_reranker.d.ts

@@ -0,0 +1,10 @@
+import type { Reranker } from '../interfaces.js';
+/** `none` — reranking disabled (the default). Reports unavailable so callers skip the rerank pass entirely. */
+export declare class NoneReranker implements Reranker {
+    readonly name = "none";
+    isAvailable(): boolean;
+    rerank(_query: string, candidates: {
+        id: number;
+        text: string;
+    }[]): Promise<number[]>;
+}

package/lib/engine/mem-retrieval/adapters/warm_gate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Retry gate for the local model adapters.
+ *
+ * The model bootstrap runs exactly once, at startup (the model artifact in
+ * `provisionToolchainAsync`). When that single attempt fails — an unreachable
+ * mirror, a poisoned DNS entry, a
+ * proxy that is not up yet — nothing used to try again, so a long-lived host
+ * stayed on the FTS+entity fallback forever, even after the network recovered
+ * or the weights landed in the cache (`vectors_fix` kept reporting
+ * `semantic_available: false` on a running plugin host).
+ *
+ * Call sites that only *observe* availability (hybrid search, best-effort
+ * indexing) now ask for a retry through {@link WarmGate.nudge}. The gate is
+ * deliberately timer-free: there is no background poll, no handle to dispose,
+ * and no traffic while nothing is asking for semantic retrieval — recovery
+ * happens on the next retrieval that needs it.
+ */
+/**
+ * Minimum gap between two retry attempts triggered by observing call sites.
+ * Comfortably above undici's 10 s connect timeout so a dead mirror is not
+ * re-probed on every query, and short enough that a recovered network is picked
+ * up without a restart.
+ */
+export declare const ENSURE_WARM_FLOOR_MS = 30000;
+/** Throttles observing-call-site retries of a failed model warmup. */
+export declare class WarmGate {
+    private readonly canAttempt;
+    private lastAttemptAt;
+    /**
+     * @param canAttempt whether a retry can still help. `false` makes the gate
+     *   inert: with downloads disabled a miss is deterministic (only a local cache
+     *   load is possible), so retrying would only add noise.
+     */
+    constructor(canAttempt: () => boolean);
+    /**
+     * Record that an attempt actually started. Called by the adapter's warmup so
+     * the startup attempt also resets the floor — otherwise the first query after
+     * a failed boot would immediately re-attempt.
+     */
+    markAttempt(now?: number): void;
+    /**
+     * Run `attempt` unless the floor has not elapsed. Non-blocking: the caller
+     * passes a fire-and-forget trigger. Returns whether an attempt was started.
+     */
+    nudge(attempt: () => void, now?: number): boolean;
+}

package/lib/engine/mem-retrieval/budget.d.ts

@@ -0,0 +1,30 @@
+/** What the budget needs from a candidate: ranked text. */
+export interface BudgetInput {
+    text: string;
+    score: number;
+}
+export interface BudgetOptions {
+    /** Total tokens to spend; `0` (or negative) means "no budget" and returns the input untouched. */
+    maxTokens: number;
+    /** Ceiling for one entry; defaults to twice the average share. */
+    perEntryCap?: number;
+    /** Token estimator override (tests, or a real tokenizer). */
+    estimate?: (text: string) => number;
+}
+export interface Budgeted<T> {
+    kept: T[];
+    used_tokens: number;
+    /** Entries whose text was shortened (including those left with no text at all). */
+    truncated: number;
+}
+/**
+ * Fit `items` into `maxTokens`, preserving their (ranked) order.
+ *
+ * Pass 1 gives every entry `min(perEntryCap, remaining)`. Pass 2 spends what is left growing the
+ * entries that were cut, best first. An entry that receives no budget keeps an empty `text` and
+ * `truncated: true` — dropping it would hide its existence, which is worse than showing a
+ * reference to it.
+ */
+export declare function fitToTokenBudget<T extends BudgetInput>(items: readonly T[], opts: BudgetOptions): Budgeted<T & {
+    truncated?: boolean;
+}>;

package/lib/engine/mem-retrieval/fusion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Hybrid fusion: each path's raw scores are scaled by that path's OWN maximum, then summed with
+ * the configured weights and cut to the top-k.
+ *
+ * Scaling by the max (rather than min-max over the path's returned set) is what makes the result
+ * INVARIANT to a capped path — FOR A PATH THAT HANDS ITS ENTRIES OVER IN ITS OWN SCORE ORDER.
+ * The store bounds every non-semantic leg (`memory.ts` `legCap`) for cost, and a cap then removes
+ * that leg's weakest entries, which is exactly the minimum a min-max normalization would have
+ * measured against: trimming used to rescale every survivor and could reorder them (a documented,
+ * previously-accepted effect). With `v/max` the number is the same with or without the cap,
+ * because the maximum belongs to an entry a cap cannot remove.
+ *
+ * That "cannot remove" is the assumption, and the store has ONE leg that breaks it: the HRR probe.
+ * Its candidates arrive in another leg's order — the entity-Jaccard ratio (`candidateFactsForAnyEntity`,
+ * which is the JACCARD leg's score, not the phase similarity this leg scores by), or recency in the
+ * no-candidate fallback (see `MemoryStore.hrrPath`). Either way the cap may drop this leg's highest
+ * scorer and the scaling does move. Stated rather than implied, because the invariance is the whole
+ * reason this normalization was chosen; `docs/PROVENANCE_REVIEW.md` N5 records the missing
+ * differential, and `recordLegCapped()` is what makes the cap observable at all.
+ *
+ * Magnitudes are kept: a path whose scores cluster high still contributes more per entry than one
+ * whose scores are near zero, which is the information ranks alone would throw away.
+ */
+export interface FusionPath {
+    weight: number;
+    /** candidate id → raw score (un-normalized). */
+    scores: Map<number, number>;
+}
+export interface Hit {
+    id: number;
+    score: number;
+}
+/**
+ * Scale raw scores by the set's maximum, into [0,1].
+ *
+ * A set whose maximum is not positive carries no ranking information, so every entry maps to 0 —
+ * it still participates in the pool (with no contribution) instead of being dropped, which is what
+ * keeps a degenerate path from emptying the result.
+ *
+ * A NON-FINITE score is treated the same way (mapped to 0, kept in the pool). It cannot come from a
+ * healthy leg, but a corrupt HRR blob decodes to NaN without a length check failing, and one NaN
+ * would otherwise do two kinds of damage: poison that candidate's merged total, and make `fuse`'s
+ * sort comparator return NaN — an undefined order, so the whole ranking (not just one entry)
+ * becomes arbitrary.
+ */
+export declare function scaleByMax(scores: Map<number, number>): Map<number, number>;
+/**
+ * Fuse paths by scaling each path's scores by its own maximum, summing weighted values, and
+ * returning the top-k descending. Ties break on ascending id so the ranking is deterministic —
+ * scaled scores collide far more often than min-max ones did (both legs of a pair can rank two
+ * candidates identically), and the previous order was Map-insertion order.
+ */
+export declare function fuse(paths: FusionPath[], topK: number): Hit[];

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

@@ -0,0 +1,14 @@
+export * from './interfaces.js';
+export * from './log.js';
+export * from './stats.js';
+export * from './text_budget.js';
+export * from './budget.js';
+export * from './registry.js';
+export * from './fusion.js';
+export * from './rerank.js';
+export * from './adapters/local_numpy.js';
+export * from './adapters/hnswlib.js';
+export * from './adapters/auto_vstore.js';
+export * from './adapters/none_reranker.js';
+export * from './adapters/local_bge.js';
+export * from './adapters/local_reranker.js';

package/lib/engine/mem-retrieval/interfaces.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The three stable contracts the business flow depends on.
+ * The business flow (fusion pipeline, stores, tools, router, UI) must depend only on
+ * these interfaces — never on a concrete backend. See DESIGN §5.
+ */
+/** Encodes text into a normalized embedding vector. */
+export interface SemanticBackend {
+    readonly name: string;
+    readonly dim: number;
+    encode(text: string): Promise<Float32Array>;
+    encodeBatch(texts: string[]): Promise<Float32Array[]>;
+    isAvailable(): boolean;
+    /** Optional async bootstrap: configure env + download/load the model. */
+    warmUp?(): Promise<void>;
+    /**
+     * Optional non-blocking retry for call sites that only *observe* availability
+     * (hybrid search, best-effort indexing): re-attempts a failed bootstrap,
+     * coalescing with any in-flight attempt and throttling to one attempt per
+     * floor. Implementations that load lazily may omit it.
+     */
+    ensureWarm?(): void;
+}
+/** Re-ranks candidate facts/chunks by query relevance. */
+export interface Reranker {
+    readonly name: string;
+    rerank(query: string, candidates: {
+        id: number;
+        text: string;
+    }[]): Promise<number[]>;
+    isAvailable(): boolean;
+    /** Optional async bootstrap: configure env + download/load the model. */
+    warmUp?(): Promise<void>;
+    /** Optional non-blocking retry — see {@link SemanticBackend.ensureWarm}. */
+    ensureWarm?(): void;
+}
+/** Distance/ann index over entry vectors (per-store instance). */
+export interface VectorStore {
+    readonly name: string;
+    readonly dim: number;
+    add(id: number, vec: Float32Array): void;
+    /** Cosine-similarity top-k over all stored vectors (brute force by default). */
+    topk(vec: Float32Array, k: number): {
+        id: number;
+        score: number;
+    }[];
+    fetch(ids: number[]): Map<number, Float32Array>;
+    remove(id: number): void;
+    /**
+     * Optional batch removal. A backend that cannot delete incrementally MUST implement this so
+     * eviction loops stay O(N) instead of O(N²); callers prefer it whenever they evict more than one
+     * id. (hnswlib deletes by tombstone, so its `removeMany` is O(k) — it implements this to share
+     * the "compact once for the whole batch" path, not because a single delete would rebuild.)
+     */
+    removeMany?(ids: number[]): void;
+    /**
+     * Optional: drop any dead/tombstoned entries the backend is carrying, now. An explicit
+     * "reclaim it" hook for maintenance; implementations that cannot accumulate dead state omit it.
+     */
+    compact?(): void;
+    count(): number;
+    rebuild(rows: Iterable<{
+        id: number;
+        vec: Float32Array;
+    }>): void;
+    /**
+     * Optional: materialize any structure the backend built LAZILY. `topk` must always be correct
+     * without it (it builds on demand); this exists so callers that need deterministic first-query
+     * latency — benchmarks, and tests that assert on build cost — can force the mission.
+     */
+    prepare?(): void;
+    /**
+     * Optional: point the backend at an on-disk cache of its native index. The path is the
+     * STORE's choice and must embed the vector space (model/dim), so a model swap cannot load a
+     * snapshot built from another space. Best-effort: a missing/corrupt/stale file is rebuilt.
+     */
+    attachPersistence?(path: string): void;
+    /**
+     * Optional: persist any state that is only in memory. Called on shutdown; implementations that
+     * have nothing pending may omit it.
+     */
+    flush?(): void;
+}

package/lib/engine/mem-retrieval/log.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Process-wide logger seam for the retrieval core. The DSH plugin installs the
+ * host logger through {@link setRetrievalLogger}; standalone runs (CLI / MCP /
+ * tests) keep the prefixed console default. The core deliberately has no Cordis
+ * dependency, so a module seam is the only way to reach every adapter.
+ */
+import { type AvantfLogger } from '../mem-contract/index.js';
+/** Route retrieval-core logs (model warm / degrade) to a host logger. */
+export declare function setRetrievalLogger(logger?: AvantfLogger): void;
+/** The logger every adapter reports through. */
+export declare function retrievalLogger(): AvantfLogger;

package/lib/engine/mem-retrieval/registry.d.ts

@@ -0,0 +1,23 @@
+import type { Config } from '../mem-contract/index.js';
+import type { Reranker, SemanticBackend, VectorStore } from './interfaces.js';
+type Factory<T> = (cfg: Config, opts?: ResolveOptions) => T;
+/**
+ * How a backend is resolved.
+ *
+ * Only `deferWarm` exists, and only because the DSH plugin cannot let a backend warm itself: the
+ * family framework installs the model into the managed root ASYNCHRONOUSLY, so a constructor-time
+ * warm would race that install and fetch a second copy. The plugin passes `deferWarm: true` and
+ * warms from the model item's `onSettled`; every other caller (CLI, MCP, tests) keeps the eager
+ * constructor warm. `encode()` / `rerank()` still warm lazily, so deferring never loses the model.
+ */
+export interface ResolveOptions {
+    /** Skip the constructor warm; the caller warms explicitly (see `ModelEnv.deferWarm`). */
+    readonly deferWarm?: boolean;
+}
+export declare function registerSemanticBackend(name: string, factory: Factory<SemanticBackend>): void;
+export declare function registerReranker(name: string, factory: Factory<Reranker>): void;
+export declare function registerVectorStore(name: string, factory: Factory<VectorStore>): void;
+export declare function resolveSemantic(cfg: Config, opts?: ResolveOptions): SemanticBackend;
+export declare function resolveReranker(cfg: Config, opts?: ResolveOptions): Reranker;
+export declare function resolveVStore(cfg: Config): VectorStore;
+export {};