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

package/src/contract-honest-queries.test.ts

@@ -1,19 +1,22 @@
 /**
- * Contract suite — honest queries at the REST boundary (Wave 1 of the
- * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
- * nine-persona deep test's WS1 findings (#550) 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 #550 for the full write-up — this file
- * covers the `src/routes.ts` REST surface specifically (the cursor-bootstrap
- * gap lives at routes.ts:1102/1106, the tags/{name} 404 gap at the GET /tags
- * handler in `handleTags`).
+ * Contract suite — honest queries at the REST + MCP boundary (Wave 1's
+ * findings, Wave 2's fixes — Reliability & Usability Program, umbrella
+ * #556). Encodes the 2026-07-09 nine-persona deep test's WS1 findings
+ * (#550) as executable tests: PASSING tests lock in behavior that is
+ * correct today; the #550 `test.todo` entries this file used to carry have
+ * all been flipped to real assertions against the WS1 fixes (warnings
+ * channel, structured invalids, cursor bootstrap, tags 404, expanded_count)
+ * — see #550 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 and a REST-only test wouldn't
+ * prove the MCP side actually got the fix.
  */
 
 import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { BunStore } from "./vault-store.ts";
-import { handleNotes, handleTags } from "./routes.ts";
+import { handleNotes, handleTags, handleFindPath } from "./routes.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
 
 let db: Database;
 let store: BunStore;
@@ -28,6 +31,21 @@ function getTags(qs: string): Promise<Response> {
   return handleTags(new Request(`${BASE}/tags?${qs}`, { method: "GET" }), store, "");
 }
 
+function getTagByName(name: string): Promise<Response> {
+  return handleTags(new Request(`${BASE}/tags/${name}`, { method: "GET" }), store, `/${name}`);
+}
+
+function findPath(source: string, target: string): Promise<Response> {
+  return handleFindPath(new Request(`${BASE}/find-path?source=${source}&target=${target}`, { 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));
+}
+
 beforeEach(() => {
   db = new Database(":memory:");
   store = new BunStore(db);
@@ -42,8 +60,9 @@ describe("contract: honest queries — passing (lock in current behavior)", () =
     const res = await getNotes("tag=zzznonexistenttag");
     expect(res.status).toBe(200);
     const body = await res.json();
-    // Shape may gain a `warnings` field later (#550) — assert only status +
-    // array shape now so that addition doesn't break this contract test.
+    // Shape may gain a `warnings` HEADER (vault#550, additive) — assert
+    // only status + array shape here so the header addition doesn't break
+    // this contract test. The header itself is exercised below.
     expect(Array.isArray(body)).toBe(true);
     expect(body).toEqual([]);
   });
@@ -63,13 +82,13 @@ describe("contract: honest queries — passing (lock in current behavior)", () =
     expect(body.note_id).toBe("does-not-exist");
   });
 
-  // removed in W2 — once #550's cursor-bootstrap fix lands, an omitted
-  // `cursor` param will (per the documented intent) still return a flat
-  // array for callers who never opt into cursor pagination, so this
-  // specific assertion should survive; the paired todo below is the one
-  // that flips when the bootstrap gap closes. Kept both here so the fix
-  // is a conscious, reviewed change rather than an incidental snapshot.
-  it("a cursor-less limit query returns a flat array (today's shape) — removed in W2", async () => {
+  // The cursor-bootstrap fix (vault#550) means `cursor` is now keyed on
+  // PRESENCE, not truthiness — `?cursor=` (present, empty) now engages the
+  // envelope (see the "cursor bootstrap" test below). An OMITTED `cursor`
+  // param is a completely different thing — no pagination intent at all —
+  // and still returns today's flat array. This test pins that omission
+  // case specifically, distinct from bootstrap.
+  it("a cursor-less limit query (cursor param OMITTED entirely) returns a flat array", async () => {
     await store.createNote("only note");
     const res = await getNotes("limit=5");
     expect(res.status).toBe(200);
@@ -78,23 +97,316 @@ describe("contract: honest queries — passing (lock in current behavior)", () =
   });
 });
 
-describe("contract: honest queries — todo (#550)", () => {
-  test.todo(
-    "#550: limit=-1 returns a structured error instead of silently meaning \"unlimited\" (today: SQLite's negative-LIMIT-means-no-limit semantics leak straight through to the caller)",
-  );
-  test.todo(
-    "#550: query responses carry a warnings: [] channel, populated with a did_you_mean suggestion for an unknown tag name",
-  );
-  test.todo(
-    "#550: an invalid date_filter value (unparseable date string) returns a structured error instead of silently matching nothing or everything",
-  );
-  test.todo(
-    "#550: GET /api/tags/{nonexistent} returns 404 instead of 200 with an all-null synthesized record",
-  );
-  test.todo(
-    "#550: list-tags reports expanded_count (rollup through parent_names descendants) alongside the literal per-tag count — today a parent tag with only child-tagged notes reports count: 0",
-  );
-  test.todo(
-    "#550: cursor bootstrap — a first call that expresses cursor intent (no `cursor` param yet, but pagination is desired) returns a {notes, next_cursor} envelope, and a second call passing that cursor back sees only notes written since the first call (today: routes.ts only wraps the response in {notes, next_cursor} when a cursor param is ALREADY present, so the very first call can never obtain one — core/src/mcp.ts:331 documents a bootstrap flow that is not actually reachable)",
-  );
+describe("contract: honest queries — structured invalids (#550)", () => {
+  it("limit=-1 returns a structured invalid_query error instead of silently meaning \"unlimited\"", async () => {
+    await store.createNote("a note");
+    const res = await getNotes("limit=-1");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.field).toBe("limit");
+    expect(body.got).toBe("-1");
+    expect(typeof body.hint).toBe("string");
+  });
+
+  it("limit=abc (non-numeric) returns invalid_query instead of silently falling back to the default", async () => {
+    const res = await getNotes("limit=abc");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.field).toBe("limit");
+    expect(body.got).toBe("abc");
+  });
+
+  it("offset=-1 (negative offset) returns a structured invalid_query error", async () => {
+    const res = await getNotes("offset=-1");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.field).toBe("offset");
+    expect(body.got).toBe("-1");
+    expect(typeof body.hint).toBe("string");
+  });
+
+  it("an unparseable date value in a bracket date filter returns invalid_query instead of silently matching nothing or everything", async () => {
+    const res = await getNotes("meta[created_at][gte]=not-a-real-date");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.got).toBe("not-a-real-date");
+    expect(typeof body.hint).toBe("string");
+    expect(body.hint.toLowerCase()).toContain("iso");
+  });
+
+  it("a malformed cursor's error message states the bootstrap flow explicitly", async () => {
+    const res = await getNotes("cursor=not-a-valid-cursor!!!");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("cursor_invalid");
+    // Must name the recovery flow, not just "this is broken" — the P1
+    // fix's whole point is that the bootstrap shape is DISCOVERABLE from
+    // the error, not just from documentation the caller may never read.
+    expect(body.error).toContain('cursor:""');
+    expect(body.error.toLowerCase()).toContain("next_cursor");
+  });
+});
+
+describe("contract: honest queries — warnings channel (#550)", () => {
+  it("an unrecognized tag surfaces an unknown_tag warning (with did_you_mean) via the X-Parachute-Warnings header, bare-array body unchanged", async () => {
+    await store.createNote("a note", { tags: ["project"] });
+    const res = await getNotes("tag=projet"); // typo: missing the second "c"
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true); // shape stays a bare array
+    expect(body).toEqual([]); // the typo'd tag genuinely matches nothing
+
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    expect(warnings).toHaveLength(1);
+    expect(warnings![0].code).toBe("unknown_tag");
+    expect(warnings![0].tag).toBe("projet");
+    expect(warnings![0].did_you_mean).toBe("project");
+  });
+
+  it("a tag that has notes via subtype expansion (a real descendant) does NOT warn, even though the literal tag has zero direct matches", async () => {
+    await store.upsertTagRecord("child", { parent_names: ["parent"] });
+    await store.createNote("a note", { tags: ["child"] });
+    const res = await getNotes("tag=parent");
+    expect(res.status).toBe(200);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).toBeNull(); // "parent" resolves via expansion — not unknown
+  });
+
+  it("the flat date_field/date_from/date_to params (removed at 0.6.4) surface a removed_param warning per param, still silently ignored in the result set", async () => {
+    await store.createNote("in range", { created_at: "2020-06-01T00:00:00.000Z" });
+    await store.createNote("out of range", { created_at: "2099-01-01T00:00:00.000Z" });
+    const res = await getNotes("date_field=created_at&date_from=2020-01-01&date_to=2020-12-31");
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    // Still unfiltered (existing behavior — bracket-style is the only
+    // supported date filter now; this locks in that the ignoring itself
+    // didn't change, only that it's no longer SILENT). Both notes come
+    // back even though `out of range` sits well outside the requested
+    // window — proof the flat params never touched the query.
+    expect(body.length).toBe(2);
+
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const codes = warnings!.map((w) => w.code);
+    expect(codes.filter((c) => c === "removed_param")).toHaveLength(3);
+    const params = warnings!.filter((w) => w.code === "removed_param").map((w) => w.param).sort();
+    expect(params).toEqual(["date_field", "date_from", "date_to"]);
+  });
+
+  it("cursor mode carries warnings INLINE in the envelope (in addition to the header)", async () => {
+    const res = await getNotes("cursor=&tag=doesnotexist");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body.notes)).toBe(true);
+    expect(typeof body.next_cursor).toBe("string");
+    expect(Array.isArray(body.warnings)).toBe(true);
+    expect(body.warnings[0].code).toBe("unknown_tag");
+    // header present too, same content
+    const headerWarnings = decodeWarningsHeader(res);
+    expect(headerWarnings).toEqual(body.warnings);
+  });
+
+  it("format=graph carries warnings INLINE in the {nodes, edges} envelope (in addition to the header)", async () => {
+    await store.createNote("a note", { tags: ["real"] });
+    const res = await getNotes("format=graph&tag=doesnotexist");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body.nodes)).toBe(true);
+    expect(Array.isArray(body.edges)).toBe(true);
+    expect(Array.isArray(body.warnings)).toBe(true);
+    expect(body.warnings[0].code).toBe("unknown_tag");
+    const headerWarnings = decodeWarningsHeader(res);
+    expect(headerWarnings).toEqual(body.warnings);
+  });
+
+  it("format=graph with no warnings carries NO warnings key and no header (shape unchanged)", async () => {
+    await store.createNote("a note", { tags: ["real"] });
+    const res = await getNotes("format=graph&tag=real");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.warnings).toBeUndefined();
+    expect(res.headers.get("X-Parachute-Warnings")).toBeNull();
+  });
+
+  it("unknown_tag warnings are capped at 8 with a warnings_truncated marker (garbage tags array can't inflate the header unboundedly)", async () => {
+    const junkTags = Array.from({ length: 12 }, (_, i) => `zz-junk-tag-${i}`);
+    const res = await getNotes(`tag=${junkTags.join(",")}`);
+    expect(res.status).toBe(200);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const unknown = warnings!.filter((w) => w.code === "unknown_tag");
+    const truncated = warnings!.filter((w) => w.code === "warnings_truncated");
+    expect(unknown).toHaveLength(8);
+    expect(truncated).toHaveLength(1);
+    expect(truncated[0].suppressed).toBe(4); // 12 junk tags − 8 reported
+    expect(truncated[0].limit).toBe(8);
+  });
+});
+
+describe("contract: honest queries — cursor bootstrap (#550, the P1)", () => {
+  it("an empty cursor (`?cursor=`) engages the {notes, next_cursor} envelope on the VERY FIRST call, and the returned next_cursor sees only notes written after it", async () => {
+    const n1 = await store.createNote("existing note");
+
+    const first = await getNotes("cursor=");
+    expect(first.status).toBe(200);
+    const firstBody: any = await first.json();
+    expect(Array.isArray(firstBody)).toBe(false);
+    expect(Array.isArray(firstBody.notes)).toBe(true);
+    expect(firstBody.notes.map((n: any) => n.id)).toEqual([n1.id]);
+    expect(typeof firstBody.next_cursor).toBe("string");
+    expect(firstBody.next_cursor.length).toBeGreaterThan(0);
+
+    const n2 = await store.createNote("new note");
+    const second = await getNotes(`cursor=${encodeURIComponent(firstBody.next_cursor)}`);
+    expect(second.status).toBe(200);
+    const secondBody: any = await second.json();
+    expect(secondBody.notes.map((n: any) => n.id)).toEqual([n2.id]);
+  });
+
+  it("MCP query-notes: cursor: \"\" likewise bootstraps the envelope on the first call", async () => {
+    const n1 = await store.createNote("existing note");
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+
+    const first = await queryNotes.execute({ cursor: "" }) as any;
+    expect(Array.isArray(first)).toBe(false);
+    expect(Array.isArray(first.notes)).toBe(true);
+    expect(first.notes.map((n: any) => n.id)).toEqual([n1.id]);
+    expect(typeof first.next_cursor).toBe("string");
+
+    const n2 = await store.createNote("new note");
+    const second = await queryNotes.execute({ cursor: first.next_cursor }) as any;
+    expect(second.notes.map((n: any) => n.id)).toEqual([n2.id]);
+  });
+
+  it("omitting `cursor` entirely (MCP) is NOT the same as bootstrapping — no envelope, no next_cursor", async () => {
+    await store.createNote("only note");
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({}) as any;
+    expect(Array.isArray(result)).toBe(true);
+  });
+});
+
+describe("contract: honest queries — tags 404 (#550)", () => {
+  it("GET /api/tags/{nonexistent} returns 404 tag_not_found instead of a synthesized all-null 200", async () => {
+    const res = await getTagByName("zzznonexistenttag");
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("tag_not_found");
+    expect(body.tag).toBe("zzznonexistenttag");
+  });
+
+  it("GET /api/tags?tag=<nonexistent> returns the same 404 tag_not_found shape, with did_you_mean when a close match exists", async () => {
+    await store.upsertTagRecord("project", {});
+    const res = await getTags("tag=projcet"); // transposed letters
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("tag_not_found");
+    expect(body.tag).toBe("projcet");
+    expect(body.did_you_mean).toBe("project");
+  });
+
+  it("a tag with an identity row but zero notes is still a real 200 (not 404) — an identity row alone is enough", async () => {
+    await store.upsertTagRecord("declared-but-unused", { description: "reserved for later" });
+    const res = await getTagByName("declared-but-unused");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.count).toBe(0);
+    expect(body.expanded_count).toBe(0);
+  });
+
+  it("MCP list-tags with a nonexistent tag param returns a structured tag_not_found object (not a thrown error, not a synthesized 200)", async () => {
+    const tools = generateMcpTools(store);
+    const listTags = tools.find((t) => t.name === "list-tags")!;
+    const result = await listTags.execute({ tag: "zzznonexistenttag" }) as any;
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("zzznonexistenttag");
+  });
+});
+
+describe("contract: honest queries — expanded_count (#550)", () => {
+  it("list-tags reports expanded_count reflecting the subtype rollup, while count stays the literal per-tag number", async () => {
+    // parent/child fixture: every note is tagged with the CHILD only, so
+    // the literal `count` on "parent" is 0 even though every one of those
+    // notes IS conceptually a "parent" via the declared hierarchy.
+    await store.upsertTagRecord("parent", {});
+    await store.upsertTagRecord("child", { parent_names: ["parent"] });
+    await store.createNote("n1", { tags: ["child"] });
+    await store.createNote("n2", { tags: ["child"] });
+    await store.createNote("n3", { tags: ["parent"] }); // also directly tagged
+
+    const res = await getTags("");
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    const parentRow = body.find((t) => t.name === "parent")!;
+    const childRow = body.find((t) => t.name === "child")!;
+
+    expect(parentRow.count).toBe(1); // only n3 carries the literal "parent" tag
+    expect(parentRow.expanded_count).toBe(3); // n1, n2 (via child) + n3
+    expect(childRow.count).toBe(2);
+    expect(childRow.expanded_count).toBe(2); // "child" has no further descendants
+  });
+
+  it("GET /api/tags/{name} single-tag detail also carries expanded_count", async () => {
+    await store.upsertTagRecord("parent2", {});
+    await store.upsertTagRecord("child2", { parent_names: ["parent2"] });
+    await store.createNote("n1", { tags: ["child2"] });
+
+    const res = await getTagByName("parent2");
+    const body: any = await res.json();
+    expect(body.count).toBe(0);
+    expect(body.expanded_count).toBe(1);
+  });
+});
+
+describe("contract: honest queries — find-path hydration (#550, additive)", () => {
+  it("REST find-path hydrates `nodes` (id+path) and `edges` (source/target/relationship+paths) alongside the original path/relationships shape", async () => {
+    const a = await store.createNote("A", { id: "a", path: "People/Alice" });
+    const b = await store.createNote("B", { id: "b" }); // no path set
+    const c = await store.createNote("C", { id: "c", path: "Projects/X" });
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("b", "c", "related-to");
+
+    const res = await findPath("a", "c");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+
+    // Original shape, byte-identical — back-compat.
+    expect(body.path).toEqual(["a", "b", "c"]);
+    expect(body.relationships).toEqual(["mentions", "related-to"]);
+
+    // Additive hydration.
+    expect(body.nodes).toEqual([
+      { id: "a", path: "People/Alice" },
+      { id: "b", path: null },
+      { id: "c", path: "Projects/X" },
+    ]);
+    expect(body.edges).toEqual([
+      { source: "a", target: "b", relationship: "mentions", sourcePath: "People/Alice", targetPath: null },
+      { source: "b", target: "c", relationship: "related-to", sourcePath: null, targetPath: "Projects/X" },
+    ]);
+  });
+
+  it("MCP find-path hydrates the same nodes/edges shape", async () => {
+    await store.createNote("A", { id: "a", path: "People/Alice" });
+    await store.createNote("B", { id: "b", path: "Projects/X" });
+    await store.createLink("a", "b", "mentions");
+
+    const tools = generateMcpTools(store);
+    const findPathTool = tools.find((t) => t.name === "find-path")!;
+    const result = await findPathTool.execute({ source: "a", target: "b" }) as any;
+    expect(result.nodes).toEqual([
+      { id: "a", path: "People/Alice" },
+      { id: "b", path: "Projects/X" },
+    ]);
+    expect(result.edges).toEqual([
+      { source: "a", target: "b", relationship: "mentions", sourcePath: "People/Alice", targetPath: "Projects/X" },
+    ]);
+  });
 });

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,26 @@ 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,
+        });
+      }
       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");
+  });
+});