brainbank 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,2161 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * BrainBank — Database Adapter Interface
+ *
+ * Abstract contract for database operations. All consumers depend on
+ * this interface — never on a concrete driver. The `SQLiteAdapter`
+ * is the built-in implementation; future adapters (LibSQL, Turso,
+ * PostgreSQL) implement the same contract.
+ *
+ * Phase 1: sync-first API matching the existing synchronous SQLite usage.
+ * Async variants will be added when needed by async-native adapters.
+ */
+/** Result from mutating queries (INSERT / UPDATE / DELETE). */
+interface ExecuteResult {
+    /** Row ID of the last inserted row. */
+    lastInsertRowid: number | bigint;
+    /** Number of rows changed by the statement. */
+    changes: number;
+}
+/** A prepared statement with typed query methods. */
+interface PreparedStatement<T = unknown> {
+    /** Execute a query and return the first matching row, or `undefined`. */
+    get(...params: unknown[]): T | undefined;
+    /** Execute a query and return all matching rows. */
+    all(...params: unknown[]): T[];
+    /** Execute a mutating statement and return the result. */
+    run(...params: unknown[]): ExecuteResult;
+    /** Iterate over matching rows without loading them all into memory. */
+    iterate(...params: unknown[]): IterableIterator<T>;
+}
+/** Adapter capability flags — describes what the underlying engine supports. */
+interface AdapterCapabilities {
+    /** Full-text search engine. */
+    fts: 'fts5' | 'tsvector' | 'none';
+    /** Upsert syntax dialect. */
+    upsert: 'or-replace' | 'on-conflict';
+    /** Native JSON column support. */
+    json: boolean;
+    /** Native vector column support (e.g. pgvector). */
+    vectors: boolean;
+}
+/**
+ * Database adapter interface.
+ *
+ * All BrainBank components depend on this contract instead of a
+ * concrete database driver. Keeps the door open for LibSQL, Turso,
+ * PostgreSQL, etc. without touching consumer code.
+ */
+interface DatabaseAdapter {
+    /** Prepare a reusable statement. */
+    prepare<T = unknown>(sql: string): PreparedStatement<T>;
+    /** Execute raw DDL / multi-statement SQL (no results). */
+    exec(sql: string): void;
+    /** Run `fn` inside a transaction. Auto-commits on success, auto-rollbacks on error. */
+    transaction<T>(fn: () => T): T;
+    /** Run a prepared statement on multiple rows inside a single transaction. */
+    batch<T extends unknown[]>(sql: string, rows: T[]): void;
+    /** Close the database and release resources. */
+    close(): void;
+    /** Engine capabilities (FTS, upsert dialect, etc.). */
+    readonly capabilities: AdapterCapabilities;
+    /**
+     * Escape hatch: access the underlying raw driver.
+     * Returns `undefined` for adapters that don't support raw access.
+     *
+     * @deprecated Use `DatabaseAdapter` methods instead. This exists
+     * only for gradual migration of plugins that depend on driver internals.
+     */
+    raw<T = unknown>(): T | undefined;
+}
+interface KvDataRow {
+    id: number;
+    collection: string;
+    content: string;
+    meta_json: string;
+    tags_json: string;
+    expires_at: number | null;
+    created_at: number;
+}
+interface KvVectorRow {
+    data_id: number;
+    embedding: Uint8Array;
+}
+interface EmbeddingMetaRow {
+    value: string;
+}
+interface VectorRow {
+    id: number;
+    embedding: Uint8Array;
+}
+interface CountRow {
+    c: number;
+}
+
+/**
+ * BrainBank — Plugin Migration System
+ *
+ * Per-plugin versioned schema migrations.
+ * Each plugin declares a schemaVersion + ordered migrations array.
+ * Core stores applied versions in `plugin_versions` table.
+ *
+ * Plugins call `runPluginMigrations()` at the top of their `initialize()`.
+ * Migrations use `IF NOT EXISTS` so first run on an existing DB is a no-op.
+ */
+
+/** A single migration step. */
+interface Migration {
+    /** Version this migration brings the schema to. */
+    version: number;
+    /** Apply the migration. Must be idempotent (use IF NOT EXISTS). */
+    up(adapter: DatabaseAdapter): void;
+}
+/**
+ * Run pending migrations for a plugin.
+ * Skips migrations whose version <= stored version.
+ * Each migration runs in its own transaction.
+ */
+declare function runPluginMigrations(adapter: DatabaseAdapter, pluginName: string, schemaVersion: number, migrations: Migration[]): void;
+
+/**
+ * BrainBank — Incremental Tracker
+ *
+ * Standardized helper for plugins to detect add/update/delete during indexing.
+ * Uses a shared `plugin_tracking` table with per-plugin namespacing.
+ *
+ * Usage in a plugin:
+ *   const tracker = ctx.createTracker();  // uses plugin name
+ *   for (const file of files) {
+ *       const hash = sha256(content);
+ *       if (tracker.isUnchanged(file, hash)) { skipped++; continue; }
+ *       indexFile(file, content);
+ *       tracker.markIndexed(file, hash);
+ *   }
+ *   const orphans = tracker.findOrphans(new Set(files));
+ *   for (const key of orphans) { removeData(key); tracker.remove(key); }
+ */
+
+/** Incremental index tracker — detects add/update/delete for plugin files. */
+interface IncrementalTracker {
+    /** Check if a key's content is unchanged. Returns true if the hash matches (skip indexing). */
+    isUnchanged(key: string, contentHash: string): boolean;
+    /** Mark a key as successfully indexed with the given hash. Call after indexing completes. */
+    markIndexed(key: string, contentHash: string): void;
+    /** Find tracked keys that are NOT in the current set. Returns keys to delete. */
+    findOrphans(currentKeys: Set<string>): string[];
+    /** Remove tracking for a key. Call after cleaning up the key's data. */
+    remove(key: string): void;
+    /** Remove all tracking entries for this plugin. */
+    clear(): void;
+}
+/** Create an IncrementalTracker scoped to a plugin name. */
+declare function createTracker(db: DatabaseAdapter, pluginName: string): IncrementalTracker;
+
+/**
+ * BrainBank — Collection
+ *
+ * Universal key-value store with vector + BM25 hybrid search.
+ * The foundation primitive — store anything, search semantically.
+ *
+ *   const errors = brain.collection('debug_errors');
+ *   await errors.add('Fixed null check in api handler', { file: 'api.ts' });
+ *   const hits = await errors.search('null pointer');
+ */
+
+interface CollectionItem {
+    id: number;
+    collection: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    tags: string[];
+    createdAt: number;
+    expiresAt?: number;
+    score?: number;
+}
+interface CollectionSearchOptions {
+    /** Max results. Default: 5 */
+    k?: number;
+    /** Search mode. Default: 'hybrid' */
+    mode?: 'hybrid' | 'vector' | 'keyword';
+    /** Minimum score threshold. Default: 0.15 */
+    minScore?: number;
+    /** Filter by tags (item must have ALL specified tags). */
+    tags?: string[];
+}
+interface CollectionAddOptions {
+    /** Metadata key-value pairs. */
+    metadata?: Record<string, unknown>;
+    /** Tags for filtering. */
+    tags?: string[];
+    /** Time-to-live duration string (e.g. '7d', '24h', '30m'). */
+    ttl?: string;
+}
+declare class Collection {
+    private _name;
+    private _db;
+    private _embedding;
+    private _hnsw;
+    private _vecs;
+    constructor(_name: string, _db: DatabaseAdapter, _embedding: EmbeddingProvider, _hnsw: HNSWIndex, _vecs: Map<number, Float32Array>);
+    /** Collection name. */
+    get name(): string;
+    /** Add an item. Returns its ID. */
+    add(content: string, options?: CollectionAddOptions | Record<string, unknown>): Promise<number>;
+    /** Update an item's content (re-embeds). Returns the new ID. */
+    update(id: number, content: string, options?: CollectionAddOptions): Promise<number>;
+    /** Add multiple items. Returns their IDs. */
+    addMany(items: {
+        content: string;
+        metadata?: Record<string, unknown>;
+        tags?: string[];
+        ttl?: string;
+    }[]): Promise<number[]>;
+    /** Search this collection. */
+    search(query: string, options?: CollectionSearchOptions): Promise<CollectionItem[]>;
+    /** Search and return results as SearchResult[] for use in hybrid search pipelines. */
+    searchAsResults(query: string, k: number): Promise<SearchResult[]>;
+    /** List items (newest first). */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+    }): CollectionItem[];
+    /** Count items in this collection. */
+    count(): number;
+    /** Keep only the N most recent items, remove the rest. */
+    trim(options: {
+        keep: number;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove items older than a duration string (e.g. '30d', '12h'). */
+    prune(options: {
+        olderThan: string;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove a specific item by ID. */
+    remove(id: number): void;
+    /** Clear all items in this collection. */
+    clear(): void;
+    private _removeById;
+    private _searchVector;
+    /** Compute adaptive over-fetch multiplier based on collection density in shared HNSW. */
+    private _adaptiveSearchK;
+    private _searchBM25;
+    private _rowToItem;
+    /** Filter results by tags (item must have ALL specified tags). */
+    private _filterByTags;
+    /** Remove expired items (TTL). Called automatically on search/list. */
+    private _pruneExpired;
+}
+
+/**
+ * BrainBank — Type Definitions
+ *
+ * All interfaces and types for the semantic knowledge bank.
+ */
+
+/** Public contract for a KV collection. Plugins depend on this interface, not the concrete class. */
+interface ICollection {
+    /** Collection name. */
+    readonly name: string;
+    /** Add an item. Returns its ID. */
+    add(content: string, options?: CollectionAddOptions | Record<string, unknown>): Promise<number>;
+    /** Update an item's content (re-embeds). Returns the new ID. */
+    update(id: number, content: string, options?: CollectionAddOptions): Promise<number>;
+    /** Add multiple items. Returns their IDs. */
+    addMany(items: {
+        content: string;
+        metadata?: Record<string, unknown>;
+        tags?: string[];
+        ttl?: string;
+    }[]): Promise<number[]>;
+    /** Search this collection. */
+    search(query: string, options?: CollectionSearchOptions): Promise<CollectionItem[]>;
+    /** List items (newest first). */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+    }): CollectionItem[];
+    /** Count items in this collection. */
+    count(): number;
+    /** Keep only the N most recent items. */
+    trim(options: {
+        keep: number;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove items older than a duration string. */
+    prune(options: {
+        olderThan: string;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove a specific item by ID. */
+    remove(id: number): void;
+    /** Clear all items in this collection. */
+    clear(): void;
+}
+interface BrainBankConfig {
+    /** Root path of the repository to index. Default: '.' */
+    repoPath?: string;
+    /** SQLite database path. Default: '.brainbank/data/brainbank.db' */
+    dbPath?: string;
+    /** Max git commits to index. Default: 500 */
+    gitDepth?: number;
+    /** Max file size in bytes to index. Default: 512_000 (500KB) */
+    maxFileSize?: number;
+    /** Max diff bytes per commit. Default: 8192 */
+    maxDiffBytes?: number;
+    /** HNSW M parameter (connections per node). Default: 16 */
+    hnswM?: number;
+    /** HNSW efConstruction (build-time candidates). Default: 200 */
+    hnswEfConstruction?: number;
+    /** HNSW efSearch (query-time candidates). Default: 50 */
+    hnswEfSearch?: number;
+    /** Embedding dimensions. Default: 384 */
+    embeddingDims?: number;
+    /** Max HNSW elements. Default: 2_000_000 */
+    maxElements?: number;
+    /** Custom embedding provider (default: local WASM model) */
+    embeddingProvider?: EmbeddingProvider;
+    /** Optional LLM noise filter — drops irrelevant results before formatting */
+    pruner?: Pruner;
+    /** Optional LLM context expander — discovers additional relevant chunks after pruning */
+    expander?: Expander;
+    /** Port for optional webhook server (enables push-based watch plugins). */
+    webhookPort?: number;
+    /** Context field defaults from config.json "context" section. */
+    contextFields?: Record<string, unknown>;
+}
+interface ResolvedConfig {
+    repoPath: string;
+    dbPath: string;
+    gitDepth: number;
+    maxFileSize: number;
+    maxDiffBytes: number;
+    hnswM: number;
+    hnswEfConstruction: number;
+    hnswEfSearch: number;
+    embeddingDims: number;
+    maxElements: number;
+    embeddingProvider?: EmbeddingProvider;
+    pruner?: Pruner;
+    expander?: Expander;
+    webhookPort?: number;
+    /** Context field defaults from config.json "context" section. */
+    contextFields?: Record<string, unknown>;
+}
+interface EmbeddingProvider {
+    /** Vector dimensions produced by this provider. */
+    readonly dims: number;
+    /** Embed a single text string. */
+    embed(text: string): Promise<Float32Array>;
+    /** Embed multiple texts (batch). */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** Release resources. */
+    close(): Promise<void>;
+}
+/** Item passed to the pruner for noise classification. */
+interface PrunerItem {
+    /** Positional index (used to map back to SearchResult[]) */
+    id: number;
+    /** File path — primary signal for relevance */
+    filePath: string;
+    /** Trimmed content preview */
+    preview: string;
+    /** Chunk metadata (type, name, language, lines, etc.) */
+    metadata: Record<string, unknown>;
+}
+interface Pruner {
+    /**
+     * Filter noise from search results and order by semantic relevance.
+     * @param query - The search query
+     * @param items - Items to evaluate (filePath + metadata + trimmed preview)
+     * @returns Array of item IDs to KEEP, ordered by relevance to the query
+     *          (most relevant first). Everything else is dropped.
+     */
+    prune(query: string, items: PrunerItem[]): Promise<number[]>;
+    /** Release resources. */
+    close?(): Promise<void>;
+}
+/** Lightweight chunk descriptor for the expander manifest. */
+interface ExpanderManifestItem {
+    /** Chunk ID (code_chunks.id) */
+    id: number;
+    /** File path */
+    filePath: string;
+    /** Chunk name (e.g. function/class name) */
+    name: string;
+    /** Chunk type (function, class, method, etc.) */
+    chunkType: string;
+    /** Line range (e.g. "L45-L89") */
+    lines: string;
+    /** True if this chunk is from an import-graph neighbor of the search results. */
+    priority?: boolean;
+}
+/** Result from the expander: chunk IDs to add + optional free-text note. */
+interface ExpanderResult {
+    /** Additional chunk IDs to splice into results. */
+    ids: number[];
+    /** Brief observation for the agent (e.g. "file X not found", "module Y is deprecated"). */
+    note?: string;
+}
+interface Expander {
+    /**
+     * Given a task and a manifest of available chunks,
+     * return additional chunk IDs + an optional contextual note.
+     * Runs after pruning. Fail-open: errors return empty result.
+     *
+     * @param query - The search query / task description
+     * @param currentIds - IDs of chunks already in results (from search + prune)
+     * @param manifest - All available chunks (lightweight descriptors)
+     * @returns Chunk IDs to add + optional note
+     */
+    expand(query: string, currentIds: number[], manifest: ExpanderManifestItem[]): Promise<ExpanderResult>;
+    /** Release resources. */
+    close?(): Promise<void>;
+}
+interface SearchHit {
+    id: number;
+    score: number;
+}
+interface VectorIndex {
+    /** Initialize the index. Must be called before add/search. */
+    init(): Promise<this>;
+    /** Add a vector with an integer ID. Idempotent: duplicate IDs are skipped. */
+    add(vector: Float32Array, id: number): void;
+    /** Mark a vector as deleted so it no longer appears in searches. */
+    remove(id: number): void;
+    /** Search for k nearest neighbors. */
+    search(query: Float32Array, k: number): SearchHit[];
+    /** Clear all vectors and reset to empty state. */
+    reinit(): void;
+    /** Number of vectors in the index. */
+    readonly size: number;
+}
+interface CodeChunk {
+    /** Auto-incremented DB id (set after insert) */
+    id?: number;
+    /** Relative file path from repo root */
+    filePath: string;
+    /** Chunk type: 'file' | 'function' | 'class' | 'block' */
+    chunkType: string;
+    /** Function/class name (if detected) */
+    name?: string;
+    /** Start line (1-indexed) */
+    startLine: number;
+    /** End line (1-indexed, inclusive) */
+    endLine: number;
+    /** Raw content of the chunk */
+    content: string;
+    /** Language identifier */
+    language: string;
+}
+interface GitCommitRecord {
+    id?: number;
+    hash: string;
+    shortHash: string;
+    message: string;
+    author: string;
+    date: string;
+    timestamp: number;
+    filesChanged: string[];
+    diff?: string;
+    additions: number;
+    deletions: number;
+    isMerge: boolean;
+}
+type SearchResultType = 'code' | 'commit' | 'document' | 'collection';
+interface CodeResultMetadata {
+    /** Database chunk ID (used by call graph annotations). */
+    id?: number;
+    /** File path (may duplicate CodeResult.filePath for metadata-only access). */
+    filePath?: string;
+    /** Adjacent chunk IDs from the same file (used by context expansion). */
+    chunkIds?: number[];
+    chunkType: string;
+    name?: string;
+    startLine: number;
+    endLine: number;
+    language: string;
+    searchType?: string;
+    rrfScore?: number;
+}
+interface CommitResultMetadata {
+    hash: string;
+    shortHash: string;
+    author: string;
+    date: string;
+    files: string[];
+    additions?: number;
+    deletions?: number;
+    diff?: string;
+    searchType?: string;
+    rrfScore?: number;
+}
+interface DocumentResultMetadata {
+    collection?: string;
+    title?: string;
+    seq?: number;
+    path?: string;
+    searchType?: string;
+    /** Internal chunk ID used by hybrid search to map fused results. */
+    chunkId?: number;
+    rrfScore?: number;
+}
+interface CodeResult {
+    type: 'code';
+    score: number;
+    filePath: string;
+    content: string;
+    context?: string;
+    metadata: CodeResultMetadata;
+}
+interface CommitResult {
+    type: 'commit';
+    score: number;
+    filePath?: string;
+    content: string;
+    context?: string;
+    metadata: CommitResultMetadata;
+}
+interface DocumentResult {
+    type: 'document';
+    score: number;
+    filePath: string;
+    content: string;
+    context?: string;
+    metadata: DocumentResultMetadata;
+}
+interface CollectionResultMetadata {
+    id?: number;
+    collection?: string;
+    rrfScore?: number;
+    [key: string]: unknown;
+}
+interface CollectionResult {
+    type: 'collection';
+    score: number;
+    filePath?: string;
+    content: string;
+    context?: string;
+    metadata: CollectionResultMetadata;
+}
+type SearchResult = CodeResult | CommitResult | DocumentResult | CollectionResult;
+/** Narrow a SearchResult to CodeResult. */
+declare function isCodeResult(r: SearchResult): r is CodeResult;
+/** Narrow a SearchResult to CommitResult. */
+declare function isCommitResult(r: SearchResult): r is CommitResult;
+/** Narrow a SearchResult to DocumentResult. */
+declare function isDocumentResult(r: SearchResult): r is DocumentResult;
+/** Narrow a SearchResult to CollectionResult. */
+declare function isCollectionResult(r: SearchResult): r is CollectionResult;
+type MatchHandlers<T> = {
+    code?: (r: CodeResult) => T;
+    commit?: (r: CommitResult) => T;
+    document?: (r: DocumentResult) => T;
+    collection?: (r: CollectionResult) => T;
+    _?: (r: SearchResult) => T;
+};
+/**
+ * Pattern-match on SearchResult type. Calls the matching handler
+ * or the `_` fallback. Returns undefined if no handler matches.
+ */
+declare function matchResult<T>(result: SearchResult, handlers: MatchHandlers<T>): T | undefined;
+interface ContextOptions {
+    /** Per-source result limits. Built-in: 'code', 'git'. Default: { code: 6, git: 5 } */
+    sources?: Record<string, number>;
+    /** Files the agent is about to modify (improves co-edit suggestions) */
+    affectedFiles?: string[];
+    /** Minimum similarity score threshold. Default: 0.25 */
+    minScore?: number;
+    /** Use MMR for diversity. Default: true */
+    useMMR?: boolean;
+    /** MMR lambda (0 = diversity, 1 = relevance). Default: 0.7 */
+    mmrLambda?: number;
+    /** Filter results to files under these path prefixes (e.g. 'src/services/' or ['src/', 'lib/']). */
+    pathPrefix?: string | string[];
+    /** Exclude results whose filePath starts with any of these prefixes (e.g. ['src/tests/', 'src/mocks/']). */
+    ignorePaths?: string[];
+    /** File paths to exclude from results (e.g. files already returned in a previous query). */
+    excludeFiles?: Set<string>;
+    /** Optional per-request pruner override (e.g. HaikuPruner for LLM noise filtering). */
+    pruner?: Pruner;
+    /** Caller origin for debug logging. */
+    source?: 'cli' | 'mcp' | 'daemon' | 'api';
+    /**
+     * Context field overrides. Merged on top of config.json "context" defaults.
+     * Plugin-defined fields like `lines`, `callTree`, `symbols`, `compact`, `imports`.
+     * Example: `{ lines: true, callTree: { depth: 3 }, symbols: true }`
+     */
+    fields?: Record<string, unknown>;
+}
+interface DocumentCollection {
+    /** Collection name (e.g. 'notes', 'docs') */
+    name: string;
+    /** Directory path to index */
+    path: string;
+    /** Glob pattern for files (default: all markdown) */
+    pattern?: string;
+    /** Glob patterns to ignore */
+    ignore?: string[];
+    /** Context description for this collection */
+    context?: string;
+}
+interface DocChunk {
+    id?: number;
+    /** Collection name */
+    collection: string;
+    /** Relative file path within the collection */
+    filePath: string;
+    /** Document title (first heading or filename) */
+    title: string;
+    /** Chunk content */
+    content: string;
+    /** Chunk sequence within the document (0, 1, 2...) */
+    seq: number;
+    /** Character position in original document */
+    pos: number;
+    /** Content hash for incremental updates */
+    contentHash: string;
+}
+/** File-level progress (used by indexers). */
+type ProgressCallback = (file: string, current: number, total: number) => void;
+/** Stage-level progress (used by BrainBank.index() orchestrator). */
+type StageProgressCallback = (stage: string, message: string) => void;
+interface IndexResult {
+    indexed: number;
+    skipped: number;
+    chunks?: number;
+    removed?: number;
+}
+interface CoEditSuggestion {
+    file: string;
+    count: number;
+}
+/** Generalized watch event — works for files, APIs, webhooks. */
+interface WatchEvent {
+    /** Event type. 'sync' is for batch/poll sources that don't distinguish CRUD. */
+    type: 'create' | 'update' | 'delete' | 'sync';
+    /** Unique ID of the changed item (file path, PR#123, PROJ-456, etc.). */
+    sourceId: string;
+    /** Source descriptor (e.g. 'file', 'github:pr', 'jira:card'). */
+    sourceName: string;
+    /** Optional raw payload to avoid re-fetching. */
+    payload?: unknown;
+}
+/** Callback that plugins invoke when they detect a change. */
+type WatchEventHandler = (event: WatchEvent) => void;
+/** Lifecycle handle returned by WatchablePlugin.watch(). */
+interface WatchHandle {
+    /** Stop watching and release resources. */
+    stop(): Promise<void>;
+    /** Whether the watcher is still active. */
+    readonly active: boolean;
+}
+/** Optional hints from plugin to core — debounce, batching, priority. */
+interface WatchConfig {
+    /** Debounce interval in ms. 0 = process immediately. Default: inherited from WatchOptions. */
+    debounceMs?: number;
+    /** Max events to batch before triggering re-index. Default: unlimited. */
+    batchSize?: number;
+    /** Processing priority. Default: 'realtime'. */
+    priority?: 'realtime' | 'background';
+}
+
+/**
+ * BrainBank — HNSW Vector Index
+ *
+ * Wraps hnswlib-node for O(log n) approximate nearest neighbor search.
+ * M=16 connections, ef=200 construction, ef=50 search by default.
+ * 150x faster than brute force at 1M vectors.
+ *
+ * Supports disk persistence: save(path) / tryLoad(path, count)
+ * to skip costly vector-by-vector rebuild on startup.
+ */
+
+declare class HNSWIndex implements VectorIndex {
+    private _dims;
+    private _maxElements;
+    private _M;
+    private _efConstruction;
+    private _efSearch;
+    private _index;
+    private _lib;
+    private _ids;
+    constructor(_dims: number, _maxElements?: number, _M?: number, _efConstruction?: number, _efSearch?: number);
+    /**
+     * Initialize the HNSW index.
+     * Must be called before add/search.
+     */
+    init(): Promise<this>;
+    /**
+     * Reinitialize the index in-place, clearing all vectors.
+     * Required after reembed or full re-index to avoid duplicate IDs.
+     * init() must have been called first.
+     */
+    reinit(): void;
+    private _createIndex;
+    /** Maximum capacity of this index. */
+    get maxElements(): number;
+    /**
+     * Add a vector with an integer ID.
+     * The vector should be pre-normalized for cosine distance.
+     */
+    add(vector: Float32Array, id: number): void;
+    /**
+     * Mark a vector as deleted so it no longer appears in searches.
+     * Uses hnswlib-node markDelete under the hood.
+     * Safe to call with an ID that doesn't exist.
+     */
+    remove(id: number): void;
+    /**
+     * Search for the k nearest neighbors.
+     * Returns results sorted by score (highest first).
+     * Score is 1 - cosine_distance (1.0 = identical).
+     */
+    search(query: Float32Array, k: number): SearchHit[];
+    /** Number of vectors in the index. */
+    get size(): number;
+    /**
+     * Save the HNSW graph to disk.
+     * The file can be loaded later with tryLoad() to skip vector-by-vector insertion.
+     */
+    save(path: string): void;
+    /**
+     * Try to load a previously saved HNSW index from disk.
+     * Returns true if loaded successfully, false if stale or missing.
+     * @param path File path to the saved index
+     * @param expectedCount Expected number of vectors (from SQLite) — used to detect staleness
+     */
+    tryLoad(path: string, expectedCount: number): boolean;
+}
+
+/**
+ * BrainBank — Search Types
+ *
+ * Shared interface for all search strategies.
+ * Implement SearchStrategy to add a new search backend.
+ */
+
+/** Any search implementation follows this shape. */
+interface SearchStrategy {
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Rebuild internal indices (e.g. FTS5). Optional. */
+    rebuild?(): void;
+}
+/** Pre-embedded vector search for a single domain (code, git, etc.). */
+interface DomainVectorSearch {
+    /** Search using a pre-computed query vector. Optional queryText enables BM25 fusion. */
+    search(queryVec: Float32Array, k: number, minScore: number, useMMR?: boolean, mmrLambda?: number, queryText?: string): SearchResult[];
+}
+interface SearchOptions {
+    /** Per-source result limits. Built-in: 'code', 'git', 'memory'. Any other key = custom plugin or KV collection. */
+    sources?: Record<string, number>;
+    /** Minimum similarity score. Default: 0.25 */
+    minScore?: number;
+    /** Use MMR for diversity. Default: true */
+    useMMR?: boolean;
+    /** MMR lambda. Default: 0.7 */
+    mmrLambda?: number;
+    /** Caller origin for debug logging. */
+    source?: 'cli' | 'mcp' | 'daemon' | 'api';
+    /** Filter results to files under these path prefixes. */
+    pathPrefix?: string | string[];
+}
+
+/**
+ * BrainBank — Webhook Server
+ *
+ * Optional shared HTTP server for push-based watch plugins (e.g. Jira, GitHub).
+ * Opt-in: only created when `new BrainBank({ webhookPort: 4242 })` is configured.
+ *
+ * Plugins register routes during `watch()`:
+ *   ctx.webhookServer?.register('jira', '/jira/webhook', handler);
+ *
+ * Each plugin gets its own path namespace. Unregistering cleans up the route.
+ */
+/** Handler for incoming webhook payloads. */
+type WebhookHandler = (body: unknown) => void;
+/** Shared HTTP server for push-based watch plugins. */
+declare class WebhookServer {
+    private _server;
+    private _routes;
+    private _listening;
+    /** Start listening on the specified port. */
+    listen(port: number): void;
+    /** Register a webhook route for a plugin. */
+    register(pluginName: string, path: string, handler: WebhookHandler): void;
+    /** Remove all routes for a plugin. */
+    unregister(pluginName: string): void;
+    /** Stop the server and clear all routes. */
+    close(): void;
+    /** Whether the server is currently listening. */
+    get active(): boolean;
+    /** Route incoming POST requests to the matching handler. */
+    private _handleRequest;
+}
+
+/**
+ * BrainBank — Plugin System
+ *
+ * Plugins are pluggable strategies that scan external data sources
+ * and push content into BrainBank. Built-in plugins handle code,
+ * git, and docs. Third-party frameworks (LangChain, etc.)
+ * can implement custom plugins.
+ *
+ *   import { BrainBank } from 'brainbank';
+ *   import { code } from 'brainbank/indexers/code';
+ *
+ *   const brain = new BrainBank()
+ *     .use(code({ repoPath: '.' }));
+ */
+
+interface PluginContext {
+    /** Database adapter (shared across all plugins). */
+    db: DatabaseAdapter;
+    /** Embedding provider (shared). */
+    embedding: EmbeddingProvider;
+    /** Resolved BrainBank config. */
+    config: ResolvedConfig;
+    /**
+     * Create and initialize an HNSW index.
+     * Pass `name` to enable disk persistence (recommended).
+     *
+     * **Private vs shared:** Use `getOrCreateSharedHnsw()` for indexes that should be
+     * part of the composite search (code, git) and persisted across restarts.
+     * Use `createHnsw()` for plugin-local indexes that don't participate in the
+     * main search pipeline (e.g. internal similarity lookups).
+     */
+    createHnsw(maxElements?: number, dims?: number, name?: string): Promise<HNSWIndex>;
+    /** Load existing vectors from a SQLite vectors table into an HNSW index + cache. */
+    loadVectors(table: string, idCol: string, hnsw: HNSWIndex, cache: Map<number, Float32Array>): void;
+    /**
+     * Get or create a shared HNSW index by key.
+     *
+     * **HNSW sharing strategies:**
+     * The `type` key determines sharing behavior. Two plugins that pass the
+     * same key share one HNSW index; different keys get separate indexes.
+     *
+     * | Plugin type | Key passed        | Sharing behavior                          |
+     * |------------|------------------|------------------------------------------|
+     * | git        | `'git'`           | All `git:*` repos share one HNSW          |
+     * | docs       | `'docs'`          | All docs share one HNSW                   |
+     * | code       | `this.name`       | Each `code:*` repo gets its own HNSW      |
+     *
+     * **Rule of thumb:**
+     * - Same key = shared index (saves memory, single search covers all)
+     * - Plugin name as key = per-repo index (avoids cross-repo noise)
+     *
+     * The key is also used for hot-reload (`ensureFresh`) and disk persistence
+     * (`hnsw-<key>.index`), so it must match the key used in `bumpVersion()`.
+     */
+    getOrCreateSharedHnsw(type: string, maxElements?: number, dims?: number): Promise<{
+        hnsw: HNSWIndex;
+        vecCache: Map<number, Float32Array>;
+        isNew: boolean;
+    }>;
+    /** Get or create a dynamic collection. */
+    collection(name: string): ICollection;
+    /**
+     * Create an incremental tracker scoped to this plugin.
+     * Provides `isUnchanged`, `markIndexed`, `findOrphans`, `remove`, `clear`
+     * for standardized add/update/delete detection during indexing.
+     */
+    createTracker(): IncrementalTracker;
+    /** Optional webhook server for push-based watch plugins. undefined if not configured. */
+    webhookServer?: WebhookServer;
+}
+interface Plugin {
+    /** Unique plugin name (e.g. 'code', 'git', 'docs'). */
+    readonly name: string;
+    /** Initialize the plugin (create HNSW, load vectors, etc.). */
+    initialize(ctx: PluginContext): Promise<void>;
+    /** Return stats for this plugin. */
+    stats?(): Record<string, number | string>;
+    /** Clean up resources. */
+    close?(): void;
+}
+/** Options accepted by IndexablePlugin.index(). */
+interface IndexOptions {
+    forceReindex?: boolean;
+    depth?: number;
+    onProgress?: ProgressCallback;
+}
+/** Plugins that can scan and index content (code, git). */
+interface IndexablePlugin extends Plugin {
+    index(options?: IndexOptions): Promise<IndexResult>;
+    /** Incremental: re-index only specific items by ID. Falls back to index() if not implemented. */
+    indexItems?(ids: string[]): Promise<IndexResult>;
+}
+/** Plugins that can search indexed content (docs). */
+interface SearchablePlugin extends Plugin {
+    search(query: string, options?: Record<string, unknown>): Promise<SearchResult[]>;
+}
+/** Plugins that can watch their own data source for changes. */
+interface WatchablePlugin extends Plugin {
+    /** Start watching. Plugin controls how (fs.watch, polling, webhook, etc.). */
+    watch(onEvent: WatchEventHandler): WatchHandle;
+    /** Optional hints for the core (debounce, batching, priority). */
+    watchConfig?(): WatchConfig;
+}
+/** Check if a plugin can scan/index content. */
+declare function isIndexable(i: Plugin): i is IndexablePlugin;
+/** Check if a plugin can search content. */
+declare function isSearchable(i: Plugin): i is SearchablePlugin;
+/** Check if a plugin can watch its own data source. */
+declare function isWatchable(i: Plugin): i is WatchablePlugin;
+/** Path-specific context metadata for document collections. */
+interface PathContext {
+    collection: string;
+    path: string;
+    context: string;
+}
+/** Plugins that manage document collections (docs). */
+interface DocsPlugin extends SearchablePlugin {
+    addCollection(collection: DocumentCollection): void;
+    removeCollection(name: string): void;
+    listCollections(): DocumentCollection[];
+    indexDocs(options?: {
+        onProgress?: (collection: string, file: string, current: number, total: number) => void;
+    }): Promise<Record<string, {
+        indexed: number;
+        skipped: number;
+        removed: number;
+        chunks: number;
+    }>>;
+    addContext(collection: string, path: string, context: string): void;
+    listContexts(): PathContext[];
+}
+/** Check if a plugin manages document collections. */
+declare function isDocsPlugin(i: Plugin): i is DocsPlugin;
+/** Plugin that provides co-edit suggestions (e.g. git). */
+interface CoEditPlugin extends Plugin {
+    coEdits: {
+        suggest(filePath: string, limit: number): {
+            file: string;
+            count: number;
+        }[];
+    };
+}
+/** Check if a plugin provides co-edit suggestions. */
+declare function isCoEditPlugin(p: Plugin): p is CoEditPlugin;
+/** Table descriptor for re-embedding — maps text rows to vector BLOBs. */
+interface ReembedTable {
+    /** Human-readable name (for progress). */
+    name: string;
+    /** Table with text content. */
+    textTable: string;
+    /** Table with vector BLOBs. */
+    vectorTable: string;
+    /** PK column in text table. */
+    idColumn: string;
+    /** FK column in vector table. */
+    fkColumn: string;
+    /** Build the embedding text from a DB row. */
+    textBuilder: (row: Record<string, unknown>) => string;
+}
+/** Plugins that own vector tables and can rebuild embedding text from DB rows. */
+interface ReembeddablePlugin extends Plugin {
+    /** Table descriptor for re-embedding. */
+    reembedConfig(): ReembedTable;
+}
+/** Check if a plugin supports re-embedding. */
+declare function isReembeddable(p: Plugin): p is ReembeddablePlugin;
+/** Plugin that provides a domain-specific vector search strategy. */
+interface VectorSearchPlugin extends Plugin {
+    /** Create the domain vector search (called during SearchAPI wiring). */
+    createVectorSearch(): DomainVectorSearch | undefined;
+}
+/** Check if a plugin provides a domain vector search. */
+declare function isVectorSearchPlugin(p: Plugin): p is VectorSearchPlugin;
+/** Describes a configurable context field that a plugin supports. */
+interface ContextFieldDef {
+    /** Field name (e.g. 'lines', 'callTree', 'symbols'). Must be unique per plugin. */
+    name: string;
+    /** Accepted value type. 'object' allows nested config like `{ depth: 3 }`. */
+    type: 'boolean' | 'number' | 'object';
+    /** Default value (used when not specified in config or query). */
+    default: unknown;
+    /** Human-readable description for CLI --help and MCP tool descriptions. */
+    description: string;
+}
+/** Plugin that declares configurable context fields. */
+interface ContextFieldPlugin extends Plugin {
+    /** Declare available context fields. Called once during setup. */
+    contextFields(): ContextFieldDef[];
+}
+/** Check if a plugin declares context fields. */
+declare function isContextFieldPlugin(p: Plugin): p is ContextFieldPlugin;
+/** Plugin that contributes sections to the context builder output. */
+interface ContextFormatterPlugin extends Plugin {
+    /**
+     * Append formatted markdown sections to `parts`.
+     * `fields` contains resolved context fields (plugin defaults ← config ← per-query).
+     */
+    formatContext(results: SearchResult[], parts: string[], fields: Record<string, unknown>): void;
+}
+/** Check if a plugin provides context formatting. */
+declare function isContextFormatterPlugin(p: Plugin): p is ContextFormatterPlugin;
+/** Plugin that owns database tables and supports versioned migrations. */
+interface MigratablePlugin extends Plugin {
+    /** Current schema version for this plugin. */
+    readonly schemaVersion: number;
+    /** Ordered list of migrations (version 1, 2, 3, …). */
+    readonly migrations: Migration[];
+}
+/** Check if a plugin supports schema migrations. */
+declare function isMigratable(p: Plugin): p is MigratablePlugin;
+/** Plugin that can do FTS5 keyword search on its own tables. */
+interface BM25SearchPlugin extends Plugin {
+    /** Run BM25 keyword search. Returns scored results. */
+    searchBM25(query: string, k: number, minScore?: number): SearchResult[];
+    /** Rebuild the FTS5 index from the content table. */
+    rebuildFTS?(): void;
+}
+/** Check if a plugin provides BM25 keyword search. */
+declare function isBM25SearchPlugin(p: Plugin): p is BM25SearchPlugin;
+/** Plugin that supports context expansion (provides manifest + resolves chunk IDs). */
+interface ExpandablePlugin extends Plugin {
+    /**
+     * Build a manifest of candidate chunks for LLM expansion.
+     * Returns chunks from files NOT already in search results.
+     * Priority chunks (from import graph neighbors) are marked with `priority: true`.
+     *
+     * @param excludeFilePaths File paths already present in search results — excluded from manifest.
+     * @param excludeIds       Chunk IDs already in search results — excluded from manifest.
+     * @param resultFilePaths  File paths in search results — used to query import graph for priority chunks.
+     */
+    buildManifest(excludeFilePaths: string[], excludeIds: number[], resultFilePaths?: string[]): ExpanderManifestItem[];
+    /**
+     * Resolve chunk IDs back into SearchResults.
+     * Called after the expander selects additional IDs.
+     */
+    resolveChunks(ids: number[]): SearchResult[];
+}
+/** Check if a plugin supports context expansion. */
+declare function isExpandablePlugin(p: Plugin): p is ExpandablePlugin;
+/** Plugin that can resolve file paths/patterns directly to SearchResults (no search). */
+interface FileResolvablePlugin extends Plugin {
+    /**
+     * Resolve file paths, directories, and glob patterns to SearchResults.
+     * Each entry is resolved: exact → directory → glob → fuzzy basename fallback.
+     *
+     * @param patterns - File paths, directory prefixes (trailing `/`), or glob patterns (`*`).
+     */
+    resolveFiles(patterns: string[]): SearchResult[];
+}
+/** Check if a plugin can resolve files directly. */
+declare function isFileResolvable(p: Plugin): p is FileResolvablePlugin;
+/**
+ * Scan info for the TUI sidebar. Describes what content a plugin can index.
+ * Exported standalone by plugin packages — called BEFORE plugin initialization.
+ *
+ * @example
+ * ```typescript
+ * // brainbank-csv/index.ts
+ * export function scan(repoPath: string): PluginScanInfo { ... }
+ * ```
+ */
+interface PluginScanInfo {
+    /** Plugin name (e.g. 'csv', 'openapi'). */
+    name: string;
+    /** Whether there's content available to index. */
+    available: boolean;
+    /** Human-readable summary (e.g. '12 CSV files'). */
+    summary: string;
+    /** Emoji icon for TUI display. */
+    icon: string;
+    /** Whether checked by default in the module selector. */
+    checked: boolean;
+    /** Reason this plugin is disabled (shown when unavailable). */
+    disabled?: string;
+    /** Detail lines for the scan tree (e.g. per-file breakdown). */
+    details?: string[];
+}
+/**
+ * A single line in the TUI explorer preview panel.
+ * Returned by `preview()` — rendered as-is in the right panel.
+ *
+ * @example
+ * ```typescript
+ * // brainbank-csv/index.ts
+ * export function preview(repoPath: string): PluginPreviewLine[] {
+ *   return [
+ *     { text: '📊 3 CSV files', bold: true },
+ *     { text: '  sales.csv  2.3 MB', color: '#9ECE6A' },
+ *   ];
+ * }
+ * ```
+ */
+interface PluginPreviewLine {
+    /** Text content for this line. */
+    text: string;
+    /** Optional hex color (e.g. '#9ECE6A'). */
+    color?: string;
+    /** Render bold. */
+    bold?: boolean;
+    /** Render dimmed. */
+    dim?: boolean;
+}
+
+/**
+ * BrainBank — Re-embedding Engine
+ *
+ * Regenerates all vectors without re-indexing.
+ * Reads existing text from SQLite, embeds with the current provider,
+ * and replaces vector BLOBs. No file I/O, no git parsing, no re-chunking.
+ *
+ * Usage:
+ *   const result = await brain.reembed({ onProgress });
+ *   // → { code: 1200, git: 500, docs: 80, kv: 45, total: 1837 }
+ */
+
+interface ReembedResult {
+    /** Per-table vector counts. Keys are table names (e.g. 'code', 'git', 'docs', 'kv'). */
+    counts: Record<string, number>;
+    total: number;
+}
+interface ReembedOptions {
+    /** Progress callback: (tableName, current, total) */
+    onProgress?: ProgressCallback;
+    /** Batch size for embedBatch. Default: 50 */
+    batchSize?: number;
+}
+
+/**
+ * BrainBank — Watcher
+ *
+ * Thin coordinator for plugin-driven watching. Each plugin CAN drive its own
+ * watching via WatchablePlugin.watch(). For IndexablePlugins that don't
+ * implement WatchablePlugin, the Watcher provides a single shared fs.watch
+ * tree with fan-out routing so each plugin only receives relevant events.
+ *
+ * Responsibilities:
+ *   1. Call `plugin.watch(onEvent)` for each WatchablePlugin
+ *   2. For IndexablePlugins without watch(), share one recursive fs.watch tree
+ *   3. Route events to the correct plugin based on sub-repo scope
+ *   4. Dedup macOS double-fire events (change+rename per save)
+ *   5. Apply per-plugin debounce from `plugin.watchConfig()`
+ *   6. On event: call `plugin.indexItems([id])` or `plugin.index()` for re-indexing
+ *   7. Call `handle.stop()` on `close()`
+ *
+ *   const watcher = brain.watch({ debounceMs: 2000 });
+ *   watcher.close(); // stop watching
+ */
+
+interface WatchOptions {
+    /** Default debounce for plugins that don't specify watchConfig. Default: 2000 */
+    debounceMs?: number;
+    /** Glob patterns to ignore (from config.json code.ignore). */
+    ignore?: string[];
+    /** Called when a source triggers re-indexing. */
+    onIndex?: (sourceId: string, pluginName: string) => void;
+    /** Called on errors. */
+    onError?: (error: Error) => void;
+}
+/** Plugin-driven watcher that coordinates re-indexing across all WatchablePlugins. */
+declare class Watcher {
+    private _active;
+    private _batches;
+    private _reindexFn;
+    private _options;
+    private _keepalive;
+    constructor(reindexFn: () => Promise<void>, plugins: Plugin[], options?: WatchOptions, repoPath?: string);
+    /** Whether the watcher is active. */
+    get active(): boolean;
+    /** Stop all plugin watchers. */
+    close(): Promise<void>;
+    /** Start watching for each WatchablePlugin, with shared fs.watch fallback. */
+    private _startWatching;
+    /**
+     * Single shared recursive fs.watch that fans out events to multiple plugins.
+     * Each event is routed based on file extension (docs → .md only, code → isSupported).
+     */
+    private _startSharedFsWatch;
+    /** Handle an incoming event from a plugin. */
+    private _onEvent;
+    /** Flush pending events for a plugin — trigger re-indexing. */
+    private _flush;
+}
+
+/**
+ * BrainBank — Main Orchestrator
+ *
+ * Thin facade that composes services:
+ *   - **PluginRegistry** — registration + lookup
+ *   - **SearchAPI** — all search + context logic
+ *   - **runIndex** — code / git / docs indexing orchestration
+ *
+ * Initialization is inline — no indirection layers.
+ * All heavy logic lives in those modules; BrainBank owns state,
+ * guards (`_requireInit` / `initialize`), and public API shape.
+ *
+ * Multi-process coordination:
+ *   - `ensureFresh()` detects stale HNSW indices via `index_state` table
+ *   - Hot-reloads from disk when another process updated the index
+ *   - Called implicitly before every search operation
+ */
+
+declare class BrainBank extends EventEmitter {
+    private _config;
+    private _db;
+    private _embedding;
+    private _registry;
+    private _searchAPI?;
+    private _indexDeps?;
+    private _kvService?;
+    private _initialized;
+    private _initPromise;
+    private _watcher?;
+    private _webhookServer?;
+    private _sharedHnsw;
+    private _repoDBs;
+    private _loadedVersions;
+    constructor(config?: BrainBankConfig);
+    /** Whether the brainbank has been initialized. */
+    get isInitialized(): boolean;
+    /** The resolved configuration. */
+    get config(): Readonly<ResolvedConfig>;
+    /** All registered plugin names (insertion order). */
+    get plugins(): string[];
+    /**
+     * Register a plugin. Chainable.
+     *
+     * @example
+     * brain.use(code({ repoPath: '.' })).use(docs());
+     *
+     * @throws If called after `initialize()`.
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Check if a plugin is loaded.
+     * Also matches type prefix (e.g. `'code'` matches `'code:frontend'`).
+     */
+    has(name: string): boolean;
+    /** Get a plugin instance by name. Returns `undefined` if not loaded. */
+    plugin<T extends Plugin = Plugin>(name: string): T | undefined;
+    /**
+     * Initialize database, HNSW indices, and load existing vectors.
+     * Automatically called by `index` / `search` methods if not yet initialized.
+     * Concurrent calls are deduped via `_initPromise`.
+     *
+     * @param options.force - If `true`, skip vector load on dimension mismatch.
+     */
+    initialize(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Estimated memory footprint of loaded HNSW indices (bytes).
+     * Counts only vector data: `vectorCount × dims × 4`.
+     * Returns 0 if not initialized.
+     */
+    memoryHint(): number;
+    /** Close database and release all resources. Synchronous. */
+    close(): void;
+    /**
+     * Get or create a dynamic collection (universal KV primitive).
+     *
+     * @example
+     * const errors = brain.collection('debug_errors');
+     * await errors.add('Fixed null check', { file: 'api.ts' });
+     * const hits = await errors.search('null pointer');
+     *
+     * @throws If not initialized.
+     */
+    collection(name: string): ICollection;
+    /** List all collection names that have data. */
+    listCollectionNames(): string[];
+    /** Delete a collection's data and evict from cache. */
+    deleteCollection(name: string): void;
+    /** Run indexing across selected modules. Auto-initializes. */
+    index(options?: {
+        modules?: string[];
+        forceReindex?: boolean;
+        onProgress?: StageProgressCallback;
+        pluginOptions?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Detect stale HNSW indices and hot-reload from disk.
+     * Called implicitly before every search operation.
+     * Cost: one SQLite SELECT (~5μs on WAL mode).
+     */
+    ensureFresh(): Promise<void>;
+    /**
+     * Semantic search across all loaded modules.
+     * Scope via `sources: { code: 10, git: 0 }`.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Hybrid search: vector + BM25 fused with Reciprocal Rank Fusion.
+     * Scope via `sources: { code: 10, git: 5, docs: 3, myNotes: 5 }`.
+     */
+    hybridSearch(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** BM25 keyword search only (no embeddings needed). */
+    searchBM25(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Build formatted context block for LLM system prompt injection. Auto-initializes. */
+    getContext(task: string, options?: ContextOptions): Promise<string>;
+    /**
+     * Resolve file paths, directories, and glob patterns to full SearchResults.
+     * Bypasses search entirely — reads directly from plugin indexes.
+     *
+     * @example
+     * const files = brain.resolveFiles(['src/auth/login.ts', 'src/graph/']);
+     */
+    resolveFiles(patterns: string[]): SearchResult[];
+    /** Rebuild FTS5 indices. */
+    rebuildFTS(): void;
+    /** Get statistics for all loaded plugins. */
+    stats(): Record<string, Record<string, number | string> | undefined>;
+    /** Start watching for changes and auto-re-index. */
+    watch(options?: WatchOptions): Watcher;
+    /**
+     * Re-embed all existing text with the current embedding provider.
+     * Use after switching providers (e.g. Local → OpenAI).
+     */
+    reembed(options?: ReembedOptions): Promise<ReembedResult>;
+    /**
+     * Linear 8-step initialization:
+     * 1. Open database
+     * 2. Resolve embedding provider
+     * 3. Check dimension mismatch
+     * 4. Create KV HNSW + KVService
+     * 5. Load KV vectors
+     * 6. Initialize plugins
+     * 7. Persist HNSW indices
+     * 8. Build SearchAPI + index deps
+     */
+    private _runInitialize;
+    /** Reset shared state after a failed `_runInitialize`. */
+    private _cleanupAfterFailedInit;
+    /** Resolve embedding: explicit config > stored DB key > local default. */
+    private _resolveEmbedding;
+    /**
+     * Get or create a per-repo SQLiteAdapter for namespaced plugins.
+     * Non-namespaced plugins use the root DB.
+     * DB path: `.brainbank/<repoName>.db` (e.g., `servicehub-backend.db`).
+     */
+    private _getOrCreatePluginDb;
+    /** Build a per-plugin `PluginContext` with appropriate DB and HNSW scoping. */
+    private _buildPluginContext;
+    /**
+     * Reload a single HNSW index by name.
+     * Discovers the vector table via ReembeddablePlugin capability.
+     * KV is handled directly since it's core-owned.
+     *
+     * The `name` comes from `index_state` and equals the plugin's `mod.name`
+     * (e.g. `code:backend`, `git`, `docs`). This matches the key used in
+     * `getOrCreateSharedHnsw()` during initialization.
+     */
+    private _reloadIndex;
+    /** Guard: throw descriptive error if not initialized. */
+    private _requireInit;
+}
+
+/** HNSW index key for KV collections (core-owned). */
+declare const HNSW: {
+    readonly KV: "kv";
+};
+type HnswKey = typeof HNSW[keyof typeof HNSW];
+
+/**
+ * BrainBank — Local Embedding Provider
+ *
+ * Uses @xenova/transformers with all-MiniLM-L6-v2 (384 dims, WASM).
+ * Downloads ~23MB on first use, cached locally.
+ * No external API calls — runs entirely in-process.
+ */
+
+declare class LocalEmbedding implements EmbeddingProvider {
+    readonly dims: number;
+    private _pipeline;
+    private _modelName;
+    private _cacheDir;
+    constructor(options?: {
+        model?: string;
+        cacheDir?: string;
+    });
+    private _pipelinePromise;
+    /**
+     * Lazy-load the transformer pipeline.
+     * Singleton — created once and reused.
+     * Promise-deduped to prevent concurrent downloads.
+     */
+    private _getPipeline;
+    /**
+     * Embed a single text string.
+     * Returns a normalized Float32Array of length 384.
+     */
+    embed(text: string): Promise<Float32Array>;
+    /**
+     * Embed multiple texts using real batch processing.
+     * Chunks into groups of BATCH_SIZE to balance throughput vs memory.
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * BrainBank — OpenAI Embedding Provider
+ *
+ * Uses OpenAI's embedding API via fetch (no SDK dependency).
+ * Supports text-embedding-3-small, text-embedding-3-large, and ada-002.
+ *
+ * Usage:
+ *   const brain = new BrainBank({
+ *     embeddingProvider: new OpenAIEmbedding({ model: 'text-embedding-3-small' }),
+ *   });
+ */
+
+interface OpenAIEmbeddingOptions {
+    /** OpenAI API key. Falls back to OPENAI_API_KEY env var. */
+    apiKey?: string;
+    /** Model name. Default: 'text-embedding-3-small' */
+    model?: string;
+    /** Vector dimensions. If omitted, uses model default. text-embedding-3-* supports custom dims. */
+    dims?: number;
+    /** Base URL override (for Azure, proxies, etc.) */
+    baseUrl?: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+}
+declare class OpenAIEmbedding implements EmbeddingProvider {
+    readonly dims: number;
+    private _apiKey;
+    private _model;
+    private _baseUrl;
+    private _requestDims;
+    private _timeout;
+    constructor(options?: OpenAIEmbeddingOptions);
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    close(): Promise<void>;
+    private _isTokenLimitError;
+    private _request;
+    /** Handle API errors with token-limit retry logic. */
+    private _handleApiError;
+}
+
+/**
+ * BrainBank — Perplexity Standard Embedding Provider
+ *
+ * Uses Perplexity's embedding API via fetch (no SDK dependency).
+ * Models: pplx-embed-v1-0.6b (1024d) and pplx-embed-v1-4b (2560d).
+ *
+ * Perplexity returns base64-encoded signed int8 vectors by default.
+ * This provider decodes them to Float32Array for HNSW compatibility.
+ *
+ * Usage:
+ *   const brain = new BrainBank({
+ *     embeddingProvider: new PerplexityEmbedding({ model: 'pplx-embed-v1-4b' }),
+ *   });
+ */
+
+interface PerplexityEmbeddingOptions {
+    /** Perplexity API key. Falls back to PERPLEXITY_API_KEY env var. */
+    apiKey?: string;
+    /** Model name. Default: 'pplx-embed-v1-4b' */
+    model?: string;
+    /** Vector dimensions (Matryoshka reduction). If omitted, uses model default. */
+    dims?: number;
+    /** Base URL override. */
+    baseUrl?: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+}
+declare class PerplexityEmbedding implements EmbeddingProvider {
+    readonly dims: number;
+    private _apiKey;
+    private _model;
+    private _baseUrl;
+    private _requestDims;
+    private _timeout;
+    constructor(options?: PerplexityEmbeddingOptions);
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    close(): Promise<void>;
+    private _request;
+}
+
+/**
+ * BrainBank — Perplexity Contextualized Embedding Provider
+ *
+ * Uses Perplexity's contextualized embeddings API for document-aware vectors.
+ * Chunks from the same document share context, improving retrieval quality.
+ *
+ * Models: pplx-embed-context-v1-0.6b (1024d), pplx-embed-context-v1-4b (2560d).
+ *
+ * Key difference from standard: input is string[][] (docs × chunks) and the
+ * response has a nested structure. This provider adapts the flat BrainBank
+ * EmbeddingProvider interface to the nested Perplexity API:
+ *   - embed(text)       → wraps as [[text]]
+ *   - embedBatch(texts) → wraps as [texts] (one "document" of related chunks)
+ *
+ * Usage:
+ *   const brain = new BrainBank({
+ *     embeddingProvider: new PerplexityContextEmbedding(),
+ *   });
+ */
+
+interface PerplexityContextEmbeddingOptions {
+    /** Perplexity API key. Falls back to PERPLEXITY_API_KEY env var. */
+    apiKey?: string;
+    /** Model name. Default: 'pplx-embed-context-v1-4b' */
+    model?: string;
+    /** Vector dimensions (Matryoshka reduction). If omitted, uses model default. */
+    dims?: number;
+    /** Base URL override. */
+    baseUrl?: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+}
+declare class PerplexityContextEmbedding implements EmbeddingProvider {
+    readonly dims: number;
+    private _apiKey;
+    private _model;
+    private _baseUrl;
+    private _requestDims;
+    private _timeout;
+    constructor(options?: PerplexityContextEmbeddingOptions);
+    /** Embed a single text. Wraps as [[text]] for the contextualized API. */
+    embed(text: string): Promise<Float32Array>;
+    /**
+     * Embed multiple texts as chunks of contextualized documents.
+     * Splits into sub-documents to stay under Perplexity's 32k token/doc limit.
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    close(): Promise<void>;
+    /** Send a contextualized request. Input is string[][] (docs × chunks). */
+    private _request;
+}
+
+/**
+ * BrainBank — Embedding Worker Proxy
+ *
+ * Drop-in replacement for any EmbeddingProvider that offloads
+ * embedding computation to a dedicated worker thread.
+ * The main thread's event loop stays free for serving searches.
+ *
+ * Usage:
+ *   const proxy = new EmbeddingWorkerProxy('local', { model: '...' });
+ *   await proxy.ready();
+ *   const vec = await proxy.embed('hello');
+ */
+
+declare class EmbeddingWorkerProxy implements EmbeddingProvider {
+    private _worker;
+    private _nextId;
+    private _pending;
+    private _ready;
+    private _dims;
+    /** Embedding dimensions (available after `ready()` resolves). */
+    get dims(): number;
+    constructor(providerType: string, providerOptions?: Record<string, unknown>);
+    /** Wait for the worker to be ready (provider loaded). */
+    ready(): Promise<void>;
+    /** Send a request to the worker and wait for the response. */
+    private _send;
+    /** Embed a single text string. */
+    embed(text: string): Promise<Float32Array>;
+    /** Embed multiple texts in a batch. */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** Terminate the worker. */
+    close(): Promise<void>;
+}
+
+/**
+ * HttpServer — Lightweight JSON API for BrainBank.
+ *
+ * Exposes BrainBank operations over HTTP so CLI commands can delegate
+ * to a running server instead of cold-loading models each time.
+ *
+ * Routes:
+ *   POST /context  → brain.getContext()
+ *   POST /search   → brain.search()
+ *   POST /hsearch  → brain.hybridSearch()
+ *   POST /ksearch  → brain.searchBM25()
+ *   POST /index    → brain.index()
+ *   GET  /health   → { ok, pid, uptime, port }
+ */
+
+interface HttpServerOptions {
+    port?: number;
+    /** Factory to create a BrainBank instance for a given repo path. */
+    factory: (repoPath: string) => Promise<BrainBank>;
+    /** Default repo path when request doesn't specify one. */
+    defaultRepo?: string;
+    /** Called when an error occurs during pool operations. */
+    onError?: (repo: string, err: unknown) => void;
+    /** Called on server lifecycle events. */
+    onLog?: (msg: string) => void;
+}
+declare class HttpServer {
+    private _server;
+    private _pool;
+    private _port;
+    private _defaultRepo;
+    private _startTime;
+    private _log;
+    constructor(options: HttpServerOptions);
+    /** Start listening. Writes PID file for daemon detection. */
+    start(): Promise<void>;
+    /** Stop the server and clean up. */
+    close(): void;
+    get port(): number;
+    private _handleRequest;
+    private _handleHealth;
+    private _handleContext;
+    private _handleIndex;
+    private _handleSearch;
+    private _readBody;
+}
+
+/**
+ * Daemon — PID file management for the BrainBank HTTP server.
+ *
+ * PID file: ~/.cache/brainbank/server.pid
+ * Format: JSON { pid: number, port: number }
+ *
+ * Used by:
+ *   - `brainbank daemon` to write PID on start
+ *   - `brainbank daemon stop` to find and kill the daemon
+ *   - `brainbank status` to report server state
+ *   - CLI commands to detect running server for delegation
+ */
+declare const DEFAULT_PORT = 8181;
+interface PidInfo {
+    pid: number;
+    port: number;
+}
+/** Write the PID file after server starts. */
+declare function writePid(pid: number, port: number): void;
+/** Read PID info from file. Returns null if missing or malformed. */
+declare function readPid(): PidInfo | null;
+/** Remove the PID file. */
+declare function removePid(): void;
+/**
+ * Check if the server process is still alive.
+ * Uses `kill(pid, 0)` which doesn't actually send a signal —
+ * it just checks whether the process exists.
+ */
+declare function isServerRunning(): PidInfo | null;
+/** Get the server URL if running, or null. */
+declare function getServerUrl(): string | null;
+
+/**
+ * BrainBank — Haiku Pruner
+ *
+ * LLM-based noise filter using Anthropic's Haiku 4.5 model.
+ * Binary classification: for each search result, Haiku decides
+ * "relevant" or "noise" based on filePath, metadata, and full
+ * file content (capped at ~8K chars per item by prune.ts).
+ *
+ * Latency: ~300-600ms.
+ */
+
+interface HaikuPrunerOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+declare class HaikuPruner implements Pruner {
+    private readonly _apiKey;
+    private readonly _model;
+    constructor(options?: HaikuPrunerOptions);
+    prune(query: string, items: PrunerItem[]): Promise<number[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * BrainBank — Prune Utility
+ *
+ * Bridges SearchResult[] → Pruner.prune() → filtered SearchResult[].
+ * Converts results to lightweight PrunerItems with full content previews,
+ * calls the pruner, and filters out dropped results.
+ *
+ * Content strategy: send the FULL chunk content to the pruner so it can
+ * make informed decisions. A per-item character cap prevents cost blowups
+ * on monster files — when truncated, the middle is kept (imports + core
+ * logic) rather than just the top.
+ */
+
+/** Run the pruner on search results. Returns results in the order the pruner chose. */
+declare function pruneResults(query: string, results: SearchResult[], pruner: Pruner): Promise<SearchResult[]>;
+
+/**
+ * BrainBank — Haiku Expander
+ *
+ * LLM-powered context expansion using Anthropic's Haiku 4.5 model.
+ * After search + pruning, reviews a manifest of available chunks
+ * and requests additional IDs to include.
+ *
+ * Flow:
+ *   1. Receives lightweight manifest (~20 chars per chunk)
+ *   2. Haiku selects additional chunk IDs (just numbers, fast)
+ *   3. Caller fetches those chunks from DB and splices into results
+ *
+ * Designed for minimal token usage:
+ *   - Input: ~2,000-3,000 tokens (manifest)
+ *   - Output: ~50-100 tokens (ID array)
+ *   - Cost: ~$0.001 per call
+ *   - Latency: ~300-600ms
+ *
+ * Fail-open: any error returns empty array (no expansion).
+ */
+
+interface HaikuExpanderOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+declare class HaikuExpander implements Expander {
+    private readonly _apiKey;
+    private readonly _model;
+    constructor(options?: HaikuExpanderOptions);
+    expand(query: string, currentIds: number[], manifest: ExpanderManifestItem[]): Promise<ExpanderResult>;
+    /** Parse Haiku response — handles both `{ ids, note }` and bare `[...]` formats. */
+    private _parseResponse;
+    close(): Promise<void>;
+}
+
+/**
+ * BrainBank — Provider Key
+ *
+ * Infers a stable key from an existing EmbeddingProvider instance.
+ * Lives in lib/ (Layer 0) to avoid db/ → providers/ dependency.
+ */
+
+/** Known embedding provider keys. */
+type EmbeddingKey = 'local' | 'openai' | 'perplexity' | 'perplexity-context';
+/** Infer a stable key from an existing provider instance. */
+declare function providerKey(p: EmbeddingProvider): EmbeddingKey;
+
+/**
+ * BrainBank — Embedding Provider Resolver
+ *
+ * Resolves an EmbeddingProvider from a stored key string.
+ * Used by the Initializer to auto-resolve from DB config.
+ */
+
+/** Resolve an EmbeddingProvider from a key string. Lazy-loads the provider module. */
+declare function resolveEmbedding(key: string): Promise<EmbeddingProvider>;
+
+declare const DEFAULTS: ResolvedConfig;
+/**
+ * Merge partial config with defaults.
+ * All fields become required.
+ * Relative dbPath is resolved against repoPath.
+ */
+declare function resolveConfig(partial?: BrainBankConfig): ResolvedConfig;
+
+/**
+ * BrainBank — Maximum Marginal Relevance (MMR)
+ *
+ * Diversifies vector search results to avoid returning redundant items.
+ * λ=1.0 → pure relevance, λ=0.0 → pure diversity.
+ * Default λ=0.7 balances both.
+ */
+
+/**
+ * Search with Maximum Marginal Relevance for diversified results.
+ *
+ * Algorithm:
+ *   1. Get 3x candidates from HNSW
+ *   2. Greedily select items that maximize: λ * relevance - (1-λ) * max_sim_to_selected
+ */
+declare function searchMMR(index: VectorIndex, query: Float32Array, vectorCache: Map<number, Float32Array>, k: number, lambda?: number): SearchHit[];
+
+/**
+ * BrainBank — Language Registry
+ *
+ * Supported file extensions, language mappings, and ignore lists.
+ * Controls which files get indexed and how they're chunked.
+ */
+declare const SUPPORTED_EXTENSIONS: Record<string, string>;
+declare const IGNORE_DIRS: Set<string>;
+/** Check if a file extension is supported for indexing. */
+declare function isSupported(filePath: string): boolean;
+/** Get the language name for a file. Returns undefined if not supported. */
+declare function getLanguage(filePath: string): string | undefined;
+/** Check if a directory name should be ignored. */
+declare function isIgnoredDir(dirName: string): boolean;
+/** Check if a filename should be ignored. */
+declare function isIgnoredFile(fileName: string): boolean;
+
+/**
+ * BrainBank — Math Utilities
+ *
+ * Pure vector math functions for similarity calculations.
+ * No dependencies — works on Float32Array directly.
+ */
+/**
+ * Cosine similarity between two vectors.
+ * Assumes vectors are already normalized (unit length).
+ * Returns value between -1.0 and 1.0.
+ */
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * L2-normalize a vector to unit length.
+ * Returns a new Float32Array.
+ */
+declare function normalize(vec: Float32Array): Float32Array;
+/**
+ * Convert a Float32Array to a Buffer for SQLite storage.
+ * Handles views with non-zero byteOffset (e.g. from batched embedding output).
+ * Using Buffer.from(vec.buffer) directly is WRONG for views — it copies the entire parent buffer.
+ */
+declare function vecToBuffer(vec: Float32Array): Buffer;
+
+/**
+ * BrainBank — KV Service
+ *
+ * Owns the shared HNSW index and vector cache for KV collections.
+ * Provides collection creation, listing, and deletion.
+ * Extracted from BrainBank to separate infrastructure from facade.
+ */
+
+declare class KVService {
+    private _db;
+    private _embedding;
+    private _hnsw;
+    private _vecs;
+    private _collections;
+    constructor(_db: DatabaseAdapter, _embedding: EmbeddingProvider, _hnsw: HNSWIndex, _vecs: Map<number, Float32Array>);
+    /** Get or create a named collection. */
+    collection(name: string): Collection;
+    /** List all collection names that have data. */
+    listNames(): string[];
+    /** Delete a collection's data and evict from cache. Removes vectors from HNSW to prevent ghost entries. */
+    delete(name: string): void;
+    /** Access the shared HNSW index (used by reembed). */
+    get hnsw(): HNSWIndex;
+    /** Access the shared vector cache. @internal */
+    get vecs(): Map<number, Float32Array>;
+    /** Clear all cached collections and vectors. */
+    clear(): void;
+}
+
+/**
+ * BrainBank — Plugin Registry
+ *
+ * Manages registration and lookup of plugins.
+ * Extracted from BrainBank so the facade stays focused on orchestration.
+ *
+ * Responsibilities:
+ *   - Store plugins by name
+ *   - Alias resolution      (currently none; add here if needed)
+ *   - Consistent error messages on missing plugins
+ */
+
+declare class PluginRegistry {
+    private _map;
+    /** Store a plugin. Duplicate names silently overwrite. */
+    register(plugin: Plugin): void;
+    /** Check whether a plugin is registered (exact match). */
+    has(name: string): boolean;
+    /**
+     * Get a plugin by name.  Throws a descriptive error if not found.
+     *
+     * Resolution order:
+     *   1. Alias map   (currently empty)
+     *   2. Exact match
+     */
+    get<T extends Plugin = Plugin>(name: string): T;
+    /** All registered plugin names (insertion order). */
+    get names(): string[];
+    /** All registered plugin instances (insertion order). */
+    get all(): Plugin[];
+    /**
+     * Underlying Map.
+     * Prefer `all` everywhere else.
+     */
+    get raw(): Map<string, Plugin>;
+    /** Remove all registered plugins. Called by BrainBank.close(). */
+    clear(): void;
+}
+
+/**
+ * BrainBank — Context Builder
+ *
+ * Orchestrates the context-building pipeline:
+ *   1. Vector search (primary)
+ *   2. Path scoping (filter)
+ *   3. LLM noise pruning (optional)
+ *   4. Session dedup (filter)
+ *   5. LLM context expansion (optional — expander field)
+ *   6. Plugin formatters (output)
+ *
+ * All search post-processing lives in `bm25-boost.ts`.
+ * Plugin-agnostic — discovers formatters from ContextFormatterPlugin.
+ */
+
+declare class ContextBuilder {
+    private _search;
+    private _registry;
+    private _pruner?;
+    private _embedding?;
+    private _configFields;
+    private _expander?;
+    constructor(_search: SearchStrategy | undefined, _registry: PluginRegistry, _pruner?: Pruner | undefined, _embedding?: EmbeddingProvider | undefined, _configFields?: Record<string, unknown>, _expander?: Expander | undefined);
+    /** Set config-level context field defaults (from config.json "context" section). */
+    set configFields(fields: Record<string, unknown>);
+    /** Set the expander instance. */
+    set expander(expander: Expander | undefined);
+    /** Build a full context block for a task. Returns markdown for system prompt. */
+    build(task: string, options?: ContextOptions): Promise<string>;
+    /** Invoke ContextFormatterPlugins. */
+    private _appendFormatterResults;
+    /**
+     * Resolve context fields: plugin defaults ← config.json ← per-query.
+     * Returns a flat Record with the final value for each field.
+     */
+    private _resolveFields;
+    /**
+     * Run LLM expansion: build manifest of candidate chunks from files
+     * NOT already in search results, call expander, resolve selected IDs.
+     */
+    private _expand;
+    /** Collect results from SearchablePlugins that don't have their own formatter. */
+    private _appendSearchableResults;
+}
+
+/**
+ * BrainBank — Composite Vector Search
+ *
+ * Generic orchestrator for domain-specific vector searches.
+ * Embeds the query once, delegates to registered DomainVectorSearch strategies.
+ * Uses round-robin interleaving when multiple strategies exist to ensure
+ * balanced representation across domains.
+ * Plugin-agnostic — strategies are discovered at wiring time.
+ */
+
+interface CompositeVectorConfig {
+    strategies: Map<string, DomainVectorSearch>;
+    embedding: EmbeddingProvider;
+    /** Default K values per strategy name. Strategies not listed default to 0. */
+    defaults?: Record<string, number>;
+}
+declare class CompositeVectorSearch implements SearchStrategy {
+    private _c;
+    /** Default K when no source override is provided. */
+    private static readonly DEFAULT_K;
+    constructor(_c: CompositeVectorConfig);
+    /** Search across all registered domain strategies with score-based merge. */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * BrainBank — Composite BM25 Search Strategy
+ *
+ * Generic BM25 coordinator that discovers BM25SearchPlugin instances
+ * from the registry and delegates per-source keyword search.
+ */
+
+declare class CompositeBM25Search implements SearchStrategy {
+    private _registry;
+    constructor(_registry: PluginRegistry);
+    /**
+     * Run BM25 keyword search across all plugins that implement BM25SearchPlugin.
+     * Each plugin searches its own FTS5 tables.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Rebuild FTS5 indices across all BM25 plugins. */
+    rebuild(): void;
+}
+
+/**
+ * BrainBank — Reciprocal Rank Fusion (RRF)
+ *
+ * Combines results from multiple search systems (vector + BM25)
+ * using the RRF algorithm: score = Σ 1/(k + rank_i)
+ *
+ * This is the same algorithm used by Elasticsearch, QMD, and most
+ * production hybrid search systems. Simple but very effective.
+ *
+ * Reference: Cormack et al., "Reciprocal Rank Fusion outperforms
+ * Condorcet and individual Rank Learning Methods" (2009)
+ */
+
+/**
+ * Fuse ranked lists from different search systems into a single ranked list.
+ *
+ * @param resultSets - Arrays of SearchResult from different systems (e.g. vector, BM25)
+ * @param k - Smoothing constant. Default: 60 (standard value). Higher = less emphasis on top ranks.
+ * @param maxResults - Maximum results to return.
+ */
+declare function reciprocalRankFusion(resultSets: SearchResult[][], k?: number, maxResults?: number): SearchResult[];
+
+/**
+ * BrainBank — FTS Utilities
+ *
+ * Shared helpers for SQLite FTS5 query sanitization.
+ */
+/**
+ * Sanitize a user query for FTS5 syntax.
+ * Strips operators that would cause parse errors, splits compound words,
+ * and converts words to implicit AND with exact-match quoting.
+ */
+declare function sanitizeFTS(query: string): string;
+/**
+ * Normalize BM25 score from SQLite (negative, lower = better)
+ * to 0.0–1.0 (higher = better) for consistency with vector search.
+ */
+declare function normalizeBM25(rawScore: number): number;
+/**
+ * Escape SQL LIKE wildcard characters (`%`, `_`, `\`).
+ * Use with `LIKE ? ESCAPE '\'` in queries.
+ */
+declare function escapeLike(s: string): string;
+
+/**
+ * BrainBank — Database Metadata
+ *
+ * Helpers for reading/writing metadata stored in core SQLite tables:
+ *
+ * - **Index State** — cross-process HNSW version tracking.
+ *   Processes compare in-memory versions with DB to detect staleness
+ *   and trigger hot-reload via `ensureFresh()`.
+ *
+ * - **Embedding Meta** — tracks which embedding provider is stored in
+ *   the database. Detects dimension mismatches at startup and updates
+ *   metadata after `reembed()`.
+ */
+
+/**
+ * Increment the version for a given index name.
+ * Sets writer_pid to current process PID.
+ * Uses UPSERT so the row is created on first call.
+ */
+declare function bumpVersion(db: DatabaseAdapter, name: string): number;
+/**
+ * Get all index versions as a Map.
+ * Used by `ensureFresh()` to compare against in-memory versions.
+ */
+declare function getVersions(db: DatabaseAdapter): Map<string, number>;
+/** Get the version of a single index. Returns 0 if not found. */
+declare function getVersion(db: DatabaseAdapter, name: string): number;
+
+/**
+ * BrainBank — Write Lock
+ *
+ * Advisory file lock for cross-process HNSW write exclusion.
+ * Uses `O_CREAT | O_EXCL` for atomic lock creation — works on all OS.
+ * Stale locks (dead PID) are detected and stolen automatically.
+ */
+/**
+ * Acquire an advisory lock. Blocks with exponential backoff if another
+ * process holds the lock. Steals stale locks from dead processes.
+ *
+ * @throws After MAX_WAIT_MS if the lock cannot be acquired.
+ */
+declare function acquireLock(lockDir: string, name: string): Promise<void>;
+/** Release an advisory lock. Safe to call even if not held. */
+declare function releaseLock(lockDir: string, name: string): void;
+/**
+ * Execute a function while holding an advisory lock.
+ * Lock is always released, even on error.
+ */
+declare function withLock<T>(lockDir: string, name: string, fn: () => T | Promise<T>): Promise<T>;
+
+/**
+ * BrainBank — SQLite Adapter
+ *
+ * Implements `DatabaseAdapter` using Node.js built-in `node:sqlite`.
+ * Zero native addons — no ABI issues across Node versions.
+ * Handles WAL mode, directory creation, schema init, and transactions.
+ */
+
+declare class SQLiteAdapter implements DatabaseAdapter {
+    private _db;
+    readonly capabilities: AdapterCapabilities;
+    constructor(dbPath: string);
+    /** Prepare a reusable statement. */
+    prepare<T = unknown>(sql: string): PreparedStatement<T>;
+    /** Execute raw SQL (no results). */
+    exec(sql: string): void;
+    /** Run a function inside a transaction. Auto-commits on success, auto-rollbacks on error. */
+    transaction<T>(fn: () => T): T;
+    /** Run a prepared statement on multiple rows. Wraps in a single transaction. */
+    batch<T extends unknown[]>(sql: string, rows: T[]): void;
+    /** Close the database. */
+    close(): void;
+    /**
+     * Access the underlying `node:sqlite` DatabaseSync instance.
+     *
+     * @deprecated Use `DatabaseAdapter` methods instead. This exists
+     * only for gradual migration of plugins that depend on driver internals.
+     */
+    raw<T = unknown>(): T;
+}
+
+/**
+ * BrainBank — Brain Context
+ *
+ * Portable input for `createBrain()`. Decouples the factory from
+ * `process.argv` / `process.env` so it can be called from the CLI,
+ * MCP server, tests, or any programmatic consumer.
+ */
+/** Everything the factory needs to build a BrainBank instance. */
+interface BrainContext {
+    /** Repository root path. */
+    repoPath: string;
+    /** Environment variable overrides. Falls back to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** CLI flag overrides (e.g. `{ ignore: 'dist,vendor' }`). */
+    flags?: Record<string, string | undefined>;
+}
+/** Build a `BrainContext` from CLI argv + process.env. */
+declare function contextFromCLI(repoPath?: string): BrainContext;
+
+/**
+ * BrainBank CLI — Config Loader
+ *
+ * Loads .brainbank/config.json (or .ts/.js/.mjs fallback).
+ * Config priority: CLI flags > config file > defaults.
+ */
+
+/** Full .brainbank/config.json schema. */
+interface ProjectConfig {
+    plugins?: string[];
+    embedding?: string;
+    pruner?: string;
+    maxFileSize?: number;
+    indexers?: Plugin[];
+    brainbank?: Partial<BrainBankConfig>;
+    /** Optional API keys — override env vars. Kept out of version control. */
+    keys?: {
+        anthropic?: string;
+        perplexity?: string;
+        openai?: string;
+    };
+    /** Context field defaults (e.g. { lines: true, callTree: true, symbols: false }). */
+    context?: Record<string, unknown>;
+    /** Per-plugin config sections (e.g. code, git, docs). */
+    [pluginName: string]: unknown;
+}
+
+/**
+ * BrainBank CLI — Brain Factory
+ *
+ * Creates a configured BrainBank instance with dynamically loaded plugins,
+ * auto-discovered indexers, and config file support.
+ * Delegates to focused modules in factory/.
+ */
+
+/** Reset factory caches. Useful for tests. */
+declare function resetFactoryCache(): void;
+/**
+ * Create a BrainBank with built-in + discovered + config plugins.
+ *
+ * Accepts either a `BrainContext` (for programmatic use) or an optional
+ * `repoPath` string (for CLI backward compat — builds context from argv).
+ */
+declare function createBrain(contextOrRepo?: BrainContext | string): Promise<BrainBank>;
+
+export { type AdapterCapabilities, type BM25SearchPlugin, BrainBank, type BrainBankConfig, type BrainContext, type CoEditPlugin, type CoEditSuggestion, type CodeChunk, type CodeResult, type CodeResultMetadata, Collection, type CollectionAddOptions, type CollectionItem, type CollectionResult, type CollectionSearchOptions, type CommitResult, type CommitResultMetadata, CompositeBM25Search, CompositeVectorSearch, ContextBuilder, type ContextFieldDef, type ContextFieldPlugin, type ContextFormatterPlugin, type ContextOptions, type CountRow, DEFAULTS, DEFAULT_PORT, type DatabaseAdapter, type DocChunk, type DocsPlugin, type DocumentCollection, type DocumentResult, type DocumentResultMetadata, type DomainVectorSearch, type EmbeddingKey, type EmbeddingMetaRow, type EmbeddingProvider, EmbeddingWorkerProxy, type ExecuteResult, type ExpandablePlugin, type Expander, type ExpanderManifestItem, type ExpanderResult, type FileResolvablePlugin, type GitCommitRecord, HNSW, HNSWIndex, HaikuExpander, type HaikuExpanderOptions, HaikuPruner, type HaikuPrunerOptions, type HnswKey, HttpServer, type HttpServerOptions, IGNORE_DIRS, type IncrementalTracker, type IndexResult, type IndexablePlugin, KVService, type KvDataRow, type KvVectorRow, LocalEmbedding, type MigratablePlugin, type Migration, OpenAIEmbedding, type OpenAIEmbeddingOptions, PerplexityContextEmbedding, type PerplexityContextEmbeddingOptions, PerplexityEmbedding, type PerplexityEmbeddingOptions, type Plugin, type PluginContext, type PluginPreviewLine, type PluginScanInfo, type PreparedStatement, type ProgressCallback, type ProjectConfig, type Pruner, type PrunerItem, type ReembedOptions, type ReembedResult, type ReembedTable, type ReembeddablePlugin, type ResolvedConfig, SQLiteAdapter, SUPPORTED_EXTENSIONS, type SearchHit, type SearchOptions, type SearchResult, type SearchResultType, type SearchStrategy, type SearchablePlugin, type StageProgressCallback, type VectorIndex, type VectorRow, type VectorSearchPlugin, type WatchConfig, type WatchEvent, type WatchEventHandler, type WatchHandle, type WatchOptions, type WatchablePlugin, Watcher, type WebhookHandler, WebhookServer, acquireLock, bumpVersion, contextFromCLI, cosineSimilarity, createBrain, createTracker, escapeLike, getLanguage, getServerUrl, getVersion, getVersions, isBM25SearchPlugin, isCoEditPlugin, isCodeResult, isCollectionResult, isCommitResult, isContextFieldPlugin, isContextFormatterPlugin, isDocsPlugin, isDocumentResult, isExpandablePlugin, isFileResolvable, isIgnoredDir, isIgnoredFile, isIndexable, isMigratable, isReembeddable, isSearchable, isServerRunning, isSupported, isVectorSearchPlugin, isWatchable, matchResult, normalize, normalizeBM25, providerKey, pruneResults, readPid, reciprocalRankFusion, releaseLock, removePid, resetFactoryCache, resolveConfig, resolveEmbedding, runPluginMigrations, sanitizeFTS, searchMMR, vecToBuffer, withLock, writePid };