@wei840222/qmd 2026.8.28 → 2026.9.25

package/dist/db.js

@@ -1,11 +1,12 @@
 /**
  * db.ts - SQLite database connection and extension management
  *
- * Provides Database export and connection management using better-sqlite3
- * and sqlite-vec.
+ * Provides a synchronous node:sqlite connection with QMD's transaction helper
+ * and sqlite-vec extension loading.
  */
-import BetterSqlite3 from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
 import * as sqliteVec from "sqlite-vec";
+let savepointSequence = 0;
 function isBusyError(err) {
     if (typeof err !== "object" || err === null)
         return false;
@@ -18,12 +19,57 @@ function isBusyError(err) {
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/** Synchronous SQLite connection with QMD-compatible transactions. */
+export class Database extends DatabaseSync {
+    transaction(operation) {
+        const execute = (mode, args) => {
+            if (!this.isTransaction) {
+                this.exec(`BEGIN ${mode}`);
+                try {
+                    const result = operation(...args);
+                    this.exec("COMMIT");
+                    return result;
+                }
+                catch (error) {
+                    try {
+                        this.exec("ROLLBACK");
+                    }
+                    catch { }
+                    throw error;
+                }
+            }
+            const savepoint = `qmd_${++savepointSequence}`;
+            this.exec(`SAVEPOINT ${savepoint}`);
+            try {
+                const result = operation(...args);
+                this.exec(`RELEASE ${savepoint}`);
+                return result;
+            }
+            catch (error) {
+                try {
+                    this.exec(`ROLLBACK TO ${savepoint}`);
+                    this.exec(`RELEASE ${savepoint}`);
+                }
+                catch { }
+                throw error;
+            }
+        };
+        const transaction = ((...args) => execute("DEFERRED", args));
+        transaction.deferred = (...args) => execute("DEFERRED", args);
+        transaction.immediate = (...args) => execute("IMMEDIATE", args);
+        transaction.exclusive = (...args) => execute("EXCLUSIVE", args);
+        return transaction;
+    }
+}
+function resolveBusyTimeout() {
+    const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
+    const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
+}
 /**
  * Switch a connection to WAL, retrying on `SQLITE_BUSY` within the busy-timeout
- * budget. Unlike ordinary writes, migrating the journal needs a brief exclusive
- * lock and does NOT invoke the busy handler, so concurrent first-time opens of a
- * cold database throw "database is locked" even with `busy_timeout` set. Once the
- * database is already WAL the pragma is a cheap no-op that does not contend.
+ * budget. Migrating the journal needs a brief exclusive lock and does not invoke
+ * SQLite's busy handler on every supported runtime.
  */
 function enableWal(db, budgetMs) {
     const deadline = Date.now() + Math.max(budgetMs, 0);
@@ -39,46 +85,23 @@ function enableWal(db, budgetMs) {
         }
     }
 }
-/**
- * Open a SQLite database using better-sqlite3.
- *
- * `better-sqlite3` defaults `busy_timeout` to 0, so concurrent writers throw
- * `SQLITE_BUSY` instead of waiting. WAL improves read-while-write concurrency
- * but does not serialise writers. Setting the timeout at connection open makes
- * parallel processes queue at batch boundaries instead of failing on contact.
- *
- * WAL is enabled here too (with a bounded retry) so connection-level pragmas
- * live in one place and the cold-database journal migration survives concurrent
- * opens.
- *
- * Default 120_000 ms outlasts the worst-case batch commit on a multi-GB
- * index. Override with `QMD_SQLITE_BUSY_TIMEOUT` (value in milliseconds; `0`
- * restores the upstream fail-fast behaviour).
- */
+/** Open a writable QMD database using Node's built-in SQLite runtime. */
 export function openDatabase(path) {
-    const db = new BetterSqlite3(path);
-    const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
-    const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
-    const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
-    db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+    const busyTimeoutMs = resolveBusyTimeout();
+    const db = new Database(path, { allowExtension: true, timeout: busyTimeoutMs });
     enableWal(db, busyTimeoutMs);
     return db;
 }
 /** Open an existing database without changing journal mode, schema, or user data. */
 export function openReadOnlyDatabase(path) {
-    const options = { readonly: true, fileMustExist: true };
-    const db = new BetterSqlite3(path, options);
-    const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
-    const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
-    const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
-    db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
-    return db;
+    const busyTimeoutMs = resolveBusyTimeout();
+    return new Database(path, {
+        readOnly: true,
+        allowExtension: true,
+        timeout: busyTimeoutMs,
+    });
 }
-/**
- * Load the sqlite-vec extension into a database.
- *
- * Throws with fix instructions when the extension is unavailable.
- */
+/** Load the sqlite-vec extension into a database. */
 export function loadSqliteVec(db) {
     try {
         sqliteVec.load(db);

package/dist/index.d.ts

@@ -17,9 +17,13 @@
  *   await store.close()
  */
 import { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES, type Store as InternalStore, type DocumentResult, type DocumentNotFound, type DocumentExcludedByIgnore, type DocumentLookupError, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type ExpandedQuery, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type SearchHooks, type ReindexProgress, type ReindexResult, type EmbedProgress, type EmbedResult, type ChunkStrategy } from "./store.js";
+import type { DocumentMetadata, MetadataScalar, MetadataScalarArray, MetadataValue } from "./metadata.js";
+import { parseMetadataFilter, MetadataFilterError, type MetadataFilter, type MetadataFilterGroup, type MetadataFilterNegation, type MetadataCondition } from "./metadata-filter.js";
 import type { ExpansionMode } from "./search/query-expansion.js";
 import { type Collection, type CollectionConfig, type NamedCollection, type ContextMap } from "./collections.js";
 export type { DocumentResult, DocumentNotFound, DocumentExcludedByIgnore, DocumentLookupError, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, ExpandedQuery, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, SearchHooks, ReindexProgress, ReindexResult, EmbedProgress, EmbedResult, Collection, CollectionConfig, NamedCollection, ContextMap, };
+export type { DocumentMetadata, MetadataScalar, MetadataScalarArray, MetadataValue, MetadataFilter, MetadataFilterGroup, MetadataFilterNegation, MetadataCondition, };
+export { parseMetadataFilter, MetadataFilterError };
 export type { InternalStore };
 export type { ExpansionMode } from "./search/query-expansion.js";
 export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
@@ -65,6 +69,8 @@ export interface SearchOptions {
     collection?: string;
     /** Filter to specific collections */
     collections?: string[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
     /** Max results (default: 10) */
     limit?: number;
     /** Max candidates to rerank (default: 40) */
@@ -88,6 +94,8 @@ export interface SearchOptions {
 export interface LexSearchOptions {
     limit?: number;
     collection?: string | string[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
 }
 /**
  * Options for searchVector() — vector similarity search.
@@ -95,6 +103,8 @@ export interface LexSearchOptions {
 export interface VectorSearchOptions {
     limit?: number;
     collection?: string | string[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
 }
 /**
  * Options for expandQuery() — manual query expansion.

package/dist/index.js

@@ -20,6 +20,7 @@ import { existsSync } from "node:fs";
 import { createStore as createStoreInternal, hybridQuery, structuredSearch, extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES, reindexCollection, generateEmbeddings, listCollections as storeListCollections, syncConfigToDb, getStoreCollections, getStoreCollection, getStoreGlobalContext, getStoreContexts, upsertStoreCollection, removeCollection as removeCollectionWithDocuments, renameCollection as renameCollectionWithDocuments, updateStoreContext, removeStoreContext, setStoreGlobalContext, vacuumDatabase, cleanupOrphanedContent, cleanupOrphanedVectors, deleteLLMCache, deleteInactiveDocuments, clearAllEmbeddings, getPendingEmbeddingDocsReadOnly, getIndexHealthReadOnly, getStatusReadOnly, } from "./store.js";
 import { DEFAULT_EMBED_MODEL_URI, LlamaCpp, waitForLLMSessionsToDrain, } from "./llm.js";
 import { LocalEmbeddingProviderOwner } from "./embedding/local.js";
+import { parseMetadataFilter, MetadataFilterError, } from "./metadata-filter.js";
 import { OpenAIEmbeddingProvider, UnavailableOpenAIEmbeddingProvider, } from "./embedding/openai.js";
 import { authorizeRemoteEmbeddingRequest, remoteEmbeddingIdentity, } from "./embedding/remote-embedding.js";
 import { readStoredEmbeddingIdentity } from "./embedding/identity.js";
@@ -29,6 +30,7 @@ import { rebuildCjkLexicalIndex } from "./search/cjk-index.js";
 import { RemoteLLM } from "./remote-llm.js";
 import { HybridLLM } from "./hybrid-llm.js";
 import { createCollectionConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, } from "./collections.js";
+export { parseMetadataFilter, MetadataFilterError };
 // Re-export utility functions and types used by frontends
 export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
 // Re-export getDefaultDbPath for CLI/MCP that need the default database location
@@ -208,10 +210,15 @@ export async function createStore(options) {
                 ...(opts.collections ?? []),
             ];
             const skipRerank = opts.rerank === false;
+            // The SDK is also a JavaScript boundary: TypeScript declarations do not
+            // protect plain-JS callers or deserialized input. Apply the same bounded,
+            // strict validation used by CLI, MCP, and HTTP before compiling SQL.
+            const filter = opts.filter === undefined ? undefined : parseMetadataFilter(opts.filter);
             if (opts.queries) {
                 // Pre-expanded queries — use structuredSearch
                 return structuredSearch(internal, opts.queries, {
                     collections: collections.length > 0 ? collections : undefined,
+                    filter,
                     limit: opts.limit,
                     minScore: opts.minScore,
                     explain: opts.explain,
@@ -225,6 +232,7 @@ export async function createStore(options) {
             return hybridQuery(internal, opts.query, {
                 collections: collections.length > 0 ? collections : undefined,
                 collection: collections.length === 1 ? collections[0] : (collections.length > 0 ? collections : undefined),
+                filter,
                 limit: opts.limit,
                 minScore: opts.minScore,
                 explain: opts.explain,
@@ -238,10 +246,14 @@ export async function createStore(options) {
                 chunkStrategy: opts.chunkStrategy,
             });
         },
-        searchLex: async (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
+        searchLex: async (q, opts) => {
+            const filter = opts?.filter === undefined ? undefined : parseMetadataFilter(opts.filter);
+            return internal.searchFTS(q, opts?.limit, opts?.collection, filter);
+        },
         searchVector: async (q, opts) => {
+            const filter = opts?.filter === undefined ? undefined : parseMetadataFilter(opts.filter);
             const provider = internal.embeddingProvider;
-            return internal.searchVec(q, provider?.model ?? internal.llm?.embedModelName ?? DEFAULT_EMBED_MODEL_URI, opts?.limit, opts?.collection);
+            return internal.searchVec(q, provider?.model ?? internal.llm?.embedModelName ?? DEFAULT_EMBED_MODEL_URI, opts?.limit, opts?.collection, undefined, undefined, filter);
         },
         expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.expansionContext, {
             includeLexical: opts?.includeLexical,

package/dist/llm.d.ts

@@ -199,7 +199,13 @@ export type PullResult = {
 export type GgufFileInspection = {
     exists: boolean;
     valid: boolean;
-    kind: "missing" | "gguf" | "html" | "invalid";
+    /**
+     * "html" and "invalid" mean the header was read and is confirmed bad.
+     * "unreadable" means the read itself failed, so nothing is known about the
+     * content. The two stay distinct because only the first justifies deleting
+     * the file.
+     */
+    kind: "missing" | "gguf" | "html" | "invalid" | "unreadable";
     sizeBytes?: number;
     magic?: string;
     details: string;

package/dist/llm.js

@@ -235,10 +235,13 @@ export function inspectGgufFile(filePath) {
         };
     }
     catch (error) {
+        // stat/open/read threw, so the header was never seen. Reporting this as
+        // "invalid" would claim a verdict no read supports, and `magic` stays
+        // undefined for the same reason.
         return {
             exists: true,
             valid: false,
-            kind: "invalid",
+            kind: "unreadable",
             sizeBytes,
             details: `cannot read model file: ${error instanceof Error ? error.message : String(error)}`,
         };
@@ -253,11 +256,25 @@ function validateGgufFile(filePath, modelUri) {
     const inspection = inspectGgufFile(filePath);
     if (!inspection.exists || inspection.valid)
         return; // let downstream handle missing files
-    // Remove the bad file so the next attempt re-downloads
+    // A read that failed says nothing about the bytes on disk. Deleting here
+    // throws away a file that is usually fine (fd exhaustion, a concurrent
+    // loader, a volume that briefly went away) and re-downloading it can cost
+    // gigabytes, so surface the real error and leave the file alone.
+    if (inspection.kind === "unreadable") {
+        throw new Error(`Model file could not be read, so it could not be validated (${inspection.details}).\n` +
+            `Model: ${modelUri}\n` +
+            `Path:  ${filePath}\n\n` +
+            `The file has been left in place. If this repeats, check open file limits, ` +
+            `permissions, and whether the volume holding the model cache is still mounted.`);
+    }
+    // Confirmed bad content: remove it so the next attempt re-downloads.
+    let removed = true;
     try {
         unlinkSync(filePath);
     }
-    catch { /* best effort */ }
+    catch {
+        removed = false;
+    }
     if (inspection.kind === "html") {
         throw new Error(`Downloaded model file is an HTML page, not a GGUF model (${formatModelFileSize(inspection.sizeBytes ?? 0)}).\n` +
             `Something is intercepting the download from huggingface.co (a proxy, firewall, or captive portal).\n\n` +
@@ -272,7 +289,9 @@ function validateGgufFile(filePath, modelUri) {
     throw new Error(`Model file is not valid GGUF (expected magic "GGUF", got "${inspection.magic ?? "unknown"}", file is ${formatModelFileSize(inspection.sizeBytes ?? 0)}).\n` +
         `Model: ${modelUri}\n` +
         `Path:  ${filePath}\n\n` +
-        `The file has been removed. Run the command again to re-download.`);
+        (removed
+            ? `The file has been removed. Run the command again to re-download.`
+            : `The file could NOT be removed. Delete it manually, then run the command again.`));
 }
 /**
  * node-llama-cpp prints a multi-line download progress bar when the second

package/dist/mcp/server.js

@@ -15,10 +15,24 @@ import { createMcpHandler, McpServer, ResourceTemplate } from "@modelcontextprot
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { existsSync } from "fs";
-import { createStore, extractSnippet, addLineNumbers, getDefaultDbPath, DEFAULT_MULTI_GET_MAX_BYTES, } from "../index.js";
+import { createStore, extractSnippet, addLineNumbers, getDefaultDbPath, DEFAULT_MULTI_GET_MAX_BYTES, parseMetadataFilter, } from "../index.js";
 import { getConfigPath } from "../collections.js";
 import { enableProductionMode } from "../store.js";
 import { checkRequestOrigin, resolveOriginGuard } from "./origin-guard.js";
+/**
+ * Validate an untrusted `filter` argument through the shared runtime
+ * validator. Returns the parse error message when invalid.
+ */
+function validateFilterArgument(filter) {
+    if (filter === undefined)
+        return {};
+    try {
+        return { filter: parseMetadataFilter(filter) };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
 // =============================================================================
 // Helper functions
 // =============================================================================
@@ -251,14 +265,21 @@ Context-aware lex (C++ performance, not sports):
             minScore: z.number().optional().default(0).describe("Min relevance 0-1 (default: 0)"),
             candidateLimit: z.number().optional().describe("Maximum candidates to rerank (default: 40, lower = faster but may miss results)"),
             collections: z.array(z.string()).optional().describe("Filter to collections (OR match)"),
+            filter: z.record(z.string(), z.unknown()).optional().describe("Metadata filter (recursive JSON AST). Every returned result satisfies it. " +
+                "Nodes are operator-discriminated: logical groups {operator:'and'|'or', operands:[...]}, " +
+                "negation {operator:'not', operand:{...}}, and conditions {key, operator, value} with " +
+                "operators eq/ne/gt/gte/lt/lte (comparison), in/nin/all (membership), exists (presence). " +
+                "Values are typed exactly (no coercion); missing keys do not match ne/nin. " +
+                "Example: {\"operator\":\"and\",\"operands\":[{\"key\":\"topics\",\"operator\":\"all\",\"value\":[\"typescript\"]}," +
+                "{\"key\":\"status\",\"operator\":\"ne\",\"value\":\"draft\"}]}"),
             expansionContext: z.string().optional().describe("Additional context used only to generate lex, vec, and hyde query expansions."),
             rerankContext: z.string().optional().describe("Additional context used only to rerank results and select snippets/chunks."),
+            intent: z.string().optional().describe("Background context to disambiguate the query. Example: query='performance', intent='web page load times and Core Web Vitals'. Does not search on its own."),
             rerank: z.boolean().optional().default(true).describe("Rerank results using LLM (default: true). Set to false for faster results on CPU-only machines."),
             explain: z.boolean().optional().default(false).describe("Include retrieval traces and the shared query-expansion decision or typed expansion error"),
             includeHyde: z.boolean().optional().default(true).describe("Whether to include HyDE (hypothetical document) in query expansion (default: true)"),
         }),
-    }, track(async ({ query, searches, expansion, includeHyde, limit, minScore, candidateLimit, collections, expansionContext, rerankContext, rerank, explain }) => {
-        // Require exactly one of `query` (plain text with an expansion policy) or `searches` (typed sub-queries).
+    }, track(async ({ query, searches, expansion, includeHyde, limit, minScore, candidateLimit, collections, filter, expansionContext, rerankContext, intent, rerank, explain }) => {
         if (!query && (!searches || searches.length === 0)) {
             return {
                 content: [{ type: "text", text: "Error: provide either 'query' (plain text) or 'searches' (typed sub-queries)" }],
@@ -271,6 +292,13 @@ Context-aware lex (C++ performance, not sports):
                 isError: true,
             };
         }
+        const filterValidation = validateFilterArgument(filter);
+        if (filterValidation.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${filterValidation.error}` }],
+                isError: true,
+            };
+        }
         // Use default collections if none specified
         const effectiveCollections = collections ?? defaultCollectionNames;
         // Plain `query` follows the requested SDK expansion policy before fusion and reranking;
@@ -278,6 +306,8 @@ Context-aware lex (C++ performance, not sports):
         const searchOptions = query
             ? { query }
             : { queries: (searches ?? []).map(s => ({ type: s.type, query: s.query })) };
+        const effectiveExpansionContext = expansionContext ?? intent;
+        const effectiveRerankContext = rerankContext ?? intent;
         let expansionDecision;
         let expansionError;
         let results;
@@ -285,12 +315,13 @@ Context-aware lex (C++ performance, not sports):
             results = await store.search({
                 ...searchOptions,
                 collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
+                filter: filterValidation.filter,
                 limit,
                 minScore,
                 candidateLimit,
                 rerank,
-                expansionContext,
-                rerankContext,
+                expansionContext: effectiveExpansionContext,
+                rerankContext: effectiveRerankContext,
                 explain,
                 expansion: query ? expansion : undefined,
                 includeHyde,
@@ -323,6 +354,7 @@ Context-aware lex (C++ performance, not sports):
                 title: r.title,
                 score: Math.round(r.score * 100) / 100,
                 context: r.context,
+                ...(Object.keys(r.metadata).length > 0 ? { metadata: r.metadata } : {}),
                 line,
                 snippet: addLineNumbers(snippet, line),
                 ...(explain && r.explain ? { explain: r.explain } : {}),
@@ -798,7 +830,21 @@ export async function startMcpHttpServer(port, options = {}) {
             // REST endpoint: POST /query (alias: /search) — structured search without MCP protocol
             if ((pathname === "/query" || pathname === "/search") && nodeReq.method === "POST") {
                 const rawBody = await collectBody(nodeReq);
-                const params = JSON.parse(rawBody);
+                let parsedParams;
+                try {
+                    parsedParams = JSON.parse(rawBody);
+                }
+                catch {
+                    nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                    nodeRes.end(JSON.stringify({ error: "Invalid JSON body" }));
+                    return;
+                }
+                if (typeof parsedParams !== "object" || parsedParams === null || Array.isArray(parsedParams)) {
+                    nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                    nodeRes.end(JSON.stringify({ error: "JSON body must be an object" }));
+                    return;
+                }
+                const params = parsedParams;
                 // Validate required fields
                 if (!params.searches || !Array.isArray(params.searches)) {
                     nodeRes.writeHead(400, { "Content-Type": "application/json" });
@@ -811,11 +857,28 @@ export async function startMcpHttpServer(port, options = {}) {
                     type: s.type,
                     query: String(s.query || ""),
                 }));
+                // Optional metadata filter — must be an object and a valid filter AST
+                let restFilter;
+                if (params.filter !== undefined) {
+                    if (typeof params.filter !== "object" || params.filter === null || Array.isArray(params.filter)) {
+                        nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                        nodeRes.end(JSON.stringify({ error: "Invalid field: filter (must be an object)" }));
+                        return;
+                    }
+                    const filterValidation = validateFilterArgument(params.filter);
+                    if (filterValidation.error) {
+                        nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                        nodeRes.end(JSON.stringify({ error: filterValidation.error }));
+                        return;
+                    }
+                    restFilter = filterValidation.filter;
+                }
                 // Use default collections if none specified
                 const effectiveCollections = Array.isArray(params.collections) ? params.collections.map(String) : defaultCollectionNames;
                 const results = await store.search({
                     queries,
                     collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
+                    filter: restFilter,
                     limit: typeof params.limit === "number" ? params.limit : 10,
                     minScore: typeof params.minScore === "number" ? params.minScore : 0,
                     candidateLimit: typeof params.candidateLimit === "number" ? params.candidateLimit : undefined,
@@ -835,6 +898,7 @@ export async function startMcpHttpServer(port, options = {}) {
                         title: r.title,
                         score: Math.round(r.score * 100) / 100,
                         context: r.context,
+                        ...(Object.keys(r.metadata).length > 0 ? { metadata: r.metadata } : {}),
                         line,
                         snippet: addLineNumbers(snippet, line),
                     };

package/dist/metadata-filter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * QMD Metadata Filter - Recursive filter AST, strict runtime validation, and
+ * parameterized SQL compilation.
+ *
+ * The filter has one canonical, `operator`-discriminated recursive shape shared
+ * by every public search surface (CLI, SDK, MCP, HTTP):
+ *
+ *   { "operator": "and", "operands": [ ... ] }
+ *   { "operator": "not", "operand": { ... } }
+ *   { "key": "status", "operator": "eq", "value": "published" }
+ *
+ * Compilation emits correlated EXISTS/NOT EXISTS subqueries over
+ * `document_metadata_values` with every user value bound as a parameter —
+ * metadata keys and values are data, never SQL.
+ */
+import type { MetadataScalar, MetadataScalarArray } from "./metadata.js";
+export type MetadataFilter = MetadataFilterGroup | MetadataFilterNegation | MetadataCondition;
+export interface MetadataFilterGroup {
+    operator: "and" | "or";
+    operands: readonly MetadataFilter[];
+}
+export interface MetadataFilterNegation {
+    operator: "not";
+    operand: MetadataFilter;
+}
+export type MetadataCondition = {
+    key: string;
+    operator: "eq" | "ne";
+    value: MetadataScalar;
+} | {
+    key: string;
+    operator: "gt" | "gte" | "lt" | "lte";
+    value: string | number;
+} | {
+    key: string;
+    operator: "in" | "nin" | "all";
+    value: MetadataScalarArray;
+} | {
+    key: string;
+    operator: "exists";
+    value: boolean;
+};
+export interface CompiledMetadataFilter {
+    sql: string;
+    params: (string | number)[];
+}
+/** Raised by parseMetadataFilter with the JSON path of the failing node. */
+export declare class MetadataFilterError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/** Defensive limits for recursive filters from untrusted callers. */
+export declare const METADATA_FILTER_LIMITS: {
+    readonly maxDepth: 16;
+    readonly maxNodes: 256;
+    readonly maxGroupOperands: 32;
+    readonly maxMembershipValues: 64;
+    readonly maxKeyBytes: 128;
+    readonly maxStringLength: 1024;
+};
+/**
+ * Strictly validate an untrusted value as a MetadataFilter.
+ * Rejects unknown operators, unknown properties, operator-incompatible values,
+ * and inputs exceeding METADATA_FILTER_LIMITS. Canonicalizes membership value
+ * arrays by de-duplicating while preserving order.
+ */
+export declare function parseMetadataFilter(input: unknown): MetadataFilter;
+/**
+ * Compile a validated filter into one parameterized SQL predicate correlated
+ * against a documents-table alias (e.g. `d`). All keys and values are bound
+ * parameters. The caller is responsible for restricting the surrounding query
+ * to active documents with current, error-free metadata extraction.
+ */
+export declare function compileMetadataFilter(filter: MetadataFilter, documentsAlias: string): CompiledMetadataFilter;