@pella-labs/pinakes 0.1.0

package/dist/db/client.js

@@ -0,0 +1,175 @@
+import { mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+import * as sqliteVec from 'sqlite-vec';
+import { logger } from '../observability/logger.js';
+import * as schema from './schema.js';
+// ----------------------------------------------------------------------------
+// SQLite version check (presearch D18)
+// ----------------------------------------------------------------------------
+/** SQLite versions known to have an FTS5 regression — never use these. */
+const FORBIDDEN_SQLITE_VERSIONS = ['3.51.0'];
+/**
+ * The minimum acceptable SQLite version. better-sqlite3@12.8.0 bundles
+ * 3.51.3 which is fine. Anything older than 3.50.4 is rejected because
+ * older versions miss FTS5 features we rely on; anything in the 3.51.0-3.51.2
+ * range is rejected due to the FTS5 regression.
+ *
+ * The check is: version === '3.50.4' OR version >= '3.51.3'.
+ */
+function isAllowedSqliteVersion(version) {
+    if (FORBIDDEN_SQLITE_VERSIONS.includes(version)) {
+        return false;
+    }
+    if (version === '3.50.4')
+        return true;
+    // Lexicographic compare works for 3-component semver where each component
+    // is the same width — but SQLite versions are not zero-padded, so we
+    // parse and compare numerically.
+    const parts = version.split('.').map((p) => parseInt(p, 10));
+    if (parts.length !== 3 || parts.some((n) => Number.isNaN(n)))
+        return false;
+    const [major, minor, patch] = parts;
+    if (major > 3)
+        return true;
+    if (major < 3)
+        return false;
+    if (minor > 51)
+        return true;
+    if (minor < 50)
+        return false;
+    if (minor === 50)
+        return patch >= 4;
+    // minor === 51
+    return patch >= 3;
+}
+// ----------------------------------------------------------------------------
+// Pragmas — applied on every connection (writer + readers)
+// ----------------------------------------------------------------------------
+/**
+ * The 6 mandatory pragmas, applied on every fresh connection. Order matters
+ * for `journal_mode=WAL` (must run before any read/write). `cache_size=-20000`
+ * is in KB units (negative = KB instead of pages); presearch §Performance
+ * settled on 20MB per connection.
+ */
+function applyPragmas(db) {
+    db.pragma('journal_mode = WAL');
+    db.pragma('busy_timeout = 5000');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('foreign_keys = ON');
+    db.pragma('cache_size = -20000');
+    db.pragma('temp_store = MEMORY');
+}
+/**
+ * Load the sqlite-vec extension on a connection. Must be called BEFORE any
+ * query that touches `kg_chunks_vec`, including the migration that creates
+ * the virtual table.
+ *
+ * better-sqlite3 disables loadExtension() by default; we re-enable it on
+ * the specific connection only and load the bundled extension shipped by
+ * the sqlite-vec npm package (no system install required).
+ */
+function loadSqliteVec(db) {
+    // Re-enable extension loading for this connection only.
+    db.loadExtension(sqliteVec.getLoadablePath());
+}
+// ----------------------------------------------------------------------------
+// Migrations (drizzle-kit output, applied via drizzle's migrate())
+// ----------------------------------------------------------------------------
+/**
+ * The migrations directory, resolved relative to this file. Works under both
+ * tsx (ESM source) and post-build (compiled dist/) by using import.meta.url.
+ */
+const MIGRATIONS_FOLDER = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, './migrations');
+})();
+export function openDb(path, options = {}) {
+    const runMigrations = options.runMigrations ?? true;
+    const absPath = resolve(path);
+    // Step 1: ensure parent dir exists. better-sqlite3 will create the file
+    // itself but won't `mkdir -p` for the directory.
+    mkdirSync(dirname(absPath), { recursive: true });
+    // Step 2: open one writer + two readers.
+    const writer = new Database(absPath);
+    const readers = [new Database(absPath, { readonly: true }), new Database(absPath, { readonly: true })];
+    // Step 3 + 4: pragmas + sqlite-vec on every connection.
+    for (const conn of [writer, ...readers]) {
+        applyPragmas(conn);
+        loadSqliteVec(conn);
+    }
+    // Step 5: SQLite version check. Done after pragmas so any error message
+    // includes a sane connection state.
+    const versionRow = writer.prepare('SELECT sqlite_version() AS v').get();
+    if (!isAllowedSqliteVersion(versionRow.v)) {
+        // Clean up before throwing so we don't leak file handles.
+        closeDb({ path: absPath, writer, readers, drizzleWriter: drizzle(writer, { schema }) });
+        throw new Error(`SQLite version ${versionRow.v} is not allowed for KG-MCP — requires 3.50.4 or >=3.51.3 (presearch D18). ` +
+            `better-sqlite3@12.8.0 bundles 3.51.3; if you see this, your better-sqlite3 was compiled against the system sqlite.`);
+    }
+    // Build the drizzle wrapper before step 6 so migrate() can use it.
+    const drizzleWriter = drizzle(writer, { schema });
+    // Step 6: run migrations. drizzle's migrate() is idempotent — it tracks
+    // applied migrations in `__drizzle_migrations` and only runs new ones.
+    if (runMigrations) {
+        migrate(drizzleWriter, { migrationsFolder: MIGRATIONS_FOLDER });
+    }
+    // Step 7: stamp schema_version=1 if absent. Subsequent phases bump this.
+    if (runMigrations) {
+        writer
+            .prepare('INSERT OR IGNORE INTO kg_meta (key, value) VALUES (?, ?)')
+            .run('schema_version', '2');
+    }
+    logger.info({ path: absPath, sqliteVersion: versionRow.v }, 'opened SQLite db');
+    return { path: absPath, writer, readers, drizzleWriter };
+}
+/**
+ * Close every connection in a bundle. Idempotent — safe to call twice.
+ * Logs at debug level so the production stdio path stays quiet on shutdown.
+ */
+export function closeDb(bundle) {
+    try {
+        if (bundle.writer.open)
+            bundle.writer.close();
+    }
+    catch (err) {
+        logger.warn({ err }, 'error closing writer');
+    }
+    for (const reader of bundle.readers) {
+        try {
+            if (reader.open)
+                reader.close();
+        }
+        catch (err) {
+            logger.warn({ err }, 'error closing reader');
+        }
+    }
+    logger.debug({ path: bundle.path }, 'closed SQLite db');
+}
+// ----------------------------------------------------------------------------
+// Reader pool helper
+// ----------------------------------------------------------------------------
+/**
+ * Round-robin reader picker. Repository methods call this to spread queries
+ * across the read pool. Stateless function — caller passes a counter (or
+ * the bundle itself if it doesn't care about even distribution).
+ */
+let readerCursor = 0;
+export function nextReader(bundle) {
+    const idx = readerCursor++ % bundle.readers.length;
+    return bundle.readers[idx];
+}
+// ----------------------------------------------------------------------------
+// Test helpers (exported for use in __tests__/)
+// ----------------------------------------------------------------------------
+/** Exposed for schema.test.ts to verify the version-check rule directly. */
+export const __test = {
+    isAllowedSqliteVersion,
+    applyPragmas,
+    loadSqliteVec,
+    MIGRATIONS_FOLDER,
+};
+//# sourceMappingURL=client.js.map

package/dist/db/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/db/client.ts"],"names":[],"mappings":"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"}

package/dist/db/repository.d.ts

@@ -0,0 +1,82 @@
+import type { Chunk } from './types.js';
+import { type DbBundle } from './client.js';
+/**
+ * The repository is the seam between the tool handlers and the SQLite
+ * storage layer. Phase 1 used an in-memory `MemoryStore` directly; Phase 2
+ * swaps in this `Repository` without changing what the tool handlers see.
+ *
+ * **Method shapes mirror MemoryStore exactly** so the swap in Pass 4 is a
+ * one-line rename in each handler. `search()` returns the same `Chunk`
+ * shape and the same insertion-order semantics; `get()` returns the same
+ * `Chunk | null`.
+ *
+ * **Query implementation: LIKE, not FTS5.** Phase 2 stops short of the
+ * FTS5+RRF query path — that lands in Phase 4. Two reasons:
+ *   1. The Phase 1 spike tests use substring queries (e.g. "hashPassword")
+ *      and assert ≥1 result; FTS5's tokenizer would split on case
+ *      boundaries differently and may break those assertions.
+ *   2. The FTS5 virtual table is *populated* in Phase 2 (via the migration's
+ *      triggers) so Phase 4 only has to swap the WHERE clause — the data is
+ *      already indexed.
+ *
+ * **Scope routing**: the data plane supports both `project` and `personal`
+ * (separate DB bundles, separate manifests). The Phase 5 privacy invariant
+ * gate lives in the tool handlers, not here — repository methods accept
+ * a scope param and route to the matching bundle. If a personal bundle
+ * isn't loaded, personal-scope reads return empty / null. The 15-test
+ * privacy adversarial suite is a Phase 5 deliverable; Phase 2 keeps the
+ * existing tool-handler gate that rejects personal-scope tool calls.
+ *
+ * **Single writer / multi reader**: writes go through `bundle.writer`;
+ * reads go through round-robin `nextReader(bundle)`. Repository.search/get
+ * are read-only and use the read pool.
+ */
+export declare class Repository {
+    private readonly project;
+    private readonly personal;
+    constructor(project: DbBundle, personal?: DbBundle | null);
+    /**
+     * Resolve the bundle for a given scope. Returns null for `'personal'`
+     * if no personal bundle was provided (so callers degrade gracefully).
+     * `'both'` is not handled here — callers must split into two calls and
+     * tag results with `source_scope` (CLAUDE.md §Security #6).
+     */
+    private bundleFor;
+    /**
+     * Case-insensitive substring search over chunks of the given scope.
+     *
+     * Phase 1 semantics preserved: returns matches in deterministic
+     * insertion order (by source_uri, then chunk_index). The `text LIKE`
+     * predicate is case-insensitive in SQLite when both sides are ASCII —
+     * to be safe across Unicode, we lowercase the query AND use a `LIKE`
+     * with `lower(text)` so the comparison is symmetrical.
+     *
+     * Empty query returns an empty array (matches MemoryStore behavior).
+     *
+     * Phase 4 swaps this to FTS5+RRF; the return shape stays identical.
+     */
+    search(query: string, scope?: 'project' | 'personal'): Chunk[];
+    /**
+     * Exact lookup by chunk id. Returns null on miss (matches MemoryStore).
+     */
+    get(id: string, scope?: 'project' | 'personal'): Chunk | null;
+    /**
+     * Total number of indexed chunks for a scope (or both if not specified).
+     * Used by `kg status` and the spike-equivalent `store.size()` checks.
+     */
+    size(scope?: 'project' | 'personal'): number;
+    /**
+     * The wiki root directory this scope's data was loaded from. Used by
+     * the CLI status command and Phase 1's `MemoryStore.root()` parity.
+     * Pass-through to whatever the caller stamped on the bundle when opening.
+     */
+    root(scope?: 'project' | 'personal'): string;
+    private countChunks;
+    /**
+     * Bump `last_accessed_at` on the parent nodes of the given chunk ids.
+     * Single statement, no transaction needed. Phase 5's LRU eviction reads
+     * this column; Phase 2 just keeps it warm.
+     */
+    private touchNodesByChunkIds;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/db/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/db/repository.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,OAAO,EAAE,QAAQ,EACjB,QAAQ,GAAE,QAAQ,GAAG,IAAW;IAGnD;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,GAAG,UAAsB,GAAG,KAAK,EAAE;IAuCzE;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,GAAG,UAAsB,GAAG,KAAK,GAAG,IAAI;IA8BxE;;;OAGG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM;IAY5C;;;;OAIG;IACH,IAAI,CAAC,KAAK,GAAE,SAAS,GAAG,UAAsB,GAAG,MAAM;IASvD,OAAO,CAAC,WAAW;IAYnB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;CAU7B"}

package/dist/db/repository.js

@@ -0,0 +1,173 @@
+import { nextReader } from './client.js';
+/**
+ * The repository is the seam between the tool handlers and the SQLite
+ * storage layer. Phase 1 used an in-memory `MemoryStore` directly; Phase 2
+ * swaps in this `Repository` without changing what the tool handlers see.
+ *
+ * **Method shapes mirror MemoryStore exactly** so the swap in Pass 4 is a
+ * one-line rename in each handler. `search()` returns the same `Chunk`
+ * shape and the same insertion-order semantics; `get()` returns the same
+ * `Chunk | null`.
+ *
+ * **Query implementation: LIKE, not FTS5.** Phase 2 stops short of the
+ * FTS5+RRF query path — that lands in Phase 4. Two reasons:
+ *   1. The Phase 1 spike tests use substring queries (e.g. "hashPassword")
+ *      and assert ≥1 result; FTS5's tokenizer would split on case
+ *      boundaries differently and may break those assertions.
+ *   2. The FTS5 virtual table is *populated* in Phase 2 (via the migration's
+ *      triggers) so Phase 4 only has to swap the WHERE clause — the data is
+ *      already indexed.
+ *
+ * **Scope routing**: the data plane supports both `project` and `personal`
+ * (separate DB bundles, separate manifests). The Phase 5 privacy invariant
+ * gate lives in the tool handlers, not here — repository methods accept
+ * a scope param and route to the matching bundle. If a personal bundle
+ * isn't loaded, personal-scope reads return empty / null. The 15-test
+ * privacy adversarial suite is a Phase 5 deliverable; Phase 2 keeps the
+ * existing tool-handler gate that rejects personal-scope tool calls.
+ *
+ * **Single writer / multi reader**: writes go through `bundle.writer`;
+ * reads go through round-robin `nextReader(bundle)`. Repository.search/get
+ * are read-only and use the read pool.
+ */
+export class Repository {
+    project;
+    personal;
+    constructor(project, personal = null) {
+        this.project = project;
+        this.personal = personal;
+    }
+    /**
+     * Resolve the bundle for a given scope. Returns null for `'personal'`
+     * if no personal bundle was provided (so callers degrade gracefully).
+     * `'both'` is not handled here — callers must split into two calls and
+     * tag results with `source_scope` (CLAUDE.md §Security #6).
+     */
+    bundleFor(scope) {
+        return scope === 'project' ? this.project : this.personal;
+    }
+    /**
+     * Case-insensitive substring search over chunks of the given scope.
+     *
+     * Phase 1 semantics preserved: returns matches in deterministic
+     * insertion order (by source_uri, then chunk_index). The `text LIKE`
+     * predicate is case-insensitive in SQLite when both sides are ASCII —
+     * to be safe across Unicode, we lowercase the query AND use a `LIKE`
+     * with `lower(text)` so the comparison is symmetrical.
+     *
+     * Empty query returns an empty array (matches MemoryStore behavior).
+     *
+     * Phase 4 swaps this to FTS5+RRF; the return shape stays identical.
+     */
+    search(query, scope = 'project') {
+        const bundle = this.bundleFor(scope);
+        if (!bundle)
+            return [];
+        const q = query.trim();
+        if (!q)
+            return [];
+        const reader = nextReader(bundle);
+        const rows = reader
+            .prepare(`SELECT c.id AS id, c.text AS text, n.source_uri AS source_uri, c.chunk_index AS chunk_index
+           FROM kg_chunks c JOIN kg_nodes n ON c.node_id = n.id
+          WHERE n.scope = ?
+            AND lower(c.text) LIKE '%' || lower(?) || '%'
+          ORDER BY n.source_uri, c.chunk_index`)
+            .all(scope, q);
+        // Bump last_accessed_at on hit nodes (Phase 5 LRU groundwork). Best-effort,
+        // failures are non-fatal — eviction is a future concern, not a hot path.
+        if (rows.length > 0) {
+            try {
+                this.touchNodesByChunkIds(bundle.writer, rows.map((r) => r.id));
+            }
+            catch {
+                /* swallow — tracking-only */
+            }
+        }
+        return rows.map((r) => ({
+            id: r.id,
+            text: r.text,
+            source_uri: r.source_uri,
+            chunk_index: r.chunk_index,
+        }));
+    }
+    /**
+     * Exact lookup by chunk id. Returns null on miss (matches MemoryStore).
+     */
+    get(id, scope = 'project') {
+        const bundle = this.bundleFor(scope);
+        if (!bundle)
+            return null;
+        const reader = nextReader(bundle);
+        const row = reader
+            .prepare(`SELECT c.id AS id, c.text AS text, n.source_uri AS source_uri, c.chunk_index AS chunk_index
+           FROM kg_chunks c JOIN kg_nodes n ON c.node_id = n.id
+          WHERE n.scope = ? AND c.id = ?
+          LIMIT 1`)
+            .get(scope, id);
+        if (!row)
+            return null;
+        try {
+            this.touchNodesByChunkIds(bundle.writer, [row.id]);
+        }
+        catch {
+            /* swallow */
+        }
+        return {
+            id: row.id,
+            text: row.text,
+            source_uri: row.source_uri,
+            chunk_index: row.chunk_index,
+        };
+    }
+    /**
+     * Total number of indexed chunks for a scope (or both if not specified).
+     * Used by `kg status` and the spike-equivalent `store.size()` checks.
+     */
+    size(scope) {
+        if (scope) {
+            const bundle = this.bundleFor(scope);
+            if (!bundle)
+                return 0;
+            return this.countChunks(bundle, scope);
+        }
+        return (this.countChunks(this.project, 'project') +
+            (this.personal ? this.countChunks(this.personal, 'personal') : 0));
+    }
+    /**
+     * The wiki root directory this scope's data was loaded from. Used by
+     * the CLI status command and Phase 1's `MemoryStore.root()` parity.
+     * Pass-through to whatever the caller stamped on the bundle when opening.
+     */
+    root(scope = 'project') {
+        const bundle = this.bundleFor(scope);
+        return bundle?.path ?? '';
+    }
+    // --------------------------------------------------------------------------
+    // Internal helpers
+    // --------------------------------------------------------------------------
+    countChunks(bundle, scope) {
+        const reader = nextReader(bundle);
+        const row = reader
+            .prepare(`SELECT count(*) AS c
+           FROM kg_chunks ch JOIN kg_nodes n ON ch.node_id = n.id
+          WHERE n.scope = ?`)
+            .get(scope);
+        return row?.c ?? 0;
+    }
+    /**
+     * Bump `last_accessed_at` on the parent nodes of the given chunk ids.
+     * Single statement, no transaction needed. Phase 5's LRU eviction reads
+     * this column; Phase 2 just keeps it warm.
+     */
+    touchNodesByChunkIds(writer, chunkIds) {
+        if (chunkIds.length === 0)
+            return;
+        const placeholders = chunkIds.map(() => '?').join(',');
+        writer
+            .prepare(`UPDATE kg_nodes SET last_accessed_at = ?
+          WHERE id IN (SELECT node_id FROM kg_chunks WHERE id IN (${placeholders}))`)
+            .run(Date.now(), ...chunkIds);
+    }
+}
+//# sourceMappingURL=repository.js.map

package/dist/db/repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../../src/db/repository.ts"],"names":[],"mappings":"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"}