@pella-labs/pinakes 0.1.0

package/dist/retrieval/fts.d.ts

@@ -0,0 +1,42 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+/**
+ * FTS5 full-text search with BM25 ranking and optional snippet extraction.
+ *
+ * Extracted from `src/sandbox/bindings/kg.ts` so both the sandbox bindings
+ * and the `kg_search` MCP tool can share the same query logic. The binding
+ * delegates here; the MCP tool calls `hybridSearch` which calls here.
+ *
+ * **Tokenizer**: `unicode61 remove_diacritics 2` (set in the migration).
+ * **NOT trigram** — it triples the DB size (presearch.md §Loop 0 gotcha).
+ *
+ * **Query escaping**: each whitespace-separated token is wrapped in double
+ * quotes so user/LLM-provided input can't trigger FTS5 syntax errors.
+ */
+export interface FtsResult {
+    id: string;
+    text: string;
+    snippet: string;
+    source_uri: string;
+    node_id: string;
+    rank: number;
+    confidence: string;
+    title: string | null;
+    section_path: string;
+}
+/**
+ * Run an FTS5 MATCH query with BM25 ranking and snippet extraction.
+ *
+ * @param reader   A read-only `better-sqlite3` connection (from the read pool).
+ * @param scope    `'project'` or `'personal'` — filters by `kg_nodes.scope`.
+ * @param query    Raw user/LLM query string (will be escaped).
+ * @param limit    Max results (clamped to 1..100 by callers).
+ * @returns        Results ranked by BM25 (lower rank = better match).
+ */
+export declare function ftsQuery(reader: BetterSqliteDatabase, scope: string, query: string, limit: number): FtsResult[];
+/**
+ * Escape an FTS5 query by wrapping each token in double quotes. This prevents
+ * FTS5 syntax errors when the query contains special characters (*, +, -, etc).
+ * Returns null if no valid tokens remain.
+ */
+export declare function escapeFts5Query(query: string): string | null;
+//# sourceMappingURL=fts.d.ts.map

package/dist/retrieval/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../src/retrieval/fts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,SAAS,EAAE,CA2Bb;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D"}

package/dist/retrieval/fts.js

@@ -0,0 +1,46 @@
+/**
+ * Run an FTS5 MATCH query with BM25 ranking and snippet extraction.
+ *
+ * @param reader   A read-only `better-sqlite3` connection (from the read pool).
+ * @param scope    `'project'` or `'personal'` — filters by `kg_nodes.scope`.
+ * @param query    Raw user/LLM query string (will be escaped).
+ * @param limit    Max results (clamped to 1..100 by callers).
+ * @returns        Results ranked by BM25 (lower rank = better match).
+ */
+export function ftsQuery(reader, scope, query, limit) {
+    const escaped = escapeFts5Query(query);
+    if (!escaped)
+        return [];
+    const rows = reader
+        .prepare(`SELECT c.id AS id, c.text AS text,
+              snippet(kg_chunks_fts, 0, '', '', '…', 64) AS snippet,
+              n.source_uri AS source_uri,
+              n.id AS node_id, bm25(kg_chunks_fts) AS rank,
+              n.confidence AS confidence,
+              n.title AS title,
+              n.section_path AS section_path
+         FROM kg_chunks_fts f
+         JOIN kg_chunks c ON c.rowid = f.rowid
+         JOIN kg_nodes n ON c.node_id = n.id
+        WHERE n.scope = ?
+          AND kg_chunks_fts MATCH ?
+        ORDER BY bm25(kg_chunks_fts)
+        LIMIT ?`)
+        .all(scope, escaped, limit);
+    return rows;
+}
+/**
+ * Escape an FTS5 query by wrapping each token in double quotes. This prevents
+ * FTS5 syntax errors when the query contains special characters (*, +, -, etc).
+ * Returns null if no valid tokens remain.
+ */
+export function escapeFts5Query(query) {
+    const tokens = query
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return null;
+    return tokens.map((t) => `"${t.replace(/"/g, '""')}"`).join(' ');
+}
+//# sourceMappingURL=fts.js.map

package/dist/retrieval/fts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.js","sourceRoot":"","sources":["../../src/retrieval/fts.ts"],"names":[],"mappings":"AA4BA;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,MAA4B,EAC5B,KAAa,EACb,KAAa,EACb,KAAa;IAEb,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,IAAI,GAAG,MAAM;SAChB,OAAO,CAIN;;;;;;;;;;;;;gBAaU,CACX;SACA,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAE9B,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,MAAM,GAAG,KAAK;SACjB,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC"}

package/dist/retrieval/hybrid.d.ts

@@ -0,0 +1,43 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+import type { Embedder } from './embedder.js';
+import { type FtsResult } from './fts.js';
+import { type VecResult } from './vec.js';
+export interface HybridResult {
+    id: string;
+    text: string;
+    source_uri: string;
+    node_id: string;
+    score: number;
+    snippet?: string;
+    confidence: string;
+    title: string | null;
+    section_path: string;
+}
+export interface HybridSearchOpts {
+    limit?: number;
+    rrf_k?: number;
+}
+/**
+ * Run a hybrid FTS5 + vector search with RRF fusion.
+ *
+ * Both sub-queries run with an over-fetch factor (2x limit) so that RRF
+ * has enough candidates to fuse meaningfully.
+ *
+ * @param reader    Read-only DB connection.
+ * @param scope     `'project'` or `'personal'`.
+ * @param query     Raw query text.
+ * @param embedder  Embedder for the vector path.
+ * @param opts      `limit` (default 20), `rrf_k` (default 60).
+ * @returns         Results sorted by descending RRF score.
+ */
+export declare function hybridSearch(reader: BetterSqliteDatabase, scope: string, query: string, embedder: Embedder, opts?: HybridSearchOpts): Promise<HybridResult[]>;
+/**
+ * Fuse FTS and vec results via equal-weight Reciprocal Rank Fusion.
+ *
+ * Phase 7.5: equal weighting — both FTS and vec contribute `1/(rrfK+rank)`.
+ * No adaptive weighting or BM25 filtering. The LLM is the precision layer.
+ *
+ * Exported for direct testing — `hybridSearch` is the normal entry point.
+ */
+export declare function rrfFuse(ftsResults: FtsResult[], vecResults: VecResult[], rrfK: number, limit: number): HybridResult[];
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/retrieval/hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.d.ts","sourceRoot":"","sources":["../../src/retrieval/hybrid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAuBrD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAczB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,SAAS,EAAE,EACvB,UAAU,EAAE,SAAS,EAAE,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CAiEhB"}

package/dist/retrieval/hybrid.js

@@ -0,0 +1,120 @@
+import { ftsQuery } from './fts.js';
+import { vecSearch } from './vec.js';
+/**
+ * Hybrid retrieval: FTS5 + sqlite-vec fused via Reciprocal Rank Fusion (RRF).
+ *
+ * This is the canonical Alex Garcia pattern from presearch.md:
+ *   RRF_score(d) = Σ 1 / (rrf_k + rank_i(d))
+ *
+ * where rank_i(d) is the 1-based rank of document d in result list i.
+ *
+ * Items appearing in only one list get a single-side RRF score (the other
+ * term is zero). Items in both lists get both terms summed.
+ *
+ * Phase 7.5: equal-weight RRF (no adaptive weighting). The LLM is the
+ * precision layer; we optimize for recall by letting both FTS and vec
+ * contribute equally. FTS catches keyword matches vec might miss; vec
+ * catches semantic matches FTS misses.
+ *
+ * Default `rrf_k = 60` per the PRD.
+ */
+const DEFAULT_RRF_K = 60;
+/**
+ * Run a hybrid FTS5 + vector search with RRF fusion.
+ *
+ * Both sub-queries run with an over-fetch factor (2x limit) so that RRF
+ * has enough candidates to fuse meaningfully.
+ *
+ * @param reader    Read-only DB connection.
+ * @param scope     `'project'` or `'personal'`.
+ * @param query     Raw query text.
+ * @param embedder  Embedder for the vector path.
+ * @param opts      `limit` (default 20), `rrf_k` (default 60).
+ * @returns         Results sorted by descending RRF score.
+ */
+export async function hybridSearch(reader, scope, query, embedder, opts) {
+    const limit = Math.min(Math.max(opts?.limit ?? 20, 1), 100);
+    const rrfK = opts?.rrf_k ?? DEFAULT_RRF_K;
+    // Over-fetch from each source so RRF has good coverage.
+    const fetchLimit = Math.min(limit * 2, 100);
+    // Run both queries. Vec is async (embedding), FTS is sync.
+    const [ftsResults, vecResults] = await Promise.all([
+        Promise.resolve(ftsQuery(reader, scope, query, fetchLimit)),
+        vecSearch(reader, scope, query, embedder, fetchLimit),
+    ]);
+    return rrfFuse(ftsResults, vecResults, rrfK, limit);
+}
+/**
+ * Fuse FTS and vec results via equal-weight Reciprocal Rank Fusion.
+ *
+ * Phase 7.5: equal weighting — both FTS and vec contribute `1/(rrfK+rank)`.
+ * No adaptive weighting or BM25 filtering. The LLM is the precision layer.
+ *
+ * Exported for direct testing — `hybridSearch` is the normal entry point.
+ */
+export function rrfFuse(ftsResults, vecResults, rrfK, limit) {
+    // Build a map keyed by chunk id. Each entry accumulates its RRF score.
+    const merged = new Map();
+    // FTS: rank is 1-based position in the result list.
+    for (let i = 0; i < ftsResults.length; i++) {
+        const r = ftsResults[i];
+        const rrfScore = 1 / (rrfK + (i + 1));
+        const existing = merged.get(r.id);
+        if (existing) {
+            existing._rrfScore += rrfScore;
+            // Prefer FTS snippet over vec (which has none).
+            if (r.snippet)
+                existing.snippet = r.snippet;
+        }
+        else {
+            merged.set(r.id, {
+                id: r.id,
+                text: r.text,
+                source_uri: r.source_uri,
+                node_id: r.node_id,
+                score: 0, // filled after fusion
+                snippet: r.snippet || undefined,
+                confidence: r.confidence,
+                title: r.title ?? null,
+                section_path: r.section_path ?? '',
+                _rrfScore: rrfScore,
+            });
+        }
+    }
+    // Vec: rank is 1-based position in the vec result list.
+    for (let i = 0; i < vecResults.length; i++) {
+        const r = vecResults[i];
+        const rrfScore = 1 / (rrfK + (i + 1));
+        const existing = merged.get(r.id);
+        if (existing) {
+            existing._rrfScore += rrfScore;
+        }
+        else {
+            merged.set(r.id, {
+                id: r.id,
+                text: r.text,
+                source_uri: r.source_uri,
+                node_id: r.node_id,
+                score: 0,
+                confidence: r.confidence,
+                title: r.title ?? null,
+                section_path: r.section_path ?? '',
+                _rrfScore: rrfScore,
+            });
+        }
+    }
+    // Sort by descending RRF score, assign final score, trim to limit.
+    const sorted = [...merged.values()].sort((a, b) => b._rrfScore - a._rrfScore);
+    return sorted.slice(0, limit).map((r) => ({
+        id: r.id,
+        text: r.text,
+        source_uri: r.source_uri,
+        node_id: r.node_id,
+        score: r._rrfScore,
+        snippet: r.snippet,
+        confidence: r.confidence,
+        title: r.title,
+        section_path: r.section_path,
+    }));
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/retrieval/hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.js","sourceRoot":"","sources":["../../src/retrieval/hybrid.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAkB,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,SAAS,EAAkB,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,aAAa,GAAG,EAAE,CAAC;AAmBzB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAA4B,EAC5B,KAAa,EACb,KAAa,EACb,QAAkB,EAClB,IAAuB;IAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,IAAI,EAAE,KAAK,IAAI,aAAa,CAAC;IAE1C,wDAAwD;IACxD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAE5C,2DAA2D;IAC3D,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjD,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAC3D,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC;KACtD,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,UAAuB,EACvB,UAAuB,EACvB,IAAY,EACZ,KAAa;IAEb,uEAAuE;IACvE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgD,CAAC;IAEvE,oDAAoD;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC;YAC/B,gDAAgD;YAChD,IAAI,CAAC,CAAC,OAAO;gBAAE,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACf,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC,EAAE,sBAAsB;gBAChC,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,SAAS;gBAC/B,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI;gBACtB,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,EAAE;gBAClC,SAAS,EAAE,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACf,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC;gBACR,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI;gBACtB,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,EAAE;gBAClC,SAAS,EAAE,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAE9E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxC,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,KAAK,EAAE,CAAC,CAAC,SAAS;QAClB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,YAAY,EAAE,CAAC,CAAC,YAAY;KAC7B,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/retrieval/vec.d.ts

@@ -0,0 +1,39 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+import type { Embedder } from './embedder.js';
+/**
+ * Vector similarity search via sqlite-vec's `vec0` virtual table.
+ *
+ * The query embedding is computed on the fly by the caller-provided embedder.
+ * The sqlite-vec `MATCH` operator performs an approximate nearest-neighbor
+ * search against `kg_chunks_vec`, returning rowids + cosine distances.
+ * We join back to `kg_chunks` + `kg_nodes` for the full result shape.
+ *
+ * **Graceful degradation**: if the vec table is empty or the embedder fails,
+ * returns an empty array (never throws on query path).
+ */
+export interface VecResult {
+    id: string;
+    text: string;
+    source_uri: string;
+    node_id: string;
+    distance: number;
+    confidence: string;
+    title: string | null;
+    section_path: string;
+}
+/**
+ * Run a vector similarity search.
+ *
+ * @param reader    A read-only `better-sqlite3` connection.
+ * @param scope     `'project'` or `'personal'`.
+ * @param embedding Pre-computed query embedding (Float32Array of length `dim`).
+ * @param limit     Max results (clamped by callers).
+ * @returns         Results sorted by ascending distance (closest first).
+ */
+export declare function vecQuery(reader: BetterSqliteDatabase, scope: string, embedding: Float32Array, limit: number): VecResult[];
+/**
+ * Convenience wrapper: embed the query text, then run vecQuery.
+ * Returns [] if the embedder fails (non-fatal on query path).
+ */
+export declare function vecSearch(reader: BetterSqliteDatabase, scope: string, query: string, embedder: Embedder, limit: number): Promise<VecResult[]>;
+//# sourceMappingURL=vec.d.ts.map

package/dist/retrieval/vec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec.d.ts","sourceRoot":"","sources":["../../src/retrieval/vec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,GACZ,SAAS,EAAE,CAgCb;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,EAAE,CAAC,CAOtB"}

package/dist/retrieval/vec.js

@@ -0,0 +1,50 @@
+/**
+ * Run a vector similarity search.
+ *
+ * @param reader    A read-only `better-sqlite3` connection.
+ * @param scope     `'project'` or `'personal'`.
+ * @param embedding Pre-computed query embedding (Float32Array of length `dim`).
+ * @param limit     Max results (clamped by callers).
+ * @returns         Results sorted by ascending distance (closest first).
+ */
+export function vecQuery(reader, scope, embedding, limit) {
+    try {
+        // sqlite-vec expects the embedding as a raw buffer of float32 values.
+        const buf = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+        const rows = reader
+            .prepare(`SELECT c.id AS id, c.text AS text,
+                n.source_uri AS source_uri,
+                n.id AS node_id,
+                v.distance AS distance,
+                n.confidence AS confidence,
+                n.title AS title,
+                n.section_path AS section_path
+           FROM kg_chunks_vec v
+           JOIN kg_chunks c ON c.rowid = v.rowid
+           JOIN kg_nodes n ON c.node_id = n.id
+          WHERE v.embedding MATCH ?
+            AND k = ?
+            AND n.scope = ?
+          ORDER BY v.distance`)
+            .all(buf, limit, scope);
+        return rows;
+    }
+    catch {
+        // Graceful degradation: empty vec table, extension not loaded, etc.
+        return [];
+    }
+}
+/**
+ * Convenience wrapper: embed the query text, then run vecQuery.
+ * Returns [] if the embedder fails (non-fatal on query path).
+ */
+export async function vecSearch(reader, scope, query, embedder, limit) {
+    try {
+        const embedding = await embedder.embed(query);
+        return vecQuery(reader, scope, embedding, limit);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=vec.js.map

package/dist/retrieval/vec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec.js","sourceRoot":"","sources":["../../src/retrieval/vec.ts"],"names":[],"mappings":"AA2BA;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,MAA4B,EAC5B,KAAa,EACb,SAAuB,EACvB,KAAa;IAEb,IAAI,CAAC;QACH,sEAAsE;QACtE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;QAEtF,MAAM,IAAI,GAAG,MAAM;aAChB,OAAO,CAIN;;;;;;;;;;;;;8BAasB,CACvB;aACA,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAE1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAA4B,EAC5B,KAAa,EACb,KAAa,EACb,QAAkB,EAClB,KAAa;IAEb,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/sandbox/bindings/budget.d.ts

@@ -0,0 +1,10 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
+/**
+ * Install the `budget` global with a `fit(items, maxTokens)` method.
+ *
+ * `budget.fit()` is a host-backed function: guest code passes an array of
+ * items and a token budget, the host runs the real `fitResults()` with
+ * js-tiktoken, and the truncated array is returned to the guest.
+ */
+export declare function installBudgetBindings(context: QuickJSContext, maxTokens: number): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/sandbox/bindings/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../src/sandbox/bindings/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,oBAAoB,CAAC;AAMxE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAyCtF"}

package/dist/sandbox/bindings/budget.js

@@ -0,0 +1,44 @@
+import { Scope } from 'quickjs-emscripten';
+import { fitResults } from '../../gate/budget.js';
+import { errorMessage, marshalJsValue } from '../helpers.js';
+/**
+ * Install the `budget` global with a `fit(items, maxTokens)` method.
+ *
+ * `budget.fit()` is a host-backed function: guest code passes an array of
+ * items and a token budget, the host runs the real `fitResults()` with
+ * js-tiktoken, and the truncated array is returned to the guest.
+ */
+export function installBudgetBindings(context, maxTokens) {
+    Scope.withScope((scope) => {
+        const budgetObj = scope.manage(context.newObject());
+        const fitFn = context.newFunction('fit', (...handles) => {
+            try {
+                const items = handles[0] ? context.dump(handles[0]) : [];
+                if (!Array.isArray(items)) {
+                    return context.newError('budget.fit: first argument must be an array');
+                }
+                const budget = typeof handles[1] !== 'undefined'
+                    ? context.dump(handles[1])
+                    : maxTokens;
+                let idx = 0;
+                const result = fitResults(items, budget, (item) => JSON.stringify(item), (item) => {
+                    const obj = item;
+                    if (obj && typeof obj.id === 'string')
+                        return obj.id;
+                    return `[${idx++}]`;
+                }, (item) => {
+                    const obj = item;
+                    return obj && typeof obj.source_uri === 'string' ? obj.source_uri : '';
+                });
+                return marshalJsValue(context, result.kept);
+            }
+            catch (e) {
+                return context.newError(errorMessage(e));
+            }
+        });
+        context.setProp(budgetObj, 'fit', fitFn);
+        fitFn.dispose();
+        context.setProp(context.global, 'budget', budgetObj);
+    });
+}
+//# sourceMappingURL=budget.js.map

package/dist/sandbox/bindings/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/sandbox/bindings/budget.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAuB,EAAE,SAAiB;IAC9E,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACxB,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QAEpD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,OAAwB,EAAE,EAAE;YACvE,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,OAAO,CAAC,QAAQ,CAAC,6CAA6C,CAAC,CAAC;gBACzE,CAAC;gBACD,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW;oBAC9C,CAAC,CAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAY;oBACtC,CAAC,CAAC,SAAS,CAAC;gBAEd,IAAI,GAAG,GAAG,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAG,UAAU,CACvB,KAAK,EACL,MAAM,EACN,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAC9B,CAAC,IAAI,EAAE,EAAE;oBACP,MAAM,GAAG,GAAG,IAA+B,CAAC;oBAC5C,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;wBAAE,OAAO,GAAG,CAAC,EAAE,CAAC;oBACrD,OAAO,IAAI,GAAG,EAAE,GAAG,CAAC;gBACtB,CAAC,EACD,CAAC,IAAI,EAAE,EAAE;oBACP,MAAM,GAAG,GAAG,IAAuC,CAAC;oBACpD,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzE,CAAC,CACF,CAAC;gBAEF,OAAO,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACzC,KAAK,CAAC,OAAO,EAAE,CAAC;QAEhB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/sandbox/bindings/install.d.ts

@@ -0,0 +1,23 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
+import { type KgBindingDeps } from './kg.js';
+/**
+ * All deps needed by the binding surface. Supports single-scope
+ * (project-only or personal-only) and dual-scope (both).
+ *
+ * Privacy invariant: if `personal` is undefined, `kg.personal`
+ * does NOT exist in the sandbox — not undefined, not null, absent.
+ */
+export interface BindingDeps {
+    project?: KgBindingDeps;
+    personal?: KgBindingDeps;
+    maxTokens: number;
+    logs: string[];
+}
+/**
+ * Install all sandbox bindings on a fresh QuickJS context:
+ *   1. `logger.log(...)` capture
+ *   2. `kg.project.*` and/or `kg.personal.*` (scope-dependent)
+ *   3. `budget.fit()`
+ */
+export declare function installBindings(context: QuickJSContext, deps: BindingDeps): void;
+//# sourceMappingURL=install.d.ts.map

package/dist/sandbox/bindings/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/sandbox/bindings/install.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAGhE;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAIhF"}

package/dist/sandbox/bindings/install.js

@@ -0,0 +1,15 @@
+import { installLogger } from './logger.js';
+import { installKgBindings } from './kg.js';
+import { installBudgetBindings } from './budget.js';
+/**
+ * Install all sandbox bindings on a fresh QuickJS context:
+ *   1. `logger.log(...)` capture
+ *   2. `kg.project.*` and/or `kg.personal.*` (scope-dependent)
+ *   3. `budget.fit()`
+ */
+export function installBindings(context, deps) {
+    installLogger(context, deps.logs);
+    installKgBindings(context, deps.project, deps.personal);
+    installBudgetBindings(context, deps.maxTokens);
+}
+//# sourceMappingURL=install.js.map

package/dist/sandbox/bindings/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/sandbox/bindings/install.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAsB,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAgBpD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB,EAAE,IAAiB;IACxE,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AACjD,CAAC"}

package/dist/sandbox/bindings/kg.d.ts

@@ -0,0 +1,29 @@
+import { type QuickJSContext } from 'quickjs-emscripten';
+import type { Repository } from '../../db/repository.js';
+import { type DbBundle } from '../../db/client.js';
+import type { Embedder } from '../../retrieval/embedder.js';
+import { type WriteCounter } from './write.js';
+/**
+ * Dependencies for installing one scope's bindings in the sandbox.
+ */
+export interface KgBindingDeps {
+    repository: Repository;
+    bundle: DbBundle;
+    scope: 'project' | 'personal';
+    embedder: Embedder;
+    wikiRoot?: string;
+    writeCounter?: WriteCounter;
+    queryEmbeddings?: Map<string, Float32Array>;
+}
+/**
+ * Install the `kg` global with `kg.project.*` and/or `kg.personal.*`
+ * bindings plus backward-compat `kg.search()` / `kg.get()` aliases
+ * and `kg.describe()`.
+ *
+ * **Privacy invariant**: if `personalDeps` is undefined, `kg.personal`
+ * does NOT exist in the sandbox — not undefined, not null, simply absent.
+ * This is enforced at the dispatcher level (tool handler decides which
+ * deps to pass). The 15-test adversarial suite verifies this.
+ */
+export declare function installKgBindings(context: QuickJSContext, projectDeps?: KgBindingDeps, personalDeps?: KgBindingDeps): void;
+//# sourceMappingURL=kg.d.ts.map

package/dist/sandbox/bindings/kg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kg.d.ts","sourceRoot":"","sources":["../../../src/sandbox/bindings/kg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAsB,MAAM,oBAAoB,CAAC;AAGpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAI5D,OAAO,EAAgD,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAI7F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,WAAW,CAAC,EAAE,aAAa,EAC3B,YAAY,CAAC,EAAE,aAAa,GAC3B,IAAI,CAmCN"}