@openparachute/vault 0.2.4 → 0.3.0

package/core/src/core.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
+import { initSchema } from "./schema.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -68,7 +69,11 @@ describe("notes", async () => {
     const updated = await store.updateNote(note.id, { created_at: newDate });
     expect(updated.createdAt).toBe(newDate);
     expect(updated.content).toBe("Test"); // content unchanged
-    expect(updated.updatedAt).not.toBe(note.updatedAt); // updated_at bumped
+    // updated_at is bumped to "now" by the update path. Can't strictly
+    // differ from note.updatedAt (same-ms collision possible) but must be
+    // monotonically non-decreasing from the prior value.
+    expect(updated.updatedAt).toBeTruthy();
+    expect(updated.updatedAt! >= note.updatedAt!).toBe(true);
   });
 
   it("updates metadata and created_at together", async () => {
@@ -87,6 +92,36 @@ describe("notes", async () => {
     expect(updated.createdAt).toBe(note.createdAt);
   });
 
+  it("sets updatedAt === createdAt on insert", async () => {
+    const note = await store.createNote("Fresh");
+    expect(note.updatedAt).toBe(note.createdAt);
+    const fetched = (await store.getNote(note.id))!;
+    expect(fetched.updatedAt).toBe(fetched.createdAt);
+  });
+
+  it("create-insert updatedAt respects an explicit created_at", async () => {
+    const note = await store.createNote("Imported", {
+      created_at: "2024-02-14T09:30:00.000Z",
+    });
+    expect(note.createdAt).toBe("2024-02-14T09:30:00.000Z");
+    expect(note.updatedAt).toBe("2024-02-14T09:30:00.000Z");
+  });
+
+  it("fresh note: if_updated_at with createdAt as the token succeeds", async () => {
+    // Regression guard: clients that pass `updatedAt ?? createdAt` as the
+    // OC token used to hit a CONFLICT on the very first edit because stored
+    // `updated_at` was NULL. Insert-time backfill removes that class of
+    // spurious conflict.
+    const note = await store.createNote("First");
+    const updated = await store.updateNote(note.id, {
+      content: "Second",
+      if_updated_at: note.createdAt,
+    });
+    expect(updated.content).toBe("Second");
+    expect(updated.updatedAt).toBeTruthy();
+    expect(updated.updatedAt).not.toBe(note.createdAt);
+  });
+
   it("deletes a note", async () => {
     const note = await store.createNote("Delete me");
     await store.deleteNote(note.id);
@@ -103,6 +138,57 @@ describe("notes", async () => {
   });
 });
 
+// ---- Backfill migration: legacy rows with NULL updated_at ----
+
+describe("updated_at backfill on init", async () => {
+  it("backfills updated_at = created_at for pre-existing NULL rows", () => {
+    const raw = new Database(":memory:");
+    initSchema(raw); // create tables
+
+    // Simulate a legacy row (pre-fix insert path left updated_at NULL).
+    raw.prepare(
+      "INSERT INTO notes (id, content, created_at, updated_at) VALUES (?, ?, ?, ?)",
+    ).run("legacy", "old", "2024-01-01T00:00:00.000Z", null);
+    const before = raw.prepare("SELECT updated_at FROM notes WHERE id = ?").get("legacy") as {
+      updated_at: string | null;
+    };
+    expect(before.updated_at).toBeNull();
+
+    // Re-run init: migration should backfill without touching the row otherwise.
+    initSchema(raw);
+    const after = raw.prepare("SELECT created_at, updated_at FROM notes WHERE id = ?").get(
+      "legacy",
+    ) as { created_at: string; updated_at: string };
+    expect(after.updated_at).toBe(after.created_at);
+    expect(after.created_at).toBe("2024-01-01T00:00:00.000Z");
+  });
+
+  it("leaves rows whose updated_at is already set untouched", () => {
+    const raw = new Database(":memory:");
+    initSchema(raw);
+
+    raw.prepare(
+      "INSERT INTO notes (id, content, created_at, updated_at) VALUES (?, ?, ?, ?)",
+    ).run("edited", "content", "2024-01-01T00:00:00.000Z", "2024-06-15T12:00:00.000Z");
+
+    initSchema(raw); // migration is idempotent
+
+    const row = raw.prepare("SELECT created_at, updated_at FROM notes WHERE id = ?").get(
+      "edited",
+    ) as { created_at: string; updated_at: string };
+    expect(row.created_at).toBe("2024-01-01T00:00:00.000Z");
+    expect(row.updated_at).toBe("2024-06-15T12:00:00.000Z");
+  });
+
+  it("is a no-op for a fresh vault with zero notes", () => {
+    const raw = new Database(":memory:");
+    initSchema(raw);
+    initSchema(raw);
+    const count = raw.prepare("SELECT COUNT(*) as c FROM notes").get() as { c: number };
+    expect(count.c).toBe(0);
+  });
+});
+
 // ---- Tags ----
 
 describe("tags", async () => {
@@ -152,6 +238,144 @@ describe("tags", async () => {
   });
 });
 
+// ---- Tag rename + merge ----
+
+describe("renameTag", async () => {
+  it("retags every note and drops the old tag", async () => {
+    const n1 = await store.createNote("A", { tags: ["voice"] });
+    const n2 = await store.createNote("B", { tags: ["voice", "keeper"] });
+
+    const result = await store.renameTag("voice", "memo");
+    expect(result).toEqual({ renamed: 2 });
+
+    expect((await store.getNote(n1.id))!.tags).toEqual(["memo"]);
+    expect((await store.getNote(n2.id))!.tags?.sort()).toEqual(["keeper", "memo"]);
+    const tags = await store.listTags();
+    expect(tags.some((t) => t.name === "voice")).toBe(false);
+    expect(tags.find((t) => t.name === "memo")!.count).toBe(2);
+  });
+
+  it("carries the schema row onto the new tag name", async () => {
+    await store.createNote("A", { tags: ["voice"] });
+    await store.upsertTagSchema("voice", {
+      description: "Voice memos",
+      fields: { transcribed: { type: "boolean" } },
+    });
+
+    await store.renameTag("voice", "memo");
+
+    expect(await store.getTagSchema("voice")).toBeNull();
+    const schema = await store.getTagSchema("memo");
+    expect(schema?.description).toBe("Voice memos");
+    expect(schema?.fields?.transcribed.type).toBe("boolean");
+  });
+
+  it("renames an unused tag (zero notes)", async () => {
+    await store.createNote("A", { tags: ["doomed"] });
+    await store.untagNote((await store.queryNotes({}))[0].id, ["doomed"]);
+
+    const result = await store.renameTag("doomed", "archived");
+    expect(result).toEqual({ 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);
+  });
+
+  it("returns target_exists without mutating when new_name already in use", async () => {
+    await store.createNote("A", { tags: ["old"] });
+    await store.createNote("B", { tags: ["new"] });
+
+    const result = await store.renameTag("old", "new");
+    expect(result).toEqual({ error: "target_exists" });
+
+    // No bleed — both tags still present with their original counts.
+    const tags = await store.listTags();
+    expect(tags.find((t) => t.name === "old")!.count).toBe(1);
+    expect(tags.find((t) => t.name === "new")!.count).toBe(1);
+  });
+
+  it("returns not_found when source tag does not exist", async () => {
+    const result = await store.renameTag("nope", "something");
+    expect(result).toEqual({ error: "not_found" });
+  });
+
+  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((await store.listTags()).find((t) => t.name === "voice")!.count).toBe(1);
+  });
+});
+
+describe("mergeTags", async () => {
+  it("retags every note from every source onto target and drops sources", async () => {
+    const n1 = await store.createNote("A", { tags: ["v1"] });
+    const n2 = await store.createNote("B", { tags: ["v2"] });
+    const n3 = await store.createNote("C", { tags: ["v1", "v2"] });
+
+    const result = await store.mergeTags(["v1", "v2"], "voice");
+    expect(result.target).toBe("voice");
+    expect(result.merged).toEqual({ v1: 2, v2: 2 });
+
+    expect((await store.getNote(n1.id))!.tags).toEqual(["voice"]);
+    expect((await store.getNote(n2.id))!.tags).toEqual(["voice"]);
+    expect((await store.getNote(n3.id))!.tags).toEqual(["voice"]);
+    const tags = await store.listTags();
+    expect(tags.some((t) => t.name === "v1")).toBe(false);
+    expect(tags.some((t) => t.name === "v2")).toBe(false);
+    expect(tags.find((t) => t.name === "voice")!.count).toBe(3);
+  });
+
+  it("creates target if it does not exist", async () => {
+    await store.createNote("A", { tags: ["old"] });
+    const result = await store.mergeTags(["old"], "brand-new");
+    expect(result).toEqual({ merged: { old: 1 }, target: "brand-new" });
+    expect((await store.listTags()).find((t) => t.name === "brand-new")!.count).toBe(1);
+  });
+
+  it("leaves target's schema intact; drops sources' schemas", async () => {
+    await store.createNote("A", { tags: ["v1"] });
+    await store.createNote("B", { tags: ["voice"] });
+    await store.upsertTagSchema("v1", { description: "legacy" });
+    await store.upsertTagSchema("voice", { description: "the keeper" });
+
+    await store.mergeTags(["v1"], "voice");
+
+    expect(await store.getTagSchema("v1")).toBeNull();
+    expect((await store.getTagSchema("voice"))!.description).toBe("the keeper");
+  });
+
+  it("dedups duplicate sources in the request", async () => {
+    await store.createNote("A", { tags: ["v1"] });
+    const result = await store.mergeTags(["v1", "v1"], "voice");
+    // A duplicated source counts once — not twice.
+    expect(result.merged).toEqual({ v1: 1 });
+  });
+
+  it("silently skips target when it appears in sources", async () => {
+    await store.createNote("A", { tags: ["v1", "voice"] });
+    const result = await store.mergeTags(["v1", "voice"], "voice");
+    // voice is target; it should drop out of sources, not be deleted.
+    expect(result.merged).toEqual({ v1: 1 });
+    expect((await store.listTags()).some((t) => t.name === "voice")).toBe(true);
+  });
+
+  it("records 0 for sources that do not exist", async () => {
+    await store.createNote("A", { tags: ["real"] });
+    const result = await store.mergeTags(["real", "ghost"], "voice");
+    expect(result.merged).toEqual({ real: 1, ghost: 0 });
+  });
+
+  it("is idempotent on notes that already have the target tag", async () => {
+    // Both source and target tags present on the same note. Merge must not
+    // blow up on the INSERT OR IGNORE into note_tags.
+    const note = await store.createNote("A", { tags: ["v1", "voice"] });
+    const result = await store.mergeTags(["v1"], "voice");
+    expect(result.merged).toEqual({ v1: 1 });
+    expect((await store.getNote(note.id))!.tags).toEqual(["voice"]);
+  });
+});
+
 // ---- Vault Stats ----
 
 describe("vault stats", async () => {
@@ -326,6 +550,204 @@ describe("queryNotes", async () => {
     const results = await store.queryNotes({ limit: 3 });
     expect(results).toHaveLength(3);
   });
+
+  it("has_tags=false returns only untagged notes", async () => {
+    await store.createNote("Tagged", { tags: ["daily"] });
+    await store.createNote("Plain");
+
+    const results = await store.queryNotes({ hasTags: false });
+    expect(results.map((n) => n.content).sort()).toEqual(["Plain"]);
+  });
+
+  it("has_tags=true returns only tagged notes", async () => {
+    await store.createNote("Tagged", { tags: ["daily"] });
+    await store.createNote("Plain");
+
+    const results = await store.queryNotes({ hasTags: true });
+    expect(results.map((n) => n.content).sort()).toEqual(["Tagged"]);
+  });
+
+  it("has_tags is ignored when `tags` is also provided (tag filter wins)", async () => {
+    await store.createNote("A", { tags: ["daily"] });
+    await store.createNote("B");
+
+    // tags:["daily"] already constrains to tagged notes; has_tags is a no-op.
+    const truthy = await store.queryNotes({ tags: ["daily"], hasTags: true });
+    expect(truthy.map((n) => n.content)).toEqual(["A"]);
+
+    // `has_tags: false` would contradict `tags` — but tag filter wins, so "A" still returns.
+    const falsy = await store.queryNotes({ tags: ["daily"], hasTags: false });
+    expect(falsy.map((n) => n.content)).toEqual(["A"]);
+  });
+
+  it("has_links=false returns orphaned notes (no inbound or outbound links)", async () => {
+    const a = await store.createNote("A", { id: "ha" });
+    const b = await store.createNote("B", { id: "hb" });
+    await store.createNote("Orphan", { id: "ho" });
+    await store.createLink(a.id, b.id, "mentions");
+
+    const orphans = await store.queryNotes({ hasLinks: false });
+    expect(orphans.map((n) => n.content).sort()).toEqual(["Orphan"]);
+  });
+
+  it("has_links=true returns notes with any link (inbound or outbound)", async () => {
+    const a = await store.createNote("Source", { id: "la" });
+    const b = await store.createNote("Target", { id: "lb" });
+    await store.createNote("Orphan", { id: "lo" });
+    await store.createLink(a.id, b.id, "mentions");
+
+    // Both Source (outbound) and Target (inbound) should appear.
+    const linked = await store.queryNotes({ hasLinks: true });
+    expect(linked.map((n) => n.content).sort()).toEqual(["Source", "Target"]);
+  });
+
+  it("composes has_tags + has_links (untagged and orphaned)", async () => {
+    const a = await store.createNote("Tagged+linked", { tags: ["x"], id: "ca" });
+    const b = await store.createNote("Plain+linked", { id: "cb" });
+    await store.createNote("Tagged+orphan", { tags: ["x"], id: "cc" });
+    await store.createNote("Plain+orphan", { id: "cd" });
+    await store.createLink(a.id, b.id, "mentions");
+
+    const loners = await store.queryNotes({ hasTags: false, hasLinks: false });
+    expect(loners.map((n) => n.content)).toEqual(["Plain+orphan"]);
+  });
+
+  it("has_tags=false composes with exclude_tags as a no-op (untagged notes have no tags to exclude)", async () => {
+    await store.createNote("Tagged", { tags: ["archived"] });
+    await store.createNote("Plain");
+
+    const results = await store.queryNotes({ hasTags: false, excludeTags: ["archived"] });
+    expect(results.map((n) => n.content)).toEqual(["Plain"]);
+  });
+
+  // ---- Operator objects + order_by on indexed metadata fields ----
+
+  describe("metadata operators + order_by", () => {
+    async function seedIndexedPriorities() {
+      const { declareField } = await import("./indexed-fields.js");
+      declareField(db, "priority", "INTEGER", "project");
+      declareField(db, "status", "TEXT", "project");
+    }
+
+    it("eq operator on indexed field matches primitive exactly", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("high", { metadata: { priority: 5 } });
+      await store.createNote("low", { metadata: { priority: 1 } });
+
+      const results = await store.queryNotes({ metadata: { priority: { eq: 5 } } });
+      expect(results.map((n) => n.content)).toEqual(["high"]);
+    });
+
+    it("ne operator returns non-matching rows AND rows without the field", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("has-1", { metadata: { priority: 1 } });
+      await store.createNote("has-2", { metadata: { priority: 2 } });
+      await store.createNote("missing"); // no priority at all
+
+      const results = await store.queryNotes({ metadata: { priority: { ne: 1 } } });
+      expect(results.map((n) => n.content).sort()).toEqual(["has-2", "missing"]);
+    });
+
+    it("gt / gte / lt / lte compose into range queries on one field", async () => {
+      await seedIndexedPriorities();
+      for (const p of [1, 2, 3, 4, 5]) {
+        await store.createNote(`p${p}`, { metadata: { priority: p } });
+      }
+      const range = await store.queryNotes({ metadata: { priority: { gte: 2, lt: 5 } } });
+      expect(range.map((n) => n.content).sort()).toEqual(["p2", "p3", "p4"]);
+    });
+
+    it("in and not_in take arrays; empty in returns no rows, empty not_in returns all", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("a", { metadata: { status: "active" } });
+      await store.createNote("b", { metadata: { status: "exploring" } });
+      await store.createNote("c", { metadata: { status: "done" } });
+
+      const inResult = await store.queryNotes({ metadata: { status: { in: ["active", "exploring"] } } });
+      expect(inResult.map((n) => n.content).sort()).toEqual(["a", "b"]);
+
+      const notInResult = await store.queryNotes({ metadata: { status: { not_in: ["done"] } } });
+      // "done" excluded; rows with status=null (none here) would also pass.
+      expect(notInResult.map((n) => n.content).sort()).toEqual(["a", "b"]);
+
+      const emptyIn = await store.queryNotes({ metadata: { status: { in: [] } } });
+      expect(emptyIn).toHaveLength(0);
+    });
+
+    it("exists: true / false distinguishes present vs absent field", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("has", { metadata: { priority: 3 } });
+      await store.createNote("missing");
+
+      const has = await store.queryNotes({ metadata: { priority: { exists: true } } });
+      expect(has.map((n) => n.content)).toEqual(["has"]);
+
+      const missing = await store.queryNotes({ metadata: { priority: { exists: false } } });
+      expect(missing.map((n) => n.content)).toEqual(["missing"]);
+    });
+
+    it("order_by sorts by the indexed field; sort='desc' reverses direction", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("p3", { metadata: { priority: 3 } });
+      await store.createNote("p1", { metadata: { priority: 1 } });
+      await store.createNote("p2", { metadata: { priority: 2 } });
+
+      const asc = await store.queryNotes({ orderBy: "priority" });
+      expect(asc.map((n) => n.content)).toEqual(["p1", "p2", "p3"]);
+
+      const desc = await store.queryNotes({ orderBy: "priority", sort: "desc" });
+      expect(desc.map((n) => n.content)).toEqual(["p3", "p2", "p1"]);
+    });
+
+    it("operator objects compose with tag and exclude_tags filters", async () => {
+      await seedIndexedPriorities();
+      await store.createNote("p5-project", { tags: ["project"], metadata: { priority: 5 } });
+      await store.createNote("p3-project", { tags: ["project"], metadata: { priority: 3 } });
+      await store.createNote("p5-other", { tags: ["other"], metadata: { priority: 5 } });
+
+      const results = await store.queryNotes({
+        tags: ["project"],
+        metadata: { priority: { gte: 4 } },
+      });
+      expect(results.map((n) => n.content)).toEqual(["p5-project"]);
+    });
+
+    it("primitive metadata values keep working (backcompat, scan JSON)", async () => {
+      // Note: priority is NOT declared indexed here — primitive match still
+      // goes through json_extract and doesn't require an index.
+      await store.createNote("match", { metadata: { kind: "draft" } });
+      await store.createNote("other", { metadata: { kind: "final" } });
+
+      const results = await store.queryNotes({ metadata: { kind: "draft" } });
+      expect(results.map((n) => n.content)).toEqual(["match"]);
+    });
+
+    it("operator on a non-indexed field throws FIELD_NOT_INDEXED", async () => {
+      await store.createNote("x", { metadata: { foo: "bar" } });
+      expect(
+        store.queryNotes({ metadata: { foo: { eq: "bar" } } }),
+      ).rejects.toThrow(/not indexed/);
+    });
+
+    it("order_by on a non-indexed field throws FIELD_NOT_INDEXED", async () => {
+      await store.createNote("x", { metadata: { foo: 1 } });
+      expect(store.queryNotes({ orderBy: "foo" })).rejects.toThrow(/not indexed/);
+    });
+
+    it("unknown operator throws UNKNOWN_OPERATOR with supported-op list", async () => {
+      await seedIndexedPriorities();
+      expect(
+        store.queryNotes({ metadata: { priority: { bogus: 5 } as any } }),
+      ).rejects.toThrow(/unknown operator "bogus"/);
+    });
+
+    it("in/not_in without an array value throws INVALID_OPERATOR_VALUE", async () => {
+      await seedIndexedPriorities();
+      expect(
+        store.queryNotes({ metadata: { priority: { in: 5 } as any } }),
+      ).rejects.toThrow(/expects an array/);
+    });
+  });
 });
 
 // ---- Search ----
@@ -445,6 +867,41 @@ describe("attachments", async () => {
     const attachments = await store.getAttachments(note.id);
     expect(attachments).toHaveLength(0);
   });
+
+  it("deleteAttachment removes row and reports orphaned path", async () => {
+    const note = await store.createNote("Has attachment");
+    const att = await store.addAttachment(note.id, "2026-04-18/pic.png", "image/png");
+
+    const result = await store.deleteAttachment(note.id, att.id);
+    expect(result).toEqual({ deleted: true, path: "2026-04-18/pic.png", orphaned: true });
+    expect(await store.getAttachments(note.id)).toHaveLength(0);
+  });
+
+  it("deleteAttachment returns deleted:false for nonexistent id", async () => {
+    const note = await store.createNote("x");
+    const result = await store.deleteAttachment(note.id, "does-not-exist");
+    expect(result).toEqual({ deleted: false, path: null, orphaned: false });
+  });
+
+  it("deleteAttachment is scoped to noteId (cross-note attempt is a no-op)", async () => {
+    const a = await store.createNote("A");
+    const b = await store.createNote("B");
+    const attA = await store.addAttachment(a.id, "files/a.png", "image/png");
+
+    const result = await store.deleteAttachment(b.id, attA.id);
+    expect(result.deleted).toBe(false);
+    expect(await store.getAttachments(a.id)).toHaveLength(1);
+  });
+
+  it("deleteAttachment reports orphaned:false when a sibling attachment shares the path", async () => {
+    const a = await store.createNote("A");
+    const b = await store.createNote("B");
+    const attA = await store.addAttachment(a.id, "shared/pic.png", "image/png");
+    await store.addAttachment(b.id, "shared/pic.png", "image/png");
+
+    const result = await store.deleteAttachment(a.id, attA.id);
+    expect(result).toEqual({ deleted: true, path: "shared/pic.png", orphaned: false });
+  });
 });
 
 // ---- MCP Tools ----
@@ -505,7 +962,7 @@ describe("MCP tools", async () => {
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
     const newDate = "2025-03-01T00:00:00.000Z";
-    const result = await updateNote.execute({ id: note.id, created_at: newDate }) as any;
+    const result = await updateNote.execute({ id: note.id, created_at: newDate, force: true }) as any;
     expect(result.createdAt).toBe(newDate);
     expect(result.content).toBe("Test");
   });
@@ -514,7 +971,7 @@ describe("MCP tools", async () => {
     const note = await store.createNote("Test", { metadata: { existing: "value" } });
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
-    const result = await updateNote.execute({ id: note.id, metadata: { importance: "high" } }) as any;
+    const result = await updateNote.execute({ id: note.id, metadata: { importance: "high" }, force: true }) as any;
     expect(result.metadata).toEqual({ existing: "value", importance: "high" });
   });
 
@@ -524,12 +981,12 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
     // Add tags
-    await updateNote.execute({ id: note.id, tags: { add: ["pinned", "daily"] } });
+    await updateNote.execute({ id: note.id, tags: { add: ["pinned", "daily"] }, force: true });
     expect((await store.getNote(note.id))!.tags).toContain("pinned");
     expect((await store.getNote(note.id))!.tags).toContain("daily");
 
     // Remove tags
-    await updateNote.execute({ id: note.id, tags: { remove: ["pinned"] } });
+    await updateNote.execute({ id: note.id, tags: { remove: ["pinned"] }, force: true });
     expect((await store.getNote(note.id))!.tags).not.toContain("pinned");
     expect((await store.getNote(note.id))!.tags).toContain("daily");
   });
@@ -541,11 +998,11 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
     // Add link
-    await updateNote.execute({ id: "a", links: { add: [{ target: "b", relationship: "mentions" }] } });
+    await updateNote.execute({ id: "a", links: { add: [{ target: "b", relationship: "mentions" }] }, force: true });
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(1);
 
     // Remove link
-    await updateNote.execute({ id: "a", links: { remove: [{ target: "b", relationship: "mentions" }] } });
+    await updateNote.execute({ id: "a", links: { remove: [{ target: "b", relationship: "mentions" }] }, force: true });
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(0);
   });
 
@@ -559,6 +1016,7 @@ describe("MCP tools", async () => {
     const result = await updateNote.execute({
       id: "source",
       links: { remove: [{ target: "target", relationship: "wikilink" }] },
+      force: true,
     }) as any;
     expect(result.content).toBe("See People/Alice for details");
   });
@@ -570,8 +1028,8 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
     const result = await updateNote.execute({
       notes: [
-        { id: "a", content: "A updated" },
-        { id: "b", tags: { add: ["pinned"] } },
+        { id: "a", content: "A updated", force: true },
+        { id: "b", tags: { add: ["pinned"] }, force: true },
       ],
     }) as any[];
     expect(result).toHaveLength(2);
@@ -583,7 +1041,7 @@ describe("MCP tools", async () => {
     await store.createNote("Test", { path: "Projects/README" });
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
-    const result = await updateNote.execute({ id: "Projects/README", content: "Updated" }) as any;
+    const result = await updateNote.execute({ id: "Projects/README", content: "Updated", force: true }) as any;
     expect(result.content).toBe("Updated");
   });
 
@@ -592,7 +1050,7 @@ describe("MCP tools", async () => {
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
-    const first = await updateNote.execute({ id: note.id, content: "Second" }) as any;
+    const first = await updateNote.execute({ id: note.id, content: "Second", force: true }) as any;
     expect(first.content).toBe("Second");
     expect(first.updatedAt).toBeTruthy();
 
@@ -609,7 +1067,7 @@ describe("MCP tools", async () => {
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
-    const after = await updateNote.execute({ id: note.id, content: "Second" }) as any;
+    const after = await updateNote.execute({ id: note.id, content: "Second", force: true }) as any;
 
     // Simulate a stale client that has the pre-update timestamp (or something else).
     const staleTimestamp = "2020-01-01T00:00:00.000Z";
@@ -635,9 +1093,11 @@ describe("MCP tools", async () => {
     expect((await store.getNote(note.id))!.content).toBe("Second");
   });
 
-  it("update-note if_updated_at conflicts for a never-updated note when caller expects a value", async () => {
+  it("update-note if_updated_at conflicts when the caller's timestamp doesn't match", async () => {
     const note = await store.createNote("First");
-    expect(note.updatedAt).toBeUndefined();
+    // A fresh note has updatedAt === createdAt. Sending a
+    // mismatching timestamp must still be rejected as a conflict.
+    expect(note.updatedAt).toBe(note.createdAt);
     const tools = generateMcpTools(store);
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
@@ -653,7 +1113,60 @@ describe("MCP tools", async () => {
     }
     expect(err).toBeTruthy();
     expect(err.code).toBe("CONFLICT");
-    expect(err.current_updated_at).toBeNull();
+    expect(err.current_updated_at).toBe(note.createdAt);
+  });
+
+  it("create-note returns updatedAt equal to createdAt on fresh notes", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({ content: "Hello" }) as any;
+    expect(result.updatedAt).toBeTruthy();
+    expect(result.updatedAt).toBe(result.createdAt);
+  });
+
+  it("update-note requires if_updated_at or force (precondition-required)", async () => {
+    const note = await store.createNote("Test", { path: "Inbox/x" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    let err: any;
+    try {
+      await updateNote.execute({ id: note.id, content: "changed" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("PRECONDITION_REQUIRED");
+    expect(err.note_id).toBe(note.id);
+    expect(err.note_path).toBe("Inbox/x");
+    expect((await store.getNote(note.id))!.content).toBe("Test");
+  });
+
+  it("update-note force:true bypasses precondition and mutates unconditionally", async () => {
+    const note = await store.createNote("First");
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({ id: note.id, content: "Second", force: true }) as any;
+    expect(result.content).toBe("Second");
+  });
+
+  it("update-note conflict error surfaces note_path", async () => {
+    const note = await store.createNote("First", { path: "Inbox/y" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await updateNote.execute({ id: note.id, content: "Second", force: true });
+
+    let err: any;
+    try {
+      await updateNote.execute({
+        id: note.id,
+        content: "Third",
+        if_updated_at: "2020-01-01T00:00:00.000Z",
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err?.code).toBe("CONFLICT");
+    expect(err.note_path).toBe("Inbox/y");
   });
 
   it("update-note batch aborts on first conflict without touching subsequent items", async () => {
@@ -663,7 +1176,7 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
     // Bump a's updated_at so any stale if_updated_at conflicts.
-    const bumped = await updateNote.execute({ id: "a", content: "A bumped" }) as any;
+    const bumped = await updateNote.execute({ id: "a", content: "A bumped", force: true }) as any;
     expect(bumped.updatedAt).toBeTruthy();
 
     let err: any;
@@ -671,7 +1184,7 @@ describe("MCP tools", async () => {
       await updateNote.execute({
         notes: [
           { id: "a", content: "A new", if_updated_at: "2020-01-01T00:00:00.000Z" },
-          { id: "b", content: "B new" },
+          { id: "b", content: "B new", force: true },
         ],
       });
     } catch (e) {
@@ -698,7 +1211,7 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
     // Establish a known updated_at the two callers both read.
-    const seed = await updateNote.execute({ id: note.id, content: "seed-v1" }) as any;
+    const seed = await updateNote.execute({ id: note.id, content: "seed-v1", force: true }) as any;
     expect(seed.updatedAt).toBeTruthy();
 
     const results = await Promise.allSettled([
@@ -731,7 +1244,7 @@ describe("MCP tools", async () => {
     const updateNote = tools.find((t) => t.name === "update-note")!;
 
     // Bump so a stale if_updated_at conflicts; and capture state after bump.
-    await updateNote.execute({ id: "source", content: "See [[People/Alice]] for details" });
+    await updateNote.execute({ id: "source", content: "See [[People/Alice]] for details", force: true });
     const preConflictLinks = await store.getLinks("source", { direction: "outbound" });
     expect(preConflictLinks).toHaveLength(1);
 
@@ -761,6 +1274,11 @@ describe("MCP tools", async () => {
     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 () => {
@@ -779,6 +1297,60 @@ describe("MCP tools", async () => {
     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);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      order_by: "priority",
+      sort: "desc",
+      include_content: true,
+    }) as any[];
+    expect(result.map((n) => n.content)).toEqual(["p5", "p2", "p1"]);
+  });
+
   it("query-notes list defaults to no content (index mode)", async () => {
     const content = "This is the note body.";
     await store.createNote(content, { tags: ["daily"], path: "Notes/test", metadata: { status: "draft" } });