@openparachute/vault 0.7.0-rc.2 → 0.7.0-rc.3

package/core/src/mcp.ts

@@ -5,7 +5,8 @@ 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, type QueryWarning } from "./query-warnings.js";
+import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, 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";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -243,7 +244,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 Response shape (vault#550 — three variants, pick by what you passed):
 - Default (no \`cursor\`, no warnings): a bare array of notes.
 - 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.`,
+- 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.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -297,7 +300,17 @@ Response shape (vault#550 — three variants, pick by what you passed):
             ],
             description: "Filter by file extension (vault#328). Pass a single extension (e.g. \"csv\") or an array (e.g. [\"csv\", \"yaml\", \"json\"]). Notes default to \"md\"; case-insensitive match.",
           },
-          search: { type: "string", description: "Full-text search query" },
+          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.',
+          },
+          search_mode: {
+            type: "string",
+            enum: [...SEARCH_MODES],
+            description:
+              'How `search` text is turned into an FTS5 query (vault#551). "literal" (DEFAULT): escape + phrase-quote the text so punctuation is literal content, not FTS5 syntax — the fix for `search: "didn\'t"` / "eleven-day" / "18.6" silently returning `[]`. "advanced": pass the text through to FTS5 raw, for callers who want boolean (AND/OR/NOT), manual phrase quoting, or prefix (`*`) syntax — a malformed advanced query throws a structured error (`error_type: "invalid_search_syntax"`) instead of silently returning `[]`. Has no effect without `search` (an `ignored_param` warning fires if you pass it without `search`). Omit for the default ("literal").',
+          },
           metadata: {
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
@@ -328,7 +341,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
             required: ["note_id"],
             description: "Scope results to notes within N hops of an anchor note",
           },
-          sort: { type: "string", enum: ["asc", "desc"], description: "Sort by created_at" },
+          sort: {
+            type: "string",
+            enum: ["asc", "desc"],
+            description:
+              'Sort by created_at. Under a structured query this is the only ordering (default "asc"). Under `search` (vault#551): omit for FTS5 relevance ranking (default, unchanged) — pass "asc"/"desc" to EXPLICITLY switch to created_at ordering instead of relevance.',
+          },
           limit: { type: "number", description: "Max results (default 50)" },
           offset: { type: "number", description: "Pagination offset (default 0)" },
           cursor: {
@@ -502,13 +520,37 @@ Response shape (vault#550 — three variants, pick by what you passed):
           expand = params.expand as TagExpandMode;
         }
 
+        // `search_mode` (vault#551) — validate loudly (same policy as
+        // `expand` above) so a typo'd value doesn't silently fall back to
+        // the default. Resolved here (before the search/structured branch)
+        // because BOTH branches need to know whether it was passed: the
+        // search branch to select escaping behavior, the structured branch
+        // to warn that it's being ignored.
+        let searchMode: SearchMode | undefined;
+        if (params.search_mode !== undefined && params.search_mode !== null) {
+          if (typeof params.search_mode !== "string" || !isValidSearchMode(params.search_mode)) {
+            throw new QueryError(
+              `invalid \`search_mode\` value ${JSON.stringify(params.search_mode)} — must be one of ${SEARCH_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("literal").`,
+              "INVALID_QUERY",
+              {
+                error_type: "invalid_query",
+                field: "search_mode",
+                got: params.search_mode,
+                hint: `pass "literal" or "advanced", or omit for the default ("literal")`,
+              },
+            );
+          }
+          searchMode = params.search_mode;
+        }
+
         // --- Full-text search ---
         let results: Note[];
         let nextCursor: string | null = null;
-        // Warnings channel (vault#550) — structured-query only for this
-        // wave; `search=` is out of scope (see #551). Scope-unaware by
-        // design (see `core/src/query-warnings.ts` doc comment) — a
-        // tag-scoped MCP session gets these stripped by the
+        // Warnings channel (vault#550). `search=` warnings (`empty_search`,
+        // `ignored_param` for a stray `search_mode`) joined the channel at
+        // #551 — the rest (`unknown_tag`) stays structured-query only.
+        // Scope-unaware by design (see `core/src/query-warnings.ts` doc
+        // comment) — a tag-scoped MCP session gets these stripped by the
         // `applyTagScopeWrappers` query-notes wrapper in `src/mcp-tools.ts`
         // before the result reaches the caller, so an out-of-scope tag name
         // never leaks via `did_you_mean`.
@@ -516,18 +558,47 @@ Response shape (vault#550 — three variants, pick by what you passed):
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
-          // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
-          // tag-hierarchy expansion fires for MCP callers the same as for
-          // HTTP REST callers — `tag: "manual"` matches descendants declared
-          // via `_tags/*` config notes. Mirrors the structured-query fix
-          // from #214; same class of bypass bug (tracked as #227).
-          results = await store.searchNotes(params.search as string, {
-            tags,
-            limit: (params.limit as number) ?? 50,
-            expand,
-          });
+          const mode: SearchMode = searchMode ?? "literal";
+          // "Only whitespace/quotes" (vault#551 edge case): short-circuit
+          // BEFORE ever calling FTS5 — an empty/all-punctuation phrase can
+          // be a syntax error (or a meaningless always-empty query)
+          // depending on exactly how it degenerates, so this is checked
+          // here rather than left to the DB layer to (maybe) reject.
+          if (mode === "literal" && buildLiteralSearchQuery(params.search as string).isEmpty) {
+            results = [];
+            queryWarnings.push(emptySearchWarning());
+          } else {
+            // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
+            // tag-hierarchy expansion fires for MCP callers the same as for
+            // HTTP REST callers — `tag: "manual"` matches descendants declared
+            // via `_tags/*` config notes. Mirrors the structured-query fix
+            // from #214; same class of bypass bug (tracked as #227). A
+            // malformed advanced-mode query throws here (structured
+            // `invalid_search_syntax`, vault#551) — uncaught on purpose, it
+            // propagates to `src/mcp-http.ts`, which maps it to a JSON-RPC
+            // error the same way it maps `invalid_query`.
+            results = await store.searchNotes(params.search as string, {
+              tags,
+              limit: (params.limit as number) ?? 50,
+              expand,
+              mode,
+              sort: params.sort as "asc" | "desc" | undefined,
+            });
+          }
         } else {
           // --- Structured query ---
+          // `search_mode` only shapes how `search` text becomes an FTS5
+          // query — passing it without `search` is almost always a mistake
+          // (meant to pass `search` too), so flag it rather than silently
+          // doing nothing with it.
+          if (searchMode !== undefined) {
+            queryWarnings.push(
+              ignoredParamWarning(
+                "search_mode",
+                "no `search` was provided — search_mode only affects full-text search query parsing",
+              ),
+            );
+          }
           const tags = normalizeTags(params.tag);
           // Accept canonical `exclude_tags` plus camelCase / singular aliases.
           // LLM callers frequently pick the wrong name (training-data drift
@@ -574,7 +645,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
             offset: params.offset as number | undefined,
             cursor: cursorMode ? (params.cursor as string) : undefined,
           };
-          queryWarnings = collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy());
+          // Concatenate (not overwrite) — `queryWarnings` may already carry
+          // the `ignored_param` warning for a stray `search_mode` pushed
+          // above (vault#551).
+          queryWarnings = queryWarnings.concat(
+            collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy()),
+          );
           if (cursorMode) {
             const page = await store.queryNotesPaged(queryOpts);
             results = page.notes;

package/core/src/notes.ts

@@ -22,6 +22,7 @@ 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";
 
 let idCounter = 0;
 
@@ -1309,12 +1310,78 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
   return { notes, next_cursor };
 }
 
+/**
+ * Turn a thrown FTS5 MATCH error into the structured `invalid_search_syntax`
+ * shape (vault#551, WS2A item 2). ALWAYS structured, never a raw rethrow —
+ * a raw `SQLiteError` escaping to the transport is an unstructured 500
+ * (REST) / generic `isError` text (MCP), which is exactly the swallowed-
+ * failure class this wave is closing.
+ *
+ * The two modes carry different hints:
+ *   - advanced: the caller passed raw FTS5 syntax that FTS5 rejected — tell
+ *     them to fix it or drop back to literal.
+ *   - literal: escaping + control-char sanitization
+ *     (`buildLiteralSearchQuery`) make every input syntactically valid
+ *     FTS5, so this is unreachable by construction — the belt-and-suspenders
+ *     structured error (rather than a raw rethrow) means that IF the
+ *     invariant is ever broken it still surfaces as an honest error, not a
+ *     500. Signals a vault bug worth reporting.
+ */
+function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): QueryError {
+  const causeMessage = err instanceof Error ? err.message : String(err);
+  const hint =
+    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.`;
+  return new QueryError(`invalid search syntax: ${causeMessage}`, "INVALID_QUERY", {
+    error_type: "invalid_search_syntax",
+    field: "search",
+    got: rawQuery,
+    hint,
+  });
+}
+
 export function searchNotes(
   db: Database,
   query: string,
-  opts?: { tags?: string[]; limit?: number },
+  opts?: { tags?: string[]; limit?: number; mode?: SearchMode; sort?: "asc" | "desc" },
 ): Note[] {
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
+  // Literal-by-default (vault#551): escape the caller's text so FTS5's own
+  // query syntax (hyphen = NOT, apostrophe/period = tokenizer breakage,
+  // etc.) is treated as ordinary content, not syntax. `search_mode:
+  // "advanced"` opts back into raw FTS5 query syntax — today's pre-#551
+  // behavior, unchanged — for callers who want boolean/phrase/prefix
+  // operators.
+  const mode: SearchMode = opts?.mode ?? "literal";
+  let ftsQuery: string;
+  if (mode === "literal") {
+    const built = buildLiteralSearchQuery(query);
+    // "Only whitespace/quotes" (vault#551 edge case): the caller (store.ts /
+    // the REST + MCP entry points) is expected to short-circuit this case
+    // itself (with an `empty_search` warning) before ever reaching here —
+    // this is a defensive fallback for any direct-core caller that skips
+    // that check.
+    if (built.isEmpty) return [];
+    ftsQuery = built.query;
+  } else {
+    ftsQuery = query;
+  }
+
+  // `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).
+  const orderBy =
+    opts?.sort === "asc"
+      ? "n.created_at ASC, n.id ASC"
+      : opts?.sort === "desc"
+        ? "n.created_at DESC, n.id DESC"
+        : "rank";
 
   if (opts?.tags && opts.tags.length > 0) {
     // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
@@ -1334,12 +1401,19 @@ export function searchNotes(
         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 rank
+        ORDER BY ${orderBy}
         LIMIT ?
-      `).all(query, ...searchTags, limit) as NoteRow[];
+      `).all(ftsQuery, ...searchTags, limit) as NoteRow[];
       return notesWithTags(db, rows);
-    } catch {
-      return [];
+    } catch (err) {
+      // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
+      // advanced mode expects it (the caller passed raw syntax); literal
+      // mode should never reach it (escaping + control-char sanitization
+      // make the query valid) but if the invariant breaks we still want an
+      // honest error, not an unstructured 500. A QueryError we threw
+      // ourselves (empty-limit validation, etc.) is re-raised untouched.
+      if (err instanceof QueryError) throw err;
+      throw searchSyntaxError(query, err, mode);
     }
     }
   }
@@ -1349,12 +1423,13 @@ export function searchNotes(
       SELECT n.* FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
-      ORDER BY rank
+      ORDER BY ${orderBy}
       LIMIT ?
-    `).all(query, limit) as NoteRow[];
+    `).all(ftsQuery, limit) as NoteRow[];
     return notesWithTags(db, rows);
-  } catch {
-    return [];
+  } catch (err) {
+    if (err instanceof QueryError) throw err;
+    throw searchSyntaxError(query, err, mode);
   }
 }
 

package/core/src/query-warnings.ts

@@ -182,3 +182,38 @@ export function collectUnknownTagWarnings(
   }
   return warnings;
 }
+
+/**
+ * `empty_search` warning (vault#551) — the `search` string carried no
+ * literal content: blank/whitespace-only, or (in literal mode, where a
+ * manually-typed `"` is ordinary content rather than syntax) nothing but
+ * quote characters. Rather than let this degenerate into an FTS5 syntax
+ * error or a confusing always-empty-but-syntactically-valid query, the
+ * search path short-circuits BEFORE ever calling FTS5 and reports this
+ * warning alongside an honest `[]`. See `core/src/search-query.ts`
+ * `buildLiteralSearchQuery`, which is the choke point that detects this.
+ */
+export function emptySearchWarning(): QueryWarning {
+  return {
+    code: "empty_search",
+    message:
+      "the search query has no literal content (blank, or only whitespace/quote characters) — returning no results without querying FTS5.",
+  };
+}
+
+/**
+ * `ignored_param` warning (vault#551) — a query-shaping param was passed
+ * but has no effect given the rest of the request. First (and so far only)
+ * case: `search_mode` without `search` — the mode only shapes how `search`
+ * text is turned into an FTS5 query, so passing it alone almost always
+ * means the caller meant to pass `search` too. Generic over `param` /
+ * `reason` so a future ignored-param case can reuse the same shape instead
+ * of inventing a new warning code.
+ */
+export function ignoredParamWarning(param: string, reason: string): QueryWarning {
+  return {
+    code: "ignored_param",
+    message: `\`${param}\` has no effect: ${reason}`,
+    param,
+  };
+}

package/core/src/search-query.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "bun:test";
+import {
+  SEARCH_MODES,
+  escapeFtsToken,
+  buildLiteralSearchQuery,
+  isValidSearchMode,
+} from "./search-query.js";
+
+describe("escapeFtsToken", () => {
+  it("wraps a plain token in quotes", () => {
+    expect(escapeFtsToken("widgets")).toBe(`"widgets"`);
+  });
+
+  it("doubles an embedded quote", () => {
+    expect(escapeFtsToken(`say"hi`)).toBe(`"say""hi"`);
+  });
+
+  it("doubles multiple embedded quotes", () => {
+    expect(escapeFtsToken(`"eleven-day`)).toBe(`"""eleven-day"`);
+    expect(escapeFtsToken(`delay"`)).toBe(`"delay"""`);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(escapeFtsToken("eleven-day")).toBe(`"eleven-day"`);
+    expect(escapeFtsToken("18.6")).toBe(`"18.6"`);
+    expect(escapeFtsToken("didn't")).toBe(`"didn't"`);
+  });
+});
+
+describe("buildLiteralSearchQuery", () => {
+  it("wraps a single token", () => {
+    const r = buildLiteralSearchQuery("widgets");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("phrase-quotes each whitespace-delimited token and ANDs them (vault#551 root fix)", () => {
+    const r = buildLiteralSearchQuery("eleven-day capping delay");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"eleven-day" "capping" "delay"`);
+  });
+
+  it("escapes an apostrophe as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("didn't");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"didn't"`);
+  });
+
+  it("escapes a decimal point as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("18.6");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"18.6"`);
+  });
+
+  it("collapses runs of whitespace between tokens", () => {
+    const r = buildLiteralSearchQuery("widgets    gadgets");
+    expect(r.query).toBe(`"widgets" "gadgets"`);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    const r = buildLiteralSearchQuery("  widgets  ");
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("escapes a manually-quoted phrase's embedded quote characters as content", () => {
+    // The user typed literal quote marks expecting phrase syntax; in
+    // literal mode those quote characters are just more content that gets
+    // escaped like anything else (vault#551 — this is CORRECT, not a bug:
+    // raw phrase/boolean/prefix syntax now requires search_mode:"advanced").
+    const r = buildLiteralSearchQuery(`"eleven-day capping delay"`);
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"""eleven-day" "capping" "delay"""`);
+  });
+
+  it("treats a blank string as empty", () => {
+    expect(buildLiteralSearchQuery("").isEmpty).toBe(true);
+  });
+
+  it("treats a whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery("   ").isEmpty).toBe(true);
+  });
+
+  it("treats a lone quote character as empty", () => {
+    expect(buildLiteralSearchQuery(`"`).isEmpty).toBe(true);
+  });
+
+  it("treats a quotes-and-whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery(`"  "  "`).isEmpty).toBe(true);
+  });
+
+  it("an empty-flagged result never carries a query string callers should use", () => {
+    const r = buildLiteralSearchQuery("   ");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  // Control-character sanitization (vault#551 review fold) — a NUL byte
+  // (or any C0/DEL control) inside a token would otherwise crash FTS5's
+  // C-string parser with a raw `unterminated string` error, breaking the
+  // "literal mode cannot throw" guarantee.
+  it("splits a token on an embedded NUL byte — both halves stay searchable", () => {
+    const r = buildLiteralSearchQuery("hello\x00world");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("treats a NUL-only string as empty (short-circuits, never reaches FTS5)", () => {
+    const r = buildLiteralSearchQuery("\x00");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  it("collapses a run of NUL/control bytes between tokens like whitespace", () => {
+    const r = buildLiteralSearchQuery("hello\x00\x00world");
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("sanitizes the other C0 controls and DEL (0x01-0x1F, 0x7F) as separators too", () => {
+    expect(buildLiteralSearchQuery("a\x01\x02b").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x1fb").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x7fb").query).toBe(`"a" "b"`);
+  });
+
+  it("a control byte adjacent to a real token still yields the clean token", () => {
+    expect(buildLiteralSearchQuery("\x00hello\x00").query).toBe(`"hello"`);
+  });
+});
+
+describe("isValidSearchMode / SEARCH_MODES", () => {
+  it("SEARCH_MODES is exactly literal + advanced", () => {
+    expect(SEARCH_MODES).toEqual(["literal", "advanced"]);
+  });
+
+  it("accepts literal and advanced", () => {
+    expect(isValidSearchMode("literal")).toBe(true);
+    expect(isValidSearchMode("advanced")).toBe(true);
+  });
+
+  it("rejects an unknown string", () => {
+    expect(isValidSearchMode("bogus")).toBe(false);
+  });
+
+  it("rejects non-string values", () => {
+    expect(isValidSearchMode(123)).toBe(false);
+    expect(isValidSearchMode(null)).toBe(false);
+    expect(isValidSearchMode(undefined)).toBe(false);
+    expect(isValidSearchMode(["literal"])).toBe(false);
+  });
+});

package/core/src/store.ts

@@ -34,6 +34,7 @@ import {
   countConformanceViolations,
   type ConformanceReport,
 } from "./conformance.js";
+import type { SearchMode } from "./search-query.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -375,7 +376,7 @@ export class BunSqliteStore implements Store {
     return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
-  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]> {
     // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
     // filters before expansion, so `#manual` and `manual` resolve identically.
     if (opts?.tags && opts.tags.length > 0) {

package/core/src/types.ts

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode, TagHierarchy } from "./tag-hierarchy.js";
+import type { SearchMode } from "./search-query.js";
 import type { ValidationStatus } from "./schema-defaults.js";
 import type { ConformanceReport } from "./conformance.js";
 import type { FindPathResult } from "./links.js";
@@ -314,7 +315,18 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]>;
+  /**
+   * `mode` (vault#551 — literal-by-default): "literal" (default) escapes +
+   * phrase-quotes the query so FTS5 punctuation syntax (hyphen = NOT, an
+   * apostrophe/period breaking the parse, ...) is treated as ordinary
+   * content. "advanced" passes `query` through to FTS5 raw (pre-#551
+   * behavior) for callers who want boolean/phrase/prefix operators — a
+   * syntax error in that mode throws (`error_type: "invalid_search_syntax"`)
+   * rather than silently returning `[]`. `sort` (vault#551): omitted stays
+   * FTS5 relevance ranking (default); an explicit "asc"/"desc" switches to
+   * `created_at` ordering. See `core/src/search-query.ts`.
+   */
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;

package/package.json

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

package/src/contract-search.test.ts

@@ -1,10 +1,16 @@
 /**
- * Contract suite — search (Wave 1 of the Reliability & Usability Program,
- * umbrella #556). Encodes the 2026-07-09 nine-persona deep test's search
- * findings (WS2, #551) as executable tests: PASSING tests lock in behavior
- * that is correct today; `test.todo` entries describe the target behavior
- * for confirmed-broken cases, to be flipped to real assertions in a later
- * wave. See #551 for the full write-up.
+ * Contract suite — search (Wave 1's findings, Wave 3's fix — Reliability &
+ * Usability Program, umbrella #556, WS2A #551). Encodes the 2026-07-09
+ * nine-persona deep test's search findings as executable tests: PASSING
+ * tests lock in behavior that is correct today; the #551 `test.todo`
+ * entries this file used to carry have all been flipped to real assertions
+ * against the literal-by-default fix (escaping, `search_mode: "advanced"`,
+ * honored `sort`, structured `invalid_search_syntax`) — see #551 for the
+ * full write-up. Covers `src/routes.ts` (the REST surface) plus a handful
+ * of MCP-parity checks (`core/src/mcp.ts`) where the two surfaces share one
+ * implementation (`core/src/notes.ts` `searchNotes` + `core/src/search-
+ * query.ts`) and a REST-only test wouldn't prove the MCP side actually got
+ * the fix — mirrors the pattern in `contract-honest-queries.test.ts`.
  *
  * Ground truth for every assertion here was re-verified live against this
  * repo's FTS5 search path (`core/src/notes.ts` searchNotes → REST `GET
@@ -16,6 +22,7 @@ import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { BunStore } from "./vault-store.ts";
 import { handleNotes } from "./routes.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
 
 let db: Database;
 let store: BunStore;
@@ -26,6 +33,13 @@ function search(qs: string): Promise<Response> {
   return handleNotes(new Request(`${BASE}/notes?${qs}`, { method: "GET" }), store, "");
 }
 
+/** Decode the `X-Parachute-Warnings` header (vault#550 — percent-encoded JSON; see `jsonWithWarnings` in routes.ts). */
+function decodeWarningsHeader(res: Response): any[] | null {
+  const raw = res.headers.get("X-Parachute-Warnings");
+  if (!raw) return null;
+  return JSON.parse(decodeURIComponent(raw));
+}
+
 /** Planted corpus — each note exists to exercise exactly one FTS5 quirk. */
 const NOTES = {
   hyphenPhrase: "The rollout had an eleven-day capping delay before it shipped.",
@@ -76,22 +90,36 @@ describe("contract: search — passing (lock in current behavior)", () => {
     expect(body.map((n: any) => n.content)).toEqual([NOTES.bothWords]);
   });
 
-  it('quoted phrase finds hyphenated phrase text: "eleven-day capping delay"', async () => {
-    const res = await search(`search=${encodeURIComponent('"eleven-day capping delay"')}&include_content=true`);
+  // The next three tests manually quote the search string, expecting raw
+  // FTS5 phrase syntax to be honored. That's advanced-mode behavior as of
+  // #551 (literal-by-default escapes a caller's own `"` characters as
+  // ordinary content instead of honoring them as phrase syntax) — updated
+  // to pass `search_mode: "advanced"` explicitly. (Note for reviewers:
+  // empirically the bare literal-mode escaping of these SAME manually-
+  // quoted strings still resolves to the identical result set for this
+  // corpus — FTS5's tokenizer strips the embedded `"` characters the same
+  // way it strips other punctuation — but the semantic guarantee these
+  // tests were written to pin (phrase ADJACENCY honored as syntax) only
+  // holds under advanced mode; literal mode no longer enforces adjacency
+  // at all, it just happens to agree here because no other note contains
+  // a subset of the same words. See #551 test coverage for the literal-
+  // mode equivalents of these same strings, unquoted, further down.)
+  it('quoted phrase finds hyphenated phrase text: "eleven-day capping delay" (search_mode: "advanced")', async () => {
+    const res = await search(`search=${encodeURIComponent('"eleven-day capping delay"')}&search_mode=advanced&include_content=true`);
     expect(res.status).toBe(200);
     const body = await bodyOf(res);
     expect(body.map((n: any) => n.content)).toEqual([NOTES.hyphenPhrase]);
   });
 
-  it('quoted decimal literal finds it: "18.6"', async () => {
-    const res = await search(`search=${encodeURIComponent('"18.6"')}&include_content=true`);
+  it('quoted decimal literal finds it: "18.6" (search_mode: "advanced")', async () => {
+    const res = await search(`search=${encodeURIComponent('"18.6"')}&search_mode=advanced&include_content=true`);
     expect(res.status).toBe(200);
     const body = await bodyOf(res);
     expect(body.map((n: any) => n.content)).toEqual([NOTES.decimal]);
   });
 
-  it('quoted contraction finds it: "didn\'t"', async () => {
-    const res = await search(`search=${encodeURIComponent(`"didn't"`)}&include_content=true`);
+  it('quoted contraction finds it: "didn\'t" (search_mode: "advanced")', async () => {
+    const res = await search(`search=${encodeURIComponent(`"didn't"`)}&search_mode=advanced&include_content=true`);
     expect(res.status).toBe(200);
     const body = await bodyOf(res);
     expect(body.map((n: any) => n.content)).toEqual([NOTES.contraction]);
@@ -105,23 +133,227 @@ describe("contract: search — passing (lock in current behavior)", () => {
   });
 });
 
-describe("contract: search — todo (#551, literal-by-default + recall + ranking)", () => {
-  test.todo(
-    `#551: unquoted search: "didn't" finds the contraction content (literal-by-default — today the bare apostrophe splits into two AND'd tokens and returns [])`,
-  );
-  test.todo(
-    `#551: unquoted search: "eleven-day capping delay" finds the hyphenated-phrase note (literal-by-default — today the bare hyphenated word tokenizes into separate AND'd terms and returns [])`,
-  );
-  test.todo(
-    `#551: unquoted search: "18.6" finds the decimal note (literal-by-default — today the bare decimal tokenizes into separate AND'd terms and returns [])`,
-  );
-  test.todo(
-    `#551: search_mode:"advanced" preserves raw FTS5 query syntax (AND/OR/NOT, phrase, prefix) once literal-by-default escaping ships as the new default`,
-  );
-  test.todo(
-    `#551: sort:"asc"/"desc" changes result order under search (today silently ignored — FTS5 rank order wins regardless of the sort param)`,
-  );
-  test.todo(
-    `#551: malformed FTS syntax (e.g. an unbalanced quote) yields a structured warning or error, not a silently swallowed [] (today searchNotes catches every FTS5 syntax error and returns [])`,
-  );
+describe('contract: search — literal-by-default (#551, flipped from todo)', () => {
+  it(`unquoted search "didn't" finds the contraction content (literal-by-default — the bare apostrophe used to split into two AND'd tokens and return [])`, async () => {
+    const res = await search(`search=${encodeURIComponent("didn't")}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.contraction]);
+  });
+
+  it(`unquoted search "eleven-day capping delay" finds the hyphenated-phrase note (literal-by-default — the bare hyphenated word used to tokenize into a NOT-operator and return [])`, async () => {
+    const res = await search(`search=${encodeURIComponent("eleven-day capping delay")}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.hyphenPhrase]);
+  });
+
+  it(`unquoted search "18.6" finds the decimal note (literal-by-default — the bare decimal used to break the FTS5 parse and return [])`, async () => {
+    const res = await search(`search=${encodeURIComponent("18.6")}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.decimal]);
+  });
+
+  it('search_mode:"advanced" preserves raw FTS5 query syntax (boolean AND/NOT, prefix *)', async () => {
+    const and = await bodyOf(
+      await search(`search=${encodeURIComponent("widgets AND gadgets")}&search_mode=advanced&include_content=true`),
+    );
+    expect(and.map((n: any) => n.content)).toEqual([NOTES.bothWords]);
+
+    const not = await bodyOf(
+      await search(`search=${encodeURIComponent("widgets NOT gadgets")}&search_mode=advanced&include_content=true`),
+    );
+    expect(not.map((n: any) => n.content)).toEqual([NOTES.widgetsOnly]);
+
+    const prefix = await bodyOf(
+      await search(`search=${encodeURIComponent("wid*")}&search_mode=advanced&include_content=true`),
+    );
+    const prefixContents = new Set(prefix.map((n: any) => n.content));
+    expect(prefixContents.has(NOTES.widgetsOnly)).toBe(true);
+    expect(prefixContents.has(NOTES.bothWords)).toBe(true);
+    expect(prefixContents.has(NOTES.gadgetsOnly)).toBe(false);
+  });
+
+  it('sort:"asc"/"desc" changes result order under search (previously silently ignored — FTS5 rank order won regardless of the sort param)', async () => {
+    await store.createNote("sortprobe alpha content", { created_at: "2020-01-01T00:00:00.000Z" });
+    await store.createNote("sortprobe beta content", { created_at: "2022-06-15T00:00:00.000Z" });
+    await store.createNote("sortprobe gamma content", { created_at: "2024-12-31T00:00:00.000Z" });
+
+    const asc = await bodyOf(await search("search=sortprobe&sort=asc&include_content=true"));
+    expect(asc.map((n: any) => n.content)).toEqual([
+      "sortprobe alpha content",
+      "sortprobe beta content",
+      "sortprobe gamma content",
+    ]);
+
+    const desc = await bodyOf(await search("search=sortprobe&sort=desc&include_content=true"));
+    expect(desc.map((n: any) => n.content)).toEqual([
+      "sortprobe gamma content",
+      "sortprobe beta content",
+      "sortprobe alpha content",
+    ]);
+  });
+
+  it("malformed FTS syntax under search_mode:\"advanced\" yields a structured 400 invalid_search_syntax error, not a silently swallowed []", async () => {
+    const res = await search(`search=${encodeURIComponent('"unbalanced')}&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(body.field).toBe("search");
+    expect(body.got).toBe('"unbalanced');
+    expect(typeof body.hint).toBe("string");
+  });
+
+  it("the SAME malformed string in literal mode (default) returns an honest result, not an error — escaping makes it syntactically valid FTS5", async () => {
+    const res = await search(`search=${encodeURIComponent('"unbalanced')}`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toEqual([]);
+  });
+
+  // Review fold: a NUL byte inside a literal-mode token used to crash FTS5's
+  // C-string parser (`SQLiteError: unterminated string`) → raw rethrow →
+  // unstructured 500. Sanitization (control chars → separators) makes it a
+  // normal search. `%00` is the URL-encoding of a NUL byte.
+  it("search=hello%00world (NUL byte in a token) does NOT 500 — literal mode cannot throw", async () => {
+    await store.createNote("hello world reachable across the NUL split", { tags: ["nul"] });
+    const res = await search("search=hello%00world&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(Array.isArray(body)).toBe(true);
+    // The NUL split the token into "hello" AND "world" — both searchable —
+    // so the planted note (containing both words) is found.
+    expect(body.some((n: any) => n.content.includes("hello world reachable"))).toBe(true);
+  });
+
+  it("a NUL-only search short-circuits to [] with an empty_search warning, no 500", async () => {
+    const res = await search("search=%00");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "empty_search")).toBe(true);
+  });
+
+  it("sort under search is STABLE at identical created_at (deterministic n.id tiebreaker, both directions)", async () => {
+    // Two notes at the SAME millisecond — without the id tiebreaker their
+    // relative order would be arbitrary/unstable (review nit).
+    const ts = "2023-03-03T03:03:03.030Z";
+    await store.createNote("tiebreak content one", { id: "tie-aaa", created_at: ts });
+    await store.createNote("tiebreak content two", { id: "tie-bbb", created_at: ts });
+
+    const asc = await bodyOf(await search("search=tiebreak&sort=asc&include_content=true"));
+    const ascIds = asc.map((n: any) => n.id);
+    // ASC id tiebreaker → tie-aaa before tie-bbb.
+    expect(ascIds).toEqual(["tie-aaa", "tie-bbb"]);
+
+    const desc = await bodyOf(await search("search=tiebreak&sort=desc&include_content=true"));
+    const descIds = desc.map((n: any) => n.id);
+    // DESC id tiebreaker → tie-bbb before tie-aaa (the exact reverse).
+    expect(descIds).toEqual(["tie-bbb", "tie-aaa"]);
+  });
+});
+
+describe("contract: search — escaping edge cases, tag-scope, warnings (#551)", () => {
+  it("a double space between tokens still finds the note containing both (whitespace runs collapse)", async () => {
+    const res = await search(`search=${encodeURIComponent("widgets    gadgets")}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.bothWords]);
+  });
+
+  it("whitespace-only search short-circuits to [] with an empty_search warning, no FTS5 call/error", async () => {
+    const res = await search(`search=${encodeURIComponent("   ")}`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "empty_search")).toBe(true);
+  });
+
+  it('a quotes-only search (e.g. a lone `"`) short-circuits to [] with an empty_search warning', async () => {
+    const res = await search(`search=${encodeURIComponent('"')}`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "empty_search")).toBe(true);
+  });
+
+  it("tag-filtered search also gets literal escaping (the tag-scoped FTS prepared statement)", async () => {
+    await store.createNote(NOTES.hyphenPhrase, { tags: ["probe"] });
+    const res = await search(
+      `search=${encodeURIComponent("eleven-day capping delay")}&tag=probe&include_content=true`,
+    );
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.hyphenPhrase]);
+    expect(body[0].tags).toContain("probe");
+  });
+
+  it("search_mode without search is a no-op that surfaces an ignored_param warning (structured-query path)", async () => {
+    const res = await search("search_mode=advanced");
+    expect(res.status).toBe(200);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
+  });
+
+  it("an unrecognized search_mode value is a structured 400 invalid_query", async () => {
+    const res = await search("search=widgets&search_mode=bogus");
+    expect(res.status).toBe(400);
+    const body = await bodyOf(res);
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.field).toBe("search_mode");
+    expect(body.got).toBe("bogus");
+  });
+});
+
+describe("contract: search — MCP parity (#551)", () => {
+  it("query-notes: literal-by-default finds punctuation content the same as REST", async () => {
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "didn't", include_content: true })) as any[];
+    expect(result.map((n: any) => n.content)).toEqual([NOTES.contraction]);
+  });
+
+  it("query-notes: search_mode validation rejects an unknown value", async () => {
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(query.execute({ search: "widgets", search_mode: "bogus" })).rejects.toThrow(/search_mode/);
+  });
+
+  it("query-notes: search_mode without search surfaces an ignored_param warning", async () => {
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search_mode: "advanced" })) as any;
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
+  });
+
+  it("query-notes: search_mode:\"advanced\" + malformed syntax throws a structured invalid_search_syntax error", async () => {
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(
+      query.execute({ search: '"unbalanced', search_mode: "advanced" }),
+    ).rejects.toMatchObject({ error_type: "invalid_search_syntax" });
+  });
+
+  it("query-notes: sort:\"asc\"/\"desc\" changes order under search (parity with REST)", async () => {
+    await store.createNote("mcpsortprobe alpha", { created_at: "2020-01-01T00:00:00.000Z" });
+    await store.createNote("mcpsortprobe beta", { created_at: "2024-01-01T00:00:00.000Z" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const asc = (await query.execute({ search: "mcpsortprobe", sort: "asc", include_content: true })) as any[];
+    expect(asc.map((n: any) => n.content)).toEqual(["mcpsortprobe alpha", "mcpsortprobe beta"]);
+    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"]);
+  });
 });

package/src/mcp-http.ts

@@ -176,6 +176,19 @@ async function handleMcp(
           hint: e.hint,
         });
       }
+      // Advanced-mode full-text search syntax error (vault#551) — a
+      // raw-passthrough FTS5 query that FTS5 itself rejected. Same shape as
+      // `invalid_query` (field/got/hint) but a DISTINCT `error_type` so a
+      // caller can tell "your search_mode:\"advanced\" syntax is malformed"
+      // apart from "your query PARAMS are malformed."
+      if (e?.error_type === "invalid_search_syntax") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "invalid_search_syntax",
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
           error_type: "conflict",

package/src/routes.ts

@@ -13,7 +13,8 @@
 
 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, type QueryWarning } from "../core/src/query-warnings.ts";
+import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, 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";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
@@ -660,6 +661,39 @@ export function parseExpandParam(url: URL): { expand?: TagExpandMode; error?: Re
   return { expand: expandParam as TagExpandMode };
 }
 
+/**
+ * Parse + validate `?search_mode=` (vault#551) — how `search` text is
+ * turned into an FTS5 query. "literal" (default, omit or pass explicitly):
+ * escape + phrase-quote so punctuation is literal content, not FTS5
+ * syntax. "advanced": raw FTS5 passthrough (pre-#551 behavior) for
+ * boolean/phrase/prefix operators. Same validation shape as
+ * `parseExpandParam` — loud 400 on an unknown value rather than a silent
+ * fallback to the default.
+ *
+ * Returns `{ mode }` (undefined when absent/empty → search branch defaults
+ * to "literal") or `{ error }` (a 400 Response) on an unknown value.
+ */
+function parseSearchModeParam(url: URL): { mode?: SearchMode; error?: Response } {
+  const raw = parseQuery(url, "search_mode");
+  if (raw === null || raw === "") return {};
+  if (!isValidSearchMode(raw)) {
+    return {
+      error: json(
+        {
+          error: `invalid \`search_mode\` value "${raw}" — must be one of ${SEARCH_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("literal").`,
+          code: "INVALID_QUERY",
+          error_type: "invalid_query",
+          field: "search_mode",
+          got: raw,
+          hint: `pass "literal" or "advanced", or omit for the default ("literal")`,
+        },
+        400,
+      ),
+    };
+  }
+  return { mode: raw };
+}
+
 /**
  * Parse the shared notes-query parameters (tags / excludeTags / path /
  * pathPrefix / extension / metadata filters / date filters / sort / paging /
@@ -973,11 +1007,54 @@ async function handleNotesInner(
         // value. The validated mode is threaded into the search tag-narrowing.
         const tagExpand = parseExpandParam(url);
         if (tagExpand.error) return tagExpand.error;
-        const rawResults = await store.searchNotes(search, {
-          tags: searchTags,
-          limit,
-          expand: tagExpand.expand,
-        });
+        // `search_mode` (vault#551) — same loud-validation policy as
+        // `expand` above; also bypasses `parseNotesQueryOpts` so it needs
+        // its own check here.
+        const searchModeParsed = parseSearchModeParam(url);
+        if (searchModeParsed.error) return searchModeParsed.error;
+        const mode: SearchMode = searchModeParsed.mode ?? "literal";
+        // `sort` under search (vault#551 item 3): omit for FTS5 relevance
+        // (default, unchanged); explicit asc/desc switches to created_at.
+        const sort = (parseQuery(url, "sort") as "asc" | "desc" | null) ?? undefined;
+
+        const searchWarnings: QueryWarning[] = [];
+        let rawResults: Note[];
+        // "Only whitespace/quotes" (vault#551 edge case) — short-circuit
+        // BEFORE ever calling FTS5 rather than risk a syntax error (or a
+        // meaningless always-empty query) on a degenerate escaped phrase.
+        if (mode === "literal" && buildLiteralSearchQuery(search).isEmpty) {
+          rawResults = [];
+          searchWarnings.push(emptySearchWarning());
+        } else {
+          try {
+            // A malformed `search_mode: "advanced"` query throws here
+            // (structured `invalid_search_syntax`, vault#551) instead of
+            // the pre-#551 silent `[]` — caught below and formatted the
+            // same way the structured-query path formats a `QueryError`.
+            rawResults = await store.searchNotes(search, {
+              tags: searchTags,
+              limit,
+              expand: tagExpand.expand,
+              mode,
+              sort,
+            });
+          } catch (e: any) {
+            if (e && e.name === "QueryError") {
+              return json(
+                {
+                  error: e.message,
+                  code: e.code ?? "INVALID_QUERY",
+                  ...(e.error_type !== undefined ? { error_type: e.error_type } : {}),
+                  ...(e.field !== undefined ? { field: e.field } : {}),
+                  ...(e.got !== undefined ? { got: e.got } : {}),
+                  ...(e.hint !== undefined ? { hint: e.hint } : {}),
+                },
+                400,
+              );
+            }
+            throw e;
+          }
+        }
         // 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
         // returns 200 [] (consistent with "no matches"), not 403.
@@ -1015,7 +1092,7 @@ async function handleNotesInner(
           );
           for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
         }
-        return json(output);
+        return jsonWithWarnings(output, searchWarnings);
       }
 
       // Structured query
@@ -1071,17 +1148,27 @@ async function handleNotesInner(
           400,
         );
       }
-      // Warnings channel (vault#550) — structured-query only for this wave
-      // (search= is out of scope, see #551). Skipped entirely for a
-      // tag-scoped session: `collectUnknownTagWarnings` resolves
-      // `did_you_mean` against the FULL vault-wide tag catalog, which would
-      // leak an out-of-scope tag's existence/name across the scope boundary
-      // — the same "no leak" stance this codebase takes everywhere else
-      // (docs/contracts/tag-scoped-tokens.md). `removed_param` warnings
-      // (below, at the response-shaping stage) carry no tag information and
-      // fire regardless of scope.
+      // Warnings channel (vault#550). `unknown_tag` stays structured-query
+      // only (skipped entirely for a tag-scoped session:
+      // `collectUnknownTagWarnings` resolves `did_you_mean` against the
+      // FULL vault-wide tag catalog, which would leak an out-of-scope tag's
+      // existence/name across the scope boundary — the same "no leak"
+      // stance this codebase takes everywhere else
+      // (docs/contracts/tag-scoped-tokens.md)). `removed_param` warnings
+      // carry no tag information and fire regardless of scope. `search_mode`
+      // without `search` (vault#551) also carries no tag information — this
+      // IS the structured-query path precisely because `search` was absent
+      // or empty, so a `search_mode` param here is always a no-op.
       const queryWarnings: QueryWarning[] = [
         ...collectRemovedParamWarnings(url),
+        ...(parseQuery(url, "search_mode")
+          ? [
+              ignoredParamWarning(
+                "search_mode",
+                "no `search` was provided — search_mode only affects full-text search query parsing",
+              ),
+            ]
+          : []),
         ...(tagScope.allowed === null
           ? collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy())
           : []),

package/src/ws-subscribe.test.ts

@@ -440,6 +440,20 @@ describe("WS live-query — bad query + cap", () => {
     expect((await res.json()).code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
   });
 
+  // vault#551 — literal-by-default search + `search_mode` are a
+  // snapshot/REST-only concept (escaping happens in `core/src/notes.ts`
+  // `searchNotes`, which the live matcher never calls). `search` itself
+  // stays categorically unsupported for live subscriptions regardless of
+  // mode — confirms `search_mode` doesn't accidentally open a bypass.
+  it("rejects an unsupported query with search_mode present too — search_mode doesn't bypass the search rejection", async () => {
+    const { server } = makeServer();
+    const res = await fetch(`http://localhost:${server.port}/vault/${VAULT}/api/subscribe?search=hi&search_mode=advanced`, {
+      headers: { Upgrade: "websocket", Connection: "Upgrade", "Sec-WebSocket-Key": "x", "Sec-WebSocket-Version": "13" },
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()).code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
+  });
+
   it("refuses over the per-vault cap (503) and self-heals when a socket closes", async () => {
     const { binding } = makeServer({ maxSubscriptions: 2 });
     const fakeWs = (): { data: SubscribeWsData; close(): void; send(): void } => ({