@openparachute/vault 0.4.0 → 0.4.4-rc.11

package/core/src/core.test.ts

@@ -357,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"]);
@@ -386,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);
@@ -397,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();
@@ -413,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"] });
@@ -775,6 +1089,58 @@ describe("queryNotes", async () => {
       }) 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 () => {
@@ -1161,16 +1527,22 @@ describe("MCP tools", async () => {
     expect(names).toContain("list-tags");
     expect(names).toContain("update-tag");
     expect(names).toContain("delete-tag");
-    expect(names).toContain("list-note-schemas");
-    expect(names).toContain("update-note-schema");
-    expect(names).toContain("delete-note-schema");
-    expect(names).toContain("list-schema-mappings");
-    expect(names).toContain("set-schema-mapping");
-    expect(names).toContain("delete-schema-mapping");
     expect(names).toContain("find-path");
-    expect(names).toContain("synthesize-notes");
     expect(names).toContain("vault-info");
-    expect(tools).toHaveLength(16);
+    // 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);
   });
 
   it("create-note tool works", async () => {
@@ -1391,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);
@@ -2205,183 +2667,6 @@ describe("MCP tools", async () => {
     expect(result.relationships).toEqual(["mentions", "related-to"]);
   });
 
-  // ---- synthesize-notes ----
-
-  it("synthesize-notes rejects when neither anchor nor query is supplied", async () => {
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({}) as any;
-    expect(result.error).toMatch(/at least one of `anchor` or `query`/);
-  });
-
-  it("synthesize-notes rejects an unknown anchor", async () => {
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "does-not-exist" }) as any;
-    expect(result.error).toMatch(/Anchor note not found/);
-  });
-
-  it("synthesize-notes returns anchor + linked neighbors ranked", async () => {
-    await store.createNote("Hub note", { id: "hub", tags: ["topic"] });
-    await store.createNote("Direct neighbor", { id: "n1" });
-    await store.createNote("Two-hop neighbor", { id: "n2" });
-    await store.createNote("Unrelated", { id: "u1" });
-    await store.createLink("hub", "n1", "mentions");
-    await store.createLink("n1", "n2", "mentions");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "hub", depth: 2 }) as any;
-
-    const ids = result.notes.map((n: any) => n.id);
-    expect(ids).toContain("hub");
-    expect(ids).toContain("n1");
-    expect(ids).toContain("n2");
-    expect(ids).not.toContain("u1");
-    // Anchor ranks first; one-hop beats two-hop.
-    expect(ids[0]).toBe("hub");
-    expect(ids.indexOf("n1")).toBeLessThan(ids.indexOf("n2"));
-    expect(result.notes[0].sources).toContain("anchor");
-    expect(result.notes[0].distance).toBe(0);
-    expect(result.topic.anchor).toEqual({ id: "hub", path: null });
-  });
-
-  it("synthesize-notes returns FTS hits when only query is supplied", async () => {
-    await store.createNote("Octopus thoughts: ink and color", { id: "o1" });
-    await store.createNote("Squid thoughts: deep blue", { id: "s1" });
-    await store.createNote("Recipe for octopus salad", { id: "o2" });
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ query: "octopus" }) as any;
-
-    const ids = result.notes.map((n: any) => n.id);
-    expect(ids).toContain("o1");
-    expect(ids).toContain("o2");
-    expect(ids).not.toContain("s1");
-    expect(result.notes[0].sources).toContain("search");
-    expect(result.notes[0]).toHaveProperty("fts_rank");
-    expect(result.topic.query).toBe("octopus");
-  });
-
-  it("synthesize-notes applies scope.tags filter (any-match)", async () => {
-    await store.createNote("Anchor", { id: "a" });
-    await store.createNote("Tagged neighbor", { id: "t1", tags: ["alpha"] });
-    await store.createNote("Other neighbor", { id: "t2", tags: ["beta"] });
-    await store.createLink("a", "t1", "mentions");
-    await store.createLink("a", "t2", "mentions");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "a", scope: { tags: ["alpha"] } }) as any;
-
-    const ids = result.notes.map((n: any) => n.id);
-    expect(ids).toContain("t1");
-    expect(ids).not.toContain("t2");
-    expect(ids).not.toContain("a"); // anchor itself has no tags
-  });
-
-  it("synthesize-notes applies scope.path prefix filter", async () => {
-    await store.createNote("Anchor", { id: "a" });
-    await store.createNote("In scope", { id: "p1", path: "Projects/Alpha/notes" });
-    await store.createNote("Out of scope", { id: "p2", path: "People/Bob" });
-    await store.createLink("a", "p1", "mentions");
-    await store.createLink("a", "p2", "mentions");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "a", scope: { path: "projects/" } }) as any;
-
-    const ids = result.notes.map((n: any) => n.id);
-    expect(ids).toContain("p1");
-    expect(ids).not.toContain("p2");
-  });
-
-  it("synthesize-notes respects limit and sets truncated flag", async () => {
-    await store.createNote("Anchor", { id: "anchor" });
-    for (let i = 0; i < 5; i++) {
-      await store.createNote(`Neighbor ${i}`, { id: `n${i}` });
-      await store.createLink("anchor", `n${i}`, "mentions");
-    }
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "anchor", limit: 3 }) as any;
-
-    expect(result.notes).toHaveLength(3);
-    expect(result.truncated).toBe(true);
-  });
-
-  it("synthesize-notes connections include only links between returned notes", async () => {
-    await store.createNote("Anchor", { id: "a" });
-    await store.createNote("In set", { id: "b" });
-    await store.createNote("Excluded", { id: "c" });
-    await store.createLink("a", "b", "mentions");
-    await store.createLink("a", "c", "mentions");
-    await store.createLink("b", "c", "related-to");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "a", depth: 1, limit: 2 }) as any;
-
-    const ids = new Set(result.notes.map((n: any) => n.id));
-    for (const c of result.connections) {
-      expect(ids.has(c.source)).toBe(true);
-      expect(ids.has(c.target)).toBe(true);
-    }
-    expect(result.connections.some((c: any) => c.target === "c")).toBe(false);
-  });
-
-  it("synthesize-notes timeline orders oldest → newest", async () => {
-    await store.createNote("Old", { id: "old", created_at: "2024-01-01T00:00:00.000Z" });
-    await store.createNote("Mid", { id: "mid", created_at: "2025-01-01T00:00:00.000Z" });
-    await store.createNote("New", { id: "new", created_at: "2026-01-01T00:00:00.000Z" });
-    await store.createLink("new", "mid", "mentions");
-    await store.createLink("mid", "old", "mentions");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "new", depth: 2 }) as any;
-
-    const ids = result.timeline.map((t: any) => t.id);
-    expect(ids).toEqual(["old", "mid", "new"]);
-  });
-
-  it("synthesize-notes tag distribution counts tags across results", async () => {
-    await store.createNote("Anchor", { id: "a", tags: ["alpha", "beta"] });
-    await store.createNote("N1", { id: "n1", tags: ["alpha"] });
-    await store.createNote("N2", { id: "n2", tags: ["alpha", "gamma"] });
-    await store.createLink("a", "n1", "mentions");
-    await store.createLink("a", "n2", "mentions");
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-    const result = await synth.execute({ anchor: "a" }) as any;
-
-    const tagMap = new Map(result.tags.map((t: any) => [t.name, t.count]));
-    expect(tagMap.get("alpha")).toBe(3);
-    expect(tagMap.get("beta")).toBe(1);
-    expect(tagMap.get("gamma")).toBe(1);
-    expect(result.tags[0].name).toBe("alpha");
-  });
-
-  it("synthesize-notes include_content controls snippet vs full body", async () => {
-    const longBody = "x".repeat(500);
-    await store.createNote(longBody, { id: "long", path: "Long" });
-
-    const tools = generateMcpTools(store);
-    const synth = tools.find((t) => t.name === "synthesize-notes")!;
-
-    const snippetResult = await synth.execute({ anchor: "long" }) as any;
-    expect(snippetResult.notes[0]).toHaveProperty("snippet");
-    expect(snippetResult.notes[0]).not.toHaveProperty("content");
-    expect(snippetResult.notes[0].snippet.length).toBeLessThanOrEqual(200);
-
-    const fullResult = await synth.execute({ anchor: "long", include_content: true }) as any;
-    expect(fullResult.notes[0].content).toBe(longBody);
-    expect(fullResult.notes[0]).not.toHaveProperty("snippet");
-  });
-
   it("create-note via store triggers wikilink sync", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -3184,64 +3469,42 @@ describe("tag hierarchy (tags.parent_names)", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Note schemas — table-driven (post-v15: `note_schemas` + `schema_mappings`)
+// 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: the
-// authoring surface is now `store.upsertNoteSchema` + `store.setSchemaMapping`
-// and the legacy notes are inert (left in place as audit trail).
+// 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("note schemas (note_schemas + schema_mappings)", async () => {
-  it("returns no validation_status when no schemas are configured", async () => {
+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("attaches validation_status when a schema matches by tag", async () => {
-    await store.upsertNoteSchema("task", {
-      description: "A task",
-      fields: { priority: { type: "string", enum: ["high", "medium", "low"] } },
-      required: ["priority"],
-    });
-    await store.setSchemaMapping("task", "tag", "task");
-
-    const tools = generateMcpTools(store);
-    const create = tools.find((t) => t.name === "create-note")!;
-    const result = await create.execute({ content: "do thing", tags: ["task"] }) as any;
-
-    expect(result.validation_status).toBeTruthy();
-    expect(result.validation_status.schemas).toEqual(["task"]);
-    expect(result.validation_status.warnings.length).toBe(1);
-    expect(result.validation_status.warnings[0].reason).toBe("missing_required");
-    expect(result.validation_status.warnings[0].field).toBe("priority");
-  });
-
-  it("attaches validation_status when a schema matches by path prefix", async () => {
-    await store.upsertNoteSchema("journal-entry", {
-      fields: { mood: { type: "string" } },
-      required: ["mood"],
+  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" } },
     });
-    await store.setSchemaMapping("journal-entry", "path_prefix", "journal/");
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;
-    const result = await create.execute({ content: "today", path: "journal/2026-04-29" }) as any;
-
-    expect(result.validation_status.schemas).toEqual(["journal-entry"]);
-    expect(result.validation_status.warnings[0].reason).toBe("missing_required");
+    const result = await create.execute({ content: "plain note", tags: ["other"] }) as any;
+    expect(result.validation_status).toBeUndefined();
   });
 
-  it("validation passes (empty warnings) when required fields are present and types match", async () => {
-    await store.upsertNoteSchema("task", {
+  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" },
       },
-      required: ["priority"],
     });
-    await store.setSchemaMapping("task", "tag", "task");
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;
@@ -3256,10 +3519,9 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
   });
 
   it("type_mismatch warning when a field's value is the wrong type", async () => {
-    await store.upsertNoteSchema("task", {
+    await store.upsertTagSchema("task", {
       fields: { priority: { type: "string" }, done: { type: "boolean" } },
     });
-    await store.setSchemaMapping("task", "tag", "task");
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;
@@ -3275,10 +3537,9 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
   });
 
   it("enum_mismatch warning when a field's value is outside the declared enum", async () => {
-    await store.upsertNoteSchema("task", {
+    await store.upsertTagSchema("task", {
       fields: { priority: { type: "string", enum: ["high", "medium", "low"] } },
     });
-    await store.setSchemaMapping("task", "tag", "task");
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;
@@ -3292,12 +3553,17 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
   });
 
   it("validation never blocks the write — note exists with warnings attached", async () => {
-    await store.upsertNoteSchema("task", { required: ["priority"] });
-    await store.setSchemaMapping("task", "tag", "task");
+    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"] }) as any;
+    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);
@@ -3308,11 +3574,9 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
   });
 
   it("update-note also surfaces validation_status", async () => {
-    await store.upsertNoteSchema("task", {
+    await store.upsertTagSchema("task", {
       fields: { priority: { type: "string", enum: ["high", "low"] } },
-      required: ["priority"],
     });
-    await store.setSchemaMapping("task", "tag", "task");
     const note = await store.createNote("body", { tags: ["task"], metadata: { priority: "high" } });
 
     const tools = generateMcpTools(store);
@@ -3326,98 +3590,83 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
     expect(result.validation_status.warnings[0].reason).toBe("enum_mismatch");
   });
 
-  it("cache invalidates when a schema mapping is removed", async () => {
-    await store.upsertNoteSchema("task", { required: ["a"] });
-    await store.setSchemaMapping("task", "tag", "task");
-
-    const tools = generateMcpTools(store);
-    const create = tools.find((t) => t.name === "create-note")!;
-    let result = await create.execute({ content: "x", tags: ["task"] }) as any;
-    expect(result.validation_status.warnings[0].field).toBe("a");
-
-    await store.deleteSchemaMapping("task", "tag", "task");
-
-    result = await create.execute({ content: "y", tags: ["task"] }) as any;
-    expect(result.validation_status).toBeUndefined();
-  });
-
-  it("cache invalidates when a schema is updated", async () => {
-    await store.upsertNoteSchema("task", { required: ["a"] });
-    await store.setSchemaMapping("task", "tag", "task");
+  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"] }) as any;
-    expect(result.validation_status.warnings[0].field).toBe("a");
+    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 different required field; cache must reflect the change.
-    await store.upsertNoteSchema("task", { required: ["b"] });
-    result = await create.execute({ content: "y", tags: ["task"] }) as any;
-    expect(result.validation_status.warnings[0].field).toBe("b");
+    // 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 schema is deleted (cascades mappings)", async () => {
-    await store.upsertNoteSchema("task", { required: ["a"] });
-    await store.setSchemaMapping("task", "tag", "task");
+  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"] }) as any;
-    expect(result.validation_status.warnings[0].field).toBe("a");
+    let result = await create.execute({
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
 
-    await store.deleteNoteSchema("task");
-    // FK CASCADE drops the mapping too.
-    expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
+    await store.deleteTagSchema("task");
 
-    result = await create.execute({ content: "y", tags: ["task"] }) as any;
+    result = await create.execute({
+      content: "y",
+      tags: ["task"],
+      metadata: { priority: "high" },
+    }) as any;
     expect(result.validation_status).toBeUndefined();
   });
 
-  it("longest path prefix wins when multiple match", async () => {
-    await store.upsertNoteSchema("journal-day", { required: ["mood"] });
-    await store.upsertNoteSchema("journal-broad", { required: ["topic"] });
-    await store.setSchemaMapping("journal-broad", "path_prefix", "journal/");
-    await store.setSchemaMapping("journal-day", "path_prefix", "journal/2026/");
-
-    const tools = generateMcpTools(store);
-    const create = tools.find((t) => t.name === "create-note")!;
-    const result = await create.execute({ content: "x", path: "journal/2026/april" }) as any;
-    expect(result.validation_status.schemas).toEqual(["journal-day"]);
-  });
-
-  it("multiple schemas can apply (path + tag combine warnings)", async () => {
-    await store.upsertNoteSchema("journal-entry", { required: ["mood"] });
-    await store.upsertNoteSchema("task", { required: ["priority"] });
-    await store.setSchemaMapping("journal-entry", "path_prefix", "journal/");
-    await store.setSchemaMapping("task", "tag", "task");
+  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",
-      path: "journal/today",
-      tags: ["task"],
+      tags: ["task", "project"],
+      metadata: { priority: 7, status: "WIP" }, // bad: wrong type, bad enum
     }) as any;
 
-    expect(result.validation_status.schemas.sort()).toEqual(["journal-entry", "task"]);
+    expect(result.validation_status.schemas.sort()).toEqual(["project", "task"]);
     expect(result.validation_status.warnings.length).toBe(2);
   });
 
-  it("a schema with no mappings is harmless (no validation)", async () => {
-    await store.upsertNoteSchema("orphan", { required: ["x"] });
-
-    const tools = generateMcpTools(store);
-    const create = tools.find((t) => t.name === "create-note")!;
-    const result = await create.execute({ content: "anything" }) as any;
-    expect(result.validation_status).toBeUndefined();
-  });
-
-  it("legacy `_schemas/<name>` notes are inert post-v15", async () => {
+  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 note_schemas/schema_mappings → no validation.
+    // as schema config. Nothing in tags.fields → no validation.
     await store.createNote("", {
       path: "_schemas/task",
-      metadata: { required: ["priority"] },
+      metadata: { fields: { priority: { type: "string" } } },
     });
     await store.createNote("", {
       path: "_schema_defaults",
@@ -3429,82 +3678,499 @@ describe("note schemas (note_schemas + schema_mappings)", async () => {
     const result = await create.execute({ content: "x", tags: ["task"] }) as any;
     expect(result.validation_status).toBeUndefined();
   });
-});
-
-// ---------------------------------------------------------------------------
-// note_schemas + schema_mappings — direct CRUD (vault#246)
-// ---------------------------------------------------------------------------
-
-describe("note_schemas / schema_mappings CRUD", async () => {
-  it("upsertNoteSchema partial-merge: undefined preserves, null clears", async () => {
-    await store.upsertNoteSchema("task", {
-      description: "A task",
-      fields: { priority: { type: "string" } },
-      required: ["priority"],
-    });
-
-    // description omitted → preserved
-    await store.upsertNoteSchema("task", { required: ["priority", "due"] });
-    let row = await store.getNoteSchema("task");
-    expect(row?.description).toBe("A task");
-    expect(row?.required).toEqual(["priority", "due"]);
 
-    // description null → cleared
-    await store.upsertNoteSchema("task", { description: null });
-    row = await store.getNoteSchema("task");
-    expect(row?.description).toBeNull();
-    expect(row?.required).toEqual(["priority", "due"]); // still preserved
-  });
-
-  it("empty `required: []` collapses to null", async () => {
-    await store.upsertNoteSchema("task", { required: ["a", "b"] });
-    await store.upsertNoteSchema("task", { required: [] });
-    const row = await store.getNoteSchema("task");
-    expect(row?.required).toBeNull();
-  });
+  // vault#310 — integer type validation. JSON has no separate integer
+  // type, so a JSON number with zero fractional part (`5`, `5.0`) must
+  // pass an `integer`-typed field. Pre-fix, the validator had no
+  // `"integer"` case at all — falling through the switch returned
+  // undefined and every integer-typed field warned `type_mismatch` on
+  // legitimate values. Gitcoin Brain's drift detector emits JSON for
+  // diffs; every `kpi: 3` triggered the false-positive and buried the
+  // real warnings.
 
-  it("setSchemaMapping is idempotent (composite PK)", async () => {
-    await store.upsertNoteSchema("task", {});
-    await store.setSchemaMapping("task", "tag", "task");
-    await store.setSchemaMapping("task", "tag", "task"); // re-set same triple
-    const mappings = await store.listSchemaMappings({ schema_name: "task" });
-    expect(mappings.length).toBe(1);
+  it("integer-typed field: JSON integer (5) passes (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
   });
 
-  it("setSchemaMapping rejects unknown match_kind", async () => {
-    await store.upsertNoteSchema("task", {});
-    await expect(
-      store.setSchemaMapping("task", "BOGUS" as any, "task"),
-    ).rejects.toThrow(/match_kind/);
+  it("integer-typed field: JSON `5.0` (zero-fractional) passes (vault#310)", async () => {
+    // 5.0 is the canonical Gitcoin shape — JSON.parse decodes the
+    // emitted JSON number as a JS Number; the JS Number for `5.0` is
+    // identical to `5` so Number.isInteger reports true. This is the
+    // load-bearing assertion for the Gitcoin drift-detector use case.
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
   });
 
-  it("setSchemaMapping fails (FK) when schema doesn't exist", async () => {
-    await expect(
-      store.setSchemaMapping("missing", "tag", "x"),
-    ).rejects.toThrow();
+  it("integer-typed field: JSON `5.5` (non-zero fractional) warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.5 },
+    }) 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("count");
   });
 
-  it("deleteNoteSchema cascades schema_mappings (FK ON DELETE CASCADE)", async () => {
-    await store.upsertNoteSchema("task", {});
-    await store.setSchemaMapping("task", "tag", "task");
-    await store.setSchemaMapping("task", "path_prefix", "Tasks/");
-    expect((await store.listSchemaMappings({ schema_name: "task" })).length).toBe(2);
+  it("integer-typed field: string `\"5\"` warns type_mismatch (no string→number coercion) (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: "5" },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
 
-    expect(await store.deleteNoteSchema("task")).toBe(true);
-    expect(await store.listSchemaMappings({ schema_name: "task" })).toEqual([]);
-    expect(await store.deleteNoteSchema("task")).toBe(false); // already gone
+  it("integer-typed field: edge `5.0000000000001` warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0000000000001 },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
   });
 
-  it("listSchemaMappings filters by schema_name and match_kind", async () => {
-    await store.upsertNoteSchema("a", {});
-    await store.upsertNoteSchema("b", {});
-    await store.setSchemaMapping("a", "tag", "a-tag");
-    await store.setSchemaMapping("a", "path_prefix", "A/");
-    await store.setSchemaMapping("b", "tag", "b-tag");
+  it("integer-typed field: boolean warns type_mismatch (vault#310)", async () => {
+    // Pin that boolean is rejected (Number.isInteger(true) returns
+    // false, but extra coverage in case anyone "improves" the check
+    // with a looser predicate later).
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: true },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
 
-    expect((await store.listSchemaMappings({ schema_name: "a" })).length).toBe(2);
-    expect((await store.listSchemaMappings({ match_kind: "tag" })).length).toBe(2);
-    expect((await store.listSchemaMappings({ schema_name: "a", match_kind: "tag" })).length).toBe(1);
+  // Note on NaN/Infinity: those values pass through
+  // JSON.stringify as `null`, then the validator's null short-circuit
+  // (schema-defaults.ts:327 — "value === null → skip") filters them out
+  // before reaching the type check. We can't observe them in
+  // validation_status from this layer; a dedicated unit test against
+  // `valueMatchesType` would catch the case at the inner boundary.
+  // Pinned at the next layer down:
+
+  it("valueMatchesType('integer', ...) rejects NaN / Infinity (vault#310)", async () => {
+    // Reach the unexported helper indirectly via validateNote on a
+    // hand-built resolved-schemas + metadata where the value is the
+    // actual NaN/Infinity (no JSON round-trip).
+    const { validateNote, loadSchemaConfig } = await import("./schema-defaults.js");
+    // Seed via the public surface, then load the resolved schemas
+    // snapshot.
+    await store.upsertTagSchema("k", { fields: { c: { type: "integer" } } });
+    const resolved = loadSchemaConfig((store as any).db);
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.NaN } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.POSITIVE_INFINITY } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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");
   });
 });
 
@@ -3904,199 +4570,111 @@ describe("schema migration v13 → v14", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Schema migration v14 → v15 — vault#246 (_schemas/* + _schema_defaults retired)
+// Schema migration v16 → v17 — vault#267 (note_schemas + schema_mappings rip)
 // ---------------------------------------------------------------------------
 
-describe("schema migration v14 → v15", async () => {
-  // Build a v14-shape DB by:
-  //   1. Calling initSchema (so we get the full v15 shape, including
-  //      note_schemas / schema_mappings tables).
-  //   2. Manually wiping the new tables, then writing the legacy
-  //      `_schemas/<name>` and `_schema_defaults` notes.
-  //   3. Re-running initSchema — the migration's short-circuit (empty
-  //      destination tables) should kick in and copy the data over.
-  async function buildV14ShapeWithLegacyNotes(): Promise<Database> {
+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 { initSchema } = await import("./schema.ts");
     const db = new Database(":memory:");
-    initSchema(db);
 
-    // Write the legacy notes that the v14 vaults stored config in.
-    const now = new Date().toISOString();
-    const insertNote = db.prepare(
-      "INSERT INTO notes (id, content, path, metadata, created_at) VALUES (?, ?, ?, ?, ?)",
-    );
-    insertNote.run(
-      "s1",
-      "",
-      "_schemas/task",
-      JSON.stringify({
-        description: "A task",
-        fields: { priority: { type: "string", enum: ["high", "low"] } },
-        required: ["priority"],
-      }),
-      now,
-    );
-    insertNote.run(
-      "s2",
-      "",
-      "_schemas/journal-entry",
-      JSON.stringify({ fields: { mood: { type: "string" } } }),
-      now,
-    );
-    insertNote.run(
-      "d1",
-      "",
-      "_schema_defaults",
-      JSON.stringify({
-        path_prefixes: { "journal/": "journal-entry" },
-        tags: { task: "task", "follow-up": "task" },
-      }),
-      now,
-    );
+    // 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)");
 
-    // Wipe the destination tables so the migration short-circuit doesn't
-    // fire (otherwise initSchema treats them as already migrated).
-    db.exec("DELETE FROM schema_mappings");
-    db.exec("DELETE FROM note_schemas");
+    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("copies `_schemas/<name>` notes → note_schemas with description / fields / required", async () => {
-    const db = await buildV14ShapeWithLegacyNotes();
+  it("drops note_schemas + schema_mappings tables on upgrade", async () => {
+    const db = await buildV16ShapeWithLegacyTables();
     const { initSchema } = await import("./schema.ts");
     initSchema(db);
 
-    const taskRow = db.prepare(
-      "SELECT description, fields, required FROM note_schemas WHERE name = 'task'",
-    ).get() as any;
-    expect(taskRow.description).toBe("A task");
-    expect(JSON.parse(taskRow.fields).priority.enum).toEqual(["high", "low"]);
-    expect(JSON.parse(taskRow.required)).toEqual(["priority"]);
-
-    const journalRow = db.prepare(
-      "SELECT description, fields FROM note_schemas WHERE name = 'journal-entry'",
-    ).get() as any;
-    expect(journalRow.description).toBeNull();
-    expect(JSON.parse(journalRow.fields).mood.type).toBe("string");
+    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("copies `_schema_defaults` → schema_mappings (path_prefixes + tags)", async () => {
-    const db = await buildV14ShapeWithLegacyNotes();
-    const { initSchema } = await import("./schema.ts");
-    initSchema(db);
-
-    const mappings = db.prepare(
-      "SELECT schema_name, match_kind, match_value FROM schema_mappings ORDER BY match_kind, match_value",
-    ).all() as { schema_name: string; match_kind: string; match_value: string }[];
-    expect(mappings).toEqual([
-      { schema_name: "journal-entry", match_kind: "path_prefix", match_value: "journal/" },
-      { schema_name: "task", match_kind: "tag", match_value: "follow-up" },
-      { schema_name: "task", match_kind: "tag", match_value: "task" },
-    ]);
-
-    db.close();
-  });
-
-  it("auto-creates a stub schema row when a mapping references an undeclared schema (FK)", async () => {
+  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);
-
-    // Only a defaults note — no `_schemas/orphan` definition.
-    db.prepare(
-      "INSERT INTO notes (id, content, path, metadata, created_at) VALUES (?, ?, ?, ?, ?)",
-    ).run(
-      "d",
-      "",
-      "_schema_defaults",
-      JSON.stringify({ tags: { orphan: "orphan" } }),
-      new Date().toISOString(),
-    );
-    db.exec("DELETE FROM schema_mappings");
-    db.exec("DELETE FROM note_schemas");
-
-    initSchema(db);
-
-    // Stub schema row was created so the FK on schema_mappings holds.
-    const stub = db.prepare("SELECT name FROM note_schemas WHERE name = 'orphan'").get();
-    expect(stub).toBeTruthy();
-    const mapping = db.prepare(
-      "SELECT match_kind, match_value FROM schema_mappings WHERE schema_name = 'orphan'",
-    ).get() as any;
-    expect(mapping).toEqual({ match_kind: "tag", match_value: "orphan" });
+    initSchema(db); // First run: fresh v17 shape.
 
-    db.close();
-  });
+    // 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([]);
 
-  it("legacy `_schemas/*` and `_schema_defaults` notes are left in place (audit trail)", async () => {
-    const db = await buildV14ShapeWithLegacyNotes();
-    const { initSchema } = await import("./schema.ts");
+    // Second run shouldn't crash and the tables stay absent.
     initSchema(db);
-
-    const schemaNote = db.prepare("SELECT id FROM notes WHERE path = '_schemas/task'").get();
-    expect(schemaNote).toBeTruthy();
-    const defaultsNote = db.prepare("SELECT id FROM notes WHERE path = '_schema_defaults'").get();
-    expect(defaultsNote).toBeTruthy();
+    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("is idempotent — second initSchema doesn't re-copy or duplicate rows", async () => {
-    const db = await buildV14ShapeWithLegacyNotes();
-    const { initSchema } = await import("./schema.ts");
-    initSchema(db);
-
-    const schemaCount1 = (db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c;
-    const mappingCount1 = (db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c;
-
-    initSchema(db);
-
-    const schemaCount2 = (db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c;
-    const mappingCount2 = (db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c;
-    expect(schemaCount2).toBe(schemaCount1);
-    expect(mappingCount2).toBe(mappingCount1);
+  it("preserves notes + tags + tokens across the rip", async () => {
+    const db = await buildV16ShapeWithLegacyTables();
 
-    db.close();
-  });
-
-  it("no legacy notes → migration is a no-op (empty tables)", async () => {
-    const { Database } = await import("bun:sqlite");
+    // 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");
-    const db = new Database(":memory:");
     initSchema(db);
 
-    expect((db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c).toBe(0);
-    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBe(0);
-
-    db.close();
-  });
-
-  // Short-circuit uses `||` not `&&`: a vault with schemas-but-no-mappings
-  // is a valid post-v15 state. Legacy `_schemas/*` notes left around from
-  // a prior import shouldn't get re-folded on every boot. (The mirror case —
-  // mappings-but-no-schemas — is structurally impossible because the
-  // schema_mappings FK to note_schemas has ON DELETE CASCADE.)
-  it("doesn't re-run when only one destination table is non-empty", async () => {
-    const db = await buildV14ShapeWithLegacyNotes();
-    const { initSchema } = await import("./schema.ts");
+    // 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);
 
-    // After first run: tables populated, legacy notes still in `notes`.
-    expect((db.prepare("SELECT COUNT(*) as c FROM note_schemas").get() as any).c).toBeGreaterThan(0);
-    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBeGreaterThan(0);
-    expect((db.prepare("SELECT COUNT(*) as c FROM notes WHERE path GLOB '_schemas/*'").get() as any).c).toBeGreaterThan(0);
-
-    // Wipe mappings only; schemas remain non-empty. With the buggy `&&`
-    // short-circuit, the migration would re-scan `_schema_defaults` and
-    // rebuild the mappings table. With `||` it correctly no-ops.
-    db.exec("DELETE FROM schema_mappings");
-    initSchema(db);
-    expect((db.prepare("SELECT COUNT(*) as c FROM schema_mappings").get() as any).c).toBe(0);
+    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();
   });
@@ -4223,3 +4801,194 @@ describe("tag-scope auth (post-v14 hierarchy)", async () => {
     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);
+  });
+});