@openparachute/vault 0.7.0-rc.8 → 0.7.1

package/src/vault.test.ts

@@ -675,6 +675,34 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
+  test("vault-info includes a compact structural map WITHOUT include_stats (front-door)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `map-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const vaultStore = getVaultStore(vaultName);
+    await vaultStore.createNote("a", { tags: ["person"], path: "People/Alice" });
+    await vaultStore.createNote("b", { tags: ["person"] }); // no path
+
+    const tools = generateScopedMcpTools(vaultName);
+    const vaultInfo = tools.find((t) => t.name === "vault-info")!;
+
+    // No `include_stats` flag — the map must still be present (that's the
+    // whole point: orient in ONE call, no flag needed).
+    const result = await vaultInfo.execute({}) as any;
+    expect(result.stats).toBeUndefined();
+    expect(result.map).toBeTruthy();
+    expect(result.map.total_notes).toBe(2);
+    expect(result.map.tags).toEqual([{ name: "person", count: 2 }]);
+    expect(result.map.path_buckets).toEqual([{ name: "People", count: 1 }]);
+    expect(result.map.unfiled_notes).toBe(1);
+
+    closeAllStores();
+  });
+
   test("getServerInstruction renders projection markdown for a populated vault (vault#271)", async () => {
     const { getServerInstruction } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
@@ -1267,6 +1295,51 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
+  test("scoped vault-info's map covers only notes reachable through an in-scope tag (front-door)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-vault-info-map-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const store0 = getVaultStore(vaultName);
+    await store0.createNote("a", { tags: ["work"], path: "Work/One" });
+    await store0.createNote("b", { tags: ["work"] }); // no path
+    await store0.createNote("c", { tags: ["personal"], path: "Personal/Two" });
+
+    // Scoped to `work` only.
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const result = await tools.find((t) => t.name === "vault-info")!.execute({}) as any;
+
+    expect(result.map.total_notes).toBe(2); // a, b — "c" (personal) excluded
+    expect(result.map.tags).toEqual([{ name: "work", count: 2 }]);
+    expect(result.map.path_buckets).toEqual([{ name: "Work", count: 1 }]);
+    expect(result.map.unfiled_notes).toBe(1);
+
+    closeAllStores();
+  });
+
+  test("scoped vault-info with an allowlist matching nothing returns an all-zero map, not the full vault", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-vault-info-map-empty-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const store0 = getVaultStore(vaultName);
+    await store0.createNote("a", { tags: ["work"], path: "Work/One" });
+
+    // Scoped to a tag that doesn't exist in this vault at all.
+    const tools = generateScopedMcpTools(vaultName, authForTags(["nonexistent"]) as any);
+    const result = await tools.find((t) => t.name === "vault-info")!.execute({}) as any;
+
+    expect(result.map).toEqual({ total_notes: 0, tags: [], path_buckets: [], unfiled_notes: 0 });
+
+    closeAllStores();
+  });
+
   test("scoped create-note rejects a note whose tags fall outside the allowlist", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
@@ -1815,6 +1888,155 @@ describe("scoped MCP wrapper", async () => {
 
     closeAllStores();
   });
+
+  // vault#555 auth-review CRITICAL: `if_exists` must NOT let a scoped MCP
+  // session read/update/replace an out-of-scope note by naming its path.
+  // The create-note wrapper pre-resolves the path and throws path_conflict on
+  // an out-of-scope hit (byte-identical to a genuine conflict). Each assertion
+  // MUST fail without the wrapper guard.
+  test('scoped create-note if_exists:"ignore" does NOT return an out-of-scope note (throws path_conflict)', async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-ignore-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("SECRET MCP PAYLOAD", { path: "Secret", tags: ["personal"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    // in-scope incoming tag passes the item-tag pre-check; the OUT-OF-SCOPE
+    // existing note at this path must still be blocked.
+    await expect(
+      create.execute({ content: "attempted read", path: "Secret", tags: ["work"], if_exists: "ignore" }),
+    ).rejects.toThrow(/path_conflict/);
+
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"update"/"replace" does NOT mutate an out-of-scope note', async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-mutate-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { keep: "me" } });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+
+    await expect(
+      create.execute({ content: "OVERWRITE", path: "Secret", tags: ["work"], metadata: { injected: true }, if_exists: "update" }),
+    ).rejects.toThrow(/path_conflict/);
+    await expect(
+      create.execute({ content: "REPLACE", path: "Secret", tags: ["work"], if_exists: "replace" }),
+    ).rejects.toThrow(/path_conflict/);
+
+    // Ground truth: the out-of-scope note is untouched by both attempts.
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ keep: "me" });
+    expect(onDisk.tags).toEqual(["personal"]);
+
+    closeAllStores();
+  });
+
+  test("scoped create-note if_exists against an IN-scope note works normally (guard doesn't over-block)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-inscope-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const existing = await store.createNote("WORK BODY", { path: "MyWork", tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "x", path: "MyWork", tags: ["work"], if_exists: "ignore" }) as any;
+    expect(result.existed).toBe(true);
+    expect(result.id).toBe(existing.id);
+    expect(result.content).toBe("WORK BODY");
+
+    closeAllStores();
+  });
+
+  // vault#555 auth-review CRITICAL (RACE PATH — the incomplete-first-fix gap).
+  // The wrapper pre-check + core's proactive getNoteByPath can BOTH miss a note
+  // that a concurrent writer INSERTs, after which core's race backstop
+  // re-resolves the (now-existing, out-of-scope) winner and calls
+  // applyExistingNote on it. Without the in-core `ifExistsVisible` guard the
+  // out-of-scope content leaks / the note is mutated. We reproduce the exact
+  // TOCTOU by monkeypatching store.createNote to (a) create the out-of-scope
+  // note itself (simulating the concurrent winner) and (b) throw
+  // PathConflictError — driving execution straight into the backstop. Both
+  // assertions MUST fail without the in-core guard.
+  async function raceVault(mode: "ignore" | "update" | "replace") {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+    const { PathConflictError } = await import("../core/src/notes.ts");
+
+    const vaultName = `tagscope-ifexists-race-${mode}-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+
+    // Monkeypatch createNote so the target path is created by a "concurrent
+    // writer" with an OUT-OF-SCOPE tag, then the real INSERT loses the race.
+    const origCreate = store.createNote.bind(store);
+    let raced = false;
+    (store as any).createNote = async (content: string, opts: any) => {
+      if (opts?.path === "Secret" && !raced) {
+        raced = true;
+        await origCreate("TOP SECRET RACE PAYLOAD", { path: "Secret", tags: ["personal"] });
+        throw new PathConflictError("Secret");
+      }
+      return origCreate(content, opts);
+    };
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    return { store, create, closeAllStores };
+  }
+
+  test('scoped create-note if_exists:"ignore" RACE backstop does NOT leak out-of-scope content', async () => {
+    const { store, create, closeAllStores } = await raceVault("ignore");
+    await expect(
+      create.execute({ content: "attempted", path: "Secret", tags: ["work"], if_exists: "ignore" }),
+    ).rejects.toThrow(/path_conflict/);
+    // The concurrently-created out-of-scope note is byte-unchanged and its
+    // payload never reached the caller (the throw carries only the path).
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD");
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"update" RACE backstop does NOT mutate the out-of-scope note', async () => {
+    const { store, create, closeAllStores } = await raceVault("update");
+    await expect(
+      create.execute({ content: "OVERWRITE", path: "Secret", tags: ["work"], metadata: { injected: true }, if_exists: "update" }),
+    ).rejects.toThrow(/path_conflict/);
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD"); // unmutated
+    expect(onDisk.metadata ?? {}).toEqual({});
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"replace" RACE backstop does NOT mutate the out-of-scope note', async () => {
+    const { store, create, closeAllStores } = await raceVault("replace");
+    await expect(
+      create.execute({ content: "REPLACE", path: "Secret", tags: ["work"], if_exists: "replace" }),
+    ).rejects.toThrow(/path_conflict/);
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD"); // unmutated
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
 });
 
 describe("auth permissions", () => {
@@ -2184,6 +2406,37 @@ describe("HTTP /notes", async () => {
     expect(body.content).toBe("hello");
   });
 
+  // ---- Title-fallback resolution (additive — id/path/basename still win first) ----
+
+  test("GET /notes/:idOrPath resolves via H1 title when id and path both miss", async () => {
+    await store.createNote("# My Great Note\n\nBody.", { path: "Inbox/2026-07-10-xyz" });
+    const enc = encodeURIComponent("My Great Note");
+    const res = await handleNotes(mkReq("GET", `/notes/${enc}`), store, `/${enc}`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.path).toBe("Inbox/2026-07-10-xyz");
+  });
+
+  test("GET /notes/:idOrPath exact path still wins over a same-named title on another note", async () => {
+    const byPath = await store.createNote("Path note", { path: "My Great Note" });
+    await store.createNote("# My Great Note\n\nOther body.", { path: "Inbox/other" });
+    const enc = encodeURIComponent("My Great Note");
+    const res = await handleNotes(mkReq("GET", `/notes/${enc}`), store, `/${enc}`);
+    const body = await res.json() as any;
+    expect(body.id).toBe(byPath.id);
+    expect(body.content).toBe("Path note");
+  });
+
+  test("GET /notes/:idOrPath stays 404 when 2+ notes share the same H1 title", async () => {
+    await store.createNote("# Dup Note\n\nA.", { path: "Inbox/dup-a" });
+    await store.createNote("# Dup Note\n\nB.", { path: "Inbox/dup-b" });
+    const enc = encodeURIComponent("Dup Note");
+    const res = await handleNotes(mkReq("GET", `/notes/${enc}`), store, `/${enc}`);
+    expect(res.status).toBe(404);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("not_found");
+  });
+
   test("GET /notes/:id?include_content=false returns lean shape", async () => {
     await store.createNote("hello", { id: "x" });
     const res = await handleNotes(mkReq("GET", "/notes/x?include_content=false"), store, "/x");
@@ -3988,6 +4241,111 @@ describe("HTTP tag-scope confidentiality (security review)", async () => {
     expect(targets).toContain("NoSuchPersonal");
   });
 
+  // vault#555 auth-review CRITICAL: `if_exists` must NOT become a tag-scope
+  // bypass. A scoped token naming an out-of-scope note's PATH must not read
+  // (ignore), update, or replace it — treat it as a path_conflict (path taken,
+  // invisible to this caller). Each assertion MUST fail without the guard in
+  // applyExistingNote.
+  test('if_exists:"ignore" does NOT return an out-of-scope note by path (POST /notes)', async () => {
+    await store.createNote("SECRET WORK PAYLOAD", { path: "Secret", tags: ["personal"] });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "attempted read",
+        path: "Secret",
+        tags: ["work"], // in-scope incoming tag — passes the item-tag pre-check
+        if_exists: "ignore",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    // Path is taken but invisible to this caller → 409 path_conflict, and the
+    // secret content appears NOWHERE in the response.
+    expect(res.status).toBe(409);
+    const text = await res.text();
+    expect(text).not.toContain("SECRET WORK PAYLOAD");
+    expect(JSON.parse(text).error_type).toBe("path_conflict");
+  });
+
+  test('if_exists:"update" does NOT mutate an out-of-scope note by path (POST /notes)', async () => {
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { keep: "me" } });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "OVERWRITE ATTEMPT",
+        path: "Secret",
+        tags: ["work"],
+        metadata: { injected: true },
+        if_exists: "update",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(409);
+    // Ground truth: the out-of-scope note is byte-for-byte unchanged.
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ keep: "me" });
+    expect(onDisk.tags).toEqual(["personal"]); // "work" never applied
+  });
+
+  test('if_exists:"replace" does NOT mutate an out-of-scope note by path (POST /notes)', async () => {
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { a: 1 } });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "REPLACE ATTEMPT",
+        path: "Secret",
+        tags: ["work"],
+        if_exists: "replace",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(409);
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ a: 1 });
+  });
+
+  test("UNSCOPED if_exists:ignore still returns the existing note (regression — guard is scope-gated)", async () => {
+    const existing = await store.createNote("PLAIN BODY", { path: "Plain", tags: ["work"] });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "x", path: "Plain", if_exists: "ignore" }),
+      store,
+      "",
+      "v",
+      NO_SCOPE,
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(existing.id);
+    expect(body.content).toBe("PLAIN BODY");
+  });
+
+  test("in-scope if_exists:ignore against an in-scope note works normally (guard doesn't over-block)", async () => {
+    const existing = await store.createNote("WORK BODY", { path: "MyWork", tags: ["work"] });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "x", path: "MyWork", tags: ["work"], if_exists: "ignore" }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(existing.id);
+    expect(body.content).toBe("WORK BODY");
+  });
+
 });
 
 describe("HTTP /notes include_link_count + order_by=link_count (vault feedback #4)", async () => {
@@ -4418,6 +4776,104 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(links[0]!.relationship).toBe("knows");
   });
 
+  // vault#570 — content-parsed [[wikilinks]] to a missing target used to
+  // fire NO write-time warning over REST either, mirroring the MCP fix.
+  test("POST /notes with a content [[wikilink]] to a missing target: warns (unresolved_link)", async () => {
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "See [[Nowhere REST]] for details." }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.warnings).toBeDefined();
+    expect(body.warnings[0].code).toBe("unresolved_link");
+    expect(body.warnings[0].target).toBe("Nowhere REST");
+    expect(await store.getLinks(body.id, { direction: "outbound" })).toHaveLength(0);
+  });
+
+  // vault#570 — a target matching ≥2 notes is a distinct situation from a
+  // genuine miss: `ambiguous_link`, not `unresolved_link`, and no edge.
+  test("POST /notes with a content [[wikilink]] to an AMBIGUOUS target: ambiguous_link, no edge", async () => {
+    await store.createNote("A", { path: "Folder1/RestDup" });
+    await store.createNote("B", { path: "Folder2/RestDup" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "See [[RestDup]] for details." }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.warnings).toBeDefined();
+    expect(body.warnings[0].code).toBe("ambiguous_link");
+    expect(body.warnings[0].target).toBe("RestDup");
+    expect(body.warnings[0].candidate_count).toBe(2);
+    expect(await store.getLinks(body.id, { direction: "outbound" })).toHaveLength(0);
+  });
+
+  // vault#570 — a structured `links` entry against an ambiguous target gets
+  // the same treatment over REST (shared core implementation).
+  test("POST /notes with a structured link to an AMBIGUOUS target: ambiguous_link, no edge", async () => {
+    await store.createNote("A", { path: "Folder1/RestDup2" });
+    await store.createNote("B", { path: "Folder2/RestDup2" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "no wikilinks here",
+        links: [{ target: "RestDup2", relationship: "knows" }],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.warnings).toBeDefined();
+    expect(body.warnings[0].code).toBe("ambiguous_link");
+    expect(body.warnings[0].candidate_count).toBe(2);
+    expect(await store.getLinks(body.id, { direction: "outbound" })).toHaveLength(0);
+  });
+
+  test("PATCH content update with a [[wikilink]] to a missing target: warns (unresolved_link)", async () => {
+    await store.createNote("plain", { id: "patchable", path: "PatchableRest" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/patchable", { content: "now references [[Not Yet Real REST]]", force: true }),
+      store,
+      "/patchable",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.warnings).toBeDefined();
+    expect(body.warnings[0].code).toBe("unresolved_link");
+    expect(body.warnings[0].target).toBe("Not Yet Real REST");
+
+    // A tags-only follow-up PATCH must not re-surface the warning.
+    const tagOnly = await handleNotes(
+      mkReq("PATCH", "/notes/patchable", { tags: { add: ["x"] }, force: true }),
+      store,
+      "/patchable",
+    );
+    const tagOnlyBody = await tagOnly.json() as any;
+    expect(tagOnlyBody.warnings).toBeUndefined();
+  });
+
+  // vault#570 — `if_missing: "create"` is a distinct create-shaped code
+  // path in routes.ts (separate from POST /notes); it needs the same fix.
+  test("PATCH if_missing:create with a [[wikilink]] to a missing target: warns (unresolved_link)", async () => {
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/brand-new-rest", {
+        if_missing: "create",
+        content: "See [[Nowhere Upsert REST]].",
+      }),
+      store,
+      "/brand-new-rest",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+    expect(body.warnings).toBeDefined();
+    expect(body.warnings[0].code).toBe("unresolved_link");
+    expect(body.warnings[0].target).toBe("Nowhere Upsert REST");
+  });
+
   test("PATCH without a link mutation or flag does NOT include links", async () => {
     await store.createNote("a", { id: "a" });
     await store.createNote("b", { id: "b" });
@@ -4964,6 +5420,206 @@ describe("HTTP POST /notes — validation_status attachment (vault#287)", async
   });
 });
 
+// vault#555 — HTTP POST /notes with if_exists: idempotent upsert on a path
+// conflict. Mirrors the MCP create-note tool's if_exists contract exactly
+// (independent REST-layer reimplementation, same core primitives).
+describe("HTTP POST /notes — if_exists (vault#555)", async () => {
+  test("default (no if_exists) still 409s — back-compat", async () => {
+    await store.createNote("first", { path: "Inbox/rest-dup" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "second", path: "Inbox/rest-dup" }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(409);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("path_conflict");
+  });
+
+  test('if_exists:"ignore" returns 201 with the existing note untouched + existed:true', async () => {
+    const first = await store.createNote("original", { path: "Inbox/rest-ignore", metadata: { v: 1 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "attempted overwrite",
+        path: "Inbox/rest-ignore",
+        metadata: { v: 2 },
+        if_exists: "ignore",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(first.id);
+    expect(body.content).toBe("original");
+    expect(body.metadata?.v).toBe(1);
+  });
+
+  test('if_exists:"update" full-replaces content and RFC-7386-merges metadata', async () => {
+    await store.createNote("v1", { path: "Inbox/rest-update", metadata: { a: 1, b: 2 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "v2",
+        path: "Inbox/rest-update",
+        metadata: { b: null, c: 3 },
+        if_exists: "update",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.content).toBe("v2");
+    expect(body.metadata).toEqual({ a: 1, c: 3 });
+  });
+
+  test('if_exists:"replace" wholesale-overwrites content + metadata, keeps id/createdAt', async () => {
+    const first = await store.createNote("v1", { path: "Inbox/rest-replace", metadata: { a: 1, b: 2 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "v2",
+        path: "Inbox/rest-replace",
+        metadata: { c: 3 },
+        if_exists: "replace",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(first.id);
+    expect(body.createdAt).toBe(first.createdAt);
+    expect(body.content).toBe("v2");
+    expect(body.metadata).toEqual({ c: 3 });
+  });
+
+  test("plain POST (no if_exists) sees zero response-shape change", async () => {
+    const res = await handleNotes(mkReq("POST", "/notes", { content: "plain" }), store, "");
+    const body = await res.json() as any;
+    expect("existed" in body).toBe(false);
+  });
+
+  test("batch: if_exists is per-item — a top-level default is NOT inherited", async () => {
+    await store.createNote("existing", { path: "Inbox/rest-batch-conflict" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        if_exists: "ignore",
+        notes: [{ content: "conflict", path: "Inbox/rest-batch-conflict" }],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(409);
+  });
+
+  test("summary:true returns {created, ids, failed} for a batch", async () => {
+    await store.createNote("pre-existing", { path: "Inbox/rest-sum-existing" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        summary: true,
+        notes: [
+          { content: "fresh", path: "Inbox/rest-sum-fresh", if_exists: "ignore" },
+          { content: "ignored", path: "Inbox/rest-sum-existing", if_exists: "ignore" },
+        ],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.created).toBe(1);
+    expect(body.ids).toHaveLength(2);
+    expect(body.failed).toEqual([]);
+  });
+
+  test("summary is ignored on a single-note POST", async () => {
+    const res = await handleNotes(mkReq("POST", "/notes", { content: "solo", summary: true }), store, "");
+    const body = await res.json() as any;
+    expect(body.content).toBe("solo");
+    expect(body.created).toBeUndefined();
+  });
+
+  // vault#555 CRITICAL 2 (REST tripwire — the generalist-flagged coverage gap:
+  // the core-side tests didn't guard the REST gate, so reverting routes.ts's
+  // gate alone left all tests green). REST parity of the two core tests.
+  test('if_exists:"update" with ONLY tags added still advances updated_at (POST /notes)', async () => {
+    const first = await store.createNote("body", { path: "rest-tagonly", tags: ["alpha"] });
+    const before = first.updatedAt!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { path: "rest-tagonly", tags: ["beta"], if_exists: "update" }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.tags?.sort()).toEqual(["alpha", "beta"]);
+    const after = (await store.getNote(first.id))!.updatedAt!;
+    expect(after > before).toBe(true);
+  });
+
+  test('if_exists:"update" with ONLY links added still advances updated_at (POST /notes)', async () => {
+    await store.createNote("target", { id: "rest-tgt-linkonly", path: "Targets/rest-linkonly" });
+    const first = await store.createNote("body", { path: "rest-linkonly", tags: ["alpha"] });
+    const before = first.updatedAt!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        path: "rest-linkonly",
+        links: [{ target: "rest-tgt-linkonly", relationship: "relates-to" }],
+        if_exists: "update",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const after = (await store.getNote(first.id))!.updatedAt!;
+    expect(after > before).toBe(true);
+  });
+});
+
+// vault#555 — has_broken_links / include_broken_links on GET /notes.
+describe("HTTP GET /notes — has_broken_links / include_broken_links (vault#555)", async () => {
+  test("has_broken_links=true filters to notes with a dangling wikilink", async () => {
+    await store.createNote("[[Nowhere]]", { path: "rest-broken" });
+    await store.createNote("clean", { path: "rest-clean" });
+    const res = await handleNotes(mkReq("GET", "/notes?has_broken_links=true&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.path)).toEqual(["rest-broken"]);
+  });
+
+  test("has_broken_links=false excludes them", async () => {
+    await store.createNote("[[Nowhere]]", { path: "rest-broken2" });
+    await store.createNote("clean", { path: "rest-clean2" });
+    const res = await handleNotes(mkReq("GET", "/notes?has_broken_links=false&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.path)).toEqual(["rest-clean2"]);
+  });
+
+  test("include_broken_links on a single note surfaces {target, relationship}", async () => {
+    await store.createNote("[[Ghost]]", { path: "rest-single-broken" });
+    const res = await handleNotes(mkReq("GET", "/notes?id=rest-single-broken&include_broken_links=true"), store, "");
+    const body = await res.json() as any;
+    expect(body.broken_links).toEqual([{ target: "Ghost", relationship: "wikilink" }]);
+  });
+
+  test("include_broken_links in list mode is batched per note", async () => {
+    await store.createNote("[[Ghost A]]", { path: "rest-list-a" });
+    await store.createNote("clean", { path: "rest-list-b" });
+    const res = await handleNotes(mkReq("GET", "/notes?include_broken_links=true&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    const byPath = new Map(body.map((n: any) => [n.path, n.broken_links]));
+    expect(byPath.get("rest-list-a")).toEqual([{ target: "Ghost A", relationship: "wikilink" }]);
+    expect(byPath.get("rest-list-b")).toEqual([]);
+  });
+});
+
 // vault#309 — HTTP PATCH /notes/:id with if_missing: "create" mirrors
 // the MCP update-note path. Sync loops (Gitcoin Brain et al) use this
 // for idempotent upsert without a separate query-first round trip.
@@ -5707,19 +6363,24 @@ describe("stateless MCP transport", async () => {
     expect(toolNames).toContain("list-tags");
     expect(toolNames).toContain("find-path");
     expect(toolNames).toContain("vault-info");
+    // `doctor` moved admin → read (re-tier): a read-only, tag-scope-
+    // restricted diagnostic, visible to a plain vault:read session.
+    expect(toolNames).toContain("doctor");
     // Mutation tools are hidden — filter applied before advertising
     expect(toolNames).not.toContain("create-note");
     expect(toolNames).not.toContain("update-note");
     expect(toolNames).not.toContain("delete-note");
+    // Tag-schema/taxonomy tools moved write → admin (re-tier): hidden from
+    // a vault:read (and, per the next describe block, a plain vault:write)
+    // session — they now need vault:admin.
     expect(toolNames).not.toContain("update-tag");
     expect(toolNames).not.toContain("delete-tag");
     expect(toolNames).not.toContain("rename-tag");
     expect(toolNames).not.toContain("merge-tags");
     // Admin tools (vault#376) are hidden too
     expect(toolNames).not.toContain("manage-token");
-    expect(toolNames).not.toContain("doctor");
-    // Read tier is exactly 4 tools.
-    expect(toolNames.length).toBe(4);
+    // Read tier is exactly 5 tools (doctor added by the re-tier).
+    expect(toolNames.length).toBe(5);
 
     closeAllStores();
   });
@@ -5767,7 +6428,7 @@ describe("stateless MCP transport", async () => {
     // the required scope — the inner guard fired even though the outer tool
     // gate allowed read-only callers through for stats.
     expect(body.result.isError).toBe(true);
-    expect(body.result.content[0].text).toContain("vault:write");
+    expect(body.result.content[0].text).toContain("vault:admin");
 
     // And critically: the vault description must NOT have been mutated.
     const cfg = readVaultConfig(vaultName);
@@ -5776,7 +6437,7 @@ describe("stateless MCP transport", async () => {
     closeAllStores();
   });
 
-  test("tools/call of vault-info with description arg and vault:write scope is allowed", async () => {
+  test("tools/call of vault-info with description arg and vault:write scope is refused (re-tier: description-write now needs admin)", async () => {
     const { handleScopedMcp } = await import("./mcp-http.ts");
     const { writeVaultConfig, readVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
@@ -5813,10 +6474,58 @@ describe("stateless MCP transport", async () => {
       scoped_tags: null,
     });
 
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // Was `isError: false` pre-re-tier — a plain vault:write session could
+    // update the vault's own description. Now needs vault:admin.
+    expect(body.result.isError).toBe(true);
+    expect(body.result.content[0].text).toContain("vault:admin");
+    expect(readVaultConfig(vaultName)?.description).toBe("original");
+
+    closeAllStores();
+  });
+
+  test("tools/call of vault-info with description arg and vault:admin scope is allowed", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig, readVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `scope-vault-info-admin-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "original",
+    });
+
+    const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "accept": "application/json, text/event-stream",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "vault-info",
+          arguments: { description: "updated via admin scope" },
+        },
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+      scoped_tags: null,
+    });
+
     expect(res.status).toBe(200);
     const body = await res.json() as any;
     expect(body.result.isError).toBeFalsy();
-    expect(readVaultConfig(vaultName)?.description).toBe("updated via write scope");
+    expect(readVaultConfig(vaultName)?.description).toBe("updated via admin scope");
 
     closeAllStores();
   });
@@ -5952,15 +6661,15 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     return names;
   }
 
-  test("vault:read sees exactly the 4 read tools", async () => {
+  test("vault:read sees exactly the 5 read tools (doctor moved admin → read)", async () => {
     const names = await listToolNames(["vault:read"]);
     expect(new Set(names)).toEqual(
-      new Set(["query-notes", "list-tags", "find-path", "vault-info"]),
+      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor"]),
     );
-    expect(names.length).toBe(4);
+    expect(names.length).toBe(5);
   });
 
-  test("vault:read + vault:write sees the 11 read+write tools", async () => {
+  test("vault:read + vault:write sees the 8 read+write tools (tag-schema tools moved write → admin)", async () => {
     const names = await listToolNames(["vault:read", "vault:write"]);
     expect(new Set(names)).toEqual(
       new Set([
@@ -5968,30 +6677,31 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
         "list-tags",
         "find-path",
         "vault-info",
+        "doctor",
         "create-note",
         "update-note",
         "delete-note",
-        "update-tag",
-        "delete-tag",
-        // vault#552: MCP parity with the pre-existing REST rename/merge engine.
-        "rename-tag",
-        "merge-tags",
       ]),
     );
-    expect(names.length).toBe(11);
+    expect(names.length).toBe(8);
     expect(names).not.toContain("manage-token");
-    expect(names).not.toContain("doctor");
-    // Aaron 2026-05-27: delete-* are write-tier (same destructive verb as
-    // update). Only manage-token/prune-schema/doctor are admin-gated.
+    // Re-tier (this PR): update-tag/delete-tag/rename-tag/merge-tags are now
+    // admin-tier — structure/taxonomy curation, not content authorship.
+    // Only delete-note (content) stays write-tier.
+    expect(names).not.toContain("update-tag");
+    expect(names).not.toContain("delete-tag");
+    expect(names).not.toContain("rename-tag");
+    expect(names).not.toContain("merge-tags");
     expect(names).toContain("delete-note");
-    expect(names).toContain("delete-tag");
   });
 
-  test("vault:admin sees all 14 tools including manage-token + prune-schema + doctor", async () => {
+  test("vault:admin sees all 14 tools including manage-token + prune-schema + the tag-schema tools", async () => {
     const names = await listToolNames(["vault:read", "vault:write", "vault:admin"]);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
     expect(names).toContain("doctor");
+    expect(names).toContain("update-tag");
+    expect(names).toContain("delete-tag");
     expect(names).toContain("rename-tag");
     expect(names).toContain("merge-tags");
     expect(names.length).toBe(14);
@@ -6081,6 +6791,144 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
   });
 });
 
+// ===========================================================================
+// Write/admin re-tier — schema/taxonomy-curation tools moved write → admin,
+// doctor moved admin → read. Content-authorship (write) is now separate from
+// structure/taxonomy/schema-curation (admin). No new scope — same
+// read/write/admin vocabulary, only which tier each tool requires moves.
+// ===========================================================================
+
+describe("MCP write/admin re-tier — scope enforcement at the tools/call layer", () => {
+  async function callTool(
+    vaultName: string,
+    scopes: string[],
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<any> {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+    });
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: scopes.includes("vault:write") || scopes.includes("vault:admin") ? "full" : "read",
+      scopes,
+      legacyDerived: false,
+      scoped_tags: null,
+    } as any);
+    return res.json();
+  }
+
+  test("vault:write CAN create-note but is DENIED rename-tag/merge-tags/delete-tag/update-tag (now admin-tier)", async () => {
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `retier-write-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("seed", { tags: ["mine"] });
+
+    const WRITE = ["vault:read", "vault:write"];
+
+    // Allowed: content authorship.
+    const create = await callTool(vaultName, WRITE, "create-note", { content: "hello", tags: ["mine"] });
+    expect(create.result?.isError).toBeFalsy();
+
+    // Denied: each now requires vault:admin, not vault:write.
+    const rename = await callTool(vaultName, WRITE, "rename-tag", { old_name: "mine", new_name: "mine2" });
+    expect(rename.result?.isError).toBe(true);
+    expect(rename.result.content[0].text).toContain("Unknown tool");
+
+    const merge = await callTool(vaultName, WRITE, "merge-tags", { sources: ["mine"], target: "mine2" });
+    expect(merge.result?.isError).toBe(true);
+    expect(merge.result.content[0].text).toContain("Unknown tool");
+
+    const del = await callTool(vaultName, WRITE, "delete-tag", { tag: "mine" });
+    expect(del.result?.isError).toBe(true);
+    expect(del.result.content[0].text).toContain("Unknown tool");
+
+    const upd = await callTool(vaultName, WRITE, "update-tag", { tag: "mine", description: "hijacked" });
+    expect(upd.result?.isError).toBe(true);
+    expect(upd.result.content[0].text).toContain("Unknown tool");
+
+    // Untouched — the denied calls above never reached core. "mine" already
+    // has a bare identity row (auto-inserted when the seed note was tagged),
+    // but its description is still unset — update-tag never ran.
+    expect((await store.getTagRecord("mine"))?.description ?? null).toBeNull();
+    const stillThere = await store.listTags();
+    expect(stillThere.some((t) => t.name === "mine")).toBe(true);
+
+    closeAllStores();
+  });
+
+  test("vault:read CAN run doctor (now read-tier)", async () => {
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `retier-read-doctor-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const result = await callTool(vaultName, ["vault:read"], "doctor", {});
+    expect(result.result?.isError).toBeFalsy();
+    const report = JSON.parse(result.result.content[0].text);
+    expect(report.findings).toBeDefined();
+    expect(report.summary).toBeDefined();
+
+    closeAllStores();
+  });
+
+  test("vault:write is DENIED the vault-info description write (now admin-tier)", async () => {
+    const { writeVaultConfig, readVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `retier-write-vaultinfo-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString(), description: "orig" });
+
+    const result = await callTool(vaultName, ["vault:read", "vault:write"], "vault-info", { description: "nope" });
+    expect(result.result?.isError).toBe(true);
+    expect(result.result.content[0].text).toContain("vault:admin");
+    expect(readVaultConfig(vaultName)?.description).toBe("orig");
+
+    closeAllStores();
+  });
+
+  test("vault:admin CAN do all of the above — create-note, rename/merge/delete/update-tag, doctor, and the vault-info description write", async () => {
+    const { writeVaultConfig, readVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `retier-admin-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString(), description: "orig" });
+    const store = getVaultStore(vaultName);
+    await store.upsertTagRecord("a", {});
+    await store.upsertTagRecord("b", {});
+    await store.createNote("seed", { tags: ["a"] });
+
+    const ADMIN = ["vault:read", "vault:write", "vault:admin"];
+
+    const create = await callTool(vaultName, ADMIN, "create-note", { content: "hello", tags: ["a"] });
+    expect(create.result?.isError).toBeFalsy();
+
+    const upd = await callTool(vaultName, ADMIN, "update-tag", { tag: "a", description: "updated" });
+    expect(upd.result?.isError).toBeFalsy();
+
+    const doctor = await callTool(vaultName, ADMIN, "doctor", {});
+    expect(doctor.result?.isError).toBeFalsy();
+
+    const vinfo = await callTool(vaultName, ADMIN, "vault-info", { description: "updated via admin" });
+    expect(vinfo.result?.isError).toBeFalsy();
+    expect(readVaultConfig(vaultName)?.description).toBe("updated via admin");
+
+    const merge = await callTool(vaultName, ADMIN, "merge-tags", { sources: ["b"], target: "a" });
+    expect(merge.result?.isError).toBeFalsy();
+
+    const del = await callTool(vaultName, ADMIN, "delete-tag", { tag: "a" });
+    expect(del.result?.isError).toBeFalsy();
+
+    closeAllStores();
+  });
+});
+
 // ===========================================================================
 // vault#376 — Change 2: manage-token mint/revoke/list
 // ===========================================================================
@@ -6863,3 +7711,57 @@ describe("handleVault: transcription capability (scribe-fold Phase 1)", async ()
   });
 });
 
+describe("handleVault: front-door structural map", async () => {
+  test("GET always includes `map` — no ?include_stats needed", async () => {
+    await store.createNote("a", { tags: ["person"], path: "People/Alice" });
+    await store.createNote("b", { tags: ["person"] }); // no path
+
+    const cfg = { name: "default" } as { name: string };
+    const res = await handleVault(mkReq("GET", "/vault"), store, cfg as any);
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.stats).toBeUndefined();
+    expect(body.map).toBeTruthy();
+    expect(body.map.total_notes).toBe(2);
+    expect(body.map.tags).toEqual([{ name: "person", count: 2 }]);
+    expect(body.map.path_buckets).toEqual([{ name: "People", count: 1 }]);
+    expect(body.map.unfiled_notes).toBe(1);
+  });
+
+  test("?include_stats=true adds stats ALONGSIDE map, not instead of it", async () => {
+    await store.createNote("a", { tags: ["person"] });
+    const cfg = { name: "default" } as { name: string };
+    const res = await handleVault(mkReq("GET", "/vault?include_stats=true"), store, cfg as any);
+    const body = await res.json() as any;
+    expect(body.stats).toBeTruthy();
+    expect(body.map).toBeTruthy();
+  });
+
+  test("a tag-scoped caller's map covers only notes reachable through an in-scope tag", async () => {
+    await store.createNote("a", { tags: ["work"], path: "Work/One" });
+    await store.createNote("b", { tags: ["work"] }); // no path
+    await store.createNote("c", { tags: ["personal"], path: "Personal/Two" });
+
+    const cfg = { name: "default" } as { name: string };
+    const scope: TagScopeCtx = { allowed: await expandTokenTagScope(store, ["work"]), raw: ["work"] };
+    const res = await handleVault(mkReq("GET", "/vault"), store, cfg as any, undefined, undefined, scope);
+    const body = await res.json() as any;
+
+    expect(body.map.total_notes).toBe(2); // a, b — "c" (personal) excluded
+    expect(body.map.tags).toEqual([{ name: "work", count: 2 }]);
+    expect(body.map.path_buckets).toEqual([{ name: "Work", count: 1 }]);
+    expect(body.map.unfiled_notes).toBe(1);
+  });
+
+  test("a tag-scoped caller whose allowlist matches nothing gets an all-zero map, not the full vault", async () => {
+    await store.createNote("a", { tags: ["work"], path: "Work/One" });
+
+    const cfg = { name: "default" } as { name: string };
+    const scope: TagScopeCtx = { allowed: await expandTokenTagScope(store, ["nonexistent"]), raw: ["nonexistent"] };
+    const res = await handleVault(mkReq("GET", "/vault"), store, cfg as any, undefined, undefined, scope);
+    const body = await res.json() as any;
+
+    expect(body.map).toEqual({ total_notes: 0, tags: [], path_buckets: [], unfiled_notes: 0 });
+  });
+});
+