mindforge-cc 11.9.1 → 11.9.3

package/bin/memory/vector-hub.js

@@ -8,6 +8,136 @@
 const crypto = require('crypto');
 const path = require('path');
 const fs = require('fs');
+const { withFileLock } = require('../utils/file-lock');
+
+// ── FTS retrieval (FTS-01) ───────────────────────────────────────────────────
+// A MATCH argument is an FTS *query expression*, not a literal. Wrapping the
+// whole user query in double quotes made it ONE phrase, so a multi-word query
+// only matched documents holding those exact ADJACENT words. Default behaviour
+// is now search-box semantics: tokenise, drop FTS operator keywords, quote each
+// term (which neutralises every FTS metacharacter) and OR the results together.
+// Callers that genuinely need adjacency pass { phrase: true }.
+//
+// The OR alone is NOT the fix. FTS4 has no ranker, so the first `limit` rows
+// are docid order over documents containing ANY term ("how", "the", "work") and
+// measured mean recall@10 stays 0.0000. Ranking is what recovers it: tf-idf
+// scored in JS from FTS4's matchinfo('pcnx') blob. Measured via
+// `npm run eval:retrieval` on the repo doc corpus (517 docs, 10 golden
+// queries): recall@10 0.0000 -> 0.6417, nDCG@10 0.0000 -> 0.5698.
+const FTS_OPERATOR_WORDS = new Set(['and', 'or', 'not', 'near']);
+const FTS_MAX_TERMS = 32;
+const FTS_DEFAULT_LIMIT = 10;
+const FTS_MAX_LIMIT = 100;
+// Candidate rows pulled PER TERM before ranking. Bounds the work done for a very
+// common term; see _rankedFtsSearch for why the pool is per term and not per
+// query.
+const FTS_RANK_POOL = 2000;
+// BM25-style term-frequency saturation. matchinfo('pcnx') carries no document
+// length, so a raw term count would systematically favour long documents;
+// saturating tf at tf/(tf + k) keeps a repeated term ranked above a single
+// occurrence without letting file size dominate the score.
+const FTS_TF_SATURATION = 1.2;
+// The only tables a ranked search may touch, with each FTS table's per-column
+// relevance weights in DECLARED column order. _rankedFtsSearch interpolates
+// these identifiers into SQL (SQLite cannot bind an identifier), so they are
+// allowlisted here rather than trusted — no caller string can reach that SQL.
+// A hit in the identifier column is a title match and is worth more than one in
+// the body; traces_search declares `id` notindexed so it can never produce a hit
+// at all, and weight 0 documents that rather than implying otherwise.
+const FTS_SEARCH_TABLES = {
+  traces: { ftsTable: 'traces_search', columnWeights: [0, 1, 1, 1] }, // id, trace_id, content, agent
+  knowledge: { ftsTable: 'knowledge_search', columnWeights: [3, 1, 1] }, // id, content, tags
+};
+
+/**
+ * Tokenise a raw user query into individual FTS4 MATCH expressions.
+ * @param {string} rawQuery - MUST be a string; anything else is a caller bug
+ * @param {{phrase?: boolean}} [opts] - phrase:true yields a single
+ *   exact-adjacency phrase expression instead of one expression per term
+ * @returns {string[]} MATCH expressions; empty when the query holds no term
+ * @throws {TypeError} when rawQuery is not a string
+ */
+function buildFtsTerms(rawQuery, opts = {}) {
+  // Reject a non-string LOUDLY. Stringifying would turn an accidentally-passed
+  // options object into "[object Object]" and silently search for that literal —
+  // a wrong answer that looks like a working search. bin/engine/
+  // remediation-engine.js did exactly that. Failing at the boundary is honest.
+  if (typeof rawQuery !== 'string') {
+    const got = rawQuery === null ? 'null' : typeof rawQuery;
+    throw new TypeError(`[VectorHub] search query must be a string, received ${got}`);
+  }
+  if (opts.phrase) {
+    // FTS query syntax has no escape for a double quote inside a phrase, so
+    // strip them rather than emit an unparseable expression.
+    const phrase = rawQuery.replace(/"/g, ' ').trim();
+    return phrase ? [`"${phrase}"`] : [];
+  }
+  const terms = [];
+  const seen = new Set();
+  // Split on every character that is not a letter, digit or underscore: the
+  // resulting tokens cannot contain an FTS metacharacter, so quoting is total.
+  for (const token of rawQuery.split(/[^\p{L}\p{N}_]+/u)) {
+    if (!token) continue;
+    const lower = token.toLowerCase();
+    if (FTS_OPERATOR_WORDS.has(lower) || seen.has(lower)) continue;
+    seen.add(lower);
+    terms.push(`"${token}"`);
+    if (terms.length >= FTS_MAX_TERMS) break;
+  }
+  return terms;
+}
+
+/**
+ * Clamp a caller-supplied row limit into a sane bounded integer.
+ * @param {*} limit
+ * @returns {number} an integer in [1, FTS_MAX_LIMIT]
+ */
+function clampFtsLimit(limit) {
+  const n = parseInt(limit, 10);
+  if (!Number.isFinite(n) || n < 1) return FTS_DEFAULT_LIMIT;
+  return Math.min(n, FTS_MAX_LIMIT);
+}
+
+/**
+ * Score one FTS4 matchinfo('pcnx') blob as a weighted tf-idf sum over every
+ * phrase/column pair.
+ *
+ * Blob layout (little-endian uint32): [p, c, n, then 3 values per (phrase,
+ * column) pair — hits in THIS row, hits in ALL rows, number of documents with at
+ * least one hit]. tf is saturated (see FTS_TF_SATURATION) because 'pcnx' carries
+ * no document length to normalise by; idf is the BM25 form clamped at 0, so a
+ * term present in nearly every document can never drive a score negative.
+ * @param {Uint8Array|Buffer|null} blob - value of matchinfo(<table>, 'pcnx')
+ * @param {number[]} [columnWeights] - per-column multipliers in declared column
+ *   order; missing entries default to 1
+ * @returns {number} non-negative relevance score; 0 when the blob is unusable
+ */
+function scoreMatchInfo(blob, columnWeights) {
+  if (!blob || typeof blob.length !== 'number' || blob.length < 12) return 0;
+  const buf = Buffer.from(blob);
+  const u32 = (i) => buf.readUInt32LE(i * 4);
+  const phrases = u32(0);
+  const columns = u32(1);
+  const totalRows = u32(2);
+  if (!phrases || !columns) return 0;
+  let score = 0;
+  for (let p = 0; p < phrases; p++) {
+    for (let c = 0; c < columns; c++) {
+      const base = 3 + 3 * (p * columns + c);
+      // Truncated blob: return what was scored rather than read past the end.
+      if ((base + 3) * 4 > buf.length) return score;
+      const hitsThisRow = u32(base);
+      if (!hitsThisRow) continue;
+      const weight = (columnWeights && columnWeights[c] !== undefined) ? columnWeights[c] : 1;
+      if (weight === 0) continue;
+      const docsWithHits = u32(base + 2);
+      const tf = hitsThisRow / (hitsThisRow + FTS_TF_SATURATION);
+      const idf = Math.max(0, Math.log((totalRows - docsWithHits + 0.5) / (docsWithHits + 0.5)));
+      score += weight * tf * idf;
+    }
+  }
+  return score;
+}
 
 /**
  * VectorHub — Unified Persistence Layer
@@ -38,6 +168,9 @@ class VectorHub {
     // deliberately bias toward flushing.
     this._pendingSaves = 0;
     this._exitGuardInstalled = false;
+    // null until a file is loaded or written. null means "no expectation", so a first write into a
+    // fresh directory is never treated as a conflict.
+    this._diskFingerprint = null;
   }
 
   _installExitGuard() {
@@ -45,10 +178,59 @@ class VectorHub {
     this._exitGuardInstalled = true;
     // 'exit' handlers can only run synchronous code — saveSync() fits exactly.
     process.once('exit', () => {
-      if (this._db && this._pendingSaves > 0) this.saveSync();
+      if (!this._db) return;
+      // _pendingSaves === 0 means every scheduled save already ran commitDb, which consumes
+      // its tmp file by renaming it. So there is nothing outstanding and the in-memory DB is
+      // durable — the reap below is safe without a further write.
+      const durable = this._pendingSaves > 0 ? this.saveSync() : true;
+      if (durable) this._reapAbandonedExport();
     });
   }
 
+  /**
+   * Delete THIS process's abandoned tmp export.
+   *
+   * THE LEAK. save() is a two-step chain: writeTmpDurable() writes and fsyncs
+   * `<db>.tmp.<pid>.async`, then commitDb() renames it into place. A 'exit' handler can only
+   * run synchronous code, so a process that exits with a save in flight abandons the pending
+   * .then() — the microtask never runs, commitDb never renames, and the tmp file stays on disk
+   * forever. Nothing anywhere deleted it. Measured in this repository: 176 orphaned
+   * `celestial.db.tmp.<pid>.async` files totalling 1.8 GB, against a live database of 10.6 MB.
+   * Each orphan is a complete copy of the database, so the directory grew by ~11 MB per exit.
+   *
+   * Reproduced with a control arm: three runs that call process.exit() without close() leave
+   * three orphans, one per pid; three runs that await close() leave zero. Orphan size records
+   * how far the chain got — 0 bytes if the process died inside fs.open, a full export if the
+   * write landed and only the rename was lost.
+   *
+   * The trigger is ordinary, not exotic. nexus-tracer.js is the framework-wide tracing
+   * singleton, so any command that traces and then exits hits this window;
+   * bin/migrations/v9-unified-memory.js calls process.exit() and never calls close() at all.
+   *
+   * WHY THIS IS SAFE, AND WHY IT IS GATED. An earlier snapshot from the SAME process is a
+   * subset of what saveSync() just exported: saveSync() serialises the entire current
+   * in-memory database, which already contains every row the abandoned export held. So once
+   * persistence is confirmed the orphan is provably redundant.
+   *
+   * It is confirmed, not assumed. When saveSync() fails — commitDb throws, or the conflict
+   * sidecar could not be written — the abandoned export may be the only copy of those rows on
+   * disk, and deleting it would be exactly the silent data destruction commitDb refuses to
+   * commit. In that case the caller does NOT reap, and the file is deliberately left behind for
+   * a human. Accumulating a file on a failed write is the correct trade against destroying the
+   * last copy of it. Measured: zero `.sync` orphans exist in this repository, so that path does
+   * not fire in practice — the accumulation was entirely the async one.
+   *
+   * Both suffixes are swept because saveSync()'s own tmp leaks by the same argument if
+   * commitDb throws after the write; that arm is currently unobserved but not impossible.
+   */
+  _reapAbandonedExport() {
+    for (const suffix of ['async', 'sync']) {
+      try {
+        fs.unlinkSync(`${this.dbPath}.tmp.${process.pid}.${suffix}`);
+      } catch { /* not present — the normal case, since commitDb usually consumes it */ }
+    }
+  }
+
   _ensureDir() {
     const dir = path.dirname(this.dbPath);
     if (!fs.existsSync(dir)) {
@@ -91,6 +273,9 @@ class VectorHub {
     if (fs.existsSync(this.dbPath)) {
       const buffer = fs.readFileSync(this.dbPath);
       this._db = new SQL.Database(buffer);
+      // What the file looked like when this process took its copy. Every later write compares
+      // against it, so a rewrite by another process is detected instead of silently clobbered.
+      this._diskFingerprint = dbFingerprint(this.dbPath);
     } else {
       this._db = new SQL.Database();
     }
@@ -203,10 +388,22 @@ class VectorHub {
 
     // ── FTS4 Virtual Tables (FTS4 is available in all sql.js builds) ────────
 
-    this._db.run(`
-      CREATE VIRTUAL TABLE IF NOT EXISTS traces_search
-      USING fts4(trace_id, content, agent, tokenize=porter)
-    `);
+    // FTS-01: traces_search must be keyed on the traces PRIMARY KEY (id), not
+    // trace_id. With a trace_id key every new span in a trace DELETEd its
+    // siblings' index rows, so only the last span per trace stayed searchable
+    // (live DB: 5,082 content-bearing traces, 2,827 index rows, 2,255 = 44.4%
+    // unsearchable). CREATE VIRTUAL TABLE IF NOT EXISTS cannot add a column to a
+    // database created before this fix, so detect the old signature and rebuild.
+    // The index is 100% derivable from `traces`, so the rebuild is lossless.
+    const ftsMigration = this._ensureTracesSearchSchema();
+    // Never let the rebuild be silent: it DROPS and recreates the index table, and a
+    // parity shortfall means rows silently stopped being searchable. Both are reported.
+    if (ftsMigration && ftsMigration.migrated && ftsMigration.expected > 0) {
+      console.log(`[VectorHub] traces_search migrated to the id-keyed schema; rebuilt ${ftsMigration.indexed}/${ftsMigration.expected} rows`);
+    }
+    if (ftsMigration && ftsMigration.migrated && ftsMigration.indexed !== ftsMigration.expected) {
+      console.warn(`[VectorHub] traces_search parity BROKEN after rebuild: indexed=${ftsMigration.indexed} expected=${ftsMigration.expected}`);
+    }
 
     this._db.run(`
       CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_search
@@ -228,6 +425,120 @@ class VectorHub {
     console.log(`[VectorHub] Initialized WASM SQLite persistence at ${this.dbPath}`);
   }
 
+  /**
+   * Create traces_search with the correct (id-keyed) schema, migrating and
+   * repopulating an older trace_id-keyed table in place when one exists.
+   * Idempotent — the sqlite_master signature check makes a re-run a no-op.
+   * `id` is declared notindexed: it is an opaque UUID, contributes no useful
+   * search term, and leaving it unindexed keeps MATCH semantics identical to the
+   * pre-fix table (content, agent and trace_id all remain searchable).
+   * @returns {{migrated: boolean, indexed: number|null, expected: number|null}}
+   */
+  _ensureTracesSearchSchema() {
+    const existing = this.query(
+      'SELECT sql FROM sqlite_master WHERE type = ? AND name = ?',
+      ['table', 'traces_search']
+    );
+    const currentSql = existing.length ? String(existing[0].sql || '') : null;
+    if (currentSql !== null && /fts4\s*\(\s*id\s*,/i.test(currentSql)) {
+      return { migrated: false, indexed: null, expected: null };
+    }
+
+    if (currentSql !== null) {
+      this._db.run('DROP TABLE traces_search');
+    }
+    this._db.run(`
+      CREATE VIRTUAL TABLE traces_search
+      USING fts4(id, trace_id, content, agent, notindexed=id, tokenize=porter)
+    `);
+    return { migrated: true, ...this.rebuildTracesSearch() };
+  }
+
+  /**
+   * Rebuild traces_search from the `traces` base table.
+   *
+   * Explicitly re-runnable and idempotent: every index row is derivable from
+   * `traces`, so this clears the index and re-inserts exactly one row per
+   * content-bearing trace. Running it twice yields the same counts. This is the
+   * backfill that recovers rows lost to the old trace_id-keyed DELETE; no schema
+   * migration is required to run it once the schema is id-keyed.
+   * @returns {{indexed: number, expected: number}} post-rebuild row counts —
+   *   equal when the index is complete
+   */
+  rebuildTracesSearch() {
+    this._db.run('DELETE FROM traces_search');
+    this._db.run(
+      `INSERT INTO traces_search (id, trace_id, content, agent)
+       SELECT id, trace_id, content, agent
+       FROM traces
+       WHERE content IS NOT NULL AND content <> ?`,
+      ['']
+    );
+    const indexed = this.query('SELECT COUNT(*) AS c FROM traces_search')[0].c;
+    const expected = this.query(
+      'SELECT COUNT(*) AS c FROM traces WHERE content IS NOT NULL AND content <> ?',
+      ['']
+    )[0].c;
+    return { indexed, expected };
+  }
+
+  /**
+   * Run an FTS MATCH per term, then return the top `limit` base-table rows ranked
+   * by summed tf-idf.
+   *
+   * One MATCH per term rather than a single OR-joined MATCH: an OR-join returns
+   * its rows in docid order, so LIMIT cuts the candidate pool at the OLDEST
+   * FTS_RANK_POOL matches. Measured on the 5,082-row live trace index, a query of
+   * "celestial" (2,888 matches) plus a unique token could not retrieve the
+   * uniquely-matching document AT ALL, because 2,000 older rows filled the pool
+   * first — and since traces are append-only, the newest rows are always the
+   * first to be dropped. Scored per term the arithmetic is identical (matchinfo
+   * sums over phrases either way), but the pool can only be exhausted by a term's
+   * OWN document frequency, so a rare, discriminating term never loses.
+   * @param {string} baseTable - key of FTS_SEARCH_TABLES
+   * @param {string[]} terms - MATCH expressions from buildFtsTerms()
+   * @param {number} limit - clamped row limit
+   * @returns {Array<Object>} base-table rows, most relevant first
+   */
+  _rankedFtsSearch(baseTable, terms, limit) {
+    const config = FTS_SEARCH_TABLES[baseTable];
+    if (!config) {
+      throw new Error(`[VectorHub] refusing to search unknown table: ${baseTable}`);
+    }
+    if (terms.length === 0) return [];
+
+    // id -> { score, order }; `order` is the first-seen position, used as an
+    // explicit tiebreak so the ranking never depends on sort stability.
+    const scored = new Map();
+    for (const term of terms) {
+      const rows = this.query(
+        `SELECT id, matchinfo(${config.ftsTable}, 'pcnx') AS mi
+         FROM ${config.ftsTable}
+         WHERE ${config.ftsTable} MATCH ?
+         LIMIT ?`,
+        [term, FTS_RANK_POOL]
+      );
+      for (const row of rows) {
+        const add = scoreMatchInfo(row.mi, config.columnWeights);
+        const prev = scored.get(row.id);
+        scored.set(row.id, prev
+          ? { score: prev.score + add, order: prev.order }
+          : { score: add, order: scored.size });
+      }
+    }
+
+    const ids = [...scored.entries()]
+      .sort((a, b) => (b[1].score - a[1].score) || (a[1].order - b[1].order))
+      .slice(0, limit)
+      .map(([id]) => id);
+    if (ids.length === 0) return [];
+
+    const placeholders = ids.map(() => '?').join(', ');
+    const rows = this.query(`SELECT * FROM ${baseTable} WHERE id IN (${placeholders})`, ids);
+    const byId = new Map(rows.map(r => [r.id, r]));
+    return ids.map(id => byId.get(id)).filter(Boolean);
+  }
+
   /**
    * Persist the in-memory database to disk (UC-09).
    *
@@ -258,11 +569,24 @@ class VectorHub {
     // COMPLETED (success or failure). The exit guard fires saveSync() while any
     // scheduled save is still outstanding — see _installExitGuard().
     this._pendingSaves++;
-    this._saveChain = this._saveChain.then(() => writeDbDurable(dbPath, buffer))
+    this._saveChain = this._saveChain
+      // Write the tmp asynchronously, then commit it under the lock. The commit MUST be the last
+      // step — see commitDb's note on the check-then-write gap that made this guard bypassable.
+      .then(() => writeTmpDurable(dbPath, buffer))
+      .then((tmpPath) => {
+        const res = commitDb(dbPath, this._diskFingerprint, buffer, tmpPath);
+        if (res.ok) {
+          this._diskFingerprint = res.fingerprint;
+          this._pendingSaves--;         // decrement ONLY on a durable write; see below
+        }
+      })
       .catch((err) => {
+        // Left deliberately outstanding. _pendingSaves gates the exit guard, so decrementing after a
+        // FAILED save would make the guard skip its last-resort saveSync() and drop this batch — the
+        // exact loss the counter exists to prevent. withFileLock throws when it cannot acquire, so
+        // lock contention lands here, and leaving the count high is what makes the retry happen.
         console.warn(`[VectorHub] Failed to save database: ${err.message}`);
-      })
-      .then(() => { this._pendingSaves--; });
+      });
     return this._saveChain;
   }
 
@@ -270,13 +594,18 @@ class VectorHub {
    * Synchronous, crash-safe persistence — used only on shutdown to GUARANTEE
    * no acknowledged write is lost if the process exits before the async save
    * chain drains. Correctness over non-blocking here.
+   *
+   * @returns {boolean} true when the in-memory database is durably on disk — either committed
+   *   over the live file or preserved in a conflict sidecar. false when it is NOT, which is the
+   *   signal _reapAbandonedExport() needs: on false, an abandoned tmp export may hold the only
+   *   copy of those rows and must be left alone.
    */
   saveSync() {
-    if (!this._db) return;
+    if (!this._db) return false;
     try {
       this._ensureDir();
       const buffer = Buffer.from(this._db.export());
-      const tmpPath = `${this.dbPath}.tmp.${process.pid}`;
+      const tmpPath = `${this.dbPath}.tmp.${process.pid}.sync`;
       const fd = fs.openSync(tmpPath, 'w');
       try {
         fs.writeSync(fd, buffer);
@@ -284,13 +613,26 @@ class VectorHub {
       } finally {
         fs.closeSync(fd);
       }
-      fs.renameSync(tmpPath, this.dbPath);
+      // Commit under the lock. Worst case this blocks the exit handler for withFileLock's bounded
+      // retry ceiling (~1-2s) and then throws into the catch below — bounded, logged, and far better
+      // than writing over a file another process just changed.
+      const res = commitDb(this.dbPath, this._diskFingerprint, buffer, tmpPath);
+      if (!res.ok) {
+        this._pendingSaves = 0;   // the data is in the sidecar; retrying would clobber again
+        // A written sidecar IS durable persistence — the bytes are on disk under a name nothing
+        // else will touch. A NULL sidecar is not: commitDb unlinked the tmp and wrote nothing,
+        // so this export exists only in memory and is about to be lost with the process.
+        return res.sidecar !== null && res.sidecar !== undefined;
+      }
+      this._diskFingerprint = res.fingerprint;
       // A sync export captures the full in-memory DB — a superset of anything the
       // outstanding async saves would have written — so the pending work is now
       // durably satisfied. Clearing the counter prevents a redundant second flush.
       this._pendingSaves = 0;
+      return true;
     } catch (err) {
       console.warn(`[VectorHub] Failed to save database (sync): ${err.message}`);
+      return false;
     }
   }
 
@@ -396,12 +738,14 @@ class VectorHub {
       [entry.id, entry.trace_id, entry.span_id, entry.event, entry.timestamp, entry.agent, entry.content, entry.metadata, entry.drift_score, entry.mesh_node_id]
     );
 
-    // Update FTS index if content exists
+    // Update the FTS index if content exists. Keyed on entry.id (the traces
+    // PRIMARY KEY) — keying the DELETE on trace_id wiped every sibling span's
+    // index row, which is what made 44.4% of trace content unsearchable (FTS-01).
     if (entry.content) {
-      this._db.run('DELETE FROM traces_search WHERE trace_id = ?', [entry.trace_id]);
+      this._db.run('DELETE FROM traces_search WHERE id = ?', [entry.id]);
       this._db.run(
-        'INSERT INTO traces_search (trace_id, content, agent) VALUES (?, ?, ?)',
-        [entry.trace_id, entry.content, entry.agent]
+        'INSERT INTO traces_search (id, trace_id, content, agent) VALUES (?, ?, ?, ?)',
+        [entry.id, entry.trace_id, entry.content, entry.agent]
       );
     }
 
@@ -436,26 +780,34 @@ class VectorHub {
   }
 
   /**
-   * Full-text search for traces.
+   * Full-text search for traces, ranked by tf-idf.
+   *
+   * Multi-word queries are ORed across terms and ranked (see _rankedFtsSearch).
+   * FTS4 has no built-in ranker, so without the ranking step the result is docid
+   * order and mean recall@10 measures 0.0000.
+   * @param {string} rawQuery - the user's query text
+   * @param {{phrase?: boolean, limit?: number}} [opts]
+   *   phrase:true searches for the exact adjacent word sequence (old behaviour);
+   *   limit is clamped to [1, 100] and defaults to 10.
+   * @returns {Promise<Array<Object>>} trace rows, most relevant first
+   * @throws {TypeError} when rawQuery is not a string
    */
-  async searchTraces(rawQuery) {
-    const escaped = rawQuery.replace(/"/g, '""');
-    const ftsQuery = `"${escaped}"`;
-    return this.query(
-      `SELECT t.*
-       FROM traces t
-       JOIN traces_search ts ON t.trace_id = ts.trace_id
-       WHERE traces_search MATCH ?
-       LIMIT 10`,
-      [ftsQuery]
+  async searchTraces(rawQuery, opts = {}) {
+    return this._rankedFtsSearch(
+      'traces',
+      buildFtsTerms(rawQuery, opts),
+      clampFtsLimit(opts.limit)
     );
   }
 
   /**
    * Full-text search for traces (alias for backward compat).
+   * @param {string} rawQuery
+   * @param {{phrase?: boolean, limit?: number}} [opts]
+   * @returns {Promise<Array<Object>>}
    */
-  async searchFTS(rawQuery) {
-    return this.searchTraces(rawQuery);
+  async searchFTS(rawQuery, opts = {}) {
+    return this.searchTraces(rawQuery, opts);
   }
 
   /**
@@ -512,16 +864,22 @@ class VectorHub {
     return record.id;
   }
 
-  async searchKnowledge(rawQuery, limit = 10) {
-    const escaped = rawQuery.replace(/"/g, '""');
-    const ftsQuery = `"${escaped}"`;
-    return this.query(
-      `SELECT k.*
-       FROM knowledge k
-       JOIN knowledge_search ks ON k.id = ks.id
-       WHERE knowledge_search MATCH ?
-       LIMIT ?`,
-      [ftsQuery, limit]
+  /**
+   * Full-text search for knowledge entries, ranked by tf-idf (see searchTraces).
+   * @param {string} rawQuery
+   * @param {number|{phrase?: boolean, limit?: number}} [limitOrOpts] - a bare
+   *   number is still accepted for backward compatibility
+   * @returns {Promise<Array<Object>>} knowledge rows, most relevant first
+   * @throws {TypeError} when rawQuery is not a string
+   */
+  async searchKnowledge(rawQuery, limitOrOpts = {}) {
+    const opts = (limitOrOpts !== null && typeof limitOrOpts === 'object')
+      ? limitOrOpts
+      : { limit: limitOrOpts };
+    return this._rankedFtsSearch(
+      'knowledge',
+      buildFtsTerms(rawQuery, opts),
+      clampFtsLimit(opts.limit)
     );
   }
 
@@ -569,9 +927,108 @@ class VectorHub {
 // ── Durable async DB file write (UC-09) ───────────────────────────────────────
 // Crash-safe: write to a tmp file, fsync, then atomically rename over the target.
 // A crash mid-write leaves the previous good .db intact (rename is atomic on POSIX).
-function writeDbDurable(dbPath, buffer) {
+/**
+ * A cheap identity for the on-disk database: size plus mtime in ms.
+ *
+ * Not a digest — this runs before every save, and hashing a 10MB+ file on each write would be a real
+ * cost for a check whose only job is "did somebody else touch this?". size+mtimeMs changes on any
+ * rewrite by another process, which is exactly the event being detected.
+ */
+function dbFingerprint(dbPath) {
+  try {
+    const st = fs.statSync(dbPath);
+    return `${st.size}:${st.mtimeMs}`;
+  } catch {
+    return null;   // absent is a legitimate state, not an error
+  }
+}
+
+/**
+ * Refuse to silently overwrite another process's writes.
+ *
+ * sql.js holds the whole database in memory and persists by exporting the ENTIRE file and renaming it
+ * over the path. Two processes each hold their own copy and each rewrite the whole file, so the last
+ * writer wins and the other's rows are gone. Measured: two concurrent writers, 15 acknowledged
+ * recordTrace() calls each, 30 expected — 15 on disk, ALL from writer A. Writer B's 15 acknowledged
+ * writes vanished, with no error on either side.
+ *
+ * A caveat on the corroborating evidence, because it was overstated. `.mindforge/` does carry
+ * orphaned `celestial.db.tmp.<pid>` files, and one IS a valid database with skills rows absent from
+ * the live file — but those rows are not lost user data. Audited all 171 non-empty orphans against
+ * the live database: 161 are strict subsets, 9 exceed it only on `traces_search_segdir` (an FTS5
+ * segment-directory count, an index-merge artifact rather than rows), and exactly one
+ * (`celestial.db.tmp.4027`, 63.5 MB, pre-dating the `.async`/`.sync` suffixes) holds 1,373 skill
+ * names the live file lacks — every one of them a `Synthesized Skill (mf-*) - ev_<hash>` row, the
+ * generated filler already slated for deletion. So the orphans corroborate that the clobber window
+ * was ENTERED; they are not evidence that anything worth keeping was destroyed.
+ *
+ * The cross-process loss itself is proven by the two-writer measurement above, which does not
+ * depend on this. Recorded because "there is a database on disk holding rows the live file lacks"
+ * reads as recoverable data loss, and here it is not.
+ *
+ * Making sql.js genuinely multi-process safe means replacing the driver — the whole-file export IS the
+ * problem, and locking alone does not fix it, because both processes loaded a stale copy before either
+ * saved. What is fixable now is the SILENCE. On a detected clobber the export goes to a
+ * `.conflict.<pid>` sidecar and the caller is told, so the data still exists and somebody knows.
+ * Refusing loudly beats destroying quietly — the same choice as auto-runner refusing to record a
+ * completion it cannot substantiate.
+ *
+ * WHY CHECK AND RENAME ARE ONE CRITICAL SECTION. A first version checked the fingerprint and then
+ * handed the buffer to an ASYNC writer. Measured with a deterministic stage — parent writes 3, spawns a
+ * child that writes 5 and exits, parent then closes:
+ *
+ *     [parent] GUARD ...898 == ...898      <- check passes
+ *     === child writes and saves ===       <- file is now ...249
+ *     [parent] ASYNC-WROTE new=...309      <- writes its PRE-CHILD snapshot anyway
+ *     live rows: P0,P1,P2,seed             <- the child's 5 rows destroyed, silently
+ *
+ * spawnSync blocked the event loop, so the child fit entirely inside the gap between the check and the
+ * write. A check followed by a later write is not a guard — it is the same clobber with extra steps.
+ * So the fingerprint comparison and the atomic rename now happen together, synchronously, under the
+ * shared fail-closed lock. withFileLock rejects a thenable outright, which makes reintroducing that gap
+ * a loud TypeError rather than silent data loss.
+ *
+ * The expensive part (writing and fsyncing the tmp file) stays OUTSIDE the lock and may still be async:
+ * the tmp path is pid-scoped, so no other process can observe or touch it.
+ *
+ * @param {string} tmpPath  a fully-written, fsynced tmp file to rename into place
+ * @returns {{ok: boolean, fingerprint?: string, sidecar?: string}}
+ */
+function commitDb(dbPath, expected, buffer, tmpPath) {
+  return withFileLock(dbPath, () => {
+    const actual = dbFingerprint(dbPath);
+    if (expected === null || actual === null || actual === expected) {
+      fs.renameSync(tmpPath, dbPath);
+      return { ok: true, fingerprint: dbFingerprint(dbPath) };
+    }
+
+    // Conflict. Keep this process's bytes and leave the other process's file untouched.
+    const sidecar = `${dbPath}.conflict.${process.pid}.${buffer.length}`;
+    try {
+      fs.renameSync(tmpPath, sidecar);   // already fsynced; a rename beats a second full write
+    } catch (err) {
+      console.error(`[VectorHub] CONFLICT and the sidecar could not be written: ${err.message}`);
+      try { fs.unlinkSync(tmpPath); } catch { /* nothing further to do */ }
+      return { ok: false, sidecar: null };
+    }
+    console.error(
+      `[VectorHub] REFUSING TO OVERWRITE ${dbPath}: another process changed it since this one loaded it `
+      + `(expected ${expected}, found ${actual}). sql.js rewrites the whole file, so continuing would `
+      + `discard that process's rows. This process's data went to ${sidecar} instead — nothing is lost, `
+      + 'but the two databases must be reconciled by hand.');
+    return { ok: false, sidecar };
+  }, { label: 'vector-hub-db' });
+}
+
+/**
+ * Write and fsync the pid-scoped tmp file, resolving to its path. Does NOT rename it into place —
+ * that is commitDb's job, because the rename has to share a critical section with the staleness check.
+ * Staying async here is the point: fsync of a multi-megabyte export is the expensive part, and the tmp
+ * path cannot be observed by another process.
+ */
+function writeTmpDurable(dbPath, buffer) {
   return new Promise((resolve, reject) => {
-    const tmpPath = `${dbPath}.tmp.${process.pid}`;
+    const tmpPath = `${dbPath}.tmp.${process.pid}.async`;
     const fail = (err) => { fs.unlink(tmpPath, () => reject(err)); };
     fs.open(tmpPath, 'w', (openErr, fd) => {
       if (openErr) return reject(openErr);
@@ -581,10 +1038,7 @@ function writeDbDurable(dbPath, buffer) {
           fs.close(fd, (closeErr) => {
             if (syncErr) return fail(syncErr);
             if (closeErr) return fail(closeErr);
-            fs.rename(tmpPath, dbPath, (renameErr) => {
-              if (renameErr) return fail(renameErr);
-              resolve();
-            });
+            resolve(tmpPath);
           });
         });
       });
@@ -611,6 +1065,7 @@ const lazyHub = new Proxy({}, {
   get(_, prop) {
     if (prop === 'VectorHub') return VectorHub;
     if (prop === 'createVectorHub') return createVectorHub;
+    if (prop === 'buildFtsTerms') return buildFtsTerms;
     if (!_instance) _instance = new VectorHub();
     return typeof _instance[prop] === 'function'
       ? _instance[prop].bind(_instance)
@@ -621,3 +1076,4 @@ const lazyHub = new Proxy({}, {
 module.exports = lazyHub;
 module.exports.VectorHub = VectorHub;
 module.exports.createVectorHub = createVectorHub;
+module.exports.buildFtsTerms = buildFtsTerms;