@wei840222/qmd 2026.9.6 → 2026.9.25

package/CHANGELOG.md

@@ -2,13 +2,27 @@
 
 ## [Unreleased]
 
+## [2026.9.25] - 2026-09-26
+
 ### Changed
 
 - Replace `better-sqlite3` with Node.js built-in `node:sqlite`, preventing SQLite runtime symbol collisions when QMD is embedded alongside other `node:sqlite` consumers. The minimum supported Node.js version is now 22.16.0.
+- Upgraded `@node-rs/jieba` to `2.0.3` and synchronized bundled Traditional Chinese dictionary assets (`zh-dict.txt`) with upstream `sysprog21/zhtw-mcp`.
+- Relocated repository release management skill to `.agents/skills/release`.
 
 ### Added
 
+- Added Oxlint lint fence.
+- Document metadata and metadata filtering. Markdown documents can opt into typed metadata through a namespaced frontmatter block (`qmd.metadata` with strings, numbers, booleans, or flat homogeneous arrays), and every search surface — CLI `search`/`vsearch`/`query` via `--filter <json>`, the SDK's `filter` option on `search()`/`searchLex()`/`searchVector()`, the MCP `query` tool, and HTTP `POST /query` and `/search` — accepts one shared recursive filter AST discriminated by `operator`: `and`/`or`/`not` logical groups, `eq`/`ne`/`gt`/`gte`/`lt`/`lte` comparisons, `in`/`nin`/`all` membership, and `exists` presence. Every returned result satisfies the filter (applied before RRF fusion and reranking); like collection filtering, highly selective filters remain best-effort for top-K completeness. Frontmatter stays ordinary searchable content — no chunking, embedding, snippet, or line-number changes — and documents without `qmd.metadata` behave exactly as before. JSON/SDK/MCP/HTTP results now include each document's indexed metadata, and `qmd status` reports how many documents still need metadata extraction (a normal `qmd update` backfills existing indexes).
 - **Disable HyDE Expansion Control**: Added `--no-hyde` CLI option for `qmd query` and `qmd vsearch`, `includeHyde` parameter to SDK (`store.search`, `store.expandQuery`) and MCP `query` tool, allowing users to disable generating hypothetical document embeddings during query expansion.
+- Added `typesafe-ai` skill to `.agents/skills/typesafe-ai`.
+
+### Fixed
+
+- Embedding generation and legacy fingerprint adoption now tokenize documents
+  with the store-selected embedding model instead of the global default. This
+  keeps chunk boundaries aligned with the model that creates and verifies the
+  stored vectors without initializing an unrelated provider.
 
 ## [2026.8.23-1] - 2026-08-23
 

package/README.md

@@ -132,7 +132,7 @@ runs in a container and a liveness probe connects from a non-loopback address.
 
 The HTTP server exposes two endpoints:
 - `POST /mcp` — MCP Streamable HTTP (JSON responses, stateless)
-- `POST /query` (alias `/search`) — structured search without the MCP protocol
+- `POST /query` (alias `/search`) — structured search without the MCP protocol. Accepts the same optional `filter` object as the `query` tool (invalid filters return `400`); see [Metadata Filtering](#metadata-filtering)
 - `GET /health` — liveness check with uptime
 
 
@@ -170,8 +170,10 @@ Point any MCP client at `http://localhost:8181/mcp` to connect.
 | `query` | `searches` | array | Typed sub-queries (`lex`/`vec`/`hyde`), 1–10. Mutually exclusive with `query`; exactly one is required. First gets 2x weight. |
 | `query` | `expansion` | string | Plain-query policy: `auto` (default), `force`, or `skip`. Ignored when `searches` is used. |
 | `query` | `collections` | string[] | Filter by collection names (OR). **Array only** — singular `collection` is silently ignored. |
+| `query` | `filter` | object | Metadata filter (recursive `operator`-discriminated JSON AST; see [Metadata Filtering](#metadata-filtering)) |
 | `query` | `expansionContext` | string | Additional context used only to generate `lex` / `vec` / `hyde` query expansions. |
 | `query` | `rerankContext` | string | Additional context used only for reranking and snippet/chunk selection. |
+| `query` | `intent` | string | Disambiguation context (alias for expansionContext & rerankContext; does not search on its own) |
 | `query` | `limit` | number | Max results (default 10) |
 | `query` | `minScore` | number | Minimum relevance 0–1 (default 0) |
 | `query` | `candidateLimit` | number | Max candidates to rerank (default 40) |
@@ -279,6 +281,20 @@ const results3 = await store.search({
 
 // Skip reranking for faster results
 const fast = await store.search({ query: "auth", rerank: false })
+
+// Metadata filter — every returned result satisfies it (also available on
+// searchLex() and searchVector()); results expose indexed metadata via
+// r.metadata. See "Metadata Filtering" for the full grammar.
+const published = await store.search({
+  query: "authentication flow",
+  filter: {
+    operator: "and",
+    operands: [
+      { key: "topics", operator: "all", value: ["typescript"] },
+      { key: "status", operator: "ne", value: "draft" },
+    ],
+  },
+})
 ```
 
 For simple queries, explicit `force` or `skip` overrides `auto`. Under `auto`, CJK
@@ -979,6 +995,7 @@ and `deep-search` (→ `query`).
 --full             # Show full document content
 --line-numbers     # Add line numbers to output
 --explain          # Include retrieval score traces (query, JSON/CLI output)
+--filter <json>    # Metadata filter (recursive JSON AST; see Metadata Filtering)
 --index <name>     # Use named index
 --intent "<text>"  # Legacy CLI alias for rerank context (e.g. "web page load times")
 --no-rerank        # Skip LLM reranking (RRF scores only; faster on CPU)
@@ -1022,6 +1039,72 @@ explicitly with `-c`.
 > lexical and vector candidate cutoff. Matching candidates from the selected
 > collections are then ranked together.
 
+### Metadata Filtering
+
+Documents can opt into typed metadata through a namespaced frontmatter block. A document without `qmd.metadata` behaves exactly as before, and the frontmatter stays ordinary searchable content (no chunking, embedding, or line-number changes):
+
+```markdown
+---
+qmd:
+  metadata:
+    topics:
+      - typescript
+      - programming
+    status: published
+    priority: 3
+    reviewed: true
+---
+
+# Document body starts here
+```
+
+Supported values are strings, numbers, booleans, and flat homogeneous arrays of one of those. Nested objects, nulls, empty arrays, and mixed-type arrays are rejected (the document still indexes; it is excluded from filtered search until corrected). Metadata keys are user-defined data — `tags`, `topics`, and `labels` are all ordinary keys with no special semantics.
+
+Every search surface (CLI, SDK, MCP, HTTP) accepts the same recursive filter, a JSON AST discriminated by `operator`:
+
+```sh
+# One condition
+qmd search "authentication" \
+  --filter '{"key":"status","operator":"eq","value":"published"}'
+
+# Composed conditions — works with search, vsearch, and query
+qmd query "dependency injection" --filter '{
+  "operator": "and",
+  "operands": [
+    { "key": "topics", "operator": "all", "value": ["typescript", "programming"] },
+    { "key": "status", "operator": "nin", "value": ["draft", "archived"] },
+    { "operator": "or", "operands": [
+      { "key": "priority", "operator": "gte", "value": 3 },
+      { "key": "reviewed", "operator": "eq", "value": true }
+    ] },
+    { "operator": "not", "operand": { "key": "audience", "operator": "eq", "value": "internal" } }
+  ]
+}'
+```
+
+| Node | Shape |
+|------|-------|
+| Logical group | `{ "operator": "and" \| "or", "operands": […] }` |
+| Negation | `{ "operator": "not", "operand": {…} }` |
+| Comparison | `{ "key", "operator": "eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte", "value" }` |
+| Membership | `{ "key", "operator": "in" \| "nin" \| "all", "value": […] }` |
+| Presence | `{ "key", "operator": "exists", "value": true \| false }` |
+
+Semantics:
+
+- Matching is typed and exact — no string/number/boolean coercion, and a type mismatch never matches (including `ne` and `nin`).
+- Array-valued metadata is a set: a condition matches when any element satisfies it, `all` requires every filter value to be present.
+- Missing keys do not match `ne`/`nin`; combine with `{ "operator": "exists", "value": false }` in an `or` group to include them.
+- Multiple conditions require an explicit `and` group — there is no implicit AND, and no `$`-prefixed shorthand.
+
+Guarantees and limits:
+
+- Every returned result satisfies the filter, before RRF fusion and reranking.
+- Like collection filtering, highly selective filters are best-effort for top-K completeness: backends over-fetch and post-filter, so a very selective filter can return fewer than `limit` results.
+- Filtered search only considers documents whose metadata has been extracted (run `qmd update` after upgrading; `qmd status` shows the pending count).
+
+JSON output (`--format json`), the SDK, MCP structured results, and the HTTP endpoints include each result's indexed metadata.
+
 ### Output Format
 
 Default output is colorized CLI format (respects `NO_COLOR` env).

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "672da2e",
-  "builtAt": "2026-09-06T06:45:32.394Z"
+  "commit": "5e88f52",
+  "builtAt": "2026-09-25T22:32:39.272Z"
 }

package/dist/cli/qmd.js

@@ -10,6 +10,8 @@ import { parseArgs } from "util";
 import { readFileSync, readdirSync, realpathSync, statSync, existsSync, unlinkSync, writeFileSync, openSync, closeSync, mkdirSync, lstatSync, rmSync, symlinkSync, readlinkSync, copyFileSync } from "fs";
 import { createInterface } from "readline/promises";
 import { getPwd, getRealPath, isPathInsideDir, homedir, resolve, enableProductionMode, searchFTS, extractSnippet, getContextForFile, getContextForPath, listCollections, findSimilarFiles, findDocument, resolveCommaListName, matchFilesByGlob, getHashesNeedingEmbedding, clearAllEmbeddings, insertEmbedding, getStatus, hashContent, extractTitle, formatDocForEmbedding, getEmbeddingFingerprint, chunkDocumentByTokens, clearCache, getCacheKey, getCachedResult, setCachedResult, getIndexHealth, parseVirtualPath, buildVirtualPath, isVirtualPath, isDocid, resolveVirtualPath, toVirtualPath, insertContent, insertDocument, insertDocumentWithContent, findActiveDocument, findOrMigrateLegacyDocument, updateDocumentTitle, updateDocument, updateDocumentWithContent, deactivateDocument, getActiveDocumentPaths, cleanupOrphanedContent, countOrphanedVectors, previewCleanup, runCleanup, getCollectionsWithoutContext, getTopLevelPathsWithoutContext, handelize, escapeLikePattern, hybridQuery, vectorSearchQuery, structuredSearch, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_EMBED_MAX_BATCH_BYTES, DEFAULT_EMBED_MAX_DOCS_PER_BATCH, DEFAULT_RERANK_MODEL, DEFAULT_QUERY_MODEL, DEFAULT_GLOB, splitGlobMask, DEFAULT_MULTI_GET_MAX_BYTES, createStore, getDefaultDbPath, reindexCollection, generateEmbeddings, getPendingEmbeddingDocsReadOnly, syncConfigToDb, } from "../store.js";
+import { syncDocumentMetadata, countDocumentsPendingMetadata } from "../metadata-store.js";
+import { parseMetadataFilter } from "../metadata-filter.js";
 import { disposeDefaultLlamaCpp, getDefaultLlamaCpp, setDefaultLlamaCpp, LlamaCpp, withLLMSession, pullModels, DEFAULT_MODEL_CACHE_DIR, resolveEmbedModel, resolveGenerateModel, resolveRerankModel, resolveModels, inspectGgufFile, isDarwinMetalMitigationActive } from "../llm.js";
 import { rebuildCjkLexicalIndex } from "../search/cjk-index.js";
 import { RemoteLLM } from "../remote-llm.js";
@@ -219,11 +221,16 @@ function mcpDaemonPaths() {
 }
 function setIndexName(name) {
     let normalizedName = name;
-    // Normalize relative paths to prevent malformed database paths
-    if (name && name.includes('/')) {
-        const absolutePath = pathResolve(process.cwd(), name);
-        // Replace path separators with underscores to create a valid filename
-        normalizedName = absolutePath.replace(/\//g, '_').replace(/^_/, '');
+    // Normalize relative paths to prevent malformed database paths. Windows
+    // absolute paths (C:\..., \\server\share) are already absolute -- skip
+    // pathResolve() for those and sanitize `:` and `\` alongside `/`.
+    if (name) {
+        const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(name) || /^\\/.test(name);
+        if (isWindowsAbsolute || /[\\/]/.test(name)) {
+            const absolutePath = isWindowsAbsolute ? name : pathResolve(process.cwd(), name);
+            // Replace path separators with underscores to create a valid filename
+            normalizedName = absolutePath.replace(/[:\\/]+/g, '_').replace(/^_+/, '');
+        }
     }
     currentIndexName = normalizedName || "index";
     storeDbPathOverride = normalizedName ? getDefaultDbPath(normalizedName) : undefined;
@@ -546,6 +553,10 @@ async function showStatus() {
     if (needsEmbedding > 0) {
         console.log(`  ${c.yellow}Pending:  ${needsEmbedding} need embedding${c.reset} (run 'qmd embed')`);
     }
+    const pendingMetadata = countDocumentsPendingMetadata(db);
+    if (pendingMetadata > 0) {
+        console.log(`  ${c.yellow}Metadata: ${pendingMetadata} need extraction${c.reset} (run 'qmd update'; excluded from --filter searches)`);
+    }
     if (mostRecent.latest) {
         const lastUpdate = new Date(mostRecent.latest);
         console.log(`  Updated:  ${formatTimeAgo(lastUpdate)}`);
@@ -954,6 +965,7 @@ async function updateCollections() {
         progress.clear();
         console.log(`\nIndexed: ${result.indexed} new, ${result.updated} updated, ${result.unchanged} unchanged, ${result.removed} removed`);
         reportSkippedReads(result.skippedFiles);
+        reportMetadataErrors(result.metadataErrors);
         if (result.orphanedCleaned > 0) {
             console.log(`Cleaned up ${result.orphanedCleaned} orphaned content hash(es)`);
         }
@@ -1858,7 +1870,7 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         console.log("No files found matching pattern.");
         // Continue so the deactivation pass can mark previously indexed docs as inactive.
     }
-    let indexed = 0, updated = 0, unchanged = 0, processed = 0;
+    let indexed = 0, updated = 0, unchanged = 0, processed = 0, metadataErrors = 0;
     const skippedFiles = [];
     const seenPaths = new Set();
     // Literal paths of every file in this scan. Passed to the legacy-path
@@ -1896,8 +1908,12 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         const title = extractTitle(content, relativeFile);
         // Check if document exists (also migrates legacy lowercase paths)
         const existing = findOrMigrateLegacyDocument(db, collectionName, path, livePaths);
+        let documentId;
+        let contentChanged = true;
         if (existing) {
+            documentId = existing.id;
             if (existing.hash === hash) {
+                contentChanged = false;
                 // Hash unchanged, but check if title needs updating
                 if (existing.title !== title) {
                     updateDocumentTitle(db, existing.id, title, now);
@@ -1918,8 +1934,12 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
             // New document - insert content and document
             indexed++;
             const stat = statSync(filepath);
-            insertDocumentWithContent(db, hash, content, now, collectionName, path, title, stat ? new Date(stat.birthtime).toISOString() : now, stat ? new Date(stat.mtime).toISOString() : now);
+            documentId = insertDocumentWithContent(db, hash, content, now, collectionName, path, title, stat ? new Date(stat.birthtime).toISOString() : now, stat ? new Date(stat.mtime).toISOString() : now);
         }
+        // Unchanged content still backfills missing or stale extraction state.
+        const extraction = syncDocumentMetadata(db, documentId, content, path, contentChanged ? undefined : { onlyIfStale: true });
+        if (extraction?.error)
+            metadataErrors++;
         processed++;
         progress.set((processed / total) * 100);
         const elapsed = (Date.now() - startTime) / 1000;
@@ -1945,6 +1965,7 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
     progress.clear();
     console.log(`\nIndexed: ${indexed} new, ${updated} updated, ${unchanged} unchanged, ${removed} removed`);
     reportSkippedReads(skippedFiles);
+    reportMetadataErrors(metadataErrors);
     if (orphanedContent > 0) {
         console.log(`Cleaned up ${orphanedContent} orphaned content hash(es)`);
     }
@@ -1962,6 +1983,11 @@ function fsErrorCode(err) {
     }
     return "ERROR";
 }
+function reportMetadataErrors(metadataErrors) {
+    if (metadataErrors === 0)
+        return;
+    console.warn(`⚠ ${metadataErrors} file(s) have invalid qmd.metadata frontmatter and are excluded from filtered search`);
+}
 function reportSkippedReads(skippedFiles) {
     if (skippedFiles.length === 0)
         return;
@@ -2375,6 +2401,7 @@ function outputResults(results, query, opts) {
                 line: snippetInfo.line,
                 title: row.title,
                 ...(row.context && { context: row.context }),
+                ...(row.metadata && Object.keys(row.metadata).length > 0 && { metadata: row.metadata }),
                 ...(body && { body }),
                 ...(snippet && { snippet }),
                 ...(opts.explain && row.explain && { explain: row.explain }),
@@ -2624,14 +2651,46 @@ export function parseStructuredQuery(query) {
     }
     return typed.length > 0 ? { searches: typed, intent } : null;
 }
+// Parse and validate a --filter JSON string; exits with an actionable
+// message on malformed JSON or an invalid filter AST.
+function parseCliMetadataFilter(rawFilter) {
+    if (rawFilter === undefined)
+        return undefined;
+    let filterJson;
+    try {
+        filterJson = JSON.parse(String(rawFilter));
+    }
+    catch (err) {
+        console.error(`Invalid --filter JSON: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`Example: --filter '{"key":"status","operator":"eq","value":"published"}'`);
+        process.exit(1);
+    }
+    try {
+        return parseMetadataFilter(filterJson);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+// Filtered search excludes documents without current metadata extraction;
+// tell the user when that makes results incomplete.
+function warnPendingMetadata(db) {
+    const pendingMetadata = countDocumentsPendingMetadata(db);
+    if (pendingMetadata === 0)
+        return;
+    process.stderr.write(`${c.yellow}Warning: ${pendingMetadata} document(s) lack current metadata extraction and are excluded from filtered results. Run 'qmd update'.${c.reset}\n`);
+}
 function search(query, opts) {
     const db = getDb();
     // Validate collection filter (supports multiple -c flags)
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
+    if (opts.filter)
+        warnPendingMetadata(db);
     // Use large limit for --all, otherwise fetch more than needed and let outputResults filter
     const fetchLimit = opts.all ? 100000 : Math.max(50, opts.limit * 2);
-    const results = searchFTS(db, query, fetchLimit, collectionNames);
+    const results = searchFTS(db, query, fetchLimit, collectionSearchFilter(collectionNames), opts.filter);
     // Add context to results
     const resultsWithContext = results.map(r => ({
         file: r.filepath,
@@ -2642,6 +2701,7 @@ function search(query, opts) {
         context: getContextForFile(db, r.filepath),
         hash: r.hash,
         docid: r.docid,
+        metadata: r.metadata,
     }));
     closeDb();
     if (resultsWithContext.length === 0) {
@@ -2672,9 +2732,12 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
     checkIndexHealth(store.db);
+    if (opts.filter)
+        warnPendingMetadata(store.db);
     await withLLMSession(async () => {
         const results = await vectorSearchQuery(store, query, {
-            collection: collectionNames,
+            collection: collectionSearchFilter(collectionNames),
+            filter: opts.filter,
             limit: opts.all ? 500 : (opts.limit || 10),
             minScore: opts.minScore || 0.3,
             expansionContext: opts.intent,
@@ -2699,6 +2762,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
             score: r.score,
             context: r.context,
             docid: r.docid,
+            metadata: r.metadata,
         })), query, { ...opts, limit: results.length });
     }, { maxDuration: 10 * 60 * 1000, name: 'vectorSearch' });
 }
@@ -2708,6 +2772,8 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
     checkIndexHealth(store.db);
+    if (opts.filter)
+        warnPendingMetadata(store.db);
     // Check for structured query syntax (lex:/vec:/hyde:/intent: prefixes)
     const parsed = parseStructuredQuery(query);
     // Intent can come from --intent flag or from intent: line in query document
@@ -2735,6 +2801,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             process.stderr.write(`${c.dim}└─ Searching...${c.reset}\n`);
             results = await structuredSearch(store, structuredQueries, {
                 collections: collectionNames.length > 0 ? collectionNames : undefined,
+                filter: opts.filter,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
@@ -2764,6 +2831,8 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             // Standard hybrid query with automatic expansion
             results = await hybridQuery(store, query, {
                 collections: collectionNames.length > 0 ? collectionNames : undefined,
+                collection: collectionSearchFilter(collectionNames),
+                filter: opts.filter,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
@@ -2830,6 +2899,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             score: r.score,
             context: r.context,
             docid: r.docid,
+            metadata: r.metadata,
             explain: r.explain,
         })), displayQuery, { ...opts, limit: results.length });
     }, { maxDuration: 10 * 60 * 1000, name: 'querySearch' });
@@ -2866,6 +2936,7 @@ function parseCLI() {
             json: { type: "boolean" },
             explain: { type: "boolean" },
             collection: { type: "string", short: "c", multiple: true }, // Filter by collection(s)
+            filter: { type: "string" }, // Metadata filter (JSON AST) for search/vsearch/query
             // Collection options
             name: { type: "string" }, // collection name
             mask: { type: "string" }, // glob pattern
@@ -3462,6 +3533,8 @@ function showHelp() {
     console.log("  --explain                  - Include retrieval score traces (query, CLI/--format json)");
     console.log("  --format <kind>            - Output format: cli (default) | json | csv | md | xml | files");
     console.log("  -c, --collection <name>    - Filter by one or more collections");
+    console.log("  --filter <json>            - Metadata filter (recursive JSON AST; search/vsearch/query)");
+    console.log("                                e.g. '{\"key\":\"status\",\"operator\":\"eq\",\"value\":\"published\"}'");
     console.log("");
     console.log("Embed/query options:");
     console.log("  --chunk-strategy <auto|regex> - Chunking mode (default: regex; auto uses AST for code files)");
@@ -4532,6 +4605,7 @@ if (isMain) {
                 console.error("Usage: qmd search [options] <query>");
                 process.exit(1);
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             search(cli.query, cli.opts);
             break;
         case "vsearch":
@@ -4544,6 +4618,7 @@ if (isMain) {
             if (!cli.values["min-score"]) {
                 cli.opts.minScore = 0.3;
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             await resolveLocalConfigTrust();
             await vectorSearch(cli.query, cli.opts);
             break;
@@ -4553,6 +4628,7 @@ if (isMain) {
                 console.error("Usage: qmd query [options] <query>");
                 process.exit(1);
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             await resolveLocalConfigTrust();
             await querySearch(cli.query, cli.opts);
             break;

package/dist/collections.js

@@ -41,11 +41,16 @@ export function setConfigSource(source) {
  * Config file will be ~/.config/qmd/{indexName}.yml
  */
 export function setConfigIndexName(name) {
-    // Resolve relative paths to absolute paths and sanitize for use as filename
-    if (name.includes('/')) {
-        const absolutePath = resolve(process.cwd(), name);
+    // Resolve relative paths to absolute paths and sanitize for use as filename.
+    // Windows absolute paths (C:\..., \\server\share) are already absolute --
+    // skip resolve() for those (POSIX path.resolve doesn't recognize a drive
+    // letter as absolute and would wrongly prefix it with cwd) and sanitize
+    // `:` and `\` alongside `/` so the derived filename is valid on Windows.
+    const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(name) || /^\\/.test(name);
+    if (isWindowsAbsolute || /[\\/]/.test(name)) {
+        const absolutePath = isWindowsAbsolute ? name : resolve(process.cwd(), name);
         // Replace path separators with underscores to create a valid filename
-        currentIndexName = absolutePath.replace(/\//g, '_').replace(/^_/, '');
+        currentIndexName = absolutePath.replace(/[:\\/]+/g, '_').replace(/^_+/, '');
     }
     else {
         currentIndexName = name;

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