@openparachute/vault 0.3.3 → 0.4.3

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 ----
@@ -246,7 +357,7 @@ describe("renameTag", async () => {
     const n2 = await store.createNote("B", { tags: ["voice", "keeper"] });
 
     const result = await store.renameTag("voice", "memo");
-    expect(result).toEqual({ renamed: 2 });
+    expect(result).toMatchObject({ renamed: 2, sub_tags_renamed: 0 });
 
     expect((await store.getNote(n1.id))!.tags).toEqual(["memo"]);
     expect((await store.getNote(n2.id))!.tags?.sort()).toEqual(["keeper", "memo"]);
@@ -275,7 +386,7 @@ describe("renameTag", async () => {
     await store.untagNote((await store.queryNotes({}))[0].id, ["doomed"]);
 
     const result = await store.renameTag("doomed", "archived");
-    expect(result).toEqual({ renamed: 0 });
+    expect(result).toMatchObject({ renamed: 0, sub_tags_renamed: 0 });
     const tags = await store.listTags();
     expect(tags.some((t) => t.name === "doomed")).toBe(false);
     expect(tags.some((t) => t.name === "archived")).toBe(true);
@@ -286,7 +397,7 @@ describe("renameTag", async () => {
     await store.createNote("B", { tags: ["new"] });
 
     const result = await store.renameTag("old", "new");
-    expect(result).toEqual({ error: "target_exists" });
+    expect(result).toMatchObject({ error: "target_exists", conflicting: ["new"] });
 
     // No bleed — both tags still present with their original counts.
     const tags = await store.listTags();
@@ -302,11 +413,325 @@ describe("renameTag", async () => {
   it("same-name rename is a no-op on an existing tag", async () => {
     await store.createNote("A", { tags: ["voice"] });
     const result = await store.renameTag("voice", "voice");
-    expect(result).toEqual({ renamed: 0 });
+    expect(result).toMatchObject({ renamed: 0, sub_tags_renamed: 0 });
     expect((await store.listTags()).find((t) => t.name === "voice")!.count).toBe(1);
   });
 });
 
+// ---- Tag rename cascade (vault#240 + #247) ----
+
+describe("renameTag cascade (vault#240 + #247)", async () => {
+  it("1. rewrites note bodies with #tag references", async () => {
+    const note = await store.createNote(
+      "Today's #task is important. Also see #task/work and the #other tag.",
+      { tags: ["task"] },
+    );
+
+    const result = await store.renameTag("task", "todo");
+    expect(result).toMatchObject({ renamed: 1, notes_rewritten: 1 });
+
+    const fresh = await store.getNote(note.id);
+    expect(fresh!.content).toContain("#todo");
+    expect(fresh!.content).not.toContain("#task ");
+    expect(fresh!.content).toContain("#other"); // untouched
+  });
+
+  it("2. cascades sub-tags recursively (task → todo, task/work → todo/work, task/work/client → todo/work/client)", async () => {
+    await store.createNote("a", { tags: ["task"] });
+    await store.createNote("b", { tags: ["task/work"] });
+    await store.createNote("c", { tags: ["task/work/client"] });
+
+    const result = await store.renameTag("task", "todo");
+    expect(result).toMatchObject({ renamed: 3, sub_tags_renamed: 2 });
+
+    const tags = (await store.listTags()).map((t) => t.name).sort();
+    expect(tags).toContain("todo");
+    expect(tags).toContain("todo/work");
+    expect(tags).toContain("todo/work/client");
+    expect(tags.some((t) => t.startsWith("task"))).toBe(false);
+  });
+
+  it("3. rewrites parent_names refs in OTHER tag rows (closes #247)", async () => {
+    await store.upsertTagRecord("task", { description: "tasks" });
+    await store.upsertTagRecord("voice", {
+      parent_names: ["manual", "task"],
+    });
+
+    const result = await store.renameTag("task", "todo");
+    expect(result).toMatchObject({ renamed: 0, parent_refs_updated: 1 });
+
+    const voice = await store.getTagRecord("voice");
+    expect(voice?.parent_names).toEqual(["manual", "todo"]);
+  });
+
+  it("4. rewrites tokens.scoped_tags JSON arrays", async () => {
+    await store.upsertTagRecord("task", {});
+    await store.upsertTagRecord("project", {});
+
+    const now = new Date().toISOString();
+    db.prepare(
+      `INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run("h_one", "tok-1", "full", "vault:read", JSON.stringify(["task"]), now);
+    db.prepare(
+      `INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run("h_two", "tok-2", "full", "vault:read", JSON.stringify(["project"]), now);
+
+    const result = await store.renameTag("task", "todo");
+    expect(result).toMatchObject({ tokens_updated: 1 });
+
+    const refreshed = db
+      .prepare("SELECT token_hash, scoped_tags FROM tokens ORDER BY token_hash")
+      .all() as { token_hash: string; scoped_tags: string }[];
+    expect(JSON.parse(refreshed[0]!.scoped_tags)).toEqual(["todo"]);
+    // Untouched.
+    expect(JSON.parse(refreshed[1]!.scoped_tags)).toEqual(["project"]);
+  });
+
+  it("5. rewrites #tag and [[_tags/...]] references in note bodies (incl. sub-tags)", async () => {
+    await store.upsertTagRecord("task/work", {});
+    await store.upsertTagRecord("task", {});
+    const a = await store.createNote(
+      "#task is important #task/work and a wikilink: [[_tags/task]]",
+      { tags: ["task"] },
+    );
+
+    const result = await store.renameTag("task", "todo");
+    expect(result.renamed).toBeGreaterThan(0);
+    if ("notes_rewritten" in result) expect(result.notes_rewritten).toBe(1);
+
+    const fresh = await store.getNote(a.id);
+    expect(fresh!.content).toContain("#todo is important");
+    expect(fresh!.content).toContain("#todo/work");
+    expect(fresh!.content).toContain("[[_tags/todo]]");
+    expect(fresh!.content).not.toContain("#task ");
+    expect(fresh!.content).not.toContain("[[_tags/task]");
+  });
+
+  it("6. pre-flight collision aborts without mutation when target exists", async () => {
+    await store.createNote("t", { tags: ["task"] });
+    await store.createNote("p", { tags: ["project"] });
+
+    const result = await store.renameTag("task", "project");
+    expect(result).toMatchObject({ error: "target_exists", conflicting: ["project"] });
+
+    // Both tags still present, untouched counts.
+    const tags = await store.listTags();
+    expect(tags.find((t) => t.name === "task")?.count).toBe(1);
+    expect(tags.find((t) => t.name === "project")?.count).toBe(1);
+  });
+
+  it("7. transactional rollback leaves the original state intact on mid-cascade failure", async () => {
+    await store.createNote("a", { tags: ["task"] });
+    await store.createNote("b", { tags: ["task/work"] });
+
+    // Inject failure: drop the tags table mid-transaction by intercepting
+    // the JSON cascade pass. Easiest reliable hook: corrupt the
+    // tokens.scoped_tags column with a value that will fail the JSON
+    // cascade's UPDATE (use a token_hash that violates a constraint when
+    // the cascade rewrites it). Simpler: spy on noteOps via monkey-patch.
+    //
+    // We use the simplest reliable approach: a row lock conflict. Two
+    // statements writing the same row in a deferred transaction would
+    // require two connections; instead we drop a required table at the
+    // SQL layer to force a SQL error on a downstream UPDATE inside the
+    // cascade. Restore after the test.
+    const originalDeleteTag = (db as any).prepare;
+    let dropOnce = false;
+    (db as any).prepare = function (sql: string) {
+      // Force the tag-row pass to fail on the DELETE step by dropping
+      // the tags table out from under it after the first INSERT.
+      if (!dropOnce && sql.startsWith("DELETE FROM tags WHERE name = ?")) {
+        dropOnce = true;
+        const stmt = originalDeleteTag.call(this, sql);
+        const wrapped = {
+          run: (...args: any[]) => {
+            (db as any).prepare = originalDeleteTag;
+            throw new Error("synthetic mid-cascade failure");
+          },
+        };
+        return wrapped;
+      }
+      return originalDeleteTag.call(this, sql);
+    };
+
+    let threw = false;
+    try {
+      await store.renameTag("task", "todo");
+    } catch {
+      threw = true;
+    }
+    (db as any).prepare = originalDeleteTag;
+    expect(threw).toBe(true);
+
+    // Original state intact: task tags still present, todo absent.
+    const tags = (await store.listTags()).map((t) => t.name);
+    expect(tags).toContain("task");
+    expect(tags).toContain("task/work");
+    expect(tags).not.toContain("todo");
+    expect(tags).not.toContain("todo/work");
+  });
+
+  it("8. invalidates hierarchy + schema caches after rename", async () => {
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string" } },
+    });
+    await store.upsertTagRecord("task/work", { parent_names: ["task"] });
+    await store.createNote("a", { tags: ["task/work"] });
+
+    // Prime the caches by querying via the hierarchy-aware path.
+    await store.queryNotes({ tags: ["task"] });
+
+    await store.renameTag("task", "todo");
+
+    // queryNotes via the new tag must find the note that's now tagged
+    // todo/work (descendant of todo via parent_names rewrite).
+    const found = await store.queryNotes({ tags: ["todo"] });
+    expect(found.length).toBe(1);
+
+    // validateNoteAgainstSchemas must surface fields under the new tag —
+    // proves the schema-config cache was busted (otherwise the resolver
+    // would still be keyed on `task`).
+    const status = store.validateNoteAgainstSchemas({
+      tags: ["todo"],
+      metadata: { status: 123 },
+    });
+    expect(status?.warnings.some((w) => w.reason === "type_mismatch")).toBe(true);
+  });
+
+  it("9. self-rename is a structured no-op when the source exists", async () => {
+    await store.createNote("a", { tags: ["task"] });
+    const result = await store.renameTag("task", "task");
+    expect(result).toMatchObject({ renamed: 0, sub_tags_renamed: 0 });
+    expect((await store.listTags()).find((t) => t.name === "task")?.count).toBe(1);
+  });
+
+  it("10. preserves transitive inheritance through the cascade (manual extends note; voice extends manual; renaming manual → instruction keeps voice's effective fields)", async () => {
+    await store.upsertTagRecord("note", {
+      fields: { topic: { type: "string" } },
+    });
+    await store.upsertTagRecord("manual", {
+      fields: { author: { type: "string" } },
+      parent_names: ["note"],
+    });
+    await store.upsertTagRecord("voice", {
+      parent_names: ["manual"],
+    });
+
+    const result = await store.renameTag("manual", "instruction");
+    expect(result.renamed).toBe(0); // no notes
+    if ("parent_refs_updated" in result) expect(result.parent_refs_updated).toBe(1);
+
+    // Voice's parent_names now references `instruction` (the renamed parent).
+    const voice = await store.getTagRecord("voice");
+    expect(voice?.parent_names).toEqual(["instruction"]);
+
+    // Voice's effective fields still inherit through instruction → note.
+    const status = store.validateNoteAgainstSchemas({
+      tags: ["voice"],
+      metadata: { topic: 123, author: "ok" },
+    });
+    expect(status?.warnings.some((w) => w.field === "topic" && w.reason === "type_mismatch")).toBe(
+      true,
+    );
+  });
+
+  it("11. rewrites indexed_fields.declarer_tags JSON arrays (#275 fold N3)", async () => {
+    // Drive through the update-tag MCP tool — it owns indexed-field
+    // lifecycle (see mcp.ts §update-tag); store.upsertTagRecord does
+    // not populate the `indexed_fields` table.
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      fields: { status: { type: "string", indexed: true } },
+    });
+
+    const beforeRow = db
+      .prepare("SELECT declarer_tags FROM indexed_fields WHERE field = ?")
+      .get("status") as { declarer_tags: string };
+    expect(JSON.parse(beforeRow.declarer_tags).sort()).toEqual(["project", "task"]);
+
+    const result = await store.renameTag("task", "todo");
+    expect(result).toMatchObject({ indexed_field_declarers_updated: 1 });
+
+    const afterRow = db
+      .prepare("SELECT declarer_tags FROM indexed_fields WHERE field = ?")
+      .get("status") as { declarer_tags: string };
+    const declarers = JSON.parse(afterRow.declarer_tags) as string[];
+    expect(declarers).toContain("todo");
+    expect(declarers).toContain("project");
+    expect(declarers).not.toContain("task");
+  });
+
+  it("12. rewrites `_tags/<path>` config-note paths via rewriteTagConfigPath (#275 fold N3)", async () => {
+    await store.upsertTagRecord("old", {});
+    const root = await store.createNote("root config", { path: "_tags/old" });
+    const sub = await store.createNote("sub config", { path: "_tags/old/nested/leaf" });
+
+    const result = await store.renameTag("old", "new");
+    expect(result).toMatchObject({ paths_renamed: 2 });
+
+    const rootFresh = await store.getNote(root.id);
+    expect(rootFresh?.path).toBe("_tags/new");
+
+    const subFresh = await store.getNote(sub.id);
+    expect(subFresh?.path).toBe("_tags/new/nested/leaf");
+  });
+
+  it("14. sub-tag discovery escapes LIKE wildcards — `task_` rename doesn't pull `taskX/sub` into the cascade (#275 re-review)", async () => {
+    // Pre-fold: the discovery query was `LIKE 'task_/%'` which matches
+    // `taskX/sub` because `_` is a single-char wildcard. `taskX/sub`
+    // would then enter `renames` and get rewritten to `<new>/sub` — a
+    // write the caller never asked for.
+    await store.upsertTagRecord("task_", {});
+    await store.upsertTagRecord("taskX/sub", {});
+    const stray = await store.createNote("stray", { tags: ["taskX/sub"] });
+
+    const result = await store.renameTag("task_", "todo_");
+    // Only the actual root rename — no spurious sub-tag pulled in.
+    expect(result).toMatchObject({ sub_tags_renamed: 0 });
+
+    expect(await store.getTagRecord("task_")).toBeNull();
+    expect(await store.getTagRecord("todo_")).toBeTruthy();
+
+    // `taskX/sub` is untouched: row still present, the note tagged with
+    // it still carries the original tag.
+    expect(await store.getTagRecord("taskX/sub")).toBeTruthy();
+    expect((await store.getNote(stray.id))!.tags).toEqual(["taskX/sub"]);
+  });
+
+  it("13. LIKE wildcard escape — a tag literally named `task_` doesn't false-match `taskX` (#275 fold N1)", async () => {
+    // `task_` and `taskX` are unrelated tags. Pre-fold N1 the LIKE
+    // pre-filter would have considered `taskX` rows as candidates for
+    // `task_`'s rewrite (LIKE `%"task_"%` matches `"taskX"` in JSON
+    // because `_` is a single-char wildcard). The cascade's downstream
+    // remapJsonArray would have rejected the row, so no data
+    // corruption — but the wasted scan + bad hygiene is what fold N1
+    // closes. This test pins the behavior end-to-end.
+    await store.upsertTagRecord("task_", {});
+    await store.upsertTagRecord("taskX", {});
+    await store.upsertTagRecord("voice", {
+      parent_names: ["taskX"],
+    });
+
+    await store.renameTag("task_", "renamed_task");
+
+    // taskX-rooted parent_names must be untouched — the escape stops
+    // taskX from being a candidate for the `task_` rewrite.
+    const voice = await store.getTagRecord("voice");
+    expect(voice?.parent_names).toEqual(["taskX"]);
+    // Sanity: the actual rename did happen.
+    expect(await store.getTagRecord("task_")).toBeNull();
+    expect(await store.getTagRecord("renamed_task")).toBeTruthy();
+  });
+});
+
 describe("mergeTags", async () => {
   it("retags every note from every source onto target and drops sources", async () => {
     const n1 = await store.createNote("A", { tags: ["v1"] });
@@ -476,12 +901,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 +971,178 @@ 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"]);
+    });
+
+    // ---- updated_at filter (vault#285 friction point 1.5) ----
+    //
+    // Incremental-rebuild flows ask "what changed since X." Like `created_at`,
+    // `updated_at` is a real column on `notes` (no indexed-field gate), but
+    // it tracks the *last write* rather than ingestion time. SSGs paginate
+    // against it; sync clients use it as a high-watermark cursor.
+    it("dateFilter on updated_at routes to the n.updated_at column (vault#285 1.5)", async () => {
+      // Two notes; only one is later modified. The filter should pick up the
+      // modification time, not the original creation time.
+      const a = await store.createNote("untouched", { created_at: "2026-01-15T00:00:00.000Z" });
+      const b = await store.createNote("modified-later", { created_at: "2026-01-20T00:00:00.000Z" });
+      // Mutate b to bump its updated_at into a window that excludes a.
+      await store.updateNote(b.id, { append: " edit" });
+
+      // Pin each note's updated_at deterministically so the assertion isn't
+      // racing real wall-clock writes from the test harness.
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-01-15T00:00:00.000Z", a.id);
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", b.id);
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "updated_at", from: "2026-04-01" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["modified-later edit"]);
+    });
+
+    it("dateFilter on updated_at requires no indexed-field declaration", async () => {
+      // `updated_at` is a recognized real column — must not hit the
+      // requireIndexedField gate that fires for arbitrary metadata fields.
+      await store.createNote("x");
+      // Should not throw.
+      const results = await store.queryNotes({
+        dateFilter: { field: "updated_at", from: "1970-01-01" },
+      });
+      expect(Array.isArray(results)).toBe(true);
+    });
+
+    it("dateFilter on updated_at honors the upper-bound exclusive `to`", async () => {
+      const a = await store.createNote("inside-window");
+      const b = await store.createNote("after-window");
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", a.id);
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+        .run("2026-05-15T00:00:00.000Z", b.id);
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "updated_at", from: "2026-04-01", to: "2026-05-01" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["inside-window"]);
+    });
+  });
+
   it("sorts ascending and descending", async () => {
     await store.createNote("First", { id: "first" });
     await store.createNote("Second", { id: "second" });
@@ -907,7 +1516,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);
 
@@ -920,6 +1529,19 @@ describe("MCP tools", async () => {
     expect(names).toContain("delete-tag");
     expect(names).toContain("find-path");
     expect(names).toContain("vault-info");
+    // Six note-schema tools (list/update/delete-note-schema +
+    // list/set/delete-schema-mapping) retired in v17 — the standalone
+    // note_schemas + schema_mappings subsystem was a parallel path to
+    // tags.fields with zero operator usage. See vault#267.
+    expect(names).not.toContain("list-note-schemas");
+    expect(names).not.toContain("update-note-schema");
+    expect(names).not.toContain("delete-note-schema");
+    expect(names).not.toContain("list-schema-mappings");
+    expect(names).not.toContain("set-schema-mapping");
+    expect(names).not.toContain("delete-schema-mapping");
+    // synthesize-notes retired in v17 — replicable with query-notes(near=) +
+    // find-path + agent-side aggregation. See vault#268.
+    expect(names).not.toContain("synthesize-notes");
     expect(tools).toHaveLength(9);
   });
 
@@ -1141,6 +1763,96 @@ describe("MCP tools", async () => {
     expect((await store.getNote(note.id))!.content).toBe("Test");
   });
 
+  // ---- include_content response-shape opt-out (vault#285 friction point 2.response) ----
+  //
+  // Default behavior is unchanged: full Note is returned with `content`.
+  // Setting `include_content: false` swaps in the lean NoteIndex shape
+  // (drops content, adds byteSize + preview). Cuts the response cost on
+  // small-edit / large-note workflows.
+  describe("update-note include_content", () => {
+    it("defaults to full Note (back-compat)", async () => {
+      const note = await store.createNote("Original body", { path: "x" });
+      const tools = generateMcpTools(store);
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      const result = await updateNote.execute({
+        id: note.id,
+        content: "Replaced body",
+        force: true,
+      }) as any;
+      expect(result.content).toBe("Replaced body");
+      // Index-only fields must NOT appear on the back-compat shape.
+      expect(result.byteSize).toBeUndefined();
+      expect(result.preview).toBeUndefined();
+    });
+
+    it("include_content: false returns the lean NoteIndex shape", async () => {
+      const longBody = "a".repeat(5_000);
+      const note = await store.createNote(longBody, { path: "big-note" });
+      const tools = generateMcpTools(store);
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      const result = await updateNote.execute({
+        id: note.id,
+        append: " edit",
+        include_content: false,
+      }) as any;
+      // No content payload — that's the whole point of the opt-out.
+      expect(result.content).toBeUndefined();
+      // Index fields present.
+      expect(typeof result.byteSize).toBe("number");
+      expect(result.byteSize).toBe(5_000 + 5); // original + " edit"
+      expect(typeof result.preview).toBe("string");
+      expect(result.preview.length).toBeGreaterThan(0);
+      expect(result.id).toBe(note.id);
+      expect(result.path).toBe("big-note");
+      expect(result.updatedAt).toBeTruthy();
+    });
+
+    it("include_content: false applies uniformly across batch responses", async () => {
+      await store.createNote("A", { id: "a", path: "a" });
+      await store.createNote("B", { id: "b", path: "b" });
+      const tools = generateMcpTools(store);
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      const result = await updateNote.execute({
+        include_content: false,
+        notes: [
+          { id: "a", content: "A v2", force: true },
+          { id: "b", append: " v2" },
+        ],
+      }) as any[];
+      expect(result).toHaveLength(2);
+      for (const item of result) {
+        expect(item.content).toBeUndefined();
+        expect(typeof item.byteSize).toBe("number");
+        expect(typeof item.preview).toBe("string");
+      }
+    });
+
+    it("include_content: false preserves validation_status when present", async () => {
+      // Declare a tag schema with an indexed `priority` field that constrains
+      // values; then write a note whose metadata violates the schema, so
+      // attachValidationStatus has something to surface.
+      await store.upsertTagSchema("task", {
+        description: "tasks",
+        fields: {
+          priority: { type: "string", enum: ["low", "med", "high"], indexed: false },
+        },
+      });
+      await store.createNote("a task", { id: "t1", tags: ["task"] });
+      const tools = generateMcpTools(store);
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      const result = await updateNote.execute({
+        id: "t1",
+        metadata: { priority: "URGENT" }, // not in enum — generates a warning
+        include_content: false,
+        force: true,
+      }) as any;
+      expect(result.content).toBeUndefined();
+      expect(result.validation_status).toBeTruthy();
+      expect(Array.isArray(result.validation_status.warnings)).toBe(true);
+      expect(result.validation_status.warnings.length).toBeGreaterThan(0);
+    });
+  });
+
   it("update-note force:true bypasses precondition and mutates unconditionally", async () => {
     const note = await store.createNote("First");
     const tools = generateMcpTools(store);
@@ -1267,78 +1979,348 @@ describe("MCP tools", async () => {
     expect((await store.getNote("source"))!.content).toBe("See [[People/Alice]] for details");
   });
 
-  it("query-notes single note by id", async () => {
-    const note = await store.createNote("Hello", { path: "test/note" });
+  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 query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({ id: note.id }) as any;
-    expect(result.content).toBe("Hello");
-    expect(result.path).toBe("test/note");
-    // updatedAt is the optimistic-concurrency token. Callers can't arm a
-    // followup update without it, so it must always come back from a
-    // single-note fetch.
-    expect(result.updatedAt).toBeTruthy();
-    expect(result.updatedAt).toBe(note.updatedAt);
+    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("query-notes single note by path", async () => {
-    await store.createNote("By Path", { path: "Projects/README" });
+  it("update-note prepend concatenates to start without precondition", async () => {
+    const note = await store.createNote("body", { id: "n1" });
     const tools = generateMcpTools(store);
-    const query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({ id: "Projects/README" }) as any;
-    expect(result.content).toBe("By Path");
+    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("query-notes by tag", async () => {
-    await store.createNote("Test", { tags: ["daily"] });
+  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 query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({ tag: ["daily"] }) as any[];
-    expect(result).toHaveLength(1);
+    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("query-notes has_tags=false surfaces untagged notes", async () => {
-    await store.createNote("Tagged", { tags: ["daily"] });
-    await store.createNote("Plain");
+  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 query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({ has_tags: false, include_content: true }) as any[];
-    expect(result.map((n) => n.content)).toEqual(["Plain"]);
-  });
+    const updateNote = tools.find((t) => t.name === "update-note")!;
 
-  it("query-notes has_links=false surfaces orphaned notes", async () => {
-    const a = await store.createNote("Source", { id: "mq-a" });
-    const b = await store.createNote("Target", { id: "mq-b" });
-    await store.createNote("Orphan", { id: "mq-o" });
-    await store.createLink(a.id, b.id, "mentions");
+    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 query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({ has_links: false, include_content: true }) as any[];
-    expect(result.map((n) => n.content)).toEqual(["Orphan"]);
-  });
+    const updateNote = tools.find((t) => t.name === "update-note")!;
 
-  it("query-notes metadata operator query routes through the indexed column", async () => {
-    const { declareField } = await import("./indexed-fields.js");
-    declareField(db, "priority", "INTEGER", "project");
-    await store.createNote("high", { metadata: { priority: 5 } });
-    await store.createNote("mid", { metadata: { priority: 3 } });
-    await store.createNote("low", { metadata: { priority: 1 } });
+    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 query = tools.find((t) => t.name === "query-notes")!;
-    const result = await query.execute({
-      metadata: { priority: { gte: 3 } },
-      include_content: true,
-    }) as any[];
-    expect(result.map((n) => n.content).sort()).toEqual(["high", "mid"]);
+    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("query-notes order_by + sort=desc surfaces highest-priority first", async () => {
-    const { declareField } = await import("./indexed-fields.js");
-    declareField(db, "priority", "INTEGER", "project");
-    await store.createNote("p2", { metadata: { priority: 2 } });
-    await store.createNote("p5", { metadata: { priority: 5 } });
+  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);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: note.id }) as any;
+    expect(result.content).toBe("Hello");
+    expect(result.path).toBe("test/note");
+    // updatedAt is the optimistic-concurrency token. Callers can't arm a
+    // followup update without it, so it must always come back from a
+    // single-note fetch.
+    expect(result.updatedAt).toBeTruthy();
+    expect(result.updatedAt).toBe(note.updatedAt);
+  });
+
+  it("query-notes single note by path", async () => {
+    await store.createNote("By Path", { path: "Projects/README" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: "Projects/README" }) as any;
+    expect(result.content).toBe("By Path");
+  });
+
+  it("query-notes by tag", async () => {
+    await store.createNote("Test", { tags: ["daily"] });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ tag: ["daily"] }) as any[];
+    expect(result).toHaveLength(1);
+  });
+
+  it("query-notes has_tags=false surfaces untagged notes", async () => {
+    await store.createNote("Tagged", { tags: ["daily"] });
+    await store.createNote("Plain");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ has_tags: false, include_content: true }) as any[];
+    expect(result.map((n) => n.content)).toEqual(["Plain"]);
+  });
+
+  it("query-notes has_links=false surfaces orphaned notes", async () => {
+    const a = await store.createNote("Source", { id: "mq-a" });
+    const b = await store.createNote("Target", { id: "mq-b" });
+    await store.createNote("Orphan", { id: "mq-o" });
+    await store.createLink(a.id, b.id, "mentions");
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ has_links: false, include_content: true }) as any[];
+    expect(result.map((n) => n.content)).toEqual(["Orphan"]);
+  });
+
+  it("query-notes metadata operator query routes through the indexed column", async () => {
+    const { declareField } = await import("./indexed-fields.js");
+    declareField(db, "priority", "INTEGER", "project");
+    await store.createNote("high", { metadata: { priority: 5 } });
+    await store.createNote("mid", { metadata: { priority: 3 } });
+    await store.createNote("low", { metadata: { priority: 1 } });
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      metadata: { priority: { gte: 3 } },
+      include_content: true,
+    }) as any[];
+    expect(result.map((n) => n.content).sort()).toEqual(["high", "mid"]);
+  });
+
+  it("query-notes order_by + sort=desc surfaces highest-priority first", async () => {
+    const { declareField } = await import("./indexed-fields.js");
+    declareField(db, "priority", "INTEGER", "project");
+    await store.createNote("p2", { metadata: { priority: 2 } });
+    await store.createNote("p5", { metadata: { priority: 5 } });
     await store.createNote("p1", { metadata: { priority: 1 } });
 
     const tools = generateMcpTools(store);
@@ -1529,6 +2511,35 @@ describe("MCP tools", async () => {
     expect(result[0].id).toBe("near");
   });
 
+  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 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);
@@ -1688,51 +2699,360 @@ describe("MCP tools", async () => {
     expect(fresh.metadata.priority).toBe(0);
     expect(fresh.metadata.status).toBe("active");
   });
-});
 
-// ---- query-notes link expansion ----
+  // ---- 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.
 
-describe("query-notes link expansion", async () => {
-  it("expands a single [[wikilink]] inline in full mode by default", async () => {
-    await store.createNote("# Who I Am\nI teach Taiji.", { path: "Statements/Who" });
-    await store.createNote(
-      "Canon:\nSee [[Statements/Who]] for identity.",
-      { path: "Canon" },
-    );
+  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 query = tools.find((t) => t.name === "query-notes")!;
+    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");
+  });
 
-    const result = await query.execute({
-      id: "Canon",
-      expand_links: true,
-    }) as any;
+  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");
+  });
 
-    expect(result.content).toContain('<expanded path="Statements/Who" mode="full">');
-    expect(result.content).toContain("I teach Taiji.");
-    expect(result.content).toContain("</expanded>");
+  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("summary mode inlines only metadata.summary, not full content", async () => {
-    await store.createNote(
-      "# Long canonical statement\n\n(Many paragraphs of detail follow...)",
-      { path: "Statements/Philosophy", metadata: { summary: "Unforced / wu wei." } },
-    );
-    await store.createNote("Overview: [[Statements/Philosophy]]", { path: "Index" });
+  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 query = tools.find((t) => t.name === "query-notes")!;
+    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 result = await query.execute({
-      id: "Index",
-      expand_links: true,
-      expand_mode: "summary",
-    }) as any;
+    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"] });
 
-    expect(result.content).toContain('mode="summary"');
-    expect(result.content).toContain("Unforced / wu wei.");
-    expect(result.content).not.toContain("Many paragraphs of detail");
+    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"]);
   });
 
-  it("deduplicates: a linked note expanded once, subsequent references marked", async () => {
+  // ---- 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 ----
+
+describe("query-notes link expansion", async () => {
+  it("expands a single [[wikilink]] inline in full mode by default", async () => {
+    await store.createNote("# Who I Am\nI teach Taiji.", { path: "Statements/Who" });
+    await store.createNote(
+      "Canon:\nSee [[Statements/Who]] for identity.",
+      { path: "Canon" },
+    );
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await query.execute({
+      id: "Canon",
+      expand_links: true,
+    }) as any;
+
+    expect(result.content).toContain('<expanded path="Statements/Who" mode="full">');
+    expect(result.content).toContain("I teach Taiji.");
+    expect(result.content).toContain("</expanded>");
+  });
+
+  it("summary mode inlines only metadata.summary, not full content", async () => {
+    await store.createNote(
+      "# Long canonical statement\n\n(Many paragraphs of detail follow...)",
+      { path: "Statements/Philosophy", metadata: { summary: "Unforced / wu wei." } },
+    );
+    await store.createNote("Overview: [[Statements/Philosophy]]", { path: "Index" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await query.execute({
+      id: "Index",
+      expand_links: true,
+      expand_mode: "summary",
+    }) as any;
+
+    expect(result.content).toContain('mode="summary"');
+    expect(result.content).toContain("Unforced / wu wei.");
+    expect(result.content).not.toContain("Many paragraphs of detail");
+  });
+
+  it("deduplicates: a linked note expanded once, subsequent references marked", async () => {
     await store.createNote("target body", { path: "Target" });
     await store.createNote(
       "First [[Target]], then [[Target]] again.",
@@ -1978,3 +3298,1581 @@ 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);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Schema validation — driven by `tags.fields` (post-v17, vault#267)
+// ---------------------------------------------------------------------------
+// Originally written against the `_schemas/<name>` + `_schema_defaults`
+// notes-as-config convention (issue #177); rewritten for vault#246 against
+// the standalone `note_schemas` + `schema_mappings` tables; rewritten again
+// for vault#267 against `tags.fields` after the standalone subsystem retired.
+// The validation surface is intentionally smaller now — schemas are tag-axis
+// only (no path_prefix) and advisory only (no `required` concept).
+
+describe("schema validation (tags.fields)", async () => {
+  it("returns no validation_status when no tag declares fields", 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("returns no validation_status when no tag on the note declares fields", async () => {
+    // A different tag has fields, but the note isn't tagged with it.
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "plain note", tags: ["other"] }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("validation passes (empty warnings) when fields match types", async () => {
+    await store.upsertTagSchema("task", {
+      fields: {
+        priority: { type: "string", enum: ["high", "medium", "low"] },
+        done: { type: "boolean" },
+      },
+    });
+
+    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.upsertTagSchema("task", {
+      fields: { priority: { type: "string" }, done: { type: "boolean" } },
+    });
+
+    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.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "medium", "low"] } },
+    });
+
+    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.upsertTagSchema("task", {
+      fields: { priority: { type: "boolean" } },
+    });
+
+    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" }, // wrong type, but the write still lands
+    }) 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.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    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 tag schema is updated", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "boolean" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
+    expect(result.validation_status.warnings[0].field).toBe("priority");
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+
+    // Re-declare with a string type; cache must reflect the change.
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string" } },
+    });
+    result = await create.execute({
+      content: "y",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
+    expect(result.validation_status.warnings).toEqual([]);
+  });
+
+  it("cache invalidates when a tag schema is deleted", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "boolean" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+
+    await store.deleteTagSchema("task");
+
+    result = await create.execute({
+      content: "y",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("multiple tag schemas combine warnings", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string" } },
+    });
+    await store.upsertTagSchema("project", {
+      fields: { status: { type: "string", enum: ["active", "done"] } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task", "project"],
+      metadata: { priority: 7, status: "WIP" }, // bad: wrong type, bad enum
+    }) as any;
+
+    expect(result.validation_status.schemas.sort()).toEqual(["project", "task"]);
+    expect(result.validation_status.warnings.length).toBe(2);
+  });
+
+  it("legacy `_schemas/<name>` notes are inert post-v17", async () => {
+    // The notes still write/read fine — they're just no longer interpreted
+    // as schema config. Nothing in tags.fields → no validation.
+    await store.createNote("", {
+      path: "_schemas/task",
+      metadata: { fields: { priority: { type: "string" } } },
+    });
+    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();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Schema inheritance via parent_names + `_default` universal parent — vault#270
+// ---------------------------------------------------------------------------
+
+describe("schema inheritance via parent_names (vault#270)", async () => {
+  it("single-parent: child inherits parent's fields", async () => {
+    await store.upsertTagRecord("work", {
+      fields: { project: { type: "string" } },
+    });
+    await store.upsertTagRecord("task", {
+      parent_names: ["work"],
+      fields: { priority: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: 7, project: 42 }, // both wrong type
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(2);
+    const fields = result.validation_status.warnings.map((w: any) => w.field).sort();
+    expect(fields).toEqual(["priority", "project"]);
+  });
+
+  it("multi-parent: child gets union of parents' fields", async () => {
+    await store.upsertTagRecord("work", {
+      fields: { project: { type: "string" } },
+    });
+    await store.upsertTagRecord("publication", {
+      fields: { venue: { type: "string" } },
+    });
+    await store.upsertTagRecord("paper", {
+      parent_names: ["work", "publication"],
+      fields: { title: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["paper"],
+      metadata: { title: 1, project: 2, venue: 3 }, // all wrong type
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(3);
+    const fields = result.validation_status.warnings.map((w: any) => w.field).sort();
+    expect(fields).toEqual(["project", "title", "venue"]);
+  });
+
+  it("diamond: A→B, A→C, B→D, C→D — D's field appears once", async () => {
+    await store.upsertTagRecord("D", {
+      fields: { d_field: { type: "string" } },
+    });
+    await store.upsertTagRecord("B", { parent_names: ["D"] });
+    await store.upsertTagRecord("C", { parent_names: ["D"] });
+    await store.upsertTagRecord("A", { parent_names: ["B", "C"] });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["A"],
+      metadata: { d_field: 999 }, // wrong type
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].field).toBe("d_field");
+    expect(result.validation_status.warnings[0].schema).toBe("D");
+  });
+
+  it("cycle: A→B, B→A — no infinite loop, both fields visible", async () => {
+    await store.upsertTagRecord("A", {
+      parent_names: ["B"],
+      fields: { a_field: { type: "string" } },
+    });
+    await store.upsertTagRecord("B", {
+      parent_names: ["A"],
+      fields: { b_field: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["A"],
+      metadata: { a_field: 1, b_field: 2 }, // both wrong type
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(2);
+    const fields = result.validation_status.warnings.map((w: any) => w.field).sort();
+    expect(fields).toEqual(["a_field", "b_field"]);
+  });
+
+  it("override: child's spec wins over parent's for the same field name", async () => {
+    await store.upsertTagRecord("parent_tag", {
+      fields: { status: { type: "string", enum: ["a", "b"] } },
+    });
+    await store.upsertTagRecord("child_tag", {
+      parent_names: ["parent_tag"],
+      fields: { status: { type: "string", enum: ["x", "y"] } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["child_tag"],
+      metadata: { status: "x" }, // valid under child, invalid under parent
+    }) as any;
+
+    // Child's spec wins → "x" passes the enum check.
+    const enumWarnings = result.validation_status.warnings.filter(
+      (w: any) => w.reason === "enum_mismatch",
+    );
+    expect(enumWarnings.length).toBe(0);
+    // The conflict surfaces as a schema_conflict warning whose `schema` field
+    // names the *winning* tag (child).
+    const conflict = result.validation_status.warnings.find(
+      (w: any) => w.reason === "schema_conflict",
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict.field).toBe("status");
+    expect(conflict.schema).toBe("child_tag");
+  });
+
+  it("conflict warning: two parents declare same field with different specs, first wins", async () => {
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string", enum: ["todo", "doing", "done"] } },
+    });
+    await store.upsertTagRecord("publication", {
+      fields: { status: { type: "string", enum: ["draft", "published"] } },
+    });
+    // parent_names order = ["task", "publication"] → task wins.
+    await store.upsertTagRecord("article_task", {
+      parent_names: ["task", "publication"],
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["article_task"],
+      metadata: { status: "todo" }, // valid under task (winner), invalid under publication
+    }) as any;
+
+    const conflict = result.validation_status.warnings.find(
+      (w: any) => w.reason === "schema_conflict",
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict.field).toBe("status");
+    expect(conflict.schema).toBe("task"); // winner
+    // No enum_mismatch — the value is valid under task's enum.
+    const enumMismatch = result.validation_status.warnings.find(
+      (w: any) => w.reason === "enum_mismatch",
+    );
+    expect(enumMismatch).toBeUndefined();
+  });
+
+  it("`_default` universal parent: untagged note picks up `_default`'s schema", async () => {
+    await store.upsertTagRecord("_default", {
+      fields: { author: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "untagged note",
+      metadata: { author: 42 }, // wrong type
+    }) as any;
+
+    expect(result.validation_status.schemas).toEqual(["_default"]);
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].field).toBe("author");
+  });
+
+  it("`_default` universal parent: tagged note gets `_default` + its tag schema", async () => {
+    await store.upsertTagRecord("_default", {
+      fields: { author: { type: "string" } },
+    });
+    await store.upsertTagRecord("task", {
+      fields: { priority: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { author: 1, priority: 2 }, // both wrong type
+    }) as any;
+
+    expect(result.validation_status.warnings.length).toBe(2);
+    const schemas = new Set(
+      result.validation_status.warnings.map((w: any) => w.schema),
+    );
+    expect(schemas.has("_default")).toBe(true);
+    expect(schemas.has("task")).toBe(true);
+  });
+
+  it("`_default` query expansion: query-notes { tag: '_default' } returns every note", async () => {
+    await store.upsertTagRecord("_default", { description: "universal parent" });
+    const a = await store.createNote("alpha", { tags: ["task"] });
+    const b = await store.createNote("beta", { tags: ["project"] });
+    const g = await store.createNote("gamma"); // untagged
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ tag: "_default" }) as any;
+
+    expect(result.length).toBe(3);
+    const ids = (result as { id: string }[]).map((n) => n.id).sort();
+    expect(ids).toEqual([a.id, b.id, g.id].sort());
+  });
+
+  it("missing parent: non-existent name in parent_names is silently skipped", async () => {
+    await store.upsertTagRecord("task", {
+      parent_names: ["nonexistent_tag"],
+      fields: { priority: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: 999 }, // wrong type
+    }) as any;
+
+    // No error. task's own field still validates.
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].field).toBe("priority");
+  });
+
+  it("`_default` deleted mid-session: cache invalidates, default behavior goes away", async () => {
+    await store.upsertTagRecord("_default", {
+      fields: { author: { type: "string" } },
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({
+      content: "x",
+      metadata: { author: 42 }, // wrong type
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+
+    await store.deleteTag("_default");
+
+    result = await create.execute({
+      content: "y",
+      metadata: { author: 42 },
+    }) as any;
+    expect(result.validation_status).toBeUndefined();
+  });
+
+  it("`_default` + `tagMatch: 'any'` drops the tag filter entirely (every note matches)", async () => {
+    // Folded from PR #272 review (N1). With OR-semantics, `_default` matches
+    // everything → the disjunction collapses regardless of what else is in
+    // the list. Pre-fold this would have narrowed to `task`-tagged notes.
+    await store.upsertTagRecord("_default", { description: "universal parent" });
+    const a = await store.createNote("alpha", { tags: ["task"] });
+    const b = await store.createNote("beta", { tags: ["project"] });
+    const g = await store.createNote("gamma"); // untagged
+
+    const results = await store.queryNotes({ tags: ["_default", "task"], tagMatch: "any" });
+    const ids = results.map((n) => n.id).sort();
+    expect(ids).toEqual([a.id, b.id, g.id].sort());
+  });
+
+  it("`_default` + `tagMatch: 'all'` drops only `_default` from the AND-set", async () => {
+    // Symmetric guard for N1: AND-semantics should NOT collapse — `_default`
+    // is universally satisfied so it can be dropped, but other tags still
+    // narrow the result set.
+    await store.upsertTagRecord("_default", { description: "universal parent" });
+    const a = await store.createNote("alpha", { tags: ["task"] });
+    await store.createNote("beta", { tags: ["project"] });
+    await store.createNote("gamma"); // untagged
+
+    const results = await store.queryNotes({ tags: ["_default", "task"], tagMatch: "all" });
+    expect(results.length).toBe(1);
+    expect(results[0].id).toBe(a.id);
+  });
+
+  it("`searchNotes` with `_default` returns matches from every note (including untagged)", async () => {
+    // Folded from PR #272 review (N2). FTS-backed search now short-circuits
+    // the tag filter when `_default` is requested, matching `queryNotes`.
+    await store.upsertTagRecord("_default", { description: "universal parent" });
+    const a = await store.createNote("findme alpha", { tags: ["task"] });
+    const b = await store.createNote("findme beta"); // untagged
+
+    const results = await store.searchNotes("findme", { tags: ["_default"] });
+    const ids = results.map((n) => n.id).sort();
+    expect(ids).toEqual([a.id, b.id].sort());
+  });
+
+  it("`schema_conflict` warning carries structured `loser_schema`", async () => {
+    // Folded from PR #272 review (N3). Agents shouldn't have to regex
+    // `message` to find the overridden tag — surface it structurally.
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string", enum: ["todo", "done"] } },
+    });
+    await store.upsertTagRecord("publication", {
+      fields: { status: { type: "string", enum: ["draft", "published"] } },
+    });
+    await store.upsertTagRecord("article_task", {
+      parent_names: ["task", "publication"],
+    });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["article_task"],
+      metadata: { status: "todo" },
+    }) as any;
+
+    const conflict = result.validation_status.warnings.find(
+      (w: any) => w.reason === "schema_conflict",
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict.schema).toBe("task"); // winner
+    expect(conflict.loser_schema).toBe("publication"); // overridden
+  });
+
+  it("non-conflict warnings (type/enum mismatch) don't carry `loser_schema`", async () => {
+    // Symmetric guard for N3: `loser_schema` is only meaningful for
+    // schema_conflict; absent on type/enum mismatches.
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+
+    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");
+    expect(result.validation_status.warnings[0].loser_schema).toBeUndefined();
+  });
+
+  it("invalidates schema cache when only parent_names changes (no fields touched)", async () => {
+    // Regression guard: pre-vault#270, parent_names changes only invalidated
+    // the hierarchy cache. Now they must also invalidate the schema cache,
+    // since inheritance walks parent chains at validation time.
+    await store.upsertTagRecord("base", {
+      fields: { tier: { type: "string" } },
+    });
+    await store.upsertTagRecord("derived", { description: "starts orphaned" });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    let result = await create.execute({
+      content: "x",
+      tags: ["derived"],
+      metadata: { tier: 1 },
+    }) as any;
+    expect(result.validation_status).toBeUndefined();
+
+    // Wire up inheritance — fields *not* touched, only parent_names.
+    await store.upsertTagRecord("derived", { parent_names: ["base"] });
+
+    result = await create.execute({
+      content: "y",
+      tags: ["derived"],
+      metadata: { tier: 1 }, // wrong type per base.tier
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].field).toBe("tier");
+    expect(result.validation_status.warnings[0].schema).toBe("base");
+  });
+});
+
+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 v16 → v17 — vault#267 (note_schemas + schema_mappings rip)
+// ---------------------------------------------------------------------------
+
+describe("schema migration v16 → v17", async () => {
+  // Build a v16-shape DB with the standalone note_schemas + schema_mappings
+  // tables and a couple of rows, then run initSchema again. The v17 migration
+  // should drop both tables.
+  async function buildV16ShapeWithLegacyTables(): Promise<Database> {
+    const { Database } = await import("bun:sqlite");
+    const db = new Database(":memory:");
+
+    // Create the v16-era schema fragments by hand. We can't call the post-v17
+    // initSchema to do this — SCHEMA_SQL no longer creates the dropped
+    // tables. Build them manually here so the migration test exercises the
+    // "upgrading from v16" path.
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec(`CREATE TABLE note_schemas (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      fields TEXT,
+      required TEXT,
+      created_at TEXT,
+      updated_at TEXT
+    )`);
+    db.exec(`CREATE TABLE schema_mappings (
+      schema_name TEXT NOT NULL REFERENCES note_schemas(name) ON DELETE CASCADE,
+      match_kind TEXT NOT NULL CHECK (match_kind IN ('path_prefix', 'tag')),
+      match_value TEXT NOT NULL,
+      PRIMARY KEY (schema_name, match_kind, match_value)
+    )`);
+    db.exec("CREATE INDEX idx_schema_mappings_match ON schema_mappings(match_kind, match_value)");
+
+    const now = new Date().toISOString();
+    db.prepare(
+      "INSERT INTO note_schemas (name, description, fields, required, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
+    ).run("task", "A task", '{"priority":{"type":"string"}}', '["priority"]', now, now);
+    db.prepare(
+      "INSERT INTO note_schemas (name, created_at, updated_at) VALUES (?, ?, ?)",
+    ).run("journal-entry", now, now);
+    db.prepare(
+      "INSERT INTO schema_mappings (schema_name, match_kind, match_value) VALUES (?, ?, ?)",
+    ).run("task", "tag", "task");
+    db.prepare(
+      "INSERT INTO schema_mappings (schema_name, match_kind, match_value) VALUES (?, ?, ?)",
+    ).run("journal-entry", "path_prefix", "journal/");
+
+    return db;
+  }
+
+  it("drops note_schemas + schema_mappings tables on upgrade", async () => {
+    const db = await buildV16ShapeWithLegacyTables();
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    const tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_schemas','schema_mappings')",
+    ).all() as { name: string }[];
+    expect(tables).toEqual([]);
+
+    db.close();
+  });
+
+  it("idempotent — running on an already-v17 vault is a no-op", async () => {
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("./schema.ts");
+    const db = new Database(":memory:");
+    initSchema(db); // First run: fresh v17 shape.
+
+    // Sanity: the dropped tables don't exist on a fresh vault.
+    let tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_schemas','schema_mappings')",
+    ).all() as { name: string }[];
+    expect(tables).toEqual([]);
+
+    // Second run shouldn't crash and the tables stay absent.
+    initSchema(db);
+    tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_schemas','schema_mappings')",
+    ).all() as { name: string }[];
+    expect(tables).toEqual([]);
+
+    db.close();
+  });
+
+  it("preserves notes + tags + tokens across the rip", async () => {
+    const db = await buildV16ShapeWithLegacyTables();
+
+    // Bring the rest of the schema up to v16 baseline so notes/tags/tokens
+    // exist, then re-run initSchema (which finishes the v17 migration).
+    const { initSchema } = await import("./schema.ts");
+    initSchema(db);
+
+    // Populate some unrelated state and re-run; nothing else should move.
+    await import("./store.ts").then(async ({ SqliteStore }) => {
+      const s = new SqliteStore(db);
+      await s.createNote("hello", { id: "n1", tags: ["task"] });
+      await s.upsertTagRecord("task", { description: "still here" });
+    });
+    initSchema(db);
+
+    const note = db.prepare("SELECT id, content FROM notes WHERE id = ?").get("n1") as any;
+    expect(note?.content).toBe("hello");
+    const tag = db.prepare("SELECT description FROM tags WHERE name = ?").get("task") as any;
+    expect(tag?.description).toBe("still here");
+
+    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);
+  });
+});
+
+// ---- Vault projection (vault#271) ----
+
+describe("vault projection (vault#271)", async () => {
+  it("projects tags-with-schemas with effective inheritance", async () => {
+    const { buildVaultProjection } = await import("./vault-projection.ts");
+
+    // Universal `_default` parent declares `created_by`.
+    await store.upsertTagRecord("_default", {
+      fields: { created_by: { type: "string", description: "Origin agent" } },
+    });
+    // `person` declares `email` and inherits `created_by`.
+    await store.upsertTagRecord("person", {
+      description: "A person",
+      fields: { email: { type: "string", indexed: true } },
+    });
+    // `employee` extends `person` — should inherit BOTH `email` and `created_by`.
+    await store.upsertTagRecord("employee", {
+      description: "Person who works here",
+      fields: { title: { type: "string" } },
+      parent_names: ["person"],
+    });
+
+    const projection = buildVaultProjection(db);
+
+    const byName = Object.fromEntries(projection.tags.map((t) => [t.name, t]));
+
+    // _default appears (has fields).
+    expect(byName._default).toBeTruthy();
+    expect(byName._default.parents).toEqual([]);
+    expect(byName._default.effective_parents).toEqual([]);
+
+    // person inherits _default's universal field.
+    expect(byName.person.parents).toEqual([]);
+    expect(byName.person.effective_parents).toEqual(["_default"]);
+    expect(Object.keys(byName.person.effective_fields).sort()).toEqual([
+      "created_by",
+      "email",
+    ]);
+    // own fields stay separate
+    expect(Object.keys(byName.person.fields ?? {})).toEqual(["email"]);
+
+    // employee walks person → _default.
+    expect(byName.employee.parents).toEqual(["person"]);
+    expect(byName.employee.effective_parents).toEqual(["person", "_default"]);
+    expect(Object.keys(byName.employee.effective_fields).sort()).toEqual([
+      "created_by",
+      "email",
+      "title",
+    ]);
+  });
+
+  it("catalogs indexed fields across declarers", async () => {
+    const { buildVaultProjection } = await import("./vault-projection.ts");
+
+    // Indexed-field lifecycle is owned by the update-tag MCP tool, not
+    // store.upsertTagRecord — go through the tool so the indexed_fields
+    // table actually gets populated.
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "task",
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await updateTag.execute({
+      tag: "project",
+      fields: {
+        status: { type: "string", indexed: true },
+        priority: { type: "integer", indexed: true },
+      },
+    });
+
+    const projection = buildVaultProjection(db);
+    const byName = Object.fromEntries(projection.indexed_fields.map((f) => [f.name, f]));
+
+    expect(byName.status).toBeTruthy();
+    expect(byName.status.type).toBe("string");
+    expect(byName.status.tags.sort()).toEqual(["project", "task"]);
+
+    expect(byName.priority).toBeTruthy();
+    expect(byName.priority.type).toBe("integer");
+    expect(byName.priority.tags).toEqual(["project"]);
+  });
+
+  it("includes the static query-hint catalog", async () => {
+    const { buildVaultProjection, QUERY_HINTS } = await import("./vault-projection.ts");
+    const projection = buildVaultProjection(db);
+    expect(projection.query_hints.length).toBe(QUERY_HINTS.length);
+    expect(projection.query_hints.some((h) => h.startsWith("query-notes { tag:"))).toBe(true);
+    expect(projection.query_hints.some((h) => h.includes("near:"))).toBe(true);
+  });
+
+  it("includes stats only when requested", async () => {
+    const { buildVaultProjection } = await import("./vault-projection.ts");
+    await store.createNote("a", { tags: ["x"] });
+    await store.createNote("b", { tags: ["x", "y"] });
+
+    const without = buildVaultProjection(db);
+    expect(without.stats).toBeUndefined();
+
+    const withStats = buildVaultProjection(db, { includeStats: true });
+    expect(withStats.stats).toBeTruthy();
+    expect(withStats.stats!.totalNotes).toBe(2);
+    expect(withStats.stats!.tagCount).toBe(2);
+  });
+
+  it("degrades gracefully on an empty vault", async () => {
+    const { buildVaultProjection } = await import("./vault-projection.ts");
+    const projection = buildVaultProjection(db);
+    expect(projection.tags).toEqual([]);
+    expect(projection.indexed_fields).toEqual([]);
+    // Query hints are static — present even on a blank vault.
+    expect(projection.query_hints.length).toBeGreaterThan(0);
+  });
+
+  it("renders a markdown brief listing tags-with-schemas and indexed fields", async () => {
+    const { buildVaultProjection, projectionToMarkdown } = await import(
+      "./vault-projection.ts"
+    );
+
+    await store.createNote("a", { tags: ["person"] });
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    await updateTag.execute({
+      tag: "person",
+      description: "A person",
+      fields: { email: { type: "string", indexed: true } },
+    });
+
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "test",
+      description: "My vault",
+      projection,
+    });
+
+    expect(md).toContain('You are connected to Parachute Vault "test"');
+    expect(md).toContain("My vault");
+    expect(md).toContain("1 tag with schemas: person");
+    expect(md).toContain("Indexed metadata fields");
+    expect(md).toContain("email");
+    expect(md).toContain("#person");
+    expect(md).toContain("vault-info");
+    expect(md).toContain("list-tags { include_schema: true }");
+  });
+
+  it("markdown brief degrades gracefully when no schemas declared", async () => {
+    const { buildVaultProjection, projectionToMarkdown } = await import(
+      "./vault-projection.ts"
+    );
+
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "fresh",
+      description: null,
+      projection,
+    });
+
+    expect(md).toContain('Parachute Vault "fresh"');
+    expect(md).toContain("No tag schemas declared");
+    expect(md).toContain("No indexed metadata fields");
+    expect(md).toContain("Querying");
+  });
+
+  it("markdown brief stays under ~5K tokens for a 50-tags-with-schemas vault", async () => {
+    const { buildVaultProjection, projectionToMarkdown } = await import(
+      "./vault-projection.ts"
+    );
+
+    for (let i = 0; i < 50; i++) {
+      await store.upsertTagRecord(`schema_tag_${i}`, {
+        description: `Description for tag ${i} — covers what this tag is used for in the vault.`,
+        fields: {
+          [`field_${i}_a`]: { type: "string", indexed: i % 3 === 0 },
+          [`field_${i}_b`]: { type: "integer" },
+        },
+      });
+    }
+
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "big",
+      description: "Big test vault",
+      projection,
+    });
+
+    // Rough token approximation: 1 token ≈ 4 chars. Budget: 5K tokens.
+    const approxTokens = md.length / 4;
+    expect(approxTokens).toBeLessThan(5000);
+  });
+});