@avantf/dsh-mem 0.4.2 → 0.6.1

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

@@ -1,4 +1,4 @@
-import type { SemanticBackend } from '../interfaces.js';
+import type { SemanticBackend, SemanticRepresentation } from '../interfaces.js';
 /**
  * The injected pipeline surface: one text OR an array of texts in, a tensor out.
  *
@@ -31,6 +31,18 @@ export interface ModelEnv {
      * text first and logs it once (`text_budget.ts`).
      */
     maxInputTokens?: number;
+    /**
+     * Pooling strategy handed to the feature-extraction pipeline (`mean` by default). Part of the
+     * representation fingerprint (`representationKey`): `mean` and `cls` produce DIFFERENT
+     * coordinates from the same weights, so a change here is a data migration, not a tuning knob.
+     */
+    pooling?: string;
+    /**
+     * Whether the pipeline L2-normalizes (`true` by default). Also part of the representation:
+     * an un-normalized vector ranks differently under cosine, so switching it invalidates every
+     * persisted vector exactly like a model swap does.
+     */
+    normalize?: boolean;
     /**
      * Do NOT warm in the constructor: the first `encode()` / `encodeBatch()` warms lazily.
      *
@@ -61,13 +73,34 @@ export declare class LocalBgeBackend implements SemanticBackend {
     private _dimWarned;
     private _lengthWarned;
     private _window;
+    /** Cached so the fingerprint cannot move while the process runs (see {@link representation}). */
+    private _representation;
     private readonly configuredMax;
+    private readonly pooling;
+    private readonly normalize;
     private readonly model;
     private readonly env;
     private readonly pipeFactory;
     private readonly gate;
     constructor(model: string, dim: number, env?: Partial<ModelEnv>, pipeFactory?: PipeFactory);
     isAvailable(): boolean;
+    /**
+     * The representation knobs this adapter applies, resolved ONCE per instance.
+     *
+     * Resolved once on purpose: the model revision comes from disk, and a fingerprint that changed
+     * mid-process (install settles, sidecar appears) would make the store declare the rows it just
+     * wrote stale. The cost of reading it early is bounded and honest — a process that starts BEFORE
+     * the family provisioner lands the model writes a revision-less fingerprint for that session, and
+     * the next start re-encodes once into the revision-carrying one. The alternative (reading late)
+     * would re-encode on every restart instead.
+     *
+     * A missing sidecar is reported once, as a DEGRADATION: the fingerprint then cannot see a repo
+     * whose weights were re-pushed under the same name, which is a real (narrow) blind spot and must
+     * not be mistaken for a healthy state. It never throws, and it stays quiet while the weights are
+     * not on disk yet (a fresh install in flight has nothing to fingerprint; the sidecar arrives with
+     * the weights). The resolved representation is CACHED, so the warning is one line per process.
+     */
+    representation(): SemanticRepresentation;
     /**
      * 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
@@ -111,11 +144,8 @@ export declare class LocalBgeBackend implements SemanticBackend {
 /**
  * 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.
+ * `mod.env` is PROCESS-GLOBAL and last-writer-wins. Setting the keys from a single place is what
+ * keeps every future adapter over this module from disagreeing: `allowLocalModels` is already the
+ * library default, stated here so the policy is explicit rather than inherited.
  */
 export declare function applyModelEnv(mod: TransformersModule, env: ModelEnv): void;

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

@@ -29,6 +29,17 @@ export interface FusionPath {
 export interface Hit {
     id: number;
     score: number;
+    /**
+     * P-01 per-leg evidence, aligned to the `paths` array the caller passed, and only present when
+     * the caller asked for it (`opts.includeLegs`). `null` at an index means that leg did not
+     * recall this candidate — the explicit "no evidence", which a missing entry would hide.
+     */
+    legs?: (LegScore | null)[];
+}
+/** P-01: one leg's contribution to one candidate (raw on the leg's scale + the value fused). */
+export interface LegScore {
+    raw: number;
+    normalized: number;
 }
 /**
  * Scale raw scores by the set's maximum, into [0,1].
@@ -50,4 +61,6 @@ export declare function scaleByMax(scores: Map<number, number>): Map<number, num
  * 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[];
+export declare function fuse(paths: FusionPath[], topK: number, opts?: {
+    includeLegs?: boolean;
+}): Hit[];

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

@@ -1,14 +1,12 @@
 export * from './interfaces.js';
+export * from './representation.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

@@ -1,8 +1,38 @@
 /**
- * The three stable contracts the business flow depends on.
+ * The two 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.
  */
+/**
+ * HOW a backend turns text into a vector — the knobs that decide which coordinates a stored vector
+ * lives in, beyond `name`/`dim`.
+ *
+ * The vector-space identity used to record only `backend/model/dim`, so a change of pooling,
+ * normalization, input window or the weights behind the same repo name produced the SAME identity:
+ * new vectors were written into an index that still held the old ones and nothing detected the
+ * migration (see `db/vectors.ts` and DESIGN §20). A backend that can name these knobs declares them
+ * here and the space id carries them (see `representationKey`).
+ */
+export interface SemanticRepresentation {
+    /** Pooling strategy handed to the feature-extraction pipeline (`mean`, `cls`, …). */
+    readonly pooling: string;
+    /** Whether vectors are L2-normalized by the pipeline (cosine relies on it). */
+    readonly normalize: boolean;
+    /**
+     * The CONFIGURED input-token cap (`0` = auto/declared window), i.e. the truncation window the
+     * adapter bounds text to before encoding. The CONFIGURED value, not the resolved one: the
+     * resolved window depends on the loaded tokenizer, so it is unknown before warmup — and the
+     * fingerprint must be identical before and after warmup, or a store would declare its own rows
+     * stale the moment the model finished loading.
+     */
+    readonly maxInputTokens: number;
+    /**
+     * Content identity of the model files (the family sidecar's revision sha), when one could be
+     * read. Absent = "could not be read" (not "known to be empty"): the fingerprint then omits it,
+     * which is the documented degradation, never an error.
+     */
+    readonly revision?: string;
+}
 /** Encodes text into a normalized embedding vector. */
 export interface SemanticBackend {
     readonly name: string;
@@ -10,6 +40,13 @@ export interface SemanticBackend {
     encode(text: string): Promise<Float32Array>;
     encodeBatch(texts: string[]): Promise<Float32Array[]>;
     isAvailable(): boolean;
+    /**
+     * Optional declaration of the representation knobs this backend applies. The built-in
+     * `local_bge` declares them; a third-party backend that omits this is fingerprinted as
+     * `rep=undeclared` (the space id still changes with name/dim), which is honest rather than a
+     * silent claim to a representation nobody verified.
+     */
+    representation?(): SemanticRepresentation;
     /** Optional async bootstrap: configure env + download/load the model. */
     warmUp?(): Promise<void>;
     /**
@@ -20,19 +57,6 @@ export interface SemanticBackend {
      */
     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;

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

@@ -1,5 +1,5 @@
 import type { Config } from '../mem-contract/index.js';
-import type { Reranker, SemanticBackend, VectorStore } from './interfaces.js';
+import type { SemanticBackend, VectorStore } from './interfaces.js';
 type Factory<T> = (cfg: Config, opts?: ResolveOptions) => T;
 /**
  * How a backend is resolved.
@@ -8,16 +8,14 @@ type Factory<T> = (cfg: Config, opts?: ResolveOptions) => T;
  * 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.
+ * constructor warm. `encode()` still warms 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 {};

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

@@ -0,0 +1,50 @@
+import type { SemanticBackend, SemanticRepresentation } from './interfaces.js';
+/** The declared representation of a backend that does not implement `representation()`. */
+export declare const UNDECLARED_REPRESENTATION = "rep=undeclared";
+/** What {@link readModelRevision} found (or why it found nothing). */
+export interface ModelRevisionRead {
+    /** The model's content identity when the sidecar recorded one. */
+    readonly revision?: string;
+    /** Where it was looked for (the degradation warning names it). */
+    readonly path: string;
+    /** Why the revision is absent — short, for the one-line degradation warning. */
+    readonly detail: string;
+}
+/**
+ * Normalized, stable representation key embedded in a vector-space id.
+ *
+ * Field order is fixed and each value is normalized (lowercased pooling, 1/0 normalize, a
+ * truncated non-negative integer window), so two runs that describe the SAME representation always
+ * produce the SAME key — a fingerprint that changed spuriously would re-encode a whole corpus for
+ * nothing. A blank/absent revision is OMITTED rather than encoded as a placeholder: "unknown" then
+ * looks different from any known revision, which is the honest reading (the weights could have
+ * changed without this process being able to tell).
+ */
+export declare function representationKey(rep: SemanticRepresentation): string;
+/** {@link representationKey} for a live backend, or the explicit "undeclared" marker. */
+export declare function representationKeyOf(backend: SemanticBackend): string;
+/** The sidecar path for `model` under `cacheDir`, mirroring the base's flat-layout naming
+ * (`models--<owner>--<name>`), which is why a slash in the repo id becomes `--`.
+ */
+export declare function modelRecordPath(cacheDir: string, model: string): string;
+/**
+ * Whether the model's weights are actually on disk in the flat layout the adapter reads
+ * (`<cacheDir>/<repo>/config.json`).
+ *
+ * Only used to decide whether a missing revision is worth a WARNING: a machine that has never
+ * installed the model (a fresh install still in flight) has nothing to fingerprint yet, so the
+ * degradation is real but not yet reportable — warning there would be noise on every first run.
+ * Once the weights are present and the sidecar still is not, "no revision" is a genuine blind spot.
+ */
+export declare function modelFilesPresent(cacheDir: string, model: string): boolean;
+/**
+ * Read the family sidecar's revision for `model`, never throwing.
+ *
+ * Absence is a legitimate state (a model fetched by transformers.js directly, a machine that never
+ * ran the family provisioner, an install still in flight), not an error: the caller reports the
+ * degradation once and the fingerprint simply omits the revision.
+ *
+ * @param cacheDir - the model cache root the adapter actually reads (`semantic.cache_dir`).
+ * @param model - the repo id (`Xenova/bge-base-zh-v1.5`).
+ */
+export declare function readModelRevision(cacheDir: string, model: string): ModelRevisionRead;

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

@@ -21,8 +21,6 @@ export interface RetrievalEvent {
     results: number;
     latencyMs: number;
     semanticLive: boolean;
-    rerankUsed?: boolean;
-    rerankFallback?: boolean;
     /**
      * Per-leg candidates removed by the relevance floors before fusion. The per-leg shape is what
      * makes an empty result readable ("the FTS floor cut 7 rows" vs "no leg had a candidate"); the
@@ -32,7 +30,7 @@ export interface RetrievalEvent {
 }
 /** Record one completed retrieval. */
 export declare function recordRetrieval(event: RetrievalEvent): void;
-export type TruncationKind = 'embedding' | 'rerank' | 'output';
+export type TruncationKind = 'embedding' | 'output';
 /**
  * Record that a retrieval LEG returned exactly its cap, i.e. that its tail was dropped.
  *