@mirk/store 0.6.0 → 0.6.1

package/README.md

@@ -24,11 +24,13 @@ npm install sqlite-vec
 | `@mirk/store` | the ports + their in-memory references + `toAsync` + cosine helpers | none |
 | `@mirk/store/kv` | `SyncStore` port (key-value + collections), `InMemoryKv`, `toAsync` | none |
 | `@mirk/store/vector` | `VectorStore` port, `InMemoryVectorStore`, cosine helpers | none |
-| `@mirk/store/sqlite` | the SQLite **source adapter** — one connection, `.kv` + `.vector` facets | `better-sqlite3` (peer), `sqlite-vec` (optional peer) |
+| `@mirk/store/search` | `SearchStore` port, `InMemorySearchStore`, BM25-style keyword search | none |
+| `@mirk/store/graph` | graph helpers over the collection port (`neighbors`, `traverse`, `traverseFrontierBatched`) | none |
+| `@mirk/store/sqlite` | the SQLite **source adapter** — one connection, `.kv` + `.vector` + `.search` facets | `better-sqlite3` (peer), `sqlite-vec` (optional peer) |
 
 Source adapters are reached **only** through their own subpath (e.g. `/sqlite`) — the root and the
-port subpaths never re-export them, so importing `@mirk/store`, `/kv`, or `/vector` never drags a
-native binding into a consumer bundle.
+port subpaths never re-export them, so importing `@mirk/store`, `/kv`, `/vector`, `/search`, or
+`/graph` never drags a native binding into a consumer bundle.
 
 ## Quickstart — zero native deps
 
@@ -60,19 +62,51 @@ kv.count("posts");                               // 1
 kv.remove("posts", "p1");
 ```
 
+## Full-text search
+
+`SearchStore` indexes documents by id and returns BM25-ranked keyword matches. Use `text` for the
+single-field shorthand or `fields` for named columns with query-time weighting:
+
+```ts
+import { InMemorySearchStore } from "@mirk/store/search";
+
+const search = new InMemorySearchStore();
+search.index("pages", { id: "a", fields: { title: "Opal guide", body: "plain body" } });
+search.index("pages", { id: "b", fields: { title: "plain title", body: "Opal guide" } });
+search.search("pages", "opal", { fieldWeights: { title: 4, body: 1 } }); // [a, b]
+```
+
+The first indexed document fixes a collection's field schema; later documents must use the same
+field names. `text` and `fields: { text }` are the same single-field schema for backwards
+compatibility.
+
+## Graph helpers
+
+`@mirk/store/graph` stores edges as ordinary collection records and traverses them through the
+existing collection port. Policy stays caller-owned through `StoreFilter`.
+
+```ts
+import { traverse } from "@mirk/store/graph";
+
+const hits = traverse(kv, { start: "node:a", depth: 2, direction: "out" });
+```
+
 ## SQLite adapter — one connection, many capabilities
 
-`SqliteAdapter` opens a single `better-sqlite3` database and exposes a `.kv` facet (a `SyncStore`)
-and a `.vector` facet (a `VectorStore`) over it:
+`SqliteAdapter` opens a single `better-sqlite3` database and exposes `.kv` (`SyncStore`), `.vector`
+(`VectorStore`), and `.search` (`SearchStore`) facets over it:
 
 ```ts
 import { SqliteAdapter } from "@mirk/store/sqlite";
 
-// `dimensions` is required to use the .vector facet; .kv works without it.
-const db = new SqliteAdapter({ path: "data.db", dimensions: 768 });
+// .kv and .search work immediately; vector dimensions infer on first write.
+const db = new SqliteAdapter({ path: "data.db" });
 
 db.kv.set("user:1", { name: "Ada" });
 
+db.search.index("pages", { id: "intro", fields: { title: "Intro", body: "hello world" } });
+db.search.search("pages", "hello", { fieldWeights: { title: 4, body: 1 } });
+
 const embedding = new Float32Array(768); // your real embedding here
 const query = new Float32Array(768);
 db.vector.upsert("docs", { id: "a", vector: embedding });
@@ -87,7 +121,7 @@ db.close();
 |---|---|---|
 | `path` | `string` | DB file path, or `":memory:"`. |
 | `db` | `Database` | Reuse an existing `better-sqlite3` connection instead of opening one. |
-| `dimensions` | `number` | Embedding dimensionality. Required before using `.vector`; persisted and enforced on reopen. |
+| `dimensions` | `number` | Optional embedding dimensionality. If omitted, inferred and persisted from the first vector `upsert` / `upsertMany`; `search` still requires known dimensions. |
 | `forceJsCosine` | `boolean` | Pin the exact JS-cosine path even when `sqlite-vec` is installed (mainly for tests). |
 
 Vectors (`Vector` is a `Float32Array`) are stored as little-endian float32 BLOBs and ranked by

package/dist/adapters/sqlite.d.ts

@@ -1,14 +1,15 @@
 import Database from 'better-sqlite3';
-import { b as SyncStore } from '../types-DyQLNtxa.js';
+import { c as SyncStore } from '../types-DHLdLZ_W.js';
 import { d as VectorStore } from '../types-B0XrD10b.js';
-import { c as SearchStore } from '../types-0B0Tw1fz.js';
+import { c as SearchStore } from '../types-BLZTMsQO.js';
 
 interface SqliteAdapterOptions {
     /** Path to the SQLite database file. Use ":memory:" for in-memory. */
     path: string;
     /** Existing better-sqlite3 instance to reuse (shares one connection). */
     db?: Database.Database;
-    /** Embedding dimensions. Required to use the `.vector` facet; KV works without it. */
+    /** Embedding dimensions. Optional: when omitted, `.vector` persists the
+     *  dimensions from the first upsert/upsertMany call. KV/search work without it. */
     dimensions?: number;
     /** Force the exact JS-cosine search path even when sqlite-vec is installed.
      *  Mainly for parity testing; production should leave this off. */

package/dist/adapters/sqlite.js

@@ -1,11 +1,17 @@
 import {
+  DEFAULT_SEARCH_FIELD,
+  assertSameSearchFields,
+  assertValidFieldWeightValues,
+  fieldWeightsFor,
+  normalizeSearchDocument,
   sanitizeFtsQuery
-} from "../chunk-6YJ66JFO.js";
+} from "../chunk-N27Y55CA.js";
 import {
   buildLimitOffset,
   buildOrderBy,
   buildWhereClause,
-  hashName
+  hashName,
+  jsonPath
 } from "../chunk-DP4D7CJY.js";
 import {
   assertDimensions,
@@ -38,6 +44,38 @@ function tryLoadSqliteVec(db) {
     return false;
   }
 }
+function assertPositiveDimensions(dimensions) {
+  if (!Number.isInteger(dimensions) || dimensions <= 0) {
+    throw new Error(`Vector dimensions must be a positive integer; got ${dimensions}.`);
+  }
+}
+function sqlParam(value) {
+  if (value === null) return null;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+    return value;
+  }
+  throw new Error("Store IN queries only support JSON scalar values.");
+}
+function buildJsonInWhere(field, values, hasPriorWhere) {
+  const path = jsonPath(field);
+  const params = [];
+  const nonNull = values.filter((value) => value !== null).map(sqlParam);
+  const hasNull = values.some((value) => value === null);
+  const parts = [];
+  if (nonNull.length > 0) {
+    parts.push(`json_extract(data, ?) IN (${nonNull.map(() => "?").join(", ")})`);
+    params.push(path, ...nonNull);
+  }
+  if (hasNull) {
+    parts.push(`json_type(data, ?) = 'null'`);
+    params.push(path);
+  }
+  return {
+    clause: `${hasPriorWhere ? " AND" : " WHERE"} (${parts.join(" OR ")})`,
+    params
+  };
+}
 var SqliteAdapter = class {
   db;
   kv;
@@ -136,6 +174,17 @@ var SqliteKvFacet = class {
     const rows = this.db.prepare(sql).all(...where.params, ...orderBy.params);
     return rows.map((r) => JSON.parse(r.data));
   }
+  listWhereIn(collection, field, values, filter) {
+    if (values.length === 0) return [];
+    const table = this.ensureTable(collection);
+    const where = buildWhereClause(filter);
+    const inWhere = buildJsonInWhere(field, values, where.clause.length > 0);
+    const orderBy = buildOrderBy(filter);
+    const limitOffset = buildLimitOffset(filter);
+    const sql = `SELECT data FROM ${table}${where.clause}${inWhere.clause}${orderBy.clause}${limitOffset}`;
+    const rows = this.db.prepare(sql).all(...where.params, ...inWhere.params, ...orderBy.params);
+    return rows.map((r) => JSON.parse(r.data));
+  }
   getById(collection, id) {
     const table = this.ensureTable(collection);
     const row = this.db.prepare(`SELECT data FROM ${table} WHERE id = ?`).get(id);
@@ -162,8 +211,10 @@ var SqliteKvFacet = class {
   }
 };
 var SqliteVectorFacet = class {
-  constructor(db, path, dimensions, forceJsCosine) {
+  constructor(db, path, dimensions, forceJsCosine = false) {
     this.db = db;
+    this.path = path;
+    this.forceJsCosine = forceJsCosine;
     this.db.exec(
       `CREATE TABLE IF NOT EXISTS vectors (
          collection TEXT NOT NULL,
@@ -183,31 +234,51 @@ var SqliteVectorFacet = class {
           `Vector store at ${path} was created with ${this.dimensions} dimensions, opened with ${dimensions}.`
         );
       }
+      this.refreshVectorMeta();
     } else if (dimensions !== void 0) {
-      this.dimensions = dimensions;
-      this.db.prepare(`INSERT INTO _vec_meta (key, value) VALUES ('dimensions', ?)`).run(String(dimensions));
-    } else {
-      this.dimensions = -1;
+      this.initializeDims(dimensions);
     }
-    this.accelerated = !forceJsCosine && this.dimensions >= 0 && tryLoadSqliteVec(this.db);
-    this.meta = {
-      backend: "sqlite",
-      dimensions: Math.max(this.dimensions, 0),
-      accelerated: this.accelerated
-    };
   }
   db;
-  meta;
-  dimensions;
+  path;
+  forceJsCosine;
+  meta = { backend: "sqlite", dimensions: 0, accelerated: false };
+  dimensions = -1;
   /** True when sqlite-vec loaded and the vec0 acceleration path is live. */
-  accelerated;
+  accelerated = false;
   vecTablesEnsured = /* @__PURE__ */ new Set();
-  requireDims(v) {
+  initializeDims(dimensions) {
+    assertPositiveDimensions(dimensions);
+    if (this.dimensions >= 0) {
+      if (dimensions !== this.dimensions) {
+        throw new Error(
+          `Vector store at ${this.path} was created with ${this.dimensions} dimensions, opened with ${dimensions}.`
+        );
+      }
+      return;
+    }
+    this.dimensions = dimensions;
+    this.db.prepare(
+      `INSERT INTO _vec_meta (key, value) VALUES ('dimensions', ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+    ).run(String(dimensions));
+    this.refreshVectorMeta();
+  }
+  refreshVectorMeta() {
+    this.accelerated = !this.forceJsCosine && this.dimensions >= 0 && tryLoadSqliteVec(this.db);
+    this.meta.dimensions = Math.max(this.dimensions, 0);
+    this.meta.accelerated = this.accelerated;
+  }
+  requireKnownDims(v) {
     if (this.dimensions < 0) {
-      throw new Error("SqliteAdapter.vector requires `dimensions` \u2014 pass { dimensions } when opening.");
+      throw new Error("SqliteAdapter.vector has no dimensions yet \u2014 pass { dimensions } when opening or upsert a vector first.");
     }
     assertDimensions(v, this.dimensions);
   }
+  ensureDimsForWrite(v) {
+    if (this.dimensions < 0) this.initializeDims(v.length);
+    assertDimensions(v, this.dimensions);
+  }
   // ── vec0 acceleration helpers ───────────────────────────────────────────
   vecTableName(collection) {
     return `vectors_vec_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
@@ -247,7 +318,7 @@ var SqliteVectorFacet = class {
     }
   }
   upsert(collection, doc) {
-    this.requireDims(doc.vector);
+    this.ensureDimsForWrite(doc.vector);
     const write = this.db.transaction(() => {
       this.db.prepare(
         `INSERT INTO vectors(collection, id, vec, metadata) VALUES (?, ?, ?, ?)
@@ -263,6 +334,14 @@ var SqliteVectorFacet = class {
     write();
   }
   upsertMany(collection, docs) {
+    const first = docs[0];
+    if (!first) return;
+    const dimensions = this.dimensions >= 0 ? this.dimensions : first.vector.length;
+    assertPositiveDimensions(dimensions);
+    for (const doc of docs) {
+      assertDimensions(doc.vector, dimensions);
+    }
+    if (this.dimensions < 0) this.initializeDims(dimensions);
     const tx = this.db.transaction((items) => {
       for (const doc of items) this.upsert(collection, doc);
     });
@@ -294,7 +373,7 @@ var SqliteVectorFacet = class {
     return row.n;
   }
   search(collection, query, opts) {
-    this.requireDims(query);
+    this.requireKnownDims(query);
     const topK = opts?.topK ?? 10;
     const minScore = opts?.minScore;
     const hasFilters = !!(opts?.where || opts?.whereNot);
@@ -346,52 +425,116 @@ var SqliteVectorFacet = class {
     return scored.slice(0, topK);
   }
 };
+function searchColumnName(field, index) {
+  if (field === DEFAULT_SEARCH_FIELD) return DEFAULT_SEARCH_FIELD;
+  return `f${index}_${hashName(field)}`;
+}
+function searchSchema(fields) {
+  return { fields: [...fields], columns: fields.map(searchColumnName) };
+}
+function quoteSqlIdent(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function searchFieldDefs(schema) {
+  return schema.columns.map((column) => `${quoteSqlIdent(column)} TEXT NOT NULL`).join(",\n        ");
+}
+function rowColumnRefs(prefix, schema) {
+  return schema.columns.map((column) => `${prefix}.${quoteSqlIdent(column)}`).join(", ");
+}
 var SqliteSearchFacet = class {
   constructor(db) {
     this.db = db;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.schemaTable} (
+        collection TEXT PRIMARY KEY,
+        fields_json TEXT NOT NULL
+      );
+    `);
   }
   db;
   ensured = /* @__PURE__ */ new Set();
+  schemaTable = "_mirk_search_schema";
   baseTable(collection) {
     return `search_docs_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
   }
   ftsTable(collection) {
     return `search_fts_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
   }
-  ensure(collection) {
+  tableExists(table) {
+    return this.db.prepare("SELECT 1 AS ok FROM sqlite_master WHERE type IN ('table', 'view') AND name = ?").get(table) !== void 0;
+  }
+  loadSchema(collection) {
+    const row = this.db.prepare(`SELECT fields_json FROM ${this.schemaTable} WHERE collection = ?`).get(collection);
+    if (row) {
+      const fields2 = JSON.parse(row.fields_json);
+      return searchSchema(fields2);
+    }
+    const docs = this.baseTable(collection);
+    if (!this.tableExists(docs)) return void 0;
+    const pragma = this.db.prepare(`PRAGMA table_info(${quoteSqlIdent(docs)})`).all();
+    if (!pragma.some((col) => col.name === DEFAULT_SEARCH_FIELD)) return void 0;
+    const fields = [DEFAULT_SEARCH_FIELD];
+    this.db.prepare(`INSERT OR IGNORE INTO ${this.schemaTable}(collection, fields_json) VALUES (?, ?)`).run(collection, JSON.stringify(fields));
+    return searchSchema(fields);
+  }
+  schemaForIndex(collection, normalized) {
+    const existing = this.loadSchema(collection);
+    if (existing) {
+      assertSameSearchFields(existing.fields, normalized.names, collection);
+      return existing;
+    }
+    const fields = [...normalized.names];
+    this.db.prepare(`INSERT INTO ${this.schemaTable}(collection, fields_json) VALUES (?, ?)`).run(collection, JSON.stringify(fields));
+    return searchSchema(fields);
+  }
+  ensure(collection, schema) {
     const docs = this.baseTable(collection);
     const fts = this.ftsTable(collection);
-    if (this.ensured.has(docs)) return { docs, fts };
+    const key = `${docs}:${schema.fields.join("\0")}`;
+    if (this.ensured.has(key)) return { docs, fts };
+    const qDocs = quoteSqlIdent(docs);
+    const qFts = quoteSqlIdent(fts);
+    const qColumns = schema.columns.map(quoteSqlIdent).join(", ");
+    const newColumns = rowColumnRefs("new", schema);
+    const oldColumns = rowColumnRefs("old", schema);
+    const fieldDefs = searchFieldDefs(schema);
     this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ${docs} (
+      CREATE TABLE IF NOT EXISTS ${qDocs} (
         id TEXT PRIMARY KEY,
-        text TEXT NOT NULL,
+        ${fieldDefs},
         meta_json TEXT
       );
-      CREATE VIRTUAL TABLE IF NOT EXISTS ${fts} USING fts5(
-        text, content='${docs}', content_rowid='rowid', tokenize='unicode61'
+      CREATE VIRTUAL TABLE IF NOT EXISTS ${qFts} USING fts5(
+        ${qColumns}, 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);
+      CREATE TRIGGER IF NOT EXISTS ${quoteSqlIdent(`${docs}_ai`)} AFTER INSERT ON ${qDocs} BEGIN
+        INSERT INTO ${qFts}(rowid, ${qColumns}) VALUES (new.rowid, ${newColumns});
       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);
+      CREATE TRIGGER IF NOT EXISTS ${quoteSqlIdent(`${docs}_ad`)} AFTER DELETE ON ${qDocs} BEGIN
+        INSERT INTO ${qFts}(${quoteSqlIdent(fts)}, rowid, ${qColumns}) VALUES('delete', old.rowid, ${oldColumns});
       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);
+      CREATE TRIGGER IF NOT EXISTS ${quoteSqlIdent(`${docs}_au`)} AFTER UPDATE ON ${qDocs} BEGIN
+        INSERT INTO ${qFts}(${quoteSqlIdent(fts)}, rowid, ${qColumns}) VALUES('delete', old.rowid, ${oldColumns});
+        INSERT INTO ${qFts}(rowid, ${qColumns}) VALUES (new.rowid, ${newColumns});
       END;
     `);
-    this.ensured.add(docs);
+    this.ensured.add(key);
     return { docs, fts };
   }
   index(collection, doc) {
-    const { docs } = this.ensure(collection);
+    const normalized = normalizeSearchDocument(doc);
+    const schema = this.schemaForIndex(collection, normalized);
+    const { docs } = this.ensure(collection, schema);
+    const qDocs = quoteSqlIdent(docs);
+    const qColumns = schema.columns.map(quoteSqlIdent);
+    const insertColumns = ["id", ...schema.columns, "meta_json"].map(quoteSqlIdent).join(", ");
+    const placeholders = Array.from({ length: schema.columns.length + 2 }, () => "?").join(", ");
+    const updateSet = [...qColumns.map((col) => `${col} = excluded.${col}`), "meta_json = excluded.meta_json"].join(", ");
     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);
+      `INSERT INTO ${qDocs}(${insertColumns}) VALUES (${placeholders})
+         ON CONFLICT(id) DO UPDATE SET ${updateSet}`
+    ).run(doc.id, ...schema.fields.map((field) => normalized.values[field] ?? ""), metaJson);
   }
   indexMany(collection, docs) {
     const tx = this.db.transaction((items) => {
@@ -400,17 +543,24 @@ var SqliteSearchFacet = class {
     tx(docs);
   }
   remove(collection, id) {
-    const { docs } = this.ensure(collection);
-    return this.db.prepare(`DELETE FROM ${docs} WHERE id = ?`).run(id).changes > 0;
+    const schema = this.loadSchema(collection);
+    if (!schema) return false;
+    const { docs } = this.ensure(collection, schema);
+    return this.db.prepare(`DELETE FROM ${quoteSqlIdent(docs)} WHERE id = ?`).run(id).changes > 0;
   }
   search(collection, query, opts) {
-    const { docs, fts } = this.ensure(collection);
     const sanitized = sanitizeFtsQuery(query);
+    assertValidFieldWeightValues(opts?.fieldWeights);
     if (sanitized.length === 0) return [];
+    const schema = this.loadSchema(collection);
+    if (!schema) return [];
+    const { docs, fts } = this.ensure(collection, schema);
+    const weights = fieldWeightsFor(schema.fields, opts?.fieldWeights);
+    const weightArgs = weights.length > 0 ? `, ${weights.map((weight) => String(weight)).join(", ")}` : "";
     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
+      `SELECT d.id AS id, d.meta_json AS meta_json, bm25(${fts}${weightArgs}) AS bm
+         FROM ${quoteSqlIdent(fts)}
+         JOIN ${quoteSqlIdent(docs)} d ON d.rowid = ${fts}.rowid
          WHERE ${fts} MATCH ?
          ORDER BY bm, d.id`
     ).all(sanitized);

package/dist/{chunk-TY472NYD.js → chunk-77IIKHQW.js}

@@ -1,6 +1,10 @@
 import {
+  assertSameSearchFields,
+  assertValidFieldWeightValues,
+  fieldWeightsFor,
+  normalizeSearchDocument,
   tokenize
-} from "./chunk-6YJ66JFO.js";
+} from "./chunk-N27Y55CA.js";
 import {
   matchesWhere
 } from "./chunk-KPMRRYTL.js";
@@ -11,21 +15,33 @@ var B = 0.75;
 var InMemorySearchStore = class {
   collections = /* @__PURE__ */ new Map();
   index(collection, doc) {
-    const coll = this.collectionFor(collection);
+    const normalized = normalizeSearchDocument(doc);
+    const coll = this.collectionFor(collection, normalized.names);
+    assertSameSearchFields(coll.fields, normalized.names, 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 tfByField = /* @__PURE__ */ new Map();
+    const terms = /* @__PURE__ */ new Set();
+    let dl = 0;
+    for (const field of coll.fields) {
+      const tokens = tokenize(normalized.values[field] ?? "");
+      dl += tokens.length;
+      const tf = /* @__PURE__ */ new Map();
+      for (const token of tokens) {
+        tf.set(token, (tf.get(token) ?? 0) + 1);
+        terms.add(token);
+      }
+      tfByField.set(field, tf);
+    }
+    coll.totalLen += dl;
     const indexed = {
       id: doc.id,
       meta: doc.meta ?? {},
-      tokens,
-      tf,
-      dl: tokens.length
+      tfByField,
+      dl,
+      terms
     };
     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);
+    for (const term of terms) coll.df.set(term, (coll.df.get(term) ?? 0) + 1);
   }
   indexMany(collection, docs) {
     for (const doc of docs) this.index(collection, doc);
@@ -38,25 +54,33 @@ var InMemorySearchStore = class {
   search(collection, query, opts) {
     const coll = this.collections.get(collection);
     const qTokens = tokenize(query);
+    assertValidFieldWeightValues(opts?.fieldWeights);
     if (!coll || qTokens.length === 0) return [];
     const limit = opts?.limit ?? 10;
     const where = opts?.filter?.where;
+    const fieldWeights = fieldWeightsFor(coll.fields, opts?.fieldWeights);
     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;
+      const avgdl = n > 0 ? coll.totalLen / n : 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;
+        if (df === 0) continue;
+        let weightedTf = 0;
+        for (let i = 0; i < coll.fields.length; i++) {
+          const field = coll.fields[i];
+          const tf = doc.tfByField.get(field)?.get(qt) ?? 0;
+          weightedTf += fieldWeights[i] * tf;
+        }
+        if (weightedTf === 0) continue;
+        matched = true;
         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;
+        const denom = weightedTf + K1 * (1 - B + B * (avgdl > 0 ? doc.dl / avgdl : 0));
+        score += idf * (weightedTf * (K1 + 1)) / denom;
       }
       if (!matched) continue;
       scored.push({ id: doc.id, score, meta: doc.meta });
@@ -69,17 +93,22 @@ var InMemorySearchStore = class {
     if (!doc) return false;
     coll.docs.delete(id);
     coll.totalLen -= doc.dl;
-    for (const term of doc.tf.keys()) {
+    for (const term of doc.terms) {
       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) {
+  collectionFor(name, fields) {
     let coll = this.collections.get(name);
     if (!coll) {
-      coll = { docs: /* @__PURE__ */ new Map(), df: /* @__PURE__ */ new Map(), totalLen: 0 };
+      coll = {
+        fields: [...fields],
+        docs: /* @__PURE__ */ new Map(),
+        df: /* @__PURE__ */ new Map(),
+        totalLen: 0
+      };
       this.collections.set(name, coll);
     }
     return coll;

package/dist/{chunk-ZI4JA6IU.js → chunk-DKCPULXT.js}

@@ -1,9 +1,16 @@
 // src/to-async.ts
+function hasListWhereIn(store) {
+  return typeof store.listWhereIn === "function";
+}
 var AsyncStoreAdapter = class {
   constructor(sync) {
     this.sync = sync;
+    if (hasListWhereIn(sync)) {
+      this.listWhereIn = async (collection, field, values, filter) => sync.listWhereIn(collection, field, values, filter);
+    }
   }
   sync;
+  listWhereIn;
   get meta() {
     return this.sync.meta;
   }
@@ -85,6 +92,16 @@ var InMemoryStore = class {
     items = applyFilter(items, filter);
     return items;
   }
+  listWhereIn(collection, field, values, filter) {
+    if (values.length === 0) return [];
+    const set = new Set(values);
+    const col = this.ensureCollection(collection);
+    const items = [...col.values()].filter((item) => {
+      if (typeof item !== "object" || item === null) return false;
+      return set.has(item[field]);
+    });
+    return applyFilter(items, filter);
+  }
   getById(collection, id) {
     const col = this.ensureCollection(collection);
     const item = col.get(id);

package/dist/chunk-N27Y55CA.js

@@ -0,0 +1,67 @@
+// 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 ");
+}
+
+// src/search/fields.ts
+var DEFAULT_SEARCH_FIELD = "text";
+function normalizeSearchDocument(doc) {
+  if (doc.text !== void 0 && doc.fields !== void 0) {
+    throw new Error("SearchDocument must provide either `text` or `fields`, not both.");
+  }
+  if (doc.text !== void 0) {
+    return { names: [DEFAULT_SEARCH_FIELD], values: { [DEFAULT_SEARCH_FIELD]: doc.text } };
+  }
+  if (doc.fields === void 0) {
+    throw new Error("SearchDocument must provide `text` or `fields`.");
+  }
+  const names = Object.keys(doc.fields).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  if (names.length === 0) throw new Error("SearchDocument.fields must contain at least one field.");
+  const values = {};
+  for (const name of names) {
+    const value = doc.fields[name];
+    if (typeof value !== "string") {
+      throw new Error(`SearchDocument field "${name}" must be a string.`);
+    }
+    values[name] = value;
+  }
+  return { names, values };
+}
+function assertSameSearchFields(existing, incoming, collection) {
+  if (existing.length !== incoming.length || existing.some((name, index) => name !== incoming[index])) {
+    throw new Error(
+      `Search collection "${collection}" was initialized with fields [${existing.join(", ")}], got [${incoming.join(", ")}].`
+    );
+  }
+}
+function assertValidFieldWeightValues(weights) {
+  for (const [field, weight] of Object.entries(weights ?? {})) {
+    if (!Number.isFinite(weight) || weight < 0) {
+      throw new Error(`Search field weight for "${field}" must be a non-negative finite number.`);
+    }
+  }
+}
+function fieldWeightsFor(fields, weights) {
+  assertValidFieldWeightValues(weights);
+  const fieldSet = new Set(fields);
+  for (const field of Object.keys(weights ?? {})) {
+    if (!fieldSet.has(field)) throw new Error(`Unknown search field weight "${field}".`);
+  }
+  return fields.map((field) => weights?.[field] ?? 1);
+}
+
+export {
+  tokenize,
+  sanitizeFtsQuery,
+  DEFAULT_SEARCH_FIELD,
+  normalizeSearchDocument,
+  assertSameSearchFields,
+  assertValidFieldWeightValues,
+  fieldWeightsFor
+};

package/dist/graph.d.ts

@@ -1,4 +1,4 @@
-import { A as AsyncStore, S as StoreFilter } from './types-DyQLNtxa.js';
+import { A as AsyncStore, S as StoreFilter } from './types-DHLdLZ_W.js';
 
 /**
  * A directed edge stored as a flat collection record. `from`/`to` are node ids,
@@ -67,5 +67,32 @@ declare function traverse(store: AsyncStore, collection: string, opts: {
     nodes: string[];
     edges: Edge[];
 }>;
+/**
+ * Frontier-IN batched BFS to `depth` hops from `start`.
+ *
+ * When the store exposes the optional `listWhereIn` capability, traversal fetches
+ * only edges adjacent to the current BFS frontier at each depth level:
+ *
+ * - "out": `from IN (frontier)`
+ * - "in": `to IN (frontier)`
+ * - "both": both queries, deduped by edge id
+ *
+ * `edgeFilter.where` is still pushed down into the same store query; the
+ * structural frontier field (`from`/`to`) overrides any same-named caller filter,
+ * matching `neighbors()`. `edgeTypes` remains in-memory because the base port has
+ * exact-match filters, not `type IN (...)`.
+ *
+ * Stores without `listWhereIn` fall back to `traverse()`'s load-once strategy.
+ */
+declare function traverseFrontierBatched(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 };
+export { type Direction, type Edge, neighbors, traverse, traverseFrontierBatched };

package/dist/graph.js

@@ -17,6 +17,28 @@ function dedupById(edges) {
 function withWhere(filter, override) {
   return { ...filter, where: { ...filter?.where, ...override } };
 }
+function withoutWhereField(filter, field) {
+  if (!filter?.where || !(field in filter.where)) return filter;
+  const where = { ...filter.where };
+  delete where[field];
+  return { ...filter, where };
+}
+function hasListWhereIn(store) {
+  return typeof store.listWhereIn === "function";
+}
+async function frontierEdges(store, collection, frontier, direction, edgeFilter) {
+  if (direction === "out") {
+    return store.listWhereIn(collection, "from", frontier, withoutWhereField(edgeFilter, "from"));
+  }
+  if (direction === "in") {
+    return store.listWhereIn(collection, "to", frontier, withoutWhereField(edgeFilter, "to"));
+  }
+  const [out, inc] = await Promise.all([
+    store.listWhereIn(collection, "from", frontier, withoutWhereField(edgeFilter, "from")),
+    store.listWhereIn(collection, "to", frontier, withoutWhereField(edgeFilter, "to"))
+  ]);
+  return dedupById([...out, ...inc]);
+}
 async function neighbors(store, collection, opts) {
   const direction = opts.direction ?? "out";
   let edges;
@@ -91,7 +113,49 @@ async function traverse(store, collection, opts) {
   traversedEdges.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
   return { nodes: reached, edges: traversedEdges };
 }
+async function traverseFrontierBatched(store, collection, opts) {
+  if (!hasListWhereIn(store)) {
+    return traverse(store, collection, opts);
+  }
+  const direction = opts.direction ?? "out";
+  if (!Number.isFinite(opts.depth) || opts.depth <= 0) {
+    return { nodes: [], edges: [] };
+  }
+  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 edges = filterByTypes(
+      await frontierEdges(store, collection, frontier, direction, opts.edgeFilter),
+      opts.edgeTypes
+    );
+    const next = [];
+    for (const node of frontier) {
+      for (const edge of edges) {
+        const adjacent = direction === "out" ? edge.from === node : direction === "in" ? edge.to === node : edge.from === node || edge.to === node;
+        if (!adjacent) continue;
+        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
+  traverse,
+  traverseFrontierBatched
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { A as AsyncStore, S as StoreFilter, a as StoreMeta, b as SyncStore } from './types-DyQLNtxa.js';
+export { A as AsyncStore, a as AsyncStoreInQuery, S as StoreFilter, b as StoreMeta, c as SyncStore, d as SyncStoreInQuery } from './types-DHLdLZ_W.js';
 export { InMemoryKv, toAsync } from './kv.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 { S as SearchDocument, a as SearchOptions, b as SearchResult, c as SearchStore } from './types-BLZTMsQO.js';
 export { InMemorySearchStore, sanitizeFtsQuery, tokenize } from './search.js';

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   InMemoryStore,
   toAsync
-} from "./chunk-ZI4JA6IU.js";
+} from "./chunk-DKCPULXT.js";
 import {
   InMemorySearchStore
-} from "./chunk-TY472NYD.js";
+} from "./chunk-77IIKHQW.js";
 import {
   InMemoryVectorStore,
   toAsyncVector
@@ -12,7 +12,7 @@ import {
 import {
   sanitizeFtsQuery,
   tokenize
-} from "./chunk-6YJ66JFO.js";
+} from "./chunk-N27Y55CA.js";
 import {
   assertDimensions,
   bufferToVector,

package/dist/kv.d.ts

@@ -1,10 +1,11 @@
-import { b as SyncStore, A as AsyncStore, a as StoreMeta, S as StoreFilter } from './types-DyQLNtxa.js';
+import { c as SyncStore, d as SyncStoreInQuery, A as AsyncStore, a as AsyncStoreInQuery, b as StoreMeta, S as StoreFilter } from './types-DHLdLZ_W.js';
 
 /** Lift a synchronous store to the {@link AsyncStore} interface. The bridge only
- *  goes this direction — sync ⊂ async. */
+ *  goes this direction — sync ⊂ async. Optional sync capabilities are lifted too. */
+declare function toAsync(store: SyncStore & SyncStoreInQuery): AsyncStore & AsyncStoreInQuery;
 declare function toAsync(store: SyncStore): AsyncStore;
 
-declare class InMemoryStore implements SyncStore {
+declare class InMemoryStore implements SyncStore, SyncStoreInQuery {
     readonly meta: StoreMeta;
     /** Key-value storage. */
     private kv;
@@ -17,6 +18,7 @@ declare class InMemoryStore implements SyncStore {
     keys(prefix?: string): string[];
     private ensureCollection;
     list<T>(collection: string, filter?: StoreFilter): T[];
+    listWhereIn<T>(collection: string, field: string, values: readonly unknown[], filter?: StoreFilter): T[];
     getById<T>(collection: string, id: string): T | null;
     put<T extends {
         id: string;
@@ -25,4 +27,4 @@ declare class InMemoryStore implements SyncStore {
     count(collection: string, filter?: StoreFilter): number;
 }
 
-export { AsyncStore, InMemoryStore as InMemoryKv, StoreFilter, StoreMeta, SyncStore, toAsync };
+export { AsyncStore, AsyncStoreInQuery, InMemoryStore as InMemoryKv, StoreFilter, StoreMeta, SyncStore, SyncStoreInQuery, toAsync };

package/dist/kv.js

@@ -1,7 +1,7 @@
 import {
   InMemoryStore,
   toAsync
-} from "./chunk-ZI4JA6IU.js";
+} from "./chunk-DKCPULXT.js";
 export {
   InMemoryStore as InMemoryKv,
   toAsync

package/dist/search.d.ts

@@ -1,6 +1,7 @@
-import { c as SearchStore, S as SearchDocument, a as SearchOptions, b as SearchResult } from './types-0B0Tw1fz.js';
+import { c as SearchStore, S as SearchDocument, a as SearchOptions, b as SearchResult } from './types-BLZTMsQO.js';
+export { d as SearchFieldDocument, e as SearchTextDocument } from './types-BLZTMsQO.js';
 export { m as matchesWhere } from './filter-B9hP-TKF.js';
-import './types-DyQLNtxa.js';
+import './types-DHLdLZ_W.js';
 
 declare class InMemorySearchStore implements SearchStore {
     private readonly collections;

package/dist/search.js

@@ -1,10 +1,10 @@
 import {
   InMemorySearchStore
-} from "./chunk-TY472NYD.js";
+} from "./chunk-77IIKHQW.js";
 import {
   sanitizeFtsQuery,
   tokenize
-} from "./chunk-6YJ66JFO.js";
+} from "./chunk-N27Y55CA.js";
 import {
   matchesWhere
 } from "./chunk-KPMRRYTL.js";

package/dist/sql.d.ts

@@ -1,4 +1,4 @@
-import { S as StoreFilter } from './types-DyQLNtxa.js';
+import { S as StoreFilter } from './types-DHLdLZ_W.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

package/dist/{types-0B0Tw1fz.d.ts → types-BLZTMsQO.d.ts}

@@ -1,23 +1,42 @@
-import { S as StoreFilter } from './types-DyQLNtxa.js';
+import { S as StoreFilter } from './types-DHLdLZ_W.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>> {
+interface SearchTextDocument<M = Record<string, unknown>> {
     /** Unique id within the collection. */
     id: string;
-    /** The text to tokenize and index. */
+    /** Single-field text to tokenize and index. Back-compat shorthand for
+     *  `fields: { text }`. */
     text: string;
+    /** Provide either `text` or `fields`, not both. */
+    fields?: never;
     /** Typed context stored alongside the text. */
     meta?: M;
 }
+interface SearchFieldDocument<M = Record<string, unknown>> {
+    /** Unique id within the collection. */
+    id: string;
+    /** Named text fields to tokenize and index with optional query-time weights
+     *  (for example `{ title, body }`). All documents in a collection must use the
+     *  same field names. */
+    fields: Record<string, string>;
+    /** Provide either `text` or `fields`, not both. */
+    text?: never;
+    /** Typed context stored alongside the text. */
+    meta?: M;
+}
+type SearchDocument<M = Record<string, unknown>> = SearchTextDocument<M> | SearchFieldDocument<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;
+    /** Per-field bm25 weights. Fields not listed default to 1. Higher means more
+     *  important; e.g. `{ title: 4, body: 1 }` boosts title matches. */
+    fieldWeights?: Record<string, number>;
 }
 /** A ranked search hit. `score` is the bm25 relevance — higher is more relevant. */
 interface SearchResult<M = Record<string, unknown>> {
@@ -30,10 +49,11 @@ interface SearchResult<M = Record<string, unknown>> {
 }
 /** 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). */
+ *  Ranking is bm25 with the FTS5 default parameters (k1 = 1.2, b = 0.75), plus
+ *  optional query-time per-field weights. 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;
@@ -46,4 +66,4 @@ interface SearchStore {
     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 };
+export type { SearchDocument as S, SearchOptions as a, SearchResult as b, SearchStore as c, SearchFieldDocument as d, SearchTextDocument as e };

package/dist/{types-DyQLNtxa.d.ts → types-DHLdLZ_W.d.ts}

@@ -20,6 +20,17 @@ interface StoreFilter {
     /** Number of results to skip. */
     offset?: number;
 }
+/** Optional collection capability for adapters that can push `field IN (...)`
+ *  down to the backing store while preserving the normal StoreFilter semantics.
+ *  Graph frontier traversal uses this when present and falls back to plain
+ *  `list()` when absent. */
+interface SyncStoreInQuery {
+    listWhereIn<T>(collection: string, field: string, values: readonly unknown[], filter?: StoreFilter): T[];
+}
+/** Async twin of SyncStoreInQuery for remote-capable stores. */
+interface AsyncStoreInQuery {
+    listWhereIn<T>(collection: string, field: string, values: readonly unknown[], filter?: StoreFilter): Promise<T[]>;
+}
 /**
  * A typed key-value + collection store. **Synchronous.**
  *
@@ -80,4 +91,4 @@ interface AsyncStore {
     count(collection: string, filter?: StoreFilter): Promise<number>;
 }
 
-export type { AsyncStore as A, StoreFilter as S, StoreMeta as a, SyncStore as b };
+export type { AsyncStore as A, StoreFilter as S, AsyncStoreInQuery as a, StoreMeta as b, SyncStore as c, SyncStoreInQuery as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirk/store",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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",
@@ -59,12 +59,6 @@
   "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"
@@ -88,5 +82,11 @@
   "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/search.ts src/graph.ts src/sql.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
   }
-}
+}

package/dist/chunk-6YJ66JFO.js

@@ -1,15 +0,0 @@
-// 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
-};