@openparachute/vault 0.3.1 → 0.4.0

package/core/src/core.test.ts

@@ -136,6 +136,117 @@ describe("notes", async () => {
     await store.deleteNote("a");
     expect(await store.getLinks("b")).toHaveLength(0);
   });
+
+  // ---- PathConflictError: typed 409 on duplicate path (#126) ----
+
+  it("createNote throws PathConflictError when path is taken (#126)", async () => {
+    await store.createNote("First", { path: "Inbox/note" });
+    let caught: any;
+    try {
+      await store.createNote("Second", { path: "Inbox/note" });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeTruthy();
+    expect(caught.code).toBe("PATH_CONFLICT");
+    expect(caught.path).toBe("Inbox/note");
+  });
+
+  it("createNote on path collision does not insert the second note (#126)", async () => {
+    await store.createNote("First", { id: "a", path: "Inbox/note" });
+    try {
+      await store.createNote("Second", { id: "b", path: "Inbox/note" });
+    } catch {}
+    expect(await store.getNote("b")).toBeNull();
+  });
+
+  it("updateNote throws PathConflictError when renaming onto an existing path (#126)", async () => {
+    const a = await store.createNote("First", { path: "a" });
+    await store.createNote("Second", { path: "b" });
+    let caught: any;
+    try {
+      await store.updateNote(a.id, { path: "b", if_updated_at: a.createdAt });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeTruthy();
+    expect(caught.code).toBe("PATH_CONFLICT");
+    expect(caught.path).toBe("b");
+  });
+
+  it("updateNote with no path collision still succeeds (#126 — no false positives)", async () => {
+    const a = await store.createNote("First", { path: "a" });
+    await store.createNote("Second", { path: "b" });
+    const updated = await store.updateNote(a.id, { path: "c", if_updated_at: a.createdAt });
+    expect(updated.path).toBe("c");
+  });
+
+  it("updateNote with no path field is unaffected by the path-conflict guard (#126)", async () => {
+    const a = await store.createNote("First", { path: "a" });
+    const updated = await store.updateNote(a.id, { content: "edited", if_updated_at: a.createdAt });
+    expect(updated.content).toBe("edited");
+    expect(updated.path).toBe("a");
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty-note invariant at the Store boundary (#213)
+  // -------------------------------------------------------------------------
+
+  it("createNote rejects content+path both absent → EmptyNoteError", async () => {
+    await expect(store.createNote("")).rejects.toMatchObject({ code: "EMPTY_NOTE" });
+    await expect(store.createNote("   ")).rejects.toMatchObject({ code: "EMPTY_NOTE" });
+    await expect(store.createNote("", { metadata: { x: 1 } })).rejects.toMatchObject({
+      code: "EMPTY_NOTE",
+    });
+  });
+
+  it("createNote accepts content-only (un-pathed jot)", async () => {
+    const n = await store.createNote("just a jot");
+    expect(n.content).toBe("just a jot");
+    expect(n.path).toBeUndefined();
+  });
+
+  it("createNote accepts path-only (wikilink placeholder / _schemas/* shape)", async () => {
+    const n = await store.createNote("", { path: "wiki/placeholder" });
+    expect(n.content).toBe("");
+    expect(n.path).toBe("wiki/placeholder");
+  });
+
+  it("updateNote rejects clearing both content and path → EmptyNoteError", async () => {
+    const n = await store.createNote("body", { path: "p" });
+    await expect(
+      store.updateNote(n.id, { content: "", path: "", if_updated_at: n.createdAt }),
+    ).rejects.toMatchObject({ code: "EMPTY_NOTE", note_id: n.id });
+  });
+
+  it("updateNote rejects clearing content when path is already null", async () => {
+    const n = await store.createNote("body");
+    await expect(
+      store.updateNote(n.id, { content: "", if_updated_at: n.createdAt }),
+    ).rejects.toMatchObject({ code: "EMPTY_NOTE" });
+  });
+
+  it("updateNote allows clearing content when path is set (or being set)", async () => {
+    const n = await store.createNote("body", { path: "p" });
+    const updated = await store.updateNote(n.id, { content: "", if_updated_at: n.createdAt });
+    expect(updated.content).toBe("");
+    expect(updated.path).toBe("p");
+  });
+
+  it("updateNote with metadata-only update against a (legacy) empty row passes", async () => {
+    // Tag/metadata-only updates don't touch content or path, so they don't
+    // trigger the new guard — important so any pre-existing empty rows
+    // (from before #213) can still be cleaned up via metadata operations.
+    const n = await store.createNote("seed", { path: "x" });
+    // Simulate a legacy row by directly clearing content via SQL (bypasses
+    // the guard); this mirrors what an old data row could look like.
+    db.prepare("UPDATE notes SET content = '', path = NULL WHERE id = ?").run(n.id);
+    const updated = await store.updateNote(n.id, {
+      metadata: { tag: "cleanup" },
+      if_updated_at: n.createdAt,
+    });
+    expect(updated.metadata).toMatchObject({ tag: "cleanup" });
+  });
 });
 
 // ---- Backfill migration: legacy rows with NULL updated_at ----
@@ -476,12 +587,24 @@ describe("vault stats", async () => {
     const result = await store.getVaultStats();
     expect(result.totalNotes).toBe(2);
     expect(result.tagCount).toBe(2);
+    expect(result.attachmentCount).toBe(0);
     expect(result.topTags[0].tag).toBe("x");
     expect(result.topTags[0].count).toBe(2);
     expect(result.notesByMonth).toHaveLength(2);
     expect(result.earliestNote!.createdAt).toBe("2025-05-01T00:00:00.000Z");
     expect(result.latestNote!.createdAt).toBe("2025-06-01T00:00:00.000Z");
   });
+
+  it("getVaultStats counts attachments", async () => {
+    const n1 = await store.createNote("one");
+    const n2 = await store.createNote("two");
+    await store.addAttachment(n1.id, "/tmp/a1.mp3", "audio/mp3");
+    await store.addAttachment(n1.id, "/tmp/i1.png", "image/png");
+    await store.addAttachment(n2.id, "/tmp/a2.mp3", "audio/mp3");
+
+    const result = await store.getVaultStats();
+    expect(result.attachmentCount).toBe(3);
+  });
 });
 
 // ---- Query ----
@@ -534,6 +657,126 @@ describe("queryNotes", async () => {
     expect(results.length).toBeGreaterThan(0);
   });
 
+  // ---- Generalized date_filter (vault#215) ----
+  //
+  // The legacy `dateFrom` / `dateTo` always filter on `n.created_at` (vault
+  // ingestion time). The new `dateFilter: { field, from, to }` shape lets a
+  // caller filter on any *content* date — an email's received date, a
+  // meeting's scheduled date — by pointing `field` at an indexed metadata
+  // field. `field` defaults to `created_at`, in which case the SQL is
+  // identical to the legacy path.
+  describe("dateFilter (generalized)", () => {
+    async function declareEmailDate() {
+      const { declareField } = await import("./indexed-fields.js");
+      declareField(db, "email_date", "TEXT", "email");
+    }
+
+    it("dateFilter with no field defaults to created_at (matches the legacy shorthand)", async () => {
+      await store.createNote("A", { created_at: "2026-01-15T00:00:00.000Z" });
+      await store.createNote("B", { created_at: "2026-02-15T00:00:00.000Z" });
+      await store.createNote("C", { created_at: "2026-03-15T00:00:00.000Z" });
+
+      const results = await store.queryNotes({
+        dateFilter: { from: "2026-02-01", to: "2026-03-01" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["B"]);
+    });
+
+    it("dateFilter on an indexed metadata field filters on content date, not ingestion date", async () => {
+      await declareEmailDate();
+      // Ingestion order doesn't match email_date order — that's the whole
+      // point: the bug was that `dateFrom` returned rows by ingestion time.
+      await store.createNote("recently-synced old email", {
+        metadata: { email_date: "2025-12-01T00:00:00.000Z" },
+      });
+      await store.createNote("recently-synced new email", {
+        metadata: { email_date: "2026-04-25T00:00:00.000Z" },
+      });
+      await store.createNote("recently-synced ancient", {
+        metadata: { email_date: "2024-08-15T00:00:00.000Z" },
+      });
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "email_date", from: "2026-04-01", to: "2026-05-01" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["recently-synced new email"]);
+    });
+
+    it("dateFilter on a non-indexed field rejects with FIELD_NOT_INDEXED", async () => {
+      await store.createNote("X", { metadata: { meeting_date: "2026-04-25T00:00:00.000Z" } });
+      // Note: not declared via declareField, so the field has no generated
+      // column. The error mirrors the metadata-operator + order_by gate.
+      try {
+        await store.queryNotes({
+          dateFilter: { field: "meeting_date", from: "2026-04-01" },
+        });
+        throw new Error("expected QueryError");
+      } catch (err: any) {
+        expect(err.name).toBe("QueryError");
+        expect(err.code).toBe("FIELD_NOT_INDEXED");
+        expect(err.message).toContain("meeting_date");
+      }
+    });
+
+    it("dateFilter combined with top-level dateFrom rejects with INVALID_QUERY", async () => {
+      await declareEmailDate();
+      try {
+        await store.queryNotes({
+          dateFrom: "2026-01-01",
+          dateFilter: { field: "email_date", from: "2026-04-01" },
+        });
+        throw new Error("expected QueryError");
+      } catch (err: any) {
+        expect(err.name).toBe("QueryError");
+        expect(err.code).toBe("INVALID_QUERY");
+        expect(err.message).toMatch(/cannot combine/i);
+      }
+    });
+
+    it("dateFilter with only `from` is open-ended on the upper bound", async () => {
+      await declareEmailDate();
+      await store.createNote("old", { metadata: { email_date: "2025-01-01T00:00:00.000Z" } });
+      await store.createNote("middle", { metadata: { email_date: "2026-04-15T00:00:00.000Z" } });
+      await store.createNote("new", { metadata: { email_date: "2026-05-01T00:00:00.000Z" } });
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "email_date", from: "2026-04-01" },
+      });
+      expect(results.map((n) => n.content).sort()).toEqual(["middle", "new"]);
+    });
+
+    it("dateFilter with explicit field='created_at' routes to the legacy SQL path", async () => {
+      // The implicit-default case is covered above; this asserts the explicit
+      // form behaves identically — no indexed-field gate, same n.created_at SQL.
+      await store.createNote("A", { created_at: "2026-01-15T00:00:00.000Z" });
+      await store.createNote("B", { created_at: "2026-02-15T00:00:00.000Z" });
+      await store.createNote("C", { created_at: "2026-03-15T00:00:00.000Z" });
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "created_at", from: "2026-02-01", to: "2026-03-01" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["B"]);
+    });
+
+    it("query-notes accepts date_filter on an indexed metadata field (vault#215)", async () => {
+      await declareEmailDate();
+      await store.createNote("old email", {
+        metadata: { email_date: "2025-12-01T00:00:00.000Z" },
+      });
+      await store.createNote("recent email", {
+        metadata: { email_date: "2026-04-25T00:00:00.000Z" },
+      });
+
+      const tools = generateMcpTools(store);
+      const query = tools.find((t) => t.name === "query-notes")!;
+      const results = await query.execute({
+        date_filter: { field: "email_date", from: "2026-04-01", to: "2026-05-01" },
+        include_content: true,
+      }) as any[];
+      expect(results.map((n) => n.content)).toEqual(["recent email"]);
+    });
+  });
+
   it("sorts ascending and descending", async () => {
     await store.createNote("First", { id: "first" });
     await store.createNote("Second", { id: "second" });
@@ -907,7 +1150,7 @@ describe("attachments", async () => {
 // ---- MCP Tools ----
 
 describe("MCP tools", async () => {
-  it("generates all 9 consolidated tools", () => {
+  it("generates the consolidated tool set", () => {
     const tools = generateMcpTools(store);
     const names = tools.map((t) => t.name);
 
@@ -918,9 +1161,16 @@ describe("MCP tools", async () => {
     expect(names).toContain("list-tags");
     expect(names).toContain("update-tag");
     expect(names).toContain("delete-tag");
+    expect(names).toContain("list-note-schemas");
+    expect(names).toContain("update-note-schema");
+    expect(names).toContain("delete-note-schema");
+    expect(names).toContain("list-schema-mappings");
+    expect(names).toContain("set-schema-mapping");
+    expect(names).toContain("delete-schema-mapping");
     expect(names).toContain("find-path");
+    expect(names).toContain("synthesize-notes");
     expect(names).toContain("vault-info");
-    expect(tools).toHaveLength(9);
+    expect(tools).toHaveLength(16);
   });
 
   it("create-note tool works", async () => {
@@ -1267,6 +1517,276 @@ describe("MCP tools", async () => {
     expect((await store.getNote("source"))!.content).toBe("See [[People/Alice]] for details");
   });
 
+  it("update-note append concatenates to end without precondition", async () => {
+    const note = await store.createNote("first line\n", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // No if_updated_at and no force — append-only is precondition-exempt.
+    const result = await updateNote.execute({ id: note.id, append: "second line\n" }) as any;
+    expect(result.content).toBe("first line\nsecond line\n");
+
+    const persisted = await store.getNote(note.id);
+    expect(persisted!.content).toBe("first line\nsecond line\n");
+  });
+
+  it("update-note prepend concatenates to start without precondition", async () => {
+    const note = await store.createNote("body", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result = await updateNote.execute({ id: note.id, prepend: "header\n" }) as any;
+    expect(result.content).toBe("header\nbody");
+  });
+
+  it("update-note prepend on frontmatter-led content injects after closing --- (#203)", async () => {
+    const original = "---\ntitle: Foo\ntags: [bar]\n---\nbody line 1\n";
+    const note = await store.createNote(original, { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result = await updateNote.execute({ id: note.id, prepend: "preamble\n" }) as any;
+    // Frontmatter still at byte 0 — parsers expecting `---\n` will find it.
+    expect(result.content.startsWith("---\ntitle: Foo\ntags: [bar]\n---\n")).toBe(true);
+    // Prepend lands immediately after the closing fence, before the body.
+    expect(result.content).toBe(
+      "---\ntitle: Foo\ntags: [bar]\n---\npreamble\nbody line 1\n",
+    );
+  });
+
+  it("update-note prepend on content lacking frontmatter injects at byte 0", async () => {
+    const note = await store.createNote("# Heading\nbody\n", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result = await updateNote.execute({ id: note.id, prepend: "preamble\n" }) as any;
+    expect(result.content).toBe("preamble\n# Heading\nbody\n");
+  });
+
+  it("update-note append+prepend in one call lands both contributions", async () => {
+    const note = await store.createNote("middle", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result = await updateNote.execute({
+      id: note.id,
+      prepend: "[start] ",
+      append: " [end]",
+    }) as any;
+    expect(result.content).toBe("[start] middle [end]");
+  });
+
+  it("update-note rejects content + append in same call", async () => {
+    const note = await store.createNote("body", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({ id: note.id, content: "new", append: "more", force: true });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.message).toMatch(/mutually exclusive/);
+  });
+
+  it("update-note rejects content + content_edit in same call", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content: "replace",
+        content_edit: { old_text: "hello", new_text: "hi" },
+        force: true,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.message).toMatch(/mutually exclusive/);
+  });
+
+  it("update-note rejects append + content_edit in same call", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        append: " more",
+        content_edit: { old_text: "hello", new_text: "hi" },
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.message).toMatch(/mutually exclusive/);
+  });
+
+  it("update-note append still requires precondition when combined with other fields", async () => {
+    const note = await store.createNote("body", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // append + metadata is NOT precondition-exempt — metadata mutation
+    // can lose data on a stale read, so the safety gate stays in.
+    let err: any;
+    try {
+      await updateNote.execute({ id: note.id, append: " more", metadata: { x: 1 } });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("PRECONDITION_REQUIRED");
+  });
+
+  it("update-note append is atomic under concurrent calls — both lands", async () => {
+    const note = await store.createNote("seed:", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // Two concurrent appends. SQL-level concat means both contributions
+    // land — neither overwrites the other.
+    const results = await Promise.all([
+      updateNote.execute({ id: note.id, append: " A" }),
+      updateNote.execute({ id: note.id, append: " B" }),
+    ]);
+    expect(results).toHaveLength(2);
+
+    const persisted = await store.getNote(note.id);
+    // Final content is one of "seed: A B" or "seed: B A" — the order
+    // depends on which write got the lock first, but both contributions
+    // are present.
+    expect(persisted!.content === "seed: A B" || persisted!.content === "seed: B A").toBe(true);
+  });
+
+  it("update-note append updates updated_at and respects if_updated_at when supplied", async () => {
+    const note = await store.createNote("seed", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // With if_updated_at — succeeds because we're using the right token.
+    const ok = await updateNote.execute({ id: note.id, append: " A", if_updated_at: note.updatedAt }) as any;
+    expect(ok.content).toBe("seed A");
+    expect(ok.updatedAt).not.toBe(note.updatedAt);
+
+    // Stale token — conflict.
+    let err: any;
+    try {
+      await updateNote.execute({ id: note.id, append: " B", if_updated_at: note.updatedAt });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("CONFLICT");
+  });
+
+  it("update-note append parses new wikilinks introduced via append", async () => {
+    const target = await store.createNote("Alice's note", { id: "alice", path: "People/Alice" });
+    const source = await store.createNote("intro\n", { id: "src" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    await updateNote.execute({ id: source.id, append: "see [[People/Alice]]" });
+
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links.some((l) => l.targetId === target.id && l.relationship === "wikilink")).toBe(true);
+  });
+
+  it("update-note content_edit replaces a single occurrence", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result = await updateNote.execute({
+      id: note.id,
+      content_edit: { old_text: "hello", new_text: "hi" },
+      if_updated_at: note.updatedAt,
+    }) as any;
+    expect(result.content).toBe("hi world");
+  });
+
+  it("update-note content_edit errors when old_text is not found", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content_edit: { old_text: "missing", new_text: "x" },
+        if_updated_at: note.updatedAt,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.message).toMatch(/not found/);
+    // Note must be untouched.
+    const persisted = await store.getNote(note.id);
+    expect(persisted!.content).toBe("hello world");
+  });
+
+  it("update-note content_edit errors when old_text matches multiple times", async () => {
+    const note = await store.createNote("hello hello", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content_edit: { old_text: "hello", new_text: "hi" },
+        if_updated_at: note.updatedAt,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.message).toMatch(/matches multiple times|exactly once/);
+    const persisted = await store.getNote(note.id);
+    expect(persisted!.content).toBe("hello hello");
+  });
+
+  it("update-note content_edit requires precondition by default", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content_edit: { old_text: "hello", new_text: "hi" },
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("PRECONDITION_REQUIRED");
+  });
+
+  it("update-note content_edit conflicts when if_updated_at is stale", async () => {
+    const note = await store.createNote("hello world", { id: "n1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // Bump the note so a stale token will conflict at the SQL layer.
+    await updateNote.execute({ id: note.id, content: "hello world", force: true });
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content_edit: { old_text: "hello", new_text: "hi" },
+        if_updated_at: "2020-01-01T00:00:00.000Z",
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("CONFLICT");
+  });
+
   it("query-notes single note by id", async () => {
     const note = await store.createNote("Hello", { path: "test/note" });
     const tools = generateMcpTools(store);
@@ -1529,12 +2049,41 @@ describe("MCP tools", async () => {
     expect(result[0].id).toBe("near");
   });
 
-  it("delete-note accepts path", async () => {
-    await store.createNote("To delete", { path: "Temp/note" });
+  it("query-notes near returns neighborhood even when limit is small and unrelated notes were created first (#130)", async () => {
+    // Repro of #130: anchor + linked notes get crowded out by unrelated notes
+    // when the query runs ORDER BY created_at LIMIT 5 BEFORE the
+    // neighborhood filter. With the SQL-pushed ids filter, LIMIT applies to
+    // the neighborhood, not the whole notes table.
+    //
+    // Seed: 10 unrelated notes created first, THEN the anchor + 2 linked
+    // notes. With limit=5 and ORDER BY created_at ASC, the unrelated ten
+    // would fill the slate and the in-neighborhood notes would never appear.
+    for (let i = 0; i < 10; i++) {
+      await store.createNote(`Unrelated ${i}`, { id: `unrelated-${i}` });
+    }
+    await store.createNote("Anchor", { id: "anchor" });
+    await store.createNote("Outbound target", { id: "outbound" });
+    await store.createNote("Inbound source", { id: "inbound" });
+    await store.createLink("anchor", "outbound", "wikilink");
+    await store.createLink("inbound", "anchor", "wikilink");
+
     const tools = generateMcpTools(store);
-    const deleteTool = tools.find((t) => t.name === "delete-note")!;
-    const result = await deleteTool.execute({ id: "Temp/note" }) as any;
-    expect(result.deleted).toBe(true);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      near: { note_id: "anchor", depth: 2 },
+      limit: 5,
+    }) as any[];
+
+    const ids = result.map((n: any) => n.id).sort();
+    expect(ids).toEqual(["anchor", "inbound", "outbound"]);
+  });
+
+  it("delete-note accepts path", async () => {
+    await store.createNote("To delete", { path: "Temp/note" });
+    const tools = generateMcpTools(store);
+    const deleteTool = tools.find((t) => t.name === "delete-note")!;
+    const result = await deleteTool.execute({ id: "Temp/note" }) as any;
+    expect(result.deleted).toBe(true);
     expect(await store.getNoteByPath("Temp/note")).toBeNull();
   });
 
@@ -1656,6 +2205,183 @@ describe("MCP tools", async () => {
     expect(result.relationships).toEqual(["mentions", "related-to"]);
   });
 
+  // ---- synthesize-notes ----
+
+  it("synthesize-notes rejects when neither anchor nor query is supplied", async () => {
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({}) as any;
+    expect(result.error).toMatch(/at least one of `anchor` or `query`/);
+  });
+
+  it("synthesize-notes rejects an unknown anchor", async () => {
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "does-not-exist" }) as any;
+    expect(result.error).toMatch(/Anchor note not found/);
+  });
+
+  it("synthesize-notes returns anchor + linked neighbors ranked", async () => {
+    await store.createNote("Hub note", { id: "hub", tags: ["topic"] });
+    await store.createNote("Direct neighbor", { id: "n1" });
+    await store.createNote("Two-hop neighbor", { id: "n2" });
+    await store.createNote("Unrelated", { id: "u1" });
+    await store.createLink("hub", "n1", "mentions");
+    await store.createLink("n1", "n2", "mentions");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "hub", depth: 2 }) as any;
+
+    const ids = result.notes.map((n: any) => n.id);
+    expect(ids).toContain("hub");
+    expect(ids).toContain("n1");
+    expect(ids).toContain("n2");
+    expect(ids).not.toContain("u1");
+    // Anchor ranks first; one-hop beats two-hop.
+    expect(ids[0]).toBe("hub");
+    expect(ids.indexOf("n1")).toBeLessThan(ids.indexOf("n2"));
+    expect(result.notes[0].sources).toContain("anchor");
+    expect(result.notes[0].distance).toBe(0);
+    expect(result.topic.anchor).toEqual({ id: "hub", path: null });
+  });
+
+  it("synthesize-notes returns FTS hits when only query is supplied", async () => {
+    await store.createNote("Octopus thoughts: ink and color", { id: "o1" });
+    await store.createNote("Squid thoughts: deep blue", { id: "s1" });
+    await store.createNote("Recipe for octopus salad", { id: "o2" });
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ query: "octopus" }) as any;
+
+    const ids = result.notes.map((n: any) => n.id);
+    expect(ids).toContain("o1");
+    expect(ids).toContain("o2");
+    expect(ids).not.toContain("s1");
+    expect(result.notes[0].sources).toContain("search");
+    expect(result.notes[0]).toHaveProperty("fts_rank");
+    expect(result.topic.query).toBe("octopus");
+  });
+
+  it("synthesize-notes applies scope.tags filter (any-match)", async () => {
+    await store.createNote("Anchor", { id: "a" });
+    await store.createNote("Tagged neighbor", { id: "t1", tags: ["alpha"] });
+    await store.createNote("Other neighbor", { id: "t2", tags: ["beta"] });
+    await store.createLink("a", "t1", "mentions");
+    await store.createLink("a", "t2", "mentions");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "a", scope: { tags: ["alpha"] } }) as any;
+
+    const ids = result.notes.map((n: any) => n.id);
+    expect(ids).toContain("t1");
+    expect(ids).not.toContain("t2");
+    expect(ids).not.toContain("a"); // anchor itself has no tags
+  });
+
+  it("synthesize-notes applies scope.path prefix filter", async () => {
+    await store.createNote("Anchor", { id: "a" });
+    await store.createNote("In scope", { id: "p1", path: "Projects/Alpha/notes" });
+    await store.createNote("Out of scope", { id: "p2", path: "People/Bob" });
+    await store.createLink("a", "p1", "mentions");
+    await store.createLink("a", "p2", "mentions");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "a", scope: { path: "projects/" } }) as any;
+
+    const ids = result.notes.map((n: any) => n.id);
+    expect(ids).toContain("p1");
+    expect(ids).not.toContain("p2");
+  });
+
+  it("synthesize-notes respects limit and sets truncated flag", async () => {
+    await store.createNote("Anchor", { id: "anchor" });
+    for (let i = 0; i < 5; i++) {
+      await store.createNote(`Neighbor ${i}`, { id: `n${i}` });
+      await store.createLink("anchor", `n${i}`, "mentions");
+    }
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "anchor", limit: 3 }) as any;
+
+    expect(result.notes).toHaveLength(3);
+    expect(result.truncated).toBe(true);
+  });
+
+  it("synthesize-notes connections include only links between returned notes", async () => {
+    await store.createNote("Anchor", { id: "a" });
+    await store.createNote("In set", { id: "b" });
+    await store.createNote("Excluded", { id: "c" });
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("a", "c", "mentions");
+    await store.createLink("b", "c", "related-to");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "a", depth: 1, limit: 2 }) as any;
+
+    const ids = new Set(result.notes.map((n: any) => n.id));
+    for (const c of result.connections) {
+      expect(ids.has(c.source)).toBe(true);
+      expect(ids.has(c.target)).toBe(true);
+    }
+    expect(result.connections.some((c: any) => c.target === "c")).toBe(false);
+  });
+
+  it("synthesize-notes timeline orders oldest → newest", async () => {
+    await store.createNote("Old", { id: "old", created_at: "2024-01-01T00:00:00.000Z" });
+    await store.createNote("Mid", { id: "mid", created_at: "2025-01-01T00:00:00.000Z" });
+    await store.createNote("New", { id: "new", created_at: "2026-01-01T00:00:00.000Z" });
+    await store.createLink("new", "mid", "mentions");
+    await store.createLink("mid", "old", "mentions");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "new", depth: 2 }) as any;
+
+    const ids = result.timeline.map((t: any) => t.id);
+    expect(ids).toEqual(["old", "mid", "new"]);
+  });
+
+  it("synthesize-notes tag distribution counts tags across results", async () => {
+    await store.createNote("Anchor", { id: "a", tags: ["alpha", "beta"] });
+    await store.createNote("N1", { id: "n1", tags: ["alpha"] });
+    await store.createNote("N2", { id: "n2", tags: ["alpha", "gamma"] });
+    await store.createLink("a", "n1", "mentions");
+    await store.createLink("a", "n2", "mentions");
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+    const result = await synth.execute({ anchor: "a" }) as any;
+
+    const tagMap = new Map(result.tags.map((t: any) => [t.name, t.count]));
+    expect(tagMap.get("alpha")).toBe(3);
+    expect(tagMap.get("beta")).toBe(1);
+    expect(tagMap.get("gamma")).toBe(1);
+    expect(result.tags[0].name).toBe("alpha");
+  });
+
+  it("synthesize-notes include_content controls snippet vs full body", async () => {
+    const longBody = "x".repeat(500);
+    await store.createNote(longBody, { id: "long", path: "Long" });
+
+    const tools = generateMcpTools(store);
+    const synth = tools.find((t) => t.name === "synthesize-notes")!;
+
+    const snippetResult = await synth.execute({ anchor: "long" }) as any;
+    expect(snippetResult.notes[0]).toHaveProperty("snippet");
+    expect(snippetResult.notes[0]).not.toHaveProperty("content");
+    expect(snippetResult.notes[0].snippet.length).toBeLessThanOrEqual(200);
+
+    const fullResult = await synth.execute({ anchor: "long", include_content: true }) as any;
+    expect(fullResult.notes[0].content).toBe(longBody);
+    expect(fullResult.notes[0]).not.toHaveProperty("snippet");
+  });
+
   it("create-note via store triggers wikilink sync", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -1688,6 +2414,315 @@ describe("MCP tools", async () => {
     expect(fresh.metadata.priority).toBe(0);
     expect(fresh.metadata.status).toBe("active");
   });
+
+  // ---- query-notes input-shape tolerance (vault#214) ----
+  //
+  // The MCP framework drops top-level keys not in the inputSchema without
+  // raising — so an LLM caller passing the wrong field name gets a silent
+  // no-op rather than an error. We accept canonical + camelCase + singular
+  // aliases so the most common LLM mistakes still apply the filter, and
+  // we mirror the `tag` param's string-or-array shape so a single excluded
+  // tag doesn't need a wrapping array.
+
+  it("query-notes accepts `excludeTags` (camelCase alias)", async () => {
+    await store.createNote("a", { tags: ["email"] });
+    await store.createNote("b", { tags: ["email", "urgent"] });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ tag: "email", excludeTags: ["urgent"], include_content: true }) as any[];
+    expect(r).toHaveLength(1);
+    expect(r[0].content).toBe("a");
+  });
+
+  it("query-notes accepts `exclude_tag` (singular alias)", async () => {
+    await store.createNote("a", { tags: ["email"] });
+    await store.createNote("b", { tags: ["email", "urgent"] });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ tag: "email", exclude_tag: "urgent", include_content: true }) as any[];
+    expect(r).toHaveLength(1);
+    expect(r[0].content).toBe("a");
+  });
+
+  it("query-notes `exclude_tags` accepts a single string (mirrors `tag`)", async () => {
+    await store.createNote("a", { tags: ["email"] });
+    await store.createNote("b", { tags: ["email", "urgent"] });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ tag: "email", exclude_tags: "urgent", include_content: true }) as any[];
+    expect(r).toHaveLength(1);
+    expect(r[0].content).toBe("a");
+  });
+
+  it("query-notes canonical `exclude_tags: [...]` still works (regression)", async () => {
+    await store.createNote("a", { tags: ["email"] });
+    await store.createNote("b", { tags: ["email", "urgent"] });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ tag: "email", exclude_tags: ["urgent"], include_content: true }) as any[];
+    expect(r).toHaveLength(1);
+    expect(r[0].content).toBe("a");
+  });
+
+  it("query-notes routes through store.queryNotes so tag-hierarchy expansion fires", async () => {
+    // `voice` and `text` declare "manual" as their parent via the v14
+    // tags.parent_names column. A query for `tag: "manual"` should match
+    // notes tagged with either child — that expansion only happens when
+    // the call goes through `store.queryNotes`, not `noteOps.queryNotes`
+    // directly.
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.upsertTagRecord("text", { parent_names: ["manual"] });
+    await store.createNote("voice memo", { tags: ["voice"] });
+    await store.createNote("text memo", { tags: ["text"] });
+    await store.createNote("unrelated", { tags: ["other"] });
+
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ tag: "manual", include_content: true }) as any[];
+    expect(r).toHaveLength(2);
+    expect(r.map((n) => n.content).sort()).toEqual(["text memo", "voice memo"]);
+  });
+
+  it("query-notes FTS path routes through store.searchNotes so tag-hierarchy expansion fires (vault#227)", async () => {
+    // Same fixture shape as the structured-query hierarchy test above, but
+    // exercising the search branch. Pre-fix the FTS path called
+    // `noteOps.searchNotes` directly and silently dropped descendant matches —
+    // `tag: "manual"` would only return notes literally tagged #manual, not
+    // notes tagged with the declared children #voice / #text.
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.upsertTagRecord("text", { parent_names: ["manual"] });
+    await store.createNote("voice handoff notes", { tags: ["voice"] });
+    await store.createNote("text handoff notes", { tags: ["text"] });
+    await store.createNote("unrelated handoff", { tags: ["other"] });
+
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({ search: "handoff", tag: "manual", include_content: true }) as any[];
+    expect(r).toHaveLength(2);
+    expect(r.map((n) => n.content).sort()).toEqual(["text handoff notes", "voice handoff notes"]);
+    expect(r.map((n) => n.content)).not.toContain("unrelated handoff");
+  });
+
+  it("query-notes does not mutate caller's params object across repeated calls", async () => {
+    // normalizeTags returns a defensive copy of array inputs so the downstream
+    // store layer can sort/dedupe without touching the caller's reference.
+    // Without the copy, a caller reusing the same params object would see its
+    // exclude_tags array reordered (or worse) on the second call.
+    await store.createNote("a", { tags: ["email"] });
+    await store.createNote("b", { tags: ["email", "urgent"] });
+    await store.createNote("c", { tags: ["email", "spam"] });
+
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const params = { tag: "email", exclude_tags: ["urgent", "spam"], include_content: true };
+
+    const r1 = await queryNotes.execute(params) as any[];
+    expect(params.exclude_tags).toEqual(["urgent", "spam"]);
+
+    const r2 = await queryNotes.execute(params) as any[];
+    expect(params.exclude_tags).toEqual(["urgent", "spam"]);
+
+    expect(r1.map((n) => n.content).sort()).toEqual(["a"]);
+    expect(r2.map((n) => n.content).sort()).toEqual(["a"]);
+  });
+
+  // ---- empty-note + batch-cap MCP regressions (#213) ----
+
+  it("create-note rejects bare empty content with no path (EMPTY_NOTE)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    let err: any;
+    try {
+      await createNote.execute({ content: "" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("EMPTY_NOTE");
+  });
+
+  it("create-note batch rejects when any entry is empty content + no path (atomic, with item_index)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const beforeCount = (await store.queryNotes({ search: "atomic-marker" })).length;
+    let err: any;
+    try {
+      await createNote.execute({
+        notes: [
+          { content: "atomic-marker first" },
+          { content: "" },
+        ],
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("EMPTY_NOTE");
+    // The first item must NOT have been created — pre-validation rolls
+    // the whole batch back atomically. Partial-create would leak prefixes
+    // on every runaway-client burst (#213).
+    const afterCount = (await store.queryNotes({ search: "atomic-marker" })).length;
+    expect(afterCount).toBe(beforeCount);
+    // Parity with HTTP route: MCP callers with multi-item batches need to
+    // know which entry triggered the rejection. The bad entry is at index 1.
+    expect(err.item_index).toBe(1);
+  });
+
+  it("create-note single empty has null item_index (not a batch position)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    let err: any;
+    try {
+      await createNote.execute({ content: "" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("EMPTY_NOTE");
+    // Single-call (no `notes` array) — there's no batch position to report.
+    expect(err.item_index).toBeNull();
+  });
+
+  it("create-note batch over MAX_BATCH_SIZE rejects with BATCH_TOO_LARGE", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const notes = Array.from({ length: 501 }, (_, i) => ({ content: `n${i}` }));
+    let err: any;
+    try {
+      await createNote.execute({ notes });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("BATCH_TOO_LARGE");
+    expect(err.limit).toBe(500);
+    expect(err.got).toBe(501);
+  });
+
+  it("update-note batch over MAX_BATCH_SIZE rejects with BATCH_TOO_LARGE", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const notes = Array.from({ length: 501 }, (_, i) => ({
+      id: `id${i}`,
+      content: "x",
+      force: true,
+    }));
+    let err: any;
+    try {
+      await updateNote.execute({ notes });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("BATCH_TOO_LARGE");
+    expect(err.limit).toBe(500);
+    expect(err.got).toBe(501);
+  });
+
+  it("create-note batch where mid-item triggers PATH_CONFLICT rolls back prefix items (#236)", async () => {
+    // The empty-note pre-walk (#213) catches `{}` before any DB write; a
+    // path-conflict can only surface on the actual INSERT, mid-loop. Without
+    // the BEGIN/COMMIT wrap the prefix items would have already landed.
+    await store.createNote("seed", { path: "taken-236" });
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const beforeIds = (await store.queryNotes({})).map((n) => n.id).sort();
+
+    let err: any;
+    try {
+      await createNote.execute({
+        notes: [
+          { content: "ok-1", path: "fresh-236-1" },
+          { content: "ok-2", path: "fresh-236-2" },
+          { content: "boom", path: "taken-236" },
+        ],
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeTruthy();
+
+    // 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-236-1" })).toHaveLength(0);
+    expect(await store.queryNotes({ path: "fresh-236-2" })).toHaveLength(0);
+  });
+
+  it("update-note batch rolls back prefix tag mutation when a later item path-conflicts (#236)", async () => {
+    await store.createNote("A", { id: "a236" });
+    await store.createNote("B", { id: "b236" });
+    await store.createNote("C", { id: "c236", path: "occupied-236" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const aBefore = await store.getNote("a236");
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        notes: [
+          // Item 0 mutates a236's content + adds a tag. force=true skips
+          // the if_updated_at precondition.
+          { id: "a236", content: "A mutated", force: true, tags: { add: ["should-rollback"] } },
+          // Item 1 tries to take a path already owned by c236 — PATH_CONFLICT.
+          { id: "b236", path: "occupied-236", force: true },
+        ],
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("PATH_CONFLICT");
+
+    // Item 0's tag-add + content change must be rolled back — the batch
+    // transaction reverted them when item 1 path-conflicted (#236).
+    const aAfter = await store.getNote("a236");
+    expect(aAfter!.content).toBe(aBefore!.content);
+    expect(aAfter!.tags ?? []).not.toContain("should-rollback");
+  });
+
+  it("update-note batch rolls back prefix mutation when a later item if_updated_at-conflicts (#261)", async () => {
+    // The companion to the PATH_CONFLICT test above. Item 1's stale
+    // `if_updated_at` must surface as a ConflictError so the batch's
+    // BEGIN/COMMIT wrap can roll back item 0's mutation.
+    //
+    // Pre-fix (vault#261): `noteOps.updateNote` checked `res.changes === 0`
+    // to detect the precondition miss. Inside this multi-statement batch
+    // transaction, `.changes` reported a stale non-zero value from prior
+    // writes, so the conflict was silently missed and item 0's mutation
+    // committed with item 1 ignored.
+    //
+    // Post-fix: the conditional UPDATE uses `RETURNING id` and detects the
+    // miss directly from row presence. ConflictError fires; batch rolls back.
+    //
+    // Standalone bun:sqlite repro is pending — six attempted reductions
+    // (basic txn, async/microtask, prepared-statement reuse, mcp-loop
+    // mirror, hook-dispatch mirror, syncWikilinks-style writes) failed to
+    // hit the .changes-stale path outside the full BunStore plumbing. The
+    // bug surfaces only through `BunStore.updateNote` → hook dispatch.
+    // See vault#261 for the audit trail.
+    await store.createNote("A", { id: "a261" });
+    await store.createNote("B", { id: "b261" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const aBefore = await store.getNote("a261");
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        notes: [
+          // Item 0 mutates a261's content + adds a tag (force, no precondition).
+          { id: "a261", content: "A mutated", force: true, tags: { add: ["should-rollback"] } },
+          // Item 1 has a stale if_updated_at on b261 — should ConflictError.
+          { id: "b261", content: "B should-not-land", if_updated_at: "2020-01-01T00:00:00.000Z" },
+        ],
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("CONFLICT");
+
+    // Item 0's tag-add + content change must be rolled back.
+    const aAfter = await store.getNote("a261");
+    expect(aAfter!.content).toBe(aBefore!.content);
+    expect(aAfter!.tags ?? []).not.toContain("should-rollback");
+  });
 });
 
 // ---- query-notes link expansion ----
@@ -1978,3 +3013,1213 @@ describe("query-notes link expansion", async () => {
     expect(result.content).not.toContain("unsummarized body");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tag hierarchy via tags.parent_names (post-v14, patterns/tag-data-model.md)
+// ---------------------------------------------------------------------------
+
+describe("tag hierarchy (tags.parent_names)", async () => {
+  it("query for parent tag returns notes tagged with declared child", async () => {
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("voice note", { tags: ["voice"] });
+    await store.createNote("text note", { tags: ["text"] });
+
+    const results = await store.queryNotes({ tags: ["manual"] });
+    expect(results.length).toBe(1);
+    expect(results[0]!.content).toBe("voice note");
+  });
+
+  it("expands transitively across multiple levels", async () => {
+    await store.upsertTagRecord("manual", { parent_names: ["note"] });
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("voice note", { tags: ["voice"] });
+    await store.createNote("manual-only note", { tags: ["manual"] });
+    await store.createNote("note-only note", { tags: ["note"] });
+
+    // #note matches all three (note + manual + voice).
+    const noteResults = await store.queryNotes({ tags: ["note"] });
+    expect(noteResults.length).toBe(3);
+
+    // #manual matches voice + manual-only, not note-only.
+    const manualResults = await store.queryNotes({ tags: ["manual"] });
+    expect(manualResults.map((n) => n.content).sort()).toEqual([
+      "manual-only note",
+      "voice note",
+    ]);
+  });
+
+  it("query for child does not match parent-tagged notes", async () => {
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("voice note", { tags: ["voice"] });
+    await store.createNote("manual-only note", { tags: ["manual"] });
+
+    const results = await store.queryNotes({ tags: ["voice"] });
+    expect(results.length).toBe(1);
+    expect(results[0]!.content).toBe("voice note");
+  });
+
+  it("supports multiple parents (diamond inheritance)", async () => {
+    await store.upsertTagRecord("voice-meeting", { parent_names: ["voice", "meeting"] });
+    await store.createNote("vm", { tags: ["voice-meeting"] });
+    await store.createNote("v", { tags: ["voice"] });
+    await store.createNote("m", { tags: ["meeting"] });
+
+    expect((await store.queryNotes({ tags: ["voice"] })).length).toBe(2); // v + vm
+    expect((await store.queryNotes({ tags: ["meeting"] })).length).toBe(2); // m + vm
+  });
+
+  it("hierarchy is invalidated when parent_names is set", async () => {
+    await store.createNote("voice note", { tags: ["voice"] });
+    // Before the parents are declared, #manual matches nothing.
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+
+    // After upsert, the cache invalidates and the next query expands.
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+  });
+
+  it("hierarchy is invalidated when parent_names is repointed", async () => {
+    await store.createNote("voice note", { tags: ["voice"] });
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+
+    // Repoint the parent.
+    await store.upsertTagRecord("voice", { parent_names: ["audio"] });
+
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+    expect((await store.queryNotes({ tags: ["audio"] })).length).toBe(1);
+  });
+
+  it("hierarchy is invalidated when parent_names is cleared", async () => {
+    await store.createNote("voice note", { tags: ["voice"] });
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+
+    await store.upsertTagRecord("voice", { parent_names: null });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+  });
+
+  it("hierarchy is invalidated when a parent tag is deleted", async () => {
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("voice note", { tags: ["voice"] });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+
+    // Drop the child tag — the row holding the parent_names declaration
+    // disappears, so the hierarchy edge goes with it.
+    await store.deleteTag("voice");
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+  });
+
+  it("tagMatch=any flattens all expansions across input tags", async () => {
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("v", { tags: ["voice"] });
+    await store.createNote("p", { tags: ["project"] });
+    await store.createNote("o", { tags: ["other"] });
+
+    const results = await store.queryNotes({
+      tags: ["manual", "project"],
+      tagMatch: "any",
+    });
+    expect(results.map((n) => n.content).sort()).toEqual(["p", "v"]);
+  });
+
+  it("tagMatch=all (default) requires each input tag's expanded set to be present", async () => {
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    // Note has both #voice (which satisfies #manual via expansion) AND #project.
+    await store.createNote("vp", { tags: ["voice", "project"] });
+    await store.createNote("p-only", { tags: ["project"] });
+
+    const results = await store.queryNotes({
+      tags: ["manual", "project"], // default tagMatch=all
+    });
+    expect(results.length).toBe(1);
+    expect(results[0]!.content).toBe("vp");
+  });
+
+  it("tolerates a cycle without infinite-looping", async () => {
+    await store.upsertTagRecord("a", { parent_names: ["b"] });
+    await store.upsertTagRecord("b", { parent_names: ["a"] });
+    await store.createNote("note-a", { tags: ["a"] });
+
+    // Both a and b should resolve without hanging; both reach the same set {a, b}.
+    expect((await store.queryNotes({ tags: ["a"] })).length).toBe(1);
+    expect((await store.queryNotes({ tags: ["b"] })).length).toBe(1);
+  });
+
+  it("malformed parent_names JSON is ignored silently", async () => {
+    // Stuff a malformed value into the column directly to simulate an
+    // out-of-band write. The resolver should drop it without throwing.
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    (store as any).db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?")
+      .run("not valid json {{{", "voice");
+    // Force cache reload.
+    (store as any)._tagHierarchy = null;
+    await store.createNote("v", { tags: ["voice"] });
+
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+    expect((await store.queryNotes({ tags: ["voice"] })).length).toBe(1);
+  });
+
+  it("a tag with no parent_names is a hierarchy no-op", async () => {
+    await store.upsertTagRecord("voice", { description: "voice notes" });
+    await store.createNote("v", { tags: ["voice"] });
+    await store.createNote("m", { tags: ["manual"] });
+
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+    expect((await store.queryNotes({ tags: ["voice"] })).length).toBe(1);
+  });
+
+  it("legacy `_tags/<name>` notes left in place do not affect the hierarchy", async () => {
+    // Post-v14, the resolver reads tags.parent_names — not notes. A leftover
+    // `_tags/*` note from a pre-v14 vault is harmless historical record.
+    await store.createNote("legacy", {
+      path: "_tags/voice",
+      metadata: { parents: ["manual"] },
+    });
+    await store.createNote("voice note", { tags: ["voice"] });
+
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Note schemas — table-driven (post-v15: `note_schemas` + `schema_mappings`)
+// ---------------------------------------------------------------------------
+// Originally written against the `_schemas/<name>` + `_schema_defaults`
+// notes-as-config convention (issue #177). Rewritten for vault#246: the
+// authoring surface is now `store.upsertNoteSchema` + `store.setSchemaMapping`
+// and the legacy notes are inert (left in place as audit trail).
+
+describe("note schemas (note_schemas + schema_mappings)", async () => {
+  it("returns no validation_status when no schemas are configured", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "plain note" }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("attaches validation_status when a schema matches by tag", async () => {
+    await store.upsertNoteSchema("task", {
+      description: "A task",
+      fields: { priority: { type: "string", enum: ["high", "medium", "low"] } },
+      required: ["priority"],
+    });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "do thing", tags: ["task"] }) as any;
+
+    expect(result.validation_status).toBeTruthy();
+    expect(result.validation_status.schemas).toEqual(["task"]);
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("missing_required");
+    expect(result.validation_status.warnings[0].field).toBe("priority");
+  });
+
+  it("attaches validation_status when a schema matches by path prefix", async () => {
+    await store.upsertNoteSchema("journal-entry", {
+      fields: { mood: { type: "string" } },
+      required: ["mood"],
+    });
+    await store.setSchemaMapping("journal-entry", "path_prefix", "journal/");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "today", path: "journal/2026-04-29" }) as any;
+
+    expect(result.validation_status.schemas).toEqual(["journal-entry"]);
+    expect(result.validation_status.warnings[0].reason).toBe("missing_required");
+  });
+
+  it("validation passes (empty warnings) when required fields are present and types match", async () => {
+    await store.upsertNoteSchema("task", {
+      fields: {
+        priority: { type: "string", enum: ["high", "medium", "low"] },
+        done: { type: "boolean" },
+      },
+      required: ["priority"],
+    });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "ok",
+      tags: ["task"],
+      metadata: { priority: "high", done: false },
+    }) as any;
+
+    expect(result.validation_status.schemas).toEqual(["task"]);
+    expect(result.validation_status.warnings).toEqual([]);
+  });
+
+  it("type_mismatch warning when a field's value is the wrong type", async () => {
+    await store.upsertNoteSchema("task", {
+      fields: { priority: { type: "string" }, done: { type: "boolean" } },
+    });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "high", done: "yes" }, // wrong: should be boolean
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(result.validation_status.warnings[0].field).toBe("done");
+  });
+
+  it("enum_mismatch warning when a field's value is outside the declared enum", async () => {
+    await store.upsertNoteSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "medium", "low"] } },
+    });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "ULTRA" },
+    }) as any;
+
+    expect(result.validation_status.warnings[0].reason).toBe("enum_mismatch");
+  });
+
+  it("validation never blocks the write — note exists with warnings attached", async () => {
+    await store.upsertNoteSchema("task", { required: ["priority"] });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "x", tags: ["task"] }) as any;
+
+    expect(result.id).toBeTruthy();
+    expect(result.validation_status.warnings.length).toBe(1);
+
+    const fetched = await store.getNote(result.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.content).toBe("x");
+  });
+
+  it("update-note also surfaces validation_status", async () => {
+    await store.upsertNoteSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      required: ["priority"],
+    });
+    await store.setSchemaMapping("task", "tag", "task");
+    const note = await store.createNote("body", { tags: ["task"], metadata: { priority: "high" } });
+
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: note.id,
+      metadata: { priority: "ULTRA" },
+      if_updated_at: note.updatedAt,
+    }) as any;
+
+    expect(result.validation_status.warnings[0].reason).toBe("enum_mismatch");
+  });
+
+  it("cache invalidates when a schema mapping is removed", async () => {
+    await store.upsertNoteSchema("task", { required: ["a"] });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({ content: "x", tags: ["task"] }) as any;
+    expect(result.validation_status.warnings[0].field).toBe("a");
+
+    await store.deleteSchemaMapping("task", "tag", "task");
+
+    result = await create.execute({ content: "y", tags: ["task"] }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("cache invalidates when a schema is updated", async () => {
+    await store.upsertNoteSchema("task", { required: ["a"] });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({ content: "x", tags: ["task"] }) as any;
+    expect(result.validation_status.warnings[0].field).toBe("a");
+
+    // Re-declare with a different required field; cache must reflect the change.
+    await store.upsertNoteSchema("task", { required: ["b"] });
+    result = await create.execute({ content: "y", tags: ["task"] }) as any;
+    expect(result.validation_status.warnings[0].field).toBe("b");
+  });
+
+  it("cache invalidates when a schema is deleted (cascades mappings)", async () => {
+    await store.upsertNoteSchema("task", { required: ["a"] });
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({ content: "x", tags: ["task"] }) as any;
+    expect(result.validation_status.warnings[0].field).toBe("a");
+
+    await store.deleteNoteSchema("task");
+    // FK CASCADE drops the mapping too.
+    expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
+
+    result = await create.execute({ content: "y", tags: ["task"] }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("longest path prefix wins when multiple match", async () => {
+    await store.upsertNoteSchema("journal-day", { required: ["mood"] });
+    await store.upsertNoteSchema("journal-broad", { required: ["topic"] });
+    await store.setSchemaMapping("journal-broad", "path_prefix", "journal/");
+    await store.setSchemaMapping("journal-day", "path_prefix", "journal/2026/");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "x", path: "journal/2026/april" }) as any;
+    expect(result.validation_status.schemas).toEqual(["journal-day"]);
+  });
+
+  it("multiple schemas can apply (path + tag combine warnings)", async () => {
+    await store.upsertNoteSchema("journal-entry", { required: ["mood"] });
+    await store.upsertNoteSchema("task", { required: ["priority"] });
+    await store.setSchemaMapping("journal-entry", "path_prefix", "journal/");
+    await store.setSchemaMapping("task", "tag", "task");
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      path: "journal/today",
+      tags: ["task"],
+    }) as any;
+
+    expect(result.validation_status.schemas.sort()).toEqual(["journal-entry", "task"]);
+    expect(result.validation_status.warnings.length).toBe(2);
+  });
+
+  it("a schema with no mappings is harmless (no validation)", async () => {
+    await store.upsertNoteSchema("orphan", { required: ["x"] });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "anything" }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("legacy `_schemas/<name>` notes are inert post-v15", async () => {
+    // The notes still write/read fine — they're just no longer interpreted
+    // as schema config. Nothing in note_schemas/schema_mappings → no validation.
+    await store.createNote("", {
+      path: "_schemas/task",
+      metadata: { required: ["priority"] },
+    });
+    await store.createNote("", {
+      path: "_schema_defaults",
+      metadata: { tags: { task: "task" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "x", tags: ["task"] }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// note_schemas + schema_mappings — direct CRUD (vault#246)
+// ---------------------------------------------------------------------------
+
+describe("note_schemas / schema_mappings CRUD", async () => {
+  it("upsertNoteSchema partial-merge: undefined preserves, null clears", async () => {
+    await store.upsertNoteSchema("task", {
+      description: "A task",
+      fields: { priority: { type: "string" } },
+      required: ["priority"],
+    });
+
+    // description omitted → preserved
+    await store.upsertNoteSchema("task", { required: ["priority", "due"] });
+    let row = await store.getNoteSchema("task");
+    expect(row?.description).toBe("A task");
+    expect(row?.required).toEqual(["priority", "due"]);
+
+    // description null → cleared
+    await store.upsertNoteSchema("task", { description: null });
+    row = await store.getNoteSchema("task");
+    expect(row?.description).toBeNull();
+    expect(row?.required).toEqual(["priority", "due"]); // still preserved
+  });
+
+  it("empty `required: []` collapses to null", async () => {
+    await store.upsertNoteSchema("task", { required: ["a", "b"] });
+    await store.upsertNoteSchema("task", { required: [] });
+    const row = await store.getNoteSchema("task");
+    expect(row?.required).toBeNull();
+  });
+
+  it("setSchemaMapping is idempotent (composite PK)", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    await store.setSchemaMapping("task", "tag", "task"); // re-set same triple
+    const mappings = await store.listSchemaMappings({ schema_name: "task" });
+    expect(mappings.length).toBe(1);
+  });
+
+  it("setSchemaMapping rejects unknown match_kind", async () => {
+    await store.upsertNoteSchema("task", {});
+    await expect(
+      store.setSchemaMapping("task", "BOGUS" as any, "task"),
+    ).rejects.toThrow(/match_kind/);
+  });
+
+  it("setSchemaMapping fails (FK) when schema doesn't exist", async () => {
+    await expect(
+      store.setSchemaMapping("missing", "tag", "x"),
+    ).rejects.toThrow();
+  });
+
+  it("deleteNoteSchema cascades schema_mappings (FK ON DELETE CASCADE)", async () => {
+    await store.upsertNoteSchema("task", {});
+    await store.setSchemaMapping("task", "tag", "task");
+    await store.setSchemaMapping("task", "path_prefix", "Tasks/");
+    expect((await store.listSchemaMappings({ schema_name: "task" })).length).toBe(2);
+
+    expect(await store.deleteNoteSchema("task")).toBe(true);
+    expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
+    expect(await store.deleteNoteSchema("task")).toBe(false); // already gone
+  });
+
+  it("listSchemaMappings filters by schema_name and match_kind", async () => {
+    await store.upsertNoteSchema("a", {});
+    await store.upsertNoteSchema("b", {});
+    await store.setSchemaMapping("a", "tag", "a-tag");
+    await store.setSchemaMapping("a", "path_prefix", "A/");
+    await store.setSchemaMapping("b", "tag", "b-tag");
+
+    expect((await store.listSchemaMappings({ schema_name: "a" })).length).toBe(2);
+    expect((await store.listSchemaMappings({ match_kind: "tag" })).length).toBe(2);
+    expect((await store.listSchemaMappings({ schema_name: "a", match_kind: "tag" })).length).toBe(1);
+  });
+});
+
+describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-tokens.md)", async () => {
+  it("returns the union of root + every descendant per tags.parent_names", async () => {
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.upsertTagRecord("health/food/breakfast", { parent_names: ["health/food"] });
+    await store.upsertTagRecord("work", { description: "work things" });
+
+    const expanded = await store.expandTagsWithDescendants(["health"]);
+    expect(expanded.has("health")).toBe(true);
+    expect(expanded.has("health/food")).toBe(true);
+    expect(expanded.has("health/food/breakfast")).toBe(true);
+    expect(expanded.has("work")).toBe(false);
+  });
+
+  it("returns an empty set for an empty input (no allowlist = nothing to expand)", async () => {
+    const expanded = await store.expandTagsWithDescendants([]);
+    expect(expanded.size).toBe(0);
+  });
+
+  it("includes the root verbatim even when the tag has no declared descendants", async () => {
+    await store.createNote("solo", { tags: ["loner"] });
+    const expanded = await store.expandTagsWithDescendants(["loner"]);
+    expect([...expanded]).toEqual(["loner"]);
+  });
+
+  it("unions descendants from multiple roots", async () => {
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.upsertTagRecord("work/standup", { parent_names: ["work"] });
+    const expanded = await store.expandTagsWithDescendants(["health", "work"]);
+    expect(expanded.has("health")).toBe(true);
+    expect(expanded.has("health/food")).toBe(true);
+    expect(expanded.has("work")).toBe(true);
+    expect(expanded.has("work/standup")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tag record API — patterns/tag-data-model.md
+// ---------------------------------------------------------------------------
+
+describe("tag record API (patterns/tag-data-model.md)", async () => {
+  it("upsertTagRecord persists description + fields + relationships + parent_names", async () => {
+    await store.upsertTagRecord("project", {
+      description: "long-running deliverable",
+      fields: { status: { type: "string", enum: ["active", "shipped"] } },
+      relationships: {
+        owned_by: { target_tag: "person", cardinality: "one", description: "DRI" },
+      },
+      parent_names: ["work"],
+    });
+    const r = await store.getTagRecord("project");
+    expect(r?.description).toBe("long-running deliverable");
+    expect(r?.fields?.status?.type).toBe("string");
+    expect(r?.relationships?.owned_by?.target_tag).toBe("person");
+    expect(r?.relationships?.owned_by?.cardinality).toBe("one");
+    expect(r?.parent_names).toEqual(["work"]);
+    expect(r?.created_at).toBeDefined();
+    expect(r?.updated_at).toBeDefined();
+  });
+
+  it("upsertTagRecord preserves columns left undefined in the patch", async () => {
+    await store.upsertTagRecord("project", {
+      description: "first",
+      fields: { status: { type: "string" } },
+      parent_names: ["work"],
+    });
+    await store.upsertTagRecord("project", { description: "second" });
+    const r = await store.getTagRecord("project");
+    expect(r?.description).toBe("second");
+    expect(r?.fields?.status?.type).toBe("string");
+    expect(r?.parent_names).toEqual(["work"]);
+  });
+
+  it("upsertTagRecord clears a column when patch passes null", async () => {
+    await store.upsertTagRecord("project", {
+      description: "deliverable",
+      parent_names: ["work"],
+    });
+    await store.upsertTagRecord("project", { parent_names: null });
+    const r = await store.getTagRecord("project");
+    expect(r?.description).toBe("deliverable");
+    expect(r?.parent_names).toBeUndefined();
+  });
+
+  it("listTagRecords returns every tag row, sorted by name", async () => {
+    await store.upsertTagRecord("zebra", { description: "z" });
+    await store.upsertTagRecord("alpha", { description: "a" });
+    const records = await store.listTagRecords();
+    const names = records.map((r) => r.tag);
+    const idxAlpha = names.indexOf("alpha");
+    const idxZebra = names.indexOf("zebra");
+    expect(idxAlpha).toBeGreaterThanOrEqual(0);
+    expect(idxZebra).toBeGreaterThan(idxAlpha);
+  });
+
+  it("update-tag MCP rejects an invalid cardinality", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    await expect(
+      update.execute({
+        tag: "project",
+        relationships: {
+          owned_by: { target_tag: "person", cardinality: "bogus" },
+        },
+      }),
+    ).rejects.toThrow(/cardinality/);
+  });
+
+  it("update-tag MCP accepts every cardinality in the named vocabulary", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    for (const card of ["one", "optional", "many", "many-required"]) {
+      await update.execute({
+        tag: `tag-${card}`,
+        relationships: {
+          rel: { target_tag: "other", cardinality: card },
+        },
+      });
+      const r = await store.getTagRecord(`tag-${card}`);
+      expect(r?.relationships?.rel?.cardinality).toBe(card);
+    }
+  });
+
+  it("update-tag MCP rejects a relationship missing target_tag", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    await expect(
+      update.execute({
+        tag: "project",
+        relationships: { owned_by: { cardinality: "one" } },
+      }),
+    ).rejects.toThrow(/target_tag/);
+  });
+
+  it("update-tag MCP sets parent_names and the hierarchy invalidates", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+
+    await store.createNote("v note", { tags: ["voice"] });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+
+    await update.execute({
+      tag: "voice",
+      parent_names: ["manual"],
+    });
+
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+  });
+
+  it("update-tag MCP empty parent_names array clears the column", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await update.execute({ tag: "voice", parent_names: [] });
+    const r = await store.getTagRecord("voice");
+    expect(r?.parent_names).toBeUndefined();
+  });
+
+  it("list-tags MCP single-tag detail includes relationships + parent_names", async () => {
+    await store.upsertTagRecord("project", {
+      description: "p",
+      relationships: { owned_by: { target_tag: "person", cardinality: "one" } },
+      parent_names: ["work"],
+    });
+    const tools = generateMcpTools(store);
+    const listTags = tools.find((t) => t.name === "list-tags")!;
+    const result = await listTags.execute({ tag: "project" }) as any;
+    expect(result.relationships?.owned_by?.target_tag).toBe("person");
+    expect(result.parent_names).toEqual(["work"]);
+    expect(result.created_at).toBeDefined();
+  });
+
+  it("list-tags MCP include_schema returns relationships + parent_names per tag", async () => {
+    await store.upsertTagRecord("project", {
+      relationships: { owned_by: { target_tag: "person", cardinality: "one" } },
+      parent_names: ["work"],
+    });
+    await store.createNote("p note", { tags: ["project"] });
+    const tools = generateMcpTools(store);
+    const listTags = tools.find((t) => t.name === "list-tags")!;
+    const all = await listTags.execute({ include_schema: true }) as any[];
+    const project = all.find((t) => t.name === "project")!;
+    expect(project.relationships?.owned_by?.target_tag).toBe("person");
+    expect(project.parent_names).toEqual(["work"]);
+  });
+
+  it("renameTag carries description + fields + relationships + parent_names onto the new row", async () => {
+    await store.upsertTagRecord("old-name", {
+      description: "before",
+      fields: { status: { type: "string" } },
+      relationships: { owned_by: { target_tag: "person", cardinality: "one" } },
+      parent_names: ["work"],
+    });
+    const result = await store.renameTag("old-name", "new-name");
+    expect("renamed" in result).toBe(true);
+
+    const renamed = await store.getTagRecord("new-name");
+    expect(renamed?.description).toBe("before");
+    expect(renamed?.fields?.status?.type).toBe("string");
+    expect(renamed?.relationships?.owned_by?.target_tag).toBe("person");
+    expect(renamed?.parent_names).toEqual(["work"]);
+
+    const old = await store.getTagRecord("old-name");
+    expect(old).toBeNull();
+  });
+
+  it("deleteTag drops the identity row + invalidates the hierarchy", async () => {
+    await store.upsertTagRecord("voice", {
+      description: "voice notes",
+      parent_names: ["manual"],
+    });
+    await store.createNote("v", { tags: ["voice"] });
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(1);
+
+    await store.deleteTag("voice");
+    expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
+    expect(await store.getTagRecord("voice")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Schema migration v13 → v14 — patterns/tag-data-model.md
+// ---------------------------------------------------------------------------
+
+describe("schema migration v13 → v14", async () => {
+  it("backfills tags.parent_names from `_tags/<name>` notes", async () => {
+    // Simulate a pre-v14 vault by writing a `_tags/<name>` note + the
+    // legacy tag_schemas row directly via a fresh DB at v13 shape.
+    const { Database } = await import("bun:sqlite");
+    const db = new Database(":memory:");
+
+    // Build the v13 shape inline: tags(name PK only), separate tag_schemas
+    // table, plus a notes row at `_tags/voice`.
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`CREATE TABLE notes (
+      id TEXT PRIMARY KEY, content TEXT DEFAULT '', path TEXT,
+      metadata TEXT DEFAULT '{}', created_at TEXT NOT NULL, updated_at TEXT
+    )`);
+    db.exec(`CREATE TABLE tags (name TEXT PRIMARY KEY)`);
+    db.exec(`CREATE TABLE tag_schemas (
+      tag_name TEXT PRIMARY KEY REFERENCES tags(name) ON DELETE CASCADE,
+      description TEXT, fields TEXT
+    )`);
+
+    db.prepare("INSERT INTO tags (name) VALUES (?)").run("voice");
+    db.prepare("INSERT INTO tag_schemas (tag_name, description, fields) VALUES (?, ?, ?)")
+      .run("voice", "voice notes", '{"recorded_at":{"type":"string"}}');
+    db.prepare(`INSERT INTO notes (id, path, metadata, created_at) VALUES (?, ?, ?, ?)`)
+      .run("n1", "_tags/voice", JSON.stringify({ parents: ["manual"] }), new Date().toISOString());
+
+    // Now run initSchema — it should add the v14 columns, copy schema +
+    // hierarchy data onto the tags row, and drop tag_schemas.
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    // tag_schemas should be gone.
+    const tableExists = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='tag_schemas'",
+    ).get();
+    expect(tableExists).toBeNull();
+
+    // tags row should carry the migrated fields.
+    const row = db.prepare(
+      "SELECT name, description, fields, parent_names FROM tags WHERE name = 'voice'",
+    ).get() as any;
+    expect(row.description).toBe("voice notes");
+    expect(JSON.parse(row.fields).recorded_at.type).toBe("string");
+    expect(JSON.parse(row.parent_names)).toEqual(["manual"]);
+
+    // The `_tags/voice` note is left in place as harmless historical record.
+    const note = db.prepare("SELECT id FROM notes WHERE path = '_tags/voice'").get();
+    expect(note).toBeDefined();
+
+    db.close();
+  });
+
+  it("is idempotent — running initSchema twice is a no-op the second time", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+    const db = new Database(":memory:");
+    initSchema(db);
+    db.prepare(`
+      INSERT INTO tags (name, description, parent_names, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(
+      "voice",
+      "voice notes",
+      JSON.stringify(["manual"]),
+      new Date().toISOString(),
+      new Date().toISOString(),
+    );
+
+    // Second run must not throw, must not perturb the row, must not
+    // reintroduce tag_schemas.
+    initSchema(db);
+
+    const row = db.prepare("SELECT description, parent_names FROM tags WHERE name = 'voice'").get() as any;
+    expect(row.description).toBe("voice notes");
+    expect(JSON.parse(row.parent_names)).toEqual(["manual"]);
+
+    const tableExists = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='tag_schemas'",
+    ).get();
+    expect(tableExists).toBeNull();
+    db.close();
+  });
+
+  // vault#248 — the migration body is wrapped in BEGIN IMMEDIATE / COMMIT
+  // with a try/catch ROLLBACK. A crash mid-migration must leave the DB in
+  // its pre-migration state (NOT half-migrated), and a retry must converge
+  // to the same final state as a clean run. The transaction wrap is what
+  // makes that guarantee — the `hasColumn` / `hasTable` idempotency guards
+  // are belt-and-suspenders, not load-bearing.
+  it("crash mid-migration rolls back to pre-migration state, then retry succeeds", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+
+    const db = new Database(":memory:");
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`CREATE TABLE notes (
+      id TEXT PRIMARY KEY, content TEXT DEFAULT '', path TEXT,
+      metadata TEXT DEFAULT '{}', created_at TEXT NOT NULL, updated_at TEXT
+    )`);
+    db.exec(`CREATE TABLE tags (name TEXT PRIMARY KEY)`);
+    db.exec(`CREATE TABLE tag_schemas (
+      tag_name TEXT PRIMARY KEY REFERENCES tags(name) ON DELETE CASCADE,
+      description TEXT, fields TEXT
+    )`);
+
+    db.prepare("INSERT INTO tags (name) VALUES (?)").run("voice");
+    db.prepare("INSERT INTO tag_schemas (tag_name, description, fields) VALUES (?, ?, ?)")
+      .run("voice", "voice notes", '{"recorded_at":{"type":"string"}}');
+    db.prepare(`INSERT INTO notes (id, path, metadata, created_at) VALUES (?, ?, ?, ?)`)
+      .run("n1", "_tags/voice", JSON.stringify({ parents: ["manual"] }), new Date().toISOString());
+
+    // Patch db.exec to simulate a crash on the final DROP TABLE step. That's
+    // the right injection point: every ALTER + data copy has already landed
+    // inside the transaction, so a successful rollback proves the wrap
+    // covers the full migration body — not just the tail.
+    const origExec = db.exec.bind(db);
+    let crashOnDrop: boolean = true;
+    (db as any).exec = function (sql: string) {
+      if (crashOnDrop && sql.includes("DROP TABLE tag_schemas")) {
+        throw new Error("simulated crash mid-migration");
+      }
+      return origExec(sql);
+    };
+
+    expect(() => initSchema(db)).toThrow("simulated crash mid-migration");
+
+    // Pre-migration shape: tag_schemas table still exists with its row,
+    // tags table back to (name) only — none of the v14 columns landed,
+    // `_tags/voice` note untouched, schema_version row not yet written.
+    const tagSchemasStill = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='tag_schemas'",
+    ).get();
+    expect(tagSchemasStill).toBeTruthy();
+    const schemaRow = db.prepare(
+      "SELECT description, fields FROM tag_schemas WHERE tag_name = 'voice'",
+    ).get() as any;
+    expect(schemaRow.description).toBe("voice notes");
+
+    const tagsCols = db.prepare("PRAGMA table_info(tags)").all() as { name: string }[];
+    const colNames = tagsCols.map((c) => c.name).sort();
+    expect(colNames).toEqual(["name"]);
+
+    const note = db.prepare("SELECT path, metadata FROM notes WHERE id = 'n1'").get() as any;
+    expect(note.path).toBe("_tags/voice");
+    expect(JSON.parse(note.metadata).parents).toEqual(["manual"]);
+
+    // No lingering open transaction — a SELECT after rollback succeeds, and
+    // a fresh BEGIN IMMEDIATE doesn't fail with "cannot start a transaction
+    // within a transaction".
+    db.exec("BEGIN IMMEDIATE");
+    db.exec("ROLLBACK");
+
+    // Retry: drop the crash injection, run initSchema again. It must
+    // converge to the same final post-v14 state as a clean run.
+    crashOnDrop = false;
+    initSchema(db);
+
+    const tableGone = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='tag_schemas'",
+    ).get();
+    expect(tableGone).toBeNull();
+    const post = db.prepare(
+      "SELECT description, fields, parent_names FROM tags WHERE name = 'voice'",
+    ).get() as any;
+    expect(post.description).toBe("voice notes");
+    expect(JSON.parse(post.fields).recorded_at.type).toBe("string");
+    expect(JSON.parse(post.parent_names)).toEqual(["manual"]);
+
+    db.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Schema migration v14 → v15 — vault#246 (_schemas/* + _schema_defaults retired)
+// ---------------------------------------------------------------------------
+
+describe("schema migration v14 → v15", async () => {
+  // Build a v14-shape DB by:
+  //   1. Calling initSchema (so we get the full v15 shape, including
+  //      note_schemas / schema_mappings tables).
+  //   2. Manually wiping the new tables, then writing the legacy
+  //      `_schemas/<name>` and `_schema_defaults` notes.
+  //   3. Re-running initSchema — the migration's short-circuit (empty
+  //      destination tables) should kick in and copy the data over.
+  async function buildV14ShapeWithLegacyNotes(): Promise<Database> {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+    const db = new Database(":memory:");
+    initSchema(db);
+
+    // Write the legacy notes that the v14 vaults stored config in.
+    const now = new Date().toISOString();
+    const insertNote = db.prepare(
+      "INSERT INTO notes (id, content, path, metadata, created_at) VALUES (?, ?, ?, ?, ?)",
+    );
+    insertNote.run(
+      "s1",
+      "",
+      "_schemas/task",
+      JSON.stringify({
+        description: "A task",
+        fields: { priority: { type: "string", enum: ["high", "low"] } },
+        required: ["priority"],
+      }),
+      now,
+    );
+    insertNote.run(
+      "s2",
+      "",
+      "_schemas/journal-entry",
+      JSON.stringify({ fields: { mood: { type: "string" } } }),
+      now,
+    );
+    insertNote.run(
+      "d1",
+      "",
+      "_schema_defaults",
+      JSON.stringify({
+        path_prefixes: { "journal/": "journal-entry" },
+        tags: { task: "task", "follow-up": "task" },
+      }),
+      now,
+    );
+
+    // Wipe the destination tables so the migration short-circuit doesn't
+    // fire (otherwise initSchema treats them as already migrated).
+    db.exec("DELETE FROM schema_mappings");
+    db.exec("DELETE FROM note_schemas");
+
+    return db;
+  }
+
+  it("copies `_schemas/<name>` notes → note_schemas with description / fields / required", async () => {
+    const db = await buildV14ShapeWithLegacyNotes();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    const taskRow = db.prepare(
+      "SELECT description, fields, required FROM note_schemas WHERE name = 'task'",
+    ).get() as any;
+    expect(taskRow.description).toBe("A task");
+    expect(JSON.parse(taskRow.fields).priority.enum).toEqual(["high", "low"]);
+    expect(JSON.parse(taskRow.required)).toEqual(["priority"]);
+
+    const journalRow = db.prepare(
+      "SELECT description, fields FROM note_schemas WHERE name = 'journal-entry'",
+    ).get() as any;
+    expect(journalRow.description).toBeNull();
+    expect(JSON.parse(journalRow.fields).mood.type).toBe("string");
+
+    db.close();
+  });
+
+  it("copies `_schema_defaults` → schema_mappings (path_prefixes + tags)", async () => {
+    const db = await buildV14ShapeWithLegacyNotes();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    const mappings = db.prepare(
+      "SELECT schema_name, match_kind, match_value FROM schema_mappings ORDER BY match_kind, match_value",
+    ).all() as { schema_name: string; match_kind: string; match_value: string }[];
+    expect(mappings).toEqual([
+      { schema_name: "journal-entry", match_kind: "path_prefix", match_value: "journal/" },
+      { schema_name: "task", match_kind: "tag", match_value: "follow-up" },
+      { schema_name: "task", match_kind: "tag", match_value: "task" },
+    ]);
+
+    db.close();
+  });
+
+  it("auto-creates a stub schema row when a mapping references an undeclared schema (FK)", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+    const db = new Database(":memory:");
+    initSchema(db);
+
+    // Only a defaults note — no `_schemas/orphan` definition.
+    db.prepare(
+      "INSERT INTO notes (id, content, path, metadata, created_at) VALUES (?, ?, ?, ?, ?)",
+    ).run(
+      "d",
+      "",
+      "_schema_defaults",
+      JSON.stringify({ tags: { orphan: "orphan" } }),
+      new Date().toISOString(),
+    );
+    db.exec("DELETE FROM schema_mappings");
+    db.exec("DELETE FROM note_schemas");
+
+    initSchema(db);
+
+    // Stub schema row was created so the FK on schema_mappings holds.
+    const stub = db.prepare("SELECT name FROM note_schemas WHERE name = 'orphan'").get();
+    expect(stub).toBeTruthy();
+    const mapping = db.prepare(
+      "SELECT match_kind, match_value FROM schema_mappings WHERE schema_name = 'orphan'",
+    ).get() as any;
+    expect(mapping).toEqual({ match_kind: "tag", match_value: "orphan" });
+
+    db.close();
+  });
+
+  it("legacy `_schemas/*` and `_schema_defaults` notes are left in place (audit trail)", async () => {
+    const db = await buildV14ShapeWithLegacyNotes();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    const schemaNote = db.prepare("SELECT id FROM notes WHERE path = '_schemas/task'").get();
+    expect(schemaNote).toBeTruthy();
+    const defaultsNote = db.prepare("SELECT id FROM notes WHERE path = '_schema_defaults'").get();
+    expect(defaultsNote).toBeTruthy();
+
+    db.close();
+  });
+
+  it("is idempotent — second initSchema doesn't re-copy or duplicate rows", async () => {
+    const db = await buildV14ShapeWithLegacyNotes();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    const schemaCount1 = (db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c;
+    const mappingCount1 = (db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c;
+
+    initSchema(db);
+
+    const schemaCount2 = (db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c;
+    const mappingCount2 = (db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c;
+    expect(schemaCount2).toBe(schemaCount1);
+    expect(mappingCount2).toBe(mappingCount1);
+
+    db.close();
+  });
+
+  it("no legacy notes → migration is a no-op (empty tables)", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+    const db = new Database(":memory:");
+    initSchema(db);
+
+    expect((db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c).toBe(0);
+    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBe(0);
+
+    db.close();
+  });
+
+  // Short-circuit uses `||` not `&&`: a vault with schemas-but-no-mappings
+  // is a valid post-v15 state. Legacy `_schemas/*` notes left around from
+  // a prior import shouldn't get re-folded on every boot. (The mirror case —
+  // mappings-but-no-schemas — is structurally impossible because the
+  // schema_mappings FK to note_schemas has ON DELETE CASCADE.)
+  it("doesn't re-run when only one destination table is non-empty", async () => {
+    const db = await buildV14ShapeWithLegacyNotes();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    // After first run: tables populated, legacy notes still in `notes`.
+    expect((db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c).toBeGreaterThan(0);
+    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBeGreaterThan(0);
+    expect((db.prepare("SELECT COUNT(*) as c FROM notes WHERE path GLOB '_schemas/*'").get() as any).c).toBeGreaterThan(0);
+
+    // Wipe mappings only; schemas remain non-empty. With the buggy `&&`
+    // short-circuit, the migration would re-scan `_schema_defaults` and
+    // rebuild the mappings table. With `||` it correctly no-ops.
+    db.exec("DELETE FROM schema_mappings");
+    initSchema(db);
+    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBe(0);
+
+    db.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Schema migration v15 → v16 — vault#257 (tokens.vault_name binding)
+// ---------------------------------------------------------------------------
+
+describe("schema migration v15 → v16", async () => {
+  // vault#257 — the v16 migration body (ALTER TABLE ADD COLUMN + CREATE
+  // INDEX) is wrapped in BEGIN IMMEDIATE / COMMIT with a try/catch
+  // ROLLBACK, mirroring the v14/v15 wrap shape from vault#251. The
+  // individual statements are atomic in SQLite, so the wrap is mostly
+  // belt-and-suspenders for THIS migration — but the test mirrors v14's
+  // crash-rollback shape so anyone touching migrations finds the same
+  // regression-pin pattern across versions.
+  it("crash mid-migration rolls back to pre-v16 state, then retry succeeds", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+
+    // Build the full post-v16 shape, plant a row, then drop the v16
+    // additions so initSchema's migrateToV16 fires on the next call.
+    const db = new Database(":memory:");
+    db.exec("PRAGMA journal_mode = WAL");
+    initSchema(db);
+
+    const now = new Date().toISOString();
+    db.prepare(
+      "INSERT INTO tokens (token_hash, label, created_at, vault_name) VALUES (?, ?, ?, ?)",
+    ).run("sha256:abc123def456", "pre-existing", now, "work");
+
+    db.exec("DROP INDEX IF EXISTS idx_tokens_vault_name");
+    db.exec("ALTER TABLE tokens DROP COLUMN vault_name");
+
+    // Pre-condition: the column is gone but the row is still there
+    // (DROP COLUMN strips the column from existing rows).
+    const preCols = db.prepare("PRAGMA table_info(tokens)").all() as { name: string }[];
+    expect(preCols.map((c) => c.name)).not.toContain("vault_name");
+    const preRow = db.prepare("SELECT label FROM tokens WHERE token_hash = ?")
+      .get("sha256:abc123def456") as { label: string } | null;
+    expect(preRow?.label).toBe("pre-existing");
+
+    // Patch db.exec to crash on CREATE INDEX — the second statement inside
+    // the v16 transaction body. Crashing here proves the wrap covers the
+    // post-ALTER state, not just the tail. The injection deliberately
+    // doesn't match BEGIN/COMMIT/ROLLBACK so the catch's ROLLBACK still
+    // runs through the patched exec.
+    const origExec = db.exec.bind(db);
+    let crashOnIndex: boolean = true;
+    (db as any).exec = function (sql: string) {
+      if (crashOnIndex && sql.includes("CREATE INDEX") && sql.includes("idx_tokens_vault_name")) {
+        throw new Error("simulated crash mid-v16-migration");
+      }
+      return origExec(sql);
+    };
+
+    expect(() => initSchema(db)).toThrow("simulated crash mid-v16-migration");
+
+    // Pre-v16 shape after rollback: vault_name column must not exist; the
+    // pre-existing row must be untouched.
+    const colsAfterRollback = db.prepare("PRAGMA table_info(tokens)").all() as { name: string }[];
+    expect(colsAfterRollback.map((c) => c.name)).not.toContain("vault_name");
+    const idxAfterRollback = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='index' AND name='idx_tokens_vault_name'",
+    ).get();
+    expect(idxAfterRollback).toBeNull();
+    const rowAfterRollback = db.prepare("SELECT label FROM tokens WHERE token_hash = ?")
+      .get("sha256:abc123def456") as { label: string } | null;
+    expect(rowAfterRollback?.label).toBe("pre-existing");
+
+    // No lingering open transaction — a fresh BEGIN IMMEDIATE + ROLLBACK
+    // doesn't fail with "cannot start a transaction within a transaction".
+    db.exec("BEGIN IMMEDIATE");
+    db.exec("ROLLBACK");
+
+    // Retry: drop the crash injection, run initSchema again. Must converge
+    // to post-v16 shape (column added, index created, lenient NULL backfill
+    // on the pre-existing row per the migration spec).
+    crashOnIndex = false;
+    initSchema(db);
+
+    const colsPost = db.prepare("PRAGMA table_info(tokens)").all() as { name: string }[];
+    expect(colsPost.map((c) => c.name)).toContain("vault_name");
+    const idxPost = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='index' AND name='idx_tokens_vault_name'",
+    ).get();
+    expect(idxPost).toBeTruthy();
+    const rowPost = db.prepare("SELECT label, vault_name FROM tokens WHERE token_hash = ?")
+      .get("sha256:abc123def456") as { label: string; vault_name: string | null };
+    expect(rowPost.label).toBe("pre-existing");
+    expect(rowPost.vault_name).toBeNull();
+
+    db.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tag-scope auth post-v14 — patterns/tag-scoped-tokens.md
+// ---------------------------------------------------------------------------
+
+describe("tag-scope auth (post-v14 hierarchy)", async () => {
+  it("token allowlisted for `health` matches descendants declared via parent_names", async () => {
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.upsertTagRecord("health/food/breakfast", { parent_names: ["health/food"] });
+
+    const expanded = await store.expandTagsWithDescendants(["health"]);
+    expect(expanded.has("health")).toBe(true);
+    expect(expanded.has("health/food")).toBe(true);
+    expect(expanded.has("health/food/breakfast")).toBe(true);
+  });
+
+  it("orphan sub-tag fallback: token for `health` still sees `#health/food` even with no declared hierarchy", async () => {
+    // Per patterns/tag-scoped-tokens.md §Storage details, the auth check
+    // also splits on '/' and matches the root verbatim against the raw
+    // allowlist. This survives the v14 source-of-truth swap because the
+    // fallback lives in src/tag-scope.ts, not in the resolver.
+    const { noteWithinTagScope } = await import("../../src/tag-scope.ts");
+    const note = { id: "x", content: "", createdAt: "", tags: ["health/food"] };
+    const allowed = await store.expandTagsWithDescendants(["health"]);
+    // No declared hierarchy — the expansion returns just `health`.
+    expect(allowed.has("health/food")).toBe(false);
+    // But the string-form fallback still matches.
+    expect(noteWithinTagScope(note, allowed, ["health"])).toBe(true);
+  });
+});