@wei840222/qmd 2026.9.6 → 2026.9.25

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;

package/dist/metadata-filter.js

@@ -0,0 +1,279 @@
+/**
+ * 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 { METADATA_LIMITS } from "./metadata.js";
+/** Raised by parseMetadataFilter with the JSON path of the failing node. */
+export class MetadataFilterError extends Error {
+    path;
+    constructor(path, message) {
+        super(`Invalid metadata filter at ${path}: ${message}`);
+        this.name = "MetadataFilterError";
+        this.path = path;
+    }
+}
+// =============================================================================
+// Limits
+// =============================================================================
+/** Defensive limits for recursive filters from untrusted callers. */
+export const METADATA_FILTER_LIMITS = {
+    maxDepth: 16,
+    maxNodes: 256,
+    maxGroupOperands: 32,
+    maxMembershipValues: 64,
+    maxKeyBytes: METADATA_LIMITS.maxKeyBytes,
+    maxStringLength: METADATA_LIMITS.maxStringLength,
+};
+const GROUP_OPERATORS = new Set(["and", "or"]);
+const COMPARISON_OPERATORS = new Set(["eq", "ne", "gt", "gte", "lt", "lte"]);
+const ORDERED_OPERATORS = new Set(["gt", "gte", "lt", "lte"]);
+const MEMBERSHIP_OPERATORS = new Set(["in", "nin", "all"]);
+const CONDITION_OPERATORS = new Set([...COMPARISON_OPERATORS, ...MEMBERSHIP_OPERATORS, "exists"]);
+const ALL_OPERATORS = [...GROUP_OPERATORS, "not", ...CONDITION_OPERATORS];
+/**
+ * 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 function parseMetadataFilter(input) {
+    const state = { nodes: 0 };
+    return parseFilterNode(input, "$", 1, state);
+}
+function parseFilterNode(input, path, depth, state) {
+    if (depth > METADATA_FILTER_LIMITS.maxDepth) {
+        throw new MetadataFilterError(path, `exceeds maximum nesting depth of ${METADATA_FILTER_LIMITS.maxDepth}`);
+    }
+    state.nodes += 1;
+    if (state.nodes > METADATA_FILTER_LIMITS.maxNodes) {
+        throw new MetadataFilterError(path, `exceeds maximum of ${METADATA_FILTER_LIMITS.maxNodes} nodes`);
+    }
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new MetadataFilterError(path, "each filter node must be an object");
+    }
+    const node = input;
+    const operator = node["operator"];
+    if (typeof operator !== "string") {
+        throw new MetadataFilterError(path, "missing 'operator' property");
+    }
+    if (GROUP_OPERATORS.has(operator)) {
+        return parseFilterGroup(node, operator, path, depth, state);
+    }
+    if (operator === "not") {
+        return parseFilterNegation(node, path, depth, state);
+    }
+    if (CONDITION_OPERATORS.has(operator)) {
+        return parseFilterCondition(node, operator, path);
+    }
+    throw new MetadataFilterError(path, `unknown operator '${operator}' — expected one of: ${ALL_OPERATORS.join(", ")}`);
+}
+function parseFilterGroup(node, operator, path, depth, state) {
+    rejectUnknownProperties(node, ["operator", "operands"], path);
+    const operands = node["operands"];
+    if (!Array.isArray(operands)) {
+        throw new MetadataFilterError(path, `'${operator}' requires an 'operands' array`);
+    }
+    if (operands.length === 0) {
+        throw new MetadataFilterError(path, `'${operator}' requires a non-empty 'operands' array`);
+    }
+    if (operands.length > METADATA_FILTER_LIMITS.maxGroupOperands) {
+        throw new MetadataFilterError(path, `'${operator}' exceeds maximum of ${METADATA_FILTER_LIMITS.maxGroupOperands} operands`);
+    }
+    return {
+        operator,
+        operands: operands.map((operand, index) => parseFilterNode(operand, `${path}.operands[${index}]`, depth + 1, state)),
+    };
+}
+function parseFilterNegation(node, path, depth, state) {
+    rejectUnknownProperties(node, ["operator", "operand"], path);
+    if (!("operand" in node)) {
+        throw new MetadataFilterError(path, "'not' requires exactly one 'operand'");
+    }
+    return {
+        operator: "not",
+        operand: parseFilterNode(node["operand"], `${path}.operand`, depth + 1, state),
+    };
+}
+function parseFilterCondition(node, operator, path) {
+    rejectUnknownProperties(node, ["key", "operator", "value"], path);
+    const key = node["key"];
+    if (typeof key !== "string" || key.length === 0) {
+        throw new MetadataFilterError(path, `'${operator}' requires a non-empty string 'key'`);
+    }
+    if (Buffer.byteLength(key, "utf-8") > METADATA_FILTER_LIMITS.maxKeyBytes) {
+        throw new MetadataFilterError(path, `'key' exceeds ${METADATA_FILTER_LIMITS.maxKeyBytes} bytes`);
+    }
+    if (!("value" in node)) {
+        throw new MetadataFilterError(path, `'${operator}' requires a 'value'`);
+    }
+    const value = node["value"];
+    if (operator === "exists") {
+        if (typeof value !== "boolean") {
+            throw new MetadataFilterError(`${path}.value`, "'exists' requires a boolean value");
+        }
+        return { key, operator, value };
+    }
+    if (MEMBERSHIP_OPERATORS.has(operator)) {
+        return {
+            key,
+            operator: operator,
+            value: parseMembershipValues(value, operator, path),
+        };
+    }
+    // Comparison operators: eq, ne, gt, gte, lt, lte.
+    const scalar = parseScalarValue(value, `${path}.value`);
+    if (ORDERED_OPERATORS.has(operator) && typeof scalar === "boolean") {
+        throw new MetadataFilterError(`${path}.value`, `'${operator}' requires a string or number value`);
+    }
+    return { key, operator, value: scalar };
+}
+function parseMembershipValues(value, operator, path) {
+    if (!Array.isArray(value)) {
+        throw new MetadataFilterError(`${path}.value`, `'${operator}' requires an array value`);
+    }
+    if (value.length === 0) {
+        throw new MetadataFilterError(`${path}.value`, `'${operator}' requires a non-empty array value`);
+    }
+    if (value.length > METADATA_FILTER_LIMITS.maxMembershipValues) {
+        throw new MetadataFilterError(`${path}.value`, `'${operator}' exceeds maximum of ${METADATA_FILTER_LIMITS.maxMembershipValues} values`);
+    }
+    const scalars = value.map((element, index) => parseScalarValue(element, `${path}.value[${index}]`));
+    // Narrow each homogeneous case explicitly so the public array union remains
+    // precise without discarding type evidence through chained assertions.
+    if (scalars.every((scalar) => typeof scalar === "string")) {
+        return Array.from(new Set(scalars));
+    }
+    if (scalars.every((scalar) => typeof scalar === "number")) {
+        return Array.from(new Set(scalars));
+    }
+    if (scalars.every((scalar) => typeof scalar === "boolean")) {
+        return Array.from(new Set(scalars));
+    }
+    throw new MetadataFilterError(`${path}.value`, `'${operator}' requires a homogeneous array of one scalar type`);
+}
+function parseScalarValue(value, path) {
+    if (typeof value === "string") {
+        if (value.length > METADATA_FILTER_LIMITS.maxStringLength) {
+            throw new MetadataFilterError(path, `string exceeds ${METADATA_FILTER_LIMITS.maxStringLength} characters`);
+        }
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new MetadataFilterError(path, "numbers must be finite");
+        }
+        return value;
+    }
+    if (typeof value === "boolean")
+        return value;
+    throw new MetadataFilterError(path, "expected a string, number, or boolean");
+}
+function rejectUnknownProperties(node, allowed, path) {
+    for (const property of Object.keys(node)) {
+        if (!allowed.includes(property)) {
+            throw new MetadataFilterError(path, `unknown property '${property}' — allowed: ${allowed.join(", ")}`);
+        }
+    }
+}
+// =============================================================================
+// SQL compilation
+// =============================================================================
+/**
+ * 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 function compileMetadataFilter(filter, documentsAlias) {
+    const params = [];
+    const sql = compileFilterNode(filter, documentsAlias, params);
+    return { sql, params };
+}
+function compileFilterNode(filter, alias, params) {
+    switch (filter.operator) {
+        case "and":
+        case "or": {
+            const joiner = filter.operator === "and" ? " AND " : " OR ";
+            return `(${filter.operands.map(operand => compileFilterNode(operand, alias, params)).join(joiner)})`;
+        }
+        case "not":
+            return `NOT ${compileFilterNode(filter.operand, alias, params)}`;
+        case "exists":
+            params.push(filter.key);
+            return filter.value
+                ? buildValueExistsSql(alias, "mv.key = ?")
+                : `NOT ${buildValueExistsSql(alias, "mv.key = ?")}`;
+        case "eq":
+        case "gt":
+        case "gte":
+        case "lt":
+        case "lte": {
+            const sqlOperator = { eq: "=", gt: ">", gte: ">=", lt: "<", lte: "<=" }[filter.operator];
+            params.push(filter.key, bindScalar(filter.value));
+            return buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueTypeOf(filter.value)}' AND mv.${valueColumnOf(filter.value)} ${sqlOperator} ?`);
+        }
+        case "ne": {
+            // Key must have at least one same-type value, and no same-type value
+            // may equal the operand. Missing keys and type mismatches do not match.
+            const valueType = valueTypeOf(filter.value);
+            params.push(filter.key);
+            const presentSql = buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}'`);
+            params.push(filter.key, bindScalar(filter.value));
+            const equalSql = buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}' AND mv.${valueColumnOf(filter.value)} = ?`);
+            return `(${presentSql} AND NOT ${equalSql})`;
+        }
+        case "in":
+        case "nin": {
+            const valueType = valueTypeOf(filter.value[0]);
+            const column = valueColumnOf(filter.value[0]);
+            const placeholders = filter.value.map(() => "?").join(", ");
+            if (filter.operator === "in") {
+                params.push(filter.key, ...filter.value.map(bindScalar));
+                return buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}' AND mv.${column} IN (${placeholders})`);
+            }
+            params.push(filter.key);
+            const presentSql = buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}'`);
+            params.push(filter.key, ...filter.value.map(bindScalar));
+            const memberSql = buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}' AND mv.${column} IN (${placeholders})`);
+            return `(${presentSql} AND NOT ${memberSql})`;
+        }
+        case "all": {
+            const valueType = valueTypeOf(filter.value[0]);
+            const column = valueColumnOf(filter.value[0]);
+            const memberSqls = filter.value.map(element => {
+                params.push(filter.key, bindScalar(element));
+                return buildValueExistsSql(alias, `mv.key = ? AND mv.value_type = '${valueType}' AND mv.${column} = ?`);
+            });
+            return `(${memberSqls.join(" AND ")})`;
+        }
+    }
+}
+function buildValueExistsSql(alias, conditionSql) {
+    return `EXISTS (SELECT 1 FROM document_metadata_values mv WHERE mv.document_id = ${alias}.id AND ${conditionSql})`;
+}
+function valueTypeOf(scalar) {
+    return typeof scalar;
+}
+function valueColumnOf(scalar) {
+    if (typeof scalar === "string")
+        return "text_value";
+    if (typeof scalar === "number")
+        return "number_value";
+    return "boolean_value";
+}
+function bindScalar(scalar) {
+    if (typeof scalar === "boolean")
+        return scalar ? 1 : 0;
+    return scalar;
+}

package/dist/metadata-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * QMD Metadata Store - Schema, persistence, and batch loading for document
+ * metadata.
+ *
+ * Metadata attaches to document identity (`documents.id`), not content
+ * identity: two paths can share one content hash while carrying different
+ * metadata. SQLite stays a derived index — metadata is rebuilt from source
+ * documents on `qmd update`, never mutated in place.
+ *
+ * `document_metadata` records extraction state per document (including
+ * successful-but-empty extraction), so filtered search can distinguish
+ * "extracted with no metadata" from "not yet extracted" and "extraction
+ * failed". `document_metadata_values` holds one indexed row per scalar value
+ * for filtering.
+ */
+import type { Database } from "./db.js";
+import { type DocumentMetadata, type MetadataExtractionResult } from "./metadata.js";
+export declare function initializeMetadataSchema(db: Database): void;
+/**
+ * Extract and persist metadata for one document, replacing any prior rows.
+ *
+ * With `onlyIfStale`, extraction is skipped when the document already has a
+ * current-version extraction row — the cheap path for unchanged documents
+ * during re-index. Returns the extraction result, or null when skipped.
+ */
+export declare function syncDocumentMetadata(db: Database, documentId: number, content: string, path: string, options?: {
+    onlyIfStale?: boolean;
+}): MetadataExtractionResult | null;
+/**
+ * Replace a document's metadata rows atomically. A failed extraction persists
+ * empty metadata plus the error, so stale metadata never survives a bad edit.
+ */
+export declare function replaceDocumentMetadata(db: Database, documentId: number, extraction: MetadataExtractionResult): void;
+/**
+ * Count active documents without a current, error-free metadata extraction.
+ * These documents are excluded from filtered search until `qmd update` runs.
+ */
+export declare function countDocumentsPendingMetadata(db: Database): number;
+/**
+ * Batch-load canonical metadata for a set of result filepaths
+ * (`qmd://collection/path`). One query — never per-result lookups.
+ */
+export declare function getMetadataByFilepath(db: Database, filepaths: readonly string[]): Map<string, DocumentMetadata>;
+/** Parse a stored `metadata_json` column value, tolerating absent rows. */
+export declare function parseMetadataJson(metadataJson: string | null | undefined): DocumentMetadata;