@noir-ai/store 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agaaaptr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @noir-ai/store
+
+Embedded storage for Noir: `better-sqlite3` + FTS5 (BM25 ranking with window snippets) + `sqlite-vec` (384-dimensional vector kNN). The daemon owns the single write handle; a read-only filesystem fallback covers the daemon-down case. The `ProjectId`-keyed database lives at `.noir/store/<projectId>.db`.
+
+Part of the **[Noir](https://github.com/agaaaptr/noir#readme)** toolkit — the discipline, context, and memory layer for any agentic CLI.
+
+## Install
+
+```bash
+npm install @noir-ai/store
+```
+
+> Most users install the CLI instead, which pulls in the packages it needs:
+>
+> ```bash
+> npm install -g @noir-ai/cli
+> ```
+
+## License
+
+MIT © agaaaptr

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import Database from 'better-sqlite3';
+import { ProjectId } from '@noir-ai/core';
+
+/**
+ * Hand-rolled versioned-SQL migration runner.
+ *
+ * Idempotent: tracks applied versions in a `schema_version` table and only runs
+ * each migration once. Each migration is applied in its own transaction; on
+ * failure the transaction is rolled back and the error re-thrown.
+ */
+declare function migrate(db: Database.Database): void;
+
+interface OpenOptions {
+    projectId: ProjectId;
+    root: string;
+    readonly?: boolean;
+}
+interface FtsHit {
+    id: string;
+    source: string;
+    score: number;
+    snippet: string;
+    meta?: unknown;
+}
+interface VecHit {
+    id: string;
+    source: string;
+    score: number;
+    meta?: unknown;
+}
+type EmbedFn = (text: string) => Promise<Float32Array>;
+/** Input to {@link Store.indexDoc}: an upsertable document. */
+interface IndexDoc {
+    id: string;
+    source: string;
+    content: string;
+    meta?: unknown;
+}
+/** Optional filters/cap for {@link Store.searchFt}. */
+interface SearchFtOpts {
+    /** Maximum number of hits to return (default 10). */
+    limit?: number;
+    /** Restrict results to a single source. */
+    source?: string;
+}
+/** Metadata accepted by {@link Store.upsertVec}. */
+interface VecUpsertMeta {
+    /** Logical source bucket for the vector (default `'default'`). */
+    source?: string;
+}
+/** Optional filters/cap for {@link Store.knn}. */
+interface VecOpts {
+    /** Maximum number of neighbors to return (default 5). */
+    limit?: number;
+    /** Restrict results to a single source bucket (applied at kNN scan time). */
+    source?: string;
+}
+interface Store {
+    readonly projectId: ProjectId;
+    getState<T>(key: string): T | null;
+    setState<T>(key: string, value: T): void;
+    /** Upsert a document into the `docs` table (FTS sync is automatic via triggers). */
+    indexDoc(doc: IndexDoc): void;
+    /** Delete a document row by id; FTS cleanup is automatic via the `docs_ad` trigger. */
+    deleteDoc(id: string): void;
+    /** BM25 full-text search with window-extracted snippets. */
+    searchFt(query: string, opts?: SearchFtOpts): FtsHit[];
+    /** Upsert a 384-dim vector keyed by `id` (idempotent; delete-by-id-then-insert). */
+    upsertVec(id: string, vec: Float32Array, meta?: VecUpsertMeta): void;
+    /** Delete a vector row by id (idempotent; used by the context indexer for removals). */
+    deleteVec(id: string): void;
+    /** k-nearest-neighbor search over `vec`; results ordered by ascending distance. */
+    knn(vec: Float32Array, opts?: VecOpts): VecHit[];
+    /** Count rows in the `docs` table (live read from the single writer handle). */
+    countDocs(): number;
+    /** Count rows in the `vec` table (live read from the single writer handle). */
+    countVecs(): number;
+    /** Export all `docs` rows to `<dir>/<id>.md` with YAML frontmatter. */
+    exportMarkdown(dir: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * Open (or create) the project's embedded SQLite store at
+ * `.noir/store/<projectId>.db`.
+ *
+ * `sqlite-vec` is loaded into every connection (read-safe) so kNN queries work
+ * in both read-write and read-only modes. In read-write mode the schema is
+ * migrated to the latest version, WAL journaling is enabled, and the `vec0`
+ * virtual table (deferred from v1 because `vec0` requires the extension
+ * loaded) is created. In read-only mode none of those writes happen; callers
+ * get a best-effort read handle against whatever schema already exists on
+ * disk — kNN works if the `vec` table was created by a prior read-write open,
+ * otherwise queries fail clearly against the missing table.
+ *
+ * `__db` is exposed for tests to assert schema state directly.
+ */
+declare function openStore(opts: OpenOptions): Promise<Store & {
+    __db: Database.Database;
+}>;
+
+type VecAvailability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Probe sqlite-vec native availability ONCE (memoized). Returns `{ ok: true }`
+ * when the binary loads, else `{ ok: false, reason }`. Use to gate vec-backed
+ * test suites (`describe.skip` on absence) so the default suite stays green
+ * offline on an unsupported platform.
+ */
+declare function vecAvailability(): VecAvailability;
+
+export { type EmbedFn, type FtsHit, type IndexDoc, type OpenOptions, type SearchFtOpts, type Store, type VecAvailability, type VecHit, type VecOpts, type VecUpsertMeta, migrate, openStore, vecAvailability };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/migrations.ts
+var V1_SQL = (
+  /* sql */
+  `
+CREATE TABLE IF NOT EXISTS kv (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS docs (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  content TEXT NOT NULL,
+  meta TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+  content,
+  content='docs',
+  content_rowid='rowid',
+  tokenize='porter unicode61'
+);
+
+-- keep docs_fts in sync with docs (external-content sync triggers:
+-- the 'delete' command requires content='docs' above to function)
+CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
+  INSERT INTO docs_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
+  INSERT INTO docs_fts(docs_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
+  INSERT INTO docs_fts(docs_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+  INSERT INTO docs_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+`
+);
+var migrations = [{ version: 1, sql: V1_SQL }];
+function migrate(db) {
+  db.exec("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY);");
+  const applied = new Set(
+    db.prepare("SELECT version FROM schema_version").all().map((r) => r.version)
+  );
+  for (const m of migrations) {
+    if (applied.has(m.version)) continue;
+    db.exec("BEGIN");
+    try {
+      db.exec(m.sql);
+      db.prepare("INSERT INTO schema_version(version) VALUES (?)").run(m.version);
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+}
+
+// src/sqlite-store.ts
+import { mkdirSync } from "fs";
+import { paths } from "@noir-ai/core";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+
+// src/markdown.ts
+import { writeFileSync } from "fs";
+import { join } from "path";
+async function exportMarkdown(db, dir) {
+  const rows = db.prepare("SELECT id, source, content FROM docs").all();
+  const written = [];
+  for (const r of rows) {
+    const p = join(dir, `${r.id}.md`);
+    writeFileSync(p, `---
+id: ${r.id}
+source: ${r.source}
+---
+
+${r.content}
+`, "utf8");
+    written.push(p);
+  }
+  return written;
+}
+
+// src/sqlite-store.ts
+async function openStore(opts) {
+  const projectId = opts.projectId;
+  const dbPath = paths.storeDb(opts.root, projectId);
+  if (opts.readonly !== true) {
+    mkdirSync(paths.storeDir(opts.root), { recursive: true });
+  }
+  const db = new Database(dbPath, { readonly: opts.readonly === true });
+  sqliteVec.load(db);
+  if (opts.readonly !== true) {
+    db.pragma("journal_mode = WAL");
+    migrate(db);
+    db.exec(
+      "CREATE VIRTUAL TABLE IF NOT EXISTS vec USING vec0(embedding float[384], source TEXT, id TEXT)"
+    );
+  }
+  const readonly = opts.readonly === true;
+  const getState = (key) => {
+    const row = db.prepare("SELECT value FROM kv WHERE key = ?").get(key);
+    return row ? JSON.parse(row.value) : null;
+  };
+  const setState = (key, value) => {
+    if (readonly) {
+      throw new Error("store is read-only (daemon down)");
+    }
+    db.prepare(
+      "INSERT INTO kv(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value"
+    ).run(key, JSON.stringify(value));
+  };
+  const indexDoc = (doc) => {
+    if (readonly) {
+      throw new Error("store is read-only (daemon down)");
+    }
+    db.prepare(
+      "INSERT INTO docs(id, source, content, meta) VALUES(?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET source=excluded.source, content=excluded.content, meta=excluded.meta"
+    ).run(doc.id, doc.source, doc.content, doc.meta ? JSON.stringify(doc.meta) : null);
+  };
+  const deleteDoc = (id) => {
+    if (readonly) {
+      throw new Error("store is read-only (daemon down)");
+    }
+    db.prepare("DELETE FROM docs WHERE id = ?").run(id);
+  };
+  const searchFt = (query, opts2) => {
+    const limit = opts2?.limit ?? 10;
+    const source = opts2?.source;
+    const sql = source ? `SELECT d.id AS id, d.source AS source, d.meta AS meta, bm25(docs_fts) AS score,
+                snippet(docs_fts, 0, '<<', '>>', '\u2026', 16) AS snippet
+         FROM docs_fts JOIN docs d ON d.rowid = docs_fts.rowid
+         WHERE docs_fts MATCH ? AND d.source = ?
+         ORDER BY score LIMIT ?` : `SELECT d.id AS id, d.source AS source, d.meta AS meta, bm25(docs_fts) AS score,
+                snippet(docs_fts, 0, '<<', '>>', '\u2026', 16) AS snippet
+         FROM docs_fts JOIN docs d ON d.rowid = docs_fts.rowid
+         WHERE docs_fts MATCH ?
+         ORDER BY score LIMIT ?`;
+    const rows = source ? db.prepare(sql).all(query, source, limit) : db.prepare(sql).all(query, limit);
+    return rows.map((r) => ({
+      id: r.id,
+      source: r.source,
+      score: r.score,
+      snippet: r.snippet,
+      ...r.meta ? { meta: JSON.parse(r.meta) } : {}
+    }));
+  };
+  const upsertVec = (id, vec, meta) => {
+    if (readonly) {
+      throw new Error("store is read-only (daemon down)");
+    }
+    const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+    const source = meta?.source ?? "default";
+    const upsert = db.transaction(() => {
+      db.prepare("DELETE FROM vec WHERE id = ?").run(id);
+      db.prepare("INSERT INTO vec(embedding, source, id) VALUES (?, ?, ?)").run(buf, source, id);
+    });
+    upsert();
+  };
+  const deleteVec = (id) => {
+    if (readonly) {
+      throw new Error("store is read-only (daemon down)");
+    }
+    db.prepare("DELETE FROM vec WHERE id = ?").run(id);
+  };
+  const knn = (vec, opts2) => {
+    const limit = opts2?.limit ?? 5;
+    const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+    const source = opts2?.source;
+    const sql = source ? "SELECT id, source, distance FROM vec WHERE embedding MATCH ? AND k = ? AND source = ? ORDER BY distance" : "SELECT id, source, distance FROM vec WHERE embedding MATCH ? AND k = ? ORDER BY distance";
+    const rows = source ? db.prepare(sql).all(buf, limit, source) : db.prepare(sql).all(buf, limit);
+    return rows.map((r) => ({ id: r.id, source: r.source, score: r.distance }));
+  };
+  const countDocs = () => db.prepare("SELECT count(*) AS c FROM docs").get().c;
+  const countVecs = () => db.prepare("SELECT count(*) AS c FROM vec").get().c;
+  return {
+    projectId,
+    __db: db,
+    getState,
+    setState,
+    indexDoc,
+    deleteDoc,
+    searchFt,
+    upsertVec,
+    deleteVec,
+    knn,
+    countDocs,
+    countVecs,
+    exportMarkdown: (dir) => exportMarkdown(db, dir),
+    close: async () => {
+      db.close();
+    }
+  };
+}
+
+// src/vec-probe.ts
+import Database2 from "better-sqlite3";
+import * as sqliteVec2 from "sqlite-vec";
+var cached;
+function vecAvailability() {
+  if (cached) return cached;
+  try {
+    const probe = new Database2(":memory:");
+    sqliteVec2.load(probe);
+    probe.close();
+    cached = { ok: true };
+  } catch (e) {
+    cached = { ok: false, reason: e instanceof Error ? e.message : String(e) };
+  }
+  return cached;
+}
+export {
+  migrate,
+  openStore,
+  vecAvailability
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/migrations.ts","../src/sqlite-store.ts","../src/markdown.ts","../src/vec-probe.ts"],"sourcesContent":["import type Database from 'better-sqlite3';\n\n/**\n * Schema v1.\n *\n * NOTE on packaging: the v1 SQL is inlined here as a TS string (rather than\n * shipped as a separate `sql/v1.sql` resolved via `import.meta.url`) because\n * the installed tsup (8.5.1) exposes no `copy: { items: [...] }` option, only\n * `publicDir`. Inlining avoids all file-resolution concerns across src/dist and\n * keeps the schema the single source of truth right next to the runner.\n *\n * NOTE on `vec`: the `vec0` virtual table requires the `sqlite-vec` extension\n * to be loaded into the connection, which T1 does NOT do. Its DDL is therefore\n * intentionally omitted from v1 and will be added in T4 (via a v2 migration or\n * a load-time create once `sqliteVec.load(db)` runs).\n */\nconst V1_SQL = /* sql */ `\nCREATE TABLE IF NOT EXISTS kv (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS docs (\n  id TEXT PRIMARY KEY,\n  source TEXT NOT NULL,\n  content TEXT NOT NULL,\n  meta TEXT\n);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(\n  content,\n  content='docs',\n  content_rowid='rowid',\n  tokenize='porter unicode61'\n);\n\n-- keep docs_fts in sync with docs (external-content sync triggers:\n-- the 'delete' command requires content='docs' above to function)\nCREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN\n  INSERT INTO docs_fts(rowid, content) VALUES (new.rowid, new.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN\n  INSERT INTO docs_fts(docs_fts, rowid, content) VALUES ('delete', old.rowid, old.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN\n  INSERT INTO docs_fts(docs_fts, rowid, content) VALUES ('delete', old.rowid, old.content);\n  INSERT INTO docs_fts(rowid, content) VALUES (new.rowid, new.content);\nEND;\n`;\n\ninterface Migration {\n  version: number;\n  sql: string;\n}\n\n/** Ordered migrations. v1 is the initial schema. */\nconst migrations: Migration[] = [{ version: 1, sql: V1_SQL }];\n\n/**\n * Hand-rolled versioned-SQL migration runner.\n *\n * Idempotent: tracks applied versions in a `schema_version` table and only runs\n * each migration once. Each migration is applied in its own transaction; on\n * failure the transaction is rolled back and the error re-thrown.\n */\nexport function migrate(db: Database.Database): void {\n  db.exec('CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY);');\n\n  const applied = new Set(\n    db\n      .prepare('SELECT version FROM schema_version')\n      .all()\n      .map((r) => (r as { version: number }).version),\n  );\n\n  for (const m of migrations) {\n    if (applied.has(m.version)) continue;\n    db.exec('BEGIN');\n    try {\n      db.exec(m.sql);\n      db.prepare('INSERT INTO schema_version(version) VALUES (?)').run(m.version);\n      db.exec('COMMIT');\n    } catch (e) {\n      db.exec('ROLLBACK');\n      throw e;\n    }\n  }\n}\n","import { mkdirSync } from 'node:fs';\nimport { type ProjectId, paths } from '@noir-ai/core';\nimport Database from 'better-sqlite3';\nimport * as sqliteVec from 'sqlite-vec';\nimport { exportMarkdown } from './markdown.js';\nimport { migrate } from './migrations.js';\nimport type {\n  FtsHit,\n  IndexDoc,\n  OpenOptions,\n  SearchFtOpts,\n  Store,\n  VecHit,\n  VecOpts,\n  VecUpsertMeta,\n} from './types.js';\n\n/** Internal row shape from the docs_fts JOIN docs query. */\ninterface FtsRow {\n  id: string;\n  source: string;\n  meta: string | null;\n  score: number;\n  snippet: string;\n}\n\n/** Internal row shape from the vec0 kNN query. */\ninterface VecRow {\n  id: string;\n  source: string;\n  distance: number;\n}\n\n/**\n * Open (or create) the project's embedded SQLite store at\n * `.noir/store/<projectId>.db`.\n *\n * `sqlite-vec` is loaded into every connection (read-safe) so kNN queries work\n * in both read-write and read-only modes. In read-write mode the schema is\n * migrated to the latest version, WAL journaling is enabled, and the `vec0`\n * virtual table (deferred from v1 because `vec0` requires the extension\n * loaded) is created. In read-only mode none of those writes happen; callers\n * get a best-effort read handle against whatever schema already exists on\n * disk — kNN works if the `vec` table was created by a prior read-write open,\n * otherwise queries fail clearly against the missing table.\n *\n * `__db` is exposed for tests to assert schema state directly.\n */\nexport async function openStore(opts: OpenOptions): Promise<Store & { __db: Database.Database }> {\n  const projectId: ProjectId = opts.projectId;\n  const dbPath = paths.storeDb(opts.root, projectId);\n  if (opts.readonly !== true) {\n    mkdirSync(paths.storeDir(opts.root), { recursive: true });\n  }\n\n  const db = new Database(dbPath, { readonly: opts.readonly === true });\n\n  // Load sqlite-vec first (read-safe; needed for kNN in either mode).\n  sqliteVec.load(db);\n\n  if (opts.readonly !== true) {\n    db.pragma('journal_mode = WAL');\n    migrate(db);\n    // vec0 DDL deferred from v1: vec0 requires the sqlite-vec extension to be\n    // loaded (done above). `source`/`id` are metadata columns — filterable in\n    // kNN (`source = ?`) and deletable for idempotent upsert (`id = ?`). vec0\n    // keys on rowid (auto-assigned); there is no text primary key.\n    db.exec(\n      'CREATE VIRTUAL TABLE IF NOT EXISTS vec USING vec0(embedding float[384], source TEXT, id TEXT)',\n    );\n  }\n  // read-only: do not write. If the schema is missing, queries simply fail —\n  // acceptable for degraded reads (e.g. inspecting a foreign DB).\n\n  const readonly = opts.readonly === true;\n\n  const getState = <T>(key: string): T | null => {\n    const row = db.prepare('SELECT value FROM kv WHERE key = ?').get(key) as\n      | { value: string }\n      | undefined;\n    return row ? (JSON.parse(row.value) as T) : null;\n  };\n\n  const setState = <T>(key: string, value: T): void => {\n    if (readonly) {\n      throw new Error('store is read-only (daemon down)');\n    }\n    db.prepare(\n      'INSERT INTO kv(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',\n    ).run(key, JSON.stringify(value));\n  };\n\n  const indexDoc = (doc: IndexDoc): void => {\n    if (readonly) {\n      throw new Error('store is read-only (daemon down)');\n    }\n    // Upsert into docs; the docs_ai/docs_au triggers keep docs_fts in sync.\n    db.prepare(\n      'INSERT INTO docs(id, source, content, meta) VALUES(?, ?, ?, ?) ' +\n        'ON CONFLICT(id) DO UPDATE SET source=excluded.source, content=excluded.content, meta=excluded.meta',\n    ).run(doc.id, doc.source, doc.content, doc.meta ? JSON.stringify(doc.meta) : null);\n  };\n\n  const deleteDoc = (id: string): void => {\n    if (readonly) {\n      throw new Error('store is read-only (daemon down)');\n    }\n    // The docs_ad AFTER DELETE trigger replays the row into docs_fts as a\n    // 'delete' command (external-content sync, see migrations.ts), keeping the\n    // FTS index consistent — no manual docs_fts work needed here.\n    db.prepare('DELETE FROM docs WHERE id = ?').run(id);\n  };\n\n  const searchFt = (query: string, opts?: SearchFtOpts): FtsHit[] => {\n    const limit = opts?.limit ?? 10;\n    // bm25(): more negative = more relevant, so ORDER BY score ascending.\n    // snippet(docs_fts, 0, ...): column 0 is `content`; 16-token window with\n    // <<match>> markers — NEVER the full content (blueprint §9.2).\n    const source = opts?.source;\n    const sql = source\n      ? `SELECT d.id AS id, d.source AS source, d.meta AS meta, bm25(docs_fts) AS score,\n                snippet(docs_fts, 0, '<<', '>>', '…', 16) AS snippet\n         FROM docs_fts JOIN docs d ON d.rowid = docs_fts.rowid\n         WHERE docs_fts MATCH ? AND d.source = ?\n         ORDER BY score LIMIT ?`\n      : `SELECT d.id AS id, d.source AS source, d.meta AS meta, bm25(docs_fts) AS score,\n                snippet(docs_fts, 0, '<<', '>>', '…', 16) AS snippet\n         FROM docs_fts JOIN docs d ON d.rowid = docs_fts.rowid\n         WHERE docs_fts MATCH ?\n         ORDER BY score LIMIT ?`;\n    const rows = source\n      ? (db.prepare(sql).all(query, source, limit) as FtsRow[])\n      : (db.prepare(sql).all(query, limit) as FtsRow[]);\n    return rows.map((r) => ({\n      id: r.id,\n      source: r.source,\n      score: r.score,\n      snippet: r.snippet,\n      ...(r.meta ? { meta: JSON.parse(r.meta) } : {}),\n    }));\n  };\n\n  const upsertVec = (id: string, vec: Float32Array, meta?: VecUpsertMeta): void => {\n    if (readonly) {\n      throw new Error('store is read-only (daemon down)');\n    }\n    // Account for Float32Array views (byteOffset/byteLength) so a subarray\n    // binds exactly its own bytes, not the whole backing ArrayBuffer.\n    const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);\n    const source = meta?.source ?? 'default';\n    // vec0 keys on rowid; `id` is a metadata column. Idempotent via\n    // delete-by-id-then-insert (both are filterable metadata ops) in one txn.\n    const upsert = db.transaction(() => {\n      db.prepare('DELETE FROM vec WHERE id = ?').run(id);\n      db.prepare('INSERT INTO vec(embedding, source, id) VALUES (?, ?, ?)').run(buf, source, id);\n    });\n    upsert();\n  };\n\n  const deleteVec = (id: string): void => {\n    if (readonly) {\n      throw new Error('store is read-only (daemon down)');\n    }\n    // vec0 keys on rowid; `id` is a filterable metadata column, so delete-by-id\n    // is a plain metadata predicate (same one upsertVec uses for idempotency).\n    db.prepare('DELETE FROM vec WHERE id = ?').run(id);\n  };\n\n  const knn = (vec: Float32Array, opts?: VecOpts): VecHit[] => {\n    const limit = opts?.limit ?? 5;\n    const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);\n    // `MATCH ? AND k = ?` is the canonical vec0 kNN form (version-independent;\n    // `ORDER BY distance` is ascending by default — nearest first). distance is\n    // L2, so lower == more similar; we mirror it onto `score` to match the FTS\n    // convention where lower bm25 == more relevant.\n    const source = opts?.source;\n    const sql = source\n      ? 'SELECT id, source, distance FROM vec WHERE embedding MATCH ? AND k = ? AND source = ? ORDER BY distance'\n      : 'SELECT id, source, distance FROM vec WHERE embedding MATCH ? AND k = ? ORDER BY distance';\n    const rows = source\n      ? (db.prepare(sql).all(buf, limit, source) as VecRow[])\n      : (db.prepare(sql).all(buf, limit) as VecRow[]);\n    return rows.map((r) => ({ id: r.id, source: r.source, score: r.distance }));\n  };\n\n  const countDocs = (): number =>\n    (db.prepare('SELECT count(*) AS c FROM docs').get() as { c: number }).c;\n\n  const countVecs = (): number =>\n    (db.prepare('SELECT count(*) AS c FROM vec').get() as { c: number }).c;\n\n  return {\n    projectId,\n    __db: db,\n    getState,\n    setState,\n    indexDoc,\n    deleteDoc,\n    searchFt,\n    upsertVec,\n    deleteVec,\n    knn,\n    countDocs,\n    countVecs,\n    exportMarkdown: (dir: string) => exportMarkdown(db, dir),\n    close: async () => {\n      db.close();\n    },\n  };\n}\n","import { writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type Database from 'better-sqlite3';\n\n/**\n * Export all documents from the `docs` table to markdown files.\n *\n * Each document is written to `<dir>/<id>.md` with YAML frontmatter\n * containing `id` and `source`, followed by the document content.\n *\n * @param db - The SQLite database connection.\n * @param dir - The directory to write markdown files to.\n * @returns Array of written file paths.\n */\nexport async function exportMarkdown(db: Database.Database, dir: string): Promise<string[]> {\n  const rows = db.prepare('SELECT id, source, content FROM docs').all() as {\n    id: string;\n    source: string;\n    content: string;\n  }[];\n  const written: string[] = [];\n  for (const r of rows) {\n    const p = join(dir, `${r.id}.md`);\n    writeFileSync(p, `---\\nid: ${r.id}\\nsource: ${r.source}\\n---\\n\\n${r.content}\\n`, 'utf8');\n    written.push(p);\n  }\n  return written;\n}\n","// Centralized sqlite-vec native-binary availability probe.\n//\n// sqlite-vec ships a per-platform native binary that the store loads into every\n// connection at open time. When the binary is missing/broken on a host, store\n// open and any vec operation throw. Workspace packages that consume the store\n// (context, daemon, …) need to gate their vec-backed test suites on this — but\n// they MUST NOT import `better-sqlite3` / `sqlite-vec` directly: those are the\n// store's own dependencies and are not resolvable from other packages under\n// pnpm's strict node_modules. This module is the single place that touches the\n// native modules; everyone else asks the store via `vecAvailability()`.\n\nimport Database from 'better-sqlite3';\nimport * as sqliteVec from 'sqlite-vec';\n\nexport type VecAvailability = { ok: true } | { ok: false; reason: string };\n\nlet cached: VecAvailability | undefined;\n\n/**\n * Probe sqlite-vec native availability ONCE (memoized). Returns `{ ok: true }`\n * when the binary loads, else `{ ok: false, reason }`. Use to gate vec-backed\n * test suites (`describe.skip` on absence) so the default suite stays green\n * offline on an unsupported platform.\n */\nexport function vecAvailability(): VecAvailability {\n  if (cached) return cached;\n  try {\n    const probe = new Database(':memory:');\n    sqliteVec.load(probe);\n    probe.close();\n    cached = { ok: true };\n  } catch (e) {\n    cached = { ok: false, reason: e instanceof Error ? e.message : String(e) };\n  }\n  return cached;\n}\n"],"mappings":"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","names":["opts","Database","sqliteVec"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@noir-ai/store",
+  "version": "1.0.0-beta.1",
+  "description": "Noir store — embedded storage: better-sqlite3 + FTS5 (BM25, window snippets) + sqlite-vec (384-dim kNN).",
+  "license": "MIT",
+  "author": "agaaaptr",
+  "homepage": "https://github.com/agaaaptr/noir#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agaaaptr/noir.git",
+    "directory": "packages/store"
+  },
+  "bugs": {
+    "url": "https://github.com/agaaaptr/noir/issues"
+  },
+  "keywords": [
+    "noir",
+    "sqlite",
+    "fts5",
+    "vector",
+    "sqlite-vec",
+    "embeddings",
+    "persistence"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.0.0",
+    "sqlite-vec": "^0.1.0",
+    "@noir-ai/core": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^26.1.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}