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

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/live-match.test.ts

@@ -196,3 +196,20 @@ describe("live-match — predicate parity with the query engine", () => {
     await assertParity({ tags: ["t"], metadata: { kind: "note" } });
   });
 });
+
+describe("live-match — unsupportedSubscriptionReason cursor guard (vault#550)", () => {
+  it("rejects a bootstrap empty-string cursor (presence, not truthiness)", async () => {
+    const { unsupportedSubscriptionReason } = await import("./live-match.ts");
+    // `cursor: ""` is cursor INTENT (the vault#550 bootstrap call) — a live
+    // subscription can't paginate, so it must be rejected the same as a
+    // real cursor, not silently treated as "no cursor requested."
+    expect(unsupportedSubscriptionReason({ cursor: "" } as QueryOpts)).toContain("cursor");
+    expect(unsupportedSubscriptionReason({ cursor: "eyJxaC" } as QueryOpts)).toContain("cursor");
+  });
+
+  it("an omitted/undefined cursor does not reject", async () => {
+    const { unsupportedSubscriptionReason } = await import("./live-match.ts");
+    expect(unsupportedSubscriptionReason({ cursor: undefined } as QueryOpts)).toBeNull();
+    expect(unsupportedSubscriptionReason({} as QueryOpts)).toBeNull();
+  });
+});

package/src/live-match.ts

@@ -76,7 +76,10 @@ export function unsupportedSubscriptionReason(opts: QueryOpts): string | null {
   // subscribe route detects them from raw query params. These guards catch the
   // remaining shapes that the matcher can't faithfully evaluate against a
   // single in-hand note (so snapshot and live would disagree).
-  if (opts.cursor) {
+  // Presence, not truthiness (vault#550) — a bootstrap `cursor: ""` is
+  // still cursor intent and must still be rejected here, not silently
+  // treated as "no cursor requested."
+  if (opts.cursor !== undefined) {
     return "cursor pagination is not supported for live subscriptions";
   }
   if (opts.hasLinks !== undefined) {

package/src/mcp-http.ts

@@ -156,7 +156,39 @@ async function handleMcp(
         to?: unknown;
         current?: unknown;
         violations?: unknown;
+        error_type?: string;
+        got?: unknown;
+        hint?: string;
       };
+      // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
+      // values that are structurally invalid rather than merely "no
+      // results." Gated on `error_type === "invalid_query"` specifically
+      // (not `code === "INVALID_QUERY"` broadly) so long-standing QueryError
+      // throws WITHOUT this field (FIELD_NOT_INDEXED, UNKNOWN_OPERATOR, the
+      // various cursor/near/search incompatibility errors, ...) keep their
+      // 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, {
+          error_type: "invalid_query",
+          field: e.field,
+          got: e.got,
+          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/mcp-list-tags-scope.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Tag-scope enforcement on the MCP `list-tags` single-tag path (vault#550
+ * fold; also closes vault#560). Core's list-tags is scope-unaware by
+ * architecture — `applyTagScopeWrappers` in src/mcp-tools.ts is the
+ * enforcement layer. Before this fix the wrapper only filtered ARRAY
+ * results, so the single-tag (`{tag}` param) shape passed through
+ * unwrapped, leaking (a) the FULL record of an existing out-of-scope tag
+ * (#560), and (b) post-#550, a vault-wide `did_you_mean` suggestion that
+ * could name an out-of-scope tag.
+ *
+ * Fixture: PARACHUTE_HOME temp home + a hand-built AuthResult (no JWT
+ * infra needed — `generateScopedMcpTools` takes the resolved auth
+ * directly), same pattern as attribution-threading.test.ts's MCP section.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-listtags-scope-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function listTagsTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "list-tags")!;
+}
+
+describe("MCP list-tags single-tag path — tag-scope enforcement (vault#550 fold, closes #560)", () => {
+  test("scoped token + EXISTING out-of-scope tag → tag_not_found with no record fields, no did_you_mean (#560's full-record leak)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("work", { description: "top secret reorg planning" });
+    await store.createNote("w", { tags: ["work"] });
+    await store.createNote("h", { tags: ["health"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "work" })) as any;
+
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("work");
+    // No leak: none of the record's fields, no counts, no suggestion.
+    expect(result.description).toBeUndefined();
+    expect(result.count).toBeUndefined();
+    expect(result.expanded_count).toBeUndefined();
+    expect(result.fields).toBeUndefined();
+    expect(result.parent_names).toBeUndefined();
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("scoped token + NONEXISTENT tag → tag_not_found without an out-of-scope did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // "project" exists but is OUT of scope — it must not surface as a
+    // suggestion for the near-miss "projet".
+    await store.upsertTagRecord("project", {});
+    await store.createNote("h", { tags: ["health"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    // "projet" is not in the allowlist → short-circuits to tag_not_found
+    // before core even computes a suggestion.
+    const result = (await tool.execute({ tag: "projet" })) as any;
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("projet");
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("scoped token + in-scope miss keeps did_you_mean only when the suggestion is also in-scope", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // Declared hierarchy: health/food is a child of health, so the
+    // allowlist expansion covers both. A near-miss on the CHILD name is in
+    // the allowlist's expansion? No — "health/fod" itself isn't a known
+    // tag, but it IS within scope only if the allowlist contains it.
+    // expandTokenTagScope(["health"]) = {health, health/food}; the literal
+    // input "health/fod" is NOT in that set → short-circuit tag_not_found
+    // (no suggestion) — pinning that the wrapper gates on the allowlist,
+    // not on string prefixes.
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.createNote("hf", { tags: ["health/food"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "health/fod" })) as any;
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("unscoped token unchanged — full record for existing tags, did_you_mean on misses", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project", { description: "projects" });
+    await store.createNote("p", { tags: ["project"] });
+
+    const tool = await listTagsTool("journal", null);
+
+    const hit = (await tool.execute({ tag: "project" })) as any;
+    expect(hit.name).toBe("project");
+    expect(hit.count).toBe(1);
+    expect(hit.description).toBe("projects");
+
+    const miss = (await tool.execute({ tag: "projet" })) as any;
+    expect(miss.error_type).toBe("tag_not_found");
+    expect(miss.did_you_mean).toBe("project");
+  });
+
+  test("scoped token + array list still filters to the allowlist (regression: pre-existing behavior)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("h", { tags: ["health"] });
+    await store.createNote("w", { tags: ["work"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({})) as any[];
+    const names = result.map((t) => t.name);
+    expect(names).toContain("health");
+    expect(names).not.toContain("work");
+  });
+});

package/src/mcp-tools.ts

@@ -308,9 +308,11 @@ function applyTagScopeWrappers(
     const allowed = await getAllowed();
     const result = await orig(params);
     if (!allowed) return result;
-    // Three possible response shapes:
-    //   - Array (legacy list, no cursor)
+    // Possible response shapes (vault#550 added the `warnings` variants):
+    //   - Array (legacy list, no cursor, no warnings)
     //   - `{notes, next_cursor}` (cursor mode, vault#313)
+    //   - `{notes, warnings}` (warnings present, not in cursor mode)
+    //   - `{notes, next_cursor, warnings}` (both)
     //   - `{...note}` with `id`+`tags` (single-note by id)
     if (Array.isArray(result)) {
       return result
@@ -321,15 +323,22 @@ function applyTagScopeWrappers(
       result &&
       typeof result === "object" &&
       "notes" in result &&
-      Array.isArray((result as any).notes) &&
-      "next_cursor" in result
+      Array.isArray((result as any).notes)
     ) {
-      const r = result as { notes: any[]; next_cursor: string | null };
+      const r = result as { notes: any[]; next_cursor?: string | null; warnings?: unknown };
       return {
         notes: r.notes
           .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
           .map(scrubNoteLinks),
-        next_cursor: r.next_cursor,
+        ...("next_cursor" in r ? { next_cursor: r.next_cursor } : {}),
+        // `warnings` intentionally DROPPED for a tag-scoped session: core's
+        // `collectUnknownTagWarnings` (core/src/query-warnings.ts) resolves
+        // `did_you_mean` against the FULL vault-wide tag catalog, which
+        // would leak an out-of-scope tag's existence/name to a token that
+        // can't otherwise see it — the same "no leak across the scope
+        // boundary" stance this file takes everywhere else (see
+        // docs/contracts/tag-scoped-tokens.md). Unscoped sessions keep
+        // `warnings` untouched via the `!allowed` early return above.
       };
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
@@ -342,9 +351,41 @@ function applyTagScopeWrappers(
 
   wrapReadTool(tools, "list-tags", async (orig, params) => {
     const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    // Single-tag detail (`{tag}` param) — the non-array shape the old
+    // wrapper silently passed through, which leaked BOTH the full record of
+    // an existing out-of-scope tag (vault#560) AND, post-#550, a vault-wide
+    // `did_you_mean` suggestion for a nonexistent one. This wrapper is the
+    // enforcement layer for tag scope on this tool; core's list-tags stays
+    // scope-unaware by architecture (same division as every other wrapper
+    // in this file).
+    const singleTag = typeof (params as any).tag === "string" ? ((params as any).tag as string) : null;
+    if (singleTag !== null && !allowed.has(singleTag)) {
+      // Out-of-scope name — whether the tag exists or not. Same
+      // "tag_not_found, no leak" shape as the REST handlers' early-return,
+      // and deliberately NO did_you_mean (any suggestion would be computed
+      // vault-wide). Short-circuits BEFORE core runs, so the full record /
+      // suggestion is never even computed.
+      return { error: "Tag not found", error_type: "tag_not_found", tag: singleTag };
+    }
     const result = await orig(params);
-    if (!allowed || !Array.isArray(result)) return result;
-    return result.filter((t: any) => allowed.has(t.name));
+    if (Array.isArray(result)) {
+      return result.filter((t: any) => allowed.has(t.name));
+    }
+    // In-scope single-tag miss (nonexistent but allowlisted name): core's
+    // tag_not_found may carry a vault-wide `did_you_mean` — keep it only
+    // when the suggestion itself is inside the allowlist.
+    if (
+      result &&
+      typeof result === "object" &&
+      (result as any).error_type === "tag_not_found" &&
+      typeof (result as any).did_you_mean === "string" &&
+      !allowed.has((result as any).did_you_mean)
+    ) {
+      const { did_you_mean: _dropped, ...scrubbed } = result as Record<string, unknown>;
+      return scrubbed;
+    }
+    return result;
   });
 
   wrapReadTool(tools, "find-path", async (orig, params) => {