markindex 0.0.0-stage → 0.1.1

package/dist/llm/summarize.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { generateText } from 'ai';
+import { SUMMARY_TOKEN_THRESHOLD } from '../config.js';
+import { approxTokens } from '../text/tokens.js';
+import { rateLimiterFor } from './rate-limit.js';
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_MAX_RETRIES = 3;
+/** PageIndex caps summaries at about this many words; stated in the prompt. */
+const SUMMARY_WORD_LIMIT = 150;
+/** Outline given to the description prompt is cut to this many chars so it cannot overflow the context. */
+export const OUTLINE_MAX_CHARS = 12_000;
+const OUTLINE_SUMMARY_CHARS = 160;
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+/** Port of PageIndex `generate_node_summary`, plus language and length constraints. */
+export function nodeSummaryPrompt(text) {
+    return `You are given a part of a document, your task is to generate a description of the partial document about what are main points covered in the partial document.
+
+Write the description in the same language as the partial document text. Keep it concise (at most ${SUMMARY_WORD_LIMIT} words).
+
+Partial Document Text: ${text}
+
+Directly return the description, do not include any other text.`;
+}
+/** Port of PageIndex `generate_doc_description`, plus a language constraint. */
+export function docDescriptionPrompt(outline) {
+    return `You are an expert in generating descriptions for a document.
+You are given a structure of a document. Your task is to generate a one-sentence description for the document, which makes it easy to distinguish the document from other documents.
+
+Write the description in the same language as the document structure's titles.
+
+Document Structure:
+${outline}
+
+Directly return the description, do not include any other text.`;
+}
+function flatten(nodes, out = []) {
+    for (const n of nodes) {
+        out.push(n);
+        flatten(n.children, out);
+    }
+    return out;
+}
+/** Nodes of a document that get a summary: blank nodes are skipped; short ones carry their own text. */
+function targets(store, docPath, tree, threshold) {
+    const out = [];
+    for (const node of flatten(tree)) {
+        const text = store.getLines(docPath, node.startLine, node.ownEndLine).join('\n');
+        if (text.trim() === '')
+            continue;
+        const field = node.children.length === 0 ? 'summary' : 'prefixSummary';
+        out.push(node.ownTokens < threshold ? { node, text, field } : { node, text, field, hash: sha256(text) });
+    }
+    return out;
+}
+/** Titles + truncated summaries, indented by depth, cut to OUTLINE_MAX_CHARS. */
+export function buildOutline(tree, maxChars = OUTLINE_MAX_CHARS) {
+    const lines = [];
+    let size = 0;
+    const walk = (nodes, depth) => {
+        for (const n of nodes) {
+            const s = (n.summary ?? n.prefixSummary ?? '').replace(/\s+/g, ' ').trim();
+            const line = `${'  '.repeat(depth)}- ${n.title}${s ? `: ${Array.from(s).slice(0, OUTLINE_SUMMARY_CHARS).join('')}` : ''}`;
+            if (size + line.length + 1 > maxChars)
+                return false;
+            lines.push(line);
+            size += line.length + 1;
+            if (!walk(n.children, depth + 1))
+                return false;
+        }
+        return true;
+    };
+    const complete = walk(tree, 0);
+    if (!complete)
+        lines.push('- ... (outline truncated)');
+    return lines.join('\n');
+}
+async function runPool(items, concurrency, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, worker));
+}
+const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Fills node summaries (leaf -> `summary`, non-leaf -> `prefixSummary` of the node's own text only) and, unless
+ * `describe` is false and the doc has none yet, the document description. Nodes under the threshold use their own
+ * text; others are looked up in the `summaries` cache by sha256 of their own text, then sent to the LLM. A failed
+ * call never throws and never touches the store: it is returned in `failures`, everything that succeeded is saved.
+ */
+export async function summarizeDocument(store, docPath, opts) {
+    const threshold = opts.threshold ?? SUMMARY_TOKEN_THRESHOLD;
+    const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
+    const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const result = { llmCalls: 0, cached: 0, usage: { inputTokens: 0, outputTokens: 0 }, failures: [] };
+    const doc = store.getDoc(docPath);
+    const tree = store.getTree(docPath);
+    if (!doc || !tree)
+        throw new Error(`document not found: ${docPath}`);
+    const limiter = opts.rateLimiter ?? rateLimiterFor(opts.rateLimit);
+    const ask = async (prompt) => {
+        result.llmCalls++;
+        await limiter?.acquire(approxTokens(prompt));
+        const res = await generateText({ model: opts.model, prompt, maxRetries });
+        result.usage.inputTokens += res.usage?.inputTokens ?? 0;
+        result.usage.outputTokens += res.usage?.outputTokens ?? 0;
+        const text = res.text.trim();
+        if (text === '')
+            throw new Error('model returned an empty response');
+        return text;
+    };
+    const summaryByHash = new Map();
+    const pending = new Map();
+    const updates = [];
+    for (const t of targets(store, docPath, tree, threshold)) {
+        if (t.hash === undefined) {
+            updates.push({ nodeId: t.node.nodeId, [t.field]: t.text });
+            continue;
+        }
+        const hit = summaryByHash.get(t.hash) ?? store.getCachedSummary(t.hash);
+        if (hit !== undefined) {
+            summaryByHash.set(t.hash, hit);
+            result.cached++;
+            updates.push({ nodeId: t.node.nodeId, [t.field]: hit });
+        }
+        else {
+            const list = pending.get(t.hash);
+            if (list)
+                list.push(t);
+            else
+                pending.set(t.hash, [t]);
+        }
+    }
+    await runPool([...pending.entries()], concurrency, async ([hash, group]) => {
+        try {
+            const summary = await ask(nodeSummaryPrompt(group[0].text));
+            store.putCachedSummary(hash, summary);
+            for (const t of group)
+                updates.push({ nodeId: t.node.nodeId, [t.field]: summary });
+        }
+        catch (e) {
+            for (const t of group)
+                result.failures.push({ nodeId: t.node.nodeId, message: errorMessage(e) });
+        }
+    });
+    if (updates.length > 0) {
+        try {
+            store.updateNodeSummaries(docPath, updates);
+        }
+        catch (e) {
+            result.failures.push({ nodeId: null, message: `could not save summaries: ${errorMessage(e)}` });
+        }
+    }
+    // No description from an incomplete outline: it would never be regenerated once stored.
+    if (opts.describe !== false && doc.description === undefined && result.failures.length === 0) {
+        try {
+            const description = await ask(docDescriptionPrompt(buildOutline(store.getTree(docPath))));
+            store.setDocDescription(docPath, description);
+        }
+        catch (e) {
+            result.failures.push({ nodeId: null, message: errorMessage(e) });
+        }
+    }
+    return result;
+}
+/**
+ * Dry-run over every indexed document: how many nodes are over the threshold, how many LLM calls a full
+ * `summarizeDocument` pass would make (unique uncached node texts + one description per undescribed document unless
+ * `describe` is false) and the node-text input tokens (description outlines are not counted).
+ */
+export function estimateSummaryCost(store, opts = {}) {
+    const threshold = opts.threshold ?? SUMMARY_TOKEN_THRESHOLD;
+    let nodes = 0;
+    let inputTokens = 0;
+    let descriptions = 0;
+    const seen = new Set();
+    for (const path of store.allDocPaths()) {
+        const tree = store.getTree(path);
+        if (opts.describe !== false && store.getDoc(path).description === undefined)
+            descriptions++;
+        for (const t of targets(store, path, tree, threshold)) {
+            if (t.hash === undefined)
+                continue;
+            nodes++;
+            if (seen.has(t.hash) || store.getCachedSummary(t.hash) !== undefined)
+                continue;
+            seen.add(t.hash);
+            inputTokens += t.node.ownTokens;
+        }
+    }
+    return { nodes, llmCalls: seen.size + descriptions, inputTokens };
+}

package/dist/parse/markdown.d.ts

@@ -0,0 +1,38 @@
+export interface Heading {
+    /** plain heading text, capped at MAX_TITLE_CHARS code points */
+    title: string;
+    level: number;
+    /** 1-based, original file line */
+    line: number;
+    /** last line of the heading (setext headings span two lines) */
+    endLine: number;
+}
+export interface Block {
+    type: string;
+    startLine: number;
+    endLine: number;
+}
+export interface ParsedDoc {
+    /** BOM stripped, split on \r\n, \r or \n (the same line endings mdast counts) */
+    lines: string[];
+    frontmatter?: {
+        startLine: number;
+        endLine: number;
+        data: Record<string, unknown>;
+    };
+    /** direct children of the mdast root only */
+    headings: Heading[];
+    /** top-level non-heading, non-frontmatter nodes */
+    blocks: Block[];
+    /** first line after frontmatter (1 when there is none) */
+    firstContentLine: number;
+}
+export interface ParseOptions {
+    /**
+     * Recognize setext headings (`Title` underlined with `===` / `---`), as CommonMark does. Default true.
+     * Set false for converter output (PDF/HTML → Markdown) that marks page breaks with a bare `---` line right after
+     * a paragraph: `---` then parses as a thematic break and `===` lines as paragraph text.
+     */
+    setext?: boolean;
+}
+export declare function parseMarkdown(src: string, opts?: ParseOptions): ParsedDoc;

package/dist/parse/markdown.js

@@ -0,0 +1,58 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfm } from 'micromark-extension-gfm';
+import { gfmFromMarkdown } from 'mdast-util-gfm';
+import { frontmatter } from 'micromark-extension-frontmatter';
+import { frontmatterFromMarkdown } from 'mdast-util-frontmatter';
+import { toString } from 'mdast-util-to-string';
+import { parse as parseYaml } from 'yaml';
+import { MAX_TITLE_CHARS } from '../config.js';
+const FM = ['yaml', 'toml'];
+const NO_SETEXT = { disable: { null: ['setextUnderline'] } };
+export function parseMarkdown(src, opts = {}) {
+    const text = src.charCodeAt(0) === 0xfeff ? src.slice(1) : src;
+    const lines = text.split(/\r\n|\r|\n/);
+    const root = fromMarkdown(text, {
+        extensions: opts.setext === false ? [gfm(), frontmatter(FM), NO_SETEXT] : [gfm(), frontmatter(FM)],
+        mdastExtensions: [gfmFromMarkdown(), frontmatterFromMarkdown(FM)],
+    });
+    const doc = { lines, headings: [], blocks: [], firstContentLine: 1 };
+    for (const node of root.children) {
+        const pos = node.position;
+        if (!pos)
+            continue;
+        const startLine = pos.start.line;
+        const endLine = pos.end.line;
+        const type = node.type; // 'toml' is absent from mdast's static types
+        if (type === 'yaml' || type === 'toml') {
+            if (!doc.frontmatter) {
+                const value = node.value;
+                doc.frontmatter = { startLine, endLine, data: parseFrontmatter(type, value) };
+                doc.firstContentLine = endLine + 1;
+            }
+        }
+        else if (node.type === 'heading') {
+            doc.headings.push({ title: capTitle(toString(node).trim()), level: node.depth, line: startLine, endLine });
+        }
+        else {
+            doc.blocks.push({ type: node.type, startLine, endLine });
+        }
+    }
+    return doc;
+}
+function capTitle(title) {
+    const cps = Array.from(title);
+    return cps.length <= MAX_TITLE_CHARS ? title : cps.slice(0, MAX_TITLE_CHARS - 1).join('') + '…';
+}
+function parseFrontmatter(kind, value) {
+    if (kind === 'toml')
+        return { raw: value };
+    try {
+        const data = parseYaml(value);
+        return data !== null && typeof data === 'object' && !Array.isArray(data)
+            ? data
+            : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/retrieve.d.ts

@@ -0,0 +1,65 @@
+import { type LanguageModel } from 'ai';
+import { type RateLimiter, type RateLimitOptions } from './llm/rate-limit.js';
+import type { Library } from './library.js';
+export interface Evidence {
+    docPath: string;
+    nodeId: string;
+    titlePath: string[];
+    startLine: number;
+    endLine: number;
+    /** Re-read from the store by line range; never the model's own text. */
+    text: string;
+}
+export interface RetrieveOptions {
+    model: LanguageModel;
+    /** Max model steps (default 12). */
+    maxSteps?: number;
+    /** Stop once cumulative input tokens over completed steps reach this (default 200_000). */
+    maxInputTokens?: number;
+    /** Restrict the search to this folder (prompt-level instruction; the tools take a `folder` argument). */
+    folder?: string;
+    /**
+     * Client-side rate limit, applied before every model step (sliding 60 s window). Input tokens per step are
+     * estimated from the instructions and messages sent (tool definitions are not counted). The estimate is
+     * conservative: it counts the JSON-serialized messages, whose syntax overhead exceeds the text actually tokenized. The same options object
+     * shares one budget across calls, e.g. across the questions of an eval run.
+     */
+    rateLimit?: RateLimitOptions;
+    /** Advanced: use this limiter instead of building one from `rateLimit` (e.g. to share a budget or inject a clock). */
+    rateLimiter?: RateLimiter;
+}
+export interface RetrieveResult {
+    evidence: Evidence[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Number of model steps (generateText round trips) taken. */
+    steps: number;
+    /** 'done': the model finished (selected evidence, or answered without selecting). */
+    stopReason: 'done' | 'budget' | 'max_steps';
+    /** Number of selected items dropped because the doc / node / range was invalid. */
+    dropped: number;
+    /** 'model': from the model's select_evidence call; 'fallback': nodes it read via get_node_content (budget / max_steps). */
+    selectedBy: 'model' | 'fallback';
+    /** True when the model called select_evidence with input that failed validation (no valid selection followed). */
+    invalidSelection: boolean;
+}
+/** Default `RetrieveOptions.maxSteps`. */
+export declare const RETRIEVE_MAX_STEPS = 12;
+/** Default `RetrieveOptions.maxInputTokens`. */
+export declare const RETRIEVE_MAX_INPUT_TOKENS = 200000;
+/**
+ * Built-in evidence retrieval loop. Returns evidence + usage + stopReason, never an answer.
+ *
+ * Termination: `select_evidence` is registered without `execute`; per the AI SDK, a step that calls a tool without
+ * `execute` ends the loop on its own (no extra `hasToolCall` condition needed). Evidence is taken from the last
+ * `select_evidence` call. If it never calls it and the stop is 'budget' or 'max_steps', evidence falls back to the
+ * nodes it successfully read via `get_node_content` (full ranges, most recent first, max 10; selectedBy 'fallback').
+ * Plain-text finish without selecting: evidence []. A select_evidence call failing schema validation is
+ * rejected by the SDK (error fed back, loop continues); if no valid selection follows, `invalidSelection` is true
+ * and the normal budget / max_steps fallback applies.
+ * Invalid refs (unknown doc, unknown node, empty clamped range) are dropped and counted in `dropped`.
+ * `folder` is a prompt-level scoping instruction only.
+ */
+export declare function retrieve(lib: Library, question: string, opts: RetrieveOptions): Promise<RetrieveResult>;

package/dist/retrieve.js

@@ -0,0 +1,174 @@
+import { generateText, stepCountIs, tool } from 'ai';
+import { z } from 'zod';
+import { createAiSdkTools } from './adapters/ai-sdk.js';
+import { estimateInputTokens, rateLimiterFor } from './llm/rate-limit.js';
+import { AGENT_INSTRUCTIONS } from './tools/contract.js';
+import { walk } from './tree/build.js';
+/** Default `RetrieveOptions.maxSteps`. */
+export const RETRIEVE_MAX_STEPS = 12;
+/** Default `RetrieveOptions.maxInputTokens`. */
+export const RETRIEVE_MAX_INPUT_TOKENS = 200_000;
+const FALLBACK_CAP = 10;
+const SELECT_EVIDENCE = 'select_evidence';
+const selectEvidenceInput = z.object({
+    items: z.array(z.object({
+        doc_path: z.string(),
+        node_id: z.string(),
+        start_line: z.number().int().optional(),
+        end_line: z.number().int().optional(),
+    })),
+});
+const EVIDENCE_INSTRUCTIONS = [
+    'You are gathering evidence, not answering. Use the discovery tools to find the relevant sections, read them to confirm,',
+    `then call ${SELECT_EVIDENCE} exactly once with every section (doc_path + node_id, optionally a narrower start_line/end_line) that`,
+    'supports the question. Do not write a final answer; the evidence text is read back from the library by line range.',
+].join(' ');
+/**
+ * Built-in evidence retrieval loop. Returns evidence + usage + stopReason, never an answer.
+ *
+ * Termination: `select_evidence` is registered without `execute`; per the AI SDK, a step that calls a tool without
+ * `execute` ends the loop on its own (no extra `hasToolCall` condition needed). Evidence is taken from the last
+ * `select_evidence` call. If it never calls it and the stop is 'budget' or 'max_steps', evidence falls back to the
+ * nodes it successfully read via `get_node_content` (full ranges, most recent first, max 10; selectedBy 'fallback').
+ * Plain-text finish without selecting: evidence []. A select_evidence call failing schema validation is
+ * rejected by the SDK (error fed back, loop continues); if no valid selection follows, `invalidSelection` is true
+ * and the normal budget / max_steps fallback applies.
+ * Invalid refs (unknown doc, unknown node, empty clamped range) are dropped and counted in `dropped`.
+ * `folder` is a prompt-level scoping instruction only.
+ */
+export async function retrieve(lib, question, opts) {
+    const maxSteps = opts.maxSteps ?? RETRIEVE_MAX_STEPS;
+    const maxInputTokens = opts.maxInputTokens ?? RETRIEVE_MAX_INPUT_TOKENS;
+    const tools = {
+        ...createAiSdkTools(lib),
+        [SELECT_EVIDENCE]: tool({
+            description: 'Submit the final evidence sections. Ends the retrieval.',
+            inputSchema: selectEvidenceInput,
+        }),
+    };
+    const overBudget = ({ steps }) => steps.reduce((sum, s) => sum + (s.usage.inputTokens ?? 0), 0) >= maxInputTokens;
+    const scope = opts.folder
+        ? `\n\nRestrict the search to the folder "${opts.folder}": pass folder="${opts.folder}" to browse/search tools.`
+        : '';
+    const limiter = opts.rateLimiter ?? rateLimiterFor(opts.rateLimit);
+    const res = await generateText({
+        model: opts.model,
+        system: `${AGENT_INSTRUCTIONS}\n\n${EVIDENCE_INSTRUCTIONS}${scope}`,
+        prompt: question,
+        tools,
+        stopWhen: [stepCountIs(maxSteps), overBudget],
+        // prepareStep runs before each model call (AI SDK v7); awaiting here delays the step without any model wrapper.
+        ...(limiter
+            ? {
+                prepareStep: async ({ instructions, messages }) => {
+                    await limiter.acquire(estimateInputTokens([instructions, messages]));
+                    return {};
+                },
+            }
+            : {}),
+    });
+    let selected;
+    let invalidSelection = false;
+    const read = []; // successfully read nodes, first-read order
+    const readKeys = new Set();
+    for (const step of res.steps) {
+        for (const call of step.toolCalls) {
+            if (call.toolName === SELECT_EVIDENCE) {
+                const parsed = selectEvidenceInput.safeParse(call.input);
+                if (parsed.success) {
+                    selected = parsed.data.items;
+                    invalidSelection = false;
+                }
+                else
+                    invalidSelection = true;
+            }
+            else if (call.toolName === 'get_node_content') {
+                const result = step.toolResults.find((r) => r.toolCallId === call.toolCallId);
+                if (!readSucceeded(result?.output))
+                    continue;
+                const input = call.input;
+                if (typeof input.doc_path !== 'string' || !Array.isArray(input.node_ids))
+                    continue;
+                for (const id of input.node_ids) {
+                    if (typeof id !== 'string')
+                        continue;
+                    const key = `${input.doc_path}\0${id}`;
+                    if (readKeys.has(key))
+                        continue;
+                    readKeys.add(key);
+                    read.push({ doc_path: input.doc_path, node_id: id });
+                }
+            }
+        }
+    }
+    let stopReason = 'done';
+    if (selected === undefined) {
+        const input = res.steps.reduce((sum, s) => sum + (s.usage.inputTokens ?? 0), 0);
+        if (input >= maxInputTokens)
+            stopReason = 'budget';
+        else if (res.steps.length >= maxSteps && res.steps.at(-1)?.finishReason === 'tool-calls')
+            stopReason = 'max_steps';
+    }
+    // Budget / max_steps without a selection: fall back to the nodes the model read (most recent first, capped).
+    const useFallback = selected === undefined && stopReason !== 'done';
+    const items = useFallback ? read.slice(-FALLBACK_CAP).reverse() : (selected ?? []);
+    const { evidence, dropped } = resolveEvidence(lib, items);
+    return {
+        evidence,
+        usage: {
+            inputTokens: res.totalUsage.inputTokens ?? 0,
+            outputTokens: res.totalUsage.outputTokens ?? 0,
+        },
+        steps: res.steps.length,
+        stopReason,
+        dropped,
+        selectedBy: useFallback ? 'fallback' : 'model',
+        invalidSelection,
+    };
+}
+function readSucceeded(output) {
+    try {
+        return JSON.parse(String(output)).success === true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveEvidence(lib, items) {
+    const evidence = [];
+    const seen = new Set();
+    let dropped = 0;
+    const nodeIndex = new Map();
+    for (const item of items) {
+        let index = nodeIndex.get(item.doc_path);
+        if (!index) {
+            const roots = lib.store.getDoc(item.doc_path) ? lib.store.getTree(item.doc_path) : undefined;
+            index = new Map();
+            for (const e of walk(roots ?? []))
+                index.set(e.node.nodeId, e);
+            nodeIndex.set(item.doc_path, index);
+        }
+        const hit = index.get(item.node_id);
+        if (!hit) {
+            dropped++;
+            continue;
+        }
+        const startLine = Math.max(hit.node.startLine, item.start_line ?? hit.node.startLine);
+        const endLine = Math.min(hit.node.endLine, item.end_line ?? hit.node.endLine);
+        const key = `${item.doc_path}\0${item.node_id}\0${startLine}\0${endLine}`;
+        if (endLine < startLine || seen.has(key)) {
+            dropped++;
+            continue;
+        }
+        seen.add(key);
+        evidence.push({
+            docPath: item.doc_path,
+            nodeId: item.node_id,
+            titlePath: hit.titlePath,
+            startLine,
+            endLine,
+            text: lib.store.getLines(item.doc_path, startLine, endLine).join('\n'),
+        });
+    }
+    return { evidence, dropped };
+}

package/dist/store/db.d.ts

@@ -0,0 +1,50 @@
+import Database from 'better-sqlite3';
+import type { DocumentRecord, TreeNode } from '../types.js';
+type DB = Database.Database;
+export interface Store {
+    readonly db: DB;
+    getDoc(path: string): DocumentRecord | undefined;
+    /** Direct subfolders (full paths) and a page of the docs directly inside `folder` ('' = library root). */
+    listDocs(folder: string, offset: number, limit: number): {
+        folders: string[];
+        docs: DocumentRecord[];
+        total: number;
+    };
+    allDocPaths(): string[];
+    getTree(path: string): TreeNode[] | undefined;
+    /** 1-based inclusive range, clamped to the document. */
+    getLines(path: string, start: number, end: number): string[];
+    /** Replaces every row of `doc.path` (docs, nodes, lines, FTS) in a single transaction. */
+    replaceDoc(doc: DocumentRecord, tree: TreeNode[], lines: string[]): void;
+    deleteDoc(path: string): void;
+    /**
+     * Writes summaries into the stored node JSON and the `summary` FTS column (segmented; fts_tri is untouched),
+     * in one transaction. Throws (and changes nothing) if a node id does not exist in `docPath`.
+     */
+    updateNodeSummaries(docPath: string, updates: {
+        nodeId: string;
+        summary?: string;
+        prefixSummary?: string;
+    }[]): void;
+    setDocDescription(docPath: string, description: string): void;
+    /** Summary cache keyed by sha256 of a node's own text. */
+    getCachedSummary(contentHash: string): string | undefined;
+    putCachedSummary(contentHash: string, summary: string): void;
+    /** Index-wide key/value settings (e.g. `index_format`). Undefined when unset or the store predates the table. */
+    getMeta(key: string): string | undefined;
+    setMeta(key: string, value: string): void;
+    close(): void;
+}
+export declare class StoreLockedError extends Error {
+    readonly lockFile: string;
+    readonly pid: number | undefined;
+    constructor(lockFile: string, pid: number | undefined);
+}
+/**
+ * Opens (creating if needed) a store file. Write mode takes an exclusive `${file}.lock` holding the pid, created
+ * atomically (temp file + link). A lock whose pid is dead, or an empty / unparsable lock older than 10 s, is taken over. Read-only opens take no lock and never block on a writer (WAL).
+ */
+export declare function openStore(file: string, opts?: {
+    readonly?: boolean;
+}): Store;
+export {};