@wei840222/qmd 2026.8.28 → 2026.9.6

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### 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.
+
 ### Added
 
 - **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.

package/README.md

@@ -982,7 +982,6 @@ and `deep-search` (→ `query`).
 --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)
---no-hyde          # Disable HyDE in query expansion (only lex and vec expansions)
 -C, --candidate-limit <n>  # Max candidates to rerank (default: 40)
 --full-path        # Emit on-disk filesystem paths instead of qmd:// URIs
                    # (a result whose file has moved or been deleted since

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "7cbc570",
-  "builtAt": "2026-08-28T11:16:06.495Z"
+  "commit": "672da2e",
+  "builtAt": "2026-09-06T06:45:32.394Z"
 }

package/dist/cli/qmd.js

@@ -137,12 +137,16 @@ function getStore() {
     }
     return store;
 }
-function getDoctorStore() {
+function getDoctorStore(options = {}) {
     if (!store) {
         const dbPath = getDbPath();
+        const shouldReconcile = existsSync(dbPath) && options.reconcileConfig !== undefined;
         store = existsSync(dbPath)
-            ? createStore(dbPath, { readOnly: true })
+            ? createStore(dbPath, { readOnly: !shouldReconcile })
             : createStore(":memory:");
+        if (shouldReconcile) {
+            syncConfigToDb(store.db, options.reconcileConfig);
+        }
     }
     return store;
 }
@@ -3916,10 +3920,6 @@ async function runDoctorDeviceChecks(nextSteps) {
     }
 }
 async function showDoctor() {
-    const storeInstance = getDoctorStore();
-    const db = storeInstance.db;
-    const pkg = readPackageJson();
-    const activeModels = resolveModelsForCli();
     let doctorConfig;
     try {
         doctorConfig = loadConfig();
@@ -3928,6 +3928,9 @@ async function showDoctor() {
         // The dedicated index-config check below reports parse errors. Keep the
         // remaining diagnostics available by falling back to DB/default config.
     }
+    const storeInstance = getDoctorStore({ reconcileConfig: doctorConfig });
+    const db = storeInstance.db;
+    const activeModels = resolveModelsForCli();
     const doctorEmbedding = resolveEmbeddingConfig({
         config: doctorConfig,
         dbConfig: readCanonicalEmbeddingConfig(db),
@@ -3938,7 +3941,7 @@ async function showDoctor() {
     const nextSteps = [];
     console.log(`${c.bold}QMD Doctor${c.reset}\n`);
     console.log(`Index: ${getDbPath()}`);
-    console.log(`Runtime: better-sqlite3`);
+    console.log(`Runtime: node:sqlite`);
     try {
         const row = db.prepare(`SELECT sqlite_version() AS version`).get();
         doctorCheck("SQLite runtime", true, row.version);
@@ -3946,8 +3949,7 @@ async function showDoctor() {
     catch (error) {
         doctorCheck("SQLite runtime", false, error instanceof Error ? error.message : String(error));
     }
-    const betterSqliteVersion = pkg.dependencies?.["better-sqlite3"] ?? pkg.devDependencies?.["better-sqlite3"] ?? "not declared";
-    doctorCheck("better-sqlite3 package", true, String(betterSqliteVersion));
+    doctorCheck("node:sqlite", true, process.versions.node);
     try {
         loadSqliteVec(db);
         const row = db.prepare(`SELECT vec_version() AS version`).get();

package/dist/db.d.ts

@@ -1,39 +1,26 @@
 /**
  * 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, type StatementSync } from "node:sqlite";
 export type SQLiteValue = string | number | bigint | Buffer | Uint8Array | Float32Array | null;
 export type SQLiteParams = readonly SQLiteValue[];
-/**
- * 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).
- */
+export type Transaction<TArgs extends unknown[], TResult> = ((...args: TArgs) => TResult) & {
+    deferred: (...args: TArgs) => TResult;
+    immediate: (...args: TArgs) => TResult;
+    exclusive: (...args: TArgs) => TResult;
+};
+/** Synchronous SQLite connection with QMD-compatible transactions. */
+export declare class Database extends DatabaseSync {
+    transaction<TArgs extends unknown[], TResult>(operation: (...args: TArgs) => TResult): Transaction<TArgs, TResult>;
+}
+/** Statement type used throughout QMD. */
+export type Statement<T extends SQLiteParams = SQLiteParams> = StatementSync;
+/** Open a writable QMD database using Node's built-in SQLite runtime. */
 export declare function openDatabase(path: string): Database;
 /** Open an existing database without changing journal mode, schema, or user data. */
 export declare function openReadOnlyDatabase(path: string): Database;
-/**
- * Database and Statement types used throughout QMD.
- */
-export type Database = BetterSqlite3.Database;
-export type Statement<T extends SQLiteParams = SQLiteParams> = BetterSqlite3.Statement<T>;
-/**
- * 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 declare function loadSqliteVec(db: Database): void;

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/store.js

@@ -1208,7 +1208,7 @@ function rebuildFTSForCjkNormalization(db) {
             }
         });
         // Pull bounded batches and finalize each SELECT before starting the insert
-        // transaction. Holding a better-sqlite3 iterator open while beginning a
+        // transaction. Holding an SQLite iterator open while beginning a
         // transaction on the same connection raises "database is busy".
         const selectBatch = db.prepare(`
       SELECT d.id, d.collection, d.path, d.title, content.doc as body
@@ -1532,6 +1532,12 @@ export function setStoreGlobalContext(db, value) {
         db.prepare(`INSERT INTO store_config (key, value) VALUES ('global_context', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(value);
     }
 }
+function writeConfigSyncDiagnostic(db, diagnostic) {
+    db.prepare(`
+    INSERT INTO store_config (key, value) VALUES ('config_sync_diagnostic', ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(JSON.stringify(diagnostic));
+}
 function storeCollectionMatchesConfig(row, collection) {
     return row.path === collection.path
         && row.pattern === (collection.pattern || '**/*.md')
@@ -1556,12 +1562,14 @@ export function syncConfigToDb(db, config) {
             });
             const currentGlobalContext = getStoreGlobalContext(db);
             if (allMatch && currentGlobalContext === config.global_context) {
-                return {
+                const diagnostic = {
                     configHashChanged: false,
                     reconciled: false,
                     collections: { added: [], updated: [], removed: [] },
                     globalContextUpdated: false,
                 };
+                writeConfigSyncDiagnostic(db, diagnostic);
+                return diagnostic;
             }
         }
     }
@@ -2905,7 +2913,7 @@ export async function maybeAdoptLegacyEmbeddingFingerprint(store, model = DEFAUL
             return { checked: true, adopted: 0, reason: `legacy sample differs from current fingerprint (nearest ${nearest.hash_seq}, distance ${nearest.distance.toFixed(6)})` };
         }
         const update = withLazyContentVectorMigration(db, () => db.prepare(`UPDATE content_vectors SET embed_fingerprint = ? WHERE model = ? AND embed_fingerprint = ''`).run(fingerprint, model));
-        return { checked: true, adopted: update.changes, reason: `sample ${expectedHashSeq} matched current fingerprint at distance ${nearest.distance.toFixed(6)}` };
+        return { checked: true, adopted: Number(update.changes), reason: `sample ${expectedHashSeq} matched current fingerprint at distance ${nearest.distance.toFixed(6)}` };
     });
 }
 export function getIndexHealth(db, model = DEFAULT_EMBED_MODEL) {
@@ -2952,7 +2960,7 @@ export function clearCache(db) {
  */
 export function deleteLLMCache(db) {
     const result = db.prepare(`DELETE FROM llm_cache`).run();
-    return result.changes;
+    return Number(result.changes);
 }
 /**
  * Remove inactive document records (active = 0).
@@ -2976,7 +2984,7 @@ export function cleanupOrphanedContent(db) {
     DELETE FROM content
     WHERE hash NOT IN (SELECT DISTINCT hash FROM documents)
   `).run();
-    return result.changes;
+    return Number(result.changes);
 }
 /**
  * Count content hashes that would be unreferenced after inactive documents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wei840222/qmd",
-  "version": "2026.8.28",
+  "version": "2026.9.6",
   "packageManager": "pnpm@11.15.1",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
@@ -66,7 +66,6 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "@node-rs/jieba": "2.0.2",
-    "better-sqlite3": "^13.0.3",
     "fast-glob": "3.3.3",
     "node-llama-cpp": "3.20.0",
     "picomatch": "4.0.5",
@@ -88,7 +87,6 @@
   },
   "devDependencies": {
     "@oxlint/plugins": "1.78.0",
-    "@types/better-sqlite3": "7.6.13",
     "oxlint": "1.78.0",
     "tsx": "4.23.12",
     "vitest": "3.2.7"
@@ -113,7 +111,7 @@
     "typescript": "^5.9.3 || ^6.0.0-0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.16.0"
   },
   "keywords": [
     "markdown",

package/skills/qmd/SKILL.md

@@ -230,8 +230,6 @@ Query types:
 - `vec` — vector semantic search. Best for natural-language concepts.
 - `hyde` — vector search using a hypothetical answer/document passage.
 
-When invoking `query` with a plain `query` string instead of explicit `searches`, you can set `includeHyde: false` (to omit HyDE passage generation) and `expansion: "auto" | "force" | "skip"`.
-
 ## Query craft
 
 Good QMD searches mix three things:

package/skills/qmd/references/query-syntax.md

@@ -30,7 +30,6 @@ newline        = "\n" ;
 
 A query is either a single policy query or a multi-line query document:
 - **`auto` (Default)**: CJK queries and strong lexical matches automatically bypass model expansion. Other plain queries expand into `lex`, `vec`, and `hyde` variants.
-- **`--no-hyde`**: Disables HyDE (hypothetical document) in query expansion, generating only `lex` and `vec` variants (faster, avoids hallucinated passage drift).
 - **`expand:` / `--expand` (`force`)**: Explicitly forces expansion even if bypass heuristics apply.
 - **`lex:` (`skip`)**: Explicitly disables expansion and performs direct BM25 search.
 
@@ -38,9 +37,6 @@ A query is either a single policy query or a multi-line query document:
 # Automatic policy:
 qmd query "how does authentication work"
 
-# Disable HyDE during expansion:
-qmd query --no-hyde "how does authentication work"
-
 # Force expansion:
 qmd query "expand: how does authentication work"
 # or: qmd query --expand "資料庫同步"
@@ -85,8 +81,6 @@ A 50–100 word hypothetical answer passage representing what the target documen
 hyde: The rate limiter uses a sliding window counter algorithm with a 60-second window. When a client exceeds 100 requests per minute, subsequent requests return 429 Too Many Requests.
 ```
 
-When relying on query expansion, HyDE generation can be excluded using `--no-hyde` (CLI) or `"includeHyde": false` (MCP/SDK).
-
 ## Multi-Line Structured Queries
 
 Combine multiple sub-query types for optimal retrieval. The first sub-query receives **2x weight** during Reciprocal Rank Fusion:
@@ -156,9 +150,8 @@ When calling the `qmd` MCP server's `query` tool, provide a structured `searches
 
 ```json
 {
-  "query": "authentication flow",
+  "query": "CAP theorem consistency",
   "expansion": "auto",
-  "includeHyde": false,
   "explain": true,
   "collections": ["docs"]
 }