syncstaff-mcp 0.2.3

package/dist/lib/index/pages.js

@@ -0,0 +1,357 @@
+import { createHash } from "node:crypto";
+import { discoverSurfaceEdges } from "./surfaces.js";
+import { byCodeUnit } from "./order.js";
+/** Roughly 350 tokens of source, inside every supported encoder's window. */
+export const EMBEDDED_BODY_CHARS = 1400;
+/** Pack chunks to about this size so each embedding is close to full. */
+const CHUNK_TARGET_CHARS = 1200;
+/** Module context carried on every chunk. Roughly 45 tokens of the 512 budget. */
+const SKELETON_CHARS = 180;
+const LICENCE_BANNER = /^\s*\/\*[\s\S]*?\*\//;
+const LEADING_IMPORTS = /^\s*(?:import\b[^\n]*|(?:export|const|let|var)\b[^\n]*\brequire\s*\([^\n]*|from\s+[^\n]*import\b[^\n]*)\n/;
+/**
+ * Tool directives — `eslint-disable`, `@ts-nocheck`, `use strict`, shebangs.
+ *
+ * They sit above the imports, so leaving one in place stops the import
+ * stripper dead and the window fills with dependency names anyway.
+ */
+const LEADING_PRAGMA = /^\s*(?:#![^\n]*|["\']use strict["\'];?|\/\/\s*(?:@ts-|eslint|prettier|global\b|jshint)[^\n]*|\/\*\s*(?:eslint|prettier|global\b|@ts-|jshint)[\s\S]*?\*\/)\n?/;
+/**
+ * Strip the opening of a file that is not about the file.
+ *
+ * Playwright opens all 3,096 of its files with the same 640-character Apache
+ * banner, so nearly half an embedding window was byte-identical across the
+ * corpus, and the rest was import lines naming other modules — the vector leg
+ * was being asked to tell files apart using the text they most have in common.
+ *
+ * A leading block comment is dropped only when it reads as a licence banner:
+ * the first comment in a file is very often the one sentence that best
+ * describes it, and discarding those would cost more than the banners do.
+ */
+export function distillBody(body) {
+    let text = body;
+    const banner = text.match(LICENCE_BANNER)?.[0];
+    if (banner && /copyright|licen[sc]e|SPDX-/i.test(banner))
+        text = text.slice(banner.length);
+    let previous;
+    do {
+        previous = text;
+        text = text.replace(LEADING_PRAGMA, "").replace(LEADING_IMPORTS, "");
+    } while (text !== previous);
+    return text.trimStart();
+}
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const quote = (value) => `\`${value}\``;
+/** Maximum bytes of parser-derived vocabulary carried on one file page. */
+export const MAX_LEXICAL_VOCABULARY_CHARS = 1200;
+const identifierWords = (value) => value
+    .split(/[^A-Za-z0-9_$]+/)
+    .flatMap((part) => part
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .match(/[A-Za-z0-9_$]+/g) ?? [])
+    .filter((word) => word.length >= 3);
+/**
+ * Pull only source phrases that a structural parse cannot name.
+ *
+ * The file body is already searchable, so copying every source token into the
+ * sidecar would merely count the same evidence twice. These are deliberately
+ * narrow signals instead: user-facing strings, route/flag/error text, and
+ * comments or docstrings. They are often the vocabulary a bug report repeats,
+ * while the parser facts contain none of it. The sidecar remains bounded and
+ * candidate-only, so this cannot change stable retrieval or make a long file
+ * win by volume alone.
+ */
+const sourceVocabulary = (source, maxChars) => {
+    if (!source || maxChars <= 0)
+        return [];
+    const phrases = [];
+    const add = (value) => {
+        const normalized = value.replace(/\\([\\'"`])/g, "$1").replace(/\s+/g, " ").trim();
+        // Ignore punctuation-only literals, generated blobs and licence banners.
+        if (normalized.length < 4 || normalized.length > 160 || !/[A-Za-z]{3}/.test(normalized))
+            return;
+        if (/^(?:copyright|spdx-license-identifier|licensed under)\b/i.test(normalized))
+            return;
+        if (!phrases.some((existing) => existing.toLowerCase() === normalized.toLowerCase()))
+            phrases.push(normalized);
+    };
+    // Triple-quoted Python docstrings need their own pass so the generic quote
+    // matcher below cannot split them into three empty strings.
+    for (const match of source.matchAll(/("""([\s\S]{4,160}?)"""|'''([\s\S]{4,160}?)''')/g)) {
+        add(match[2] ?? match[3] ?? "");
+    }
+    // Keep short literals such as flag names and error messages, but not long
+    // serialized payloads or SQL/template blobs that consume the cap without
+    // giving a useful natural-language anchor.
+    for (const match of source.matchAll(/"((?:\\.|[^"\\\r\n]){3,160})"|'((?:\\.|[^'\\\r\n]){3,160})'|`((?:\\.|[^`\\\r\n]){3,160})`/g)) {
+        add(match[1] ?? match[2] ?? match[3] ?? "");
+    }
+    // Line and block comments provide the prose that generated structural cards
+    // cannot. Strip comment markers, and stop at a reasonable sentence budget.
+    for (const match of source.matchAll(/\/\*([\s\S]{4,180}?)\*\/|\/\/([^\r\n]{4,160})|^[ \t]*#[ \t]?([^\r\n]{4,160})/gm)) {
+        add(match[1] ?? match[2] ?? match[3] ?? "");
+    }
+    return phrases;
+};
+/**
+ * Render a deterministic, bounded structural vocabulary for lexical search.
+ *
+ * The source body is already searchable, but BM25 length normalisation makes
+ * a long file a poor place to match a name that occurs once. This sidecar is
+ * intentionally not a code summary: it contains only parser facts that are
+ * useful query anchors, and it is capped so a large file cannot flood the
+ * index. The ordering is most-specific first, then references as a fallback.
+ */
+export function lexicalVocabulary(file, maxChars = MAX_LEXICAL_VOCABULARY_CHARS) {
+    const entries = [];
+    const addEntry = (value) => {
+        if (value?.trim())
+            entries.push(value.trim());
+    };
+    addEntry(file.path);
+    for (const definition of file.result.definitions ?? []) {
+        addEntry(definition.name);
+        addEntry(definition.owner ? `${definition.owner}.${definition.name}` : undefined);
+    }
+    for (const exported of file.result.exports) {
+        addEntry(exported.name);
+        addEntry(exported.from);
+    }
+    for (const imported of file.result.imports) {
+        addEntry(imported.specifier);
+        for (const name of imported.names)
+            addEntry(name);
+        for (const [local, original] of Object.entries(imported.aliases ?? {})) {
+            addEntry(local);
+            addEntry(original);
+        }
+    }
+    for (const call of file.result.calls ?? [])
+        addEntry(call.callee);
+    for (const reference of file.result.references ?? [])
+        addEntry(reference.name);
+    // Parser facts lead because they are the most discriminative and stable
+    // part of the sidecar. Source phrases follow: they recover the wording of
+    // issue reports without letting comments or literals crowd out identifiers.
+    for (const phrase of sourceVocabulary(file.searchText ?? "", maxChars))
+        addEntry(phrase);
+    const seen = new Set();
+    const words = [];
+    let used = 0;
+    for (const entry of entries) {
+        for (const term of [entry, ...identifierWords(entry)]) {
+            const normalized = term.toLowerCase();
+            if (term.length < 3 || seen.has(normalized))
+                continue;
+            const cost = term.length + (words.length ? 1 : 0);
+            if (used + cost > Math.max(0, maxChars))
+                return words.join(" ");
+            seen.add(normalized);
+            words.push(term);
+            used += cost;
+        }
+    }
+    return words.join(" ");
+}
+function filePage(file) {
+    const imports = file.result.imports.map((item) => item.specifier).sort();
+    const exports = file.result.exports.map((item) => `${item.kind} ${item.name}`).sort();
+    const facts = [
+        `Path: ${quote(file.path)}`,
+        `Language: ${file.language ?? "unknown"}`,
+        `Parser: ${file.parser ?? "none"}`,
+        `Exports: ${exports.length ? exports.join(", ") : "none"}`,
+        `Imports: ${imports.length ? imports.join(", ") : "none"}`,
+    ];
+    const summary = `${file.path} is a ${file.language ?? "source"} file with ${exports.length} export${exports.length === 1 ? "" : "s"} and ${imports.length} import${imports.length === 1 ? "" : "s"}.`;
+    const vocabulary = lexicalVocabulary(file);
+    return {
+        page_id: `file:${file.path}`,
+        target_path: file.path,
+        page_type: "file",
+        title: file.path,
+        content: facts.join("\n"),
+        summary,
+        source_hash: file.contentHash,
+        ...(file.searchText ? { body: file.searchText } : {}),
+        ...(vocabulary ? { lexical_vocabulary: vocabulary } : {}),
+    };
+}
+function modulePage(path, files) {
+    const members = files.map((file) => file.path).sort();
+    const source_hash = digest(files.map((file) => `${file.path}\0${file.contentHash}`).sort().join("\n"));
+    return {
+        page_id: `module:${path}`,
+        target_path: path,
+        page_type: "module",
+        title: path || ".",
+        content: [`Module: ${path || "."}`, `Files: ${members.join(", ")}`].join("\n"),
+        summary: `${path || "."} contains ${members.length} indexed file${members.length === 1 ? "" : "s"}.`,
+        source_hash,
+    };
+}
+/**
+ * Split one oversized file into chunks the embedder can actually read.
+ *
+ * A sentence embedder truncates hard, so a single page per file meant the
+ * vector leg saw the first 1,400 characters and nothing else — 8.7% of this
+ * repository's source and 9.3% of Playwright's. Every semantic result so far
+ * was produced through that keyhole.
+ *
+ * Chunks break at definition sites so a symbol is not split down the middle,
+ * and are packed to about a full window so no embedding is spent on a
+ * three-line local constant. Where definitions run out the split falls back to
+ * line boundaries: markdown, JSON and YAML have no symbols at all, and on this
+ * repository 97 oversized files are in that state — chunking on symbols alone
+ * reached only 41.6% coverage against 91.6% with the fallback.
+ *
+ * Chunks are `page_type: "chunk"` and carry the *file's* `target_path`, which
+ * is what lets the vector leg score spans while lexical, delivery and grading
+ * all stay file-level.
+ */
+function chunkPages(file, page) {
+    // Off by default, permanently, and the reason is measured.
+    //
+    // Chunking works as retrieval: +0.0224 recall@10 over 662 paired instances,
+    // 95% CI [0.0064, 0.0390], holding under a cluster bootstrap over epochs.
+    // It costs more than it is worth.
+    //
+    // Charging the benchmark for what is actually delivered — spans where a chunk
+    // won, files otherwise — the per-instance change in tokens to first gold is
+    // **+127%, CI [+76%, +195%]**, above zero on every one of six epochs. The
+    // damage is not on chunked files: on the 190 instances that received a span
+    // the effect is +31% with a CI spanning zero, while on the 472 that received
+    // none it is +166%. Chunking reranks every query but only about one result in
+    // three carries a fragment, so most queries pay the ranking cost and collect
+    // no saving.
+    //
+    // A pooled ratio-of-sums says -10.9% on the same data. That statistic is
+    // dominated by its largest terms and file sizes here span four orders of
+    // magnitude; an agent experiences one query at a time, not a ratio of sums.
+    //
+    // Span delivery is not what failed. It is built, verified (3,972 chunks, 100%
+    // of spans reproduce their chunk exactly) and cost-neutral on its own. What is
+    // rejected is the economic case for chunking on top of it. Re-open this only
+    // with a measurement that beats the per-instance figure above, not a pooled
+    // one.
+    if (process.env.KEEL_CHUNK !== "1" && process.env.CHARTER_CHUNK !== "1")
+        return [];
+    const original = page.body ?? "";
+    const body = distillBody(original);
+    if (body.length <= EMBEDDED_BODY_CHARS)
+        return [];
+    // `distillBody` strips the licence banner, pragmas and leading imports, so an
+    // offset into it is not an offset into the file. Count what was removed once,
+    // and every span below is reported in the file's own line numbers.
+    const strippedLines = original.length > body.length
+        ? original.slice(0, original.length - body.length).split("\n").length - 1
+        : 0;
+    const lineStarts = [];
+    let offset = 0;
+    for (const line of body.split("\n")) {
+        lineStarts.push(offset);
+        offset += line.length + 1;
+    }
+    const atLine = (line) => lineStarts[Math.min(Math.max(line - 1, 0), lineStarts.length - 1)] ?? 0;
+    const declared = [...new Set((file.result.definitions ?? [])
+            .map((definition) => definition.line)
+            .filter((line) => typeof line === "number")
+            .map(atLine))]
+        .sort((a, b) => a - b)
+        .filter((position) => position > 0 && position < body.length);
+    // Fill any run longer than two targets with synthetic line breaks, so a file
+    // with no definitions — or one very long function — is still covered.
+    const breaks = [];
+    let previous = 0;
+    for (const boundary of [...declared, body.length]) {
+        let cursor = previous;
+        while (boundary - cursor > CHUNK_TARGET_CHARS * 2) {
+            const newline = body.indexOf("\n", cursor + CHUNK_TARGET_CHARS);
+            if (newline < 0 || newline >= boundary)
+                break;
+            breaks.push(newline + 1);
+            cursor = newline + 1;
+        }
+        if (boundary < body.length)
+            breaks.push(boundary);
+        previous = boundary;
+    }
+    const spans = [];
+    let start = 0;
+    for (const position of [...new Set(breaks)].sort((a, b) => a - b)) {
+        if (position - start >= CHUNK_TARGET_CHARS) {
+            spans.push([start, position]);
+            start = position;
+        }
+    }
+    spans.push([start, body.length]);
+    if (spans.length < 2)
+        return [];
+    const owners = (file.result.definitions ?? []).filter((definition) => typeof definition.line === "number");
+    const imports = file.result.imports.map((item) => item.specifier).sort();
+    const exports = file.result.exports.map((item) => item.name).sort();
+    return spans.map(([from, to], position) => {
+        // The skeleton stays terse on purpose: it is charged against the same
+        // window as the code, so a verbose one would crowd out the logic it exists
+        // to contextualise.
+        const first = owners.find((definition) => atLine(definition.line) >= from && atLine(definition.line) < to);
+        const label = first ? `${first.owner ? `${first.owner}.` : ""}${first.name}` : `part ${position + 1}`;
+        // Without this a chunk is a semantic orphan: `distillBody` strips the
+        // imports before the split, so every chunk after the first lost the module
+        // context that tells the embedder what kind of file it is looking at, and
+        // chunk zero had it removed on purpose. Bounded hard — the skeleton is
+        // charged against the same window as the code it is meant to explain.
+        const skeleton = [
+            imports.length ? `imports ${imports.slice(0, 8).join(" ")}` : "",
+            exports.length ? `exports ${exports.slice(0, 8).join(" ")}` : "",
+        ].filter(Boolean).join(" ").slice(0, SKELETON_CHARS);
+        return {
+            page_id: `chunk:${file.path}#${position}`,
+            target_path: file.path,
+            page_type: "chunk",
+            title: file.path,
+            content: page.content,
+            summary: `${file.path} — ${label}${skeleton ? ` | ${skeleton}` : ""}`,
+            body: body.slice(from, to),
+            span: {
+                start_line: strippedLines + body.slice(0, from).split("\n").length,
+                // A chunk boundary sits just after a newline, so slicing to it leaves a
+                // trailing empty element that counts as one line too many.
+                end_line: strippedLines + body.slice(0, to).replace(/\n$/, "").split("\n").length,
+            },
+            source_hash: digest(`${file.contentHash}\0${position}`),
+        };
+    });
+}
+/** Render stable retrieval pages from structure only; no provider or network is used. */
+export function generatePages(index) {
+    const pages = index.files.map(filePage);
+    const byPathForChunks = new Map(index.files.map((file, position) => [file, pages[position]]));
+    for (const [file, page] of byPathForChunks)
+        pages.push(...chunkPages(file, page));
+    const groups = new Map();
+    for (const file of index.files) {
+        const parts = file.path.split("/");
+        parts.pop();
+        const path = parts.join("/");
+        const group = groups.get(path) ?? [];
+        group.push(file);
+        groups.set(path, group);
+    }
+    for (const [path, files] of groups)
+        pages.push(modulePage(path, files));
+    return pages.sort((a, b) => byCodeUnit(a.page_id, b.page_id));
+}
+/** Generate pages and attach stylesheet/token/route relationships to their source pages. */
+export function generatePagesWithSurfaces(index, sources) {
+    const pages = generatePages(index);
+    const byPath = new Map(pages.filter((page) => page.page_type === "file").map((page) => [page.target_path, page]));
+    for (const edge of discoverSurfaceEdges(sources)) {
+        const page = byPath.get(edge.from);
+        if (!page)
+            continue;
+        page.content += `\n${edge.kind}: ${edge.to}`;
+        page.summary += ` Related ${edge.kind}: ${edge.to}.`;
+    }
+    return pages;
+}

package/dist/lib/index/persistence.js

@@ -0,0 +1,233 @@
+/**
+ * Durable, local storage for the derived index.
+ *
+ * This database is deliberately a client-side cache. It stores parser output
+ * and index identity beside the checkout; no server code needs to understand
+ * or receive the contents. A single snapshot is enough for the first tier:
+ * the incremental updater can load it, verify hashes, and reparse only the
+ * files that changed.
+ */
+import { DatabaseSync } from "node:sqlite";
+// 2: index_files.search_text — the file's own text, which retrieval needs
+// to match code and comments. A v1 database has no column for it, and
+// restoring one would produce an index that silently searches only
+// structural cards, so the bump forces a rebuild rather than a quiet
+// downgrade.
+const SCHEMA_VERSION = 2;
+/** A local SQLite archive containing the latest FileIndex snapshot. */
+export class IndexSnapshotArchive {
+    database;
+    constructor(databasePath) {
+        this.database = new DatabaseSync(databasePath);
+        this.database.exec(`
+      PRAGMA foreign_keys = ON;
+      -- Negative value is KB, not pages: bounds this client-side cache to
+      -- ~2MB so it can't grow unbounded per agent process
+      -- (tsk_01M1MQ01E1D7JSEHFVE2RCK8DJ).
+      PRAGMA cache_size = -2000;
+      CREATE TABLE IF NOT EXISTS index_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS index_files (
+        path TEXT PRIMARY KEY,
+        content_hash TEXT NOT NULL,
+        language TEXT,
+        parser TEXT,
+        result_json TEXT NOT NULL,
+        search_text TEXT
+      );
+      CREATE TABLE IF NOT EXISTS index_blind_spots (
+        path TEXT PRIMARY KEY,
+        reason TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS index_vectors (
+        cache_key TEXT PRIMARY KEY,
+        vector_json TEXT NOT NULL
+      );
+      -- Per-file coverage facts, stored so "which files in this repo are blind
+      -- spots" is answerable without running an impact query against each one.
+      -- Written separately from putIndex because coverage is derived from the
+      -- graph and the call resolution, which the index alone does not carry and
+      -- putIndex's caller does not have.
+      --
+      -- Keyed by the index fingerprint: facts describe one specific index, and
+      -- serving them beside a different one would be a confidently stale answer,
+      -- which is the failure the whole honesty contract exists to avoid.
+      CREATE TABLE IF NOT EXISTS index_coverage (
+        path TEXT PRIMARY KEY,
+        fingerprint TEXT NOT NULL,
+        fact_json TEXT NOT NULL
+      );
+    `);
+    }
+    /** Replace the current snapshot in one transaction. */
+    putIndex(index, metadata = { indexedCommit: null, indexedAt: null }) {
+        this.database.exec("BEGIN IMMEDIATE");
+        try {
+            this.database.exec("DELETE FROM index_meta; DELETE FROM index_files; DELETE FROM index_blind_spots;");
+            const putMeta = this.database.prepare("INSERT INTO index_meta (key, value) VALUES (?, ?)");
+            putMeta.run("schema_version", String(SCHEMA_VERSION));
+            putMeta.run("root", index.root);
+            putMeta.run("fingerprint", index.fingerprint);
+            putMeta.run("coverage", JSON.stringify(index.coverage));
+            putMeta.run("aliases", JSON.stringify(index.aliases ?? null));
+            putMeta.run("indexed_commit", metadata.indexedCommit ?? "");
+            putMeta.run("indexed_at", metadata.indexedAt ?? "");
+            const putFile = this.database.prepare("INSERT INTO index_files (path, content_hash, language, parser, result_json, search_text) VALUES (?, ?, ?, ?, ?, ?)");
+            for (const file of index.files) {
+                putFile.run(file.path, file.contentHash, file.language, file.parser, JSON.stringify(file.result), file.searchText ?? null);
+            }
+            const putBlindSpot = this.database.prepare("INSERT INTO index_blind_spots (path, reason) VALUES (?, ?)");
+            for (const blindSpot of index.blindSpots)
+                putBlindSpot.run(blindSpot.path, blindSpot.reason);
+            this.database.exec("COMMIT");
+        }
+        catch (error) {
+            this.database.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /** Read the commit and timestamp associated with the current snapshot. */
+    getMetadata() {
+        const commit = this.meta("indexed_commit");
+        const indexedAt = this.meta("indexed_at");
+        return {
+            indexedCommit: commit || null,
+            indexedAt: indexedAt || null,
+        };
+    }
+    /** Read the latest snapshot, or null when this checkout has not been indexed. */
+    getIndex() {
+        const schema = this.meta("schema_version");
+        if (schema === null)
+            return null;
+        if (schema !== String(SCHEMA_VERSION)) {
+            throw new Error(`unsupported local index schema ${JSON.stringify(schema)}`);
+        }
+        const root = this.requiredMeta("root");
+        const fingerprint = this.requiredMeta("fingerprint");
+        const coverage = parseJson(this.requiredMeta("coverage"), "coverage");
+        const aliases = parseJson(this.requiredMeta("aliases"), "aliases");
+        const files = this.database
+            .prepare("SELECT path, content_hash, language, parser, result_json, search_text FROM index_files ORDER BY path")
+            .all()
+            .map((row) => ({
+            path: textColumn(row.path, "path"),
+            contentHash: textColumn(row.content_hash, "content_hash"),
+            language: nullableTextColumn(row.language, "language"),
+            parser: nullableTextColumn(row.parser, "parser"),
+            result: parseJson(textColumn(row.result_json, "result_json"), "file result"),
+            ...(row.search_text === null || row.search_text === undefined
+                ? {}
+                : { searchText: textColumn(row.search_text, "search_text") }),
+        }));
+        const blindSpots = this.database
+            .prepare("SELECT path, reason FROM index_blind_spots ORDER BY path")
+            .all()
+            .map((row) => ({
+            path: textColumn(row.path, "blind spot path"),
+            reason: textColumn(row.reason, "blind spot reason"),
+        }));
+        return { root, fingerprint, aliases: aliases ?? undefined, files, coverage, blindSpots };
+    }
+    /** Read a cached document vector, or null when it has not been embedded locally. */
+    getVector(cacheKey) {
+        const row = this.database
+            .prepare("SELECT vector_json FROM index_vectors WHERE cache_key = ?")
+            .get(cacheKey);
+        if (!row)
+            return null;
+        return vectorJson(textColumn(row.vector_json, "vector_json"));
+    }
+    /** Persist or replace a cached document vector independently of the index snapshot. */
+    putVector(cacheKey, vector) {
+        validateVector(vector);
+        this.database
+            .prepare("INSERT INTO index_vectors (cache_key, vector_json) VALUES (?, ?) " +
+            "ON CONFLICT(cache_key) DO UPDATE SET vector_json = excluded.vector_json")
+            .run(cacheKey, JSON.stringify(vector));
+    }
+    /** Close the local database. Repeated shutdown is harmless. */
+    /**
+     * Replace the stored coverage facts.
+     *
+     * Stamped with the fingerprint of the index they describe. `getCoverage`
+     * refuses to return facts stamped with any other, because coverage attached
+     * to the wrong index is worse than no coverage: it would report a file as
+     * clean on the strength of an analysis of different bytes.
+     */
+    putCoverage(fingerprint, facts) {
+        this.database.exec("BEGIN IMMEDIATE");
+        try {
+            this.database.exec("DELETE FROM index_coverage");
+            const put = this.database.prepare("INSERT INTO index_coverage (path, fingerprint, fact_json) VALUES (?, ?, ?)");
+            // Sorted, so the stored bytes are a function of the facts and not of Map
+            // iteration order — the same determinism rule the rest of the index keeps.
+            for (const path of [...facts.keys()].sort()) {
+                put.run(path, fingerprint, JSON.stringify(facts.get(path)));
+            }
+            this.database.exec("COMMIT");
+        }
+        catch (error) {
+            this.database.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /** Stored facts for this fingerprint, or null when there are none for it. */
+    getCoverage(fingerprint) {
+        const rows = this.database
+            .prepare("SELECT path, fact_json FROM index_coverage WHERE fingerprint = ? ORDER BY path")
+            .all(fingerprint);
+        if (rows.length === 0)
+            return null;
+        const facts = new Map();
+        for (const row of rows)
+            facts.set(row.path, JSON.parse(row.fact_json));
+        return facts;
+    }
+    shutdown() {
+        if (this.database.isOpen)
+            this.database.close();
+    }
+    meta(key) {
+        const row = this.database.prepare("SELECT value FROM index_meta WHERE key = ?").get(key);
+        return row?.value === null || row?.value === undefined ? null : textColumn(row.value, key);
+    }
+    requiredMeta(key) {
+        const value = this.meta(key);
+        if (value === null)
+            throw new Error(`local index is missing metadata ${JSON.stringify(key)}`);
+        return value;
+    }
+}
+function textColumn(value, name) {
+    if (typeof value !== "string")
+        throw new Error(`local index column ${name} is not text`);
+    return value;
+}
+function nullableTextColumn(value, name) {
+    if (value === null || value === undefined)
+        return null;
+    return textColumn(value, name);
+}
+function parseJson(value, name) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`local index ${name} is not valid JSON`, { cause: error });
+    }
+}
+function vectorJson(value) {
+    const parsed = parseJson(value, "vector");
+    if (!Array.isArray(parsed) || parsed.some((component) => typeof component !== "number" || !Number.isFinite(component))) {
+        throw new Error("local index vector must be an array of finite numbers");
+    }
+    return parsed;
+}
+function validateVector(vector) {
+    if (vector.some((component) => !Number.isFinite(component))) {
+        throw new Error("local index vector must contain only finite numbers");
+    }
+}