@cruxy/cli 0.1.1 → 0.2.0

package/dist/indexing/embedder.js

@@ -0,0 +1,140 @@
+import { promises as fs } from "node:fs";
+import { l2normalize } from "./util.js";
+/**
+ * Output dimensionality of bge-small-en-v1.5, and the default size of the
+ * hashing embedder's feature space, so the two backends are interchangeable in
+ * the store schema.
+ */
+export const DEFAULT_DIM = 384;
+// ── Hashing embedder ────────────────────────────────────────────────────────
+/** 32-bit FNV-1a hash of a string. Deterministic and dependency-free. */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        // h *= 16777619, kept in 32-bit range via Math.imul.
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Split text into lowercase lexical tokens, breaking identifiers on camelCase
+ * and snake/kebab boundaries so `getUserById` contributes `get`/`user`/`by`/`id`.
+ */
+export function tokenize(text) {
+    const tokens = [];
+    for (const word of text.match(/[A-Za-z0-9]+/g) ?? []) {
+        for (const sub of word.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Za-z])(?=[0-9])/)) {
+            if (sub)
+                tokens.push(sub.toLowerCase());
+        }
+    }
+    return tokens;
+}
+/**
+ * A deterministic, dependency-free embedder: signed feature hashing
+ * (bag-of-words) over code-aware tokens, L2-normalized. It captures lexical
+ * overlap rather than true semantics, but it is offline, instant, and stable —
+ * which makes it the right default for tests and a sane fallback when the native
+ * embedding model is unavailable.
+ */
+export class HashingEmbedder {
+    id;
+    dim;
+    constructor(opts = {}) {
+        this.dim = opts.dim ?? DEFAULT_DIM;
+        this.id = `hash:v1:${this.dim}`;
+    }
+    async embed(texts) {
+        return texts.map((t) => this.embedOne(t));
+    }
+    async embedQuery(text) {
+        return this.embedOne(text);
+    }
+    embedOne(text) {
+        const v = new Float32Array(this.dim);
+        for (const tok of tokenize(text)) {
+            const bucket = fnv1a(tok) % this.dim;
+            // A second hash supplies a sign, halving the bias from bucket collisions.
+            const sign = (fnv1a(`#${tok}`) & 1) === 0 ? 1 : -1;
+            v[bucket] += sign;
+        }
+        return l2normalize(v);
+    }
+}
+/**
+ * Local semantic embeddings via fastembed (ONNX), model bge-small-en-v1.5
+ * (384-dim). The native dependency is imported lazily on first use, so merely
+ * registering the `search_codebase` tool stays cheap and the heavy ONNX runtime
+ * only loads when an index is actually built or queried.
+ *
+ * Embedding is CPU-bound and single-threaded inside ONNX, so throughput is
+ * bounded by `batchSize` (fed sequentially through fastembed's batching
+ * generator) rather than by JS-level concurrency.
+ */
+export class FastEmbedEmbedder {
+    id = "fastembed:bge-small-en-v1.5";
+    dim = DEFAULT_DIM;
+    opts;
+    model = null;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    getModel() {
+        if (!this.model) {
+            this.model = (async () => {
+                const mod = await import("fastembed");
+                // fastembed's init does a non-recursive mkdir of the cache dir, so it
+                // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
+                if (this.opts.cacheDir) {
+                    await fs.mkdir(this.opts.cacheDir, { recursive: true });
+                }
+                return (await mod.FlagEmbedding.init({
+                    model: mod.EmbeddingModel.BGESmallENV15,
+                    maxLength: this.opts.maxLength ?? 512,
+                    cacheDir: this.opts.cacheDir,
+                    showDownloadProgress: this.opts.showDownloadProgress ?? false,
+                }));
+            })();
+        }
+        return this.model;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const model = await this.getModel();
+        const out = [];
+        for await (const batch of model.embed(texts, this.opts.batchSize ?? 32)) {
+            for (const vec of batch)
+                out.push(l2normalize(Float32Array.from(vec)));
+        }
+        return out;
+    }
+    async embedQuery(text) {
+        const model = await this.getModel();
+        return l2normalize(Float32Array.from(await model.queryEmbed(text)));
+    }
+}
+/**
+ * Build the **production** embedder: fastembed / bge-small-en-v1.5.
+ *
+ * The native dependency is loaded eagerly here so a missing or broken install
+ * fails *now*, loudly, with an actionable message — rather than silently
+ * degrading search quality at query time. There is deliberately **no** fallback
+ * to {@link HashingEmbedder}: that backend is reachable only by explicit
+ * injection in tests (see `getIndexService`'s `deps.embedder`), never selected
+ * automatically by this factory or by config.
+ *
+ * @throws if the fastembed native module cannot be loaded.
+ */
+export async function createEmbedder(opts = {}) {
+    try {
+        await import("fastembed");
+    }
+    catch (err) {
+        throw new Error(`the local embedding model (fastembed) could not be loaded: ${err.message}. ` +
+            "It requires the onnxruntime-node native addon — reinstall with `pnpm install` and " +
+            "ensure the native build completed. The codebase index is unavailable until this is fixed.");
+    }
+    return new FastEmbedEmbedder({ cacheDir: opts.cacheDir });
+}

package/dist/indexing/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./util.js";
+export * from "./chunker.js";
+export * from "./embedder.js";
+export * from "./store.js";
+export * from "./walker.js";
+export * from "./indexer.js";
+export * from "./retriever.js";
+export * from "./service.js";

package/dist/indexing/index.js

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./util.js";
+export * from "./chunker.js";
+export * from "./embedder.js";
+export * from "./store.js";
+export * from "./walker.js";
+export * from "./indexer.js";
+export * from "./retriever.js";
+export * from "./service.js";

package/dist/indexing/indexer.d.ts

@@ -0,0 +1,45 @@
+import { type ChunkOptions } from "./chunker.js";
+import type { Embedder } from "./embedder.js";
+import type { VectorStore } from "./store.js";
+import type { IndexStats } from "./types.js";
+/** Minimal logger surface the indexer reports progress to. */
+interface IndexerLogger {
+    debug(message: string): void;
+    info(message: string): void;
+}
+export interface IndexerOptions {
+    /** Absolute project root to index. */
+    root: string;
+    /** Where embeddings are stored. */
+    store: VectorStore;
+    /** How text is turned into vectors. */
+    embedder: Embedder;
+    /** Hard per-file size cap, in bytes. */
+    maxFileBytes: number;
+    /** Chunking parameters. */
+    chunk: ChunkOptions;
+    /** Concurrency for reading/hashing files. */
+    readConcurrency?: number;
+    /** Files chunked + embedded + upserted per batch (bounds peak memory). */
+    fileBatchSize?: number;
+    /** Optional progress logger. */
+    logger?: IndexerLogger;
+}
+/**
+ * Orchestrates the index: walk → hash → (skip unchanged | chunk → embed →
+ * upsert) → purge removed.
+ *
+ * Incrementality is content-hash based: a file is re-embedded only when its
+ * bytes change; unchanged files are skipped; files that disappeared (deleted or
+ * newly ignored) are purged. Changing the embedder (a new model or dimension)
+ * invalidates the whole index — its signature is stored, and a mismatch forces a
+ * full re-embed so vectors never mix across models.
+ */
+export declare class Indexer {
+    private readonly opts;
+    constructor(opts: IndexerOptions);
+    index(runOpts?: {
+        force?: boolean;
+    }): Promise<IndexStats>;
+}
+export {};

package/dist/indexing/indexer.js

@@ -0,0 +1,104 @@
+import { promises as fs } from "node:fs";
+import { chunkFile } from "./chunker.js";
+import { contentHash, isBinary, mapLimit } from "./util.js";
+import { walkRepo } from "./walker.js";
+const DEFAULT_READ_CONCURRENCY = 8;
+const DEFAULT_FILE_BATCH = 64;
+/**
+ * Orchestrates the index: walk → hash → (skip unchanged | chunk → embed →
+ * upsert) → purge removed.
+ *
+ * Incrementality is content-hash based: a file is re-embedded only when its
+ * bytes change; unchanged files are skipped; files that disappeared (deleted or
+ * newly ignored) are purged. Changing the embedder (a new model or dimension)
+ * invalidates the whole index — its signature is stored, and a mismatch forces a
+ * full re-embed so vectors never mix across models.
+ */
+export class Indexer {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async index(runOpts = {}) {
+        const started = Date.now();
+        const { store, embedder, root, logger } = this.opts;
+        // Embedder-signature gate: a change (or an explicit --force) re-embeds all.
+        const meta = store.getMeta();
+        const signatureChanged = meta !== null &&
+            (meta.embedderId !== embedder.id || meta.dim !== embedder.dim);
+        const force = Boolean(runOpts.force) || meta === null || signatureChanged;
+        if (signatureChanged) {
+            logger?.info(`embedder changed (${meta.embedderId} → ${embedder.id}); re-embedding the whole index`);
+            for (const path of store.getFileHashes().keys())
+                store.deleteByPath(path);
+        }
+        store.setMeta({ embedderId: embedder.id, dim: embedder.dim });
+        const previousHashes = store.getFileHashes();
+        const seen = new Set();
+        // 1. Walk the repo into a candidate list.
+        const entries = [];
+        for await (const entry of walkRepo(root, {
+            maxFileBytes: this.opts.maxFileBytes,
+        })) {
+            entries.push({ relPath: entry.relPath, absPath: entry.absPath });
+        }
+        // 2. Read + hash candidates, deciding which changed (bounded concurrency).
+        const results = await mapLimit(entries, this.opts.readConcurrency ?? DEFAULT_READ_CONCURRENCY, async (entry) => {
+            const buf = await fs.readFile(entry.absPath);
+            // The walker already sniffed binaries; re-check in case the file changed
+            // between walk and read.
+            if (isBinary(buf))
+                return null;
+            seen.add(entry.relPath);
+            const hash = contentHash(buf);
+            if (!force && previousHashes.get(entry.relPath) === hash) {
+                return null; // unchanged
+            }
+            return { relPath: entry.relPath, text: buf.toString("utf8"), hash };
+        });
+        const changed = results.filter((r) => r !== null);
+        // `seen` holds readable text candidates (changed + unchanged); the rest are
+        // unchanged. Files that turned binary/unreadable aren't seen and collapse
+        // into purges below.
+        const filesSkipped = seen.size - changed.length;
+        // 3. Chunk → embed → upsert, batched by file to bound peak memory.
+        let chunksIndexed = 0;
+        const batchSize = this.opts.fileBatchSize ?? DEFAULT_FILE_BATCH;
+        for (let i = 0; i < changed.length; i += batchSize) {
+            const batch = changed.slice(i, i + batchSize);
+            const chunked = batch.map((f) => ({
+                relPath: f.relPath,
+                hash: f.hash,
+                chunks: chunkFile(f.relPath, f.text, this.opts.chunk),
+            }));
+            const texts = chunked.flatMap((f) => f.chunks.map((c) => c.text));
+            const vectors = texts.length > 0 ? await embedder.embed(texts) : [];
+            let v = 0;
+            for (const file of chunked) {
+                const embedded = file.chunks.map((chunk) => ({
+                    chunk,
+                    vector: vectors[v++],
+                }));
+                store.upsertFile(file.relPath, file.hash, embedded);
+                chunksIndexed += embedded.length;
+            }
+            logger?.debug(`indexed ${Math.min(i + batchSize, changed.length)}/${changed.length} changed files`);
+        }
+        // 4. Purge anything previously indexed that we no longer saw.
+        let filesPurged = 0;
+        for (const path of store.getFileHashes().keys()) {
+            if (!seen.has(path)) {
+                store.deleteByPath(path);
+                filesPurged++;
+            }
+        }
+        return {
+            filesSeen: seen.size,
+            filesIndexed: changed.length,
+            filesSkipped,
+            filesPurged,
+            chunksIndexed,
+            durationMs: Date.now() - started,
+        };
+    }
+}

package/dist/indexing/retriever.d.ts

@@ -0,0 +1,32 @@
+import type { Embedder } from "./embedder.js";
+import type { VectorStore } from "./store.js";
+import type { SearchHit } from "./types.js";
+/** Inputs to {@link searchCodebase}. */
+export interface SearchOptions {
+    query: string;
+    /** Number of hits to return; falls back to `defaultK`. Clamped to [1, 50]. */
+    k?: number;
+    /** Optional glob restricting results by path, e.g. `src/**\/*.ts`. */
+    pathGlob?: string;
+}
+/** Collaborators + budget knobs for the retriever. */
+export interface RetrieverDeps {
+    store: VectorStore;
+    embedder: Embedder;
+    /** `k` used when the caller omits it. */
+    defaultK: number;
+    /** Approximate combined-snippet token budget (chars/4 heuristic). */
+    tokenBudget: number;
+    /** Maximum lines kept in any single snippet. */
+    maxSnippetLines: number;
+}
+/**
+ * Embed the query, run a cosine top-k over the index, and return ranked hits.
+ *
+ * Results are token-budgeted: snippets are trimmed to `maxSnippetLines`, then
+ * hits are appended only while the combined snippet estimate stays under
+ * `tokenBudget` — except the top hit, which is always included so a single large
+ * match is never dropped. This keeps tool output from flooding the agent's
+ * context window.
+ */
+export declare function searchCodebase(deps: RetrieverDeps, opts: SearchOptions): Promise<SearchHit[]>;

package/dist/indexing/retriever.js

@@ -0,0 +1,53 @@
+import { estimateTokens, globToRegExp } from "./util.js";
+const MAX_K = 50;
+/**
+ * Embed the query, run a cosine top-k over the index, and return ranked hits.
+ *
+ * Results are token-budgeted: snippets are trimmed to `maxSnippetLines`, then
+ * hits are appended only while the combined snippet estimate stays under
+ * `tokenBudget` — except the top hit, which is always included so a single large
+ * match is never dropped. This keeps tool output from flooding the agent's
+ * context window.
+ */
+export async function searchCodebase(deps, opts) {
+    const k = clamp(opts.k ?? deps.defaultK, 1, MAX_K);
+    const pathFilter = opts.pathGlob ? buildPathFilter(opts.pathGlob) : undefined;
+    const queryVector = await deps.embedder.embedQuery(opts.query);
+    const records = deps.store.search(queryVector, k, pathFilter);
+    const hits = [];
+    let remaining = deps.tokenBudget;
+    for (const record of records) {
+        const snippet = trimSnippet(record.text, deps.maxSnippetLines);
+        const cost = estimateTokens(snippet);
+        if (hits.length > 0 && cost > remaining)
+            break;
+        remaining -= cost;
+        hits.push({
+            path: record.path,
+            startLine: record.startLine,
+            endLine: record.endLine,
+            score: roundScore(record.score),
+            snippet,
+        });
+    }
+    return hits;
+}
+/** Build a path predicate from a glob (compiled once). */
+function buildPathFilter(glob) {
+    const re = globToRegExp(glob);
+    return (p) => re.test(p);
+}
+/** Trim a snippet to at most `maxLines`, noting how many lines were dropped. */
+function trimSnippet(text, maxLines) {
+    const lines = text.split("\n");
+    if (lines.length <= maxLines)
+        return text;
+    const kept = lines.slice(0, maxLines).join("\n");
+    return `${kept}\n… (+${lines.length - maxLines} more lines)`;
+}
+function roundScore(score) {
+    return Math.round(score * 10000) / 10000;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, Math.trunc(value)));
+}

package/dist/indexing/service.d.ts

@@ -0,0 +1,49 @@
+import type { CruxyConfig } from "../config/index.js";
+import { type Embedder } from "./embedder.js";
+import { type SearchOptions } from "./retriever.js";
+import type { IndexStats, IndexStatus, SearchHit } from "./types.js";
+/** Logger surface the service reports through. */
+interface ServiceLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * A ready-to-use index for one project root: it owns the store, embedder, and
+ * indexer, exposes `search`/`index`/`status`, and refreshes itself lazily on the
+ * first search. Build one with {@link getIndexService}, which caches per cwd so
+ * the heavy backends are constructed at most once per process.
+ */
+export interface IndexService {
+    /** Search the index, refreshing it first if it hasn't been this process. */
+    search(opts: SearchOptions): Promise<SearchHit[]>;
+    /** Build/refresh the index (incremental unless `force`). */
+    index(runOpts?: {
+        force?: boolean;
+    }): Promise<IndexStats>;
+    /** Read-only snapshot for `cruxy index --status` (does not modify the index). */
+    status(): IndexStatus;
+    /** Release backend resources. */
+    close(): void;
+}
+/** Absolute path of the SQLite index for a project root. */
+export declare function indexDbPath(cwd: string): string;
+/**
+ * Explicit dependency overrides. The sole supported override is `embedder`: it
+ * is the *only* way to substitute a non-production embedder (e.g.
+ * `HashingEmbedder`) and exists for tests. Production callers (the
+ * `search_codebase` tool, `cruxy index`) never pass it, so they always go
+ * through {@link createEmbedder} — fastembed or a loud failure.
+ */
+export interface IndexServiceDeps {
+    embedder?: Embedder;
+}
+/**
+ * Get (or build) the {@link IndexService} for a project root, cached per
+ * resolved cwd so the embedder + store are created at most once per process.
+ * `deps` is for explicit test injection only (see {@link IndexServiceDeps}).
+ */
+export declare function getIndexService(cwd: string, config: CruxyConfig, logger: ServiceLogger, deps?: IndexServiceDeps): Promise<IndexService>;
+/** Drop all cached services (closing them). For tests and process teardown. */
+export declare function resetIndexServices(): Promise<void>;
+export {};

package/dist/indexing/service.js

@@ -0,0 +1,132 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/index.js";
+import { GLOBAL_DIR_NAME } from "../constants.js";
+import { createEmbedder } from "./embedder.js";
+import { Indexer } from "./indexer.js";
+import { searchCodebase } from "./retriever.js";
+import { createSqliteVectorStore, InMemoryVectorStore, } from "./store.js";
+/** Absolute path of the SQLite index for a project root. */
+export function indexDbPath(cwd) {
+    return path.join(path.resolve(cwd), GLOBAL_DIR_NAME, "index.db");
+}
+class IndexServiceImpl {
+    store;
+    embedder;
+    config;
+    storePath;
+    logger;
+    indexer;
+    refreshed = false;
+    constructor(store, embedder, config, storePath, logger, root) {
+        this.store = store;
+        this.embedder = embedder;
+        this.config = config;
+        this.storePath = storePath;
+        this.logger = logger;
+        this.indexer = new Indexer({
+            root,
+            store,
+            embedder,
+            maxFileBytes: config.maxFileBytes,
+            chunk: config.chunk,
+            logger,
+        });
+    }
+    async index(runOpts = {}) {
+        const stats = await this.indexer.index(runOpts);
+        this.refreshed = true;
+        return stats;
+    }
+    async search(opts) {
+        // Lazily bring the index up to date once per process so searches never read
+        // stale (or, for a fresh/in-memory store, empty) results.
+        if (!this.refreshed) {
+            this.logger.debug("refreshing codebase index before first search");
+            const stats = await this.index();
+            this.logger.debug(`index refresh: +${stats.filesIndexed} ~${stats.filesSkipped} -${stats.filesPurged} ` +
+                `(${stats.chunksIndexed} chunks, ${stats.durationMs}ms)`);
+        }
+        return searchCodebase({
+            store: this.store,
+            embedder: this.embedder,
+            defaultK: this.config.search.defaultK,
+            tokenBudget: this.config.search.tokenBudget,
+            maxSnippetLines: this.config.search.maxSnippetLines,
+        }, opts);
+    }
+    status() {
+        const meta = this.store.getMeta();
+        const files = this.store.countFiles();
+        return {
+            exists: files > 0,
+            embedderId: meta?.embedderId ?? null,
+            dim: meta?.dim ?? null,
+            files,
+            chunks: this.store.countChunks(),
+            storePath: this.storePath,
+        };
+    }
+    close() {
+        this.store.close();
+    }
+}
+// ── per-cwd cache ─────────────────────────────────────────────────────────────
+const cache = new Map();
+/**
+ * Get (or build) the {@link IndexService} for a project root, cached per
+ * resolved cwd so the embedder + store are created at most once per process.
+ * `deps` is for explicit test injection only (see {@link IndexServiceDeps}).
+ */
+export function getIndexService(cwd, config, logger, deps) {
+    const root = path.resolve(cwd);
+    let pending = cache.get(root);
+    if (!pending) {
+        pending = buildService(root, config, logger, deps).catch((err) => {
+            // Don't cache a failed construction — let the next call retry.
+            cache.delete(root);
+            throw err;
+        });
+        cache.set(root, pending);
+    }
+    return pending;
+}
+/** Drop all cached services (closing them). For tests and process teardown. */
+export async function resetIndexServices() {
+    const services = [...cache.values()];
+    cache.clear();
+    for (const pending of services) {
+        try {
+            (await pending).close();
+        }
+        catch {
+            /* already closed or failed to build */
+        }
+    }
+}
+async function buildService(root, config, logger, deps) {
+    const indexConfig = config.index;
+    // Production always builds the fastembed embedder (or fails loudly). An
+    // injected embedder is honored only when a test passes one explicitly.
+    const embedder = deps?.embedder ??
+        (await createEmbedder({ cacheDir: path.join(globalDir(), "models") }));
+    const { store, storePath } = await openStore(root, indexConfig.store, logger);
+    return new IndexServiceImpl(store, embedder, indexConfig, storePath, logger, root);
+}
+async function openStore(root, kind, logger) {
+    if (kind === "memory") {
+        return { store: new InMemoryVectorStore(), storePath: null };
+    }
+    const dbPath = indexDbPath(root);
+    try {
+        await fsp.mkdir(path.dirname(dbPath), { recursive: true });
+        const store = await createSqliteVectorStore(dbPath);
+        return { store, storePath: dbPath };
+    }
+    catch (err) {
+        if (kind === "sqlite")
+            throw err;
+        logger.warn(`sqlite index unavailable (${err.message}); using an in-memory index`);
+        return { store: new InMemoryVectorStore(), storePath: null };
+    }
+}

package/dist/indexing/store.d.ts

@@ -0,0 +1,103 @@
+import type DatabaseNs from "better-sqlite3";
+import type { EmbeddedChunk, ScoredRecord } from "./types.js";
+/**
+ * Vector storage for the codebase index. The {@link VectorStore} interface hides
+ * the backend so the brute-force cosine search here can be swapped for an ANN
+ * index later without touching the indexer, retriever, or tool. Two backends
+ * ship: {@link SqliteVectorStore} (persistent, the default) and
+ * {@link InMemoryVectorStore} (ephemeral, for tests).
+ *
+ * Vectors are stored L2-normalized, so cosine similarity reduces to a dot
+ * product (see {@link dot}).
+ */
+/** Embedder identity + dimensionality the index was built with. */
+export interface VectorStoreMeta {
+    embedderId: string;
+    dim: number;
+}
+export interface VectorStore {
+    /** Embedder identity + dim recorded for this index, or null if never set. */
+    getMeta(): VectorStoreMeta | null;
+    /** Record the embedder identity + dim. Called when the index is (re)initialized. */
+    setMeta(meta: VectorStoreMeta): void;
+    /** Map of indexed file path → content hash, for incremental decisions. */
+    getFileHashes(): Map<string, string>;
+    /** Replace every chunk for `path` with `chunks` and record its hash. Atomic. */
+    upsertFile(path: string, hash: string, chunks: EmbeddedChunk[]): void;
+    /** Remove a file and all of its chunks. */
+    deleteByPath(path: string): void;
+    /**
+     * Brute-force cosine top-k over stored vectors, optionally restricted to paths
+     * for which `pathFilter` returns true. Results are sorted by score, descending.
+     */
+    search(query: Float32Array, k: number, pathFilter?: (path: string) => boolean): ScoredRecord[];
+    /** Number of indexed files. */
+    countFiles(): number;
+    /** Number of stored chunks. */
+    countChunks(): number;
+    /** Release any held resources (e.g. the SQLite handle). Idempotent. */
+    close(): void;
+}
+/** Dot product over the overlapping prefix of two vectors. */
+export declare function dot(a: Float32Array, b: Float32Array): number;
+/** Cosine similarity in [-1, 1]. Returns 0 if either vector is all-zero. */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/** Serialize a vector to a little-endian Float32 BLOB (an owning copy). */
+export declare function vectorToBlob(v: Float32Array): Buffer;
+/** Deserialize a little-endian Float32 BLOB back into a vector. */
+export declare function blobToVector(buf: Buffer): Float32Array;
+/** Indices of the `k` largest scores, sorted descending. */
+export declare function topKIndices(scores: ArrayLike<number>, k: number): number[];
+/**
+ * A non-persistent {@link VectorStore} backed by plain JS maps. Used by the test
+ * suite and as the `auto` fallback when the SQLite native dependency is
+ * unavailable. Holds everything in memory; rebuilt on each process.
+ */
+export declare class InMemoryVectorStore implements VectorStore {
+    private meta;
+    private readonly fileHashes;
+    private readonly chunksByPath;
+    getMeta(): VectorStoreMeta | null;
+    setMeta(meta: VectorStoreMeta): void;
+    getFileHashes(): Map<string, string>;
+    upsertFile(path: string, hash: string, chunks: EmbeddedChunk[]): void;
+    deleteByPath(path: string): void;
+    countFiles(): number;
+    countChunks(): number;
+    search(query: Float32Array, k: number, pathFilter?: (path: string) => boolean): ScoredRecord[];
+    close(): void;
+}
+type DB = DatabaseNs.Database;
+/**
+ * Persistent {@link VectorStore} backed by better-sqlite3 at `.cruxy/index.db`.
+ * Vectors are stored as Float32 BLOBs; search lazily loads them into one
+ * contiguous matrix (cached until the next write) so warm queries are a tight
+ * dot-product scan rather than per-row deserialization.
+ *
+ * Construct via {@link createSqliteVectorStore}, which loads the native module.
+ */
+export declare class SqliteVectorStore implements VectorStore {
+    private readonly db;
+    private cache;
+    private closed;
+    constructor(db: DB);
+    getMeta(): VectorStoreMeta | null;
+    setMeta(meta: VectorStoreMeta): void;
+    getFileHashes(): Map<string, string>;
+    upsertFile(path: string, hash: string, chunks: EmbeddedChunk[]): void;
+    deleteByPath(path: string): void;
+    countFiles(): number;
+    countChunks(): number;
+    search(query: Float32Array, k: number, pathFilter?: (path: string) => boolean): ScoredRecord[];
+    close(): void;
+    private ensureCache;
+    private getMetaValue;
+    private setMetaValue;
+}
+/**
+ * Open (or create) a {@link SqliteVectorStore} at `dbPath`. The native module is
+ * imported lazily here, so nothing loads it until an index is actually used.
+ * The parent directory must already exist.
+ */
+export declare function createSqliteVectorStore(dbPath: string): Promise<SqliteVectorStore>;
+export {};