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

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-http.test.ts

@@ -0,0 +1,140 @@
+/**
+ * MCP JSON-RPC error mapping — no double-wrap (vault#555 fix 6).
+ *
+ * Verified at code: the catch block in `handleMcp` read `err.message` and
+ * fed it into a fresh `new McpError(...)`. The MCP SDK's `McpError`
+ * constructor bakes `"MCP error <code>: "` into `.message` ITSELF (not just
+ * `.toString()`) — confirmed directly against the SDK below. So an already-
+ * formed `McpError` reaching that catch block (or a plain error whose
+ * `.message` happens to already carry that prefix — e.g. forwarded verbatim
+ * from another MCP-speaking service) got double-prefixed:
+ * `"MCP error -32602: MCP error -32602: ..."`. The structured
+ * `data.error_type` was always correct — only the human-readable `message`
+ * string could double.
+ *
+ * `handleMcp` (the underlying dispatcher `handleScopedMcp` wraps) is
+ * exported specifically so a test can inject a synthetic failing tool and
+ * exercise the exact catch-block path without needing a real domain error
+ * class that happens to throw an `McpError` naturally (none of core's tools
+ * do — `McpError` is only ever constructed inside `mcp-http.ts` itself).
+ */
+import { describe, test, expect } from "bun:test";
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { handleMcp, mcpDomainError } from "./mcp-http.ts";
+import type { McpToolDef } from "../core/src/mcp.ts";
+import type { AuthResult } from "./auth.ts";
+
+function toolsWith(execute: (params: Record<string, unknown>) => unknown): () => McpToolDef[] {
+  return () => [
+    {
+      name: "boom",
+      description: "throws whatever `execute` throws",
+      inputSchema: { type: "object", properties: {} },
+      requiredVerb: "read",
+      execute,
+    },
+  ];
+}
+
+function fullAuth(): AuthResult {
+  return {
+    permission: "full",
+    scopes: ["vault:v:read", "vault:v:write", "vault:v:admin"],
+    legacyDerived: false,
+    scoped_tags: null,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function callBoom(execute: (params: Record<string, unknown>) => unknown): Promise<any> {
+  const req = new Request("http://localhost:1940/vault/v/mcp", {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "boom", arguments: {} },
+    }),
+  });
+  const res = await handleMcp(req, toolsWith(execute), "test-server", "v", fullAuth(), "");
+  return res.json();
+}
+
+describe("MCP SDK McpError — confirms the mechanics this fix depends on", () => {
+  test("the SDK bakes the JSON-RPC prefix into .message itself, not just .toString()", () => {
+    const err = new McpError(ErrorCode.InvalidParams, "bad stuff happened", { error_type: "invalid_query" });
+    expect(err.message).toBe("MCP error -32602: bad stuff happened");
+    // Naive re-wrap (the pre-fix behavior) doubles it — this is the exact
+    // bug, reproduced directly against the SDK class.
+    const naiveRewrap = new McpError(ErrorCode.InvalidParams, err.message, { error_type: "invalid_query" });
+    expect(naiveRewrap.message).toBe("MCP error -32602: MCP error -32602: bad stuff happened");
+  });
+});
+
+describe("mcpDomainError — single source of truth for the JSON-RPC mapping (vault#555 fix 6)", () => {
+  test("a plain message gets the error_type token prepended (optional polish)", () => {
+    const err = mcpDomainError(ErrorCode.InvalidParams, "bad stuff happened", { error_type: "invalid_query" });
+    expect(err.message).toBe("MCP error -32602: [invalid_query] bad stuff happened");
+    expect(err.data).toEqual({ error_type: "invalid_query" });
+  });
+
+  test("a message that ALREADY carries the JSON-RPC prefix is not doubled", () => {
+    const err = mcpDomainError(ErrorCode.InvalidParams, "MCP error -32602: bad stuff happened", {
+      error_type: "invalid_query",
+    });
+    expect(err.message).toBe("MCP error -32602: [invalid_query] bad stuff happened");
+    expect(err.message).not.toContain("MCP error -32602: MCP error");
+  });
+
+  test("no error_type in data — message passes through without a bracketed token", () => {
+    const err = mcpDomainError(ErrorCode.InternalError, "something broke", {});
+    expect(err.message).toBe("MCP error -32603: something broke");
+  });
+});
+
+describe("handleMcp JSON-RPC error mapping — end to end (vault#555 fix 6)", () => {
+  test("a tool throwing an ALREADY-formed McpError passes through unchanged — no double prefix, data preserved verbatim", async () => {
+    const inner = new McpError(ErrorCode.InvalidRequest, "conflict: note was modified", {
+      error_type: "conflict",
+      note_id: "abc123",
+      hint: "re-read and retry",
+    });
+    const body = await callBoom(() => {
+      throw inner;
+    });
+    expect(body.error.code).toBe(ErrorCode.InvalidRequest);
+    // Single prefix — NOT "MCP error -32600: MCP error -32600: ...".
+    expect(body.error.message).toBe("MCP error -32600: conflict: note was modified");
+    expect((body.error.message.match(/MCP error/g) ?? []).length).toBe(1);
+    // data.error_type fidelity preserved exactly — nothing re-derived.
+    expect(body.error.data).toEqual({
+      error_type: "conflict",
+      note_id: "abc123",
+      hint: "re-read and retry",
+    });
+  });
+
+  test("a plain domain error (never wrapped) is mapped once, with the error_type token in the human message", async () => {
+    const body = await callBoom(() => {
+      throw Object.assign(new Error("something went wrong"), { error_type: "invalid_query", field: "limit" });
+    });
+    expect(body.error.message).toBe("MCP error -32602: [invalid_query] something went wrong");
+    expect((body.error.message.match(/MCP error/g) ?? []).length).toBe(1);
+    expect(body.error.data.error_type).toBe("invalid_query");
+    expect(body.error.data.field).toBe("limit");
+  });
+
+  test("a truly unknown error (no error_type anywhere) falls through to the unstructured isError text, not a thrown McpError", async () => {
+    const body = await callBoom(() => {
+      throw new Error("plain unstructured failure");
+    });
+    // No JSON-RPC `error` — the tool result carries isError: true instead.
+    expect(body.error).toBeUndefined();
+    expect(body.result.isError).toBe(true);
+    expect(body.result.content[0].text).toContain("plain unstructured failure");
+  });
+});

package/src/mcp-http.ts

@@ -45,6 +45,48 @@ function requiredVerbForTool(tool: { requiredVerb?: VaultVerb }): VaultVerb {
   return tool.requiredVerb ?? "write";
 }
 
+/** Matches the JSON-RPC prefix the MCP SDK's `McpError` constructor bakes
+ *  into `.message` itself (not just `.toString()`) — e.g.
+ *  `"MCP error -32602: the actual message"`. */
+const MCP_ERROR_PREFIX_RE = /^MCP error -?\d+:\s*/;
+
+/**
+ * Build a JSON-RPC `McpError` for a domain error, in ONE place (vault#555
+ * fix 6 — was 15 duplicated `new McpError(...)` call sites below, each a
+ * chance to drift). Two things this fixes over the old inline construction:
+ *
+ * 1. **No double-wrap.** The MCP SDK's `McpError` constructor bakes
+ *    `"MCP error <code>: "` into `.message` ITSELF. If the message being
+ *    wrapped ALREADY carries that prefix (a message forwarded verbatim
+ *    from another MCP-speaking service, or a stale caller that read
+ *    `err.message` off an already-formed `McpError` instead of re-throwing
+ *    it — see the `err instanceof McpError` guard at the top of the catch
+ *    block below, which is the PRIMARY fix for that exact case), naively
+ *    constructing `new McpError(code, message, data)` doubles it:
+ *    `"MCP error -32602: MCP error -32602: ..."`. This strips any
+ *    pre-existing prefix before building the new one, so the message is
+ *    single-prefixed no matter how many times a message string passes
+ *    through this function.
+ * 2. **`error_type` in the human-readable message too** (optional polish,
+ *    vault#555) — a string-reading human (not just a JSON-parsing agent
+ *    keying off `data.error_type`) sees `[error_type] message` rather than
+ *    a bare message with no clue which structured category it belongs to.
+ *
+ * `data.error_type` fidelity was never actually broken — it was always
+ * threaded correctly through the JSON-RPC `data` field; only the
+ * human-readable `message` string could double-prefix.
+ */
+export function mcpDomainError(
+  code: ErrorCode,
+  rawMessage: string,
+  data: Record<string, unknown>,
+): McpError {
+  const cleanMessage = rawMessage.replace(MCP_ERROR_PREFIX_RE, "");
+  const errorType = typeof data.error_type === "string" ? data.error_type : undefined;
+  const humanMessage = errorType ? `[${errorType}] ${cleanMessage}` : cleanMessage;
+  return new McpError(code, humanMessage, data);
+}
+
 /**
  * Handle scoped MCP at /vault/{name}/mcp (single vault).
  *
@@ -75,7 +117,10 @@ export async function handleScopedMcp(
   );
 }
 
-async function handleMcp(
+/** Exported for direct testing (vault#555 fix 6) — lets a test inject a
+ *  synthetic failing tool to exercise the `err instanceof McpError` guard
+ *  without needing a real domain error class to construct one naturally. */
+export async function handleMcp(
   req: Request,
   getTools: () => McpToolDef[],
   serverName: string,
@@ -139,6 +184,18 @@ async function handleMcp(
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
+      // vault#555 fix 6 — never re-wrap an already-formed McpError. Passing
+      // the SAME instance straight through is strictly correct (no
+      // information lost — `.message` AND `.data.error_type` are already
+      // exactly right) and is the primary fix for the double-prefix bug
+      // ("MCP error -32602: MCP error -32602: ..."): every branch below
+      // reads `err.message` and feeds it into a NEW McpError, which would
+      // double the SDK's baked-in "MCP error <code>: " prefix if `err` were
+      // already one. See `mcpDomainError`'s doc comment for the belt-and-
+      // suspenders half of this fix (stripping a pre-existing prefix from a
+      // plain message too).
+      if (err instanceof McpError) throw err;
+
       // Domain errors from the core tools (conflict, missing precondition,
       // path collisions, batch caps, cursor/query validation, tag-field
       // conflicts, ...) get surfaced as JSON-RPC errors with a structured
@@ -182,7 +239,7 @@ async function handleMcp(
       // existing unstructured `isError: true` fallback — only the NEW #550
       // call sites that explicitly set `error_type` opt into this shape.
       if (e?.error_type === "invalid_query") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "invalid_query",
           field: e.field,
           got: e.got,
@@ -195,7 +252,7 @@ async function handleMcp(
       // 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, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "invalid_search_syntax",
           field: e.field,
           got: e.got,
@@ -203,7 +260,7 @@ async function handleMcp(
         });
       }
       if (e?.code === "CONFLICT") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "conflict",
           current_updated_at: e.current_updated_at ?? null,
           your_updated_at: e.expected_updated_at,
@@ -216,7 +273,7 @@ async function handleMcp(
       // DISTINCT vocabulary from `conflict` (settled lead #3): the value
       // didn't match, not the updated_at token.
       if (e?.code === "TRANSITION_CONFLICT") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "transition_conflict",
           note_id: e.note_id,
           path: e.note_path ?? null,
@@ -230,14 +287,14 @@ async function handleMcp(
       // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
       // per-field violations (settled lead #1).
       if (e?.code === "SCHEMA_VALIDATION") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "schema_validation",
           violations: e.violations ?? [],
           hint: "fix every field listed in violations and retry — none of this write was applied",
         });
       }
       if (e?.code === "PRECONDITION_REQUIRED") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "precondition_required",
           note_id: e.note_id,
           path: e.note_path ?? null,
@@ -252,7 +309,7 @@ async function handleMcp(
       // REST already uses for this whole error class — so these no longer
       // fall through to the unstructured `isError: true` text.
       if (e?.name === "QueryError") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: e.error_type ?? "invalid_query",
           code: e.code,
           field: e.field,
@@ -266,14 +323,14 @@ async function handleMcp(
       // already the exact `error_type` vocabulary: "cursor_invalid" or
       // "cursor_query_mismatch".
       if (e?.name === "CursorError" && typeof e.code === "string") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: e.code,
         });
       }
       // Path-rename/create collision (vault#126, vault#554) — schema's
       // UNIQUE(path) tripped. Mirrors REST's 409 `path_conflict` shape.
       if (e?.code === "PATH_CONFLICT") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "path_conflict",
           path: e.path,
         });
@@ -282,7 +339,7 @@ async function handleMcp(
       // mirrors REST's 409 `ambiguous_path` shape (candidates = the
       // disambiguating extensions).
       if (e?.code === "AMBIGUOUS_PATH") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "ambiguous_path",
           path: e.path,
           candidates: e.candidates,
@@ -291,7 +348,7 @@ async function handleMcp(
       // Bad `extension` value (vault#328, vault#554) — mirrors REST's 400
       // `invalid_extension` shape.
       if (e?.code === "INVALID_EXTENSION") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "invalid_extension",
           extension: e.extension,
           reason: e.reason,
@@ -300,7 +357,7 @@ async function handleMcp(
       // Batch cap exceeded (#213, vault#554) — mirrors REST's 413
       // `batch_too_large` shape.
       if (e?.code === "BATCH_TOO_LARGE") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "batch_too_large",
           limit: e.limit,
           got: e.got,
@@ -309,7 +366,7 @@ async function handleMcp(
       // update-tag cross-tag field conflicts (vault#553/#554) — carries
       // EVERY violation in one response (see `TagFieldConflictError`).
       if (e?.code === "TAG_FIELD_CONFLICT") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: "tag_field_conflict",
           tag: e.tag,
           violations: e.violations ?? [],
@@ -320,7 +377,7 @@ async function handleMcp(
       // wrapper (src/mcp-tools.ts) scope-scrubs `cycle` before this throw
       // for a tag-scoped caller, same as TAG_FIELD_CONFLICT above.
       if (e?.code === "PARENT_CYCLE") {
-        throw new McpError(ErrorCode.InvalidRequest, message, {
+        throw mcpDomainError(ErrorCode.InvalidRequest, message, {
           error_type: "parent_cycle",
           tag: e.tag,
           cycle: e.cycle ?? [],
@@ -338,7 +395,7 @@ async function handleMcp(
       // error" true by construction: only errors nobody tagged with
       // `error_type` still hit the fallback below.
       if (typeof e?.error_type === "string") {
-        throw new McpError(ErrorCode.InvalidParams, message, {
+        throw mcpDomainError(ErrorCode.InvalidParams, message, {
           error_type: e.error_type,
           field: e.field,
           hint: e.hint,

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/mcp-tools.ts

@@ -26,6 +26,7 @@ import {
   scrubParentCycleError,
   scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
+  scrubValidationStatusByScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
 import { TagFieldConflictError, ParentCycleError } from "../core/src/tag-schemas.ts";
@@ -332,6 +333,16 @@ function applyTagScopeWrappers(
     if (n && Array.isArray(n.links)) {
       n.links = filterHydratedLinksByTagScope(n.links, allowedHolder?.value ?? null, rawTags);
     }
+    // vault#555 auth review — a note the caller can see may ALSO carry an
+    // out-of-scope co-tag whose schema `validation_status` would otherwise
+    // leak (field name / type / enum values, the #560 class). Scrub it with
+    // the same allowlist the link scrub uses. Reads the resolved holder for
+    // the same reason (see the ordering-invariant note above scrubNoteLinks).
+    if (n && n.validation_status) {
+      const scrubbed = scrubValidationStatusByScope(n.validation_status, allowedHolder?.value ?? null, rawTags);
+      if (scrubbed === undefined) delete n.validation_status;
+      else n.validation_status = scrubbed;
+    }
     return n;
   };