@openparachute/vault 0.7.0-rc.6 → 0.7.0-rc.7

package/core/src/mcp.ts

@@ -5,7 +5,14 @@ import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
-import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "./query-warnings.js";
+import {
+  collectUnknownTagWarnings,
+  emptySearchWarning,
+  ignoredParamWarning,
+  computeSearchDidYouMean,
+  searchDidYouMeanWarning,
+  type QueryWarning,
+} from "./query-warnings.js";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
@@ -265,7 +272,9 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
 - Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
 
-\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.`,
+\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.
+
+\`search\` indexes BOTH a note's title (\`path\`) and its \`content\` (vault#551 WS2C, schema v25) — a title match is weighted far above a passing body mention, so a dedicated note on a topic outranks another note that merely references it. Every result carries a \`score\` field (higher = more relevant; only meaningful as a RELATIVE comparison within one result set). Word matching also stems regular English affixes ("firefighter" matches "firefighters", "microbe" matches "microbes") — irregular plurals with a consonant change ("wolf"/"wolves") aren't covered by stemming. A search that returns ZERO results may carry a \`search_did_you_mean\` warning suggesting the closest indexed term when one looks like a likely typo (only unscoped sessions — tag-scoped tokens never see it, since the suggestion is computed vault-wide).`,
       inputSchema: {
         type: "object",
         properties: {
@@ -322,7 +331,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           search: {
             type: "string",
             description:
-              'Full-text search query. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking.',
+              'Full-text search query, matched against BOTH a note\'s title (path) and its content — a title match ranks far above a passing body mention. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking. Matching stems regular affixes ("firefighter"/"firefighters") but not irregular plurals ("wolf"/"wolves"). Results carry a `score` field (higher = more relevant, relative within this result set only). A zero-result search may carry a `search_did_you_mean` warning (unscoped sessions only).',
           },
           search_mode: {
             type: "string",
@@ -603,6 +612,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
               mode,
               sort: params.sort as "asc" | "desc" | undefined,
             });
+            // Zero-result `did_you_mean` (vault#551 WS2B) — cheap (a bounded
+            // FTS5-vocabulary scan) and ONLY computed on the already-rare
+            // empty-result path, mirroring `unknown_tag`'s did_you_mean.
+            // Scope-unaware by construction (same as `collectUnknownTagWarnings`
+            // above) — safe here because `applyTagScopeWrappers`'s
+            // `query-notes` wrapper (`src/mcp-tools.ts`) strips the ENTIRE
+            // `warnings` array for a tag-scoped session before it reaches the
+            // caller, so this never leaks out-of-scope vocabulary to one.
+            if (results.length === 0) {
+              const suggestion = computeSearchDidYouMean(db, params.search as string);
+              if (suggestion) {
+                queryWarnings.push(searchDidYouMeanWarning(params.search as string, suggestion));
+              }
+            }
           }
         } else {
           // --- Structured query ---

package/core/src/notes.ts

@@ -22,7 +22,12 @@ import {
 import { getIndexedField, releaseField } from "./indexed-fields.js";
 import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-hierarchy.js";
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
-import { buildLiteralSearchQuery, type SearchMode } from "./search-query.js";
+import {
+  buildLiteralSearchQuery,
+  SEARCH_WEIGHT_PATH,
+  SEARCH_WEIGHT_CONTENT,
+  type SearchMode,
+} from "./search-query.js";
 
 let idCounter = 0;
 
@@ -1336,12 +1341,41 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
  *     invariant is ever broken it still surfaces as an honest error, not a
  *     500. Signals a vault bug worth reporting.
  */
+/**
+ * FTS5's own error text for a syntax mistake is written for someone who
+ * already knows FTS5's grammar — "no such column: espresso" for a bare
+ * leading `-espresso` (NOT with no left-hand term — FTS5's `-`/`NOT` is a
+ * BINARY operator, so a lone `-token` with nothing before it gets
+ * misparsed as `column:term` filter syntax and fails looking for a column
+ * named after the token) is confusing/leaky rather than actionable: it
+ * reads as if a column literally named "espresso" was expected, which
+ * exposes FTS5-internal parsing behavior instead of explaining the actual
+ * mistake (vault#551 WS2B item 4 — interim harness finding). Detected
+ * generically off the FTS5 error text (`/no such column:/i`) rather than
+ * re-parsing the query ourselves, since the SAME message also covers the
+ * other real cause (an explicit `column:term` filter naming a column that
+ * isn't one of `notes_fts`'s declared columns, `path`/`content`) — the hint
+ * below covers both without claiming to know which one happened.
+ */
+function advancedModeColumnHint(causeMessage: string): string | null {
+  if (!/no such column:/i.test(causeMessage)) return null;
+  return (
+    `FTS5 read part of this query as column-filter syntax ("column:term") or as a ` +
+    `leading "-" with no term to its left — NOT/"-" is a BINARY operator in FTS5 ` +
+    `("good -bad", not "-bad" alone). Indexed columns are "path" and "content". ` +
+    `Add a preceding positive term before a NOT, quote the phrase to search it ` +
+    `literally, or use search_mode:"literal" (the default) to skip advanced syntax entirely.`
+  );
+}
+
 function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): QueryError {
   const causeMessage = err instanceof Error ? err.message : String(err);
+  const columnHint = mode === "advanced" ? advancedModeColumnHint(causeMessage) : null;
   const hint =
-    mode === "advanced"
+    columnHint ??
+    (mode === "advanced"
       ? `FTS5 rejected this as advanced query syntax (${causeMessage}). Fix the syntax, or omit search_mode:"advanced" for literal (punctuation-safe) search.`
-      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`;
+      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`);
   return new QueryError(`invalid search syntax: ${causeMessage}`, "INVALID_QUERY", {
     error_type: "invalid_search_syntax",
     field: "search",
@@ -1377,20 +1411,33 @@ export function searchNotes(
     ftsQuery = query;
   }
 
+  // Weighted bm25 relevance expression (vault#551 WS2C, schema v25):
+  // `notes_fts` now indexes `path` (title, column 0) then `content` (body,
+  // column 1) — SEARCH_WEIGHT_PATH/SEARCH_WEIGHT_CONTENT bias ranking so a
+  // title match outranks a passing body mention. Raw SQLite bm25 is
+  // negative-is-better; `-1.0 * bm25(...)` flips it so bigger is more
+  // relevant (see `Note.score`'s doc comment for the external contract).
+  // The weights are our own numeric constants (not user input) interpolated
+  // directly — bm25()'s weight arguments are positional per-column
+  // multipliers, not general SQL expressions callers can influence.
+  const scoreExpr = `(-1.0 * bm25(notes_fts, ${SEARCH_WEIGHT_PATH}, ${SEARCH_WEIGHT_CONTENT}))`;
+
   // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
-  // relevance (`rank`, unchanged); an EXPLICIT `sort: "asc"|"desc"` switches
-  // to `created_at` ordering. Checked against the literal string values (not
-  // truthiness) so an absent `sort` can never accidentally match a branch.
-  // `n.id ${direction}` is appended as a deterministic tiebreaker — same
-  // rationale as `queryNotes` (two notes at the same created_at millisecond
-  // would otherwise return in arbitrary/unstable order). `rank` needs no
-  // tiebreaker (bm25 score is effectively unique per row).
+  // relevance (the weighted `score` expression); an EXPLICIT
+  // `sort: "asc"|"desc"` switches to `created_at` ordering. Checked against
+  // the literal string values (not truthiness) so an absent `sort` can
+  // never accidentally match a branch. `n.id ${direction}` is appended as a
+  // deterministic tiebreaker in every branch — two notes at the same
+  // created_at millisecond (structured-sort branches) OR with an
+  // identical weighted score (relevance branch — much more likely than
+  // with unweighted `rank`, since many notes share "zero path matches")
+  // would otherwise return in arbitrary/unstable order.
   const orderBy =
     opts?.sort === "asc"
       ? "n.created_at ASC, n.id ASC"
       : opts?.sort === "desc"
         ? "n.created_at DESC, n.id DESC"
-        : "rank";
+        : "score DESC, n.id ASC";
 
   if (opts?.tags && opts.tags.length > 0) {
     // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
@@ -1406,14 +1453,14 @@ export function searchNotes(
       // DISTINCT over full rows. The FTS join itself is 1:1 on rowid.
       const tagPlaceholders = searchTags.map(() => "?").join(", ");
       const rows = db.prepare(`
-        SELECT n.* FROM notes n
+        SELECT n.*, ${scoreExpr} AS score FROM notes n
         JOIN notes_fts fts ON fts.rowid = n.rowid
         WHERE notes_fts MATCH ?
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
         ORDER BY ${orderBy}
         LIMIT ?
-      `).all(ftsQuery, ...searchTags, limit) as NoteRow[];
-      return notesWithTags(db, rows);
+      `).all(ftsQuery, ...searchTags, limit) as (NoteRow & { score: number })[];
+      return notesWithTags(db, rows, scoresById(rows));
     } catch (err) {
       // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
       // advanced mode expects it (the caller passed raw syntax); literal
@@ -1429,27 +1476,44 @@ export function searchNotes(
 
   try {
     const rows = db.prepare(`
-      SELECT n.* FROM notes n
+      SELECT n.*, ${scoreExpr} AS score FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
       ORDER BY ${orderBy}
       LIMIT ?
-    `).all(ftsQuery, limit) as NoteRow[];
-    return notesWithTags(db, rows);
+    `).all(ftsQuery, limit) as (NoteRow & { score: number })[];
+    return notesWithTags(db, rows, scoresById(rows));
   } catch (err) {
     if (err instanceof QueryError) throw err;
     throw searchSyntaxError(query, err, mode);
   }
 }
 
-/** Map rows → Notes with tags hydrated in one batched query. */
-function notesWithTags(db: Database, rows: NoteRow[]): Note[] {
+/**
+ * Map rows → Notes with tags hydrated in one batched query. `scores`
+ * (vault#551 WS2C) is an optional id → weighted-bm25-score map, attached
+ * onto each returned `Note.score` when present — ONLY `searchNotes`'s two
+ * callers pass it; every other caller (plain `queryNotes`, `getNotesByIds`,
+ * ...) omits it and gets byte-identical output to before `score` existed.
+ */
+function notesWithTags(db: Database, rows: NoteRow[], scores?: Map<string, number>): Note[] {
   const notes = rows.map(rowToNote);
   const tagsById = getNoteTagsForNotes(db, notes.map((n) => n.id));
-  for (const note of notes) note.tags = tagsById.get(note.id) ?? [];
+  for (const note of notes) {
+    note.tags = tagsById.get(note.id) ?? [];
+    if (scores) {
+      const s = scores.get(note.id);
+      if (s !== undefined) note.score = s;
+    }
+  }
   return notes;
 }
 
+/** Build an id → score map from search result rows carrying a `score` column. */
+function scoresById(rows: (NoteRow & { score: number })[]): Map<string, number> {
+  return new Map(rows.map((r) => [r.id, r.score]));
+}
+
 // ---- Tag Operations ----
 
 export function tagNote(db: Database, noteId: string, tags: string[]): void {
@@ -2120,6 +2184,7 @@ export function toNoteIndex(note: Note): NoteIndex {
     metadata: note.metadata,
     byteSize,
     preview,
+    ...(note.score !== undefined ? { score: note.score } : {}),
   };
 }
 

package/core/src/query-warnings.ts

@@ -217,3 +217,113 @@ export function ignoredParamWarning(param: string, reason: string): QueryWarning
     param,
   };
 }
+
+/**
+ * Cheap zero-result search suggestion (vault#551 WS2B — mirrors the tag
+ * `did_you_mean` above via the SAME `suggestSimilarTag` scorer, just over a
+ * different candidate pool). Callers MUST only invoke this AFTER a search
+ * already returned zero rows — it is never on the hot non-empty path, so
+ * the extra vocabulary scan costs nothing in the overwhelmingly common
+ * case where the search actually found something.
+ *
+ * Candidates are drawn from two cheap-to-reach sources, unioned:
+ *
+ *   - the FTS5 vocabulary — a `notes_fts_vocab` `fts5vocab('row')` table
+ *     created here LAZILY and BEST-EFFORT (not part of the schema/
+ *     migration — see the try/catch below) — the terms actually indexed,
+ *     POST-tokenization/stemming (porter). A suggestion therefore
+ *     sometimes reads as a stemmed form ("propoli" rather than "propolis")
+ *     rather than the original dictionary word — an accepted tradeoff
+ *     (documented in docs/HTTP_API.md) rather than maintaining a second,
+ *     unstemmed index just for spelling suggestions.
+ *   - tag names, when the caller passes `tagNames` (already cached by the
+ *     caller's tag hierarchy — free to include).
+ *
+ * `fts5vocab` is registered by the same FTS5 extension init as `notes_fts`
+ * itself (not a separately-enabled module) so it's expected to be
+ * available anywhere search already works — but this is NOT exercised
+ * against Cloudflare DO SQLite (flagged for the wire reviewer). The WHOLE
+ * function is wrapped in try/catch and degrades to "no suggestion" on ANY
+ * failure — including a runtime where `fts5vocab` is unavailable — rather
+ * than ever throwing; a spelling hint is a nicety, never worth risking the
+ * search response itself.
+ *
+ * Per-token length filtering (`length(term) BETWEEN len-2 AND len+2`) keeps
+ * the vocabulary scan bounded on a large vault without a hardcoded row cap
+ * that could silently exclude the very term a caller needs (a `LIMIT`
+ * ORDER-BY-frequency would bias toward common words, which is backwards
+ * for a name/typo lookup — the word you're trying to find is often rare).
+ */
+export function computeSearchDidYouMean(
+  db: Database,
+  rawQuery: string,
+  tagNames?: Iterable<string>,
+): string | undefined {
+  try {
+    const tokens = rawQuery.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) return undefined;
+
+    db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts_vocab USING fts5vocab(notes_fts, 'row')");
+    const exactStmt = db.prepare("SELECT 1 FROM notes_fts_vocab WHERE term = ? LIMIT 1");
+    const rangeStmt = db.prepare("SELECT term FROM notes_fts_vocab WHERE length(term) BETWEEN ? AND ?");
+
+    let changed = false;
+    const corrected = tokens.map((tok) => {
+      // Strip leading/trailing punctuation for the lookup (the FTS5
+      // vocabulary never contains punctuation) but leave short tokens
+      // (numbers, "a", "of", ...) alone — too little signal to safely
+      // "correct" without a high false-positive rate.
+      const clean = tok.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+      if (clean.length < 3) return tok;
+      const lower = clean.toLowerCase();
+
+      // Already indexed verbatim (post-stemming) — no typo signal.
+      if (exactStmt.get(lower)) return tok;
+
+      const lo = Math.max(1, clean.length - 2);
+      const hi = clean.length + 2;
+      const rows = rangeStmt.all(lo, hi) as { term: string }[];
+      const candidates = new Set<string>(rows.map((r) => r.term));
+      if (tagNames) for (const t of tagNames) candidates.add(t);
+
+      const suggestion = suggestSimilarTag(candidates, lower);
+      if (suggestion && suggestion.toLowerCase() !== lower) {
+        changed = true;
+        return suggestion;
+      }
+      return tok;
+    });
+
+    if (!changed) return undefined;
+    return corrected.join(" ");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `search_did_you_mean` warning (vault#551 WS2B) — wraps
+ * {@link computeSearchDidYouMean}'s suggestion in the standard warning
+ * shape, mirroring `unknown_tag`'s `did_you_mean` field. Returns
+ * `undefined` (nothing to push) when no suggestion clears the bar — a
+ * zero-result search is a perfectly ordinary outcome on its own and does
+ * NOT warrant a warning by itself; only an actual spelling suggestion does.
+ *
+ * Scope-unaware by construction, exactly like `collectUnknownTagWarnings`
+ * (see this file's top-of-file doc comment) — the FTS5 vocabulary spans
+ * the WHOLE vault regardless of any caller's tag scope. Callers on a
+ * tag-scoped session MUST NOT surface this warning directly:
+ * `src/mcp-tools.ts`'s `query-notes` wrapper already strips the entire
+ * `warnings` array for a scoped caller (so MCP is safe with no extra
+ * work); `src/routes.ts` must gate the call itself behind
+ * `tagScope.allowed === null`, same as it already does for
+ * `collectUnknownTagWarnings`.
+ */
+export function searchDidYouMeanWarning(rawQuery: string, suggestion: string): QueryWarning {
+  return {
+    code: "search_did_you_mean",
+    message: `no results for "${rawQuery}" — did you mean "${suggestion}"?`,
+    query: rawQuery,
+    did_you_mean: suggestion,
+  };
+}

package/core/src/schema.ts

@@ -4,7 +4,7 @@ import { rebuildIndexes, listIndexedFields } from "./indexed-fields.js";
 import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
 
-export const SCHEMA_VERSION = 24;
+export const SCHEMA_VERSION = 25;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -256,25 +256,43 @@ CREATE TABLE IF NOT EXISTS schema_version (
   applied_at TEXT NOT NULL
 );
 
--- Full-text search on note content
+-- Full-text search on note title (path) AND content (v25, vault#551 WS2B/C).
+-- Two columns, declared in this order — bm25(notes_fts, w_path, w_content)
+-- calls in core/src/notes.ts positionally match column 0 = path, column 1 =
+-- content, weighted so a TITLE match outranks a passing body mention (see
+-- SEARCH_WEIGHT_PATH/SEARCH_WEIGHT_CONTENT in core/src/search-query.ts).
+-- Pre-v25, only content was indexed — a note's title/path was completely
+-- unsearchable, which both defeated any title-biased ranking (nothing to
+-- bias) and was a plain recall gap. tokenize='porter unicode61' adds
+-- Porter stemming on top of the v3-era default unicode61 tokenizer so
+-- regular-affix variants (firefighter/firefighters, microbe/microbes) match
+-- each other; irregular plurals with a consonant change (wolf/wolves) are a
+-- known Porter limitation, not fixed by this — see docs/HTTP_API.md.
+-- Existing vaults upgrade via migrateToV25 (rebuild + repopulate); this
+-- CREATE only reaches its new shape directly on a fresh vault.
 CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+  path,
   content,
   content='notes',
-  content_rowid='rowid'
+  content_rowid='rowid',
+  tokenize='porter unicode61'
 );
 
--- FTS triggers
+-- FTS triggers. UPDATE OF content, path (not content alone, pre-v25) —
+-- either column changing must resync the index now that path is indexed too;
+-- a path-only rename (content untouched) used to be silently invisible to
+-- notes_fts because the trigger's column list didn't include it.
 CREATE TRIGGER IF NOT EXISTS notes_fts_insert AFTER INSERT ON notes BEGIN
-  INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+  INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
 END;
 
 CREATE TRIGGER IF NOT EXISTS notes_fts_delete AFTER DELETE ON notes BEGIN
-  INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+  INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
 END;
 
-CREATE TRIGGER IF NOT EXISTS notes_fts_update AFTER UPDATE OF content ON notes BEGIN
-  INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
-  INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+CREATE TRIGGER IF NOT EXISTS notes_fts_update AFTER UPDATE OF content, path ON notes BEGIN
+  INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
+  INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
 END;
 
 -- Indexes
@@ -507,6 +525,10 @@ export function initSchema(db: Database): void {
   // leave the rest in place for `doctor` to surface. See vault#553.
   migrateToV24(db);
 
+  // Migrate v24 → v25: rebuild notes_fts with path+content columns +
+  // porter stemming, repopulate from every existing note. See vault#551.
+  migrateToV25(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1332,6 +1354,143 @@ function migrateToV24(db: Database): void {
   }
 }
 
+/**
+ * Migrate v24 → v25: rebuild `notes_fts` to index BOTH `path` (title) and
+ * `content` as separate weighted FTS5 columns, with Porter stemming added
+ * to the tokenizer (vault#551 WS2B/C — the Reliability & Usability
+ * Program's interim-harness finding: a note's title/path was completely
+ * unsearchable pre-v25, which both defeated title-biased ranking and was a
+ * plain recall gap on its own).
+ *
+ * `notes_fts` is an EXTERNAL CONTENT table (`content='notes'`) — the FTS5
+ * index is a side structure over `notes`, not a copy of the data itself, so
+ * changing its column shape means DROP + CREATE, not `ALTER`. FTS5 virtual
+ * tables don't support `ALTER TABLE ... ADD COLUMN` the way ordinary tables
+ * do. The three sync triggers are defined ON `notes` (`AFTER INSERT/UPDATE/
+ * DELETE ON notes`), not on `notes_fts` itself, so dropping `notes_fts`
+ * does NOT drop them automatically — they're dropped explicitly FIRST
+ * (referencing the old single-column shape, they'd fail on the very next
+ * note write if left in place against the new table) and recreated
+ * immediately after in the new two-column form. SCHEMA_SQL carries the
+ * identical CREATE VIRTUAL TABLE + trigger definitions for fresh vaults;
+ * this function is the upgrade path for a vault that already has the old
+ * shape.
+ *
+ * External-content tables start EMPTY after a bare CREATE — unlike a normal
+ * table, there's no data to inherit from the old dropped table (FTS5 stores
+ * its own inverted-index structures, not a row-for-row copy). The
+ * repopulation pass below re-derives every row from `notes` directly, so
+ * this migration is self-contained (it does NOT read from the old
+ * `notes_fts` — that data is gone the moment DROP TABLE runs).
+ *
+ * ALL-OR-NOTHING (generalist review, #565): the entire DROP + CREATE +
+ * trigger-recreate + repopulation sequence runs inside a SINGLE
+ * `transaction`, not just the repopulation loop. A crash partway through
+ * with the DDL committed but the index empty would otherwise be
+ * unrecoverable — the recreated table already has the `path` column, so the
+ * `hasColumn(db, "notes_fts", "path")` guard would report "done" and never
+ * retry, leaving search permanently empty. Wrapping the whole sequence means a
+ * rollback restores the pre-v25 single-column shape (no `path`), so the
+ * guard correctly re-detects "not migrated" and the next boot re-runs it —
+ * correct-by-construction rather than dependent on the DDL fully
+ * completing.
+ *
+ * Idempotent via `hasColumn(db, "notes_fts", "path")` (checked first — a
+ * vault already on the v25 shape, including every fresh vault, no-ops
+ * immediately; `PRAGMA table_info` returns `[]` for a nonexistent table and
+ * the declared columns for an FTS5 virtual table, so the shared helper is
+ * correct here without a separate `hasTable` pre-check).
+ * Cross-runtime: DROP/CREATE VIRTUAL TABLE, triggers, and the repopulation
+ * SELECT/INSERT are all standard FTS5 + SQL surface — no bun-only
+ * functions — but `tokenize='porter unicode61'` and the two-column
+ * external-content shape are new usage for this codebase; flagged for the
+ * wire reviewer to confirm against Cloudflare DO SQLite's FTS5 build (the
+ * hosted door's async Store backend is not shipped yet — see `store.ts`'s
+ * `BunSqliteStore` doc comment — so this is unverified-until-that-lands,
+ * not a regression against a working path). Porter is part of the same
+ * FTS5 extension registration as unicode61 (not a separately-enabled
+ * module) and `PRAGMA table_info` on a virtual table is standard SQLite,
+ * so the expected risk surface is narrow, but it hasn't been exercised
+ * against DO SQLite directly.
+ */
+function migrateToV25(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+  if (hasColumn(db, "notes_fts", "path")) return;
+
+  console.log(
+    "[vault] migrating to schema v25 (vault#551): rebuilding notes_fts with path+content columns and porter stemming...",
+  );
+
+  // The ENTIRE sequence — DROP triggers + table, CREATE the new virtual
+  // table, CREATE the three sync triggers, AND repopulate — runs inside ONE
+  // transaction so it's strictly all-or-nothing (generalist review, #565).
+  //
+  // Why this matters: if the DDL ran outside the transaction (only the
+  // repopulation transacted, the pre-review shape), a crash between
+  // "CREATE VIRTUAL TABLE" and the end of repopulation would leave a
+  // recreated-but-EMPTY notes_fts — and the idempotency guard
+  // (`hasColumn(db, "notes_fts", "path")`) would see the new `path` column
+  // and report the migration "done" on the next boot, so search stays
+  // PERMANENTLY empty with no retry. Worse, a crash before the CREATE TRIGGERs would leave
+  // future writes unindexed too. Wrapping the whole thing means a rollback
+  // restores the pre-v25 shape (single `content` column, no `path`), so the
+  // guard correctly reports "not migrated" and the next boot re-runs it
+  // cleanly — the guard becomes correct-by-construction rather than relying
+  // on the DDL having fully completed. The reviewer verified CREATE VIRTUAL
+  // TABLE + CREATE TRIGGER execute fine inside bun's `BEGIN IMMEDIATE …
+  // COMMIT`; a DO backend routes the same block through `transactionSync`
+  // (see core/src/txn.ts) with the identical commit-on-return /
+  // rollback-on-throw contract.
+  let repopulated = 0;
+  transaction(db, () => {
+    db.exec("DROP TRIGGER IF EXISTS notes_fts_insert");
+    db.exec("DROP TRIGGER IF EXISTS notes_fts_delete");
+    db.exec("DROP TRIGGER IF EXISTS notes_fts_update");
+    db.exec("DROP TABLE IF EXISTS notes_fts");
+
+    db.exec(`
+      CREATE VIRTUAL TABLE notes_fts USING fts5(
+        path,
+        content,
+        content='notes',
+        content_rowid='rowid',
+        tokenize='porter unicode61'
+      )
+    `);
+    db.exec(`
+      CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes BEGIN
+        INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER notes_fts_delete AFTER DELETE ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER notes_fts_update AFTER UPDATE OF content, path ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
+        INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
+      END
+    `);
+
+    const rows = db.prepare("SELECT rowid, path, content FROM notes").all() as {
+      rowid: number;
+      path: string | null;
+      content: string | null;
+    }[];
+    const insert = db.prepare("INSERT INTO notes_fts(rowid, path, content) VALUES (?, ?, ?)");
+    for (const row of rows) {
+      insert.run(row.rowid, row.path ?? "", row.content ?? "");
+      repopulated++;
+    }
+  });
+
+  console.log(
+    `[vault] migrated to schema v25 (vault#551): notes_fts rebuilt with path+content columns + porter stemming; repopulated ${repopulated} note(s).`,
+  );
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/search-fts-v25.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Search recall + ranking — schema v25 FTS rebuild (Wave 7 of the
+ * Reliability & Usability Program, WS2B/C, vault#551). Covers the
+ * MIGRATION-bearing risk this PR carries:
+ *
+ *   - a v24 vault (single-column `content`-only notes_fts) upgrades to the
+ *     v25 shape (path + content, porter stemming) via `migrateToV25`,
+ *     idempotently, without touching note data;
+ *   - a fresh vault gets the v25 shape directly from SCHEMA_SQL;
+ *   - post-migration, a note's TITLE (path) is searchable — impossible
+ *     pre-v25;
+ *   - existing body-text search keeps working (no regression);
+ *   - porter stemming matches regular-affix variants;
+ *   - bm25 ranking is weighted so a title match outranks a passing body
+ *     mention, and every result carries a legible `score`;
+ *   - the sync triggers keep the index correct across insert/update
+ *     (content-only, path-only, both)/delete, including notes with no path.
+ *
+ * See `src/contract-search.test.ts` for the REST/MCP-surface coverage
+ * (did_you_mean, the wrapped advanced-mode column-filter hint, sort
+ * override parity).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+import * as noteOps from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("search — schema v25 FTS rebuild", () => {
+  it("bumped SCHEMA_VERSION to at least 25 (notes_fts path+content landed)", () => {
+    expect(SCHEMA_VERSION).toBeGreaterThanOrEqual(25);
+  });
+
+  it("a fresh vault gets the v25 notes_fts shape directly (path + content columns)", () => {
+    const cols = (db.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map(
+      (r) => r.name,
+    );
+    expect(cols).toContain("path");
+    expect(cols).toContain("content");
+  });
+
+  it("a fresh vault: a note's title (path) is searchable even with unrelated body content", async () => {
+    await store.createNote("nothing relevant in the body here", {
+      path: "quarterly-budget-review",
+    });
+    const hits = await store.searchNotes("budget");
+    expect(hits.map((n) => n.path)).toContain("quarterly-budget-review");
+  });
+
+  it("a fresh vault: existing body search still works (no regression)", async () => {
+    await store.createNote("the widget shipped on time", { path: "unrelated-title" });
+    const hits = await store.searchNotes("widget");
+    expect(hits.map((n) => n.path)).toContain("unrelated-title");
+  });
+});
+
+describe("search — v24 → v25 migration (legacy vault upgrade)", () => {
+  /**
+   * Build a v24-shaped vault by hand: the OLD single-column notes_fts
+   * (content only), the OLD triggers (UPDATE OF content only — no path
+   * sync), and a handful of notes seeded BEFORE the migration runs —
+   * mirroring the real upgrade scenario (existing data, not a fresh DB).
+   * `initSchema` then drives the whole migration chain up through v25.
+   */
+  function buildLegacyV24Vault(): Database {
+    const legacy = new Database(":memory:");
+    legacy.exec(`
+      CREATE TABLE notes (
+        id TEXT PRIMARY KEY,
+        content TEXT DEFAULT '',
+        path TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT,
+        extension TEXT NOT NULL DEFAULT 'md',
+        created_by TEXT,
+        created_via TEXT,
+        last_updated_by TEXT,
+        last_updated_via TEXT
+      );
+      CREATE TABLE tags (
+        name TEXT PRIMARY KEY,
+        description TEXT,
+        fields TEXT,
+        relationships TEXT,
+        parent_names TEXT,
+        created_at TEXT,
+        updated_at TEXT
+      );
+      CREATE TABLE note_tags (
+        note_id TEXT NOT NULL,
+        tag_name TEXT NOT NULL,
+        PRIMARY KEY (note_id, tag_name)
+      );
+      CREATE TABLE indexed_fields (
+        field TEXT PRIMARY KEY,
+        sqlite_type TEXT NOT NULL,
+        declarer_tags TEXT NOT NULL DEFAULT '[]'
+      );
+      CREATE TABLE schema_version (version INTEGER PRIMARY KEY, applied_at TEXT);
+      INSERT INTO schema_version (version, applied_at) VALUES (24, '2026-01-01T00:00:00.000Z');
+
+      CREATE VIRTUAL TABLE notes_fts USING fts5(
+        content,
+        content='notes',
+        content_rowid='rowid'
+      );
+      CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes BEGIN
+        INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+      CREATE TRIGGER notes_fts_delete AFTER DELETE ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+      END;
+      CREATE TRIGGER notes_fts_update AFTER UPDATE OF content ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+        INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+    `);
+
+    // Seed BEFORE migration — real-data-like: some notes with a path, one
+    // without (path IS NULL — the coalesce-to-'' path must not throw).
+    const insert = legacy.prepare(
+      "INSERT INTO notes (id, content, path, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
+    );
+    insert.run(
+      "legacy-1",
+      "a dedicated writeup mentioning propolis only once in passing text",
+      "beekeeping-notes",
+      "2026-01-01T00:00:00.000Z",
+      "2026-01-01T00:00:00.000Z",
+    );
+    insert.run(
+      "legacy-2",
+      "nothing about the topic here at all",
+      "propolis",
+      "2026-01-02T00:00:00.000Z",
+      "2026-01-02T00:00:00.000Z",
+    );
+    insert.run(
+      "legacy-3",
+      "the firefighters responded quickly to the call",
+      null,
+      "2026-01-03T00:00:00.000Z",
+      "2026-01-03T00:00:00.000Z",
+    );
+    // Manually populate the OLD single-column FTS index (mirrors what the
+    // old triggers would have done on real inserts).
+    legacy.exec(`INSERT INTO notes_fts(rowid, content) SELECT rowid, content FROM notes`);
+
+    return legacy;
+  }
+
+  it("migrates a v24 vault to the current SCHEMA_VERSION without throwing", () => {
+    const legacy = buildLegacyV24Vault();
+    expect(() => initSchema(legacy)).not.toThrow();
+    const ver = (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v;
+    expect(ver).toBe(SCHEMA_VERSION);
+  });
+
+  it("post-migration: notes_fts carries path + content columns", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const cols = (legacy.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map(
+      (r) => r.name,
+    );
+    expect(cols).toContain("path");
+    expect(cols).toContain("content");
+  });
+
+  it("post-migration: a note's TITLE is searchable (impossible pre-v25)", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // "beekeeping-notes" (legacy-1's path) never appears in any note's body.
+    const hits = noteOps.searchNotes(legacy, "beekeeping");
+    expect(hits.map((n) => n.id)).toContain("legacy-1");
+  });
+
+  it("post-migration: existing body search still works (no regression from the rebuild)", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const hits = noteOps.searchNotes(legacy, "firefighters");
+    expect(hits.map((n) => n.id)).toContain("legacy-3");
+  });
+
+  it("post-migration: porter stemming matches a regular-affix variant not present verbatim", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // legacy-3's body has "firefighters" (plural) — singular query must match.
+    const hits = noteOps.searchNotes(legacy, "firefighter");
+    expect(hits.map((n) => n.id)).toContain("legacy-3");
+  });
+
+  it("post-migration: a title match ranks ABOVE a passing body-only mention, and both carry a score", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // legacy-2's path IS "propolis" (title match); legacy-1's body mentions
+    // "propolis" once in passing (body-only match). Weighted bm25 must rank
+    // the title match first.
+    const hits = noteOps.searchNotes(legacy, "propolis");
+    const ids = hits.map((n) => n.id);
+    expect(ids.indexOf("legacy-2")).toBeLessThan(ids.indexOf("legacy-1"));
+    for (const n of hits) {
+      expect(typeof n.score).toBe("number");
+    }
+    const byId = new Map(hits.map((n) => [n.id, n.score!]));
+    expect(byId.get("legacy-2")!).toBeGreaterThan(byId.get("legacy-1")!);
+  });
+
+  it("post-migration: a note that had NO path (path IS NULL) survived the rebuild and stays body-searchable", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const hits = noteOps.searchNotes(legacy, "firefighters");
+    expect(hits.some((n) => n.id === "legacy-3")).toBe(true);
+  });
+
+  it("post-migration: the FTS index isn't duplicated or corrupted — an integrity-check passes", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // FTS5's built-in consistency check: throws if the shadow tables and
+    // the external-content table have drifted apart (e.g. double-inserted
+    // rows from a repopulation bug).
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+
+  it("migration is idempotent — running initSchema twice does not duplicate rows or throw", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    expect(() => initSchema(legacy)).not.toThrow();
+    const hits = noteOps.searchNotes(legacy, "firefighter");
+    // Exactly one match, not duplicated by a second repopulation pass.
+    expect(hits.filter((n) => n.id === "legacy-3").length).toBe(1);
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+
+  it("migration is idempotent on a vault that was ALREADY on v25 (e.g. a fresh vault) — no rebuild, no data loss", async () => {
+    // `store`/`db` from the outer beforeEach is already a fresh v25 vault.
+    await store.createNote("hello world", { path: "greeting" });
+    expect(() => initSchema(db)).not.toThrow();
+    const hits = await store.searchNotes("hello");
+    expect(hits.length).toBe(1);
+  });
+
+  /**
+   * MUST-FIX (generalist review, #565) — LOAD-BEARING regression guard: the
+   * whole DDL + repopulation runs inside ONE `transaction`, so a crash partway
+   * through can NEVER leave a recreated-but-EMPTY notes_fts (which the
+   * path-column idempotency guard would then treat as "done," leaving search
+   * permanently empty).
+   *
+   * This drives the REAL `migrateToV25` (via `initSchema`) and injects the
+   * crash by monkey-patching `db.prepare` to throw on the repopulation
+   * `INSERT INTO notes_fts(rowid, path, content)` statement — a faithful
+   * mid-migration interruption AFTER the rebuild DDL (which runs via
+   * `db.exec`, untouched by the patch) but during repopulation. It does NOT
+   * hand-roll its own copy of the DDL: an earlier draft did, which made it a
+   * generic "transaction() rolls back DDL" test that stayed green even against
+   * the pre-fix unwrapped-DDL code. Driving `initSchema` means the test
+   * actually guards `migrateToV25`'s OWN transaction wrapping — verified by
+   * reverting the fix locally (DDL moved back outside `transaction`) and
+   * confirming this test goes RED (the post-crash `ftsCols()` reads
+   * `["path","content"]`, the guard skips on restart, and recovery search is
+   * empty).
+   *
+   * The load-bearing assertion is (a): post-crash `ftsCols() === ["content"]`
+   * — the rollback restored the pre-v25 shape. Under the unwrapped-DDL
+   * regression the recreated table would still carry `path` here.
+   */
+  it("a REAL interrupted migrateToV25 (crash during repopulation) rolls back to the v24 shape — the next initSchema fully recovers, never silent-empty", () => {
+    const legacy = buildLegacyV24Vault();
+
+    const ftsCols = () =>
+      (legacy.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map((c) => c.name);
+    const ftsShadowTables = () =>
+      (
+        legacy
+          .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'notes_fts%' ORDER BY name")
+          .all() as { name: string }[]
+      ).map((r) => r.name);
+
+    // Sanity: starts on the OLD single-column shape.
+    expect(ftsCols()).toEqual(["content"]);
+    const shadowsBefore = ftsShadowTables();
+
+    // Monkey-patch prepare so migrateToV25's repopulation INSERT throws —
+    // everything else (earlier migrations, the guard's PRAGMA, the
+    // repopulation SELECT, the DDL via db.exec) delegates to the real prepare.
+    const origPrepare = legacy.prepare.bind(legacy);
+    let injected = false;
+    (legacy as any).prepare = (sql: string) => {
+      if (!injected && /INSERT INTO notes_fts\(rowid, path, content\)/.test(sql)) {
+        injected = true;
+        throw new Error("simulated crash during notes_fts repopulation");
+      }
+      return origPrepare(sql);
+    };
+
+    // initSchema runs the whole migration chain; migrateToV25 throws mid-repopulation.
+    expect(() => initSchema(legacy)).toThrow("simulated crash during notes_fts repopulation");
+    // Positive control: the injection actually fired (not a vacuous pass).
+    expect(injected).toBe(true);
+
+    // Restore the real prepare for the assertions + recovery run.
+    (legacy as any).prepare = origPrepare;
+
+    // (a) LOAD-BEARING: rollback restored the v24 single-column shape. Under
+    //     the pre-fix shape (DDL OUTSIDE the transaction) this reads
+    //     ["path","content"], the hasColumn(notes_fts,"path") guard skips on
+    //     restart, and search stays silently empty forever.
+    expect(ftsCols()).toEqual(["content"]);
+    // schema_version never advanced past the fixture's 24.
+    expect(
+      (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v,
+    ).toBe(24);
+    // No orphaned/duplicated FTS shadow tables — the set is exactly what it was.
+    expect(ftsShadowTables()).toEqual(shadowsBefore);
+    // The restored v24 index is intact + consistent (integrity-check passes).
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+
+    // (b) A clean restart re-runs the REAL migration and fully populates
+    //     search — both a title-only term and a body term are findable.
+    initSchema(legacy);
+    expect(ftsCols()).toContain("path");
+    expect(noteOps.searchNotes(legacy, "beekeeping").map((n) => n.id)).toContain("legacy-1"); // title-only
+    expect(noteOps.searchNotes(legacy, "firefighters").map((n) => n.id)).toContain("legacy-3"); // body
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+});
+
+describe("search — FTS sync triggers keep path + content current (schema v25)", () => {
+  it("a note created with no path is indexed fine (empty path, not an error)", async () => {
+    const note = await store.createNote("body text only, no title");
+    const hits = await store.searchNotes("body");
+    expect(hits.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("a path-ONLY update (content untouched) is now synced to the index — pre-v25 this was invisible to notes_fts", async () => {
+    const note = await store.createNote("unrelated body text", { path: "oldtitle" });
+    expect((await store.searchNotes("oldtitle")).map((n) => n.id)).toContain(note.id);
+    await store.updateNote(note.id, { path: "newtitle" });
+    expect((await store.searchNotes("newtitle")).map((n) => n.id)).toContain(note.id);
+    expect((await store.searchNotes("oldtitle")).map((n) => n.id)).not.toContain(note.id);
+  });
+
+  it("deleting a note removes it from both the path and content index", async () => {
+    const note = await store.createNote("nothing in the body matches this term", {
+      path: "uniquetitleterm",
+    });
+    expect((await store.searchNotes("uniquetitleterm")).map((n) => n.id)).toContain(note.id);
+    expect((await store.searchNotes("nothing")).map((n) => n.id)).toContain(note.id);
+    await store.deleteNote(note.id);
+    expect((await store.searchNotes("uniquetitleterm")).map((n) => n.id)).not.toContain(note.id);
+    expect((await store.searchNotes("nothing")).map((n) => n.id)).not.toContain(note.id);
+  });
+});

package/core/src/types.ts

@@ -57,6 +57,21 @@ export interface Note {
    * for the exact degree semantics (self-loop = 2 under `both`).
    */
   linkCount?: number;
+  /**
+   * Full-text search relevance score (vault#551 WS2C — ranking legibility).
+   * ONLY present on results from `search=`/`query-notes{search}` — every
+   * other read path (structured `queryNotes`, `getNoteById`, ...) leaves
+   * this `undefined`. Higher is more relevant — the sign-flipped weighted
+   * `bm25(notes_fts, SEARCH_WEIGHT_PATH, SEARCH_WEIGHT_CONTENT)` value (raw
+   * SQLite bm25 is negative-is-better; flipped here so external callers get
+   * the more intuitive "bigger number wins" convention). Meaningful only
+   * for RELATIVE comparison within one result set — the absolute magnitude
+   * has no fixed scale and isn't comparable across different queries. When
+   * an explicit `sort: "asc"|"desc"` overrides relevance ordering, `score`
+   * is still computed and returned (for legibility) even though it no
+   * longer determines the result order.
+   */
+  score?: number;
 }
 
 // ---- Link ----
@@ -248,6 +263,11 @@ export interface NoteIndex {
   preview: string;
   /** Opt-in link degree (see `Note.linkCount`). */
   linkCount?: number;
+  /** Full-text search relevance score (see `Note.score`). Carried onto the
+   *  lean shape too — search's default response IS the lean `NoteIndex[]`
+   *  (`include_content` is opt-in), so `score` would be invisible in the
+   *  common case if it only lived on the full `Note` shape. */
+  score?: number;
 }
 
 /** Link with hydrated note summaries. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.0-rc.6",
+  "version": "0.7.0-rc.7",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/contract-search.test.ts

@@ -316,6 +316,111 @@ describe("contract: search — escaping edge cases, tag-scope, warnings (#551)",
   });
 });
 
+describe("contract: search — recall + ranking legibility (WS2B/C, #551, schema v25)", () => {
+  it("a note's TITLE (path) is now searchable — a term appearing ONLY in path, not content", async () => {
+    await store.createNote("nothing in this body matches the query term", {
+      path: "quarterly-budget-review",
+    });
+    const res = await search("search=budget&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.some((n: any) => n.path === "quarterly-budget-review")).toBe(true);
+  });
+
+  it("a title match outranks a passing body-only mention — legible via the score field", async () => {
+    await store.createNote("only a passing mention of espresso here, nothing more", {
+      path: "coffee-notes",
+    });
+    await store.createNote("everything about espresso — brewing, grinding, tasting", {
+      path: "espresso",
+    });
+    const res = await search("search=espresso&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const titleMatchIdx = body.findIndex((n: any) => n.path === "espresso");
+    const bodyMatchIdx = body.findIndex((n: any) => n.path === "coffee-notes");
+    expect(titleMatchIdx).toBeGreaterThanOrEqual(0);
+    expect(bodyMatchIdx).toBeGreaterThanOrEqual(0);
+    expect(titleMatchIdx).toBeLessThan(bodyMatchIdx);
+    for (const n of body) expect(typeof n.score).toBe("number");
+    const scoreOf = (path: string) => body.find((n: any) => n.path === path).score;
+    expect(scoreOf("espresso")).toBeGreaterThan(scoreOf("coffee-notes"));
+  });
+
+  it("score is present on the LEAN (default, no include_content) shape too", async () => {
+    await store.createNote(NOTES.bothWords);
+    const res = await search("search=widgets");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.length).toBeGreaterThan(0);
+    for (const n of body) expect(typeof n.score).toBe("number");
+  });
+
+  it("porter stemming: singular query matches a plural-only body word", async () => {
+    await store.createNote("the firefighters responded quickly to the call");
+    const res = await search("search=firefighter&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.some((n: any) => n.content.includes("firefighters"))).toBe(true);
+  });
+
+  it("a zero-result search with a nearby indexed term surfaces a search_did_you_mean warning", async () => {
+    await store.createNote("a note that discusses Vasquez and the incident report");
+    const res = await search("search=Vasqez");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const w = warnings!.find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+
+  it("a genuinely zero-result search with NO close vocabulary match carries no did_you_mean warning", async () => {
+    await store.createNote(NOTES.bothWords);
+    const res = await search("search=zzzznonexistentword");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    if (warnings) {
+      expect(warnings.some((w: any) => w.code === "search_did_you_mean")).toBe(false);
+    }
+  });
+
+  it("did_you_mean is suppressed for a tag-scoped session (no leak of vault-wide vocabulary)", async () => {
+    // Out-of-scope note carries the near-match term; the scoped token's
+    // own allowlist ("health") sees nothing else. The did_you_mean
+    // suggestion is computed against the WHOLE vault's FTS5 vocabulary
+    // regardless of scope, so a scoped caller must never see it — same
+    // "no leak" stance as `unknown_tag`'s did_you_mean.
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+    const scopedReq = new Request(`${BASE}/notes?search=Vasqez`, { method: "GET" });
+    const res = await handleNotes(scopedReq, store, "", undefined, {
+      allowed: new Set(["health"]),
+      raw: ["health"],
+    });
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w: any) => w.code === "search_did_you_mean")).toBeFalsy();
+  });
+
+  it('search_mode:"advanced" — a lone leading hyphen gets a caller-actionable hint, not raw "no such column" text', async () => {
+    await store.createNote("espresso and coffee content");
+    const res = await search(`search=${encodeURIComponent("-espresso")}&search_mode=advanced`);
+    expect(res.status).toBe(400);
+    const body = await bodyOf(res);
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error_type).toBe("invalid_search_syntax");
+    expect(typeof body.hint).toBe("string");
+    expect(body.hint).toMatch(/BINARY operator/i);
+    expect(body.hint).not.toMatch(/^no such column/i);
+  });
+});
+
 describe("contract: search — MCP parity (#551)", () => {
   it("query-notes: literal-by-default finds punctuation content the same as REST", async () => {
     const tools = generateMcpTools(store);
@@ -356,4 +461,67 @@ describe("contract: search — MCP parity (#551)", () => {
     const desc = (await query.execute({ search: "mcpsortprobe", sort: "desc", include_content: true })) as any[];
     expect(desc.map((n: any) => n.content)).toEqual(["mcpsortprobe beta", "mcpsortprobe alpha"]);
   });
+
+  it("query-notes: title match outranks a body-only mention, and results carry a score (parity with REST)", async () => {
+    await store.createNote("only a passing mention of espresso here, nothing more", { path: "coffee-notes" });
+    await store.createNote("everything about espresso — brewing, grinding, tasting", { path: "espresso" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "espresso" })) as any[];
+    const titleIdx = result.findIndex((n: any) => n.path === "espresso");
+    const bodyIdx = result.findIndex((n: any) => n.path === "coffee-notes");
+    expect(titleIdx).toBeGreaterThanOrEqual(0);
+    expect(bodyIdx).toBeGreaterThanOrEqual(0);
+    expect(titleIdx).toBeLessThan(bodyIdx);
+    for (const n of result) expect(typeof n.score).toBe("number");
+  });
+
+  it("query-notes: a note's title (path) is searchable (parity with REST)", async () => {
+    await store.createNote("nothing in this body matches the query term", { path: "quarterly-budget-review" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "budget" })) as any[];
+    expect(result.some((n: any) => n.path === "quarterly-budget-review")).toBe(true);
+  });
+
+  it("query-notes: porter stemming matches a plural-only body word (parity with REST)", async () => {
+    await store.createNote("the firefighters responded quickly to the call");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "firefighter", include_content: true })) as any[];
+    expect(result.some((n: any) => n.content.includes("firefighters"))).toBe(true);
+  });
+
+  it("query-notes: zero-result search with a nearby indexed term surfaces search_did_you_mean", async () => {
+    await store.createNote("a note that discusses Vasquez and the incident report");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "Vasqez" })) as any;
+    // Zero notes + a non-empty warnings array — per the response-shape
+    // contract (vault#550) that's the `{notes, warnings}` envelope, not a
+    // bare array (a bare array can't carry `warnings` at all).
+    expect(Array.isArray(result)).toBe(false);
+    expect(result.notes).toEqual([]);
+    expect(result.warnings).toBeDefined();
+    const w = result.warnings.find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+
+  it('query-notes: search_mode:"advanced" — a lone leading hyphen gets a caller-actionable hint, not raw "no such column" text', async () => {
+    await store.createNote("espresso and coffee content");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await query.execute({ search: "-espresso", search_mode: "advanced" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.error_type).toBe("invalid_search_syntax");
+    expect(typeof err.hint).toBe("string");
+    expect(err.hint).toMatch(/BINARY operator/i);
+    expect(err.hint).not.toMatch(/^no such column/i);
+  });
 });

package/src/mcp-query-notes-search-scope.test.ts

@@ -134,3 +134,56 @@ describe("MCP query-notes search × tag-scope — combined enforcement (vault#55
     }
   });
 });
+
+/**
+ * NIT 1 (auth-561 review, #565): did_you_mean on a zero-result search is
+ * computed against the WHOLE vault's FTS5 vocabulary regardless of scope
+ * (`computeSearchDidYouMean` is scope-unaware by architecture, like every
+ * warning core produces). The MCP query-notes wrapper
+ * (`applyTagScopeWrappers`, src/mcp-tools.ts) strips the ENTIRE `warnings`
+ * array for a tag-scoped session, which covers `search_did_you_mean`
+ * generically — but the security property (a scoped token must not learn an
+ * out-of-scope note's vocabulary via a spelling suggestion) deserves a
+ * direct test, mirroring the REST test in src/contract-search.test.ts.
+ */
+function warningsOf(result: unknown): any[] {
+  if (result && typeof result === "object" && "warnings" in result && Array.isArray((result as any).warnings)) {
+    return (result as any).warnings;
+  }
+  return [];
+}
+
+describe("MCP query-notes did_you_mean × tag-scope suppression (#565 NIT 1)", () => {
+  test("a scoped session's zero-result search does NOT surface an out-of-scope term via search_did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // The near-match term "Vasquez" lives ONLY in an out-of-scope note.
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const scopedResult = await scopedTool.execute({ search: "Vasqez" }); // typo → zero results
+    expect(idsOf(scopedResult)).toEqual([]);
+    // The wrapper strips warnings wholesale for a scoped session — no
+    // search_did_you_mean leaking the out-of-scope "vasquez".
+    expect(warningsOf(scopedResult).some((w: any) => w.code === "search_did_you_mean")).toBe(false);
+    // Belt-and-suspenders: the out-of-scope term must not appear ANYWHERE in
+    // the serialized response (no did_you_mean field slipping through under a
+    // different shape).
+    expect(JSON.stringify(scopedResult).toLowerCase()).not.toContain("vasquez");
+  });
+
+  test("control: an UNSCOPED session's zero-result search DOES surface the suggestion (proves it's suppressed by scope, not simply absent)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+
+    const unscopedTool = await queryNotesTool("journal", null);
+    const result = await unscopedTool.execute({ search: "Vasqez" });
+    expect(idsOf(result)).toEqual([]);
+    const w = warningsOf(result).find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+});

package/src/routes.ts

@@ -13,7 +13,14 @@
 
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
-import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "../core/src/query-warnings.ts";
+import {
+  collectUnknownTagWarnings,
+  emptySearchWarning,
+  ignoredParamWarning,
+  computeSearchDidYouMean,
+  searchDidYouMeanWarning,
+  type QueryWarning,
+} from "../core/src/query-warnings.ts";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "../core/src/search-query.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { transactionAsync } from "../core/src/txn.ts";
@@ -1103,6 +1110,22 @@ async function handleNotesInner(
             }
             throw e;
           }
+          // Zero-result `did_you_mean` (vault#551 WS2B) — cheap (a bounded
+          // FTS5-vocabulary scan) and ONLY computed on the already-rare
+          // empty-result path, mirroring `unknown_tag`'s did_you_mean.
+          // Gated on `tagScope.allowed === null` (unscoped) — same stance
+          // as `collectUnknownTagWarnings` below: the FTS5 vocabulary spans
+          // the whole vault regardless of scope, so surfacing a suggestion
+          // to a scoped token would leak out-of-scope content's existence
+          // across the scope boundary. Unlike the MCP path, REST enforces
+          // tag-scope inline (no post-hoc wrapper to strip it for us), so
+          // the gate has to live here explicitly.
+          if (rawResults.length === 0 && tagScope.allowed === null) {
+            const suggestion = computeSearchDidYouMean(db, search);
+            if (suggestion) {
+              searchWarnings.push(searchDidYouMeanWarning(search, suggestion));
+            }
+          }
         }
         // Tag-scope: drop any result the token isn't permitted to see. Filter
         // happens after the store query so an empty post-filter list still