@mirk/store 0.4.1 → 0.6.0

package/dist/adapters/sqlite.d.ts

@@ -1,6 +1,7 @@
 import Database from 'better-sqlite3';
 import { b as SyncStore } from '../types-DyQLNtxa.js';
-import { d as VectorStore } from '../types-BqSZEMAB.js';
+import { d as VectorStore } from '../types-B0XrD10b.js';
+import { c as SearchStore } from '../types-0B0Tw1fz.js';
 
 interface SqliteAdapterOptions {
     /** Path to the SQLite database file. Use ":memory:" for in-memory. */
@@ -19,6 +20,7 @@ declare class SqliteAdapter {
     private readonly db;
     readonly kv: SyncStore;
     readonly vector: VectorStore;
+    readonly search: SearchStore;
     constructor(opts: SqliteAdapterOptions);
     /** Close the underlying connection (shared by both facets). */
     close(): void;

package/dist/adapters/sqlite.js

@@ -1,9 +1,22 @@
+import {
+  sanitizeFtsQuery
+} from "../chunk-6YJ66JFO.js";
+import {
+  buildLimitOffset,
+  buildOrderBy,
+  buildWhereClause,
+  hashName
+} from "../chunk-DP4D7CJY.js";
 import {
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
+  isUsableVector,
   vectorToBuffer
-} from "../chunk-GC4MYP45.js";
+} from "../chunk-BXM3YDOC.js";
+import {
+  matchesWhere
+} from "../chunk-KPMRRYTL.js";
 
 // src/adapters/sqlite.ts
 import Database from "better-sqlite3";
@@ -25,19 +38,11 @@ function tryLoadSqliteVec(db) {
     return false;
   }
 }
-function isUsableVector(v) {
-  let nonZero = false;
-  for (let i = 0; i < v.length; i++) {
-    const x = v[i] ?? 0;
-    if (!Number.isFinite(x)) return false;
-    if (x !== 0) nonZero = true;
-  }
-  return nonZero;
-}
 var SqliteAdapter = class {
   db;
   kv;
   vector;
+  search;
   constructor(opts) {
     const ownsDb = opts.db === void 0;
     this.db = opts.db ?? new Database(opts.path);
@@ -45,6 +50,7 @@ var SqliteAdapter = class {
       this.db.pragma("journal_mode = WAL");
       this.kv = new SqliteKvFacet(this.db);
       this.vector = new SqliteVectorFacet(this.db, opts.path, opts.dimensions, opts.forceJsCosine);
+      this.search = new SqliteSearchFacet(this.db);
     } catch (err) {
       if (ownsDb) {
         try {
@@ -271,6 +277,9 @@ var SqliteVectorFacet = class {
       metadata: row.metadata === null ? void 0 : JSON.parse(row.metadata)
     };
   }
+  has(collection, id) {
+    return this.db.prepare(`SELECT 1 FROM vectors WHERE collection = ? AND id = ?`).get(collection, id) !== void 0;
+  }
   remove(collection, id) {
     if (this.accelerated) {
       const row = this.db.prepare(`SELECT rowid FROM vectors WHERE collection = ? AND id = ?`).get(collection, id);
@@ -288,13 +297,14 @@ var SqliteVectorFacet = class {
     this.requireDims(query);
     const topK = opts?.topK ?? 10;
     const minScore = opts?.minScore;
-    if (this.accelerated && isUsableVector(query)) {
+    const hasFilters = !!(opts?.where || opts?.whereNot);
+    if (this.accelerated && isUsableVector(query) && !hasFilters) {
       try {
         return this.searchVec(collection, query, topK, minScore);
       } catch {
       }
     }
-    return this.searchJs(collection, query, topK, minScore);
+    return this.searchJs(collection, query, topK, minScore, opts?.where, opts?.whereNot);
   }
   searchVec(collection, query, topK, minScore) {
     const table = this.ensureVecTable(collection);
@@ -318,65 +328,103 @@ var SqliteVectorFacet = class {
     out.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
     return out;
   }
-  searchJs(collection, query, topK, minScore) {
+  searchJs(collection, query, topK, minScore, where, whereNot) {
     const rows = this.db.prepare(`SELECT id, vec, metadata FROM vectors WHERE collection = ?`).all(collection);
     const scored = [];
     for (const row of rows) {
+      const meta = row.metadata === null ? void 0 : JSON.parse(row.metadata);
+      if (where && !matchesWhere(meta, where)) continue;
+      if (whereNot && matchesWhere(meta, whereNot)) continue;
       const vec = bufferToVector(row.vec);
       if (!isUsableVector(vec)) continue;
       const score = cosineSimilarity(query, vec);
       if (!Number.isFinite(score)) continue;
       if (minScore !== void 0 && score < minScore) continue;
-      scored.push({
-        id: row.id,
-        score,
-        metadata: row.metadata === null ? void 0 : JSON.parse(row.metadata)
-      });
+      scored.push({ id: row.id, score, metadata: meta });
     }
     scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
     return scored.slice(0, topK);
   }
 };
-function buildWhereClause(filter) {
-  if (!filter?.where || Object.keys(filter.where).length === 0) {
-    return { clause: "", params: [] };
-  }
-  const conditions = [];
-  const params = [];
-  for (const [key, value] of Object.entries(filter.where)) {
-    conditions.push(`json_extract(data, '$.' || ?) = ?`);
-    const bound = typeof value === "boolean" ? value ? 1 : 0 : value;
-    params.push(key, bound);
-  }
-  return { clause: ` WHERE ${conditions.join(" AND ")}`, params };
-}
-function buildOrderBy(filter) {
-  if (!filter?.sortBy) return { clause: "", params: [] };
-  const dir = filter.sortDir === "desc" ? "DESC" : "ASC";
-  return {
-    clause: ` ORDER BY json_extract(data, '$.' || ?) IS NULL, json_extract(data, '$.' || ?) ${dir}`,
-    params: [filter.sortBy, filter.sortBy]
-  };
-}
-function hashName(s) {
-  let h = 2166136261;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 16777619);
+var SqliteSearchFacet = class {
+  constructor(db) {
+    this.db = db;
   }
-  return (h >>> 0).toString(36);
-}
-function buildLimitOffset(filter) {
-  let sql = "";
-  if (filter?.limit !== void 0) {
-    sql += ` LIMIT ${Math.max(0, Math.floor(filter.limit))}`;
+  db;
+  ensured = /* @__PURE__ */ new Set();
+  baseTable(collection) {
+    return `search_docs_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
   }
-  if (filter?.offset !== void 0 && filter.offset > 0) {
-    if (!sql.includes("LIMIT")) sql += " LIMIT -1";
-    sql += ` OFFSET ${Math.max(0, Math.floor(filter.offset))}`;
+  ftsTable(collection) {
+    return `search_fts_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
   }
-  return sql;
-}
+  ensure(collection) {
+    const docs = this.baseTable(collection);
+    const fts = this.ftsTable(collection);
+    if (this.ensured.has(docs)) return { docs, fts };
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${docs} (
+        id TEXT PRIMARY KEY,
+        text TEXT NOT NULL,
+        meta_json TEXT
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS ${fts} USING fts5(
+        text, content='${docs}', content_rowid='rowid', tokenize='unicode61'
+      );
+      CREATE TRIGGER IF NOT EXISTS ${docs}_ai AFTER INSERT ON ${docs} BEGIN
+        INSERT INTO ${fts}(rowid, text) VALUES (new.rowid, new.text);
+      END;
+      CREATE TRIGGER IF NOT EXISTS ${docs}_ad AFTER DELETE ON ${docs} BEGIN
+        INSERT INTO ${fts}(${fts}, rowid, text) VALUES('delete', old.rowid, old.text);
+      END;
+      CREATE TRIGGER IF NOT EXISTS ${docs}_au AFTER UPDATE ON ${docs} BEGIN
+        INSERT INTO ${fts}(${fts}, rowid, text) VALUES('delete', old.rowid, old.text);
+        INSERT INTO ${fts}(rowid, text) VALUES (new.rowid, new.text);
+      END;
+    `);
+    this.ensured.add(docs);
+    return { docs, fts };
+  }
+  index(collection, doc) {
+    const { docs } = this.ensure(collection);
+    const metaJson = doc.meta === void 0 ? null : JSON.stringify(doc.meta);
+    this.db.prepare(
+      `INSERT INTO ${docs}(id, text, meta_json) VALUES (?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET text = excluded.text, meta_json = excluded.meta_json`
+    ).run(doc.id, doc.text, metaJson);
+  }
+  indexMany(collection, docs) {
+    const tx = this.db.transaction((items) => {
+      for (const doc of items) this.index(collection, doc);
+    });
+    tx(docs);
+  }
+  remove(collection, id) {
+    const { docs } = this.ensure(collection);
+    return this.db.prepare(`DELETE FROM ${docs} WHERE id = ?`).run(id).changes > 0;
+  }
+  search(collection, query, opts) {
+    const { docs, fts } = this.ensure(collection);
+    const sanitized = sanitizeFtsQuery(query);
+    if (sanitized.length === 0) return [];
+    const rows = this.db.prepare(
+      `SELECT d.id AS id, d.meta_json AS meta_json, bm25(${fts}) AS bm
+         FROM ${fts}
+         JOIN ${docs} d ON d.rowid = ${fts}.rowid
+         WHERE ${fts} MATCH ?
+         ORDER BY bm, d.id`
+    ).all(sanitized);
+    const limit = opts?.limit ?? 10;
+    const where = opts?.filter?.where;
+    const out = [];
+    for (const r of rows) {
+      const meta = r.meta_json === null ? {} : JSON.parse(r.meta_json);
+      if (where && !matchesWhere(meta, where)) continue;
+      out.push({ id: r.id, score: -r.bm, meta });
+    }
+    return out.slice(0, limit);
+  }
+};
 export {
   SqliteAdapter
 };

package/dist/chunk-6YJ66JFO.js

@@ -0,0 +1,15 @@
+// src/search/tokenize.ts
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+function sanitizeFtsQuery(q) {
+  const tokens = tokenize(q);
+  if (tokens.length === 0) return "";
+  return tokens.map((tok) => `"${tok.replace(/"/g, '""')}"`).join(" OR ");
+}
+
+export {
+  tokenize,
+  sanitizeFtsQuery
+};

package/dist/{chunk-GC4MYP45.js → chunk-BXM3YDOC.js}

@@ -29,6 +29,15 @@ function bufferToVector(buf) {
   }
   return out;
 }
+function isUsableVector(v) {
+  let nonZero = false;
+  for (let i = 0; i < v.length; i++) {
+    const x = v[i] ?? 0;
+    if (!Number.isFinite(x)) return false;
+    if (x !== 0) nonZero = true;
+  }
+  return nonZero;
+}
 function assertDimensions(vector, dimensions) {
   if (vector.length !== dimensions) {
     throw new Error(`Vector dimension mismatch: expected ${dimensions}, got ${vector.length}`);
@@ -39,5 +48,6 @@ export {
   cosineSimilarity,
   vectorToBuffer,
   bufferToVector,
+  isUsableVector,
   assertDimensions
 };

package/dist/chunk-DP4D7CJY.js

@@ -0,0 +1,59 @@
+// src/sql.ts
+function jsonPath(field) {
+  return `$."${field.replace(/"/g, '""')}"`;
+}
+function buildWhereClause(filter) {
+  if (!filter?.where || Object.keys(filter.where).length === 0) {
+    return { clause: "", params: [] };
+  }
+  const conditions = [];
+  const params = [];
+  for (const [key, value] of Object.entries(filter.where)) {
+    const path = jsonPath(key);
+    if (value === null) {
+      conditions.push(`json_type(data, ?) = 'null'`);
+      params.push(path);
+    } else {
+      const bound = typeof value === "boolean" ? value ? 1 : 0 : value;
+      conditions.push(`json_extract(data, ?) = ?`);
+      params.push(path, bound);
+    }
+  }
+  return { clause: ` WHERE ${conditions.join(" AND ")}`, params };
+}
+function buildOrderBy(filter) {
+  if (!filter?.sortBy) return { clause: "", params: [] };
+  const dir = filter.sortDir === "desc" ? "DESC" : "ASC";
+  const path = jsonPath(filter.sortBy);
+  return {
+    clause: ` ORDER BY json_extract(data, ?) IS NULL, json_extract(data, ?) ${dir}`,
+    params: [path, path]
+  };
+}
+function buildLimitOffset(filter) {
+  let sql = "";
+  if (filter?.limit !== void 0) {
+    sql += ` LIMIT ${Math.max(0, Math.floor(filter.limit))}`;
+  }
+  if (filter?.offset !== void 0 && filter.offset > 0) {
+    if (!sql.includes("LIMIT")) sql += " LIMIT -1";
+    sql += ` OFFSET ${Math.max(0, Math.floor(filter.offset))}`;
+  }
+  return sql;
+}
+function hashName(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(36);
+}
+
+export {
+  jsonPath,
+  buildWhereClause,
+  buildOrderBy,
+  buildLimitOffset,
+  hashName
+};

package/dist/chunk-KPMRRYTL.js

@@ -0,0 +1,14 @@
+// src/vector/filter.ts
+function matchesWhere(metadata, filter) {
+  if (!metadata) return false;
+  for (const [key, expected] of Object.entries(filter)) {
+    const actual = metadata[key];
+    if (actual === expected) continue;
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) return false;
+  }
+  return true;
+}
+
+export {
+  matchesWhere
+};

package/dist/{chunk-ZFSKQHBT.js → chunk-OUY3D4RT.js}

@@ -1,7 +1,11 @@
 import {
   assertDimensions,
-  cosineSimilarity
-} from "./chunk-GC4MYP45.js";
+  cosineSimilarity,
+  isUsableVector
+} from "./chunk-BXM3YDOC.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
 
 // src/vector/memory.ts
 var InMemoryVectorStore = class {
@@ -25,6 +29,9 @@ var InMemoryVectorStore = class {
     const doc = this.collections.get(collection)?.get(id);
     return doc ?? null;
   }
+  has(collection, id) {
+    return this.collections.get(collection)?.has(id) ?? false;
+  }
   remove(collection, id) {
     return this.collections.get(collection)?.delete(id) ?? false;
   }
@@ -39,12 +46,15 @@ var InMemoryVectorStore = class {
     if (!coll) return [];
     const scored = [];
     for (const doc of coll.values()) {
+      if (opts?.where && !matchesWhere(doc.metadata, opts.where)) continue;
+      if (opts?.whereNot && matchesWhere(doc.metadata, opts.whereNot)) continue;
+      if (!isUsableVector(doc.vector)) continue;
       const score = cosineSimilarity(query, doc.vector);
       if (!Number.isFinite(score)) continue;
       if (minScore !== void 0 && score < minScore) continue;
       scored.push({ id: doc.id, score, metadata: doc.metadata });
     }
-    scored.sort((a, b) => b.score - a.score);
+    scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
     return scored.slice(0, topK);
   }
   collectionFor(name) {
@@ -57,6 +67,42 @@ var InMemoryVectorStore = class {
   }
 };
 
+// src/vector/to-async-vector.ts
+var AsyncVectorStoreAdapter = class {
+  constructor(sync) {
+    this.sync = sync;
+  }
+  sync;
+  get meta() {
+    return this.sync.meta;
+  }
+  async upsert(collection, doc) {
+    this.sync.upsert(collection, doc);
+  }
+  async upsertMany(collection, docs) {
+    this.sync.upsertMany(collection, docs);
+  }
+  async get(collection, id) {
+    return this.sync.get(collection, id);
+  }
+  async has(collection, id) {
+    return this.sync.has(collection, id);
+  }
+  async remove(collection, id) {
+    return this.sync.remove(collection, id);
+  }
+  async count(collection) {
+    return this.sync.count(collection);
+  }
+  async search(collection, query, opts) {
+    return this.sync.search(collection, query, opts);
+  }
+};
+function toAsyncVector(store) {
+  return new AsyncVectorStoreAdapter(store);
+}
+
 export {
-  InMemoryVectorStore
+  InMemoryVectorStore,
+  toAsyncVector
 };

package/dist/chunk-TY472NYD.js

@@ -0,0 +1,91 @@
+import {
+  tokenize
+} from "./chunk-6YJ66JFO.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
+
+// src/search/memory.ts
+var K1 = 1.2;
+var B = 0.75;
+var InMemorySearchStore = class {
+  collections = /* @__PURE__ */ new Map();
+  index(collection, doc) {
+    const coll = this.collectionFor(collection);
+    this.removeFromColl(coll, doc.id);
+    const tokens = tokenize(doc.text);
+    const tf = /* @__PURE__ */ new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+    const indexed = {
+      id: doc.id,
+      meta: doc.meta ?? {},
+      tokens,
+      tf,
+      dl: tokens.length
+    };
+    coll.docs.set(doc.id, indexed);
+    coll.totalLen += indexed.dl;
+    for (const term of tf.keys()) coll.df.set(term, (coll.df.get(term) ?? 0) + 1);
+  }
+  indexMany(collection, docs) {
+    for (const doc of docs) this.index(collection, doc);
+  }
+  remove(collection, id) {
+    const coll = this.collections.get(collection);
+    if (!coll) return false;
+    return this.removeFromColl(coll, id);
+  }
+  search(collection, query, opts) {
+    const coll = this.collections.get(collection);
+    const qTokens = tokenize(query);
+    if (!coll || qTokens.length === 0) return [];
+    const limit = opts?.limit ?? 10;
+    const where = opts?.filter?.where;
+    const n = coll.docs.size;
+    const avgdl = n > 0 ? coll.totalLen / n : 0;
+    const scored = [];
+    for (const doc of coll.docs.values()) {
+      if (where && !matchesWhere(doc.meta, where)) continue;
+      let matched = false;
+      let score = 0;
+      for (const qt of qTokens) {
+        const tf = doc.tf.get(qt) ?? 0;
+        if (tf === 0) continue;
+        matched = true;
+        const df = coll.df.get(qt) ?? 0;
+        const idf = Math.log((n - df + 0.5) / (df + 0.5));
+        if (idf <= 0) continue;
+        const denom = tf + K1 * (1 - B + B * (avgdl > 0 ? doc.dl / avgdl : 0));
+        score += idf * (tf * (K1 + 1)) / denom;
+      }
+      if (!matched) continue;
+      scored.push({ id: doc.id, score, meta: doc.meta });
+    }
+    scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+    return scored.slice(0, limit);
+  }
+  removeFromColl(coll, id) {
+    const doc = coll.docs.get(id);
+    if (!doc) return false;
+    coll.docs.delete(id);
+    coll.totalLen -= doc.dl;
+    for (const term of doc.tf.keys()) {
+      const next = (coll.df.get(term) ?? 0) - 1;
+      if (next <= 0) coll.df.delete(term);
+      else coll.df.set(term, next);
+    }
+    return true;
+  }
+  collectionFor(name) {
+    let coll = this.collections.get(name);
+    if (!coll) {
+      coll = { docs: /* @__PURE__ */ new Map(), df: /* @__PURE__ */ new Map(), totalLen: 0 };
+      this.collections.set(name, coll);
+    }
+    return coll;
+  }
+};
+
+export {
+  InMemorySearchStore
+};

package/dist/filter-B9hP-TKF.d.ts

@@ -0,0 +1,8 @@
+/** Returns true when `metadata` satisfies ALL exact-match conditions in `filter`.
+ *  A missing metadata object never satisfies a non-empty filter (no field can match).
+ *  Comparison is deep-equal via JSON round-trip — the same fidelity as metadata
+ *  persisted and re-parsed from disk; avoids reference-equality surprises for
+ *  objects/arrays in the filter. */
+declare function matchesWhere(metadata: Record<string, unknown> | undefined, filter: Record<string, unknown>): boolean;
+
+export { matchesWhere as m };

package/dist/graph.d.ts

@@ -0,0 +1,71 @@
+import { A as AsyncStore, S as StoreFilter } from './types-DyQLNtxa.js';
+
+/**
+ * A directed edge stored as a flat collection record. `from`/`to` are node ids,
+ * `type` is the relation kind. Arbitrary metadata fields (e.g. `published`,
+ * `weight`) live alongside and are matchable via StoreFilter.where / edgeFilter.
+ */
+interface Edge {
+    id: string;
+    from: string;
+    to: string;
+    type: string;
+    [field: string]: unknown;
+}
+/** Which way to walk an edge. "both" treats every edge as bidirectional. */
+type Direction = "out" | "in" | "both";
+/**
+ * Single-hop adjacent edges of `opts.from`.
+ *
+ * - "out": edges where `from === opts.from`.
+ * - "in":  edges where `to === opts.from`.
+ * - "both": the union of the two (deduped by edge id).
+ *
+ * `opts.edgeFilter` (a StoreFilter on edge fields) is applied at the store level;
+ * `opts.edgeTypes`, if given, is applied in-memory afterward (the port's `where`
+ * is exact-match only and cannot express "type IN [...]").
+ *
+ * Returns the full stored edge record untouched — no projection. All extra fields
+ * (e.g. `from_type`, `to_type`, `weight`) are present on every returned edge.
+ */
+declare function neighbors(store: AsyncStore, collection: string, opts: {
+    from: string;
+    direction?: Direction;
+    edgeTypes?: string[];
+    edgeFilter?: StoreFilter;
+}): Promise<Edge[]>;
+/**
+ * Batched, fanout-free BFS to `depth` hops from `start`.
+ *
+ * Load-once strategy (the fanout avoidance): the candidate edge set is loaded
+ * with ONE store call — `store.list(collection, edgeFilter)` — applying the
+ * caller's policy `edgeFilter` at load. Everything after is in-memory: filter by
+ * `edgeTypes`, build an adjacency index, then BFS level-by-level. No per-node
+ * query fan-out, regardless of graph size.
+ *
+ * Return shape:
+ * - `nodes`: reached node ids, EXCLUDING `start`. `start` is the origin, not a
+ *   discovered neighbor — depth 0 therefore yields `[]`, depth 1 yields the
+ *   direct neighbors, etc. Cycles terminate: a node is expanded at most once.
+ * - `edges`: every edge actually traversed, deduped by id.
+ *
+ * Both arrays are sorted by id so results are deterministic across backings
+ * (the parity test relies on this). depth ≤ 0 → `{ nodes: [], edges: [] }`.
+ *
+ * "both" adjacency: an edge {from:a,to:b} makes a→b AND b→a reachable.
+ *
+ * Returns the full stored edge record untouched — no projection. All extra fields
+ * (e.g. `from_type`, `to_type`, `weight`) are present on every returned edge.
+ */
+declare function traverse(store: AsyncStore, collection: string, opts: {
+    start: string;
+    depth: number;
+    direction?: Direction;
+    edgeTypes?: string[];
+    edgeFilter?: StoreFilter;
+}): Promise<{
+    nodes: string[];
+    edges: Edge[];
+}>;
+
+export { type Direction, type Edge, neighbors, traverse };

package/dist/graph.js

@@ -0,0 +1,97 @@
+// src/graph.ts
+function filterByTypes(edges, edgeTypes) {
+  if (!edgeTypes || edgeTypes.length === 0) return edges;
+  const set = new Set(edgeTypes);
+  return edges.filter((e) => set.has(e.type));
+}
+function dedupById(edges) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const e of edges) {
+    if (seen.has(e.id)) continue;
+    seen.add(e.id);
+    out.push(e);
+  }
+  return out;
+}
+function withWhere(filter, override) {
+  return { ...filter, where: { ...filter?.where, ...override } };
+}
+async function neighbors(store, collection, opts) {
+  const direction = opts.direction ?? "out";
+  let edges;
+  if (direction === "out") {
+    edges = await store.list(
+      collection,
+      withWhere(opts.edgeFilter, { from: opts.from })
+    );
+  } else if (direction === "in") {
+    edges = await store.list(
+      collection,
+      withWhere(opts.edgeFilter, { to: opts.from })
+    );
+  } else {
+    const [out, inc] = await Promise.all([
+      store.list(collection, withWhere(opts.edgeFilter, { from: opts.from })),
+      store.list(collection, withWhere(opts.edgeFilter, { to: opts.from }))
+    ]);
+    edges = dedupById([...out, ...inc]);
+  }
+  return filterByTypes(edges, opts.edgeTypes);
+}
+async function traverse(store, collection, opts) {
+  const direction = opts.direction ?? "out";
+  if (!Number.isFinite(opts.depth) || opts.depth <= 0) {
+    return { nodes: [], edges: [] };
+  }
+  const loaded = await store.list(collection, opts.edgeFilter);
+  const all = filterByTypes(loaded, opts.edgeTypes);
+  const adjacency = /* @__PURE__ */ new Map();
+  const addAdj = (node, edge) => {
+    const list = adjacency.get(node);
+    if (list) list.push(edge);
+    else adjacency.set(node, [edge]);
+  };
+  for (const e of all) {
+    if (direction === "out") {
+      addAdj(e.from, e);
+    } else if (direction === "in") {
+      addAdj(e.to, e);
+    } else {
+      addAdj(e.from, e);
+      addAdj(e.to, e);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set([opts.start]);
+  const reached = [];
+  const traversedEdges = [];
+  const seenEdgeIds = /* @__PURE__ */ new Set();
+  let frontier = [opts.start];
+  for (let hop = 0; hop < opts.depth && frontier.length > 0; hop++) {
+    const next = [];
+    for (const node of frontier) {
+      const out = adjacency.get(node);
+      if (!out) continue;
+      for (const edge of out) {
+        if (!seenEdgeIds.has(edge.id)) {
+          seenEdgeIds.add(edge.id);
+          traversedEdges.push(edge);
+        }
+        const neighbor = edge.from === node ? edge.to : edge.from;
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          reached.push(neighbor);
+          next.push(neighbor);
+        }
+      }
+    }
+    frontier = next;
+  }
+  reached.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  traversedEdges.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  return { nodes: reached, edges: traversedEdges };
+}
+export {
+  neighbors,
+  traverse
+};

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { A as AsyncStore, S as StoreFilter, a as StoreMeta, b as SyncStore } from './types-DyQLNtxa.js';
 export { InMemoryKv, toAsync } from './kv.js';
-export { V as Vector, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult, d as VectorStore, e as VectorStoreMeta } from './types-BqSZEMAB.js';
-export { InMemoryVectorStore, assertDimensions, bufferToVector, cosineSimilarity, vectorToBuffer } from './vector.js';
+export { A as AsyncVectorStore, V as Vector, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult, d as VectorStore, e as VectorStoreMeta } from './types-B0XrD10b.js';
+export { InMemoryVectorStore, assertDimensions, bufferToVector, cosineSimilarity, isUsableVector, toAsyncVector, vectorToBuffer } from './vector.js';
+export { m as matchesWhere } from './filter-B9hP-TKF.js';
+export { S as SearchDocument, a as SearchOptions, b as SearchResult, c as SearchStore } from './types-0B0Tw1fz.js';
+export { InMemorySearchStore, sanitizeFtsQuery, tokenize } from './search.js';

package/dist/index.js

@@ -3,20 +3,38 @@ import {
   toAsync
 } from "./chunk-ZI4JA6IU.js";
 import {
-  InMemoryVectorStore
-} from "./chunk-ZFSKQHBT.js";
+  InMemorySearchStore
+} from "./chunk-TY472NYD.js";
+import {
+  InMemoryVectorStore,
+  toAsyncVector
+} from "./chunk-OUY3D4RT.js";
+import {
+  sanitizeFtsQuery,
+  tokenize
+} from "./chunk-6YJ66JFO.js";
 import {
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
+  isUsableVector,
   vectorToBuffer
-} from "./chunk-GC4MYP45.js";
+} from "./chunk-BXM3YDOC.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
 export {
   InMemoryStore as InMemoryKv,
+  InMemorySearchStore,
   InMemoryVectorStore,
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
+  isUsableVector,
+  matchesWhere,
+  sanitizeFtsQuery,
   toAsync,
+  toAsyncVector,
+  tokenize,
   vectorToBuffer
 };

package/dist/search.d.ts

@@ -0,0 +1,25 @@
+import { c as SearchStore, S as SearchDocument, a as SearchOptions, b as SearchResult } from './types-0B0Tw1fz.js';
+export { m as matchesWhere } from './filter-B9hP-TKF.js';
+import './types-DyQLNtxa.js';
+
+declare class InMemorySearchStore implements SearchStore {
+    private readonly collections;
+    index<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: SearchDocument<M>): void;
+    indexMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<SearchDocument<M>>): void;
+    remove(collection: string, id: string): boolean;
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: string, opts?: SearchOptions): SearchResult<M>[];
+    private removeFromColl;
+    private collectionFor;
+}
+
+/** Tokenize `text` into lowercase unicode word tokens. A reasonable FTS5
+ *  `unicode61`-ish split: letters and digits are token characters, everything
+ *  else is a separator. */
+declare function tokenize(text: string): string[];
+/** Sanitize a raw query into an FTS5 MATCH expression: tokenize, double-quote
+ *  each token (doubling embedded quotes), OR them. Mirrors the knowledge/session
+ *  index sanitizers so user punctuation / operators never throw. Returns "" for
+ *  an empty/whitespace query — callers treat that as "no results". */
+declare function sanitizeFtsQuery(q: string): string;
+
+export { InMemorySearchStore, SearchDocument, SearchOptions, SearchResult, SearchStore, sanitizeFtsQuery, tokenize };

package/dist/search.js

@@ -0,0 +1,16 @@
+import {
+  InMemorySearchStore
+} from "./chunk-TY472NYD.js";
+import {
+  sanitizeFtsQuery,
+  tokenize
+} from "./chunk-6YJ66JFO.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
+export {
+  InMemorySearchStore,
+  matchesWhere,
+  sanitizeFtsQuery,
+  tokenize
+};

package/dist/sql.d.ts

@@ -0,0 +1,27 @@
+import { S as StoreFilter } from './types-DyQLNtxa.js';
+
+/** A bound SQL parameter — the common subset both better-sqlite3 and @libsql/client
+ *  accept. Booleans are pre-converted to 0/1 by the builders (better-sqlite3 rejects
+ *  a raw boolean), so they never appear here. */
+type SqlParam = string | number | bigint | null;
+/** A field name is ONE top-level JSON key, never a nested path. Build the JSON path
+ *  `$."field"` (with `"` in the field doubled per SQLite JSON-path quoting) so a
+ *  dotted name (`"a.b"`) resolves to the single top-level key `a.b`, matching the
+ *  in-memory reference's `record[key]` lookup — not the nested path `$.a.b`. Returned
+ *  as a value to BIND, never interpolated into SQL: field names are caller-supplied,
+ *  so inlining them would be a SQL-injection vector. */
+declare function jsonPath(field: string): string;
+declare function buildWhereClause(filter?: StoreFilter): {
+    clause: string;
+    params: SqlParam[];
+};
+declare function buildOrderBy(filter?: StoreFilter): {
+    clause: string;
+    params: SqlParam[];
+};
+declare function buildLimitOffset(filter?: StoreFilter): string;
+/** Deterministic 32-bit FNV-1a hash → base36. Used to make collection table names
+ *  injective (distinct collection names never alias to one physical table). */
+declare function hashName(s: string): string;
+
+export { type SqlParam, buildLimitOffset, buildOrderBy, buildWhereClause, hashName, jsonPath };

package/dist/sql.js

@@ -0,0 +1,14 @@
+import {
+  buildLimitOffset,
+  buildOrderBy,
+  buildWhereClause,
+  hashName,
+  jsonPath
+} from "./chunk-DP4D7CJY.js";
+export {
+  buildLimitOffset,
+  buildOrderBy,
+  buildWhereClause,
+  hashName,
+  jsonPath
+};

package/dist/types-0B0Tw1fz.d.ts

@@ -0,0 +1,49 @@
+import { S as StoreFilter } from './types-DyQLNtxa.js';
+
+/** A document to be full-text indexed. `meta` is an exact-match-filterable
+ *  payload persisted as JSON by disk-backed backends, so it must be JSON-
+ *  serializable; values JSON can't represent (`undefined`, functions) are dropped
+ *  on persistence — don't rely on them. */
+interface SearchDocument<M = Record<string, unknown>> {
+    /** Unique id within the collection. */
+    id: string;
+    /** The text to tokenize and index. */
+    text: string;
+    /** Typed context stored alongside the text. */
+    meta?: M;
+}
+interface SearchOptions {
+    /** Maximum results to return. Default: 10. */
+    limit?: number;
+    /** Exact-match filter on document `meta` (uses `filter.where`, evaluated with
+     *  the shared `matchesWhere`). Applied before limit, after the FTS MATCH. */
+    filter?: StoreFilter;
+}
+/** A ranked search hit. `score` is the bm25 relevance — higher is more relevant. */
+interface SearchResult<M = Record<string, unknown>> {
+    id: string;
+    /** bm25 relevance. Higher = more relevant. (sqlite exposes `-bm25(fts)`; the
+     *  in-memory reference computes the same quantity directly.) */
+    score: number;
+    /** The document's `meta`, or `{}` when none was indexed. */
+    meta: M;
+}
+/** A synchronous full-text search store with per-collection documents.
+ *
+ *  Ranking is bm25 with the FTS5 default parameters (k1 = 1.2, b = 0.75). The
+ *  in-memory reference and the sqlite `.search` facet produce the same RANKING
+ *  on clear relevance differences; exact float scores need not match across
+ *  backends (the same parity caveat as /vector). */
+interface SearchStore {
+    /** Insert or replace a document by (collection, id). */
+    index<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: SearchDocument<M>): void;
+    /** Insert or replace many documents in one collection. */
+    indexMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<SearchDocument<M>>): void;
+    /** Remove a document by id. Returns true if it existed. */
+    remove(collection: string, id: string): boolean;
+    /** bm25-ranked keyword search, highest score first. Supports an exact-match
+     *  meta `filter`. An empty/whitespace query returns `[]`. */
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: string, opts?: SearchOptions): SearchResult<M>[];
+}
+
+export type { SearchDocument as S, SearchOptions as a, SearchResult as b, SearchStore as c };

package/dist/{types-BqSZEMAB.d.ts → types-B0XrD10b.d.ts}

@@ -32,6 +32,13 @@ interface VectorSearchOptions {
     topK?: number;
     /** Minimum cosine similarity; results below are excluded. Default: no floor. */
     minScore?: number;
+    /** Pre-KNN filter: only consider documents whose metadata satisfies ALL of these
+     *  exact-match conditions. Applied before scoring, so topK is out of the passing
+     *  set only. `where` and `whereNot` are independent — both may be provided. */
+    where?: Record<string, unknown>;
+    /** Pre-KNN filter: exclude documents whose metadata satisfies ANY of these
+     *  exact-match conditions. Applied before scoring. */
+    whereNot?: Record<string, unknown>;
 }
 /** A synchronous vector similarity store with per-collection documents.
  *
@@ -46,12 +53,31 @@ interface VectorStore {
     upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
     /** Fetch a document by id, or null. */
     get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    /** Check whether a document exists by (collection, id). */
+    has(collection: string, id: string): boolean;
     /** Remove a document by id. Returns true if it existed. */
     remove(collection: string, id: string): boolean;
     /** Number of documents in a collection. */
     count(collection: string): number;
-    /** k-nearest-neighbour search by cosine similarity, highest score first. */
+    /** k-nearest-neighbour search by cosine similarity, highest score first.
+     *  Supports pre-KNN filtering via opts.where / opts.whereNot. */
     search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
 }
+/** The async face of the same vector store. Remote backends (e.g. Qdrant) implement
+ *  this natively; sync backends reach it via {@link toAsyncVector}.
+ *
+ *  Hand-written rather than derived from VectorStore via a mapped type: per-method
+ *  generics (`get<M>`, `search<M>`, …) collapse to `unknown` under inference — same
+ *  constraint as the KV AsyncStore twin in src/types.ts. */
+interface AsyncVectorStore {
+    readonly meta: VectorStoreMeta;
+    upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): Promise<void>;
+    upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): Promise<void>;
+    get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): Promise<VectorDocument<M> | null>;
+    has(collection: string, id: string): Promise<boolean>;
+    remove(collection: string, id: string): Promise<boolean>;
+    count(collection: string): Promise<number>;
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): Promise<VectorSearchResult<M>[]>;
+}
 
-export type { Vector as V, VectorDocument as a, VectorSearchOptions as b, VectorSearchResult as c, VectorStore as d, VectorStoreMeta as e };
+export type { AsyncVectorStore as A, Vector as V, VectorDocument as a, VectorSearchOptions as b, VectorSearchResult as c, VectorStore as d, VectorStoreMeta as e };

package/dist/vector.d.ts

@@ -1,4 +1,5 @@
-import { V as Vector, d as VectorStore, e as VectorStoreMeta, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult } from './types-BqSZEMAB.js';
+import { V as Vector, d as VectorStore, e as VectorStoreMeta, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult, A as AsyncVectorStore } from './types-B0XrD10b.js';
+export { m as matchesWhere } from './filter-B9hP-TKF.js';
 
 /** Cosine similarity in [-1, 1]. Exact. Shared by the in-memory backend and the
  *  sqlite backend's search path. Returns 0 for length mismatch or a zero vector
@@ -10,6 +11,12 @@ declare function cosineSimilarity(a: Vector, b: Vector): number;
 declare function vectorToBuffer(vec: Vector): Buffer;
 /** Inverse of vectorToBuffer. */
 declare function bufferToVector(buf: Buffer | Uint8Array): Vector;
+/** A vector is usable for cosine similarity only if it is all-finite and has a
+ *  non-zero magnitude. A zero / non-finite vector has no cosine direction, so it is
+ *  EXCLUDED from search results on EVERY backend (in-memory, sqlite JS path, and
+ *  sqlite's vec0 path) — that keeps the backends in parity (vec0 would otherwise
+ *  return a zero vector with a null distance). Shared so the rule lives in one place. */
+declare function isUsableVector(v: Vector): boolean;
 /** Throw if a vector's length doesn't match the store's configured dimensions.
  *  Shared by every backend so the check and its message live in one place. */
 declare function assertDimensions(vector: Vector, dimensions: number): void;
@@ -26,10 +33,15 @@ declare class InMemoryVectorStore implements VectorStore {
     upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): void;
     upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
     get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    has(collection: string, id: string): boolean;
     remove(collection: string, id: string): boolean;
     count(collection: string): number;
     search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
     private collectionFor;
 }
 
-export { InMemoryVectorStore, Vector, VectorDocument, VectorSearchOptions, VectorSearchResult, VectorStore, VectorStoreMeta, assertDimensions, bufferToVector, cosineSimilarity, vectorToBuffer };
+/** Lift a synchronous VectorStore to the {@link AsyncVectorStore} interface. The
+ *  bridge only goes this direction — sync ⊂ async. */
+declare function toAsyncVector(store: VectorStore): AsyncVectorStore;
+
+export { AsyncVectorStore, InMemoryVectorStore, Vector, VectorDocument, VectorSearchOptions, VectorSearchResult, VectorStore, VectorStoreMeta, assertDimensions, bufferToVector, cosineSimilarity, isUsableVector, toAsyncVector, vectorToBuffer };

package/dist/vector.js

@@ -1,16 +1,24 @@
 import {
-  InMemoryVectorStore
-} from "./chunk-ZFSKQHBT.js";
+  InMemoryVectorStore,
+  toAsyncVector
+} from "./chunk-OUY3D4RT.js";
 import {
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
+  isUsableVector,
   vectorToBuffer
-} from "./chunk-GC4MYP45.js";
+} from "./chunk-BXM3YDOC.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
 export {
   InMemoryVectorStore,
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
+  isUsableVector,
+  matchesWhere,
+  toAsyncVector,
   vectorToBuffer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirk/store",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Code-split storage ports + source adapters under one namespace. KV + collection store and vector similarity store as interface subpaths; the sqlite source-adapter implements both over one connection.",
   "license": "Apache-2.0",
@@ -25,6 +25,7 @@
   "homepage": "https://github.com/nightwork-dev/mirk/tree/main/packages/store#readme",
   "bugs": "https://github.com/nightwork-dev/mirk/issues",
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -38,6 +39,18 @@
       "import": "./dist/vector.js",
       "types": "./dist/vector.d.ts"
     },
+    "./search": {
+      "import": "./dist/search.js",
+      "types": "./dist/search.d.ts"
+    },
+    "./graph": {
+      "import": "./dist/graph.js",
+      "types": "./dist/graph.d.ts"
+    },
+    "./sql": {
+      "import": "./dist/sql.js",
+      "types": "./dist/sql.d.ts"
+    },
     "./sqlite": {
       "import": "./dist/adapters/sqlite.js",
       "types": "./dist/adapters/sqlite.d.ts"
@@ -46,6 +59,12 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsup src/index.ts src/kv.ts src/vector.ts src/search.ts src/graph.ts src/sql.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
+  },
   "peerDependencies": {
     "better-sqlite3": "^11.0.0 || ^12.0.0",
     "sqlite-vec": "^0.1.0"
@@ -69,12 +88,5 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "build": "rm -rf dist && tsup src/index.ts src/kv.ts src/vector.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
-  },
-  "types": "./dist/index.d.ts"
-}
+  }
+}