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

package/src/contract-errors.test.ts

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

package/src/mcp-http.ts

@@ -139,13 +139,18 @@ async function handleMcp(
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
-      // Domain errors from the core tools (conflict, missing precondition) get
-      // surfaced as JSON-RPC errors with a structured `data` field so an
-      // agent can key off `data.error_type` and the concurrency tokens.
-      // Everything else falls through to an in-band tool error with
-      // `isError: true` — legible but unstructured.
+      // 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
+      // `data` field so an agent can key off `data.error_type` and any
+      // error-specific fields (concurrency tokens, violations, candidates,
+      // ...). vault#554: every domain error class is mapped below, either by
+      // a dedicated branch (full field fidelity) or the generic `error_type`
+      // catch-all near the end. Only a TRULY unknown error (no `error_type`
+      // anywhere on it) falls through to the in-band `isError: true` text.
       const message = err instanceof Error ? err.message : "Unknown error";
       const e = err as {
+        name?: string;
         code?: string;
         note_id?: string;
         note_path?: string | null;
@@ -159,6 +164,14 @@ async function handleMcp(
         error_type?: string;
         got?: unknown;
         hint?: string;
+        path?: string;
+        candidates?: unknown;
+        extension?: string;
+        reason?: string;
+        limit?: number;
+        tag?: string;
+        cycle?: unknown;
+        referencing_tags?: unknown;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -196,6 +209,7 @@ async function handleMcp(
           your_updated_at: e.expected_updated_at,
           path: e.note_path ?? null,
           note_id: e.note_id,
+          hint: "re-read the note (query-notes) and re-apply your change against its current updated_at, or pass force: true to overwrite",
         });
       }
       // State-transition compare-and-set conflict (vault#299 Part B) — a
@@ -210,6 +224,7 @@ async function handleMcp(
           expected_from: e.expected_from,
           to: e.to,
           current: e.current ?? null,
+          hint: "re-read the note's current value for this field and retry the transition from its actual current state",
         });
       }
       // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
@@ -218,6 +233,7 @@ async function handleMcp(
         throw new McpError(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") {
@@ -225,6 +241,107 @@ async function handleMcp(
           error_type: "precondition_required",
           note_id: e.note_id,
           path: e.note_path ?? null,
+          hint: "re-read the note, pass its updated_at as if_updated_at, or pass force: true to skip the check",
+        });
+      }
+      // Any other QueryError (vault#554) — FIELD_NOT_INDEXED, UNKNOWN_OPERATOR,
+      // INVALID_OPERATOR_VALUE, and the various cursor/near/search
+      // incompatibility throws that predate the vault#550/#551 `error_type`
+      // convention (which is why they weren't caught by the two branches
+      // above). Falls back to `error_type: "invalid_query"` — the umbrella
+      // 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, {
+          error_type: e.error_type ?? "invalid_query",
+          code: e.code,
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
+      // Malformed / stale opaque cursor (vault#313, vault#554) — was
+      // entirely unmapped here before (REST already returns `{error, code}`
+      // — no `error_type` either; both surfaces get one now). `code` is
+      // 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, {
+          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, {
+          error_type: "path_conflict",
+          path: e.path,
+        });
+      }
+      // A path lookup matched more than one note (vault#330 S1, vault#554) —
+      // mirrors REST's 409 `ambiguous_path` shape (candidates = the
+      // disambiguating extensions).
+      if (e?.code === "AMBIGUOUS_PATH") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "ambiguous_path",
+          path: e.path,
+          candidates: e.candidates,
+        });
+      }
+      // 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, {
+          error_type: "invalid_extension",
+          extension: e.extension,
+          reason: e.reason,
+        });
+      }
+      // 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, {
+          error_type: "batch_too_large",
+          limit: e.limit,
+          got: e.got,
+        });
+      }
+      // 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, {
+          error_type: "tag_field_conflict",
+          tag: e.tag,
+          violations: e.violations ?? [],
+        });
+      }
+      // parent_names cycle guard (vault#552) — `update-tag`'s write would
+      // close a cycle. Mirrors REST's 409 `parent_cycle` shape; the tool
+      // 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, {
+          error_type: "parent_cycle",
+          tag: e.tag,
+          cycle: e.cycle ?? [],
+        });
+      }
+      // Generic catch-all (vault#554): any remaining error that carries a
+      // stable `error_type` — either a domain error class that stamps it as
+      // an instance property (IndexedFieldError, and the classes handled by
+      // dedicated branches above as defense-in-depth) or a validation leaf
+      // built with `structuredError()` in core/src/mcp.ts (mutually_exclusive,
+      // invalid_content_edit, content_edit_not_found, content_edit_ambiguous,
+      // invalid_state_transition, invalid_parent_names, invalid_relationships,
+      // not_found, ...). This is the backstop that makes "nothing falls
+      // through to the unstructured isError text except a TRULY unknown
+      // 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, {
+          error_type: e.error_type,
+          field: e.field,
+          hint: e.hint,
         });
       }
       return {

package/src/mcp-list-tags-scope.test.ts

@@ -151,4 +151,40 @@ describe("MCP list-tags single-tag path — tag-scope enforcement (vault#550 fol
     expect(names).toContain("health");
     expect(names).not.toContain("work");
   });
+
+  // vault#554 carry-forward: the wrapper's SECOND scrub branch (the one
+  // AFTER the early out-of-scope short-circuit above) fires when the queried
+  // tag itself IS in the allowlist but core still reports tag_not_found —
+  // the hollow-tag case (vault#550: no identity row, no notes directly
+  // carrying it) reached ONLY via a child's `parent_names`. Core computes
+  // `did_you_mean` vault-wide (scope-unaware by architecture), so it can
+  // name an out-of-scope tag; the wrapper must strip that suggestion even
+  // though the queried tag itself passed the allowlist gate. This branch was
+  // execution-verified in a prior review; this test commits it.
+  test("scoped token + in-scope HOLLOW tag (reachable only via a child's parent_names) scrubs an out-of-scope did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // "health" itself has NO identity row and NO note directly carrying it —
+    // it's in the allowlist expansion ONLY because "kale" declares it as a
+    // parent. "kale" is deliberately NOT lexically close to "health" (the
+    // mission's "non-close child") so it can't win did_you_mean and mask
+    // the bug this test targets.
+    await store.upsertTagRecord("kale", { parent_names: ["health"] });
+    await store.createNote("k", { tags: ["kale"] });
+
+    // Out-of-scope decoy, lexically close to "health" (prefix match) — this
+    // is what core's vault-wide suggestSimilarTag would pick if nothing
+    // scrubbed it.
+    await store.createNote("hy", { tags: ["healthy"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "health" })) as any;
+
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("health");
+    // The scrub: did_you_mean must NOT leak the out-of-scope "healthy",
+    // even though "health" (the query) itself passed the allowlist gate.
+    expect(result.did_you_mean).toBeUndefined();
+  });
 });

package/src/mcp-query-notes-search-scope.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Combined tag-scope × full-text-search enforcement (vault#554 carry-forward
+ * — "auth-561" review traced the code clean; this commits the self-verifying
+ * test the review promised).
+ *
+ * `applyTagScopeWrappers`'s `query-notes` wrapper (`src/mcp-tools.ts`) runs
+ * the ENTIRE search — content matching, `search_mode` escaping, `sort` — via
+ * core (scope-unaware by architecture), then filters the returned notes
+ * against the token's allowlist as a post-hoc array `.filter()`
+ * (`noteWithinTagScope`, `src/tag-scope.ts`). Because the filter is applied
+ * uniformly AFTER core returns, in principle no single (mode, sort)
+ * combination is special — but a regression in one code path (e.g. a search
+ * branch that bypasses the wrapper, or a shape the filter doesn't recognize)
+ * could still slip an out-of-scope note through for SOME combination. This
+ * test exercises the full `search_mode × sort` matrix and asserts the
+ * out-of-scope note never appears in any of them.
+ *
+ * Fixture: two notes both match the search term "widget" in punctuation-
+ * bearing content (so literal-mode escaping and advanced-mode raw FTS5 both
+ * still match it) — one tagged in-scope (`health`), one out-of-scope
+ * (`work`). A tag-scoped session ["health"] must see only the in-scope note
+ * across every (search_mode, sort) pairing.
+ */
+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";
+import { SEARCH_MODES } from "../core/src/search-query.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-search-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 queryNotesTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "query-notes")!;
+}
+
+// Normalize the tool's response (bare array, or {notes, next_cursor?,
+// warnings?} in cursor/warnings mode) down to the note-id list actually
+// returned — search is never cursor mode, but stays defensive to shape.
+function idsOf(result: unknown): string[] {
+  if (Array.isArray(result)) return result.map((n: any) => n.id);
+  const notes = (result as any)?.notes;
+  return Array.isArray(notes) ? notes.map((n: any) => n.id) : [];
+}
+
+describe("MCP query-notes search × tag-scope — combined enforcement (vault#554 carry-forward)", () => {
+  test("out-of-scope notes never appear across every search_mode × sort combination", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // Punctuation-bearing content so literal-mode's escaping and
+    // advanced-mode's raw FTS5 passthrough both still match "widget"
+    // cleanly (advanced mode has no operator characters to trip on here).
+    const inScope = await store.createNote("didn't fix the widget yet", { tags: ["health"] });
+    const outOfScope = await store.createNote("ordered a replacement widget", { tags: ["work"] });
+
+    const tool = await queryNotesTool("journal", ["health"]);
+
+    const sorts: (undefined | "asc" | "desc")[] = [undefined, "asc", "desc"];
+    const modes: (undefined | (typeof SEARCH_MODES)[number])[] = [undefined, ...SEARCH_MODES];
+
+    for (const search_mode of modes) {
+      for (const sort of sorts) {
+        const params: Record<string, unknown> = { search: "widget" };
+        if (search_mode !== undefined) params.search_mode = search_mode;
+        if (sort !== undefined) params.sort = sort;
+
+        const result = await tool.execute(params);
+        const ids = idsOf(result);
+
+        expect(ids).toContain(inScope.id);
+        expect(ids).not.toContain(outOfScope.id);
+      }
+    }
+  });
+
+  test("unscoped session sees both notes across the same matrix (control)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    const a = await store.createNote("didn't fix the widget yet", { tags: ["health"] });
+    const b = await store.createNote("ordered a replacement widget", { tags: ["work"] });
+
+    const tool = await queryNotesTool("journal", null);
+
+    for (const search_mode of [undefined, ...SEARCH_MODES]) {
+      for (const sort of [undefined, "asc", "desc"] as const) {
+        const params: Record<string, unknown> = { search: "widget" };
+        if (search_mode !== undefined) params.search_mode = search_mode;
+        if (sort !== undefined) params.sort = sort;
+
+        const ids = idsOf(await tool.execute(params));
+        expect(ids).toContain(a.id);
+        expect(ids).toContain(b.id);
+      }
+    }
+  });
+});