@openparachute/vault 0.2.3 → 0.3.0-rc.1

package/src/vault.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
-import { mkdirSync, rmSync, existsSync } from "fs";
+import { mkdirSync, rmSync, existsSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import { BunStore } from "./vault-store.ts";
@@ -60,25 +60,31 @@ describe("BunStore", async () => {
 
   test("user updates bump updatedAt", async () => {
     const note = await store.createNote("Original");
-    expect(note.updatedAt).toBeUndefined();
+    expect(note.updatedAt).toBe(note.createdAt);
     const updated = await store.updateNote(note.id, { content: "Edited by user" });
     expect(updated.updatedAt).toBeTruthy();
+    // Must be monotonically non-decreasing — and strictly greater when the
+    // caller passed if_updated_at (tested elsewhere). Same-millisecond
+    // collisions are possible here since no if_updated_at is supplied.
+    expect(updated.updatedAt! >= note.createdAt).toBe(true);
   });
 
   test("skipUpdatedAt preserves updatedAt (hook-style writes)", async () => {
     // Hook writes (e.g., the reader-audio hook's metadata markers) must not
     // count as user activity. See issue #44 — hook writes were bumping
-    // updatedAt and wrecking Daily's reader sort.
+    // updatedAt and wrecking Daily's reader sort. Fresh notes have
+    // `updatedAt === createdAt`; a hook write must leave it at that value so
+    // `updatedAt > createdAt` remains the correct "user-touched" signal.
     const note = await store.createNote("Content");
-    expect(note.updatedAt).toBeUndefined();
+    expect(note.updatedAt).toBe(note.createdAt);
 
-    // Fresh note: a machine write must not set updatedAt.
+    // Fresh note: a machine write must not advance updatedAt past createdAt.
     await store.updateNote(note.id, {
       metadata: { audio_pending_at: "2026-04-09T10:00:00.000Z" },
       skipUpdatedAt: true,
     });
     let fetched = (await store.getNote(note.id))!;
-    expect(fetched.updatedAt).toBeUndefined();
+    expect(fetched.updatedAt).toBe(note.createdAt);
     expect((fetched.metadata as { audio_pending_at?: string } | undefined)?.audio_pending_at).toBe(
       "2026-04-09T10:00:00.000Z",
     );
@@ -522,30 +528,29 @@ describe("MCP tools", async () => {
   });
 });
 
-describe("unified MCP wrapper", async () => {
-  test("vault-info routes through vault param", async () => {
-    const { generateUnifiedMcpTools } = await import("./mcp-tools.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+describe("scoped MCP wrapper", async () => {
+  test("vault-info returns the vault's stats", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
-    const vaultName = `unified-stats-${Date.now()}`;
+    const vaultName = `scoped-stats-${Date.now()}`;
     writeVaultConfig({
       name: vaultName,
       api_keys: [],
       created_at: new Date().toISOString(),
       description: "Test vault",
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.createNote("alpha", { tags: ["x", "y"] });
     await vaultStore.createNote("beta", { tags: ["x"] });
 
-    const tools = generateUnifiedMcpTools();
+    const tools = generateScopedMcpTools(vaultName);
     const vaultInfo = tools.find((t) => t.name === "vault-info");
     expect(vaultInfo).toBeTruthy();
 
-    const result = await vaultInfo!.execute({ vault: vaultName, include_stats: true }) as any;
+    const result = await vaultInfo!.execute({ include_stats: true }) as any;
     expect(result.name).toBe(vaultName);
     expect(result.description).toBe("Test vault");
     expect(result.stats.totalNotes).toBe(2);
@@ -554,9 +559,9 @@ describe("unified MCP wrapper", async () => {
     closeAllStores();
   });
 
-  test("list-tags with schema works through unified wrapper", async () => {
-    const { generateUnifiedMcpTools } = await import("./mcp-tools.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+  test("list-tags with schema returns per-tag detail", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
     const vaultName = `tag-schema-${Date.now()}`;
@@ -565,7 +570,6 @@ describe("unified MCP wrapper", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.createNote("A", { tags: ["person"] });
@@ -574,11 +578,11 @@ describe("unified MCP wrapper", async () => {
       fields: { name: { type: "string", description: "Full name" } },
     });
 
-    const tools = generateUnifiedMcpTools();
+    const tools = generateScopedMcpTools(vaultName);
 
     // list-tags with tag param for single tag detail
     const listTags = tools.find((t) => t.name === "list-tags")!;
-    const detail = await listTags.execute({ vault: vaultName, tag: "person" }) as any;
+    const detail = await listTags.execute({ tag: "person" }) as any;
     expect(detail.name).toBe("person");
     expect(detail.count).toBe(1);
     expect(detail.description).toBe("A person");
@@ -588,8 +592,8 @@ describe("unified MCP wrapper", async () => {
   });
 
   test("create-note with schema tag auto-populates defaults", async () => {
-    const { generateUnifiedMcpTools } = await import("./mcp-tools.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
     const vaultName = `schema-create-${Date.now()}`;
@@ -598,7 +602,6 @@ describe("unified MCP wrapper", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.upsertTagSchema("person", {
@@ -609,31 +612,29 @@ describe("unified MCP wrapper", async () => {
       },
     });
 
-    const tools = generateUnifiedMcpTools();
+    const tools = generateScopedMcpTools(vaultName);
     const createNote = tools.find((t) => t.name === "create-note")!;
     const queryNotes = tools.find((t) => t.name === "query-notes")!;
 
     // Create a note tagged person with no metadata — defaults auto-populated
     const result = await createNote.execute({
-      vault: vaultName,
       content: "Alice",
       tags: ["person"],
     }) as any;
     expect(result.content).toBe("Alice");
 
     // Verify defaults were written
-    const fresh = await queryNotes.execute({ vault: vaultName, id: result.id }) as any;
+    const fresh = await queryNotes.execute({ id: result.id }) as any;
     expect(fresh.metadata.first_appeared).toBe("");
     expect(fresh.metadata.relationship).toBe("");
 
     // Create with explicit metadata — preserved
     const result2 = await createNote.execute({
-      vault: vaultName,
       content: "Bob",
       tags: ["person"],
       metadata: { first_appeared: "2024-01", relationship: "friend" },
     }) as any;
-    const fresh2 = await queryNotes.execute({ vault: vaultName, id: result2.id }) as any;
+    const fresh2 = await queryNotes.execute({ id: result2.id }) as any;
     expect(fresh2.metadata.first_appeared).toBe("2024-01");
     expect(fresh2.metadata.relationship).toBe("friend");
 
@@ -641,8 +642,8 @@ describe("unified MCP wrapper", async () => {
   });
 
   test("update-note tags.add with schema auto-populates defaults", async () => {
-    const { generateUnifiedMcpTools } = await import("./mcp-tools.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores: close } = await import("./vault-store.ts");
 
     const vaultName = `schema-defaults-${Date.now()}`;
@@ -651,7 +652,6 @@ describe("unified MCP wrapper", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.upsertTagSchema("person", {
@@ -669,41 +669,40 @@ describe("unified MCP wrapper", async () => {
         priority: { type: "integer", description: "Priority level" },
       },
     });
-    const tools = generateUnifiedMcpTools();
+    const tools = generateScopedMcpTools(vaultName);
     const createNote = tools.find((t) => t.name === "create-note")!;
     const updateNote = tools.find((t) => t.name === "update-note")!;
     const queryNotes = tools.find((t) => t.name === "query-notes")!;
 
     // Create a note, then add #person tag via update-note
-    const note = await createNote.execute({ vault: vaultName, content: "Alice" }) as any;
-    await updateNote.execute({ vault: vaultName, id: note.id, tags: { add: ["person"] } });
-    const after = await queryNotes.execute({ vault: vaultName, id: note.id }) as any;
+    const note = await createNote.execute({ content: "Alice" }) as any;
+    await updateNote.execute({ id: note.id, tags: { add: ["person"] }, force: true });
+    const after = await queryNotes.execute({ id: note.id }) as any;
     expect(after.metadata.first_appeared).toBe("");
     expect(after.metadata.relationship).toBe("");
 
     // Tag note that already has partial metadata — only missing fields populated
     const note2 = await createNote.execute({
-      vault: vaultName,
       content: "Bob",
       metadata: { first_appeared: "2023-11" },
     }) as any;
-    await updateNote.execute({ vault: vaultName, id: note2.id, tags: { add: ["person"] } });
-    const after2 = await queryNotes.execute({ vault: vaultName, id: note2.id }) as any;
+    await updateNote.execute({ id: note2.id, tags: { add: ["person"] }, force: true });
+    const after2 = await queryNotes.execute({ id: note2.id }) as any;
     expect(after2.metadata.first_appeared).toBe("2023-11"); // preserved
     expect(after2.metadata.relationship).toBe(""); // added
 
     // Tag with #project — enum defaults to first value, boolean to false, integer to 0
-    const note4 = await createNote.execute({ vault: vaultName, content: "My Project" }) as any;
-    await updateNote.execute({ vault: vaultName, id: note4.id, tags: { add: ["project"] } });
-    const after4 = await queryNotes.execute({ vault: vaultName, id: note4.id }) as any;
+    const note4 = await createNote.execute({ content: "My Project" }) as any;
+    await updateNote.execute({ id: note4.id, tags: { add: ["project"] }, force: true });
+    const after4 = await queryNotes.execute({ id: note4.id }) as any;
     expect(after4.metadata.status).toBe("active");
     expect(after4.metadata.active).toBe(false);
     expect(after4.metadata.priority).toBe(0);
 
     // Multiple schema tags at once — all defaults merged
-    const note5 = await createNote.execute({ vault: vaultName, content: "Multi" }) as any;
-    await updateNote.execute({ vault: vaultName, id: note5.id, tags: { add: ["person", "project"] } });
-    const after5 = await queryNotes.execute({ vault: vaultName, id: note5.id }) as any;
+    const note5 = await createNote.execute({ content: "Multi" }) as any;
+    await updateNote.execute({ id: note5.id, tags: { add: ["person", "project"] }, force: true });
+    const after5 = await queryNotes.execute({ id: note5.id }) as any;
     expect(after5.metadata.first_appeared).toBe("");
     expect(after5.metadata.relationship).toBe("");
     expect(after5.metadata.status).toBe("active");
@@ -713,8 +712,8 @@ describe("unified MCP wrapper", async () => {
   });
 
   test("update-note tags.add auto-populate does not bump updatedAt", async () => {
-    const { generateUnifiedMcpTools } = await import("./mcp-tools.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores: close } = await import("./vault-store.ts");
 
     const vaultName = `schema-noupdate-${Date.now()}`;
@@ -723,7 +722,6 @@ describe("unified MCP wrapper", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.upsertTagSchema("person", {
@@ -731,15 +729,15 @@ describe("unified MCP wrapper", async () => {
       fields: { name: { type: "string" } },
     });
 
-    const tools = generateUnifiedMcpTools();
+    const tools = generateScopedMcpTools(vaultName);
     const createNote = tools.find((t) => t.name === "create-note")!;
     const updateNote = tools.find((t) => t.name === "update-note")!;
     const queryNotes = tools.find((t) => t.name === "query-notes")!;
 
-    const note = await createNote.execute({ vault: vaultName, content: "Test" }) as any;
+    const note = await createNote.execute({ content: "Test" }) as any;
     const originalUpdatedAt = note.updatedAt;
-    await updateNote.execute({ vault: vaultName, id: note.id, tags: { add: ["person"] } });
-    const after = await queryNotes.execute({ vault: vaultName, id: note.id }) as any;
+    await updateNote.execute({ id: note.id, tags: { add: ["person"] }, force: true });
+    const after = await queryNotes.execute({ id: note.id }) as any;
     expect(after.updatedAt).toBe(originalUpdatedAt);
     expect(after.metadata.name).toBe("");
 
@@ -754,7 +752,6 @@ describe("auth permissions", () => {
     expect(isToolAllowed("list-tags", "read")).toBe(true);
     expect(isToolAllowed("find-path", "read")).toBe(true);
     expect(isToolAllowed("vault-info", "read")).toBe(true);
-    expect(isToolAllowed("list-vaults", "read")).toBe(true);
   });
 
   test("read permission blocks mutation tools", () => {
@@ -834,6 +831,24 @@ describe("HTTP /notes", async () => {
     expect(body).toHaveLength(1);
   });
 
+  test("GET /notes?has_tags=false returns only untagged notes", async () => {
+    await store.createNote("tagged", { tags: ["x"], path: "t" });
+    await store.createNote("plain", { path: "p" });
+    const res = await handleNotes(mkReq("GET", "/notes?has_tags=false&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.content)).toEqual(["plain"]);
+  });
+
+  test("GET /notes?has_links=false returns only orphaned notes", async () => {
+    const a = await store.createNote("src", { id: "qa" });
+    const b = await store.createNote("tgt", { id: "qb" });
+    await store.createNote("orphan", { id: "qo" });
+    await store.createLink(a.id, b.id, "mentions");
+    const res = await handleNotes(mkReq("GET", "/notes?has_links=false&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.content)).toEqual(["orphan"]);
+  });
+
   test("GET /notes?search=fox&include_metadata=false strips metadata from search results", async () => {
     await store.createNote("The quick brown fox", { metadata: { summary: "animal" } });
     const res = await handleNotes(mkReq("GET", "/notes?search=fox&include_metadata=false"), store, "");
@@ -962,6 +977,174 @@ describe("HTTP /notes", async () => {
     const body = await res.json() as any;
     expect(body.mimeType).toBe("image/png");
   });
+
+  describe("POST /notes/:id/attachments with transcribe flag", async () => {
+    test("transcribe: true seeds pending status and marks note as stub", async () => {
+      await store.createNote("# 🎙️ Voice memo\n\n_Transcript pending._", { id: "v1" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/v1/attachments", {
+          path: "memos/memo-1.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+        }),
+        store,
+        "/v1/attachments",
+      );
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      expect(att.metadata?.transcribe_status).toBe("pending");
+      expect(att.metadata?.transcribe_requested_at).toBeTruthy();
+
+      const note = await store.getNote("v1");
+      expect((note!.metadata as any)?.transcribe_stub).toBe(true);
+    });
+
+    test("transcribe: false (default) leaves metadata empty and note untouched", async () => {
+      await store.createNote("note body", { id: "v2" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/v2/attachments", {
+          path: "memos/memo-2.webm",
+          mimeType: "audio/webm",
+        }),
+        store,
+        "/v2/attachments",
+      );
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      expect(att.metadata?.transcribe_status).toBeUndefined();
+
+      const note = await store.getNote("v2");
+      expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
+    });
+
+    test("transcribe: true preserves other note metadata", async () => {
+      await store.createNote("body", { id: "v3", metadata: { summary: "keep me" } });
+      await handleNotes(
+        mkReq("POST", "/notes/v3/attachments", {
+          path: "memos/memo-3.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+        }),
+        store,
+        "/v3/attachments",
+      );
+      const note = await store.getNote("v3");
+      const meta = note!.metadata as any;
+      expect(meta?.summary).toBe("keep me");
+      expect(meta?.transcribe_stub).toBe(true);
+    });
+  });
+
+  describe("DELETE /notes/:id/attachments/:attId", async () => {
+    test("happy path: 204, DB row gone, storage file unlinked", async () => {
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, "2026-04-18"), { recursive: true });
+      const relPath = "2026-04-18/shot.png";
+      const filePath = join(assetsRoot, relPath);
+      writeFileSync(filePath, Buffer.from([1, 2, 3]));
+      process.env.ASSETS_DIR = assetsRoot;
+
+      const n = await store.createNote("x", { id: "n1" });
+      const att = await store.addAttachment(n.id, relPath, "image/png");
+
+      const res = await handleNotes(
+        mkReq("DELETE", `/notes/n1/attachments/${att.id}`),
+        store,
+        `/n1/attachments/${att.id}`,
+        "default",
+      );
+      expect(res.status).toBe(204);
+      expect((await store.getAttachments(n.id)).length).toBe(0);
+      expect(existsSync(filePath)).toBe(false);
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("404 when attachment does not exist", async () => {
+      await store.createNote("x", { id: "n2" });
+      const res = await handleNotes(
+        mkReq("DELETE", "/notes/n2/attachments/nonexistent"),
+        store,
+        "/n2/attachments/nonexistent",
+        "default",
+      );
+      expect(res.status).toBe(404);
+    });
+
+    test("second delete is idempotent (404)", async () => {
+      const n = await store.createNote("x", { id: "n3" });
+      const att = await store.addAttachment(n.id, "files/a.png", "image/png");
+      const first = await handleNotes(
+        mkReq("DELETE", `/notes/n3/attachments/${att.id}`),
+        store,
+        `/n3/attachments/${att.id}`,
+      );
+      expect(first.status).toBe(204);
+      const second = await handleNotes(
+        mkReq("DELETE", `/notes/n3/attachments/${att.id}`),
+        store,
+        `/n3/attachments/${att.id}`,
+      );
+      expect(second.status).toBe(404);
+    });
+
+    test("cross-note delete attempt returns 404 and leaves record intact", async () => {
+      const a = await store.createNote("a", { id: "na" });
+      const b = await store.createNote("b", { id: "nb" });
+      const attA = await store.addAttachment(a.id, "files/a.png", "image/png");
+
+      const res = await handleNotes(
+        mkReq("DELETE", `/notes/nb/attachments/${attA.id}`),
+        store,
+        `/nb/attachments/${attA.id}`,
+      );
+      expect(res.status).toBe(404);
+      expect((await store.getAttachments(a.id)).length).toBe(1);
+    });
+
+    test("file survives first delete when a sibling attachment still references it", async () => {
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, "shared"), { recursive: true });
+      const relPath = "shared/pic.png";
+      const filePath = join(assetsRoot, relPath);
+      writeFileSync(filePath, Buffer.from([9]));
+      process.env.ASSETS_DIR = assetsRoot;
+
+      const a = await store.createNote("a", { id: "sa" });
+      const b = await store.createNote("b", { id: "sb" });
+      const attA = await store.addAttachment(a.id, relPath, "image/png");
+      const attB = await store.addAttachment(b.id, relPath, "image/png");
+
+      await handleNotes(
+        mkReq("DELETE", `/notes/sa/attachments/${attA.id}`),
+        store,
+        `/sa/attachments/${attA.id}`,
+        "default",
+      );
+      expect(existsSync(filePath)).toBe(true);
+
+      await handleNotes(
+        mkReq("DELETE", `/notes/sb/attachments/${attB.id}`),
+        store,
+        `/sb/attachments/${attB.id}`,
+        "default",
+      );
+      expect(existsSync(filePath)).toBe(false);
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("method not allowed on /attachments/:attId returns 405", async () => {
+      const n = await store.createNote("x", { id: "nm" });
+      const att = await store.addAttachment(n.id, "files/a.png", "image/png");
+      const res = await handleNotes(
+        mkReq("PATCH", `/notes/nm/attachments/${att.id}`),
+        store,
+        `/nm/attachments/${att.id}`,
+      );
+      expect(res.status).toBe(405);
+    });
+  });
 });
 
 describe("HTTP GET /notes?format=graph", async () => {
@@ -1048,7 +1231,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
   test("PATCH updates content and merges metadata", async () => {
     const note = await store.createNote("original", { id: "x", metadata: { a: 1 } });
     const res = await handleNotes(
-      mkReq("PATCH", "/notes/x", { content: "updated", metadata: { b: 2 } }),
+      mkReq("PATCH", "/notes/x", { content: "updated", metadata: { b: 2 }, force: true }),
       store,
       "/x",
     );
@@ -1060,7 +1243,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
   test("PATCH adds/removes tags", async () => {
     await store.createNote("x", { id: "x", tags: ["old"] });
     const res = await handleNotes(
-      mkReq("PATCH", "/notes/x", { tags: { add: ["new"], remove: ["old"] } }),
+      mkReq("PATCH", "/notes/x", { tags: { add: ["new"], remove: ["old"] }, force: true }),
       store,
       "/x",
     );
@@ -1073,7 +1256,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     await store.createNote("a", { id: "a" });
     await store.createNote("b", { id: "b" });
     const res = await handleNotes(
-      mkReq("PATCH", "/notes/a", { links: { add: [{ target: "b", relationship: "mentions" }] } }),
+      mkReq("PATCH", "/notes/a", { links: { add: [{ target: "b", relationship: "mentions" }] }, force: true }),
       store,
       "/a",
     );
@@ -1083,7 +1266,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
 
     // Remove
     await handleNotes(
-      mkReq("PATCH", "/notes/a", { links: { remove: [{ target: "b", relationship: "mentions" }] } }),
+      mkReq("PATCH", "/notes/a", { links: { remove: [{ target: "b", relationship: "mentions" }] }, force: true }),
       store,
       "/a",
     );
@@ -1093,7 +1276,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
   test("PATCH resolves note by path", async () => {
     await store.createNote("x", { path: "Projects/README" });
     const res = await handleNotes(
-      mkReq("PATCH", `/notes/${encodeURIComponent("Projects/README")}`, { content: "updated" }),
+      mkReq("PATCH", `/notes/${encodeURIComponent("Projects/README")}`, { content: "updated", force: true }),
       store,
       `/${encodeURIComponent("Projects/README")}`,
     );
@@ -1105,7 +1288,7 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     const note = await store.createNote("first", { id: "x" });
     // First bump — sets updated_at
     const first = await handleNotes(
-      mkReq("PATCH", "/notes/x", { content: "second" }),
+      mkReq("PATCH", "/notes/x", { content: "second", force: true }),
       store,
       "/x",
     );
@@ -1123,8 +1306,8 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
   });
 
   test("PATCH with stale if_updated_at returns 409 and does not modify note", async () => {
-    await store.createNote("first", { id: "x" });
-    await handleNotes(mkReq("PATCH", "/notes/x", { content: "second" }), store, "/x");
+    await store.createNote("first", { id: "x", path: "Inbox/x" });
+    await handleNotes(mkReq("PATCH", "/notes/x", { content: "second", force: true }), store, "/x");
     const current = await store.getNote("x");
 
     const res = await handleNotes(
@@ -1137,6 +1320,11 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     );
     expect(res.status).toBe(409);
     const body = await res.json() as any;
+    // New structured shape
+    expect(body.error_type).toBe("conflict");
+    expect(body.path).toBe("Inbox/x");
+    expect(body.your_updated_at).toBe("2020-01-01T00:00:00.000Z");
+    // Legacy fields retained for compat
     expect(body.error).toBe("conflict");
     expect(body.note_id).toBe("x");
     expect(body.current_updated_at).toBe(current!.updatedAt);
@@ -1146,6 +1334,24 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect((await store.getNote("x"))!.content).toBe("second");
   });
 
+  test("PATCH without if_updated_at or force returns 428 and does not modify note", async () => {
+    await store.createNote("first", { id: "x", path: "Inbox/x" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { content: "second" }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(428);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("precondition_required");
+    expect(body.note_id).toBe("x");
+    expect(body.path).toBe("Inbox/x");
+
+    // Unchanged
+    expect((await store.getNote("x"))!.content).toBe("first");
+  });
+
   test("DELETE resolves note by path", async () => {
     await store.createNote("x", { path: "Temp/note" });
     const res = await handleNotes(
@@ -1199,6 +1405,115 @@ describe("HTTP /tags", async () => {
     expect(body.deleted).toBe(true);
     expect((await store.listTags()).some((t) => t.name === "doomed")).toBe(false);
   });
+
+  test("POST /tags/:name/rename retags every note in one shot", async () => {
+    const n1 = await store.createNote("A", { tags: ["voice"] });
+    const n2 = await store.createNote("B", { tags: ["voice", "keeper"] });
+    const res = await handleTags(
+      mkReq("POST", "/tags/voice/rename", { new_name: "memo" }),
+      store,
+      "/voice/rename",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body).toEqual({ renamed: 2 });
+    expect((await store.getNote(n1.id))!.tags).toEqual(["memo"]);
+    expect((await store.getNote(n2.id))!.tags?.sort()).toEqual(["keeper", "memo"]);
+  });
+
+  test("POST /tags/:name/rename returns 409 target_exists when new_name is taken", async () => {
+    await store.createNote("A", { tags: ["old"] });
+    await store.createNote("B", { tags: ["new"] });
+    const res = await handleTags(
+      mkReq("POST", "/tags/old/rename", { new_name: "new" }),
+      store,
+      "/old/rename",
+    );
+    expect(res.status).toBe(409);
+    const body = await res.json() as any;
+    expect(body.error).toBe("target_exists");
+    expect(body.target).toBe("new");
+    // Hint at the remediation so clients don't reinvent merge client-side.
+    expect(body.message).toMatch(/merge/i);
+  });
+
+  test("POST /tags/:name/rename returns 404 when source tag does not exist", async () => {
+    const res = await handleTags(
+      mkReq("POST", "/tags/ghost/rename", { new_name: "phantom" }),
+      store,
+      "/ghost/rename",
+    );
+    expect(res.status).toBe(404);
+    const body = await res.json() as any;
+    expect(body.error).toBe("not_found");
+  });
+
+  test("POST /tags/:name/rename rejects empty/missing new_name with 400", async () => {
+    const res = await handleTags(
+      mkReq("POST", "/tags/anything/rename", { new_name: "" }),
+      store,
+      "/anything/rename",
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("POST /tags/merge combines multiple sources into target", async () => {
+    await store.createNote("A", { tags: ["v1"] });
+    await store.createNote("B", { tags: ["v2"] });
+    await store.createNote("C", { tags: ["v1", "v2"] });
+
+    const res = await handleTags(
+      mkReq("POST", "/tags/merge", { sources: ["v1", "v2"], target: "voice" }),
+      store,
+      "/merge",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.target).toBe("voice");
+    expect(body.merged).toEqual({ v1: 2, v2: 2 });
+
+    const tags = await store.listTags();
+    expect(tags.find((t: any) => t.name === "voice")!.count).toBe(3);
+    expect(tags.some((t: any) => t.name === "v1")).toBe(false);
+    expect(tags.some((t: any) => t.name === "v2")).toBe(false);
+  });
+
+  test("POST /tags/merge dedupes duplicate sources", async () => {
+    await store.createNote("A", { tags: ["v1"] });
+    const res = await handleTags(
+      mkReq("POST", "/tags/merge", { sources: ["v1", "v1"], target: "voice" }),
+      store,
+      "/merge",
+    );
+    const body = await res.json() as any;
+    expect(body.merged).toEqual({ v1: 1 });
+  });
+
+  test("POST /tags/merge creates the target tag if missing", async () => {
+    await store.createNote("A", { tags: ["legacy"] });
+    const res = await handleTags(
+      mkReq("POST", "/tags/merge", { sources: ["legacy"], target: "fresh" }),
+      store,
+      "/merge",
+    );
+    expect(res.status).toBe(200);
+    const tags = await store.listTags();
+    expect(tags.find((t: any) => t.name === "fresh")!.count).toBe(1);
+  });
+
+  test("POST /tags/merge rejects bad body with 400", async () => {
+    const res = await handleTags(
+      mkReq("POST", "/tags/merge", { sources: "v1", target: "voice" }),
+      store,
+      "/merge",
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("POST /tags/merge rejects non-POST with 405", async () => {
+    const res = await handleTags(mkReq("GET", "/tags/merge"), store, "/merge");
+    expect(res.status).toBe(405);
+  });
 });
 
 describe("HTTP /find-path", async () => {
@@ -1230,8 +1545,8 @@ describe("HTTP /find-path", async () => {
 
 describe("stateless MCP transport", async () => {
   test("tools/call works without prior initialize handshake", async () => {
-    const { handleUnifiedMcp } = await import("./mcp-http.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
     const vaultName = `stateless-mcp-${Date.now()}`;
@@ -1240,13 +1555,12 @@ describe("stateless MCP transport", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
     const vaultStore = getVaultStore(vaultName);
     await vaultStore.createNote("test note", { tags: ["daily"] });
 
     // Direct tools/call — no initialize, no session header
-    const req = new Request("http://localhost:1940/mcp", {
+    const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -1256,11 +1570,15 @@ describe("stateless MCP transport", async () => {
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
-        params: { name: "vault-info", arguments: { vault: vaultName, include_stats: true } },
+        params: { name: "vault-info", arguments: { include_stats: true } },
       }),
     });
 
-    const res = await handleUnifiedMcp(req, "write");
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+    });
     expect(res.status).toBe(200);
 
     const body = await res.json() as any;
@@ -1272,8 +1590,8 @@ describe("stateless MCP transport", async () => {
   });
 
   test("tools/list works without prior initialize handshake", async () => {
-    const { handleUnifiedMcp } = await import("./mcp-http.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
 
     const vaultName = `stateless-list-${Date.now()}`;
@@ -1282,9 +1600,8 @@ describe("stateless MCP transport", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
-    const req = new Request("http://localhost:1940/mcp", {
+    const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -1298,7 +1615,11 @@ describe("stateless MCP transport", async () => {
       }),
     });
 
-    const res = await handleUnifiedMcp(req, "write");
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+    });
     expect(res.status).toBe(200);
 
     const body = await res.json() as any;
@@ -1311,9 +1632,193 @@ describe("stateless MCP transport", async () => {
     closeAllStores();
   });
 
+  test("tools/list with vault:read scope only advertises read-only tools", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `scope-list-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+    });
+
+    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/list",
+        params: {},
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "read",
+      scopes: ["vault:read"],
+      legacyDerived: false,
+    });
+    expect(res.status).toBe(200);
+
+    const body = await res.json() as any;
+    const toolNames: string[] = body.result.tools.map((t: any) => t.name);
+    // Read-only tools are visible
+    expect(toolNames).toContain("query-notes");
+    expect(toolNames).toContain("list-tags");
+    expect(toolNames).toContain("find-path");
+    expect(toolNames).toContain("vault-info");
+    // 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");
+    expect(toolNames).not.toContain("update-tag");
+    expect(toolNames).not.toContain("delete-tag");
+
+    closeAllStores();
+  });
+
+  test("tools/call of vault-info with description arg and vault:read scope is refused", 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-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "original description",
+    });
+
+    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: "hijacked description" },
+        },
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "read",
+      scopes: ["vault:read"],
+      legacyDerived: false,
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // The tool call must surface as an error (isError: true) and mention
+    // 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");
+
+    // And critically: the vault description must NOT have been mutated.
+    const cfg = readVaultConfig(vaultName);
+    expect(cfg?.description).toBe("original description");
+
+    closeAllStores();
+  });
+
+  test("tools/call of vault-info with description arg and vault:write 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-write-${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 write scope" },
+        },
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write"],
+      legacyDerived: false,
+    });
+
+    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");
+
+    closeAllStores();
+  });
+
+  test("tools/call of create-note with vault:read scope is refused (not silently allowed)", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `scope-call-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+    });
+
+    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: "create-note", arguments: { content: "nope" } },
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "read",
+      scopes: ["vault:read"],
+      legacyDerived: false,
+    });
+    expect(res.status).toBe(200); // JSON-RPC envelope is 200 even for tool errors
+    const body = await res.json() as any;
+    expect(body.result.isError).toBe(true);
+    expect(body.result.content[0].text).toContain("vault:write");
+
+    closeAllStores();
+  });
+
   test("initialize still works for clients that send it", async () => {
-    const { handleUnifiedMcp } = await import("./mcp-http.ts");
-    const { writeVaultConfig, writeGlobalConfig } = await import("./config.ts");
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
 
     const vaultName = `stateless-init-${Date.now()}`;
@@ -1322,9 +1827,8 @@ describe("stateless MCP transport", async () => {
       api_keys: [],
       created_at: new Date().toISOString(),
     });
-    writeGlobalConfig({ port: 1940, default_vault: vaultName });
 
-    const req = new Request("http://localhost:1940/mcp", {
+    const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -1342,12 +1846,16 @@ describe("stateless MCP transport", async () => {
       }),
     });
 
-    const res = await handleUnifiedMcp(req, "write");
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+    });
     expect(res.status).toBe(200);
 
     const body = await res.json() as any;
     expect(body.result.protocolVersion).toBe("2024-11-05");
-    expect(body.result.serverInfo.name).toBe("parachute-vault");
+    expect(body.result.serverInfo.name).toBe(`parachute-vault/${vaultName}`);
     expect(body.result.capabilities.tools).toBeDefined();
 
     closeAllStores();
@@ -1401,3 +1909,111 @@ describe("extractApiKey", () => {
   });
 });
 
+describe("handleVault: audio_retention", async () => {
+  function mkVaultReq(method: string, body?: unknown): Request {
+    const init: RequestInit = { method };
+    if (body !== undefined) {
+      init.body = JSON.stringify(body);
+      init.headers = { "Content-Type": "application/json" };
+    }
+    return new Request(`${BASE}/vault`, init);
+  }
+
+  test("GET returns config.audio_retention defaulting to 'keep' when unset", async () => {
+    const cfg = { name: "default" } as { name: string; audio_retention?: 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.name).toBe("default");
+    expect(body.config.audio_retention).toBe("keep");
+  });
+
+  test("GET reflects the currently stored value", async () => {
+    const cfg = { name: "default", audio_retention: "until_transcribed" };
+    const res = await handleVault(mkReq("GET", "/vault"), store, cfg as any);
+    const body = await res.json() as any;
+    expect(body.config.audio_retention).toBe("until_transcribed");
+  });
+
+  test("PATCH sets audio_retention and invokes persist", async () => {
+    const cfg: { name: string; audio_retention?: string } = { name: "default" };
+    let persisted = 0;
+    const res = await handleVault(
+      mkVaultReq("PATCH", { config: { audio_retention: "until_transcribed" } }),
+      store,
+      cfg as any,
+      () => { persisted++; },
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.config.audio_retention).toBe("until_transcribed");
+    expect(cfg.audio_retention).toBe("until_transcribed");
+    expect(persisted).toBe(1);
+  });
+
+  test("PATCH accepts 'never'", async () => {
+    const cfg: { name: string; audio_retention?: string } = { name: "default" };
+    const res = await handleVault(
+      mkVaultReq("PATCH", { config: { audio_retention: "never" } }),
+      store,
+      cfg as any,
+      () => {},
+    );
+    expect(res.status).toBe(200);
+    expect(cfg.audio_retention).toBe("never");
+  });
+
+  test("PATCH rejects invalid modes with 400 and does not mutate", async () => {
+    const cfg: { name: string; audio_retention?: string } = {
+      name: "default",
+      audio_retention: "keep",
+    };
+    let persisted = 0;
+    const res = await handleVault(
+      mkVaultReq("PATCH", { config: { audio_retention: "forever" } }),
+      store,
+      cfg as any,
+      () => { persisted++; },
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error).toBe("invalid_audio_retention");
+    expect(cfg.audio_retention).toBe("keep");
+    expect(persisted).toBe(0);
+  });
+
+  test("PATCH with only description leaves audio_retention alone", async () => {
+    const cfg: { name: string; description?: string; audio_retention?: string } = {
+      name: "default",
+      audio_retention: "until_transcribed",
+    };
+    const res = await handleVault(
+      mkVaultReq("PATCH", { description: "new desc" }),
+      store,
+      cfg as any,
+      () => {},
+    );
+    expect(res.status).toBe(200);
+    expect(cfg.description).toBe("new desc");
+    expect(cfg.audio_retention).toBe("until_transcribed");
+  });
+
+  test("PATCH with empty body is a no-op that still returns current state", async () => {
+    const cfg: { name: string; audio_retention?: string } = {
+      name: "default",
+      audio_retention: "never",
+    };
+    let persisted = 0;
+    const res = await handleVault(
+      mkVaultReq("PATCH", {}),
+      store,
+      cfg as any,
+      () => { persisted++; },
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.config.audio_retention).toBe("never");
+    expect(persisted).toBe(0);
+  });
+});
+