@openparachute/vault 0.3.1 → 0.4.0

package/src/vault.test.ts

@@ -10,7 +10,7 @@ import { tmpdir } from "os";
 import { BunStore } from "./vault-store.ts";
 import { generateMcpTools } from "../core/src/mcp.ts";
 import { getLinksHydrated } from "../core/src/links.ts";
-import { handleNotes, handleTags, handleFindPath, handleVault } from "./routes.ts";
+import { handleNotes, handleTags, handleNoteSchemas, handleFindPath, handleVault } from "./routes.ts";
 import { extractApiKey } from "./auth.ts";
 
 let db: Database;
@@ -476,9 +476,9 @@ describe("deeper link queries", async () => {
 });
 
 describe("MCP tools", async () => {
-  test("generates all 9 core tools", () => {
+  test("generates the consolidated tool set", () => {
     const tools = generateMcpTools(store);
-    expect(tools.length).toBe(9);
+    expect(tools.length).toBe(16);
 
     const names = tools.map((t) => t.name);
     expect(names).toContain("query-notes");
@@ -488,7 +488,14 @@ describe("MCP tools", async () => {
     expect(names).toContain("list-tags");
     expect(names).toContain("update-tag");
     expect(names).toContain("delete-tag");
+    expect(names).toContain("list-note-schemas");
+    expect(names).toContain("update-note-schema");
+    expect(names).toContain("delete-note-schema");
+    expect(names).toContain("list-schema-mappings");
+    expect(names).toContain("set-schema-mapping");
+    expect(names).toContain("delete-schema-mapping");
     expect(names).toContain("find-path");
+    expect(names).toContain("synthesize-notes");
     expect(names).toContain("vault-info");
   });
 
@@ -711,6 +718,275 @@ describe("scoped MCP wrapper", async () => {
     close();
   });
 
+  // -- tag-scoped MCP wrappers (patterns/tag-scoped-tokens.md) ------------
+  //
+  // These pin the behavior of `applyTagScopeWrappers` in mcp-tools.ts: each
+  // wrapped tool's execute() honors the auth's scoped_tags allowlist. The
+  // unscoped path (auth.scoped_tags === null) remains identical to the
+  // baseline scoped MCP tests above; here we only assert the *scoped*
+  // path's deltas.
+
+  function authForTags(tags: string[]) {
+    return {
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+      scoped_tags: tags,
+    } as const;
+  }
+
+  test("scoped query-notes filters list to in-scope notes only", 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-query-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("h", { tags: ["health"] });
+    await store.createNote("w", { tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({}) as any[];
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.every((n: any) => n.tags.includes("health"))).toBe(true);
+    expect(result.find((n: any) => n.content === "w")).toBeUndefined();
+
+    closeAllStores();
+  });
+
+  test("scoped query-notes by id 404s on 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-byid-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const w = await store.createNote("w", { tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: w.id }) as any;
+    expect(result.error).toBe("Note not found");
+    expect(result.id).toBe(w.id);
+
+    closeAllStores();
+  });
+
+  test("scoped list-tags filters to allowlisted root + descendants", 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-tags-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.createNote("h", { tags: ["health"] });
+    await store.createNote("hf", { tags: ["health/food"] });
+    await store.createNote("w", { tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const listTags = tools.find((t) => t.name === "list-tags")!;
+    const result = await listTags.execute({}) as any[];
+    const names = result.map((t) => t.name);
+    expect(names).toContain("health");
+    expect(names).toContain("health/food");
+    expect(names).not.toContain("work");
+
+    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");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-create-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    getVaultStore(vaultName);
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "denied", tags: ["work"] }) as any;
+    expect(result.error).toBe("Forbidden");
+    expect(result.error_type).toBe("tag_scope_violation");
+    expect(result.scoped_tags).toEqual(["health"]);
+
+    closeAllStores();
+  });
+
+  test("scoped create-note batch rejects atomically when any note is out of scope", 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-batch-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      notes: [
+        { content: "ok", tags: ["health"] },
+        { content: "no", tags: ["work"] },
+      ],
+    }) as any;
+    expect(result.error).toBe("Forbidden");
+    // Atomic — neither write should have landed.
+    expect((await store.listTags()).length).toBe(0);
+
+    closeAllStores();
+  });
+
+  test("scoped delete-note 404s on an out-of-scope note (no leak)", 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-del-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const w = await store.createNote("w", { tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const del = tools.find((t) => t.name === "delete-note")!;
+    const result = await del.execute({ id: w.id }) as any;
+    expect(result.error).toBe("Note not found");
+    // Untouched.
+    expect(await store.getNote(w.id)).toBeTruthy();
+
+    closeAllStores();
+  });
+
+  test("scoped update-tag/delete-tag refuse to touch out-of-scope tags", 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-tagop-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("w", { tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    const del = tools.find((t) => t.name === "delete-tag")!;
+
+    const updateRes = await update.execute({ tag: "work", description: "denied" }) as any;
+    expect(updateRes.error).toBe("Forbidden");
+    expect(updateRes.error_type).toBe("tag_scope_violation");
+
+    const delRes = await del.execute({ tag: "work" }) as any;
+    expect(delRes.error).toBe("Forbidden");
+
+    // The `work` tag is still attached to its note.
+    expect((await store.listTags()).find((t) => t.name === "work")).toBeTruthy();
+
+    closeAllStores();
+  });
+
+  // -- Q6: orphan sub-tag fail-open via string-form root ------------------
+
+  test("scoped query-notes sees orphan sub-tag via string-form root (no schema)", 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-orphan-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    // No `_tags/health/food` schema is created — the hierarchy is implicit.
+    const orphan = await store.createNote("orphan", { tags: ["health/food"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const res = await query.execute({ id: orphan.id }) as any;
+    // String-form fallback: `health/food` → root `health` → in allowlist.
+    expect(res.error).toBeUndefined();
+    expect(res.id).toBe(orphan.id);
+
+    closeAllStores();
+  });
+
+  test("scoped create-note allows orphan sub-tag via string-form root", 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-orphan-write-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    getVaultStore(vaultName);
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["health"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+
+    const res = await create.execute({ content: "ok", tags: ["health/food"] }) as any;
+    expect(res.error).toBeUndefined();
+    expect(res.id).toBeDefined();
+
+    closeAllStores();
+  });
+
+  // -- Q5: MCP delete-tag dependency check -------------------------------
+
+  test("MCP delete-tag returns tag_in_use_by_tokens when a tag-scoped token references the tag", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+    const { generateToken, createToken } = await import("./token-store.ts");
+
+    const vaultName = `tagscope-dep-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("h", { tags: ["health"] });
+
+    // Mint a tag-scoped token that references "health".
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "health-claw",
+      permission: "read",
+      scopes: ["vault:read"],
+      scoped_tags: ["health"],
+    });
+
+    // Unscoped admin attempts to delete `health` via MCP — should 409.
+    const tools = generateScopedMcpTools(vaultName);
+    const del = tools.find((t) => t.name === "delete-tag")!;
+    const res = await del.execute({ tag: "health" }) as any;
+    expect(res.error).toBe("TagInUseByTokens");
+    expect(res.error_type).toBe("tag_in_use_by_tokens");
+    expect(res.tag).toBe("health");
+    expect(res.referenced_by?.length).toBe(1);
+    expect(res.referenced_by?.[0]?.label).toBe("health-claw");
+
+    // Tag is still attached to its note.
+    expect((await store.listTags()).find((t) => t.name === "health")).toBeTruthy();
+
+    closeAllStores();
+  });
+
+  test("MCP delete-tag proceeds when no token references the tag", 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-nodep-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("h", { tags: ["health"] });
+
+    const tools = generateScopedMcpTools(vaultName);
+    const del = tools.find((t) => t.name === "delete-tag")!;
+    const res = await del.execute({ tag: "health" }) as any;
+    expect(res.error).toBeUndefined();
+
+    closeAllStores();
+  });
+
   test("update-note tags.add auto-populate does not bump updatedAt", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
@@ -1145,6 +1421,152 @@ describe("HTTP /notes", async () => {
       expect(res.status).toBe(405);
     });
   });
+
+  // -------------------------------------------------------------------------
+  // Empty-note guard + batch cap (#213) — runaway-client protection
+  // -------------------------------------------------------------------------
+
+  describe("empty-note guard (#213)", async () => {
+    test("POST bare {} body → 400 EmptyNoteError", async () => {
+      const res = await handleNotes(mkReq("POST", "/notes", {}), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("empty_note");
+      expect(body.error).toBe("EmptyNoteError");
+    });
+
+    test("POST batch with one empty entry → 400 EmptyNoteError, NOTHING created (atomic)", async () => {
+      // Pre-validate the batch before any DB writes so a mixed batch with one
+      // bad entry rolls back the whole call. The runaway-client signature
+      // (#213) is "thousands of empties" — partial-create semantics would
+      // still leak the prefix on every burst. Atomic is the only safe shape.
+      const beforeCount = (await store.queryNotes({ path: "ok-1" })).length;
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { notes: [{ path: "ok-1" }, {}] }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("empty_note");
+      expect(body.item_index).toBe(1);
+      // ok-1 must NOT have been created — atomic rollback.
+      const afterCount = (await store.queryNotes({ path: "ok-1" })).length;
+      expect(afterCount).toBe(beforeCount);
+    });
+
+    test("POST single content-only (path absent) → 201", async () => {
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { content: "un-pathed jot" }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(201);
+    });
+
+    test("POST single path-only (content absent) → 201, no warning log", async () => {
+      // Path-only is a wikilink placeholder / `_schemas/*` shape — must
+      // remain accepted (per #223 design Q3).
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { path: "wiki/placeholder" }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(201);
+    });
+
+    test("PATCH that would clear both content and path → 400 EmptyNoteError", async () => {
+      const note = await store.createNote("starts with content", { id: "ep1" });
+      const updated = await store.getNote("ep1");
+      const res = await handleNotes(
+        mkReq("PATCH", "/notes/ep1", {
+          content: "",
+          path: "",
+          if_updated_at: updated!.updatedAt,
+        }),
+        store,
+        "/ep1",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("empty_note");
+      expect(body.note_id).toBe("ep1");
+    });
+
+    test("PATCH that clears content but preserves path → 200", async () => {
+      const note = await store.createNote("body", { id: "ep2", path: "p2" });
+      const updated = await store.getNote("ep2");
+      const res = await handleNotes(
+        mkReq("PATCH", "/notes/ep2", {
+          content: "",
+          if_updated_at: updated!.updatedAt,
+        }),
+        store,
+        "/ep2",
+      );
+      expect(res.status).toBe(200);
+    });
+  });
+
+  describe("batch atomicity (#236)", async () => {
+    test("POST batch where mid-item triggers PATH_CONFLICT → 409, NOTHING created", async () => {
+      // The empty-note pre-walk catches `{}` before any DB write (#213); a
+      // path-conflict only surfaces on the actual INSERT, mid-loop. Without
+      // the BEGIN/COMMIT wrap the prefix would have already landed by then.
+      await store.createNote("existing", { path: "taken" });
+      const beforeIds = (await store.queryNotes({})).map((n) => n.id).sort();
+
+      const res = await handleNotes(
+        mkReq("POST", "/notes", {
+          notes: [
+            { content: "ok-1", path: "fresh-1" },
+            { content: "ok-2", path: "fresh-2" },
+            { content: "boom", path: "taken" },
+            { content: "ok-3", path: "fresh-3" },
+          ],
+        }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(409);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("path_conflict");
+
+      // The two prefix items must NOT have been created — atomic rollback.
+      const afterIds = (await store.queryNotes({})).map((n) => n.id).sort();
+      expect(afterIds).toEqual(beforeIds);
+      expect(await store.queryNotes({ path: "fresh-1" })).toHaveLength(0);
+      expect(await store.queryNotes({ path: "fresh-2" })).toHaveLength(0);
+    });
+  });
+
+  describe("batch cap (#213)", async () => {
+    test("POST with 501-item batch → 413 BatchTooLarge", async () => {
+      const oversized = Array.from({ length: 501 }, (_, i) => ({ content: `n${i}` }));
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { notes: oversized }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(413);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("batch_too_large");
+      expect(body.error).toBe("BatchTooLarge");
+      expect(body.limit).toBe(500);
+    });
+
+    test("POST with exactly 500-item batch → 201 (boundary)", async () => {
+      const exactly500 = Array.from({ length: 500 }, (_, i) => ({ content: `n${i}` }));
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { notes: exactly500 }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(201);
+      const body = await res.json() as any[];
+      expect(body).toHaveLength(500);
+    });
+  });
 });
 
 describe("HTTP GET /notes?format=graph", async () => {
@@ -1352,6 +1774,98 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect((await store.getNote("x"))!.content).toBe("first");
   });
 
+  test("PATCH append without precondition succeeds (no-conflict-by-design)", async () => {
+    await store.createNote("seed:", { id: "x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { append: " A" }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(200);
+    expect((await store.getNote("x"))!.content).toBe("seed: A");
+  });
+
+  test("PATCH append + tags without precondition is rejected (#201)", async () => {
+    // The append-only exemption is justified by SQL-atomic concat. Tag
+    // mutations don't share that property — they're idempotent, but the
+    // caller should still observe the prior state before re-asserting.
+    await store.createNote("seed:", { id: "x", path: "Inbox/x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { append: " A", tags: { add: ["important"] } }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(428);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("precondition_required");
+    // Unchanged on rejection.
+    expect((await store.getNote("x"))!.content).toBe("seed:");
+  });
+
+  test("PATCH content_edit replaces a single occurrence", async () => {
+    const note = await store.createNote("hello world", { id: "x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", {
+        content_edit: { old_text: "hello", new_text: "hi" },
+        if_updated_at: note.updatedAt,
+      }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(200);
+    expect((await store.getNote("x"))!.content).toBe("hi world");
+  });
+
+  test("PATCH content_edit returns 422 when old_text is not found (#202)", async () => {
+    // 404 misleadingly read as "note doesn't exist"; 422 says "request is
+    // valid, but old_text doesn't apply to the current content."
+    const note = await store.createNote("hello world", { id: "x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", {
+        content_edit: { old_text: "missing", new_text: "x" },
+        if_updated_at: note.updatedAt,
+      }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(422);
+    const body = await res.json() as any;
+    expect(body.error).toBe("unprocessable_content");
+    expect((await store.getNote("x"))!.content).toBe("hello world");
+  });
+
+  test("PATCH content_edit returns 409 on multiple matches", async () => {
+    const note = await store.createNote("hi hi", { id: "x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", {
+        content_edit: { old_text: "hi", new_text: "hello" },
+        if_updated_at: note.updatedAt,
+      }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(409);
+    expect((await store.getNote("x"))!.content).toBe("hi hi");
+  });
+
+  test("PATCH rejects content + append combination with 400", async () => {
+    await store.createNote("seed", { id: "x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { content: "new", append: "more", force: true }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error).toBe("mutually_exclusive");
+  });
+
   test("DELETE resolves note by path", async () => {
     await store.createNote("x", { path: "Temp/note" });
     const res = await handleNotes(
@@ -1363,6 +1877,47 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(body.deleted).toBe(true);
     expect(await store.getNoteByPath("Temp/note")).toBeNull();
   });
+
+  test("POST /notes returns 409 path_conflict when path already exists (#126)", async () => {
+    await store.createNote("first", { path: "Inbox/note" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "second", path: "Inbox/note" }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(409);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("path_conflict");
+    expect(body.error).toBe("path_conflict");
+    expect(body.path).toBe("Inbox/note");
+  });
+
+  test("POST /notes path_conflict — second note never lands in DB (#126)", async () => {
+    await store.createNote("first", { path: "Inbox/note" });
+    const before = (await store.queryNotes({})).length;
+    await handleNotes(
+      mkReq("POST", "/notes", { content: "second", path: "Inbox/note" }),
+      store,
+      "",
+    );
+    expect((await store.queryNotes({})).length).toBe(before);
+  });
+
+  test("PATCH /notes returns 409 path_conflict when renaming onto existing path (#126)", async () => {
+    const a = await store.createNote("first", { id: "a", path: "alpha" });
+    await store.createNote("second", { id: "b", path: "beta" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/a", { path: "beta", if_updated_at: a.createdAt }),
+      store,
+      "/a",
+    );
+    expect(res.status).toBe(409);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("path_conflict");
+    expect(body.path).toBe("beta");
+    // Source note unchanged
+    expect((await store.getNote("a"))!.path).toBe("alpha");
+  });
 });
 
 describe("HTTP /tags", async () => {
@@ -1397,6 +1952,21 @@ describe("HTTP /tags", async () => {
     expect(body.description).toBe("A person");
   });
 
+  test("PUT /tags/:name returns 400 with error_type: invalid_relationships on bad shape", async () => {
+    const res = await handleTags(
+      mkReq("PUT", "/tags/person", {
+        relationships: { mentions: { target_tag: "topic", cardinality: "infinite" } },
+      }),
+      store,
+      "/person",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("invalid_relationships");
+    expect(typeof body.error).toBe("string");
+    expect(body.error.length).toBeGreaterThan(0);
+  });
+
   test("DELETE /tags/:name removes tag and schema", async () => {
     await store.createNote("A", { tags: ["doomed"] });
     await store.upsertTagSchema("doomed", { description: "will be deleted" });
@@ -1516,6 +2086,294 @@ describe("HTTP /tags", async () => {
   });
 });
 
+describe("HTTP /note-schemas", async () => {
+  test("PUT /note-schemas/:name creates a schema", async () => {
+    const res = await handleNoteSchemas(
+      mkReq("PUT", "/note-schemas/task", {
+        description: "A task",
+        fields: { priority: { type: "string", enum: ["high", "low"] } },
+        required: ["priority"],
+      }),
+      store,
+      "/task",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.name).toBe("task");
+    expect(body.description).toBe("A task");
+    expect(body.required).toEqual(["priority"]);
+  });
+
+  test("GET /note-schemas lists all schemas", async () => {
+    await store.upsertNoteSchema("task", { description: "t" });
+    await store.upsertNoteSchema("project", { description: "p" });
+    const res = await handleNoteSchemas(mkReq("GET", "/note-schemas"), store);
+    const body = await res.json() as any[];
+    const names = body.map((s) => s.name).sort();
+    expect(names).toEqual(["project", "task"]);
+  });
+
+  test("GET /note-schemas?include_mappings=true inlines mappings per schema", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    const res = await handleNoteSchemas(
+      mkReq("GET", "/note-schemas?include_mappings=true"),
+      store,
+    );
+    const body = await res.json() as any[];
+    const task = body.find((s) => s.name === "task");
+    expect(task.mappings).toEqual([{ schema_name: "task", match_kind: "tag", match_value: "task" }]);
+  });
+
+  test("GET /note-schemas/:name returns the schema and its mappings", async () => {
+    await store.upsertNoteSchema("task", { description: "A task" });
+    await store.setSchemaMapping("task", "tag", "task");
+    const res = await handleNoteSchemas(mkReq("GET", "/note-schemas/task"), store, "/task");
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.name).toBe("task");
+    expect(body.mappings.length).toBe(1);
+  });
+
+  test("GET /note-schemas/:name returns 404 when missing", async () => {
+    const res = await handleNoteSchemas(mkReq("GET", "/note-schemas/missing"), store, "/missing");
+    expect(res.status).toBe(404);
+  });
+
+  test("PUT /note-schemas/:name with required: [] clears required", async () => {
+    await store.upsertNoteSchema("task", { required: ["a"] });
+    const res = await handleNoteSchemas(
+      mkReq("PUT", "/note-schemas/task", { required: [] }),
+      store,
+      "/task",
+    );
+    const body = await res.json() as any;
+    expect(body.required).toBeNull();
+  });
+
+  test("PUT /note-schemas/:name returns 400 when required isn't an array", async () => {
+    const res = await handleNoteSchemas(
+      mkReq("PUT", "/note-schemas/task", { required: "priority" }),
+      store,
+      "/task",
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("DELETE /note-schemas/:name removes schema (and cascades mappings)", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    const res = await handleNoteSchemas(mkReq("DELETE", "/note-schemas/task"), store, "/task");
+    expect(res.status).toBe(200);
+    expect(await store.getNoteSchema("task")).toBeNull();
+    expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
+  });
+
+  test("POST /note-schemas/:name/mappings adds a mapping", async () => {
+    await store.upsertNoteSchema("task", {});
+    const res = await handleNoteSchemas(
+      mkReq("POST", "/note-schemas/task/mappings", { match_kind: "tag", match_value: "task" }),
+      store,
+      "/task/mappings",
+    );
+    expect(res.status).toBe(201);
+    expect((await store.listSchemaMappings({ schema_name: "task" })).length).toBe(1);
+  });
+
+  test("POST /note-schemas/:name/mappings returns 400 on bad match_kind", async () => {
+    await store.upsertNoteSchema("task", {});
+    const res = await handleNoteSchemas(
+      mkReq("POST", "/note-schemas/task/mappings", { match_kind: "BOGUS", match_value: "x" }),
+      store,
+      "/task/mappings",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("invalid_match_kind");
+  });
+
+  test("POST /note-schemas/:name/mappings returns 404 when schema doesn't exist", async () => {
+    const res = await handleNoteSchemas(
+      mkReq("POST", "/note-schemas/missing/mappings", { match_kind: "tag", match_value: "x" }),
+      store,
+      "/missing/mappings",
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("GET /note-schemas/:name/mappings lists mappings for a schema", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    await store.setSchemaMapping("task", "path_prefix", "Tasks/");
+    const res = await handleNoteSchemas(
+      mkReq("GET", "/note-schemas/task/mappings"),
+      store,
+      "/task/mappings",
+    );
+    const body = await res.json() as any[];
+    expect(body.length).toBe(2);
+  });
+
+  test("DELETE /note-schemas/:name/mappings?match_kind=...&match_value=... removes one", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    await store.setSchemaMapping("task", "path_prefix", "Tasks/");
+    const res = await handleNoteSchemas(
+      mkReq("DELETE", "/note-schemas/task/mappings?match_kind=tag&match_value=task"),
+      store,
+      "/task/mappings",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.deleted).toBe(true);
+    const remaining = await store.listSchemaMappings({ schema_name: "task" });
+    expect(remaining).toEqual([{ schema_name: "task", match_kind: "path_prefix", match_value: "Tasks/" }]);
+  });
+
+  test("DELETE /note-schemas/:name/mappings handles slash-containing path prefixes via query string", async () => {
+    await store.upsertNoteSchema("journal", {});
+    await store.setSchemaMapping("journal", "path_prefix", "journal/2026/");
+    const res = await handleNoteSchemas(
+      mkReq(
+        "DELETE",
+        `/note-schemas/journal/mappings?match_kind=path_prefix&match_value=${encodeURIComponent("journal/2026/")}`,
+      ),
+      store,
+      "/journal/mappings",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.deleted).toBe(true);
+  });
+
+  // Tag-scoped tokens enumerate `schema_mappings` through the same handler.
+  // Without these gates, a token allowlisted for `health` can both see and
+  // create `tag` mappings for tags outside its scope (e.g. `finance`). The
+  // path_prefix kind carries no tag-axis info and stays visible/writable.
+  describe("tag-scope", async () => {
+    const healthScope = { allowed: new Set(["health"]), raw: ["health"] };
+
+    test("GET /note-schemas?include_mappings filters out-of-scope tag mappings", async () => {
+      await store.upsertNoteSchema("task", {});
+      await store.setSchemaMapping("task", "tag", "health");
+      await store.setSchemaMapping("task", "tag", "finance");
+      await store.setSchemaMapping("task", "path_prefix", "Tasks/");
+      const res = await handleNoteSchemas(
+        mkReq("GET", "/note-schemas?include_mappings=true"),
+        store,
+        "",
+        healthScope,
+      );
+      const body = await res.json() as any[];
+      const task = body.find((s) => s.name === "task");
+      const kinds = task.mappings.map((m: any) => `${m.match_kind}:${m.match_value}`).sort();
+      expect(kinds).toEqual(["path_prefix:Tasks/", "tag:health"]);
+    });
+
+    test("GET /note-schemas/:name filters out-of-scope tag mappings", async () => {
+      await store.upsertNoteSchema("task", {});
+      await store.setSchemaMapping("task", "tag", "health");
+      await store.setSchemaMapping("task", "tag", "finance");
+      const res = await handleNoteSchemas(
+        mkReq("GET", "/note-schemas/task"),
+        store,
+        "/task",
+        healthScope,
+      );
+      const body = await res.json() as any;
+      expect(body.mappings.map((m: any) => m.match_value)).toEqual(["health"]);
+    });
+
+    test("GET /note-schemas/:name/mappings filters out-of-scope tag mappings", async () => {
+      await store.upsertNoteSchema("task", {});
+      await store.setSchemaMapping("task", "tag", "health");
+      await store.setSchemaMapping("task", "tag", "finance");
+      const res = await handleNoteSchemas(
+        mkReq("GET", "/note-schemas/task/mappings"),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      const body = await res.json() as any[];
+      expect(body.map((m) => m.match_value)).toEqual(["health"]);
+    });
+
+    test("POST /:name/mappings rejects out-of-scope tag with 403", async () => {
+      await store.upsertNoteSchema("task", {});
+      const res = await handleNoteSchemas(
+        mkReq("POST", "/note-schemas/task/mappings", { match_kind: "tag", match_value: "finance" }),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      expect(res.status).toBe(403);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("tag_scope_violation");
+      expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
+    });
+
+    test("POST /:name/mappings accepts in-scope tag and string-form fallback descendant", async () => {
+      await store.upsertNoteSchema("task", {});
+      const inScope = await handleNoteSchemas(
+        mkReq("POST", "/note-schemas/task/mappings", { match_kind: "tag", match_value: "health" }),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      expect(inScope.status).toBe(201);
+      // String-form fallback: `health/food` has root `health`, which is in
+      // the raw allowlist, so it's permitted even when no `_tags/health/food`
+      // schema declares the descendant relationship.
+      const descendant = await handleNoteSchemas(
+        mkReq("POST", "/note-schemas/task/mappings", { match_kind: "tag", match_value: "health/food" }),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      expect(descendant.status).toBe(201);
+    });
+
+    test("POST /:name/mappings allows path_prefix regardless of tag-scope", async () => {
+      await store.upsertNoteSchema("task", {});
+      const res = await handleNoteSchemas(
+        mkReq("POST", "/note-schemas/task/mappings", { match_kind: "path_prefix", match_value: "Tasks/" }),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      expect(res.status).toBe(201);
+    });
+
+    test("DELETE /:name/mappings rejects out-of-scope tag with 403", async () => {
+      await store.upsertNoteSchema("task", {});
+      await store.setSchemaMapping("task", "tag", "finance");
+      const res = await handleNoteSchemas(
+        mkReq("DELETE", "/note-schemas/task/mappings?match_kind=tag&match_value=finance"),
+        store,
+        "/task/mappings",
+        healthScope,
+      );
+      expect(res.status).toBe(403);
+      // Mapping still present — write was denied.
+      expect((await store.listSchemaMappings({ schema_name: "task" })).length).toBe(1);
+    });
+
+    test("unscoped tokens see and write everything (regression of fast-path)", async () => {
+      await store.upsertNoteSchema("task", {});
+      await store.setSchemaMapping("task", "tag", "finance");
+      await store.setSchemaMapping("task", "tag", "health");
+      const res = await handleNoteSchemas(
+        mkReq("GET", "/note-schemas/task/mappings"),
+        store,
+        "/task/mappings",
+        // default tagScope (unscoped) — omitted parameter
+      );
+      const body = await res.json() as any[];
+      expect(body.length).toBe(2);
+    });
+  });
+});
+
 describe("HTTP /find-path", async () => {
   test("finds path between two notes", async () => {
     await store.createNote("a", { id: "a" });
@@ -1578,6 +2436,7 @@ describe("stateless MCP transport", async () => {
       permission: "full",
       scopes: ["vault:read", "vault:write", "vault:admin"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200);
 
@@ -1619,6 +2478,7 @@ describe("stateless MCP transport", async () => {
       permission: "full",
       scopes: ["vault:read", "vault:write", "vault:admin"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200);
 
@@ -1662,6 +2522,7 @@ describe("stateless MCP transport", async () => {
       permission: "read",
       scopes: ["vault:read"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200);
 
@@ -1716,6 +2577,7 @@ describe("stateless MCP transport", async () => {
       permission: "read",
       scopes: ["vault:read"],
       legacyDerived: false,
+      scoped_tags: null,
     });
 
     expect(res.status).toBe(200);
@@ -1767,6 +2629,7 @@ describe("stateless MCP transport", async () => {
       permission: "full",
       scopes: ["vault:read", "vault:write"],
       legacyDerived: false,
+      scoped_tags: null,
     });
 
     expect(res.status).toBe(200);
@@ -1807,6 +2670,7 @@ describe("stateless MCP transport", async () => {
       permission: "read",
       scopes: ["vault:read"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200); // JSON-RPC envelope is 200 even for tool errors
     const body = await res.json() as any;
@@ -1850,6 +2714,7 @@ describe("stateless MCP transport", async () => {
       permission: "full",
       scopes: ["vault:read", "vault:write", "vault:admin"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200);