@wrongstack/vector-memory 0.319.1 → 1.0.0

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

@@ -249,6 +249,11 @@ function encodeVector(vec) {
   return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
 }
 function decodeVector(buf) {
+  if (buf.byteLength % 4 !== 0) {
+    throw new Error(
+      `decodeVector: invalid vector byteLength ${buf.byteLength} (must be a multiple of 4)`
+    );
+  }
   const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   const copy = new Float32Array(buf.byteLength / 4);
   for (let i = 0; i < copy.length; i++) {
@@ -264,6 +269,12 @@ import * as path from "node:path";
 import { withFileLock } from "@wrongstack/core/utils";
 import { loadRuntimeDatabaseSync } from "@wrongstack/persistence";
 import { cosineSimilarity, HashingEmbeddingProvider } from "@wrongstack/sage";
+var DEFAULT_SEARCH_LIMIT = 10;
+function normalizeLimit(limit) {
+  if (limit === void 0 || !Number.isFinite(limit)) return DEFAULT_SEARCH_LIMIT;
+  const floored = Math.floor(limit);
+  return floored < 1 ? DEFAULT_SEARCH_LIMIT : floored;
+}
 var DEFAULT_DIRECTORY = ".wrongstack/vector-memory";
 var DEFAULT_FILENAME = "vector-memory.db";
 var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
@@ -525,7 +536,7 @@ var VectorMemoryStore = class _VectorMemoryStore {
   }
   async search(query, opts = {}) {
     this.assertOpen();
-    const limit = opts.limit ?? 10;
+    const limit = normalizeLimit(opts.limit);
     const threshold = opts.threshold ?? 0;
     const includeVectors = opts.includeVectors === true;
     if (typeof query !== "string" || query.trim().length === 0) return [];
@@ -543,29 +554,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 = [];
@@ -578,8 +619,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));
@@ -1180,12 +1225,6 @@ async function fuseWithVectorMemory(query, lexical, options = {}) {
   }
   const sageById = /* @__PURE__ */ new Map();
   for (const memory of lexical) sageById.set(memory.id, memory);
-  for (const hit of vectorHits) {
-    const sageId = hit.entry.metadata?.["sageId"];
-    if (typeof sageId === "string" && !sageById.has(sageId)) {
-      continue;
-    }
-  }
   const lexicalRanked = lexical.map((memory, index) => ({
     memory,
     rankScore: lexicalRankScore(index, lexical.length),
@@ -1203,7 +1242,7 @@ async function fuseWithVectorMemory(query, lexical, options = {}) {
   const fused = /* @__PURE__ */ new Map();
   for (let i = 0; i < lexicalRanked.length; i++) {
     const c = lexicalRanked[i];
-    const rrf = weight * 0 + (1 - weight) * (1 / (k + i + 1));
+    const rrf = (1 - weight) * (1 / (k + i + 1));
     fused.set(c.memory.id, {
       memory: c.memory,
       vectorScore: null,
@@ -1261,20 +1300,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) {
@@ -1295,18 +1325,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),
@@ -1318,13 +1369,11 @@ 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(original.searchSageWithBreakdown)
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
+            original.searchSageWithBreakdown
+          )
         } : {}
       };
     }
@@ -1333,9 +1382,11 @@ function wrapMemoryPortWithVectorRecall(port, options) {
       if (!original) return void 0;
       return {
         ...original,
-        searchSage: wrapSearch(original.searchSage),
+        searchSage: wrapSearchSage(original.searchSage),
         ...original.searchSageWithBreakdown ? {
-          searchSageWithBreakdown: wrapSearch(original.searchSageWithBreakdown)
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
+            original.searchSageWithBreakdown
+          )
         } : {}
       };
     }
@@ -1345,6 +1396,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;
@@ -1435,14 +1488,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,13 +1513,43 @@ async function forgetStaleSageMirrors(store, memoryStore, logger) {
         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) {
@@ -1549,9 +1636,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,
@@ -1574,6 +1663,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-fusion.d.ts

@@ -6,8 +6,15 @@
  *
  * The fusion is a Reciprocal Rank Fusion (RRF)-style blend rather than a
  * raw cosine-blend, so it stays robust when one side returns nothing
- * (e.g. embedding provider unavailable). All inputs are optional:
- *   - `lexical` may be `[]` → fusion falls back to pure vector ranking.
+ * (e.g. embedding provider unavailable).
+ *
+ * IMPORTANT — the vector channel can only RE-RANK the lexical list, never
+ * extend it. A vector hit is kept only when its `metadata.sageId` resolves to
+ * a memory already present in `lexical`, because the caller's lexical list is
+ * the authoritative source of `Sage` objects and this function will not
+ * fabricate one (pinned by tests/sage-fusion.test.ts). Therefore:
+ *   - `lexical` may be `[]` → the result is `[]`, whatever the vector channel
+ *     found. This is NOT a fallback to pure vector ranking.
  *   - `vector` may be `[]` → fusion falls back to pure lexical ranking.
  *   - either may be `undefined` → fusion silently drops that channel.
  *
@@ -40,6 +47,10 @@ export interface SageFusionOptions {
     /**
      * Cosine threshold below which a vector-only hit is dropped (no lexical
      * counterpart to lift it). Default 0 — keep all, let RRF decide.
+     *
+     * Currently inert: vector-only hits cannot occur (see the module docstring),
+     * so nothing ever reaches this threshold. Kept for API stability and for
+     * the day the vector channel is allowed to extend the candidate set.
      */
     vectorOnlyThreshold?: number | undefined;
 }
@@ -51,7 +62,11 @@ export interface SageFusionHit {
     lexicalScore: number | null;
     /** 0..1, monotonically higher = better. */
     finalScore: number;
-    /** Where the candidate came from. */
+    /**
+     * Where the candidate came from. `'vector'` is currently unreachable —
+     * every candidate originates in the lexical list (see the module
+     * docstring); the vector channel only upgrades one to `'both'`.
+     */
     source: 'lexical' | 'vector' | 'both';
 }
 declare function lexicalRankScore(index: number, total: number): number;

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.1",
+  "version": "1.0.0",
   "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.1",
-    "@wrongstack/persistence": "0.319.1",
-    "@wrongstack/sage": "0.319.1"
+    "@wrongstack/core": "1.0.0",
+    "@wrongstack/persistence": "1.0.0",
+    "@wrongstack/sage": "1.0.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0"