codesift-mcp 0.15.3 → 0.17.0

package/dist/storage/sqlite/index-io.js

@@ -1,5 +1,5 @@
 import { recordIndexFootprint } from "../index-footprint.js";
-import { openIndexDb, openReadConnection, readMetaValue, rollbackQuietly, writeMetaValue, } from "./connection.js";
+import { openIndexDb, openReadConnection, readMetaValue, rollbackQuietly, writeMetaValue, maybeCheckpointWal, } from "./connection.js";
 import { rethrowOperational } from "./errors.js";
 import { readMetaExtras } from "./meta.js";
 import { INSERT_FILE_SQL, INSERT_SYMBOL_SQL, fileEntryToRow, fileRowBytes, rowToFileEntry, rowToSymbol, symbolRowBytes, symbolToRow, } from "./rows.js";
@@ -29,11 +29,14 @@ export async function saveIndexSqlite(dbPath, index, opts) {
     const db = await openIndexDb(dbPath);
     db.exec("BEGIN");
     try {
-        writeIndexRows(db, index);
+        await writeIndexRows(db, index);
         if (opts?.sourceComplete === true) {
             db.prepare("DELETE FROM meta WHERE key = ?").run("lossy_v1_migration");
         }
         db.exec("COMMIT");
+        // AFTER the commit, never inside the transaction: a checkpoint cannot run in one, and it must
+        // not be able to fail a write that already succeeded.
+        maybeCheckpointWal(db, dbPath);
     }
     catch (err) {
         rollbackQuietly(db);
@@ -60,15 +63,64 @@ export async function wasLossilyMigrated(dbPath) {
  * as "no index" — so a write killed midway rolls back and the db reads as empty rather than
  * as a partially-populated index that later looks complete.
  */
-function writeIndexRows(db, index) {
+/**
+ * Rows written per turn before the event loop gets a chance to run.
+ *
+ * `node:sqlite` is entirely synchronous — every `.run()` blocks the thread — and this loop used to
+ * hold it for the WHOLE index. Measured on the largest real index here (372,949 symbols, a 732 MB
+ * database): **3.2 seconds of uninterrupted main thread** per full save. In a shared daemon that is
+ * 3.2 seconds during which no other client gets an answer, `/health` included; sampling a stalled
+ * daemon put 41% of main-thread time inside `StatementSync::Run`.
+ *
+ * Yielding does not make the write faster — the work is the same. It makes the SERVER responsive
+ * while the work happens, which is the actual complaint. Measured on that index, longest stall the
+ * event loop saw during a full save:
+ *
+ *     no yielding   the loop never ran at all (0 timer ticks in 3.8 s)
+ *     every 5000    42 ms
+ *     every  500    22 ms
+ *     every  250    22 ms
+ *
+ * 500 and 250 are indistinguishable on responsiveness, and total time between them differed by 30%
+ * across runs on identical work — i.e. noise, not signal, so it did not decide anything. 500 buys
+ * the same 22 ms at half the yields.
+ *
+ * Note the first row is not "0 ms of stall": the timer never fired, so there was nothing to
+ * measure. That is the worst case, not the best.
+ *
+ * Tuning the database instead was tried and rejected on measurement: `cache_size = 64 MB` plus
+ * `synchronous = NORMAL` bought 3% on that same index. The cost is the row count, not the pager.
+ */
+const ROWS_PER_TURN = 500;
+/** Hand the event loop a turn. `setImmediate` runs after I/O callbacks, so pending requests progress. */
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+async function writeIndexRows(db, index) {
     db.exec("DELETE FROM symbols");
     db.exec("DELETE FROM files");
+    // The transaction stays OPEN across these yields, which is safe only because writes to one index
+    // are serialised (see the per-path write lock in index-json-mutations.ts and the mutex in
+    // saveIndexSqlite): a second BEGIN on this shared connection would otherwise fail with
+    // "cannot start a transaction within a transaction". Readers are unaffected — they use a private
+    // connection whose WAL snapshot is fixed at BEGIN.
     const insSym = db.prepare(INSERT_SYMBOL_SQL);
-    for (const sym of index.symbols)
+    let sinceYield = 0;
+    for (const sym of index.symbols) {
         insSym.run(...symbolToRow(sym));
+        if (++sinceYield >= ROWS_PER_TURN) {
+            sinceYield = 0;
+            await yieldToEventLoop();
+        }
+    }
     const insFile = db.prepare(INSERT_FILE_SQL);
-    for (const file of index.files)
+    for (const file of index.files) {
         insFile.run(...fileEntryToRow(file));
+        if (++sinceYield >= ROWS_PER_TURN) {
+            sinceYield = 0;
+            await yieldToEventLoop();
+        }
+    }
     writeMetaValue(db, "repo", index.repo);
     writeMetaValue(db, "root", index.root);
     writeMetaValue(db, "created_at", String(index.created_at));
@@ -98,7 +150,10 @@ export async function importLegacyIndexIfEmpty(dbPath, index) {
             db.exec("ROLLBACK");
             return false; // another process got there first
         }
-        writeIndexRows(db, index);
+        // Yields inside BEGIN IMMEDIATE hold the cross-process write lock a little longer, which is
+        // acceptable here: this runs once per index, when migrating a legacy JSON file, and the guard
+        // it implements is exactly about not letting a second process write meanwhile.
+        await writeIndexRows(db, index);
         db.exec("COMMIT");
         return true;
     }
@@ -152,13 +207,47 @@ export async function importLegacyIndexIfEmpty(dbPath, index) {
  * turning a linear read into a quadratic one exactly on the biggest indexes this exists for.
  */
 const PAGE_TARGET_MS = 50;
-const PAGE_MIN_ROWS = 500;
+/**
+ * The floor was 500 — and 500 is a ROW COUNT, which is the one thing the paragraph above says a page
+ * must not be sized by.
+ *
+ * It held while pages were slow for CPU reasons (GC, allocation), because those vary by maybe an
+ * order of magnitude. It does not hold when the DISK is the slow part. Measured 2026-09-02 with 21
+ * concurrent `npm ci` on this machine: 50,835 IOPS at ~6.9 KB each, the daemon sitting in state `U`
+ * (uninterruptible kernel I/O), `initialize` taking 40 s, and clients giving up and running the rest
+ * of their session with no CodeSift tools at all.
+ *
+ * `node:sqlite` is synchronous by design — DatabaseSync and StatementSync are the entire module,
+ * there is no async class to switch to — so a page is a blocking syscall for as long as the disk
+ * takes. The feedback loop is the right mechanism and was simply not allowed to go low enough:
+ * against a disk 100x slower it wanted a page 100x smaller and could not have one.
+ *
+ * 50 keeps the bulk fetch meaningful — per-ROW yielding was measured to turn the same load into
+ * minutes — while giving the loop an order of magnitude more room to shrink.
+ */
+const PAGE_MIN_ROWS = 50;
 const PAGE_MAX_ROWS = 20_000;
+/**
+ * The FIRST page is the one nothing has measured yet, so it is the one that can block longest. At
+ * 4,000 rows it was a bet that the disk is fast, taken before any evidence — and on a saturated disk
+ * that is a multi-second stall in front of every other client's request, the handshake included.
+ *
+ * Starting at the floor costs two or three extra pages on a fast disk (the loop multiplies back up
+ * to 20,000 within a page or two) and bounds the worst case on a slow one.
+ */
+const PAGE_FIRST_ROWS = PAGE_MIN_ROWS;
+/**
+ * Row count for the next page, aimed at the time budget. Extracted so the adaptation can be tested
+ * directly: a disk-bound stall is not reproducible in a unit test, but the decision it forces is.
+ */
+export function nextPageRows(currentRows, elapsedMs) {
+    return Math.max(PAGE_MIN_ROWS, Math.min(PAGE_MAX_ROWS, Math.round(currentRows * (PAGE_TARGET_MS / Math.max(elapsedMs, 1)))));
+}
 async function readTablePaged(db, table, fn) {
     const stmt = db.prepare(`SELECT rowid AS _rid, * FROM ${table} WHERE rowid > ? ORDER BY rowid LIMIT ?`);
     const out = [];
     let cursor = 0;
-    let rows = 4_000;
+    let rows = PAGE_FIRST_ROWS;
     for (;;) {
         const started = Date.now();
         const page = stmt.all(cursor, rows);
@@ -175,7 +264,7 @@ async function readTablePaged(db, table, fn) {
         // under a daemon already holding several indexes, because allocating a few thousand
         // objects there lands in incremental marking. A fixed row count is therefore tuned for
         // one heap and wrong for the other; a fixed time budget holds in both.
-        rows = Math.max(PAGE_MIN_ROWS, Math.min(PAGE_MAX_ROWS, Math.round(rows * (PAGE_TARGET_MS / Math.max(elapsed, 1)))));
+        rows = nextPageRows(rows, elapsed);
         await new Promise((r) => setImmediate(r));
     }
 }

package/dist/storage/sqlite/index-io.js.map

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

package/dist/storage/sqlite/meta.d.ts

@@ -18,6 +18,13 @@ import type { FileEntry, Workspace } from "../../types.js";
  * `symbol_count` is counted in SQL rather than derived from an array, so it stays a real count.
  */
 export interface IndexSummary {
+    /**
+     * Where this repo's artifacts live. Set by the tool-layer accessor, which knows it from the
+     * registry; absent when a summary is built directly from a database path. Consumers that cache
+     * something alongside the index (the parsed-imports cache) need it, and everything else ignores
+     * it.
+     */
+    indexPath?: string | undefined;
     repo: string;
     root: string;
     files: FileEntry[];

package/dist/storage/sqlite/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACxC,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,YAAY,GAAG,iBAAiB,CAAC,CAmB5E"}
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACxC,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,YAAY,GAAG,iBAAiB,CAAC,CAmB5E"}

package/dist/storage/sqlite/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../../src/storage/sqlite/meta.ts"],"names":[],"mappings":"AAkCA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAyC;IAEzC,MAAM,GAAG,GAA+E,EAAE,CAAC;IAE3F,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC/C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAkC,CAAC;QACzE,IAAI,MAAM,KAAK,IAAI;YAAE,GAAG,CAAC,iBAAiB,GAAG,MAAM,CAAC;IACtD,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAuB,CAAC;QAC/D,IAAI,MAAM,KAAK,IAAI;YAAE,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC;IAC/C,CAAC;IAED,0FAA0F;IAC1F,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,SAAS;QAAE,GAAG,CAAC,eAAe,GAAG,IAAI,CAAC;IAEzE,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../../src/storage/sqlite/meta.ts"],"names":[],"mappings":"AAyCA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAyC;IAEzC,MAAM,GAAG,GAA+E,EAAE,CAAC;IAE3F,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC/C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAkC,CAAC;QACzE,IAAI,MAAM,KAAK,IAAI;YAAE,GAAG,CAAC,iBAAiB,GAAG,MAAM,CAAC;IACtD,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAuB,CAAC;QAC/D,IAAI,MAAM,KAAK,IAAI;YAAE,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC;IAC/C,CAAC;IAED,0FAA0F;IAC1F,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,SAAS;QAAE,GAAG,CAAC,eAAe,GAAG,IAAI,CAAC;IAEzE,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/storage/sqlite/queries.d.ts

@@ -0,0 +1,66 @@
+import type { CodeSymbol } from "../../types.js";
+/**
+ * Ask the database for the rows a tool needs, instead of materialising the whole index.
+ *
+ * A cold `getCodeIndex` builds 349 MB and ~352,000 objects for the largest repo here, through a
+ * synchronous SQLite API, and hands the same object to every caller. Measured against that:
+ *
+ *     WHERE name = ?      9 ms        WHERE kind = ?     32 ms (after idx_symbols_kind)
+ *     WHERE file = ?     10 ms        materialise all   ~10,000 ms
+ *
+ * Three orders of magnitude, and the classification of the 159 call sites says 31% of them need no
+ * array at all — a metadata read or a single WHERE.
+ */
+/**
+ * `withSource` has NO DEFAULT, on purpose.
+ *
+ * `source` is 45% of the footprint — roughly 650 bytes per symbol — and two thirds of call sites
+ * never read it. But omitting the column silently is the dangerous half: `rowToSymbol` does
+ * `if (row.source !== null) sym.source = row.source`, so a projected-away column arrives as
+ * `undefined` and produces a symbol that is INDISTINGUISHABLE from one whose source is genuinely
+ * empty. A caller would read "this function has no body" as a fact about the code.
+ *
+ * Requiring the flag makes the compiler ask the question at every call site. When it is false the
+ * key is omitted entirely rather than set to undefined, so `"source" in symbol` is an honest test.
+ */
+export interface SymbolQuery {
+    withSource: boolean;
+    file?: string;
+    name?: string;
+    /** Prefix only. A leading `%` cannot use idx_symbols_name and degrades to a full scan. */
+    namePrefix?: string;
+    kind?: string;
+    parent?: string;
+    ids?: readonly string[];
+    limit?: number;
+}
+export interface IndexMeta {
+    repo: string;
+    root: string;
+    updatedAt: number;
+    symbolCount: number;
+    fileCount: number;
+}
+export declare function findSymbolsSqlite(dbPath: string, query: SymbolQuery): Promise<CodeSymbol[]>;
+/**
+ * Fold over matching symbols in pages, yielding the event loop between them.
+ *
+ * For the whole-scan callers (bucket A: 37 of 159 call sites) that genuinely have to see every
+ * symbol but never need them all resident at once — regex scanners, adjacency builders, vocabulary
+ * collectors. They fold and discard, so holding 352,000 objects was never the requirement.
+ *
+ * A private read connection, like `loadIndexSqlite`: the pages must come from ONE snapshot, and
+ * this yields between them, so a shared connection could observe another process's commit halfway
+ * through and return a mixture of two states.
+ */
+export declare function streamSymbolsSqlite(dbPath: string, query: SymbolQuery, 
+/** Return `false` to stop early — for callers with a wall-clock budget, which must be able to
+ *  abandon a scan without reading the rest of the table. */
+onBatch: (batch: CodeSymbol[]) => void | boolean | Promise<void | boolean>): Promise<void>;
+/**
+ * Root, repo and counts — for the 26 call sites that materialise 349 MB to read `index.root`, and
+ * the two that materialise it to check whether the index exists at all
+ * (`nest-pipeline-tools.ts:45`, `sql-dml-safety-tools.ts:32`).
+ */
+export declare function getIndexMetaSqlite(dbPath: string): Promise<IndexMeta | null>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/storage/sqlite/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMjD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AA0DD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CA2BvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW;AAClB;4DAC4D;AAC5D,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,GACzE,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAkBlF"}

package/dist/storage/sqlite/queries.js

@@ -0,0 +1,196 @@
+import { openIndexDb, openReadConnection, readMetaValue } from "./connection.js";
+import { rethrowOperational } from "./errors.js";
+import { rowToSymbol } from "./rows.js";
+import { nextPageRows } from "./index-io.js";
+/** Every column except `source`, so the projection can drop the expensive one by name. */
+const COLUMNS_WITHOUT_SOURCE = "id, file, name, kind, start_line, end_line, start_col, end_col, start_byte, end_byte, " +
+    "signature, docstring, parent, is_async, is_exported, extras";
+/**
+ * SQLite's default parameter limit is 999. An `ids` list longer than that is a hard error rather
+ * than a slow query, so it is chunked — and the chunks are unioned by the caller, not by SQL,
+ * because a UNION would have to re-sort.
+ */
+const MAX_BOUND_PARAMS = 900;
+function buildPredicate(query, idChunk) {
+    const clauses = [];
+    const binds = [];
+    if (query.file !== undefined) {
+        clauses.push("file = ?");
+        binds.push(query.file);
+    }
+    if (query.name !== undefined) {
+        clauses.push("name = ?");
+        binds.push(query.name);
+    }
+    if (query.namePrefix !== undefined) {
+        // `LIKE 'x%'` uses idx_symbols_name; the ESCAPE clause keeps a literal % or _ in a symbol name
+        // from turning into a wildcard, which would silently widen the query.
+        clauses.push("name LIKE ? ESCAPE '\\'");
+        binds.push(`${query.namePrefix.replace(/[\\%_]/g, "\\$&")}%`);
+    }
+    if (query.kind !== undefined) {
+        clauses.push("kind = ?");
+        binds.push(query.kind);
+    }
+    if (query.parent !== undefined) {
+        clauses.push("parent = ?");
+        binds.push(query.parent);
+    }
+    if (idChunk !== undefined) {
+        clauses.push(`id IN (${idChunk.map(() => "?").join(",")})`);
+        binds.push(...idChunk);
+    }
+    return { sql: clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "", binds };
+}
+function chunkIds(ids) {
+    if (ids === undefined)
+        return [undefined];
+    if (ids.length === 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < ids.length; i += MAX_BOUND_PARAMS)
+        out.push([...ids.slice(i, i + MAX_BOUND_PARAMS)]);
+    return out;
+}
+/**
+ * Map a row whose `source` column was never selected.
+ *
+ * Not `rowToSymbol` with a patched row: that mapper tests `row.source !== null`, and `undefined`
+ * passes that test. Giving it an explicit null is what keeps the key absent rather than present
+ * and undefined — the distinction the whole `withSource` contract rests on.
+ */
+function rowToSymbolNoSource(row, repo) {
+    return rowToSymbol({ ...row, source: null }, repo);
+}
+export async function findSymbolsSqlite(dbPath, query) {
+    const db = await openIndexDb(dbPath);
+    try {
+        const repo = readMetaValue(db, "repo");
+        if (repo === undefined)
+            return [];
+        const columns = query.withSource ? "*" : COLUMNS_WITHOUT_SOURCE;
+        const out = [];
+        for (const idChunk of chunkIds(query.ids)) {
+            if (query.limit !== undefined && out.length >= query.limit)
+                break;
+            const { sql, binds } = buildPredicate(query, idChunk);
+            const remaining = query.limit === undefined ? undefined : query.limit - out.length;
+            const limitSql = remaining === undefined ? "" : ` LIMIT ${Math.max(0, remaining)}`;
+            const rows = db
+                .prepare(`SELECT ${columns} FROM symbols ${sql}${limitSql}`)
+                .all(...binds);
+            for (const row of rows) {
+                out.push(query.withSource ? rowToSymbol(row, repo) : rowToSymbolNoSource(row, repo));
+            }
+        }
+        return out;
+    }
+    catch (err) {
+        // Corruption surfaces on the first page touched, not at open, and callers use
+        // `isIndexStorageError` to tell a storage fault from "nothing indexed here". Without this the
+        // read falls into the branch that reports an unindexed repo — a fault rendered as an empty
+        // answer, which is the worst shape a search result can take.
+        rethrowOperational(err, dbPath);
+    }
+}
+/**
+ * Fold over matching symbols in pages, yielding the event loop between them.
+ *
+ * For the whole-scan callers (bucket A: 37 of 159 call sites) that genuinely have to see every
+ * symbol but never need them all resident at once — regex scanners, adjacency builders, vocabulary
+ * collectors. They fold and discard, so holding 352,000 objects was never the requirement.
+ *
+ * A private read connection, like `loadIndexSqlite`: the pages must come from ONE snapshot, and
+ * this yields between them, so a shared connection could observe another process's commit halfway
+ * through and return a mixture of two states.
+ */
+export async function streamSymbolsSqlite(dbPath, query, 
+/** Return `false` to stop early — for callers with a wall-clock budget, which must be able to
+ *  abandon a scan without reading the rest of the table. */
+onBatch) {
+    const reader = await openReadConnection(dbPath);
+    try {
+        const repo = readMetaValue(reader, "repo");
+        if (repo === undefined)
+            return;
+        const columns = query.withSource ? "*" : COLUMNS_WITHOUT_SOURCE;
+        reader.exec("BEGIN");
+        try {
+            for (const idChunk of chunkIds(query.ids)) {
+                const { sql, binds } = buildPredicate(query, idChunk);
+                const where = sql === "" ? "WHERE rowid > ?" : `${sql} AND rowid > ?`;
+                const stmt = reader.prepare(`SELECT rowid AS _rid, ${columns} FROM symbols ${where} ORDER BY rowid LIMIT ?`);
+                let cursor = 0;
+                let rows = 50;
+                let seen = 0;
+                for (;;) {
+                    const started = Date.now();
+                    const page = stmt.all(...binds, cursor, rows);
+                    // Terminate on EMPTY, not on a short page.
+                    //
+                    // With the filter in SQL a short page does in fact mean exhaustion — LIMIT counts
+                    // MATCHES, not scanned rows — so `page.length < rows` would be correct today. It is not
+                    // used anyway, for one round-trip: the moment anyone adds a post-fetch filter in JS (the
+                    // obvious way to express a predicate SQL cannot), the short-page test silently becomes
+                    // "stop at the first sparsely-matching stretch and report success". Costing one extra
+                    // query to remove that trap is the right trade in a reader that folds over 352,000 rows.
+                    if (page.length === 0)
+                        break;
+                    cursor = page[page.length - 1]._rid;
+                    const batch = page.map((row) => query.withSource ? rowToSymbol(row, repo) : rowToSymbolNoSource(row, repo));
+                    seen += batch.length;
+                    if (query.limit !== undefined && seen >= query.limit) {
+                        await onBatch(batch.slice(0, batch.length - (seen - query.limit)));
+                        break;
+                    }
+                    if ((await onBatch(batch)) === false)
+                        break;
+                    rows = nextPageRows(rows, Date.now() - started);
+                    await new Promise((resolve) => setImmediate(resolve));
+                }
+            }
+        }
+        finally {
+            try {
+                reader.exec("COMMIT");
+            }
+            catch { /* the close below is what matters */ }
+        }
+    }
+    catch (err) {
+        rethrowOperational(err, dbPath);
+    }
+    finally {
+        try {
+            reader.close();
+        }
+        catch { /* already gone */ }
+    }
+}
+/**
+ * Root, repo and counts — for the 26 call sites that materialise 349 MB to read `index.root`, and
+ * the two that materialise it to check whether the index exists at all
+ * (`nest-pipeline-tools.ts:45`, `sql-dml-safety-tools.ts:32`).
+ */
+export async function getIndexMetaSqlite(dbPath) {
+    const db = await openIndexDb(dbPath);
+    try {
+        const repo = readMetaValue(db, "repo");
+        const root = readMetaValue(db, "root");
+        if (repo === undefined || root === undefined)
+            return null;
+        const symbolCount = db.prepare("SELECT COUNT(*) AS n FROM symbols").get().n;
+        const fileCount = db.prepare("SELECT COUNT(*) AS n FROM files").get().n;
+        return {
+            repo,
+            root,
+            updatedAt: Number(readMetaValue(db, "updated_at") ?? 0),
+            symbolCount,
+            fileCount,
+        };
+    }
+    catch (err) {
+        rethrowOperational(err, dbPath);
+    }
+}
+//# sourceMappingURL=queries.js.map

package/dist/storage/sqlite/queries.js.map

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

package/dist/storage/sqlite/schema.d.ts

@@ -21,7 +21,7 @@
  * id return the first match exactly as the array scan did.
  */
 export declare const SCHEMA_VERSION = 2;
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS files (\n  path          TEXT PRIMARY KEY,\n  language      TEXT NOT NULL,\n  symbol_count  INTEGER NOT NULL,\n  last_modified INTEGER NOT NULL,\n  mtime_ms      INTEGER,\n  stale         INTEGER\n);\n\nCREATE TABLE IF NOT EXISTS symbols (\n  id          TEXT NOT NULL,\n  file        TEXT NOT NULL,\n  name        TEXT NOT NULL,\n  kind        TEXT NOT NULL,\n  start_line  INTEGER NOT NULL,\n  end_line    INTEGER NOT NULL,\n  start_col   INTEGER,\n  end_col     INTEGER,\n  start_byte  INTEGER,\n  end_byte    INTEGER,\n  signature   TEXT,\n  docstring   TEXT,\n  source      TEXT,\n  parent      TEXT,\n  is_async    INTEGER,\n  is_exported INTEGER,\n  extras      TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);\nCREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);\nCREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS files (\n  path          TEXT PRIMARY KEY,\n  language      TEXT NOT NULL,\n  symbol_count  INTEGER NOT NULL,\n  last_modified INTEGER NOT NULL,\n  mtime_ms      INTEGER,\n  stale         INTEGER\n);\n\nCREATE TABLE IF NOT EXISTS symbols (\n  id          TEXT NOT NULL,\n  file        TEXT NOT NULL,\n  name        TEXT NOT NULL,\n  kind        TEXT NOT NULL,\n  start_line  INTEGER NOT NULL,\n  end_line    INTEGER NOT NULL,\n  start_col   INTEGER,\n  end_col     INTEGER,\n  start_byte  INTEGER,\n  end_byte    INTEGER,\n  signature   TEXT,\n  docstring   TEXT,\n  source      TEXT,\n  parent      TEXT,\n  is_async    INTEGER,\n  is_exported INTEGER,\n  extras      TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);\nCREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);\nCREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);\nCREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);\nCREATE INDEX IF NOT EXISTS idx_symbols_parent ON symbols(parent);\n";
 /**
  * v1 -> v2: rebuild `symbols` without the PRIMARY KEY, keeping every row already stored.
  *
@@ -30,5 +30,5 @@ export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS meta (\n  key
  * incomplete for no store at all. This recovers nothing on its own; rows lost under v1 come
  * back when the repo is next indexed from source, which now keeps them.
  */
-export declare const MIGRATE_V1_TO_V2_SQL = "\nALTER TABLE symbols RENAME TO symbols_v1;\nCREATE TABLE symbols (\n  id          TEXT NOT NULL,\n  file        TEXT NOT NULL,\n  name        TEXT NOT NULL,\n  kind        TEXT NOT NULL,\n  start_line  INTEGER NOT NULL,\n  end_line    INTEGER NOT NULL,\n  start_col   INTEGER,\n  end_col     INTEGER,\n  start_byte  INTEGER,\n  end_byte    INTEGER,\n  signature   TEXT,\n  docstring   TEXT,\n  source      TEXT,\n  parent      TEXT,\n  is_async    INTEGER,\n  is_exported INTEGER,\n  extras      TEXT\n);\nINSERT INTO symbols SELECT * FROM symbols_v1;\nDROP TABLE symbols_v1;\nCREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);\nCREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);\nCREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);\n";
+export declare const MIGRATE_V1_TO_V2_SQL = "\nALTER TABLE symbols RENAME TO symbols_v1;\nCREATE TABLE symbols (\n  id          TEXT NOT NULL,\n  file        TEXT NOT NULL,\n  name        TEXT NOT NULL,\n  kind        TEXT NOT NULL,\n  start_line  INTEGER NOT NULL,\n  end_line    INTEGER NOT NULL,\n  start_col   INTEGER,\n  end_col     INTEGER,\n  start_byte  INTEGER,\n  end_byte    INTEGER,\n  signature   TEXT,\n  docstring   TEXT,\n  source      TEXT,\n  parent      TEXT,\n  is_async    INTEGER,\n  is_exported INTEGER,\n  extras      TEXT\n);\nINSERT INTO symbols SELECT * FROM symbols_v1;\nDROP TABLE symbols_v1;\nCREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);\nCREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);\nCREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);\nCREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);\nCREATE INDEX IF NOT EXISTS idx_symbols_parent ON symbols(parent);\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/storage/sqlite/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,eAAO,MAAM,UAAU,+9BAsCtB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,gwBA0BhC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,eAAO,MAAM,UAAU,imCAwCtB,CAAC;AAmCF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,k4BA4BhC,CAAC"}

package/dist/storage/sqlite/schema.js

@@ -59,7 +59,41 @@ CREATE TABLE IF NOT EXISTS symbols (
 CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);
 CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
 CREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);
+CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
+CREATE INDEX IF NOT EXISTS idx_symbols_parent ON symbols(parent);
 `;
+/*
+ * Why `kind` and `parent` are indexed, and why that needed no schema version bump.
+ *
+ * Measured on this machine's largest index (352,166 symbols, 767 MB) BEFORE they existed:
+ *
+ *     WHERE name = ?     9 ms      (idx_symbols_name)
+ *     WHERE file = ?    10 ms      (idx_symbols_file)
+ *     WHERE kind = ?  2128 ms      full table scan
+ *
+ * Every predicate the tool layer filters on is one of those four columns, and `kind` and `parent`
+ * are most of them: `sql-schema-tools.ts:94` (`kind === "field" && parent === sym.id`),
+ * `react-compiler-tools.ts:61` (`kind === "component"`), `php-god-model-tools.ts:88` (methods per
+ * class). Today each runs as a 352k-row scan in JS after materialising the whole index; they are
+ * about to become SQL, and a scan in SQLite is no better than a scan in JS.
+ *
+ * After: kind 32 ms, parent 28 ms — 66x — and the file grew by nothing measurable.
+ *
+ * NO version bump, deliberately. `SCHEMA_SQL` runs on every open and every statement in it is
+ * `IF NOT EXISTS`, so existing databases pick these up by themselves and there is nothing to
+ * migrate. Bumping SCHEMA_VERSION would instead make every older CodeSift refuse these databases
+ * outright ("written by a newer CodeSift"), trading a backward-compatible addition for a one-way
+ * door. An older version simply does not use the new indexes.
+ *
+ * The one cost: an EXISTING large database builds them once, on its first open after the upgrade —
+ * measured 2.26 s + 0.67 s on the 352k-symbol index, inside `openIndexDb`, on the daemon's thread.
+ * A new database pays nothing, because the table is empty when the statements run.
+ *
+ * A composite `(file, kind)` was measured too (0.51 s to build, 26 ms to query) and left out on
+ * purpose: `idx_symbols_file` already narrows a per-file query to a handful of rows, and every
+ * index is paid again on WRITE — `saveIncrementalSqlite` deletes and re-inserts a file's rows on
+ * each edit, and the PostToolUse hook fires that after every agent edit.
+ */
 /**
  * v1 -> v2: rebuild `symbols` without the PRIMARY KEY, keeping every row already stored.
  *
@@ -94,5 +128,7 @@ DROP TABLE symbols_v1;
 CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);
 CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
 CREATE INDEX IF NOT EXISTS idx_symbols_id ON symbols(id);
+CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
+CREATE INDEX IF NOT EXISTS idx_symbols_parent ON symbols(parent);
 `;
 //# sourceMappingURL=schema.js.map

package/dist/storage/sqlite/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/storage/sqlite/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCzB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BnC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/storage/sqlite/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BnC,CAAC"}

package/dist/storage/sqlite-index-store.d.ts

@@ -45,5 +45,7 @@ export { SCHEMA_VERSION } from "./sqlite/schema.js";
 export { closeAllIndexDbs, closeIndexDb, openIndexDb } from "./sqlite/connection.js";
 export type { IndexSummary } from "./sqlite/meta.js";
 export { importLegacyIndexIfEmpty, loadIndexSqlite, saveIndexSqlite, wasLossilyMigrated, } from "./sqlite/index-io.js";
-export { getDataVersion, getFileEntrySqlite, getFileMtimeSqlite, getSymbolsForFileSqlite, loadIndexSummarySqlite, removeFileFromIndexSqlite, saveIncrementalSqlite, } from "./sqlite/accessors.js";
+export { getDataVersion, getFileEntrySqlite, getFileMtimeSqlite, getSymbolsForFileSqlite, loadIndexSummarySqlite, removeFileFromIndexSqlite, saveIncrementalSqlite, indexDbIsPopulated, } from "./sqlite/accessors.js";
+export { findSymbolsSqlite, streamSymbolsSqlite, getIndexMetaSqlite, } from "./sqlite/queries.js";
+export type { SymbolQuery, IndexMeta } from "./sqlite/queries.js";
 //# sourceMappingURL=sqlite-index-store.d.ts.map

package/dist/storage/sqlite-index-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-index-store.d.ts","sourceRoot":"","sources":["../../src/storage/sqlite-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErF,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"sqlite-index-store.d.ts","sourceRoot":"","sources":["../../src/storage/sqlite-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErF,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/storage/sqlite-index-store.js

@@ -44,5 +44,8 @@ export { IndexStorageError, classifyStorageError, isIndexStorageError } from "./
 export { SCHEMA_VERSION } from "./sqlite/schema.js";
 export { closeAllIndexDbs, closeIndexDb, openIndexDb } from "./sqlite/connection.js";
 export { importLegacyIndexIfEmpty, loadIndexSqlite, saveIndexSqlite, wasLossilyMigrated, } from "./sqlite/index-io.js";
-export { getDataVersion, getFileEntrySqlite, getFileMtimeSqlite, getSymbolsForFileSqlite, loadIndexSummarySqlite, removeFileFromIndexSqlite, saveIncrementalSqlite, } from "./sqlite/accessors.js";
+export { getDataVersion, getFileEntrySqlite, getFileMtimeSqlite, getSymbolsForFileSqlite, loadIndexSummarySqlite, removeFileFromIndexSqlite, saveIncrementalSqlite, indexDbIsPopulated, } from "./sqlite/accessors.js";
+// Narrow reads for ADR-004 stage 2. Listed explicitly, like everything else here: adding an export
+// to a submodule should be a decision about this facade, not a side effect of writing a helper.
+export { findSymbolsSqlite, streamSymbolsSqlite, getIndexMetaSqlite, } from "./sqlite/queries.js";
 //# sourceMappingURL=sqlite-index-store.js.map

package/dist/storage/sqlite-index-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-index-store.js","sourceRoot":"","sources":["../../src/storage/sqlite-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAIrF,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"sqlite-index-store.js","sourceRoot":"","sources":["../../src/storage/sqlite-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAIrF,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,mGAAmG;AACnG,gGAAgG;AAChG,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}