@openparachute/vault 0.3.3 → 0.4.3

package/src/vault.test.ts

@@ -476,7 +476,7 @@ 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);
 
@@ -490,6 +490,12 @@ describe("MCP tools", async () => {
     expect(names).toContain("delete-tag");
     expect(names).toContain("find-path");
     expect(names).toContain("vault-info");
+    // Six note-schema MCP tools (list/update/delete-note-schema +
+    // list/set/delete-schema-mapping) retired in v17 — vault#267.
+    expect(names).not.toContain("list-note-schemas");
+    expect(names).not.toContain("set-schema-mapping");
+    // synthesize-notes retired in v17 — vault#268.
+    expect(names).not.toContain("synthesize-notes");
   });
 
   test("query-notes by id works", async () => {
@@ -559,6 +565,355 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
+  test("vault-info projection includes tags-with-schemas + indexed_fields + query_hints (vault#271)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `proj-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "vault for #271",
+    });
+
+    const vaultStore = getVaultStore(vaultName);
+    await vaultStore.upsertTagRecord("_default", {
+      fields: { created_by: { type: "string", description: "Origin" } },
+    });
+
+    // Indexed-field lifecycle is owned by the update-tag MCP tool — go
+    // through the tool, not the store, so indexed_fields gets populated.
+    const tools = generateScopedMcpTools(vaultName);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "person",
+      description: "A person",
+      fields: { email: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "employee",
+      description: "Employee",
+      fields: { title: { type: "string" } },
+      parent_names: ["person"],
+    });
+
+    const vaultInfo = tools.find((t) => t.name === "vault-info")!;
+    const result = await vaultInfo.execute({}) as any;
+
+    expect(result.name).toBe(vaultName);
+    expect(result.description).toBe("vault for #271");
+
+    // tags array — only schema-bearing rows, with effective inheritance
+    const byName = Object.fromEntries(
+      (result.tags as any[]).map((t) => [t.name, t]),
+    );
+    expect(byName.person).toBeTruthy();
+    expect(byName.person.effective_parents).toEqual(["_default"]);
+    expect(Object.keys(byName.person.effective_fields).sort()).toEqual([
+      "created_by",
+      "email",
+    ]);
+    expect(byName.employee.effective_parents).toEqual(["person", "_default"]);
+    expect(Object.keys(byName.employee.effective_fields).sort()).toEqual([
+      "created_by",
+      "email",
+      "title",
+    ]);
+
+    // indexed_fields catalog
+    const indexed = result.indexed_fields as any[];
+    const emailEntry = indexed.find((f) => f.name === "email");
+    expect(emailEntry).toBeTruthy();
+    expect(emailEntry.type).toBe("string");
+    expect(emailEntry.tags).toEqual(["person"]);
+
+    // query_hints — static catalog, present even without include_stats
+    expect(Array.isArray(result.query_hints)).toBe(true);
+    expect((result.query_hints as string[]).length).toBeGreaterThan(0);
+
+    // stats omitted unless requested
+    expect(result.stats).toBeUndefined();
+
+    const withStats = await vaultInfo.execute({ include_stats: true }) as any;
+    expect(withStats.stats).toBeTruthy();
+
+    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");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+
+    const vaultName = `instr-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "Working notebook for the daily team.",
+    });
+
+    const vaultStore = getVaultStore(vaultName);
+    await vaultStore.createNote("A", { tags: ["person"] });
+
+    const tools = generateScopedMcpTools(vaultName);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "person",
+      description: "A person",
+      fields: { email: { type: "string", indexed: true } },
+    });
+
+    const md = await getServerInstruction(vaultName);
+
+    expect(md).toContain(`Parachute Vault "${vaultName}"`);
+    expect(md).toContain("Working notebook for the daily team.");
+    // vault#274: stats line distinguishes total tag count (note-usage)
+    // from schema-bearing count. One note tagged `person`, one tag
+    // overall, that one tag has a schema → "1 tag total, 1 with schemas".
+    expect(md).toContain("1 note, 1 tag total, 1 with schemas");
+    expect(md).toContain("1 tag with schemas: person");
+    expect(md).toContain("Indexed metadata fields");
+    expect(md).toContain("email");
+    expect(md).toContain("#person");
+    expect(md).toContain("Querying");
+    expect(md).toContain("vault-info");
+    expect(md).toContain("list-tags { include_schema: true }");
+
+    closeAllStores();
+  });
+
+  test("getServerInstruction degrades gracefully on an empty vault (vault#271)", async () => {
+    const { getServerInstruction } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `instr-empty-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+    });
+
+    const md = await getServerInstruction(vaultName);
+
+    expect(md).toContain(`Parachute Vault "${vaultName}"`);
+    // vault#274: empty vault — no schemas, so the suffix is omitted.
+    // 0 is plural per English convention. The not.toContain guard
+    // pins that "with schemas" doesn't leak through anywhere — when
+    // schemas exist it appears in two places (stats suffix + the
+    // tags-with-schemas list line); on an empty vault both branches
+    // are unreachable, so the phrase shouldn't appear at all.
+    expect(md).toContain("0 notes, 0 tags total");
+    expect(md).not.toContain("with schemas");
+    expect(md).toContain("No tag schemas declared");
+    expect(md).toContain("No indexed metadata fields");
+    // Refresh hints surface both pointers so the agent knows where to look.
+    expect(md).toContain("vault-info");
+    expect(md).toContain("list-tags");
+
+    closeAllStores();
+  });
+
+  test("getServerInstruction stays under ~5K tokens at 50 tags-with-schemas (vault#271)", async () => {
+    const { getServerInstruction } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `instr-big-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "Stress-test fixture for the connect-time projection size.",
+    });
+
+    const vaultStore = getVaultStore(vaultName);
+    for (let i = 0; i < 50; i++) {
+      await vaultStore.upsertTagRecord(`schema_tag_${i}`, {
+        description: `Description for tag ${i} — covers a meaningful chunk of the vault's domain.`,
+        fields: {
+          [`field_${i}_a`]: { type: "string" },
+          [`field_${i}_b`]: { type: "integer" },
+        },
+      });
+    }
+
+    const md = await getServerInstruction(vaultName);
+    // Rough token approximation: 1 token ≈ 4 chars. Budget: 5K tokens.
+    const approxTokens = md.length / 4;
+    expect(approxTokens).toBeLessThan(5000);
+
+    closeAllStores();
+  });
+
+  test("getServerInstruction filters projection by tag-scoped allowlist (vault#271 fold 5)", async () => {
+    const { getServerInstruction, generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `instr-scoped-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      description: "Scoped session brief.",
+    });
+
+    // Seed three schema-bearing tags. Cross-declarer indexed `status`
+    // exercises the same shape the JSON wrapper test pinned: scoped to
+    // `task`, the brief should mention `status` via `task` but never
+    // surface `project` or `person`.
+    const tools = generateScopedMcpTools(vaultName);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      description: "A task",
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      description: "A project",
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "person",
+      description: "A person",
+      fields: { email: { type: "string", indexed: true } },
+    });
+
+    const auth = {
+      permission: "full" as const,
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+      scoped_tags: ["task"],
+    };
+    const md = await getServerInstruction(vaultName, auth as any);
+
+    // Allowlisted tag surfaces; out-of-scope tags do not. Use word-boundary
+    // regex — the static refresh-pointer text mentions "full projection"
+    // which contains the substring "project".
+    expect(md).toMatch(/\btask\b/);
+    expect(md).not.toMatch(/\bproject\b/);
+    expect(md).not.toMatch(/\bperson\b/);
+
+    // Indexed-field catalog: `status` survives (declared by `task`);
+    // `email` (person-only) is filtered out entirely.
+    expect(md).toMatch(/\bstatus\b/);
+    expect(md).not.toMatch(/\bemail\b/);
+
+    // Aggregate stats line still flows through unchanged — counts are
+    // pre-existing leak surface (per the rc.3 design discussion).
+    expect(md).toMatch(/\d+ note/);
+
+    closeAllStores();
+  });
+
+  test("getServerInstruction passes the full projection through for unscoped tokens (vault#271 fold 5)", async () => {
+    const { getServerInstruction, generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `instr-unscoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const tools = generateScopedMcpTools(vaultName);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      description: "A task",
+      fields: { status: { type: "string" } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      description: "A project",
+      fields: { priority: { type: "integer" } },
+    });
+
+    // No `auth` arg → no scoping applied, full projection rendered.
+    const md = await getServerInstruction(vaultName);
+    expect(md).toContain("task");
+    expect(md).toContain("project");
+    expect(md).toContain("tags with schemas");
+    // Same for explicit auth with `scoped_tags: null`.
+    const mdNullScoped = await getServerInstruction(vaultName, {
+      permission: "full",
+      scopes: ["vault:read"],
+      legacyDerived: false,
+      scoped_tags: null,
+    } as any);
+    expect(mdNullScoped).toContain("task");
+    expect(mdNullScoped).toContain("project");
+
+    closeAllStores();
+  });
+
+  test("MCP initialize response carries scope-filtered instructions for tag-scoped tokens (vault#271 fold 5)", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `init-scoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    // Same fixture shape as the unit test, but driven through the actual
+    // `handleScopedMcp` initialize path the MCP client invokes at session
+    // start. The reviewer asked for an integration assertion on the
+    // `instructions` field carried in the `initialize` response.
+    const tools = generateScopedMcpTools(vaultName);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      description: "A task",
+      fields: { status: { type: "string" } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      description: "A project",
+      fields: { priority: { type: "integer" } },
+    });
+
+    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: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "test", version: "1.0" },
+        },
+      }),
+    });
+
+    const res = await handleScopedMcp(req, vaultName, {
+      permission: "full",
+      scopes: ["vault:read", "vault:write", "vault:admin"],
+      legacyDerived: false,
+      scoped_tags: ["task"],
+    } as any);
+    expect(res.status).toBe(200);
+
+    const body = await res.json() as any;
+    const instructions: string = body.result.instructions;
+    expect(instructions).toBeTruthy();
+    // Word-boundary match — the static refresh text mentions "full
+    // projection" which would false-trigger a substring check.
+    expect(instructions).toMatch(/\btask\b/);
+    expect(instructions).not.toMatch(/\bproject\b/);
+
+    closeAllStores();
+  });
+
   test("list-tags with schema returns per-tag detail", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
@@ -711,89 +1066,445 @@ describe("scoped MCP wrapper", async () => {
     close();
   });
 
-  test("update-note tags.add auto-populate does not bump updatedAt", async () => {
+  // -- 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: close } = await import("./vault-store.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
-    const vaultName = `schema-noupdate-${Date.now()}`;
-    writeVaultConfig({
-      name: vaultName,
-      api_keys: [],
-      created_at: new Date().toISOString(),
-    });
+    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 vaultStore = getVaultStore(vaultName);
-    await vaultStore.upsertTagSchema("person", {
-      description: "A person",
-      fields: { name: { type: "string" } },
-    });
+    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();
 
-    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")!;
+    closeAllStores();
+  });
 
-    const note = await createNote.execute({ content: "Test" }) as any;
-    const originalUpdatedAt = note.updatedAt;
-    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("");
+  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");
 
-    close();
-  });
-});
+    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"] });
 
-describe("auth permissions", () => {
-  test("read permission allows read-only tools", () => {
-    const { isToolAllowed } = require("./auth.ts");
-    expect(isToolAllowed("query-notes", "read")).toBe(true);
-    expect(isToolAllowed("list-tags", "read")).toBe(true);
-    expect(isToolAllowed("find-path", "read")).toBe(true);
-    expect(isToolAllowed("vault-info", "read")).toBe(true);
-  });
+    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);
 
-  test("read permission blocks mutation tools", () => {
-    const { isToolAllowed } = require("./auth.ts");
-    expect(isToolAllowed("create-note", "read")).toBe(false);
-    expect(isToolAllowed("update-note", "read")).toBe(false);
-    expect(isToolAllowed("delete-note", "read")).toBe(false);
-    expect(isToolAllowed("update-tag", "read")).toBe(false);
-    expect(isToolAllowed("delete-tag", "read")).toBe(false);
+    closeAllStores();
   });
 
-  test("full permission allows all tools", () => {
-    const { isToolAllowed } = require("./auth.ts");
-    expect(isToolAllowed("create-note", "full")).toBe(true);
-    expect(isToolAllowed("update-note", "full")).toBe(true);
-    expect(isToolAllowed("delete-note", "full")).toBe(true);
-    expect(isToolAllowed("update-tag", "full")).toBe(true);
-    expect(isToolAllowed("delete-tag", "full")).toBe(true);
-    expect(isToolAllowed("query-notes", "full")).toBe(true);
-  });
+  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");
 
-  test("read permission allows GET but not POST/PATCH/DELETE", () => {
-    const { isMethodAllowed } = require("./auth.ts");
-    expect(isMethodAllowed("GET", "read")).toBe(true);
-    expect(isMethodAllowed("HEAD", "read")).toBe(true);
-    expect(isMethodAllowed("POST", "read")).toBe(false);
-    expect(isMethodAllowed("PATCH", "read")).toBe(false);
-    expect(isMethodAllowed("DELETE", "read")).toBe(false);
-  });
+    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"] });
 
-  test("full permission allows all methods", () => {
-    const { isMethodAllowed } = require("./auth.ts");
-    expect(isMethodAllowed("GET", "full")).toBe(true);
-    expect(isMethodAllowed("POST", "full")).toBe(true);
-    expect(isMethodAllowed("PATCH", "full")).toBe(true);
-    expect(isMethodAllowed("DELETE", "full")).toBe(true);
-  });
-});
+    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");
 
-// ---- HTTP route handlers ----
+    closeAllStores();
+  });
 
-const BASE = "http://localhost/api";
+  test("scoped vault-info filters projection.tags + indexed_fields to the allowlist (vault#271 fold)", 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-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    // Seed two schema-bearing tags. `task` and `project` BOTH declare a
+    // shared indexed `status` field — this exercises the cross-declarer
+    // case the reviewer called out: a token scoped to `task` should see
+    // `status` (because task is a declarer) but the entry's `tags` array
+    // must list only `task`, not `project`.
+    const unscopedTools = generateScopedMcpTools(vaultName);
+    const updateTag = unscopedTools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      description: "A task",
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      description: "A project",
+      fields: {
+        status: { type: "string", indexed: true },
+        priority: { type: "integer", indexed: true },
+      },
+    });
+
+    // Now mint scoped tools, scoped to `task` only.
+    const tools = generateScopedMcpTools(vaultName, authForTags(["task"]) as any);
+    const vaultInfo = tools.find((t) => t.name === "vault-info")!;
+    const result = await vaultInfo.execute({}) as any;
+
+    // tags array: only `task`, not `project`.
+    const tagNames = (result.tags as { name: string }[]).map((t) => t.name);
+    expect(tagNames).toContain("task");
+    expect(tagNames).not.toContain("project");
+
+    // indexed_fields: `status` survives (task is a declarer), `priority`
+    // dropped entirely (only project declared it).
+    const indexedNames = (result.indexed_fields as { name: string }[]).map((f) => f.name);
+    expect(indexedNames).toContain("status");
+    expect(indexedNames).not.toContain("priority");
+
+    // Cross-declarer attribution leak: `status` lists declarer tags. The
+    // scoped response must show only `task`, never the out-of-scope
+    // `project`.
+    const status = (result.indexed_fields as { name: string; tags: string[] }[]).find(
+      (f) => f.name === "status",
+    )!;
+    expect(status.tags).toEqual(["task"]);
+
+    // Top-level passthrough sanity: name, description, and query_hints are
+    // not tag-scoped surfaces — they must still flow through.
+    expect(result.name).toBe(vaultName);
+    expect(Array.isArray(result.query_hints)).toBe(true);
+    expect((result.query_hints as string[]).length).toBeGreaterThan(0);
+
+    closeAllStores();
+  });
+
+  test("unscoped vault-info still sees the full projection (vault#271 fold)", 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-unscoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+
+    const tools0 = generateScopedMcpTools(vaultName);
+    const updateTag = tools0.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({ tag: "task", description: "T", fields: { status: { type: "string", indexed: true } } });
+    await updateTag.execute({ tag: "project", description: "P", fields: { status: { type: "string", indexed: true } } });
+
+    // No `auth` and no `scoped_tags` — unscoped path must remain
+    // identical to pre-fold behavior (full projection).
+    const tools = generateScopedMcpTools(vaultName);
+    const result = await tools.find((t) => t.name === "vault-info")!.execute({}) as any;
+    const tagNames = (result.tags as { name: string }[]).map((t) => t.name);
+    expect(tagNames.sort()).toEqual(["project", "task"]);
+    const status = (result.indexed_fields as { name: string; tags: string[] }[]).find((f) => f.name === "status")!;
+    expect(status.tags.sort()).toEqual(["project", "task"]);
+
+    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");
+    const { getVaultStore, closeAllStores: close } = await import("./vault-store.ts");
+
+    const vaultName = `schema-noupdate-${Date.now()}`;
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+    });
+
+    const vaultStore = getVaultStore(vaultName);
+    await vaultStore.upsertTagSchema("person", {
+      description: "A person",
+      fields: { name: { type: "string" } },
+    });
+
+    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({ content: "Test" }) as any;
+    const originalUpdatedAt = note.updatedAt;
+    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("");
+
+    close();
+  });
+});
+
+describe("auth permissions", () => {
+  test("read permission allows read-only tools", () => {
+    const { isToolAllowed } = require("./auth.ts");
+    expect(isToolAllowed("query-notes", "read")).toBe(true);
+    expect(isToolAllowed("list-tags", "read")).toBe(true);
+    expect(isToolAllowed("find-path", "read")).toBe(true);
+    expect(isToolAllowed("vault-info", "read")).toBe(true);
+  });
+
+  test("read permission blocks mutation tools", () => {
+    const { isToolAllowed } = require("./auth.ts");
+    expect(isToolAllowed("create-note", "read")).toBe(false);
+    expect(isToolAllowed("update-note", "read")).toBe(false);
+    expect(isToolAllowed("delete-note", "read")).toBe(false);
+    expect(isToolAllowed("update-tag", "read")).toBe(false);
+    expect(isToolAllowed("delete-tag", "read")).toBe(false);
+  });
+
+  test("full permission allows all tools", () => {
+    const { isToolAllowed } = require("./auth.ts");
+    expect(isToolAllowed("create-note", "full")).toBe(true);
+    expect(isToolAllowed("update-note", "full")).toBe(true);
+    expect(isToolAllowed("delete-note", "full")).toBe(true);
+    expect(isToolAllowed("update-tag", "full")).toBe(true);
+    expect(isToolAllowed("delete-tag", "full")).toBe(true);
+    expect(isToolAllowed("query-notes", "full")).toBe(true);
+  });
+
+  test("read permission allows GET but not POST/PATCH/DELETE", () => {
+    const { isMethodAllowed } = require("./auth.ts");
+    expect(isMethodAllowed("GET", "read")).toBe(true);
+    expect(isMethodAllowed("HEAD", "read")).toBe(true);
+    expect(isMethodAllowed("POST", "read")).toBe(false);
+    expect(isMethodAllowed("PATCH", "read")).toBe(false);
+    expect(isMethodAllowed("DELETE", "read")).toBe(false);
+  });
+
+  test("full permission allows all methods", () => {
+    const { isMethodAllowed } = require("./auth.ts");
+    expect(isMethodAllowed("GET", "full")).toBe(true);
+    expect(isMethodAllowed("POST", "full")).toBe(true);
+    expect(isMethodAllowed("PATCH", "full")).toBe(true);
+    expect(isMethodAllowed("DELETE", "full")).toBe(true);
+  });
+});
+
+// ---- HTTP route handlers ----
+
+const BASE = "http://localhost/api";
 
 function mkReq(method: string, path: string, body?: unknown): Request {
   const init: RequestInit = { method };
@@ -839,6 +1550,31 @@ describe("HTTP /notes", async () => {
     expect(body.map((n) => n.content)).toEqual(["plain"]);
   });
 
+  // ---- updated_at filter via date_field (vault#285 friction point 1.5) ----
+  //
+  // HTTP plumbing routes `date_field=updated_at&date_from=…` straight to
+  // the core `dateFilter` resolver, which now recognizes `updated_at` as
+  // a real column. Smoke-tests the end-to-end HTTP path; the engine-side
+  // semantics are exercised in core.test.ts.
+  test("GET /notes?date_field=updated_at filters by last-write time", async () => {
+    const a = await store.createNote("untouched", { id: "ua", path: "ua" });
+    const b = await store.createNote("modified", { id: "ub", path: "ub" });
+    // Bump b's updated_at into the test window, leave a's at its createdAt.
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-01-15T00:00:00.000Z", a.id);
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-25T00:00:00.000Z", b.id);
+
+    const res = await handleNotes(
+      mkReq("GET", "/notes?date_field=updated_at&date_from=2026-04-01&include_content=true"),
+      store,
+      "",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.content)).toEqual(["modified"]);
+  });
+
   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" });
@@ -978,171 +1714,689 @@ describe("HTTP /notes", async () => {
     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" });
+  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);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 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);
+    });
+  });
+
+  // ---- Bracket-style metadata filter (vault#285 friction point 1.3) ----
+  //
+  // Exposes vault's engine-level metadata-value filtering to HTTP REST
+  // callers (today: only MCP). Uses `meta[field][op]=value` (Stripe /
+  // JSON:API / Strapi convention). The HTTP layer translates to the engine's
+  // existing `metadata` filter; engine semantics + gates are unchanged.
+  // Bridges `created_at` / `updated_at` through `dateFilter`.
+  describe("bracket-style metadata filter", () => {
+    async function declareIndexed() {
+      const { declareField } = await import("../core/src/indexed-fields.ts");
+      declareField(db, "priority", "INTEGER", "project");
+      declareField(db, "status", "TEXT", "project");
+    }
+
+    test("shorthand `?meta[field]=value` does exact equality (JSON scan, no indexed gate)", async () => {
+      // Deliberately NOT calling declareIndexed — shorthand should work on
+      // any field via the json_extract fallback at core/src/notes.ts:504-507.
+      await store.createNote("matches", { metadata: { kind: "draft" } });
+      await store.createNote("other", { metadata: { kind: "final" } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[kind]=draft&include_content=true"),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["matches"]);
+    });
+
+    test("eq operator on indexed field", async () => {
+      await declareIndexed();
+      await store.createNote("p5", { metadata: { priority: 5 } });
+      await store.createNote("p1", { metadata: { priority: 1 } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][eq]=5&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["p5"]);
+    });
+
+    test("ne operator returns non-matching rows plus rows without the field", async () => {
+      await declareIndexed();
+      await store.createNote("has-1", { metadata: { priority: 1 } });
+      await store.createNote("has-2", { metadata: { priority: 2 } });
+      await store.createNote("missing");
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][ne]=1&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content).sort()).toEqual(["has-2", "missing"]);
+    });
+
+    test("gt / gte / lt / lte compose into a range query on one field", async () => {
+      await declareIndexed();
+      for (const p of [1, 2, 3, 4, 5]) {
+        await store.createNote(`p${p}`, { metadata: { priority: p } });
+      }
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][gte]=2&meta[priority][lt]=5&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content).sort()).toEqual(["p2", "p3", "p4"]);
+    });
+
+    test("in array form: `?meta[field][in][]=v1&meta[field][in][]=v2`", async () => {
+      await declareIndexed();
+      await store.createNote("a", { metadata: { status: "active" } });
+      await store.createNote("b", { metadata: { status: "exploring" } });
+      await store.createNote("c", { metadata: { status: "done" } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[status][in][]=active&meta[status][in][]=exploring&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content).sort()).toEqual(["a", "b"]);
+    });
+
+    test("in comma form: `?meta[field][in]=v1,v2`", async () => {
+      await declareIndexed();
+      await store.createNote("a", { metadata: { status: "active" } });
+      await store.createNote("b", { metadata: { status: "exploring" } });
+      await store.createNote("c", { metadata: { status: "done" } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[status][in]=active,exploring&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content).sort()).toEqual(["a", "b"]);
+    });
+
+    test("not_in via comma form", async () => {
+      await declareIndexed();
+      await store.createNote("a", { metadata: { status: "active" } });
+      await store.createNote("b", { metadata: { status: "done" } });
       const res = await handleNotes(
-        mkReq("POST", "/notes/v1/attachments", {
-          path: "memos/memo-1.webm",
-          mimeType: "audio/webm",
-          transcribe: true,
-        }),
+        mkReq("GET", "/notes?meta[status][not_in]=done&include_content=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 body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["a"]);
+    });
 
-      const note = await store.getNote("v1");
-      expect((note!.metadata as any)?.transcribe_stub).toBe(true);
+    test("exists: true / false distinguishes present vs absent field", async () => {
+      await declareIndexed();
+      await store.createNote("has", { metadata: { priority: 3 } });
+      await store.createNote("missing");
+
+      const hasRes = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][exists]=true&include_content=true"),
+        store,
+        "",
+      );
+      const hasBody = await hasRes.json() as any[];
+      expect(hasBody.map((n) => n.content)).toEqual(["has"]);
+
+      const missingRes = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][exists]=false&include_content=true"),
+        store,
+        "",
+      );
+      const missingBody = await missingRes.json() as any[];
+      expect(missingBody.map((n) => n.content)).toEqual(["missing"]);
     });
 
-    test("transcribe: false (default) leaves metadata empty and note untouched", async () => {
-      await store.createNote("note body", { id: "v2" });
+    test("exists with non-boolean value rejects with INVALID_OPERATOR_VALUE", async () => {
+      await declareIndexed();
       const res = await handleNotes(
-        mkReq("POST", "/notes/v2/attachments", {
-          path: "memos/memo-2.webm",
-          mimeType: "audio/webm",
-        }),
+        mkReq("GET", "/notes?meta[priority][exists]=yes"),
         store,
-        "/v2/attachments",
+        "",
       );
-      expect(res.status).toBe(201);
-      const att = await res.json() as any;
-      expect(att.metadata?.transcribe_status).toBeUndefined();
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_OPERATOR_VALUE");
+    });
 
-      const note = await store.getNote("v2");
-      expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
+    test("compound filter across two fields ANDs together", async () => {
+      await declareIndexed();
+      await store.createNote("hit", { metadata: { priority: 5, status: "active" } });
+      await store.createNote("priority-only", { metadata: { priority: 5, status: "done" } });
+      await store.createNote("status-only", { metadata: { priority: 1, status: "active" } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][gte]=4&meta[status][eq]=active&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["hit"]);
     });
 
-    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,
-        }),
+    test("operator query on a non-indexed field returns 400 with FIELD_NOT_INDEXED", async () => {
+      // Don't declare the field — the engine's indexed-field gate should fire.
+      await store.createNote("x", { metadata: { mood: "great" } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[mood][eq]=great"),
         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);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("FIELD_NOT_INDEXED");
     });
-  });
 
-  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;
+    test("unknown operator returns 400 with UNKNOWN_OPERATOR", async () => {
+      await declareIndexed();
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][bogus]=5"),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("UNKNOWN_OPERATOR");
+    });
 
-      const n = await store.createNote("x", { id: "n1" });
-      const att = await store.addAttachment(n.id, relPath, "image/png");
+    // ---- Bridge: created_at / updated_at via brackets route to dateFilter ----
+    test("`meta[created_at][gte]=…` routes to dateFilter (same result as flat date_field)", async () => {
+      await store.createNote("old", { created_at: "2026-01-15T00:00:00.000Z" });
+      await store.createNote("new", { created_at: "2026-04-15T00:00:00.000Z" });
 
-      const res = await handleNotes(
-        mkReq("DELETE", `/notes/n1/attachments/${att.id}`),
+      const bracketRes = await handleNotes(
+        mkReq("GET", "/notes?meta[created_at][gte]=2026-04-01&include_content=true"),
         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);
+      const bracketBody = await bracketRes.json() as any[];
+      const flatRes = await handleNotes(
+        mkReq("GET", "/notes?date_field=created_at&date_from=2026-04-01&include_content=true"),
+        store,
+        "",
+      );
+      const flatBody = await flatRes.json() as any[];
+      expect(bracketBody.map((n) => n.content)).toEqual(["new"]);
+      expect(bracketBody.map((n) => n.content)).toEqual(flatBody.map((n) => n.content));
+    });
 
-      delete process.env.ASSETS_DIR;
+    test("`meta[updated_at][gte]=…` routes to dateFilter on n.updated_at", async () => {
+      const a = await store.createNote("untouched");
+      const b = await store.createNote("modified");
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-01-15T00:00:00.000Z", a.id);
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", b.id);
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[updated_at][gte]=2026-04-01&include_content=true"),
+        store,
+        "",
+      );
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["modified"]);
     });
 
-    test("404 when attachment does not exist", async () => {
-      await store.createNote("x", { id: "n2" });
+    test("`meta[created_at][lt]=…` maps to dateFilter's exclusive upper bound", async () => {
+      await store.createNote("inside", { created_at: "2026-04-15T00:00:00.000Z" });
+      await store.createNote("on-boundary", { created_at: "2026-05-01T00:00:00.000Z" });
       const res = await handleNotes(
-        mkReq("DELETE", "/notes/n2/attachments/nonexistent"),
+        mkReq("GET", "/notes?meta[created_at][lt]=2026-05-01&include_content=true"),
         store,
-        "/n2/attachments/nonexistent",
-        "default",
+        "",
       );
-      expect(res.status).toBe(404);
+      const body = await res.json() as any[];
+      // "on-boundary" excluded because `< to` is half-open by design.
+      expect(body.map((n) => n.content)).toEqual(["inside"]);
     });
 
-    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}`),
+    test("unsupported date-column operator (e.g. gt) rejects with a guiding error", async () => {
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[created_at][gt]=2026-01-01"),
         store,
-        `/n3/attachments/${att.id}`,
+        "",
       );
-      expect(first.status).toBe(204);
-      const second = await handleNotes(
-        mkReq("DELETE", `/notes/n3/attachments/${att.id}`),
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      // Error must call out the supported ops so callers can self-correct.
+      expect(body.error).toContain("gte");
+      expect(body.error).toContain("lt");
+    });
+
+    test("`meta[created_at]=…` (shorthand, no operator) rejects with a guiding error", async () => {
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[created_at]=2026-01-01"),
         store,
-        `/n3/attachments/${att.id}`,
+        "",
       );
-      expect(second.status).toBe(404);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("operator");
     });
 
-    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");
+    // ---- Mutually-exclusive shapes that would silently corrupt input ----
 
+    test("bracket-date filter spanning created_at AND updated_at in one request rejects (vault#289 F1)", async () => {
+      // Before this guard, the parser flattened both columns onto a single
+      // `dateBucket.field`, so the second column silently won and the first
+      // column's bound was applied against the wrong column.
       const res = await handleNotes(
-        mkReq("DELETE", `/notes/nb/attachments/${attA.id}`),
+        mkReq(
+          "GET",
+          "/notes?meta[created_at][gte]=2026-04-01&meta[updated_at][lt]=2026-06-01",
+        ),
         store,
-        `/nb/attachments/${attA.id}`,
+        "",
       );
-      expect(res.status).toBe(404);
-      expect((await store.getAttachments(a.id)).length).toBe(1);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("cannot span");
+      expect(body.error).toContain("created_at");
+      expect(body.error).toContain("updated_at");
     });
 
-    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");
+    test("two bracket-date params on the same column compose into a range (regression)", async () => {
+      // The F1 guard must reject *different* columns only — same-column
+      // gte+lt is the canonical range case and must keep working.
+      await store.createNote("in-window", { created_at: "2026-04-15T00:00:00.000Z" });
+      await store.createNote("after-window", { created_at: "2026-05-15T00:00:00.000Z" });
+      await store.createNote("before-window", { created_at: "2026-03-15T00:00:00.000Z" });
+      const res = await handleNotes(
+        mkReq(
+          "GET",
+          "/notes?meta[created_at][gte]=2026-04-01&meta[created_at][lt]=2026-05-01&include_content=true",
+        ),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["in-window"]);
+    });
 
-      await handleNotes(
-        mkReq("DELETE", `/notes/sa/attachments/${attA.id}`),
+    test("shorthand-then-operator on the same field rejects (vault#289 F2)", async () => {
+      // `URLSearchParams` iteration is insertion-order. Before this guard,
+      // shorthand wrote `metadata[field] = primitive`, then the operator
+      // handler called `metaOpBucket` which overwrote it with a fresh op
+      // object — the shorthand was silently dropped.
+      await declareIndexed();
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority]=5&meta[priority][gte]=3"),
         store,
-        `/sa/attachments/${attA.id}`,
-        "default",
+        "",
       );
-      expect(existsSync(filePath)).toBe(true);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("mix shorthand and operator");
+    });
 
-      await handleNotes(
-        mkReq("DELETE", `/notes/sb/attachments/${attB.id}`),
+    test("operator-then-shorthand on the same field rejects (vault#289 F2, reverse order)", async () => {
+      // Reverse insertion order. Before this guard, the operator was set
+      // first, then the shorthand wrote `metadata[field] = primitive` and
+      // clobbered the op bucket — operator silently dropped.
+      await declareIndexed();
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][gte]=3&meta[priority]=5"),
         store,
-        `/sb/attachments/${attB.id}`,
-        "default",
+        "",
       );
-      expect(existsSync(filePath)).toBe(false);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("mix shorthand and operator");
+    });
 
-      delete process.env.ASSETS_DIR;
+    test("`[]` array form on a non-array operator rejects at the parser layer (vault#289 F4)", async () => {
+      // `meta[field][eq][]=value` is a shape error — `eq` takes a scalar.
+      // The engine would also catch this (the value would be an array
+      // SQLite can't bind), but the parser-level error names the issue
+      // more precisely: "use single-value form for `eq`."
+      const res = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][eq][]=5"),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_OPERATOR_VALUE");
+      expect(body.error).toContain("array form");
+      expect(body.error).toContain("in");
+      expect(body.error).toContain("not_in");
     });
 
-    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");
+    // ---- Precedence on overlap ----
+    test("when both flat and bracket date params overlap, bracket wins", async () => {
+      await store.createNote("old", { created_at: "2026-01-15T00:00:00.000Z" });
+      await store.createNote("new", { created_at: "2026-04-15T00:00:00.000Z" });
+      // Bracket says "from 2026-04-01"; flat says "from 2020-01-01". If
+      // flat won, both notes would match. The bracket-wins precedence is
+      // verified by getting back only the post-April note.
       const res = await handleNotes(
-        mkReq("PATCH", `/notes/nm/attachments/${att.id}`),
+        mkReq(
+          "GET",
+          "/notes?meta[created_at][gte]=2026-04-01&date_field=created_at&date_from=2020-01-01&include_content=true",
+        ),
         store,
-        `/nm/attachments/${att.id}`,
+        "",
       );
-      expect(res.status).toBe(405);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["new"]);
     });
   });
 });
@@ -1352,6 +2606,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 +2709,80 @@ 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");
+  });
+
+  // ---- include_content response-shape opt-out (vault#285 friction point 2.response) ----
+  test("PATCH defaults to returning the full Note (back-compat)", async () => {
+    await store.createNote("body", { id: "x" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { content: "updated", force: true }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.content).toBe("updated");
+    expect(body.byteSize).toBeUndefined();
+    expect(body.preview).toBeUndefined();
+  });
+
+  test("PATCH with include_content: false returns the lean NoteIndex shape", async () => {
+    const longBody = "x".repeat(2_000);
+    await store.createNote(longBody, { id: "big", path: "big" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/big", { append: " edit", include_content: false }),
+      store,
+      "/big",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.content).toBeUndefined();
+    expect(typeof body.byteSize).toBe("number");
+    expect(body.byteSize).toBe(2_000 + 5);
+    expect(typeof body.preview).toBe("string");
+    expect(body.id).toBe("big");
+    expect(body.path).toBe("big");
+  });
 });
 
 describe("HTTP /tags", async () => {
@@ -1397,6 +2817,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" });
@@ -1416,7 +2851,7 @@ describe("HTTP /tags", async () => {
     );
     expect(res.status).toBe(200);
     const body = await res.json() as any;
-    expect(body).toEqual({ renamed: 2 });
+    expect(body).toMatchObject({ renamed: 2, sub_tags_renamed: 0 });
     expect((await store.getNote(n1.id))!.tags).toEqual(["memo"]);
     expect((await store.getNote(n2.id))!.tags?.sort()).toEqual(["keeper", "memo"]);
   });
@@ -1516,6 +2951,7 @@ describe("HTTP /tags", async () => {
   });
 });
 
+
 describe("HTTP /find-path", async () => {
   test("finds path between two notes", async () => {
     await store.createNote("a", { id: "a" });
@@ -1578,6 +3014,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 +3056,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 +3100,7 @@ describe("stateless MCP transport", async () => {
       permission: "read",
       scopes: ["vault:read"],
       legacyDerived: false,
+      scoped_tags: null,
     });
     expect(res.status).toBe(200);
 
@@ -1716,6 +3155,7 @@ describe("stateless MCP transport", async () => {
       permission: "read",
       scopes: ["vault:read"],
       legacyDerived: false,
+      scoped_tags: null,
     });
 
     expect(res.status).toBe(200);
@@ -1767,6 +3207,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 +3248,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 +3292,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);