@plebeiantech/lat.md 0.12.3-fork.15 → 0.12.3-fork.17

package/dist/src/lattice-model.d.ts

@@ -1,3 +1,4 @@
+import type { SearchEvidence, SearchDiagnostics } from './search/types.js';
 import type { ForkFrontmatter } from './fork/frontmatter-fields.js';
 export type Section = {
     id: string;
@@ -72,6 +73,12 @@ export declare function resolveRef(target: string, sectionIds: Set<string>, file
 export type SectionMatch = {
     section: Section;
     reason: string;
-    score?: number;
+    rankScore?: number;
+    semanticSimilarity?: number;
+    lexicalScore?: number;
+    semanticRank?: number;
+    lexicalRank?: number;
+    evidence?: SearchEvidence[];
+    diagnostics?: SearchDiagnostics;
 };
 export declare function findSections(sections: Section[], query: string): SectionMatch[];

package/dist/src/lattice-model.js

@@ -94,8 +94,11 @@ export function buildSectionSlugIndex(sections) {
         const levels = [
             ...stack,
             {
+                id: section.id,
                 depth: section.depth,
-                literal: section.heading.toLowerCase(),
+                literal: section.id
+                    .slice((stack.at(-1)?.id ?? section.file).length + 1)
+                    .toLowerCase(),
                 slug: headingSlug.toLowerCase(),
             },
         ];

package/dist/src/lattice.d.ts

@@ -1,4 +1,4 @@
-import type { LatFrontmatter, MdLink, Ref, Section } from './lattice-model.js';
+import { type LatFrontmatter, type MdLink, type Ref, type Section } from './lattice-model.js';
 import type { Root } from 'mdast';
 import type { Profiler } from './profiler.js';
 export { buildFileIndex, buildSectionSlugIndex, findSections, flattenSections, resolveRef, } from './lattice-model.js';
@@ -9,6 +9,6 @@ export type { ForkFrontmatter, FrontmatterProblem, } from './fork/frontmatter-fi
 export declare function parseFrontmatter(content: string): LatFrontmatter;
 export declare function parseSections(filePath: string, content: string, projectRoot?: string, tree?: Root): Section[];
 export declare function loadAllSections(latticeDir: string, projectRoot?: string, profile?: Profiler): Promise<Section[]>;
-export declare function extractRefs(filePath: string, content: string, projectRoot?: string, tree?: Root): Ref[];
+export declare function extractRefs(filePath: string, content: string, projectRoot?: string, tree?: Root, sections?: Section[]): Ref[];
 /** Extract link destinations and undefined reference syntax. */
 export declare function extractLinks(content: string, tree?: Root): MdLink[];

package/dist/src/lattice.js

@@ -6,6 +6,7 @@ import { parse } from './parser.js';
 import { toPosix } from './path.js';
 import { visit } from 'unist-util-visit';
 import { listLatticeFiles } from './project-discovery.js';
+import { flattenSections, } from './lattice-model.js';
 import { LAT_FIELDS, } from './fork/frontmatter-fields.js';
 export { buildFileIndex, buildSectionSlugIndex, findSections, flattenSections, resolveRef, } from './lattice-model.js';
 export { findLatticeDir, findProjectRoot, listLatticeFiles, } from './project-discovery.js';
@@ -56,14 +57,8 @@ export function parseFrontmatter(content) {
         result.problems = problems;
     return result;
 }
-function headingText(node) {
-    return node.children
-        .filter((c) => c.type === 'text')
-        .map((c) => c.value)
-        .join('');
-}
 /** Extract the rendered text GitHub uses as input to its heading slugger. */
-function githubHeadingText(node) {
+function headingText(node) {
     if (!node || typeof node !== 'object')
         return '';
     const value = node;
@@ -77,7 +72,7 @@ function githubHeadingText(node) {
         return value.data?.alias ?? value.value ?? '';
     }
     if (value.children) {
-        return value.children.map(githubHeadingText).join('');
+        return value.children.map(headingText).join('');
     }
     return '';
 }
@@ -112,6 +107,8 @@ export function parseSections(filePath, content, projectRoot, tree = parse(conte
     const stack = [];
     const flat = [];
     const slugger = new GithubSlugger();
+    const usedIds = new Set();
+    const nextSuffix = new Map();
     visit(tree, 'heading', (node) => {
         const heading = headingText(node);
         const depth = node.depth;
@@ -121,7 +118,14 @@ export function parseSections(filePath, content, projectRoot, tree = parse(conte
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1] : null;
-        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
+        const baseId = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
+        let id = baseId;
+        const key = baseId.toLowerCase();
+        let suffix = nextSuffix.get(key) ?? 1;
+        while (usedIds.has(id.toLowerCase()))
+            id = `${baseId}-${suffix++}`;
+        nextSuffix.set(key, suffix);
+        usedIds.add(id.toLowerCase());
         const section = {
             id,
             heading,
@@ -132,7 +136,7 @@ export function parseSections(filePath, content, projectRoot, tree = parse(conte
             startLine,
             endLine: 0,
             firstParagraph: '',
-            githubSlug: slugger.slug(githubHeadingText(node)),
+            githubSlug: slugger.slug(headingText(node)),
         };
         if (parent) {
             parent.children.push(section);
@@ -190,34 +194,13 @@ export async function loadAllSections(latticeDir, projectRoot = dirname(latticeD
     }
     return all;
 }
-export function extractRefs(filePath, content, projectRoot, tree = parse(content)) {
+export function extractRefs(filePath, content, projectRoot, tree = parse(content), sections = parseSections(filePath, content, projectRoot, tree)) {
     const file = projectRoot
         ? toPosix(relative(projectRoot, filePath)).replace(/\.md$/, '')
         : basename(filePath, '.md');
     const refs = [];
-    // Build a flat list of sections to determine enclosing section for each wiki link
-    const flat = [];
-    visit(tree, 'heading', (node) => {
-        flat.push({
-            id: '', // filled below
-            startLine: node.position.start.line,
-        });
-    });
-    // Re-derive ids using the same logic as parseSections
-    const stack = [];
-    let idx = 0;
-    visit(tree, 'heading', (node) => {
-        const heading = headingText(node);
-        const depth = node.depth;
-        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
-            stack.pop();
-        }
-        const parent = stack.length > 0 ? stack[stack.length - 1] : null;
-        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
-        flat[idx].id = id;
-        stack.push({ id, depth });
-        idx++;
-    });
+    // Reuse canonical identities, including duplicate suffixes and formatted text.
+    const flat = flattenSections(sections);
     visit(tree, 'wikiLink', (node) => {
         const line = node.position.start.line;
         // Find enclosing section: last heading with startLine <= link line

package/dist/src/markdown-analysis.d.ts

@@ -6,6 +6,16 @@ export type MarkdownParagraph = {
     endLine: number;
     text: string;
 };
+/** Source-positioned block facts; never retains the parser AST. */
+export type MarkdownBlock = {
+    type: string;
+    start: number;
+    end: number;
+    startLine: number;
+    endLine: number;
+    language?: string;
+    children: MarkdownBlock[];
+};
 export type MarkdownDestinationLink = {
     kind: 'image' | 'link';
     line: number;
@@ -37,6 +47,7 @@ export type MarkdownFileAnalysis = {
     headingTitles: string[];
     wikiRefs: Ref[];
     paragraphs: MarkdownParagraph[];
+    blocks: MarkdownBlock[];
     markdownLinks: MarkdownDestinationLink[];
     validationLinks: MdLink[];
     indexEntries: string[];

package/dist/src/markdown-analysis.js

@@ -5,6 +5,35 @@ import { extractLinks, extractRefs, parseFrontmatter, parseSections, } from './l
 import { parse } from './parser.js';
 import { toPosix } from './path.js';
 import { analyzeLocalMarkdownDiagnostics, } from './markdown-validation.js';
+function extractBlocks(tree) {
+    const block = (node) => {
+        if (node.position?.start.offset === undefined ||
+            node.position?.end.offset === undefined)
+            return;
+        return {
+            type: node.type,
+            start: node.position.start.offset,
+            end: node.position.end.offset,
+            startLine: node.position.start.line,
+            endLine: node.position.end.line,
+            ...('lang' in node && node.lang ? { language: node.lang } : {}),
+            children: [
+                'list',
+                'listItem',
+                'blockquote',
+                'table',
+                'tableRow',
+            ].includes(node.type)
+                ? ('children' in node ? node.children : [])
+                    .map(block)
+                    .filter((item) => !!item)
+                : [],
+        };
+    };
+    return tree.children
+        .map(block)
+        .filter((item) => !!item);
+}
 function elapsed(work) {
     const start = performance.now();
     return [work(), performance.now() - start];
@@ -96,7 +125,7 @@ function extractIndexEntries(content) {
 export function analyzeMarkdownFile(absolutePath, content, latDir, projectRoot) {
     const [tree, parseMs] = elapsed(() => parse(content));
     const [sections, sectionsMs] = elapsed(() => parseSections(absolutePath, content, projectRoot, tree));
-    const [wikiRefs, refsMs] = elapsed(() => extractRefs(absolutePath, content, projectRoot, tree));
+    const [wikiRefs, refsMs] = elapsed(() => extractRefs(absolutePath, content, projectRoot, tree, sections));
     const [validationLinks, linksMs] = elapsed(() => extractLinks(content, tree));
     const [[paragraphs, markdownLinks, headingTitles], paragraphsMs] = elapsed(() => [
         extractParagraphs(content, tree),
@@ -116,6 +145,7 @@ export function analyzeMarkdownFile(absolutePath, content, latDir, projectRoot)
         headingTitles,
         wikiRefs,
         paragraphs,
+        blocks: extractBlocks(tree),
         markdownLinks,
         validationLinks,
         indexEntries,

package/dist/src/mcp/server.js

@@ -7,7 +7,7 @@ import { plainStyler } from '../context.js';
 import { locateCommand } from '../cli/locate.js';
 import { sectionCommand } from '../cli/section.js';
 import { searchCommand } from '../cli/search.js';
-import { DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_THRESHOLD, } from '../search/search.js';
+import { DEFAULT_SEARCH_LIMIT, DEFAULT_MIN_SIMILARITY, } from '../search/search.js';
 import { expandCommand } from '../cli/expand.js';
 import { checkAllCommand } from '../cli/check.js';
 import { refsCommand } from '../cli/refs.js';
@@ -40,21 +40,21 @@ export async function startMcpServer() {
             .string()
             .describe('Local section id or exact handle:path#fragment target'),
     }, async ({ query }) => toMcp(await sectionCommand(requestContext(), query)));
-    server.tool('lat_search', 'Semantic search across lat.md sections using embeddings', {
+    server.tool('lat_search', 'Hybrid lexical and semantic search across lat.md sections', {
         query: z.string().describe('Search query in natural language'),
         limit: z
             .number()
             .optional()
             .default(DEFAULT_SEARCH_LIMIT)
             .describe(`Max results (default ${DEFAULT_SEARCH_LIMIT})`),
-        threshold: z
+        minSimilarity: z
             .number()
             .min(0)
             .max(1)
             .optional()
-            .default(DEFAULT_SEARCH_THRESHOLD)
-            .describe('Minimum cosine similarity score (default 0.35)'),
-    }, async ({ query, limit, threshold }) => toMcp(await searchCommand(requestContext(), query, { limit, threshold })));
+            .default(DEFAULT_MIN_SIMILARITY)
+            .describe('Minimum cosine similarity score (default 0.20)'),
+    }, async ({ query, limit, minSimilarity }) => toMcp(await searchCommand(requestContext(), query, { limit, minSimilarity })));
     server.tool('lat_expand', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text: input }) => toMcp(await expandCommand(requestContext(), input)));
     server.tool('lat_check', 'Run full lat.md validation: links, code references, indexes, and section structure', {}, async () => toMcp(await checkAllCommand(requestContext())));
     server.tool('lat_refs', 'Find sections that reference a given section via wiki links or @lat code comments', {

package/dist/src/parser-cache.d.ts

@@ -1,5 +1,5 @@
 /** Version of persistent parser outputs and their shared on-disk contract. */
-export declare const PARSER_CACHE_VERSION = 1;
+export declare const PARSER_CACHE_VERSION = 3;
 export type ParsedCacheEntry = {
     version: number;
     contentHash: string;

package/dist/src/parser-cache.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join, relative } from 'node:path';
 import { toPosix } from './path.js';
 /** Version of persistent parser outputs and their shared on-disk contract. */
-export const PARSER_CACHE_VERSION = 1;
+export const PARSER_CACHE_VERSION = 3;
 /** Hash complete parser input bytes for cache invalidation. */
 export function hashParserContent(content) {
     return createHash('sha1').update(content).digest('hex');

package/dist/src/search/cache.d.ts

@@ -0,0 +1,3 @@
+import { SearchDb } from './db.js';
+/** Build a private staging database; readers only open snapshots of search.db. */
+export declare function writeIndex<T>(latDir: string, cacheDir: string | undefined, rebuild: boolean, work: (db: SearchDb, storedModel: string | null) => Promise<T>): Promise<T>;

package/dist/src/search/cache.js

@@ -0,0 +1,71 @@
+import { copyFile, mkdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acquireSearchLock } from './lock.js';
+import { SearchDb, hasIndex, INDEX_FILE, ensureMeta, getStoredModel, } from './db.js';
+/** Retry transient Windows handles without deleting the usable index first. */
+async function withFileRetry(work) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await work();
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            // Windows may briefly retain a staging handle or a reader's copy handle.
+            if (process.platform !== 'win32' ||
+                attempt >= 9 ||
+                !['EBUSY', 'EPERM', 'EACCES'].includes(code ?? ''))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+        }
+    }
+}
+async function removeStaging(path) {
+    for (const suffix of ['', '-wal', '-shm', '-journal'])
+        await withFileRetry(() => rm(path + suffix, { force: true }));
+}
+/** Build a private staging database; readers only open snapshots of search.db. */
+export async function writeIndex(latDir, cacheDir, rebuild, work) {
+    const dir = cacheDir ?? join(latDir, '.cache');
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, '_search.db');
+    const activePath = join(dir, INDEX_FILE);
+    let db;
+    const release = await acquireSearchLock(dir);
+    try {
+        // A crashed writer may have left a partial database and journal behind.
+        await removeStaging(path);
+        const existing = hasIndex(dir);
+        if (existing && !rebuild)
+            await copyFile(activePath, path);
+        db = new SearchDb(path);
+        const model = existing && !rebuild ? await getStoredModel(db) : null;
+        await ensureMeta(db);
+        const changesBefore = (await db.execute('SELECT total_changes() AS n'))
+            .rows[0].n;
+        const result = await work(db, model);
+        const unchanged = existing &&
+            !rebuild &&
+            (await db.execute('SELECT total_changes() AS n')).rows[0].n ===
+                changesBefore;
+        await db.checkpoint();
+        await db.close();
+        db = undefined;
+        if (!unchanged)
+            await withFileRetry(() => rename(path, activePath));
+        return result;
+    }
+    finally {
+        try {
+            await db?.close();
+        }
+        finally {
+            try {
+                await removeStaging(path);
+            }
+            finally {
+                await release();
+            }
+        }
+    }
+}

package/dist/src/search/chunks.d.ts

@@ -0,0 +1,23 @@
+import type { SourceSpan } from './types.js';
+import type { Embedder } from './embedder.js';
+import type { MarkdownFileAnalysis } from '../markdown-analysis.js';
+import type { Section } from '../lattice-model.js';
+export declare const CHUNK_POLICY = "owned-blocks-v1";
+export type Passage = {
+    id: string;
+    sectionId: string;
+    ordinal: number;
+    type: string;
+    spans: SourceSpan[];
+    text: string;
+    input: string;
+    inputHash: string;
+    heading: string;
+    path: string;
+};
+export declare const digest: (text: string) => string;
+export declare function embeddingFingerprint(embedder: Embedder): string;
+/** Find a fitting Unicode-safe prefix without assuming token-count monotonicity. */
+export declare function fittingPrefix(text: string, fits: (text: string) => boolean): number;
+/** Every body block is owned once; headings provide context instead of copied subtrees. */
+export declare function chunkFile(file: MarkdownFileAnalysis, sections: readonly Section[], embedder: Embedder): Passage[];

package/dist/src/search/chunks.js

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto';
+export const CHUNK_POLICY = 'owned-blocks-v1';
+export const digest = (text) => createHash('sha256').update(text).digest('hex');
+export function embeddingFingerprint(embedder) {
+    return `${CHUNK_POLICY}:${embedder.name}:${embedder.dimensions}:${embedder.maxInputTokens}:${embedder.tokenizerFingerprint}`;
+}
+/** Find a fitting Unicode-safe prefix without assuming token-count monotonicity. */
+export function fittingPrefix(text, fits) {
+    if (fits(text))
+        return text.length;
+    let size = text.length;
+    while (size > 0) {
+        size = Math.floor(size / 2);
+        if (size && /[\uD800-\uDBFF]/.test(text[size - 1]))
+            size--;
+        if (size && fits(text.slice(0, size)))
+            return size;
+    }
+    return 0;
+}
+/** Every body block is owned once; headings provide context instead of copied subtrees. */
+export function chunkFile(file, sections, embedder) {
+    const local = embedder.name.startsWith('local:');
+    const target = local ? 192 : 512;
+    const contextBudget = local ? 48 : 96;
+    const source = file.content;
+    const lineStarts = [0];
+    for (let i = 0; i < source.length; i++)
+        if (source[i] === '\n')
+            lineStarts.push(i + 1);
+    const lineAt = (offset) => {
+        let lo = 0, hi = lineStarts.length;
+        while (lo + 1 < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (lineStarts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        return lo + 1;
+    };
+    const own = new Map();
+    const ordered = [...sections].sort((a, b) => a.startLine - b.startLine || a.depth - b.depth);
+    let sectionIndex = 0;
+    let ancestors = [];
+    for (const block of file.blocks) {
+        if (block.type === 'heading' || block.type === 'yaml')
+            continue;
+        while (sectionIndex < ordered.length &&
+            ordered[sectionIndex].startLine <= block.startLine) {
+            const next = ordered[sectionIndex++];
+            ancestors = ancestors.filter((s) => s.endLine >= next.startLine);
+            ancestors.push(next);
+        }
+        ancestors = ancestors.filter((s) => s.endLine >= block.endLine);
+        const owner = ancestors.at(-1);
+        if (!owner)
+            throw new Error(`No section owns ${file.path}:${block.startLine}`);
+        const blocks = own.get(owner.id) ?? [];
+        blocks.push(block);
+        own.set(owner.id, blocks);
+    }
+    const result = [];
+    for (const section of sections) {
+        const headings = section.id.split('#').slice(1);
+        const rawContext = `Section: ${section.heading}\nPage: ${file.headingTitles[0] ?? file.path}\nPath: ${headings.slice(0, -1).join(' > ')}`;
+        const contextLength = fittingPrefix(rawContext, (t) => embedder.countTokens(t) <= contextBudget);
+        const context = rawContext.slice(0, contextLength);
+        const path = headings.slice(0, -1).join(' > ');
+        let ordinal = 0;
+        const inputFor = (text, extra) => {
+            const extraSize = fittingPrefix(extra, (t) => embedder.countTokens(t) <= contextBudget / 2);
+            const fullContext = [extra.slice(0, extraSize), context]
+                .filter(Boolean)
+                .join('\n');
+            const n = fittingPrefix(fullContext, (c) => embedder.countTokens(c) <= contextBudget &&
+                embedder.countTokens(`${c}\n\n${text}`) <= embedder.maxInputTokens);
+            return n ? `${fullContext.slice(0, n)}\n\n${text}` : text;
+        };
+        const fits = (text, extra = '') => embedder.countTokens(text) <= target &&
+            embedder.countTokens(inputFor(text, extra)) <= embedder.maxInputTokens;
+        const split = (block, extra = '') => {
+            const text = source.slice(block.start, block.end);
+            if (fits(text, extra))
+                return [
+                    { start: block.start, end: block.end, type: block.type, extra },
+                ];
+            if (block.children.length) {
+                const pieces = [];
+                let start = block.start;
+                for (let i = 0; i < block.children.length; i++) {
+                    const child = block.children[i];
+                    const end = i + 1 < block.children.length
+                        ? block.children[i + 1].start
+                        : block.end;
+                    let label = extra;
+                    if (block.type === 'table')
+                        label = `Row: ${i}\nTable headers: ${source.slice(block.children[0].start, block.children[0].end)}\n${extra}`;
+                    if (block.type === 'tableRow')
+                        label = `Column: ${i + 1}\n${extra}`;
+                    if (block.type === 'listItem')
+                        label += `\nList item: ${text.split('\n')[0]}`;
+                    pieces.push(...split({ ...child, start, end }, label));
+                    start = end;
+                }
+                return pieces;
+            }
+            const pieces = [];
+            let start = block.start;
+            const label = block.type === 'code'
+                ? `${extra}\nCode: ${block.language ?? ''}`
+                : extra;
+            while (start < block.end) {
+                const rest = source.slice(start, block.end);
+                let n = fittingPrefix(rest, (t) => fits(t, label));
+                if (!n)
+                    throw new Error(`Cannot fit source text at ${file.path}:${lineAt(start)}`);
+                if (n < rest.length) {
+                    const prefix = rest.slice(0, n);
+                    const boundary = block.type === 'code'
+                        ? prefix.lastIndexOf('\n') + 1
+                        : [...prefix.matchAll(/[.!?](?:\s+|$)/g)].at(-1)?.index;
+                    const preferred = typeof boundary === 'number' && boundary > n / 2
+                        ? boundary
+                        : prefix.search(/\s+\S*$/);
+                    if (preferred > n / 2 && fits(rest.slice(0, preferred), label))
+                        n = preferred;
+                }
+                pieces.push({ start, end: start + n, type: block.type, extra: label });
+                start += n;
+            }
+            return pieces;
+        };
+        const pieces = (own.get(section.id) ?? []).flatMap((block) => split(block));
+        if (!pieces.length) {
+            const start = lineStarts[section.startLine - 1] ?? 0;
+            const end = source.indexOf('\n', start);
+            pieces.push(...split({
+                type: 'heading',
+                start,
+                end: end < 0 ? source.length : end,
+                startLine: section.startLine,
+                endLine: section.startLine,
+                children: [],
+            }));
+        }
+        let pending;
+        const emit = (piece) => {
+            const text = source.slice(piece.start, piece.end);
+            if (!text.trim())
+                return;
+            const input = inputFor(text, piece.extra);
+            if (embedder.countTokens(input) > embedder.maxInputTokens)
+                throw new Error('Chunk exceeds embedding limit');
+            const inputHash = digest(`${embeddingFingerprint(embedder)}\0${input}`);
+            result.push({
+                id: `${section.id}:${ordinal}`,
+                sectionId: section.id,
+                ordinal: ordinal++,
+                type: piece.type,
+                spans: [
+                    {
+                        start: piece.start,
+                        end: piece.end,
+                        startLine: lineAt(piece.start),
+                        endLine: lineAt(Math.max(piece.start, piece.end - 1)),
+                    },
+                ],
+                text,
+                input,
+                inputHash,
+                heading: section.heading,
+                path,
+            });
+        };
+        for (const piece of pieces) {
+            if (pending &&
+                !pending.extra &&
+                !piece.extra &&
+                !source.slice(pending.end, piece.start).trim() &&
+                fits(source.slice(pending.start, piece.end)))
+                pending = {
+                    ...pending,
+                    end: piece.end,
+                    type: pending.type === piece.type ? piece.type : 'mixed',
+                };
+            else {
+                if (pending)
+                    emit(pending);
+                pending = piece;
+            }
+        }
+        if (pending)
+            emit(pending);
+    }
+    return result;
+}

package/dist/src/search/db.d.ts

@@ -1,16 +1,27 @@
-import { type Client } from '@libsql/client';
-export declare function openDb(latDir: string, requestedCacheDir?: string): Client;
-/** Create the `meta` key/value table if absent. */
-export declare function ensureMeta(db: Client): Promise<void>;
-/**
- * The embedding backend this index was built with, e.g. `local:minilm-l6-v2:384`
- * or `openai:1536`. This record is *authoritative*: it governs which backend
- * `lat search` uses. Null when the index has never been built.
- */
-export declare function getStoredModel(db: Client): Promise<string | null>;
-export declare function setStoredModel(db: Client, value: string): Promise<void>;
-/** Create the `sections` table (fixed-width vector column) + index if absent. */
-export declare function ensureSectionsSchema(db: Client, dimensions: number): Promise<void>;
-/** Drop the vector table (used by `lat reindex` before a full rebuild). */
-export declare function dropSections(db: Client): Promise<void>;
-export declare function closeDb(db: Client): Promise<void>;
+export declare const INDEX_FILE = "search.db";
+export declare const CREATE_PASSAGE_FTS = "CREATE INDEX IF NOT EXISTS chunks_fts ON lexical_chunks USING fts(body,heading,path) WITH (tokenizer='whitespace',weights='body=1.0,heading=2.0,path=0.5')";
+export declare function hasIndex(cacheDir: string): boolean;
+/** Small SQL adapter; callers never depend on a libSQL connection. */
+export declare class SearchDb {
+    readonly path: string;
+    private readonly snapshot;
+    private connection;
+    constructor(path: string, snapshot?: boolean);
+    private snapshotDir;
+    private get;
+    execute(statement: string | {
+        sql: string;
+        args?: any[];
+    }): Promise<{
+        rows: any[];
+    }>;
+    close(): Promise<void>;
+    checkpoint(): Promise<void>;
+}
+export declare function openDb(latDir: string, requestedCacheDir?: string, readOnly?: boolean): SearchDb;
+export declare function ensureMeta(db: SearchDb): Promise<void>;
+export declare function getStoredModel(db: SearchDb): Promise<string | null>;
+export declare function setStoredModel(db: SearchDb, value: string): Promise<void>;
+export declare function ensureSectionsSchema(db: SearchDb, _dimensions: number): Promise<void>;
+export declare function dropSections(db: SearchDb): Promise<void>;
+export declare function closeDb(db: SearchDb): Promise<void>;