@wei840222/qmd 2026.8.28 → 2026.9.25

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;

package/dist/metadata-store.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { extractDocumentMetadata, METADATA_EXTRACTION_VERSION, } from "./metadata.js";
+// =============================================================================
+// Schema
+// =============================================================================
+export function initializeMetadataSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS document_metadata (
+      document_id INTEGER PRIMARY KEY,
+      metadata_json TEXT NOT NULL DEFAULT '{}',
+      extraction_version INTEGER NOT NULL,
+      extraction_error TEXT,
+      extracted_at TEXT NOT NULL,
+      FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS document_metadata_values (
+      document_id INTEGER NOT NULL,
+      key TEXT NOT NULL,
+      ordinal INTEGER NOT NULL,
+      value_type TEXT NOT NULL,
+      text_value TEXT,
+      number_value REAL,
+      boolean_value INTEGER,
+      PRIMARY KEY (document_id, key, ordinal),
+      FOREIGN KEY (document_id)
+        REFERENCES document_metadata(document_id)
+        ON DELETE CASCADE,
+      CHECK (value_type IN ('string', 'number', 'boolean')),
+      CHECK (
+        (value_type = 'string' AND text_value IS NOT NULL AND number_value IS NULL AND boolean_value IS NULL)
+        OR (value_type = 'number' AND number_value IS NOT NULL AND text_value IS NULL AND boolean_value IS NULL)
+        OR (value_type = 'boolean' AND boolean_value IN (0, 1) AND text_value IS NULL AND number_value IS NULL)
+      )
+    )
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_text_lookup
+    ON document_metadata_values(key, text_value, document_id)
+    WHERE value_type = 'string'
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_number_lookup
+    ON document_metadata_values(key, number_value, document_id)
+    WHERE value_type = 'number'
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_boolean_lookup
+    ON document_metadata_values(key, boolean_value, document_id)
+    WHERE value_type = 'boolean'
+  `);
+}
+// =============================================================================
+// Persistence
+// =============================================================================
+/**
+ * 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 function syncDocumentMetadata(db, documentId, content, path, options) {
+    if (options?.onlyIfStale && isDocumentMetadataCurrent(db, documentId))
+        return null;
+    const extraction = extractDocumentMetadata(content, path);
+    replaceDocumentMetadata(db, documentId, extraction);
+    return extraction;
+}
+/**
+ * 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 function replaceDocumentMetadata(db, documentId, extraction) {
+    const replace = db.transaction(() => {
+        db.prepare(`
+      INSERT INTO document_metadata (document_id, metadata_json, extraction_version, extraction_error, extracted_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(document_id) DO UPDATE SET
+        metadata_json = excluded.metadata_json,
+        extraction_version = excluded.extraction_version,
+        extraction_error = excluded.extraction_error,
+        extracted_at = excluded.extracted_at
+    `).run(documentId, JSON.stringify(extraction.metadata), extraction.extractionVersion, extraction.error ?? null, new Date().toISOString());
+        db.prepare(`DELETE FROM document_metadata_values WHERE document_id = ?`).run(documentId);
+        const insertValue = db.prepare(`
+      INSERT INTO document_metadata_values (document_id, key, ordinal, value_type, text_value, number_value, boolean_value)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        for (const [key, value] of Object.entries(extraction.metadata)) {
+            const scalars = Array.isArray(value) ? value : [value];
+            scalars.forEach((scalar, ordinal) => {
+                insertValue.run(documentId, key, ordinal, typeof scalar, typeof scalar === "string" ? scalar : null, typeof scalar === "number" ? scalar : null, typeof scalar === "boolean" ? (scalar ? 1 : 0) : null);
+            });
+        }
+    });
+    replace();
+}
+function isDocumentMetadataCurrent(db, documentId) {
+    const row = db.prepare(`SELECT extraction_version FROM document_metadata WHERE document_id = ?`)
+        .get(documentId);
+    return row?.extraction_version === METADATA_EXTRACTION_VERSION;
+}
+// =============================================================================
+// Queries
+// =============================================================================
+/**
+ * Count active documents without a current, error-free metadata extraction.
+ * These documents are excluded from filtered search until `qmd update` runs.
+ */
+export function countDocumentsPendingMetadata(db) {
+    const row = db.prepare(`
+    SELECT COUNT(*) as c FROM documents d
+    WHERE d.active = 1
+      AND NOT EXISTS (
+        SELECT 1 FROM document_metadata dm
+        WHERE dm.document_id = d.id
+          AND dm.extraction_version = ?
+          AND dm.extraction_error IS NULL
+      )
+  `).get(METADATA_EXTRACTION_VERSION);
+    return row.c;
+}
+/**
+ * Batch-load canonical metadata for a set of result filepaths
+ * (`qmd://collection/path`). One query — never per-result lookups.
+ */
+export function getMetadataByFilepath(db, filepaths) {
+    const metadataByFilepath = new Map();
+    if (filepaths.length === 0)
+        return metadataByFilepath;
+    const placeholders = filepaths.map(() => "?").join(", ");
+    const stmt = db.prepare(`
+    SELECT 'qmd://' || d.collection || '/' || d.path AS filepath, dm.metadata_json
+    FROM documents d
+    JOIN document_metadata dm ON dm.document_id = d.id
+    WHERE d.active = 1
+      AND 'qmd://' || d.collection || '/' || d.path IN (${placeholders})
+  `);
+    const rows = typeof stmt?.all === "function"
+        ? stmt.all(...filepaths)
+        : [];
+    for (const row of rows) {
+        metadataByFilepath.set(row.filepath, parseMetadataJson(row.metadata_json));
+    }
+    return metadataByFilepath;
+}
+/** Parse a stored `metadata_json` column value, tolerating absent rows. */
+export function parseMetadataJson(metadataJson) {
+    if (!metadataJson)
+        return {};
+    try {
+        return JSON.parse(metadataJson);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/metadata.d.ts

@@ -0,0 +1,61 @@
+/**
+ * QMD Metadata - Public metadata types and frontmatter extraction.
+ *
+ * Documents opt into metadata through a namespaced Markdown frontmatter block:
+ *
+ *   ---
+ *   qmd:
+ *     metadata:
+ *       topics:
+ *         - typescript
+ *         - programming
+ *       status: published
+ *   ---
+ *
+ * Extraction is source-agnostic at the persistence boundary: this module
+ * produces a canonical `MetadataExtractionResult`, and future non-frontmatter
+ * sources can produce the same shape without touching storage or filtering.
+ *
+ * The raw document is never modified — frontmatter stays part of the stored,
+ * indexed, chunked, and embedded content.
+ */
+export type MetadataScalar = string | number | boolean;
+export type MetadataScalarArray = readonly string[] | readonly number[] | readonly boolean[];
+export type MetadataValue = MetadataScalar | MetadataScalarArray;
+export type DocumentMetadata = Record<string, MetadataValue>;
+/**
+ * Result of extracting metadata from one document.
+ *
+ * `error` is set when the document opted into `qmd.metadata` but the value was
+ * invalid — the document still indexes normally, but it is excluded from
+ * filtered search until the metadata is corrected and re-indexed.
+ */
+export interface MetadataExtractionResult {
+    metadata: DocumentMetadata;
+    error?: string;
+    extractionVersion: number;
+}
+/**
+ * Bump when extraction or normalization semantics change so existing rows are
+ * re-extracted on the next `qmd update`.
+ */
+export declare const METADATA_EXTRACTION_VERSION = 1;
+/** Defensive limits for metadata from untrusted repositories. */
+export declare const METADATA_LIMITS: {
+    readonly maxFrontmatterBytes: number;
+    readonly maxKeys: 64;
+    readonly maxKeyBytes: 128;
+    readonly maxStringLength: 1024;
+    readonly maxArrayLength: 128;
+    readonly maxYamlAliasCount: 100;
+    readonly maxErrorLength: 200;
+};
+/**
+ * Extract `qmd.metadata` from a document's leading YAML frontmatter.
+ *
+ * Never throws. A document without frontmatter, without a `qmd` namespace, or
+ * with a non-frontmatter extension yields empty metadata with no error.
+ * Invalid frontmatter or invalid metadata yields empty metadata plus a bounded
+ * extraction error.
+ */
+export declare function extractDocumentMetadata(content: string, path: string): MetadataExtractionResult;