@wrongstack/vector-memory 0.319.0 → 0.320.1

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { SAGE_SYNC_MARKER_FILENAME, decideWhetherToSync, startFirstBootSageSync,
 export { createVectorMemoryTools } from './tools.js';
 export { asVectorRecallProvider, fuseWithVectorMemory, type SageFusionHit, type SageFusionOptions, } from './sage-fusion.js';
 export { wrapMemoryPortWithVectorRecall, type VectorPortWrappingOptions, } from './sage-port-wrapper.js';
-export { forgetStaleSageMirrors, subscribeVectorMemoryToSage, type VectorMemoryMirrorHandle, type VectorMemoryMirrorOptions, } from './sage-event-mirror.js';
+export { DEFAULT_SWEEP_INTERVAL_MS, forgetStaleSageMirrors, SAGE_SWEEP_MARKER_FILENAME, subscribeVectorMemoryToSage, sweepStaleSageMirrors, type SweepStaleSageMirrorsOptions, type SweepStaleSageMirrorsResult, type VectorMemoryMirrorHandle, type VectorMemoryMirrorOptions, } from './sage-event-mirror.js';
 export { runSearchRace, type SearchRaceChannelHit, type SearchRaceOptions, type SearchRaceResult, } from './search-race.js';
 export type { SageSyncReport, VectorEntry, VectorEntryInput, VectorEntryWithVector, VectorKind, VectorMemoryStoreOptions, VectorScope, VectorSearchHit, VectorSearchOptions, VectorStoreStats, } from './types.js';
 export { VectorMemoryError, VectorMemoryProviderUnavailableError, } from './errors.js';

package/dist/index.js

@@ -165,9 +165,7 @@ function initVectorSchema(db) {
   db.exec("CREATE INDEX IF NOT EXISTS idx_entries_scope ON entries(scope)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_entries_kind ON entries(kind)");
   db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_hash ON entries(content_hash)");
-  db.exec(
-    "CREATE INDEX IF NOT EXISTS idx_entries_updated ON entries(updated_at DESC)"
-  );
+  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_updated ON entries(updated_at DESC)");
   db.exec(`
     CREATE TABLE IF NOT EXISTS vectors (
       entry_id TEXT NOT NULL,
@@ -229,15 +227,7 @@ function upsertEmbeddingCache(db, row) {
        last_used_at = excluded.last_used_at,
        use_count = embedding_cache.use_count + 1,
        vector = excluded.vector`
-  ).run(
-    row.contentHash,
-    row.providerId,
-    row.dimensions,
-    row.vector,
-    row.text,
-    row.now,
-    row.now
-  );
+  ).run(row.contentHash, row.providerId, row.dimensions, row.vector, row.text, row.now, row.now);
 }
 function lookupEmbeddingCache(db, contentHash, providerId, dimensions, now) {
   const row = db.prepare(
@@ -553,29 +543,59 @@ var VectorMemoryStore = class _VectorMemoryStore {
       filters.push("e.kind = ?");
       params.push(opts.kind);
     }
-    const rows = this.db.prepare(
-      `SELECT e.id, e.text, e.summary, e.metadata, e.tags, e.scope, e.kind,
-                e.content_hash, e.created_at, e.updated_at,
-                v.vector AS vec_blob
+    const scanRows = this.db.prepare(
+      `SELECT e.id AS id, v.vector AS vec_blob
            FROM entries e
            JOIN vectors v ON v.entry_id = e.id
           WHERE ${filters.join(" AND ")}`
     ).all(...params);
-    const scored = [];
-    for (const row of rows) {
-      const blob = row.vec_blob;
-      const vec = decodeVector(blob);
+    const top = [];
+    for (const row of scanRows) {
+      const vec = decodeVector(row.vec_blob);
       const raw = cosineSimilarity(queryVec, vec);
       const score = Math.max(0, Math.min(1, raw));
       if (score < threshold) continue;
-      const entry = this.rowToEntry(row);
-      const hit = { entry, score, providerId };
-      if (includeVectors) hit.vector = vec;
+      if (top.length >= limit && score <= (top[top.length - 1]?.score ?? 0)) continue;
+      let at = top.length;
+      while (at > 0 && (top[at - 1]?.score ?? 0) < score) at--;
+      top.splice(at, 0, { id: row.id, score, vector: vec });
+      if (top.length > limit) top.length = limit;
+    }
+    if (top.length === 0) return [];
+    const placeholders = top.map(() => "?").join(",");
+    const hydrated = this.db.prepare(
+      `SELECT id, text, summary, metadata, tags, scope, kind,
+                content_hash, created_at, updated_at
+           FROM entries WHERE id IN (${placeholders})`
+    ).all(...top.map((t) => t.id));
+    const entryById = /* @__PURE__ */ new Map();
+    for (const row of hydrated) {
+      entryById.set(row.id, this.rowToEntry(row));
+    }
+    const scored = [];
+    for (const candidate of top) {
+      const entry = entryById.get(candidate.id);
+      if (!entry) continue;
+      const hit = { entry, score: candidate.score, providerId };
+      if (includeVectors) hit.vector = candidate.vector;
       scored.push(hit);
     }
-    scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, limit);
+    return scored;
   }
+  /**
+   * Page through entries, newest first.
+   *
+   * Ordering is `(updated_at, id)` DESC — `updated_at` alone is not unique, so
+   * without the id tiebreak two entries written in the same millisecond can
+   * swap places between calls and a paging caller silently skips one.
+   *
+   * Pagination is keyset (`after`), not offset, because the only caller that
+   * pages is `forgetStaleSageMirrors`, which *deletes as it walks*. Under
+   * `OFFSET` every deletion shifts the remaining rows left and the next page
+   * skips exactly as many entries as were removed. Keyset is immune: it
+   * resumes from a position, and the rows a deletion removes are ones the
+   * sweep has already passed.
+   */
   list(opts = {}) {
     this.assertOpen();
     const where = [];
@@ -588,8 +608,12 @@ var VectorMemoryStore = class _VectorMemoryStore {
       where.push("kind = ?");
       params.push(opts.kind);
     }
+    if (opts.after) {
+      where.push("(updated_at < ? OR (updated_at = ? AND id < ?))");
+      params.push(opts.after.updatedAt, opts.after.updatedAt, opts.after.id);
+    }
     const sql = `SELECT * FROM entries ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
-                 ORDER BY updated_at DESC LIMIT ?`;
+                 ORDER BY updated_at DESC, id DESC LIMIT ?`;
     params.push(opts.limit ?? 100);
     const rows = this.db.prepare(sql).all(...params);
     return rows.map((r) => this.rowToEntry(r));
@@ -934,7 +958,10 @@ function decideWhetherToSync(store, staleAfterMs, now = /* @__PURE__ */ new Date
   const ageMs = Number.isNaN(startedAt) ? Number.POSITIVE_INFINITY : now.getTime() - startedAt;
   const stale = ageMs > staleAfterMs;
   if (existing.pid === void 0) {
-    return Number.isNaN(startedAt) || stale ? { run: true, reason: Number.isNaN(startedAt) ? "running-marker-undated" : "running-marker-stale" } : { run: false, reason: "running-unknown-pid" };
+    return Number.isNaN(startedAt) || stale ? {
+      run: true,
+      reason: Number.isNaN(startedAt) ? "running-marker-undated" : "running-marker-stale"
+    } : { run: false, reason: "running-unknown-pid" };
   }
   try {
     if (pidAlive(existing.pid)) {
@@ -987,7 +1014,12 @@ function storeProvider(store) {
   return void 0;
 }
 function counts(report) {
-  return { scanned: report.scanned, indexed: report.indexed, skipped: report.skipped, failed: report.failed };
+  return {
+    scanned: report.scanned,
+    indexed: report.indexed,
+    skipped: report.skipped,
+    failed: report.failed
+  };
 }
 
 // src/tools.ts
@@ -1062,7 +1094,12 @@ function vectorMemorySearchTool(store) {
       type: "object",
       properties: {
         query: { type: "string", minLength: 1, description: "The natural-language query." },
-        limit: { type: "number", minimum: 1, maximum: 100, description: "Max results (default 10)." },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 100,
+          description: "Max results (default 10)."
+        },
         threshold: {
           type: "number",
           minimum: 0,
@@ -1137,7 +1174,11 @@ function vectorMemoryForgetTool(store) {
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", minLength: 1, description: "Entry id returned by `vector_memory_remember`." }
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Entry id returned by `vector_memory_remember`."
+        }
       },
       required: ["id"],
       additionalProperties: false
@@ -1254,20 +1295,11 @@ function clamp01(value) {
 
 // src/sage-port-wrapper.ts
 import {
+  augmentLexicalWithVectorRecall,
+  isSageVisibleForSearch,
   SAGE_RETRIEVAL_CAPABILITY,
   SAGE_SURFACE_CAPABILITY
 } from "@wrongstack/sage";
-function mergeVectorRecall(options, recall, weight, threshold) {
-  if (options && typeof options === "object" && "vectorRecall" in options && options["vectorRecall"]) {
-    return options;
-  }
-  return {
-    ...options ?? {},
-    vectorRecall: recall,
-    ...weight !== void 0 ? { vectorRecallWeight: weight } : {},
-    ...threshold !== void 0 ? { vectorRecallMinScore: threshold } : {}
-  };
-}
 function asVectorRecallProviderAdapter(store) {
   return {
     async search(query, opts) {
@@ -1288,18 +1320,39 @@ function asVectorRecallProviderAdapter(store) {
 }
 function wrapMemoryPortWithVectorRecall(port, options) {
   const recall = options.vectorRecall ?? asVectorRecallProviderAdapter(options.store);
-  const weight = options.weight;
-  const threshold = options.threshold;
-  const wrapSearch = (original) => {
-    return ((query, searchOpts) => original(
+  const materializeFor = (searchOpts) => async (sageId) => {
+    const surface = port.getCapability(SAGE_SURFACE_CAPABILITY);
+    if (!surface?.getSage) return void 0;
+    const memory = await surface.getSage(sageId);
+    if (!memory) return void 0;
+    return isSageVisibleForSearch(memory, searchOpts) ? memory : void 0;
+  };
+  const fusionOptions = (searchOpts) => ({
+    vectorRecall: recall,
+    materializeVectorOnly: materializeFor(searchOpts),
+    ...options.weight !== void 0 ? { vectorWeight: options.weight } : {},
+    ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
+    ...options.vectorOnlyThreshold !== void 0 ? { vectorOnlyThreshold: options.vectorOnlyThreshold } : {},
+    ...options.maxMaterializations !== void 0 ? { maxMaterializations: options.maxMaterializations } : {},
+    ...searchOpts?.limit !== void 0 ? { limit: searchOpts.limit } : {}
+  });
+  const callerOwnsFusion = (searchOpts) => Boolean(searchOpts?.vectorRecall);
+  const wrapSearchSage = (original) => async (query, searchOpts) => {
+    const opts = searchOpts;
+    const lexical = await original(query, searchOpts);
+    if (callerOwnsFusion(opts)) return lexical;
+    const fused = await augmentLexicalWithVectorRecall(query, lexical, fusionOptions(opts));
+    return fused.map((hit) => hit.memory);
+  };
+  const wrapSearchWithBreakdown = (original) => async (query, searchOpts) => {
+    const opts = searchOpts;
+    const lexicalHits = await original(query, searchOpts);
+    if (callerOwnsFusion(opts)) return lexicalHits;
+    return augmentLexicalWithVectorRecall(
       query,
-      mergeVectorRecall(
-        searchOpts,
-        recall,
-        weight,
-        threshold
-      )
-    ));
+      lexicalHits.map((hit) => hit.memory),
+      fusionOptions(opts)
+    );
   };
   const wrapped = Object.create(
     Object.getPrototypeOf(port),
@@ -1311,13 +1364,9 @@ function wrapMemoryPortWithVectorRecall(port, options) {
       if (!original) return void 0;
       return {
         ...original,
-        searchSage: wrapSearch(original.searchSage),
-        // The rich-breakdown variant uses the same options-merge
-        // helper — pass the vector recall through so consumers that
-        // want the per-channel score breakdown get the same fusion
-        // behaviour as `searchSage`.
+        searchSage: wrapSearchSage(original.searchSage),
         ...original.searchSageWithBreakdown ? {
-          searchSageWithBreakdown: wrapSearch(
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
             original.searchSageWithBreakdown
           )
         } : {}
@@ -1328,9 +1377,9 @@ function wrapMemoryPortWithVectorRecall(port, options) {
       if (!original) return void 0;
       return {
         ...original,
-        searchSage: wrapSearch(original.searchSage),
+        searchSage: wrapSearchSage(original.searchSage),
         ...original.searchSageWithBreakdown ? {
-          searchSageWithBreakdown: wrapSearch(
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
             original.searchSageWithBreakdown
           )
         } : {}
@@ -1342,6 +1391,8 @@ function wrapMemoryPortWithVectorRecall(port, options) {
 }
 
 // src/sage-event-mirror.ts
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
 import { getSageSurface as getSageSurface2 } from "@wrongstack/sage";
 function subscribeVectorMemoryToSage(opts) {
   const { store, memoryStore } = opts;
@@ -1363,9 +1414,7 @@ function subscribeVectorMemoryToSage(opts) {
     try {
       return await surface.getSage(memoryId);
     } catch (err) {
-      log?.warn?.(
-        `vector-memory mirror fetch failed for ${memoryId}: ${errMsg2(err)}`
-      );
+      log?.warn?.(`vector-memory mirror fetch failed for ${memoryId}: ${errMsg2(err)}`);
       return null;
     }
   };
@@ -1392,9 +1441,7 @@ function subscribeVectorMemoryToSage(opts) {
         }
       });
     } catch (err) {
-      log?.warn?.(
-        `vector-memory mirror remember failed for ${memoryId}: ${errMsg2(err)}`
-      );
+      log?.warn?.(`vector-memory mirror remember failed for ${memoryId}: ${errMsg2(err)}`);
     }
   };
   const forgetMirror = async (memoryId) => {
@@ -1402,9 +1449,7 @@ function subscribeVectorMemoryToSage(opts) {
       const existing = store.findBySageId(memoryId);
       if (existing) await store.forget(existing.id);
     } catch (err) {
-      log?.warn?.(
-        `vector-memory mirror forget failed for ${memoryId}: ${errMsg2(err)}`
-      );
+      log?.warn?.(`vector-memory mirror forget failed for ${memoryId}: ${errMsg2(err)}`);
     }
   };
   const offAccepted = events.onPattern("memory.accepted", (_event, payload) => {
@@ -1438,14 +1483,18 @@ function subscribeVectorMemoryToSage(opts) {
     }
   };
 }
-async function forgetStaleSageMirrors(store, memoryStore, logger) {
+async function forgetStaleSageMirrors(store, memoryStore, logger, options) {
   const surface = getSageSurface2(memoryStore);
   if (!surface) return { scanned: 0, removed: 0 };
   let scanned = 0;
   let removed = 0;
-  for (let offset = 0; ; offset += 1e3) {
-    const page = store.list({ limit: 1e3 });
+  const PAGE = Math.max(1, options?.pageSize ?? 500);
+  let after;
+  for (; ; ) {
+    const page = store.list(after ? { limit: PAGE, after } : { limit: PAGE });
     if (page.length === 0) break;
+    const last = page[page.length - 1];
+    after = { updatedAt: last.updatedAt, id: last.id };
     for (const entry of page) {
       scanned++;
       const sageId = entry.metadata?.sageId;
@@ -1456,18 +1505,46 @@ async function forgetStaleSageMirrors(store, memoryStore, logger) {
         await store.forget(entry.id);
         removed++;
       } catch (err) {
-        logger?.warn?.(
-          `vector-memory stale-mirror sweep failed for ${sageId}: ${errMsg2(err)}`
-        );
+        logger?.warn?.(`vector-memory stale-mirror sweep failed for ${sageId}: ${errMsg2(err)}`);
       }
     }
-    if (page.length < 1e3) break;
+    if (page.length < PAGE) break;
   }
   return { scanned, removed };
 }
 function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+var SAGE_SWEEP_MARKER_FILENAME = "sage-mirror-sweep.json";
+var DEFAULT_SWEEP_INTERVAL_MS = 60 * 6e4;
+async function sweepStaleSageMirrors(opts) {
+  const markerPath2 = path3.join(opts.store.directory, SAGE_SWEEP_MARKER_FILENAME);
+  const interval = opts.minIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+  if (!opts.force) {
+    try {
+      const raw = JSON.parse(fs3.readFileSync(markerPath2, "utf8"));
+      const at = typeof raw.at === "string" ? Date.parse(raw.at) : Number.NaN;
+      if (Number.isFinite(at) && Date.now() - at < interval) {
+        return { swept: false, reason: "throttled" };
+      }
+    } catch {
+    }
+  }
+  try {
+    fs3.writeFileSync(markerPath2, JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
+  } catch {
+  }
+  try {
+    const result = await forgetStaleSageMirrors(opts.store, opts.memoryStore, opts.logger);
+    opts.logger?.debug?.(
+      `vector-memory stale-mirror sweep: scanned=${result.scanned} removed=${result.removed}`
+    );
+    return { swept: true, ...result };
+  } catch (err) {
+    opts.logger?.warn?.(`vector-memory stale-mirror sweep failed: ${errMsg2(err)}`);
+    return { swept: false, reason: errMsg2(err) };
+  }
+}
 
 // src/search-race.ts
 function previewText(text, maxLen) {
@@ -1499,8 +1576,8 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
     overlap.push({
       id,
       lexicalScore: score,
-      vectorScore: 0,
-      // patched below
+      vectorScore: null,
+      // patched below when a vector hit carries this id
       preview: previewText(mem.text, 140)
     });
   }
@@ -1523,7 +1600,7 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
   }
   for (let i = overlap.length - 1; i >= 0; i--) {
     const row = overlap[i];
-    if (row.vectorScore === 0) {
+    if (row.vectorScore === null) {
       lexicalOnly.push({
         id: row.id,
         lexicalScore: row.lexicalScore,
@@ -1540,6 +1617,8 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
     query,
     lexicalOnly,
     vectorOnly,
+    // The sweep above removed every row still carrying a null vectorScore,
+    // so every remaining row holds a real number here.
     overlap,
     metrics: {
       lexicalCount,
@@ -1552,9 +1631,11 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
   };
 }
 export {
+  DEFAULT_SWEEP_INTERVAL_MS,
   DEFAULT_VECTOR_DIMENSIONS,
   DEFAULT_VECTOR_DTYPE,
   DEFAULT_VECTOR_MODEL_ID,
+  SAGE_SWEEP_MARKER_FILENAME,
   SAGE_SYNC_MARKER_FILENAME,
   TransformersEmbeddingProvider,
   VECTOR_DIMENSIONS_KEY,
@@ -1577,6 +1658,7 @@ export {
   runSearchRace,
   startFirstBootSageSync,
   subscribeVectorMemoryToSage,
+  sweepStaleSageMirrors,
   upsertEmbeddingCache,
   wrapMemoryPortWithVectorRecall
 };

package/dist/sage-event-mirror.d.ts

@@ -34,14 +34,64 @@ export declare function subscribeVectorMemoryToSage(opts: VectorMemoryMirrorOpti
  * Walks the store, looks up each `metadata.sageId` in the SAGE surface,
  * and forgets entries whose SAGE id no longer resolves.
  *
- * Useful after bulk operations (`memory.cleared`, `hygiene.purge_deleted`)
- * that emit a single top-level event but may not emit per-memory
- * `memory.deleted` events.
+ * This is the safety net for bulk operations — hygiene's archive/purge
+ * passes, `memory.cleared` — which emit a single top-level event rather than
+ * a per-memory `memory.deleted`, so the live mirror never sees them. Without
+ * a periodic sweep those rows stay in the vector store forever.
+ *
+ * A stale row is not a *correctness* hole: a semantic-only hit is resolved
+ * through `SageSurface.getSage` and re-checked with `isSageVisibleForSearch`,
+ * which rejects an archived or deleted memory. It is a *cost* — every stale
+ * row is scanned on every cosine pass and can consume one of the fusion's
+ * bounded `maxMaterializations` slots before being dropped.
+ *
+ * Hosts run this from the session-end teardown, throttled alongside SAGE
+ * hygiene (see `setupVectorMemory` / `startWebUI`).
  */
 export declare function forgetStaleSageMirrors(store: VectorMemoryStore, memoryStore: MemoryPort, logger?: {
     warn?(msg: string, ctx?: unknown): void | undefined;
+}, 
+/** Rows per keyset page. Exposed so tests can exercise multi-page walks. */
+options?: {
+    pageSize?: number | undefined;
 }): Promise<{
     scanned: number;
     removed: number;
 }>;
+/** Sidecar recording the last stale-mirror sweep, next to the vector db. */
+export declare const SAGE_SWEEP_MARKER_FILENAME = "sage-mirror-sweep.json";
+/** Default minimum gap between sweeps. Matches SAGE's auto-hygiene throttle. */
+export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
+export interface SweepStaleSageMirrorsOptions {
+    store: VectorMemoryStore;
+    memoryStore: MemoryPort;
+    logger?: {
+        debug?(msg: string): void | undefined;
+        warn?(msg: string): void | undefined;
+    } | undefined;
+    /** Skip when the last sweep was more recent than this. Default 1 hour. */
+    minIntervalMs?: number | undefined;
+    /** Run regardless of the throttle (operator-forced re-sync). */
+    force?: boolean | undefined;
+}
+export interface SweepStaleSageMirrorsResult {
+    swept: boolean;
+    reason?: string;
+    scanned?: number;
+    removed?: number;
+}
+/**
+ * Throttled wrapper around {@link forgetStaleSageMirrors} for host wiring.
+ *
+ * The sweep is O(corpus) with one `getSage` per mirrored row, so it must not
+ * run on every boot of every surface — a project with the CLI and the WebUI
+ * open would otherwise sweep twice per session start. The throttle is a
+ * timestamp file beside the vector database rather than a process-local
+ * variable, precisely so that those two independent processes share it.
+ *
+ * Fail-open in every direction: an unreadable or corrupt marker is treated as
+ * "never swept", and a failed sweep is logged and swallowed. Callers
+ * fire-and-forget this during boot.
+ */
+export declare function sweepStaleSageMirrors(opts: SweepStaleSageMirrorsOptions): Promise<SweepStaleSageMirrorsResult>;
 //# sourceMappingURL=sage-event-mirror.d.ts.map

package/dist/sage-port-wrapper.d.ts

@@ -1,21 +1,47 @@
 /**
  * Wrap an existing SAGE `MemoryPort` so that every `searchSage` /
- * `unifiedSearch` / `retrieveForAudience` call automatically injects
- * the supplied `VectorRecallProvider`. The wrapper preserves the
- * underlying port's identity for callers that compare ports, but routes
- * the read-side capability methods through a vector-augmented
- * `searchSage`.
+ * `searchSageWithBreakdown` call fuses the port's lexical candidate set with
+ * a semantic recall from the local vector store.
  *
  * Why a wrapper and not a direct constructor change:
  *   - non-invasive: no migration needed for existing host construction
  *   - opt-in: hosts that don't want vector augmentation just don't wrap
  *   - testable: easy to mock the wrapper in unit tests
  *
- * The wrapper only augments paths that go through the read-side
- * capability (`getCapability(SAGE_RETRIEVAL_CAPABILITY)` /
- * `getCapability(SAGE_SURFACE_CAPABILITY)`). Other capabilities
- * (write-side, hygiene, audit) pass through unchanged so the wrapper
- * never widens the trust boundary.
+ * ## Why the fusion runs HERE and not inside the store
+ *
+ * The historical implementation merged a `vectorRecall` provider into the
+ * search *options* and let `SqliteSageStore.searchSage` do the fusion. That
+ * works only when the store is in-process. In production it is not: hosts
+ * build the port with `createProjectSageMemoryPort`, which returns a
+ * `ProjectSageMemoryPort` speaking line-delimited JSON to the per-project
+ * SAGE daemon (`encodeSageProjectServerMessage` = `JSON.stringify`).
+ * `JSON.stringify({ vectorRecall: { search: fn } })` yields
+ * `{"vectorRecall":{}}` — functions do not survive the wire — so the daemon
+ * saw a truthy-but-empty provider, threw `search is not a function` inside
+ * the fusion's fail-open `try`, and silently returned the lexical list.
+ * The entire semantic channel was dead in every production surface while
+ * every diagnostic reported it as wired.
+ *
+ * The vector store also *cannot* simply move into the daemon: it owns an
+ * ONNX embedding provider and `@wrongstack/vector-memory` already depends on
+ * `@wrongstack/sage`, so wiring it the other way is a dependency cycle.
+ *
+ * So the fusion runs on the host side of the boundary:
+ *   1. call the port's `searchSage` (remote or in-process) for the lexical list
+ *   2. query the local vector store for the semantic list
+ *   3. fuse with RRF via `augmentLexicalWithVectorRecall`
+ *   4. resolve vector-only hits by id through the port's surface capability,
+ *      re-applying every visibility rule the lexical channel enforces in SQL
+ *      (`isSageVisibleForSearch`)
+ *
+ * Step 4 is one round-trip per admitted vector-only hit, which is why the
+ * fusion is called with a `maxMaterializations` bound.
+ *
+ * The wrapper only augments read-side capabilities
+ * (`SAGE_RETRIEVAL_CAPABILITY` / `SAGE_SURFACE_CAPABILITY`). Other
+ * capabilities (write-side, hygiene, audit) pass through unchanged so the
+ * wrapper never widens the trust boundary.
  */
 import type { MemoryPort } from '@wrongstack/core/types';
 import { type VectorRecallProvider } from '@wrongstack/sage';
@@ -25,18 +51,28 @@ export interface VectorPortWrappingOptions {
     store: VectorMemoryStore;
     /**
      * Optional pre-built provider. When omitted, the wrapper builds one via
-     * `asVectorRecallProvider(store)`.
+     * `asVectorRecallProviderAdapter(store)`.
      */
     vectorRecall?: VectorRecallProvider | undefined;
     /**
-     * Cosine threshold forwarded to the vector backend. 0 = no threshold
-     * (keep all hits, let RRF decide).
+     * Cosine threshold forwarded to the vector backend. Undefined = no
+     * threshold (keep all hits, let RRF decide).
      */
     threshold?: number | undefined;
     /**
      * Weight of the vector channel in the RRF blend. Default 0.3.
      */
     weight?: number | undefined;
+    /**
+     * Cosine floor a semantic-only hit must clear before it is resolved and
+     * admitted. Falls back to the fusion's own default (0.62).
+     */
+    vectorOnlyThreshold?: number | undefined;
+    /**
+     * Cap on by-id resolutions of semantic-only hits per search. Each one is a
+     * round-trip when the port is remote. Falls back to the fusion default.
+     */
+    maxMaterializations?: number | undefined;
 }
 /**
  * Adapt a `VectorMemoryStore` to the SAGE `VectorRecallProvider` contract.
@@ -45,9 +81,9 @@ export interface VectorPortWrappingOptions {
  */
 export declare function asVectorRecallProviderAdapter(store: VectorMemoryStore): VectorRecallProvider;
 /**
- * Return a new `MemoryPort` that routes `searchSage` calls through the
- * supplied `VectorRecallProvider`. All other capabilities are passed
- * through unchanged.
+ * Return a new `MemoryPort` whose `searchSage` / `searchSageWithBreakdown`
+ * fuse lexical and semantic recall. All other capabilities pass through
+ * unchanged.
  */
 export declare function wrapMemoryPortWithVectorRecall(port: MemoryPort, options: VectorPortWrappingOptions): MemoryPort;
 //# sourceMappingURL=sage-port-wrapper.d.ts.map

package/dist/store.d.ts

@@ -70,10 +70,29 @@ export declare class VectorMemoryStore {
     /** Hard-delete an entry by id. Wrapped in `withFileLock` for cross-process safety. */
     forget(id: string): Promise<boolean>;
     search(query: string, opts?: VectorSearchOptions): Promise<VectorSearchHit[]>;
+    /**
+     * Page through entries, newest first.
+     *
+     * Ordering is `(updated_at, id)` DESC — `updated_at` alone is not unique, so
+     * without the id tiebreak two entries written in the same millisecond can
+     * swap places between calls and a paging caller silently skips one.
+     *
+     * Pagination is keyset (`after`), not offset, because the only caller that
+     * pages is `forgetStaleSageMirrors`, which *deletes as it walks*. Under
+     * `OFFSET` every deletion shifts the remaining rows left and the next page
+     * skips exactly as many entries as were removed. Keyset is immune: it
+     * resumes from a position, and the rows a deletion removes are ones the
+     * sweep has already passed.
+     */
     list(opts?: {
         limit?: number;
         scope?: VectorScope;
         kind?: VectorKind;
+        /** Resume after this entry — pass the last row of the previous page. */
+        after?: {
+            updatedAt: string;
+            id: string;
+        } | undefined;
     }): VectorEntry[];
     reindexAll(): Promise<{
         processed: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/vector-memory",
-  "version": "0.319.0",
+  "version": "0.320.1",
   "license": "MIT",
   "description": "WrongStack Vector Memory — an additional vector-search memory store powered by @huggingface/transformers (local ONNX embeddings), alongside the SAGE lexical memory system.",
   "repository": {
@@ -27,9 +27,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.319.0",
-    "@wrongstack/persistence": "0.319.0",
-    "@wrongstack/sage": "0.319.0"
+    "@wrongstack/core": "0.320.1",
+    "@wrongstack/persistence": "0.320.1",
+    "@wrongstack/sage": "0.320.1"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0"