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

package/src/contract-errors.test.ts

@@ -4,15 +4,16 @@
  * nine-persona deep test's WS5 findings (#554) as executable tests: PASSING
  * tests lock in the structured-error precedents that already exist
  * (`path_conflict`, `conflict` with current/expected timestamps,
- * `precondition_required`, `schema_validation`); `test.todo` entries
- * describe the target behavior for confirmed-broken cases, to be flipped to
- * real assertions in a later wave. See #554 for the full write-up.
+ * `precondition_required`, `schema_validation`). The Wave 4 (#554) error
+ * taxonomy sweep flipped the original `test.todo` entries into real
+ * assertions below — see that describe block.
  */
 
-import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { BunStore } from "./vault-store.ts";
-import { handleNotes } from "./routes.ts";
+import { handleNotes, handleTags } from "./routes.ts";
+import { generateMcpTools, PreconditionRequiredError } from "../core/src/mcp.ts";
 
 let db: Database;
 let store: BunStore;
@@ -52,6 +53,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     const body: any = await res.json();
     expect(body.error_type).toBe("path_conflict");
     expect(body.path).toBe("taken");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("updating with a stale if_updated_at returns 409 conflict carrying current_updated_at + your_updated_at", async () => {
@@ -62,6 +64,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     expect(body.error_type).toBe("conflict");
     expect(body.current_updated_at).toBe(note.updatedAt);
     expect(body.your_updated_at).toBe("2020-01-01T00:00:00.000Z");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("a strict schema violation on write returns 422 schema_validation naming every violation", async () => {
@@ -76,6 +79,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     expect(body.violations.length).toBeGreaterThan(0);
     expect(body.violations[0].field).toBe("status");
     expect(body.violations[0].reason).toBe("enum_mismatch");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("updating a note without if_updated_at or force returns 428 precondition_required", async () => {
@@ -85,14 +89,176 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     const body: any = await res.json();
     expect(body.error_type).toBe("precondition_required");
     expect(body.note_id).toBe(note.id);
+    expect(typeof body.hint).toBe("string");
   });
 });
 
-describe("contract: error taxonomy — todo (#554)", () => {
-  test.todo(
-    "#554: every error response carries a structured {error_type, hint} pair — today error_type exists on many paths but no response carries a `hint` field, and some error paths (e.g. bad_request/ambiguous/unprocessable_content in the PATCH content_edit branch) are still bare {error, message} strings with no error_type at all",
-  );
-  test.todo(
-    "#554: batch update-note honors a top-level `force` (or `if_updated_at`) applied per-item — today the batch entry point does `items = batch ?? [params]`, so a top-level force:true on the request never reaches the per-item precondition check (core/src/mcp.ts ~line 1114 reads item.force only) and each item without its OWN force/if_updated_at still throws precondition_required",
-  );
+describe("contract: error taxonomy — #554 (flipped from todo)", () => {
+  it("every error response on the PATCH content_edit branch carries a structured {error_type, hint} pair — previously bare {error, message} strings with no error_type at all", async () => {
+    const note = await store.createNote("the quick brown fox jumps over the fox", { id: "n1" });
+
+    // mutually_exclusive — content + append in the same call.
+    const mutEx = await patch(note.id, { content: "x", append: "y", force: true });
+    expect(mutEx.status).toBe(400);
+    const mutExBody: any = await mutEx.json();
+    expect(mutExBody.error_type).toBe("mutually_exclusive");
+    expect(typeof mutExBody.hint).toBe("string");
+
+    // invalid_content_edit — content_edit missing new_text.
+    const badShape = await patch(note.id, { content_edit: { old_text: "fox" }, force: true });
+    expect(badShape.status).toBe(400);
+    const badShapeBody: any = await badShape.json();
+    expect(badShapeBody.error_type).toBe("invalid_content_edit");
+    expect(badShapeBody.field).toBe("content_edit");
+    expect(typeof badShapeBody.hint).toBe("string");
+
+    // content_edit_not_found — old_text absent from the note's content.
+    const notFound = await patch(note.id, {
+      content_edit: { old_text: "giraffe", new_text: "zebra" },
+      force: true,
+    });
+    expect(notFound.status).toBe(422);
+    const notFoundBody: any = await notFound.json();
+    expect(notFoundBody.error_type).toBe("content_edit_not_found");
+    expect(notFoundBody.field).toBe("content_edit.old_text");
+    expect(typeof notFoundBody.hint).toBe("string");
+
+    // content_edit_ambiguous — old_text ("fox") matches twice in the seed content.
+    const ambiguous = await patch(note.id, {
+      content_edit: { old_text: "fox", new_text: "wolf" },
+      force: true,
+    });
+    expect(ambiguous.status).toBe(409);
+    const ambiguousBody: any = await ambiguous.json();
+    expect(ambiguousBody.error_type).toBe("content_edit_ambiguous");
+    expect(ambiguousBody.field).toBe("content_edit.old_text");
+    expect(typeof ambiguousBody.hint).toBe("string");
+
+    // invalid_state_transition — state_transition.field is an empty string.
+    const badTransition = await patch(note.id, { state_transition: { field: "", from: "a", to: "b" } });
+    expect(badTransition.status).toBe(400);
+    const badTransitionBody: any = await badTransition.json();
+    expect(badTransitionBody.error_type).toBe("invalid_state_transition");
+    expect(badTransitionBody.field).toBe("state_transition.field");
+    expect(typeof badTransitionBody.hint).toBe("string");
+  });
+
+  it("batch update-note honors a top-level `force` applied per-item as a DEFAULT, and an item's own value still wins", async () => {
+    const a = await store.createNote("a", { id: "a1" });
+    const b = await store.createNote("b", { id: "b1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // Top-level force:true, item omits its own force/if_updated_at — the
+    // default applies and the write succeeds instead of throwing
+    // precondition_required. Before the fix, `items = batch ?? [params]`
+    // never merged the top-level field in, so this ALWAYS threw.
+    const result: any = await updateNote.execute({
+      force: true,
+      notes: [{ id: a.id, content: "a-updated" }],
+    });
+    expect(result[0].content).toBe("a-updated");
+
+    // Item-level values still win over the top-level default: this item
+    // explicitly sets `force: false` (overriding the batch default) and
+    // supplies no `if_updated_at` of its own, so the precondition gate
+    // still fires for it.
+    let caught: unknown;
+    try {
+      await updateNote.execute({
+        force: true,
+        notes: [{ id: b.id, content: "b-updated", force: false }],
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PreconditionRequiredError);
+  });
+
+  it("REST PUT /api/tags/:name reports ALL cross-tag field violations in one call and states no changes were applied (#553 messaging, mirrors the MCP tool)", async () => {
+    // Tag "a" declares two fields; tag "b" redeclares BOTH with conflicting
+    // specs in the SAME PUT — a NON-indexed type conflict on "x" and an
+    // indexed-flag conflict on "y" (both were silent 200s on main; the
+    // both-indexed type-conflict case deliberately keeps its pre-existing
+    // 400 path — see the regression test below). Before this fix REST had
+    // no cross-tag pre-check at all here (a gap distinct from the MCP
+    // tool's old first-field-only throw); now both surfaces report
+    // identically.
+    await store.upsertTagRecord("a", {
+      fields: {
+        x: { type: "string" },
+        y: { type: "boolean", indexed: true },
+      },
+    });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({
+        fields: {
+          x: { type: "integer" },
+          y: { type: "boolean", indexed: false },
+        },
+      }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("tag_field_conflict");
+    expect(body.violations).toHaveLength(2);
+    const byField = new Map(body.violations.map((v: any) => [v.field, v.reason]));
+    expect(byField.get("x")).toBe("type_conflict");
+    expect(byField.get("y")).toBe("indexed_flag_conflict");
+    expect(body.message).toContain("no changes were applied");
+    // Full detail for an unscoped caller — the conflicting declarer is named.
+    expect(body.violations[0].other_tag).toBe("a");
+
+    // Nothing partially landed.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+
+  it("REST PUT /api/tags/:name still returns 400 invalid_indexed_field for a solo bad field name (vault#478 contract unchanged)", async () => {
+    // No cross-tag conflict here — "meeting-type" is invalid on its OWN
+    // (kebab-case). This must stay on the pre-existing 400/invalid_indexed_field
+    // path, NOT the new 422/tag_field_conflict path — the cross-tag pre-check
+    // is deliberately scoped to type/indexed-flag agreement only (see
+    // `collectCrossTagFieldViolations`'s doc comment in core/src/tag-schemas.ts).
+    const req = new Request("http://localhost/api/tags/meeting", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { "meeting-type": { type: "string", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/meeting");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+  });
+
+  it("REST PUT /api/tags/:name: a BOTH-INDEXED cross-tag type conflict stays 400 invalid_indexed_field, NOT 422 (wire-contract floor — pre-existing declareField behavior)", async () => {
+    // Exact regression from the wire review: tag "a" declares x
+    // string+indexed; tag "b" PUTs x integer+indexed. On main this
+    // returned 400 invalid_indexed_field (declareField's cross-declarer
+    // sqlite-type check inside store.upsertTagRecord); the vault#554
+    // pre-check must NOT intercept it as a 422 — statuses/error_types on
+    // previously-working calls are wire contract. See
+    // `collectCrossTagFieldViolations`'s doc-comment exclusion 2.
+    await store.upsertTagRecord("a", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+    // Unscoped caller: declareField's full message (naming the declarer)
+    // is preserved verbatim.
+    expect(body.error).toContain("tag(s) [a]");
+
+    // Nothing persisted — the store's transaction rolled back.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
 });

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"]);
+  });
 });