ko-qmd 2.8.3-ko.10

package/dist/store.d.ts

@@ -0,0 +1,1267 @@
+/**
+ * QMD Store - Core data access and retrieval functions
+ *
+ * This module provides all database operations, search functions, and document
+ * retrieval for QMD. It returns raw data structures that can be formatted by
+ * CLI or MCP consumers.
+ *
+ * Usage:
+ *   const store = createStore("/path/to/db.sqlite");
+ *   // or use default path:
+ *   const store = createStore();
+ */
+import type { Database } from "./db.js";
+import { type DocumentFilter } from "./filters.js";
+import { INTENT_WEIGHT_CHUNK } from "./rerank-input.js";
+import { LlamaCpp, formatQueryForEmbedding, formatDocForEmbedding, type ILLMSession } from "./llm.js";
+import type { NamedCollection, Collection, CollectionConfig } from "./collections.js";
+import { type DocumentMetadata } from "./metadata.js";
+import { type MetadataFilter } from "./metadata-filter.js";
+export declare const DEFAULT_EMBED_MODEL = "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf";
+export declare const DEFAULT_RERANK_MODEL = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
+export declare const DEFAULT_QUERY_MODEL = "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf";
+export declare const DEFAULT_GLOB = "**/*.md";
+/**
+ * Split a collection glob mask into fast-glob patterns.
+ *
+ * `--mask "a.md,*.txt"` is a comma-separated union (issue #557), but
+ * fast-glob treats a comma outside `{...}` as a literal character, so
+ * the joined string matches nothing. Brace form `{a.md,*.txt}` is
+ * already valid glob syntax and is left intact.
+ *
+ * Commas inside `{...}` or `[...]` are not separators. Empty segments
+ * after the split are dropped.
+ */
+export declare function splitGlobMask(mask: string): string[];
+export declare const DEFAULT_MULTI_GET_MAX_BYTES: number;
+export declare const DEFAULT_EMBED_MAX_DOCS_PER_BATCH = 64;
+export declare const DEFAULT_EMBED_MAX_BATCH_BYTES: number;
+export declare const DEFAULT_EMBED_MAX_DURATION_MS: number;
+export declare const CHUNK_SIZE_TOKENS = 900;
+export declare const CHUNK_OVERLAP_TOKENS: number;
+export declare const CHUNK_SIZE_CHARS: number;
+export declare const CHUNK_OVERLAP_CHARS: number;
+export declare const CHUNK_WINDOW_TOKENS = 200;
+export declare const CHUNK_WINDOW_CHARS: number;
+export declare function getEmbeddingFingerprint(model?: string): string;
+/**
+ * A potential break point in the document with a base score indicating quality.
+ */
+export interface BreakPoint {
+    pos: number;
+    score: number;
+    type: string;
+}
+/**
+ * A region where a code fence exists (between ``` markers).
+ * We should never split inside a code fence.
+ */
+export interface CodeFenceRegion {
+    start: number;
+    end: number;
+}
+/**
+ * Patterns for detecting break points in markdown documents.
+ * Higher scores indicate better places to split.
+ * Scores are spread wide so headings decisively beat lower-quality breaks.
+ * Order matters for scoring - more specific patterns first.
+ */
+export declare const BREAK_PATTERNS: [RegExp, number, string][];
+/**
+ * Scan text for all potential break points.
+ * Returns sorted array of break points with higher-scoring patterns taking precedence
+ * when multiple patterns match the same position.
+ */
+export declare function scanBreakPoints(text: string): BreakPoint[];
+/**
+ * Find all code fence regions in the text.
+ * Code fences are delimited by ``` and we should never split inside them.
+ */
+export declare function findCodeFences(text: string): CodeFenceRegion[];
+/**
+ * Check if a position is inside a code fence region.
+ */
+export declare function isInsideCodeFence(pos: number, fences: CodeFenceRegion[]): boolean;
+/**
+ * Find the best cut position using scored break points with distance decay.
+ *
+ * Uses squared distance for gentler early decay - headings far back still win
+ * over low-quality breaks near the target.
+ *
+ * @param breakPoints - Pre-scanned break points from scanBreakPoints()
+ * @param targetCharPos - The ideal cut position (e.g., maxChars boundary)
+ * @param windowChars - How far back to search for break points (default ~200 tokens)
+ * @param decayFactor - How much to penalize distance (0.7 = 30% score at window edge)
+ * @param codeFences - Code fence regions to avoid splitting inside
+ * @returns The best position to cut at
+ */
+export declare function findBestCutoff(breakPoints: BreakPoint[], targetCharPos: number, windowChars?: number, decayFactor?: number, codeFences?: CodeFenceRegion[]): number;
+export type ChunkStrategy = "auto" | "regex";
+/**
+ * Merge two sets of break points (e.g. regex + AST), keeping the highest
+ * score at each position. Result is sorted by position.
+ */
+export declare function mergeBreakPoints(a: BreakPoint[], b: BreakPoint[]): BreakPoint[];
+/**
+ * Core chunk algorithm that operates on precomputed break points and code fences.
+ * This is the shared implementation used by both regex-only and AST-aware chunking.
+ */
+export declare function chunkDocumentWithBreakPoints(content: string, breakPoints: BreakPoint[], codeFences: CodeFenceRegion[], maxChars?: number, overlapChars?: number, windowChars?: number): {
+    text: string;
+    pos: number;
+}[];
+export declare const STRONG_SIGNAL_MIN_SCORE = 0.85;
+export declare const STRONG_SIGNAL_MIN_GAP = 0.15;
+export declare const RERANK_CANDIDATE_LIMIT = 40;
+/**
+ * A typed query expansion result. Decoupled from llm.ts internal Queryable —
+ * same shape, but store.ts owns its own public API type.
+ *
+ * - lex: keyword variant → routes to FTS only
+ * - vec: semantic variant → routes to vector only
+ * - hyde: hypothetical document → routes to vector only
+ */
+export type ExpandedQuery = {
+    type: 'lex' | 'vec' | 'hyde';
+    query: string;
+    /** Optional line number for error reporting (CLI parser) */
+    line?: number;
+};
+export declare function homedir(): string;
+/**
+ * Check if a path is absolute.
+ * Supports:
+ * - Unix paths: /path/to/file
+ * - Windows native: C:\path or C:/path
+ * - Git Bash: /c/path or /C/path (C-Z drives, excluding A/B floppy drives)
+ *
+ * Note: /c without trailing slash is treated as Unix path (directory named "c"),
+ * while /c/ or /c/path are treated as Git Bash paths (C: drive).
+ */
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * Normalize path separators to forward slashes.
+ * Converts Windows backslashes to forward slashes.
+ */
+export declare function normalizePathSeparators(path: string): string;
+/**
+ * Get the relative path from a prefix.
+ * Returns null if path is not under prefix.
+ * Returns empty string if path equals prefix.
+ */
+export declare function getRelativePathFromPrefix(path: string, prefix: string): string | null;
+export declare function resolve(...paths: string[]): string;
+export declare function enableProductionMode(): void;
+/** Reset production mode flag — only for testing. */
+export declare function _resetProductionModeForTesting(): void;
+export declare function getDefaultDbPath(indexName?: string): string;
+export declare function getPwd(): string;
+export declare function getRealPath(path: string): string;
+/**
+ * True if `target` is `dir` or a descendant, after resolving symlinks.
+ * Used to keep indexing and qmd:// filesystem resolution inside a collection.
+ */
+export declare function isPathInsideDir(dir: string, target: string): boolean;
+export type VirtualPath = {
+    collectionName: string;
+    path: string;
+    indexName?: string;
+};
+/**
+ * Normalize explicit virtual path formats to standard qmd:// format.
+ * Only handles paths that are already explicitly virtual:
+ * - qmd://collection/path.md (already normalized)
+ * - qmd:////collection/path.md (extra slashes - normalize)
+ * - //collection/path.md (missing qmd: prefix - add it)
+ *
+ * Does NOT handle:
+ * - collection/path.md (bare paths - could be filesystem relative)
+ * - :linenum suffix (should be parsed separately before calling this)
+ */
+export declare function normalizeVirtualPath(input: string): string;
+/**
+ * Parse a virtual path like "qmd://collection-name/path/to/file.md"
+ * into its components.
+ * Also supports collection root: "qmd://collection-name/" or "qmd://collection-name"
+ */
+export declare function parseVirtualPath(virtualPath: string): VirtualPath | null;
+/**
+ * Build a virtual path from collection name and relative path.
+ */
+export declare function buildVirtualPath(collectionName: string, path: string, indexName?: string): string;
+/**
+ * Check if a path is explicitly a virtual path.
+ * Only recognizes explicit virtual path formats:
+ * - qmd://collection/path.md
+ * - //collection/path.md
+ *
+ * Does NOT consider bare collection/path.md as virtual - that should be
+ * handled separately by checking if the first component is a collection name.
+ */
+export declare function isVirtualPath(path: string): boolean;
+/**
+ * Resolve a virtual path to absolute filesystem path.
+ */
+export declare function resolveVirtualPath(db: Database, virtualPath: string): string | null;
+/**
+ * Convert an absolute filesystem path to a virtual path.
+ * Returns null if the file is not in any indexed collection.
+ */
+export declare function toVirtualPath(db: Database, absolutePath: string): string | null;
+export declare function verifySqliteVecLoaded(db: Database): void;
+/**
+ * FTS5's unicode61 tokenizer does not segment CJK text into searchable words.
+ * Normalize CJK runs by spacing every character so exact CJK queries can be
+ * translated into phrase queries while Latin text keeps the default tokenizer.
+ */
+export declare function normalizeCjkForFTS(text: string): string;
+export declare function getStoreCollections(db: Database): NamedCollection[];
+export declare function getStoreCollection(db: Database, name: string): NamedCollection | null;
+export declare function getStoreGlobalContext(db: Database): string | undefined;
+export declare function getStoreContexts(db: Database): Array<{
+    collection: string;
+    path: string;
+    context: string;
+}>;
+export declare function upsertStoreCollection(db: Database, name: string, collection: Omit<Collection, 'pattern'> & {
+    pattern?: string;
+}): void;
+export declare function deleteStoreCollection(db: Database, name: string): boolean;
+export declare function renameStoreCollection(db: Database, oldName: string, newName: string): boolean;
+export declare function updateStoreContext(db: Database, collectionName: string, path: string, text: string): boolean;
+export declare function removeStoreContext(db: Database, collectionName: string, path: string): boolean;
+export declare function setStoreGlobalContext(db: Database, value: string | undefined): void;
+/**
+ * Sync external config (YAML/inline) into SQLite store_collections.
+ * External config always wins. Skips sync if config hash hasn't changed.
+ */
+export declare function syncConfigToDb(db: Database, config: CollectionConfig): void;
+export declare function isSqliteVecAvailable(): boolean;
+export type Store = {
+    db: Database;
+    dbPath: string;
+    /** Optional LlamaCpp instance for this store (overrides the global singleton) */
+    llm?: LlamaCpp;
+    close: () => void;
+    ensureVecTable: (dimensions: number) => void;
+    getHashesNeedingEmbedding: (model?: string) => number;
+    getIndexHealth: (model?: string) => IndexHealthInfo;
+    getStatus: (model?: string) => IndexStatus;
+    getCacheKey: typeof getCacheKey;
+    getCachedResult: (cacheKey: string) => string | null;
+    setCachedResult: (cacheKey: string, result: string) => void;
+    clearCache: () => void;
+    deleteLLMCache: () => number;
+    deleteInactiveDocuments: () => number;
+    cleanupOrphanedContent: () => number;
+    cleanupOrphanedVectors: () => number;
+    vacuumDatabase: () => void;
+    getContextForFile: (filepath: string) => string | null;
+    getContextForPath: (collectionName: string, path: string) => string | null;
+    getCollectionByName: (name: string) => {
+        name: string;
+        pwd: string;
+        glob_pattern: string;
+    } | null;
+    getCollectionsWithoutContext: () => {
+        name: string;
+        pwd: string;
+        doc_count: number;
+    }[];
+    getTopLevelPathsWithoutContext: (collectionName: string) => string[];
+    parseVirtualPath: typeof parseVirtualPath;
+    buildVirtualPath: typeof buildVirtualPath;
+    isVirtualPath: typeof isVirtualPath;
+    resolveVirtualPath: (virtualPath: string) => string | null;
+    toVirtualPath: (absolutePath: string) => string | null;
+    searchFTS: (query: string, limit?: number, collectionName?: string | readonly string[], filter?: MetadataFilter, scope?: DocumentFilter, onScanCapped?: () => void) => SearchResult[];
+    searchVec: (query: string, model: string, limit?: number, collectionName?: string | readonly string[], session?: ILLMSession, precomputedEmbedding?: number[], filter?: MetadataFilter, scope?: DocumentFilter) => Promise<SearchResult[]>;
+    /** `onModelReady` fires once the generation model is loaded (not at all on a cache hit). */
+    expandQuery: (query: string, model?: string, options?: {
+        onModelReady?: () => void;
+    }) => Promise<ExpandedQuery[]>;
+    /** Drop the cached expansion for a query so the next call regenerates. */
+    invalidateExpansionCache: (query: string) => void;
+    rerank: (query: string, documents: {
+        file: string;
+        text: string;
+    }[], model?: string, intent?: string, options?: StoreRerankOptions) => Promise<{
+        file: string;
+        score: number;
+    }[]>;
+    findDocument: (filename: string, options?: {
+        includeBody?: boolean;
+    }) => DocumentResult | DocumentLookupError;
+    getDocumentBody: (doc: DocumentResult | {
+        filepath: string;
+    }, fromLine?: number, maxLines?: number) => string | null;
+    findDocuments: (pattern: string, options?: {
+        includeBody?: boolean;
+        maxBytes?: number;
+    }) => {
+        docs: MultiGetResult[];
+        errors: string[];
+    };
+    findSimilarFiles: (query: string, maxDistance?: number, limit?: number) => string[];
+    matchFilesByGlob: (pattern: string) => {
+        filepath: string;
+        displayPath: string;
+        bodyLength: number;
+    }[];
+    findDocumentByDocid: (docid: string) => {
+        filepath: string;
+        hash: string;
+    } | null;
+    insertContent: (hash: string, content: string, createdAt: string) => void;
+    insertDocument: (collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string) => number;
+    findActiveDocument: (collectionName: string, path: string) => {
+        id: number;
+        hash: string;
+        title: string;
+    } | null;
+    findOrMigrateLegacyDocument: (collectionName: string, path: string) => {
+        id: number;
+        hash: string;
+        title: string;
+    } | null;
+    updateDocumentTitle: (documentId: number, title: string, modifiedAt: string) => void;
+    updateDocument: (documentId: number, title: string, hash: string, modifiedAt: string) => void;
+    deactivateDocument: (collectionName: string, path: string) => void;
+    getActiveDocumentPaths: (collectionName: string) => string[];
+    getHashesForEmbedding: () => {
+        hash: string;
+        body: string;
+        path: string;
+    }[];
+    clearAllEmbeddings: () => void;
+    insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, totalChunks?: number, fingerprint?: string) => void;
+};
+export type ReindexProgress = {
+    file: string;
+    current: number;
+    total: number;
+};
+export type ReindexSkippedFile = {
+    file: string;
+    code: string;
+};
+export type ReindexResult = {
+    indexed: number;
+    updated: number;
+    unchanged: number;
+    removed: number;
+    orphanedCleaned: number;
+    skipped: number;
+    skippedFiles: ReindexSkippedFile[];
+    /** Documents whose qmd.metadata frontmatter failed extraction this pass. */
+    metadataErrors: number;
+};
+/**
+ * The files a collection is made of, relative to its root: the glob, minus dependency and
+ * build directories, minus the collection's own ignore patterns, minus anything hidden.
+ * One definition, because the daemon's refresh has to see exactly the set that
+ * reindexCollection indexes or it would decide staleness about different files.
+ */
+export declare function listCollectionFiles(collectionPath: string, globPattern: string, ignorePatterns?: string[]): Promise<string[]>;
+/**
+ * Re-index a single collection by scanning the filesystem and updating the database.
+ * Pure function — no console output, no db lifecycle management.
+ */
+export declare function reindexCollection(store: Store, collectionPath: string, globPattern: string, collectionName: string, options?: {
+    ignorePatterns?: string[];
+    onProgress?: (info: ReindexProgress) => void;
+}): Promise<ReindexResult>;
+export type EmbedFailure = {
+    path: string;
+    hash: string;
+    seq: number;
+    attempts: number;
+    reason: string;
+};
+export type EmbedProgress = {
+    chunksEmbedded: number;
+    totalChunks: number;
+    bytesProcessed: number;
+    totalBytes: number;
+    /** Active failed chunks still awaiting a successful retry. */
+    errors: number;
+    failures?: EmbedFailure[];
+};
+export type EmbedResult = {
+    docsProcessed: number;
+    chunksEmbedded: number;
+    /** Active failed chunks that did not recover after retries. */
+    errors: number;
+    failures?: EmbedFailure[];
+    durationMs: number;
+};
+export type EmbedOptions = {
+    force?: boolean;
+    model?: string;
+    /**
+     * Restrict embedding to documents in a single collection.
+     * When omitted, all pending documents across every collection are embedded.
+     */
+    collection?: string;
+    maxDocsPerBatch?: number;
+    maxBatchBytes?: number;
+    chunkStrategy?: ChunkStrategy;
+    /**
+     * Max wall-clock duration for the whole embed session, in milliseconds. When the
+     * cap is reached, remaining document batches are skipped (re-run `qmd embed` to
+     * continue). A value <= 0 disables the cap. Defaults to
+     * {@link DEFAULT_EMBED_MAX_DURATION_MS} (30 minutes).
+     */
+    maxDurationMs?: number;
+    onProgress?: (info: EmbedProgress) => void;
+};
+/**
+ * Generate vector embeddings for documents that need them.
+ * Pure function — no console output, no db lifecycle management.
+ * Uses the store's LlamaCpp instance if set, otherwise the global singleton.
+ */
+export declare function generateEmbeddings(store: Store, options?: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Create a new store instance with the given database path.
+ * If no path is provided, uses the default path (~/.cache/qmd/index.sqlite).
+ *
+ * @param dbPath - Path to the SQLite database file
+ * @returns Store instance with all methods bound to the database
+ */
+export declare function createStore(dbPath?: string): Store;
+/**
+ * Unified document result type with all metadata.
+ * Body is optional - use getDocumentBody() to load it separately if needed.
+ */
+export type DocumentResult = {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    context: string | null;
+    hash: string;
+    docid: string;
+    collectionName: string;
+    modifiedAt: string;
+    bodyLength: number;
+    body?: string;
+};
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export declare function getDocid(hash: string): string;
+export declare function handelize(path: string): string;
+/**
+ * Search result extends DocumentResult with score and source info
+ */
+export type SearchResult = DocumentResult & {
+    metadata: DocumentMetadata;
+    score: number;
+    source: "fts" | "vec";
+    matchMode?: "all" | "any";
+    chunkPos?: number;
+};
+/**
+ * Ranked result for RRF fusion (simplified, used internally)
+ */
+export type RankedResult = {
+    file: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    score: number;
+};
+export type RRFContributionTrace = {
+    listIndex: number;
+    source: "fts" | "vec";
+    queryType: "original" | "lex" | "vec" | "hyde";
+    query: string;
+    rank: number;
+    weight: number;
+    multiplier?: number;
+    backendScore: number;
+    rrfContribution: number;
+};
+export type RRFScoreTrace = {
+    contributions: RRFContributionTrace[];
+    baseScore: number;
+    topRank: number;
+    topRankBonus: number;
+    totalScore: number;
+};
+export type HybridQueryExplain = {
+    ftsScores: number[];
+    vectorScores: number[];
+    rrf: {
+        rank: number;
+        positionScore: number;
+        weight: number;
+        baseScore: number;
+        topRankBonus: number;
+        totalScore: number;
+        contributions: RRFContributionTrace[];
+    };
+    rerankScore: number;
+    blendedScore: number;
+};
+/**
+ * Error result when document is not found
+ */
+export type DocumentNotFound = {
+    error: "not_found";
+    query: string;
+    similarFiles: string[];
+};
+export type DocumentExcludedByIgnore = {
+    error: "excluded_by_ignore";
+    query: string;
+    collection: string;
+    path: string;
+    rule: string;
+};
+export type DocumentLookupError = DocumentNotFound | DocumentExcludedByIgnore;
+/**
+ * Result from multi-get operations
+ */
+export type MultiGetResult = {
+    doc: DocumentResult;
+    skipped: false;
+} | {
+    doc: Pick<DocumentResult, "filepath" | "displayPath">;
+    skipped: true;
+    skipReason: string;
+};
+export type CollectionInfo = {
+    name: string;
+    path: string | null;
+    pattern: string | null;
+    documents: number;
+    lastUpdated: string;
+};
+export type IndexStatus = {
+    totalDocuments: number;
+    needsEmbedding: number;
+    hasVectorIndex: boolean;
+    /** Active documents without current, error-free metadata extraction. */
+    pendingMetadata: number;
+    collections: CollectionInfo[];
+};
+export declare function getHashesNeedingEmbedding(db: Database, collection?: string, model?: string): number;
+export type IndexHealthInfo = {
+    needsEmbedding: number;
+    totalDocs: number;
+    daysStale: number | null;
+};
+export type LegacyFingerprintAdoptionResult = {
+    checked: boolean;
+    adopted: number;
+    reason: string;
+};
+export declare function maybeAdoptLegacyEmbeddingFingerprint(store: Store, model?: string): Promise<LegacyFingerprintAdoptionResult>;
+export declare function getIndexHealth(db: Database, model?: string): IndexHealthInfo;
+export type CacheKeyBody = {
+    query?: string;
+    model?: string;
+    chunk?: string;
+    file?: string;
+};
+export declare function getCacheKey(url: string, body: CacheKeyBody): string;
+export declare function getCachedResult(db: Database, cacheKey: string): string | null;
+export declare function setCachedResult(db: Database, cacheKey: string, result: string): void;
+export declare function clearCache(db: Database): void;
+/**
+ * Delete cached LLM API responses.
+ * Returns the number of cached responses deleted.
+ */
+export declare function deleteLLMCache(db: Database): number;
+/**
+ * Remove inactive document records (active = 0).
+ * Returns the number of inactive documents deleted.
+ */
+export declare function deleteInactiveDocuments(db: Database): number;
+/**
+ * Remove orphaned content hashes that are not referenced by any document.
+ * Inactive documents are soft-deleted tombstones, so their content rows must
+ * remain referenced until deleteInactiveDocuments() hard-deletes them.
+ * Returns the number of orphaned content hashes deleted.
+ */
+export declare function cleanupOrphanedContent(db: Database): number;
+/**
+ * Count content hashes that would be unreferenced after inactive documents
+ * are hard-deleted. Shared hashes still used by an active document are kept.
+ */
+export declare function countOrphanedContent(db: Database): number;
+/**
+ * Count embedding chunks whose hash is not referenced by any active document.
+ * Reads `content_vectors` only, so this works even when sqlite-vec is unavailable (#768).
+ */
+export declare function countOrphanedVectors(db: Database): number;
+/**
+ * Remove orphaned vector embeddings that are not referenced by any active document.
+ * Returns the number of orphaned embedding chunks deleted.
+ */
+export declare function cleanupOrphanedVectors(db: Database): number;
+/**
+ * Run VACUUM to reclaim unused space in the database.
+ * This operation rebuilds the database file to eliminate fragmentation.
+ */
+export declare function vacuumDatabase(db: Database): void;
+/**
+ * Merge FTS5 b-trees so deleted rows (deactivated / hard-deleted documents)
+ * leave `documents_fts_data`. VACUUM alone does not compact FTS5 (#550).
+ */
+export declare function optimizeDocumentsFts(db: Database): void;
+export type CleanupStats = {
+    cacheCount: number;
+    orphanedVectors: number;
+    inactiveDocs: number;
+    orphanedContent: number;
+};
+/** Counts what `runCleanup` would remove, including content only held by inactive docs. */
+export declare function previewCleanup(db: Database): CleanupStats;
+/**
+ * Full `qmd cleanup` sequence: drop cache, orphaned vectors, inactive document
+ * rows, then the content those rows were pinning, compact FTS5, vacuum.
+ */
+export declare function runCleanup(db: Database): CleanupStats;
+export declare function hashContent(content: string): Promise<string>;
+export declare function extractTitle(content: string, filename: string): string;
+/**
+ * Insert content into the content table (content-addressable storage).
+ * Uses INSERT OR IGNORE so duplicate hashes are skipped.
+ */
+export declare function insertContent(db: Database, hash: string, content: string, createdAt: string): void;
+/**
+ * Insert a new document into the documents table.
+ * Returns the document's id so callers can attach document-scoped state.
+ */
+export declare function insertDocument(db: Database, collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string): number;
+/**
+ * Find an active document by collection name and path.
+ */
+export declare function findActiveDocument(db: Database, collectionName: string, path: string): {
+    id: number;
+    hash: string;
+    title: string;
+} | null;
+/**
+ * Find an active document, falling back to a legacy handalized-path match.
+ * If found under the pre-2.6 slug, renames it in-place and rebuilds the
+ * FTS entry. Embeddings are keyed by content hash, so the rename is
+ * safe — no re-embedding required.
+ *
+ * `livePaths`, when given, is the set of literal paths of every file in the
+ * current scan of this collection. A legacy row whose path is in that set
+ * belongs to a *different* file that still exists on disk, so it must never be
+ * adopted — renaming it would evict that file from the index (#717).
+ *
+ * @internal Used by reindexCollection and indexFiles during qmd update.
+ * Returns null if the document does not exist under either path.
+ */
+export declare function findOrMigrateLegacyDocument(db: Database, collectionName: string, path: string, livePaths?: ReadonlySet<string>): {
+    id: number;
+    hash: string;
+    title: string;
+} | null;
+/**
+ * Update the title and modified_at timestamp for a document.
+ *
+ * Title-only fast path: callers invoke this only when the content hash is
+ * unchanged, so the body needs no re-tokenization. The documents_au sync
+ * trigger is scoped to (collection, path, hash, active) and does not fire
+ * for this write, so a single FTS title UPDATE preserves the existing
+ * normalized filepath/body — skipping both the body re-normalization and
+ * the redundant raw DELETE+INSERT rewrite (~5ms per 105KB document).
+ * When no FTS row exists, fall back to a full rebuild so the title is still
+ * indexed (and any orphan row is cleaned up, as before).
+ */
+export declare function updateDocumentTitle(db: Database, documentId: number, title: string, modifiedAt: string): void;
+/**
+ * Update an existing document's hash, title, and modified_at timestamp.
+ * Used when content changes but the file path stays the same.
+ */
+export declare function updateDocument(db: Database, documentId: number, title: string, hash: string, modifiedAt: string): void;
+/**
+ * Deactivate a document (mark as inactive but don't delete).
+ */
+export declare function deactivateDocument(db: Database, collectionName: string, path: string): void;
+/**
+ * Get all active document paths for a collection.
+ */
+export declare function getActiveDocumentPaths(db: Database, collectionName: string): string[];
+export { formatQueryForEmbedding, formatDocForEmbedding };
+/**
+ * Chunk a document using regex-only break point detection.
+ * This is the sync, backward-compatible API used by tests and legacy callers.
+ */
+export declare function chunkDocument(content: string, maxChars?: number, overlapChars?: number, windowChars?: number): {
+    text: string;
+    pos: number;
+}[];
+/**
+ * Async AST-aware chunking. Detects language from filepath, computes AST
+ * break points for supported code files, merges with regex break points,
+ * and delegates to the shared chunk algorithm.
+ *
+ * Falls back to regex-only when strategy is "regex", filepath is absent,
+ * or language is unsupported.
+ */
+export declare function chunkDocumentAsync(content: string, maxChars?: number, overlapChars?: number, windowChars?: number, filepath?: string, chunkStrategy?: ChunkStrategy): Promise<{
+    text: string;
+    pos: number;
+}[]>;
+export declare function chunkDocumentByTokens(content: string, maxTokens?: number, overlapTokens?: number, windowTokens?: number, filepath?: string, chunkStrategy?: ChunkStrategy, signal?: AbortSignal): Promise<{
+    text: string;
+    pos: number;
+    tokens: number;
+}[]>;
+/**
+ * Normalize a docid input by stripping surrounding quotes and leading #.
+ * Handles: "#abc123", 'abc123', "abc123", #abc123, abc123
+ * Returns the bare hex string.
+ */
+export declare function normalizeDocid(docid: string): string;
+/**
+ * Check if a string looks like a docid reference.
+ * Accepts: #abc123, abc123, "#abc123", "abc123", '#abc123', 'abc123'
+ * Returns true if the normalized form is a valid hex string of 6+ chars.
+ */
+export declare function isDocid(input: string): boolean;
+/**
+ * Find a document by its short docid (first 6 characters of hash).
+ * Returns the document's virtual path if found, null otherwise.
+ * If multiple documents match the same short hash (collision), returns the first one.
+ *
+ * Accepts lenient input: #abc123, abc123, "#abc123", "abc123"
+ */
+export declare function findDocumentByDocid(db: Database, docid: string): {
+    filepath: string;
+    hash: string;
+} | null;
+export declare function findSimilarFiles(db: Database, query: string, maxDistance?: number, limit?: number): string[];
+export declare function matchFilesByGlob(db: Database, pattern: string): {
+    filepath: string;
+    displayPath: string;
+    bodyLength: number;
+}[];
+/**
+ * Get context for a file path using hierarchical inheritance.
+ * Contexts are collection-scoped and inherit from parent directories.
+ * For example, context at "/talks" applies to "/talks/2024/keynote.md".
+ *
+ * @param db Database instance (unused - kept for compatibility)
+ * @param collectionName Collection name
+ * @param path Relative path within the collection
+ * @returns Context string or null if no context is defined
+ */
+export declare function getContextForPath(db: Database, collectionName: string, path: string): string | null;
+/**
+ * Get context for a file path (virtual or filesystem).
+ * Resolves the collection and relative path from the DB store_collections table.
+ */
+export declare function getContextForFile(db: Database, filepath: string): string | null;
+/**
+ * Batch version of {@link getContextForFile}: one collections fetch, one
+ * global-context fetch and one document-existence query for the whole batch
+ * instead of three per file. Context assembly per file is identical.
+ */
+export declare function getContextsForFiles(db: Database, filepaths: string[]): Map<string, string | null>;
+/**
+ * Get collection by name from DB store_collections table.
+ */
+export declare function getCollectionByName(db: Database, name: string): {
+    name: string;
+    pwd: string;
+    glob_pattern: string;
+} | null;
+/**
+ * List all collections with document counts from database.
+ * Merges store_collections config with database statistics.
+ */
+export declare function listCollections(db: Database): {
+    name: string;
+    pwd: string;
+    glob_pattern: string;
+    doc_count: number;
+    active_count: number;
+    last_modified: string | null;
+    includeByDefault: boolean;
+}[];
+/**
+ * Remove a collection and clean up its documents.
+ * Uses collections.ts to remove from YAML config and cleans up database.
+ */
+export declare function removeCollection(db: Database, collectionName: string): {
+    deletedDocs: number;
+    cleanedHashes: number;
+};
+/**
+ * Rename a collection.
+ * Updates both YAML config and database documents table.
+ */
+export declare function renameCollection(db: Database, oldName: string, newName: string): void;
+/**
+ * Insert or update a context for a specific collection and path prefix.
+ *
+ * `store_collections` is keyed by name (`TEXT PRIMARY KEY`), not an integer id.
+ * #754 retargeted this query from the dropped `collections` table but left
+ * `WHERE id = ?`, which throws `no such column: id`.
+ */
+export declare function insertContext(db: Database, collectionName: string, pathPrefix: string, context: string): void;
+/**
+ * Check which collections don't have any context defined.
+ * Returns collections that have no context entries at all (not even root context).
+ */
+export declare function getCollectionsWithoutContext(db: Database): {
+    name: string;
+    pwd: string;
+    doc_count: number;
+}[];
+/**
+ * Get top-level directories in a collection that don't have context.
+ * Useful for suggesting where context might be needed.
+ */
+export declare function getTopLevelPathsWithoutContext(db: Database, collectionName: string): string[];
+export declare function sanitizeFTS5Term(term: string): string;
+/**
+ * Validate that a vec/hyde query doesn't use lex-only syntax.
+ * Returns error message if invalid, null if valid.
+ */
+export declare function validateSemanticQuery(query: string): string | null;
+export declare function validateLexQuery(query: string): string | null;
+/** One collection, several (OR), or all (undefined). */
+export type CollectionScope = string | readonly string[] | undefined;
+/**
+ * Candidate ceiling for a filtered FTS scan. High enough that a real query's whole match set
+ * gets through — which is what stops a narrow filter from starving — and low enough that a
+ * query matching most of a large index still terminates.
+ *
+ * A caller asking for more than this (today: `--all` at 100k) with a filter/scope in play
+ * gets at most the cap's worth of candidates, and the excess is dropped before narrowing —
+ * silently, unless the caller passes `onScanCapped` to `searchFTS`. Never raise this to
+ * satisfy `--all`; it is a perf guard, not a result-size knob.
+ */
+export declare const FILTERED_FTS_SCAN_MAX = 50000;
+/**
+ * How many active documents the filter leaves standing, and how many there were.
+ *
+ * An empty result list cannot tell a user whether nothing matched their words or whether
+ * their filter removed the corpus first. Callers ask this only when they got nothing back,
+ * so the scan costs nothing on the path that found something.
+ */
+export declare function countFilteredDocuments(db: Database, filter: DocumentFilter, collectionName?: string | readonly string[]): {
+    kept: number;
+    total: number;
+};
+export declare function searchFTS(db: Database, query: string, limit?: number, collectionName?: string | readonly string[], filter?: MetadataFilter, scope?: DocumentFilter, onScanCapped?: () => void): SearchResult[];
+export declare function searchVec(db: Database, query: string, model: string, limit?: number, collectionName?: string | readonly string[], session?: ILLMSession, precomputedEmbedding?: number[], llm?: LlamaCpp, filter?: MetadataFilter, scope?: DocumentFilter): Promise<SearchResult[]>;
+/**
+ * Get all unique content hashes that need embeddings (from active documents).
+ * Returns hash, document body, and a sample path for display purposes.
+ */
+export declare function getHashesForEmbedding(db: Database, model?: string): {
+    hash: string;
+    body: string;
+    path: string;
+}[];
+/**
+ * Clear embeddings for the whole index, or just for one collection.
+ *
+ * When `collection` is omitted the entire content_vectors table is emptied and
+ * the vectors_vec virtual table is dropped (it is recreated with the right
+ * dimensions on the next embed run).
+ *
+ * When `collection` is provided, only vectors whose hash is referenced
+ * exclusively by active documents in that collection are removed. Hashes
+ * shared with active documents in other collections are left in place so
+ * vector search keeps working there (content_vectors is keyed globally by
+ * content hash; identical document bodies across collections share a row).
+ * vectors_vec is preserved so other collections keep working unless the scoped
+ * clear empties content_vectors entirely, in which case it is dropped so the
+ * next embed can recreate the table with the current dimensions.
+ */
+export declare function clearAllEmbeddings(db: Database, collection?: string): void;
+/**
+ * Insert a single embedding into both content_vectors and vectors_vec tables.
+ * The hash_seq key is formatted as "hash_seq" for the vectors_vec table.
+ *
+ * The content_vectors INSERT and the vectors_vec DELETE + INSERT run inside
+ * one IMMEDIATE transaction, so a crash or error between them can never leave
+ * a phantom-complete row (content_vectors claiming a chunk whose vector is
+ * missing — pending checks read content_vectors only and would skip the hash
+ * forever). Either both tables show the chunk or neither does; a killed batch
+ * leaves a partial hash that the next embed run re-selects and converges.
+ *
+ * IMMEDIATE (not deferred): the txn writes after reading nothing, but the
+ * reserved lock must be taken up front — upgrading a deferred read snapshot
+ * under a concurrent WAL writer fails with SQLITE_BUSY_SNAPSHOT instead of
+ * honoring busy_timeout. Readers still proceed under WAL; writers queue via
+ * busy_timeout. Never EXCLUSIVE. The migration wrapper stays outside: a
+ * column repair (ALTER TABLE) must not run inside the chunk txn — on a
+ * column-miss the txn body throws, rolls back, the repair runs, and the retry
+ * re-enters a fresh txn.
+ *
+ * vectors_vec uses DELETE + INSERT instead of INSERT OR REPLACE because sqlite-vec's
+ * vec0 virtual tables silently ignore the OR REPLACE conflict clause.
+ */
+export declare function insertEmbedding(db: Database, hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, totalChunks?: number, fingerprint?: string): void;
+export declare function expandQuery(query: string, model: string | undefined, db: Database, llmOverride?: LlamaCpp, options?: {
+    onModelReady?: () => void;
+}): Promise<ExpandedQuery[]>;
+/**
+ * Delete the cached expansion for a query. hybridQuery() calls this when an
+ * expansion's sub-queries all came back empty — left in place, the dud entry
+ * would replay the same misses on every warm repeat of the query.
+ */
+export declare function deleteExpansionCacheEntry(db: Database, query: string, model?: string): void;
+/** Per-request rerank options. A 5th positional on Store.rerank keeps existing SDK callers working. */
+export type StoreRerankOptions = {
+    /** Doc token cap for this request; overrides QMD_RERANK_MAX_DOC_TOKENS. */
+    maxDocTokens?: number;
+    /** Called once the rerank model is loaded (not at all when every chunk is cached). */
+    onModelReady?: () => void;
+};
+export declare function rerank(query: string, documents: {
+    file: string;
+    text: string;
+}[], model: string | undefined, db: Database, intent?: string, llmOverride?: LlamaCpp, options?: StoreRerankOptions): Promise<{
+    file: string;
+    score: number;
+}[]>;
+/**
+ * Fraction of the query's units present in the document body, used to weight a
+ * relaxed (any-word) FTS list per document instead of one global constant
+ * (BASELINE.md 2026-10-09 follow-up: a global weight cannot split the mirrored
+ * tie of `hmu-05` vs `sem-08`).
+ *
+ * Units mirror the rerank chunk scorer: one per Hangul run of two or more
+ * syllables (a run of three or more also matches on any shared syllable
+ * bigram, so a particle-suffixed word meets its stem), one per Latin/digit run
+ * longer than two characters. Single syllables and short tokens carry no
+ * signal and are skipped. A query with no units covers everything (1.0) so it
+ * never punishes.
+ */
+export declare function relaxedDocCoverage(query: string, body: string): number;
+/**
+ * Per-document RRF multipliers, aligned with `rankedLists`: a relaxed list
+ * scales each document by `0.5 + 0.5 × coverage`, every other list is untouched
+ * (`undefined` entry = multiplier 1.0). The 0.5 floor keeps a zero-coverage
+ * candidate in the pool instead of erasing it.
+ */
+export declare function rrfDocMultipliers(rankedLists: RankedResult[][], rankedListMeta: RankedListMeta[]): Array<Map<string, number> | undefined>;
+export declare function reciprocalRankFusion(resultLists: RankedResult[][], weights?: number[], k?: number, docMultipliers?: Array<Map<string, number> | undefined>): RankedResult[];
+/**
+ * Build per-document RRF contribution traces for explain/debug output.
+ */
+export declare function buildRrfTrace(resultLists: RankedResult[][], weights?: number[], listMeta?: RankedListMeta[], k?: number, docMultipliers?: Array<Map<string, number> | undefined>): Map<string, RRFScoreTrace>;
+/**
+ * Find a document by filename/path, docid (#hash), or path-boundary suffix.
+ * Returns document metadata without body by default.
+ *
+ * Supports:
+ * - Virtual paths: qmd://collection/path/to/file.md
+ * - Absolute paths: /path/to/file.md
+ * - Relative paths: path/to/file.md
+ * - Short docid: #abc123 (first 6 chars of hash)
+ */
+export declare function findDocument(db: Database, filename: string, options?: {
+    includeBody?: boolean;
+}): DocumentResult | DocumentLookupError;
+/**
+ * Get the body content for a document
+ * Optionally slice by line range
+ */
+export declare function getDocumentBody(db: Database, doc: DocumentResult | {
+    filepath: string;
+}, fromLine?: number, maxLines?: number): string | null;
+/**
+ * Escape a user-supplied string so it is matched literally by SQLite LIKE.
+ * Uses '#' as the ESCAPE character (avoids quote-escaping pitfalls with '\\').
+ */
+export declare function escapeLikePattern(value: string): string;
+export type CommaListMatch = {
+    collection: string;
+    path: string;
+    virtualPath: string;
+    bodyLength: number;
+};
+export type CommaListResolve = {
+    ok: true;
+    match: CommaListMatch;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve one comma-list name for multi-get (shared by CLI and SDK/MCP).
+ *
+ * Match order: docid / qmd:// URI (exact only), then exact collection-prefixed
+ * path, then exact document path, then a path-boundary suffix (`.../name`).
+ * Unanchored LIKE is never used, so a fragment like `NTAX.md` cannot silently
+ * fetch `SYNTAX.md`. Multiple hits at the same tier error with the candidate
+ * list instead of `LIMIT 1` (#759).
+ */
+export declare function resolveCommaListName(db: Database, name: string): CommaListResolve;
+/**
+ * Find multiple documents by glob pattern or comma-separated list
+ * Returns documents without body by default (use getDocumentBody to load)
+ */
+export declare function findDocuments(db: Database, pattern: string, options?: {
+    includeBody?: boolean;
+    maxBytes?: number;
+}): {
+    docs: MultiGetResult[];
+    errors: string[];
+};
+export declare function getStatus(db: Database, model?: string): IndexStatus;
+export type SnippetResult = {
+    line: number;
+    snippet: string;
+    linesBefore: number;
+    linesAfter: number;
+    snippetLines: number;
+};
+/** Weight for intent terms relative to query terms (1.0) in snippet scoring */
+export declare const INTENT_WEIGHT_SNIPPET = 0.3;
+export { INTENT_WEIGHT_CHUNK };
+/**
+ * Extract meaningful terms from an intent string, filtering stop words and punctuation.
+ * Uses Unicode-aware punctuation stripping so domain terms like "API" survive.
+ * Returns lowercase terms suitable for text matching.
+ */
+export declare function extractIntentTerms(intent: string): string[];
+export declare function extractSnippet(body: string, query: string, maxLen?: number, chunkPos?: number, chunkLen?: number, intent?: string): SnippetResult;
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ */
+export declare function addLineNumbers(text: string, startLine?: number): string;
+/**
+ * Optional progress hooks for search orchestration.
+ * CLI wires these to stderr for user feedback; MCP leaves them unset.
+ */
+export interface SearchHooks {
+    /** BM25 probe found strong signal — expansion will be skipped */
+    onStrongSignal?: (topScore: number) => void;
+    /** Query expansion starting */
+    onExpandStart?: () => void;
+    /** Query expansion complete. Empty array = strong signal skip. elapsedMs = time taken. */
+    onExpand?: (original: string, expanded: ExpandedQuery[], elapsedMs: number) => void;
+    /** Embedding starting (vec/hyde queries) */
+    onEmbedStart?: (count: number) => void;
+    /** Embedding complete */
+    onEmbedDone?: (elapsedMs: number) => void;
+    /** Every BM25 lookup of the search finished; elapsedMs is their total */
+    onFtsDone?: (elapsedMs: number) => void;
+    /** Every sqlite-vec lookup of the search finished (embedding excluded); elapsedMs is their total */
+    onVecDone?: (elapsedMs: number) => void;
+    /** Candidates were chunked and each one's best chunk picked (runs with or without rerank) */
+    onChunkDone?: (elapsedMs: number) => void;
+    /**
+     * A stage went without its LLM (expansion: original query only, rerank: RRF order). elapsedMs is
+     * how long it was waited on after its model loaded; undefined when it was skipped outright because
+     * an earlier call of that stage, abandoned at its deadline, is still running.
+     */
+    onDeadline?: (stage: DeadlineStage, elapsedMs?: number) => void;
+    /** The stage's model finished loading (cold start or reload after idle unload); elapsedMs is the wait */
+    onModelLoad?: (stage: DeadlineStage, elapsedMs: number) => void;
+    /** Reranking is about to start */
+    onRerankStart?: (chunkCount: number) => void;
+    /** Reranking finished */
+    onRerankDone?: (elapsedMs: number) => void;
+}
+export interface HybridQueryOptions {
+    collection?: string | readonly string[];
+    filter?: MetadataFilter;
+    limit?: number;
+    minScore?: number;
+    candidateLimit?: number;
+    rerankMaxDocTokens?: number;
+    explain?: boolean;
+    intent?: string;
+    skipRerank?: boolean;
+    rerankDeadlineMs?: number;
+    expandDeadlineMs?: number;
+    chunkStrategy?: ChunkStrategy;
+    scope?: DocumentFilter;
+    hooks?: SearchHooks;
+}
+export interface HybridQueryResult {
+    file: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    bestChunk: string;
+    bestChunkPos: number;
+    score: number;
+    context: string | null;
+    docid: string;
+    metadata: DocumentMetadata;
+    explain?: HybridQueryExplain;
+}
+export type RankedListMeta = {
+    source: "fts" | "vec";
+    queryType: "original" | "lex" | "vec" | "hyde";
+    query: string;
+    relaxed?: boolean;
+    searchIndex?: number;
+};
+/**
+ * RRF list weights for hybridQuery.
+ *
+ * Original-query retrieval paths are the primary evidence and get 2x weight:
+ * - original FTS
+ * - original vector search
+ *
+ * Expansion-derived lists (lex/vec/hyde) stay at 1x regardless of list order,
+ * so a lex expansion inserted before original vector search cannot steal the
+ * original vector boost.
+ */
+export declare function getHybridRrfWeights(rankedListMeta: RankedListMeta[]): number[];
+export declare function getStructuredRrfWeights(rankedListMeta: RankedListMeta[]): number[];
+/**
+ * Blend a reranker score with a linear retrieval-position tiebreak.
+ *
+ * The position term used to be 1/rrfRank under rank-gated weights (0.75/0.60/0.40).
+ * That score drops 50% between rank 1 and rank 2 — a gap of 0.375 at weight 0.75,
+ * larger than the 0.25 the whole reranker term could ever contribute — so no
+ * reranker score could displace the top retrieval hit, and the reranker was inert
+ * exactly where it decided the answer. A linear decay over the candidate window
+ * separates adjacent ranks by a constant the reranker can overcome.
+ *
+ * Measured 2026-09-18 on one fixed candidate dump per goldset, so every formula was
+ * scored against identical retrieval (scripts/bench-dump-candidates.ts feeding
+ * scripts/bench-blend-sweep.mjs):
+ *
+ *                 alias (n=223)         paraphrase (n=30)
+ *   1/rrfRank     r@1 .713  mrr .808    r@1 .467  mrr .664
+ *   this          r@1 .874  mrr .927    r@1 .867  mrr .903
+ *
+ * On both goldsets the old blend's r@1 equalled retrieval-only r@1 to three
+ * decimals, which is what "the reranker cannot move rank 1" looks like as a number.
+ */
+export declare function blendRerankScore(rrfRank: number, rerankScore: number, candidateLimit: number): number;
+export type DeadlineStage = "expand" | "rerank";
+/**
+ * Bound on the model-load wait inside runWithDeadline: a load that never
+ * reports ready must not hang the query. QMD_LLM_LOAD_TIMEOUT_MS sets it
+ * (positive ms, 0 = wait forever, anything else = the default).
+ */
+export declare const DEFAULT_LOAD_TIMEOUT_MS = 120000;
+/** Load-timeout resolver for runWithDeadline; exported for tests. */
+export declare function resolveLoadTimeoutMs(): number;
+/** Rerank `chunks`, or null when the reranker misses `deadlineMs` (the caller then answers in RRF order). */
+export declare const RERANK_CASCADE_FIRST_BATCH = 8;
+/** Skip the tail past the first batch when the top-2 rerank margin reaches this. */
+export declare const RERANK_CASCADE_MARGIN = 0.08;
+/** First-batch size, overridable for tuning via `QMD_RERANK_FIRST_BATCH`. */
+export declare function rerankCascadeFirstBatch(): number;
+/** Tail-skip margin, overridable for tuning via `QMD_RERANK_MARGIN`. */
+export declare function rerankCascadeMargin(): number;
+/**
+ * QMD_RERANK_CASCADE=0 (or false/off/no) restores single-batch rerank;
+ * anything else (including unset) cascades. Kill switch for measurement and
+ * operations; exported for tests.
+ */
+export declare function isRerankCascadeEnabled(): boolean;
+/**
+ * True when the first cascade batch's top-2 margin is too tight to skip the
+ * tail: a contested top means an unscored document could still win the blend.
+ * A batch of fewer than two holds nothing to contest.
+ */
+export declare function cascadeNeedsSecondBatch(sortedScores: number[], margin?: number): boolean;
+export declare function rerankWithDeadline(store: Store, query: string, chunks: {
+    file: string;
+    text: string;
+}[], intent: string | undefined, options: {
+    rerankMaxDocTokens?: number;
+    rerankDeadlineMs?: number;
+    hooks?: SearchHooks;
+} | undefined): Promise<{
+    file: string;
+    score: number;
+    unscored?: boolean;
+}[] | null>;
+/**
+ * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
+ *
+ * Pipeline:
+ * 1. BM25 probe → skip expansion if strong signal
+ * 2. expandQuery() → typed query variants (lex/vec/hyde)
+ * 3. Type-routed search: original→vector, lex→FTS, vec/hyde→vector
+ * 4. RRF fusion → slice to candidateLimit
+ * 5. chunkDocument() + keyword-best-chunk selection
+ * 6. rerank on chunks (NOT full bodies — O(tokens) trap)
+ * 7. Position-aware score blending (RRF rank × reranker score)
+ * 8. Dedup by file, filter by minScore, slice to limit
+ */
+export declare function hybridQuery(store: Store, rawQuery: string, options?: HybridQueryOptions): Promise<HybridQueryResult[]>;
+export interface VectorSearchOptions {
+    collection?: string | readonly string[];
+    filter?: MetadataFilter;
+    limit?: number;
+    minScore?: number;
+    intent?: string;
+    scope?: DocumentFilter;
+    hooks?: Pick<SearchHooks, 'onExpand'>;
+}
+export interface VectorSearchResult {
+    file: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    score: number;
+    context: string | null;
+    docid: string;
+    metadata: DocumentMetadata;
+}
+/**
+ * Vector-only semantic search with query expansion.
+ *
+ * Pipeline:
+ * 1. expandQuery() → typed variants, filter to vec/hyde only (lex irrelevant here)
+ * 2. searchVec() for original + vec/hyde variants (sequential — node-llama-cpp embed limitation)
+ * 3. Dedup by filepath (keep max score)
+ * 4. Sort by score descending, filter by minScore, slice to limit
+ */
+export declare function vectorSearchQuery(store: Store, query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+/**
+ * A single sub-search in a structured search request.
+ * Matches the format used in QMD training data.
+ */
+export interface StructuredSearchOptions {
+    collections?: string[];
+    filter?: MetadataFilter;
+    limit?: number;
+    minScore?: number;
+    candidateLimit?: number;
+    rerankMaxDocTokens?: number;
+    explain?: boolean;
+    /** Domain intent hint for disambiguation — steers reranking and chunk selection */
+    intent?: string;
+    /** Skip LLM reranking, use only RRF scores */
+    skipRerank?: boolean;
+    rerankDeadlineMs?: number;
+    chunkStrategy?: ChunkStrategy;
+    /** Narrow the corpus by path glob and modified_at before anything is ranked */
+    scope?: DocumentFilter;
+    hooks?: SearchHooks;
+}
+/**
+ * Structured search: execute pre-expanded queries without LLM query expansion.
+ *
+ * Designed for LLM callers (MCP/HTTP) that generate their own query expansions.
+ * Skips the internal expandQuery() step — goes directly to:
+ *
+ * Pipeline:
+ * 1. Route searches: lex→FTS, vec/hyde→vector (batch embed)
+ * 2. RRF fusion across all result lists
+ * 3. Chunk documents + keyword-best-chunk selection
+ * 4. Rerank on chunks
+ * 5. Position-aware score blending
+ * 6. Dedup, filter, slice
+ *
+ * This is the recommended endpoint for capable LLMs — they can generate
+ * better query variations than our small local model, especially for
+ * domain-specific or nuanced queries.
+ */
+export declare function structuredSearch(store: Store, rawSearches: ExpandedQuery[], options?: StructuredSearchOptions): Promise<HybridQueryResult[]>;