@pella-labs/pinakes 0.1.0

package/dist/cli/serve.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { closeDb, openDb } from '../db/client.js';
+import { Repository } from '../db/repository.js';
+import { ChokidarWatcher } from '../ingest/chokidar.js';
+import { IngesterService } from '../ingest/ingester.js';
+import { checkConsistency, listMarkdownFiles } from '../ingest/manifest.js';
+import { kgExecuteToolConfig, makeKgExecuteHandler } from '../mcp/tools/execute.js';
+import { kgSearchToolConfig, makeKgSearchHandler } from '../mcp/tools/search.js';
+import { writeAuditRow } from '../observability/audit.js';
+import { child, logger } from '../observability/logger.js';
+import { installSighupHandler, metrics } from '../observability/metrics.js';
+import { createEmbedder } from '../retrieval/embedder.js';
+import { QuickJSExecutor } from '../sandbox/executor.js';
+/**
+ * Build (but don't start) the stdio server. Exposed as a function so future
+ * tests / in-process integrations can construct a server without going
+ * through the CLI argv path.
+ */
+export async function buildServer(options) {
+    const projectWiki = resolveAbs(options.wikiPath);
+    if (!existsSync(projectWiki)) {
+        throw new Error(`wiki path does not exist: ${projectWiki}`);
+    }
+    const projectDbPath = resolveAbs(options.dbPath ?? defaultDbPathFor(projectWiki));
+    const profileWiki = resolveAbs(options.profilePath ?? defaultProfileWikiPath());
+    const profileDbPath = resolveAbs(options.profileDbPath ?? defaultDbPathFor(profileWiki));
+    const enablePersonal = existsSync(profileWiki);
+    // Step 1: open DBs
+    const projectBundle = openDb(projectDbPath);
+    const personalBundle = enablePersonal ? openDb(profileDbPath) : null;
+    // Step 2: warm embedder
+    const embedder = createEmbedder();
+    await embedder.warmup();
+    // Step 3: ingesters per scope
+    const projectIngester = new IngesterService(projectBundle, embedder, 'project', projectWiki);
+    const personalIngester = personalBundle
+        ? new IngesterService(personalBundle, embedder, 'personal', profileWiki)
+        : null;
+    // Step 4: startup consistency check — re-ingest any stale files.
+    // Pass the DB writer so checkConsistency can cross-validate manifest claims
+    // against actual DB rows. This catches the "manifest says indexed but DB is
+    // empty" scenario (DB recreated, migration dropped tables, etc.).
+    await runStartupConsistency(projectIngester, projectWiki, 'project', projectBundle.writer);
+    if (personalIngester && personalBundle) {
+        await runStartupConsistency(personalIngester, profileWiki, 'personal', personalBundle.writer);
+    }
+    // Step 5: start watchers
+    const projectWatcher = new ChokidarWatcher({ rootDir: projectWiki, scope: 'project' });
+    const personalWatcher = personalIngester
+        ? new ChokidarWatcher({ rootDir: profileWiki, scope: 'personal' })
+        : null;
+    await projectWatcher.start(makeOnEvent(projectIngester));
+    if (personalWatcher && personalIngester) {
+        await personalWatcher.start(makeOnEvent(personalIngester));
+    }
+    // Step 6: build the MCP server
+    const repository = new Repository(projectBundle, personalBundle);
+    const executor = new QuickJSExecutor();
+    await executor.warmup();
+    // Audit JSONL paths (CLAUDE.md §Security #7: scope-split)
+    const projectAuditJsonl = resolve(dirname(projectDbPath), 'audit.jsonl');
+    const personalAuditJsonl = resolve(homedir(), '.kg/audit.jsonl');
+    const auditCtx = {
+        projectBundle,
+        personalBundle: personalBundle ?? undefined,
+        projectAuditJsonl,
+        personalAuditJsonl,
+    };
+    const mcp = new McpServer({ name: 'kg-mcp', version: '0.7.0' }, { capabilities: { tools: {} } });
+    mcp.registerTool('kg_search', kgSearchToolConfig, instrumentHandler('kg_search', makeKgSearchHandler({
+        repository, embedder, bundle: projectBundle,
+        personalBundle: personalBundle ?? undefined,
+    }), auditCtx));
+    mcp.registerTool('kg_execute', kgExecuteToolConfig, instrumentHandler('kg_execute', makeKgExecuteHandler({
+        repository, executor, bundle: projectBundle, embedder,
+        wikiRoot: projectWiki,
+        personalBundle: personalBundle ?? undefined,
+        personalWikiRoot: enablePersonal ? profileWiki : undefined,
+    }), auditCtx));
+    // Step 7: periodic background health check — detect index drift at runtime.
+    // Compares disk file count vs DB indexed file count every HEALTH_CHECK_INTERVAL_MS.
+    // If there's a mismatch, re-runs the full consistency check (with DB cross-validation)
+    // and re-ingests stale files. This catches missed chokidar events, silent write
+    // failures, or DB state changes that happen while the server is running.
+    const HEALTH_CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+    let healthCheckRunning = false;
+    const healthCheckTimer = setInterval(() => {
+        if (healthCheckRunning)
+            return; // don't overlap
+        void runHealthCheck();
+    }, HEALTH_CHECK_INTERVAL_MS);
+    // Don't let the timer keep the process alive on shutdown.
+    healthCheckTimer.unref();
+    async function runHealthCheck() {
+        healthCheckRunning = true;
+        try {
+            const diskFiles = listMarkdownFiles(projectWiki);
+            const dbCount = projectBundle.writer
+                .prepare('SELECT COUNT(DISTINCT source_uri) AS cnt FROM kg_nodes WHERE scope = ?')
+                .get('project')?.cnt ?? 0;
+            if (diskFiles.length !== dbCount) {
+                logger.info({ diskFiles: diskFiles.length, dbIndexed: dbCount, scope: 'project' }, 'health check: index drift detected — running consistency check');
+                await runStartupConsistency(projectIngester, projectWiki, 'project', projectBundle.writer);
+            }
+            if (personalIngester && personalBundle) {
+                const personalDiskFiles = listMarkdownFiles(profileWiki);
+                const personalDbCount = personalBundle.writer
+                    .prepare('SELECT COUNT(DISTINCT source_uri) AS cnt FROM kg_nodes WHERE scope = ?')
+                    .get('personal')?.cnt ?? 0;
+                if (personalDiskFiles.length !== personalDbCount) {
+                    logger.info({ diskFiles: personalDiskFiles.length, dbIndexed: personalDbCount, scope: 'personal' }, 'health check: index drift detected — running consistency check');
+                    await runStartupConsistency(personalIngester, profileWiki, 'personal', personalBundle.writer);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'health check failed');
+        }
+        finally {
+            healthCheckRunning = false;
+        }
+    }
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info({ signal }, 'kg-mcp shutting down');
+        try {
+            clearInterval(healthCheckTimer);
+            await projectWatcher.stop();
+            if (personalWatcher)
+                await personalWatcher.stop();
+            await mcp.close();
+        }
+        catch (err) {
+            logger.warn({ err }, 'shutdown error');
+        }
+        finally {
+            closeDb(projectBundle);
+            if (personalBundle)
+                closeDb(personalBundle);
+        }
+    };
+    return { server: mcp, shutdown };
+}
+/**
+ * The CLI entry point: build the server, connect stdio, install signal
+ * handlers, listen forever.
+ */
+export async function serveCommand(options) {
+    logger.info({ wikiPath: options.wikiPath }, 'kg-mcp starting');
+    installSighupHandler();
+    const { server, shutdown } = await buildServer(options);
+    const transport = new StdioServerTransport();
+    process.on('SIGTERM', () => {
+        void shutdown('SIGTERM').then(() => process.exit(0));
+    });
+    process.on('SIGINT', () => {
+        void shutdown('SIGINT').then(() => process.exit(0));
+    });
+    await server.connect(transport);
+    logger.info('kg-mcp listening on stdio');
+}
+// ----------------------------------------------------------------------------
+// Internals
+// ----------------------------------------------------------------------------
+function makeOnEvent(ingester) {
+    return async (ev) => {
+        if (ev.kind === 'file:removed') {
+            ingester.removeFile(ev.path);
+            return;
+        }
+        await ingester.ingestFile(ev.path);
+    };
+}
+async function runStartupConsistency(ingester, wikiDir, scope, writer) {
+    ingester.reloadManifest();
+    const manifest = ingester.getManifest();
+    const stale = checkConsistency(manifest, wikiDir, writer);
+    if (stale.length === 0) {
+        logger.info({ scope, wikiDir }, 'startup consistency check: nothing stale');
+        return;
+    }
+    logger.info({ scope, wikiDir, stale: stale.length }, 'startup consistency check: re-ingesting stale files');
+    for (const file of stale) {
+        try {
+            await ingester.ingestFile(file);
+        }
+        catch (err) {
+            logger.warn({ err, file, scope }, 'startup consistency: file ingest failed');
+        }
+    }
+}
+function resolveAbs(p) {
+    return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+function defaultDbPathFor(wikiDir) {
+    return resolve(dirname(wikiDir), 'kg.db');
+}
+function defaultProfileWikiPath() {
+    const env = process.env.KG_PROFILE_PATH;
+    if (env)
+        return resolve(env, 'wiki');
+    return resolve(homedir(), '.pharos/profile/wiki');
+}
+/**
+ * Wrap a tool handler with:
+ *   1. Per-call correlation ID (callId) threaded into a pino child logger
+ *   2. Structured entry/exit logging with latency
+ *   3. Audit row written to the scope-appropriate DB + JSONL mirror
+ *   4. Metrics counter update
+ */
+function instrumentHandler(toolName, handler, ctx) {
+    return async (args) => {
+        const callId = randomUUID();
+        const scope = args.scope ?? 'project';
+        const log = child({ callId, tool: toolName, scope });
+        log.info({ args: summarizeArgs(args) }, 'tool call start');
+        const start = performance.now();
+        let result;
+        let error;
+        try {
+            result = await handler(args);
+        }
+        catch (err) {
+            const latencyMs = Math.round(performance.now() - start);
+            error = err instanceof Error ? err.message : String(err);
+            log.error({ err, latencyMs }, 'tool call failed');
+            metrics.recordToolCall(toolName, latencyMs, true);
+            writeAudit(ctx, toolName, scope, callId, undefined, error);
+            throw err;
+        }
+        const latencyMs = Math.round(performance.now() - start);
+        // Extract tokens_used from the envelope embedded in the response text
+        let responseTokens;
+        try {
+            const envelope = JSON.parse(result.content[0].text);
+            responseTokens = envelope?.meta?.tokens_used;
+            if (envelope?.result && typeof envelope.result === 'object' && 'error' in envelope.result) {
+                error = String(envelope.result.error);
+            }
+        }
+        catch {
+            // Non-JSON response — shouldn't happen, but don't crash the wrapper
+        }
+        log.info({ latencyMs, responseTokens }, 'tool call end');
+        metrics.recordToolCall(toolName, latencyMs, !!error);
+        writeAudit(ctx, toolName, scope, callId, responseTokens, error);
+        return result;
+    };
+}
+/**
+ * Write audit row to the correct DB + JSONL per scope-split rule.
+ */
+function writeAudit(ctx, toolName, scope, callId, responseTokens, error) {
+    const entry = {
+        toolName,
+        scopeRequested: scope,
+        callerCtx: callId,
+        responseTokens,
+        error,
+    };
+    if (scope === 'project') {
+        writeAuditRow(ctx.projectBundle.writer, ctx.projectAuditJsonl, entry);
+    }
+    else if (ctx.personalBundle) {
+        writeAuditRow(ctx.personalBundle.writer, ctx.personalAuditJsonl, entry);
+    }
+    else {
+        // Fallback: write to project DB if personal is not configured
+        writeAuditRow(ctx.projectBundle.writer, ctx.projectAuditJsonl, entry);
+    }
+}
+/**
+ * Summarize args for logging without dumping huge code strings.
+ */
+function summarizeArgs(args) {
+    const summary = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (k === 'code' && typeof v === 'string') {
+            summary[k] = v.length > 100 ? v.slice(0, 100) + '...' : v;
+        }
+        else {
+            summary[k] = v;
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=serve.js.map

package/dist/cli/serve.js.map

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

package/dist/cli/status.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `kg status` — health check for KG-MCP Phase 2.
+ *
+ * Opens the project + personal DBs (if they exist), reports row counts per
+ * table, schema version, last full rebuild timestamp, and SQLite version.
+ *
+ * No DB writes — strictly read-only. Safe to run while a `kg serve` instance
+ * is also running on the same DB (WAL mode + read connection makes this fine).
+ */
+export interface StatusOptions {
+    /** Path to project DB. If omitted, defaults to `.pharos/kg.db` from wikiPath if given. */
+    dbPath?: string;
+    /** Path to project wiki dir, used to derive default dbPath if dbPath omitted */
+    wikiPath?: string;
+    /** Path to personal DB (default: `~/.pharos/profile/kg.db`) */
+    profileDbPath?: string;
+}
+export interface ScopeStatus {
+    scope: 'project' | 'personal';
+    dbPath: string;
+    exists: boolean;
+    schemaVersion: string | null;
+    lastFullRebuild: number | null;
+    sqliteVersion: string | null;
+    rowCounts: Record<string, number>;
+}
+/**
+ * Build a status report for both scopes. The result is a structured object
+ * suitable for both human-readable rendering and JSON output (e.g.
+ * `kg status --json`).
+ */
+export declare function statusCommand(options?: StatusOptions): ScopeStatus[];
+/**
+ * Pretty-print a list of `ScopeStatus` to a string. Used by the CLI entry to
+ * write to stdout. Tests assert against the structured `statusCommand` result
+ * directly, not the rendered string.
+ */
+export declare function renderStatus(statuses: ScopeStatus[]): string;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/cli/status.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,WAAW,EAAE,CAQxE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAqB5D"}

package/dist/cli/status.js

@@ -0,0 +1,108 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { closeDb, openDb } from '../db/client.js';
+import { KG_TABLES, KG_VIRTUAL_TABLES } from '../db/schema.js';
+/**
+ * Build a status report for both scopes. The result is a structured object
+ * suitable for both human-readable rendering and JSON output (e.g.
+ * `kg status --json`).
+ */
+export function statusCommand(options = {}) {
+    const projectDbPath = resolveProjectDb(options);
+    const profileDbPath = resolveProfileDb(options);
+    return [
+        inspectScope('project', projectDbPath),
+        inspectScope('personal', profileDbPath),
+    ];
+}
+/**
+ * Pretty-print a list of `ScopeStatus` to a string. Used by the CLI entry to
+ * write to stdout. Tests assert against the structured `statusCommand` result
+ * directly, not the rendered string.
+ */
+export function renderStatus(statuses) {
+    const lines = [];
+    for (const s of statuses) {
+        lines.push(`${s.scope.toUpperCase()} DB: ${s.dbPath}`);
+        if (!s.exists) {
+            lines.push('  (not initialized)');
+            lines.push('');
+            continue;
+        }
+        lines.push(`  sqlite_version: ${s.sqliteVersion ?? '<unknown>'}`);
+        lines.push(`  schema_version: ${s.schemaVersion ?? '<absent>'}`);
+        lines.push(`  last_full_rebuild: ${s.lastFullRebuild ? new Date(s.lastFullRebuild).toISOString() : '<never>'}`);
+        for (const table of [...KG_TABLES, ...KG_VIRTUAL_TABLES]) {
+            const count = s.rowCounts[table] ?? 0;
+            lines.push(`  ${table.padEnd(20)} ${count}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ----------------------------------------------------------------------------
+// Internals
+// ----------------------------------------------------------------------------
+function inspectScope(scope, dbPath) {
+    const status = {
+        scope,
+        dbPath,
+        exists: existsSync(dbPath),
+        schemaVersion: null,
+        lastFullRebuild: null,
+        sqliteVersion: null,
+        rowCounts: {},
+    };
+    if (!status.exists)
+        return status;
+    // Open with `runMigrations: false` to avoid surprising the user with a
+    // schema upgrade just from running `status`. If the schema is out of
+    // date, the row counts will still be readable for the tables that exist.
+    const bundle = openDb(dbPath, { runMigrations: false });
+    try {
+        status.sqliteVersion = bundle.writer.prepare('SELECT sqlite_version() AS v').get().v;
+        const schemaRow = bundle.writer
+            .prepare("SELECT value FROM kg_meta WHERE key = 'schema_version'")
+            .get();
+        status.schemaVersion = schemaRow?.value ?? null;
+        const rebuildRow = bundle.writer
+            .prepare("SELECT value FROM kg_meta WHERE key = 'last_full_rebuild'")
+            .get();
+        status.lastFullRebuild = rebuildRow ? parseInt(rebuildRow.value, 10) : null;
+        for (const table of [...KG_TABLES, ...KG_VIRTUAL_TABLES]) {
+            try {
+                const row = bundle.writer.prepare(`SELECT count(*) AS c FROM ${table}`).get();
+                status.rowCounts[table] = row.c;
+            }
+            catch {
+                // Table may not exist on an old schema; report 0 and move on.
+                status.rowCounts[table] = 0;
+            }
+        }
+    }
+    finally {
+        closeDb(bundle);
+    }
+    return status;
+}
+function resolveProjectDb(options) {
+    if (options.dbPath)
+        return resolveAbs(options.dbPath);
+    if (options.wikiPath) {
+        return resolve(dirname(resolveAbs(options.wikiPath)), 'kg.db');
+    }
+    // Last resort: ./.pharos/kg.db relative to cwd
+    return resolve(process.cwd(), '.pharos/kg.db');
+}
+function resolveProfileDb(options) {
+    if (options.profileDbPath)
+        return resolveAbs(options.profileDbPath);
+    const env = process.env.KG_PROFILE_PATH;
+    const profileDir = env ? resolveAbs(env) : resolve(homedir(), '.pharos/profile');
+    return resolve(profileDir, 'kg.db');
+}
+function resolveAbs(p) {
+    return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/status.js.map

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

package/dist/db/client.d.ts

@@ -0,0 +1,109 @@
+import { type Database as BetterSqliteDatabase } from 'better-sqlite3';
+import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import * as schema from './schema.js';
+/**
+ * SQLite connection management for KG-MCP.
+ *
+ * **Single-writer + read-pool-of-2** invariant (CLAUDE.md §Architecture #3,
+ * §Database Rules #1):
+ *   - One writer connection — all DML for a given DB file goes through this.
+ *     Enforced at the app layer via the single-flight gate in the ingester
+ *     (a `Map<source_uri, Promise>`), not by the DB driver.
+ *   - Two reader connections in a tiny round-robin pool. Reads can run
+ *     concurrently with the writer because we use WAL mode. SQLite's
+ *     "many readers, one writer" model is fastest with this exact shape;
+ *     adding a connection pool with multiple writers actually HURTS
+ *     throughput (presearch.md §Loop 0 gotcha).
+ *
+ * **Mandatory pragmas** (CLAUDE.md §Database Rules #1) applied on EVERY
+ * connection (writer + readers) at open time. Foreign keys are enforced
+ * per-connection in SQLite, so missing them on a reader would silently
+ * skip CASCADE checks.
+ *
+ * **sqlite-vec extension** is loaded on every connection so that the vec0
+ * virtual table is queryable from any reader and writable by the writer.
+ * The migration that creates `kg_chunks_vec` requires the extension to be
+ * loaded BEFORE drizzle's `migrate()` runs — this file orders things so
+ * that load happens first.
+ *
+ * **SQLite version check**: 3.50.4 OR ≥3.51.3, never 3.51.0 (FTS5
+ * regression, presearch D18). Throws on a bad version at openDb() time.
+ */
+/**
+ * A bundle of one writer + two readers for a given SQLite file. The
+ * `drizzleWriter` is a drizzle wrapper around the writer connection,
+ * suitable for Drizzle queries; the raw `writer` and `readers` are
+ * also exposed for raw-SQL hot paths (FTS5, vec0, repository LIKE
+ * search) where Drizzle's overhead isn't worth it.
+ */
+export interface DbBundle {
+    /** Absolute path to the SQLite file */
+    path: string;
+    /** Single writer connection — all DML goes through this */
+    writer: BetterSqliteDatabase;
+    /** Read pool of 2; pick via {@link nextReader} for round-robin */
+    readers: BetterSqliteDatabase[];
+    /** Drizzle wrapper around `writer` for typed queries */
+    drizzleWriter: BetterSQLite3Database<typeof schema>;
+}
+/**
+ * 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'.
+ */
+declare function isAllowedSqliteVersion(version: string): boolean;
+/**
+ * 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.
+ */
+declare function applyPragmas(db: BetterSqliteDatabase): void;
+/**
+ * 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).
+ */
+declare function loadSqliteVec(db: BetterSqliteDatabase): void;
+/**
+ * Open (or create) a SQLite file with the full Phase 2 setup applied:
+ *   1. Create the parent directory if missing
+ *   2. Open one writer + two readers via better-sqlite3
+ *   3. Apply mandatory pragmas on each connection
+ *   4. Load sqlite-vec on each connection
+ *   5. Verify SQLite version (3.50.4 or ≥3.51.3, never 3.51.0)
+ *   6. Run drizzle migrations on the writer
+ *   7. Stamp `kg_meta.schema_version='1'` if not yet set
+ *
+ * Returns a `DbBundle` ready for repository / ingester use.
+ *
+ * Pass `{ runMigrations: false }` to skip step 6 — useful for tests that
+ * want to assert pragma state on a virgin connection.
+ */
+export interface OpenDbOptions {
+    /** Skip the migration run (default: true). Tests use `false` to test pragmas in isolation. */
+    runMigrations?: boolean;
+}
+export declare function openDb(path: string, options?: OpenDbOptions): DbBundle;
+/**
+ * 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 declare function closeDb(bundle: DbBundle): void;
+export declare function nextReader(bundle: DbBundle): BetterSqliteDatabase;
+/** Exposed for schema.test.ts to verify the version-check rule directly. */
+export declare const __test: {
+    isAllowedSqliteVersion: typeof isAllowedSqliteVersion;
+    applyPragmas: typeof applyPragmas;
+    loadSqliteVec: typeof loadSqliteVec;
+    MIGRATIONS_FOLDER: string;
+};
+export {};
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/db/client.ts"],"names":[],"mappings":"AAIA,OAAiB,EAAE,KAAK,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAW,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAKjF,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,kEAAkE;IAClE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,wDAAwD;IACxD,aAAa,EAAE,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC;CACrD;AASD;;;;;;;GAOG;AACH,iBAAS,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBxD;AAMD;;;;;GAKG;AACH,iBAAS,YAAY,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI,CAOpD;AAED;;;;;;;;GAQG;AACH,iBAAS,aAAa,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI,CAGrD;AAmBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,QAAQ,CAiD1E;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAc9C;AAYD,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,oBAAoB,CAGjE;AAMD,4EAA4E;AAC5E,eAAO,MAAM,MAAM;;;;;CAKlB,CAAC"}