@openparachute/vault 0.7.0-rc.7 → 0.7.0-rc.9

package/core/src/core.test.ts

@@ -597,6 +597,22 @@ describe("renameTag cascade (vault#240 + #247)", async () => {
     expect(fresh!.content).toContain("#other"); // untouched
   });
 
+  // vault#555 fix 2 — a rename cascade's inline content rewrite is a real
+  // persisted-state change; `updated_at` must move or a cursor/sync-poll
+  // loop never sees the rewritten note.
+  it("1b. content rewrite bumps updated_at (vault#555)", async () => {
+    const note = await store.createNote("Today's #task is important.", { tags: ["task"] });
+    const before = note.updatedAt;
+    await new Promise((r) => setTimeout(r, 5));
+
+    await store.renameTag("task", "todo");
+
+    const fresh = await store.getNote(note.id);
+    expect(fresh!.content).toContain("#todo");
+    expect(fresh!.updatedAt).not.toBe(before);
+    expect(new Date(fresh!.updatedAt) > new Date(before)).toBe(true);
+  });
+
   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"] });
@@ -2253,6 +2269,92 @@ describe("MCP tools", async () => {
     expect(links.some((l) => l.relationship === "mentions")).toBe(true);
   });
 
+  // vault#555 — structured `links` used to resolve by exact path only (no
+  // basename/title fallback, unlike [[wikilinks]]). "Bare Title" against a
+  // note filed at "People/Alice" is a basename match, same as `[[Alice]]`.
+  it("create-note with links resolves targets by BASENAME (title), same as [[wikilinks]]", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    await store.createNote("Target", { path: "People/Alice" });
+    const result = await createNote.execute({
+      content: "Links to Alice by bare title",
+      links: [{ target: "Alice", relationship: "knows" }],
+    }) as any;
+    const links = await store.getLinks(result.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.relationship).toBe("knows");
+  });
+
+  // vault#555 — a link to a note created LATER in the same create-note
+  // batch used to silently drop (item 0 resolved before item 1 existed).
+  // The equivalent forward-ref via a [[wikilink]] already resolved; this
+  // makes structured `links` match.
+  it("create-note batch: a link to a note created LATER in the same batch resolves (forward-ref)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({
+      notes: [
+        { path: "A", content: "links to B", links: [{ target: "B", relationship: "knows" }] },
+        { path: "B", content: "the target" },
+      ],
+    }) as any[];
+    const a = result.find((n: any) => n.path === "A");
+    const links = await store.getLinks(a.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.relationship).toBe("knows");
+    // No warning — it resolved within the batch.
+    expect(a.warnings).toBeUndefined();
+  });
+
+  // vault#555 — a target that genuinely can't resolve now must surface an
+  // `unresolved_link` warning (never silent), AND lazily backfill the edge
+  // the moment a matching note is created later — mirroring the
+  // `unresolved_wikilinks` forward-ref contract.
+  it("create-note with an unresolvable link target: warns now, backfills the edge when the target is created later", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const source = await createNote.execute({
+      content: "links to a note that doesn't exist yet",
+      links: [{ target: "Nonexistent Target", relationship: "knows" }],
+    }) as any;
+
+    expect(source.warnings).toBeDefined();
+    expect(source.warnings).toHaveLength(1);
+    expect(source.warnings[0].code).toBe("unresolved_link");
+    expect(source.warnings[0].target).toBe("Nonexistent Target");
+    expect(source.warnings[0].relationship).toBe("knows");
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(0);
+
+    // Creating the target note later backfills the edge automatically.
+    const target = await store.createNote("here now", { path: "Nonexistent Target" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(target.id);
+    expect(links[0]!.relationship).toBe("knows");
+  });
+
+  // vault#555 — structured-link forward-refs (any relationship) must
+  // coexist with pending [[wikilink]] forward-refs on the SAME note without
+  // one clobbering the other when the note's content is re-synced.
+  it("pending structured-link forward-ref survives a wikilink content re-sync on the same note", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const source = await createNote.execute({
+      content: "no wikilinks yet",
+      links: [{ target: "Future Note", relationship: "knows" }],
+    }) as any;
+    expect(source.warnings?.[0]?.code).toBe("unresolved_link");
+
+    // Editing content (which re-syncs [[wikilink]]-kind unresolved entries)
+    // must not wipe the pending structured-link entry.
+    await updateNote.execute({ id: source.id, content: "now with a [[Some Other Unresolved Note]]", force: true });
+
+    const target = await store.createNote("arrived", { path: "Future Note" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links.some((l) => l.targetId === target.id && l.relationship === "knows")).toBe(true);
+  });
+
   it("update-note tool updates created_at", async () => {
     const note = await store.createNote("Test");
     const tools = generateMcpTools(store);
@@ -2287,6 +2389,47 @@ describe("MCP tools", async () => {
     expect((await store.getNote(note.id))!.tags).toContain("daily");
   });
 
+  // vault#555 fix 2 — a tag-only (or links-only) update-note call with
+  // `force: true` (no `if_updated_at`) used to leave `updated_at` frozen:
+  // the mcp.ts `updates` object had no core fields, so `store.updateNote`
+  // was never even called. Breaks cursor polling (ORDER BY updated_at) and
+  // any updated_at-based sync filter.
+  it("update-note tags-only mutation with force:true bumps updated_at", async () => {
+    const note = await store.createNote("Test");
+    const before = note.updatedAt;
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    await updateNote.execute({ id: note.id, tags: { add: ["pinned"] }, force: true });
+    const after1 = (await store.getNote(note.id))!.updatedAt;
+    expect(after1).not.toBe(before);
+    expect(new Date(after1) > new Date(before)).toBe(true);
+
+    await new Promise((r) => setTimeout(r, 5));
+    await updateNote.execute({ id: note.id, tags: { remove: ["pinned"] }, force: true });
+    const after2 = (await store.getNote(note.id))!.updatedAt;
+    expect(new Date(after2) > new Date(after1)).toBe(true);
+  });
+
+  it("update-note links-only mutation with force:true bumps updated_at", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    const before = (await store.getNote("a"))!.updatedAt;
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    await updateNote.execute({ id: "a", links: { add: [{ target: "b", relationship: "mentions" }] }, force: true });
+    const after1 = (await store.getNote("a"))!.updatedAt;
+    expect(new Date(after1) > new Date(before)).toBe(true);
+
+    await new Promise((r) => setTimeout(r, 5));
+    await updateNote.execute({ id: "a", links: { remove: [{ target: "b", relationship: "mentions" }] }, force: true });
+    const after2 = (await store.getNote("a"))!.updatedAt;
+    expect(new Date(after2) > new Date(after1)).toBe(true);
+  });
+
   it("update-note links add/remove works", async () => {
     await store.createNote("A", { id: "a" });
     await store.createNote("B", { id: "b" });
@@ -2302,6 +2445,38 @@ describe("MCP tools", async () => {
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(0);
   });
 
+  // vault#555 — update-note's links.add gets the same basename/title
+  // resolution + lazy forward-ref queueing as create-note's.
+  it("update-note links.add resolves by BASENAME and warns+queues when unresolvable", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("Target", { path: "People/Bob" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // Basename match
+    const byTitle = await updateNote.execute({
+      id: "a",
+      links: { add: [{ target: "Bob", relationship: "knows" }] },
+      force: true,
+    }) as any;
+    expect(byTitle.warnings).toBeUndefined();
+    expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(1);
+
+    // Unresolvable target: warns, queues, backfills later.
+    const unresolved = await updateNote.execute({
+      id: "a",
+      links: { add: [{ target: "Not Yet Real", relationship: "wants" }] },
+      force: true,
+    }) as any;
+    expect(unresolved.warnings).toBeDefined();
+    expect(unresolved.warnings[0].code).toBe("unresolved_link");
+    expect(unresolved.warnings[0].target).toBe("Not Yet Real");
+
+    const target = await store.createNote("arrived", { path: "Not Yet Real" });
+    const links = await store.getLinks("a", { direction: "outbound" });
+    expect(links.some((l) => l.targetId === target.id && l.relationship === "wants")).toBe(true);
+  });
+
   // vault feedback #8 — echo hydrated links on the update response when the
   // request mutated links OR `include_links` is set, so callers don't re-query.
   it("update-note echoes hydrated links when the update mutates links", async () => {
@@ -3030,6 +3205,126 @@ describe("MCP tools", async () => {
     expect(err?.code).toBe("CONFLICT");
   });
 
+  // vault#555 fix 7 (INVESTIGATE) — a tester reported update-note batch
+  // AND parallel singles failing 7/8 with "old_text not found" when
+  // multiple items share the SAME content_edit.old_text, though each
+  // succeeded standalone. The orchestrator could NOT reproduce live (repro
+  // hit shell artifacts). Investigated here with proper in-memory tests:
+  //
+  //   - Batch AND parallel-singles, N items EACH TARGETING A DIFFERENT
+  //     note, all sharing the same old_text: every item succeeds. Each
+  //     item resolves its OWN note's content fresh (there's no shared
+  //     mutable state across items/calls — `resolveNote` reads straight
+  //     off the DB per item, and the content_edit search+replace is pure
+  //     synchronous JS with no `await` between the read and the write, so
+  //     two "parallel" async calls can't interleave mid-computation
+  //     either). Re-run 20x below with zero failures.
+  //   - The one scenario that DOES reproduce "1 succeeds, 7 fail
+  //     content_edit_not_found" is N calls sharing the same old_text
+  //     against the SAME note — and that's CORRECT behavior (the first
+  //     call consumes the only occurrence; the rest correctly report it's
+  //     gone), not a bug. This is the most plausible explanation for what
+  //     was actually observed: a test harness that accidentally pointed
+  //     every call at one note (a variable/loop bug — "shell artifacts")
+  //     rather than N distinct notes.
+  //
+  // VERDICT: not reproducible as a real bug against different notes. No
+  // fix applied — these tests document the correct behavior.
+  it("update-note BATCH: N items with the SAME content_edit.old_text on DIFFERENT notes all succeed", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const N = 8;
+    const notes = [];
+    for (let i = 0; i < N; i++) {
+      notes.push(await store.createNote(`prefix TARGET_TEXT suffix-${i}`, { path: `batch-ce-${i}` }));
+    }
+
+    const result = await updateNote.execute({
+      notes: notes.map((n) => ({
+        id: n.id,
+        content_edit: { old_text: "TARGET_TEXT", new_text: "REPLACED" },
+        force: true,
+      })),
+    }) as any[];
+
+    expect(result).toHaveLength(N);
+    for (let i = 0; i < N; i++) {
+      expect(result[i].content).toBe(`prefix REPLACED suffix-${i}`);
+    }
+  });
+
+  it("update-note PARALLEL SINGLES: N concurrent calls with the SAME content_edit.old_text on DIFFERENT notes all succeed", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const N = 8;
+    const notes = [];
+    for (let i = 0; i < N; i++) {
+      notes.push(await store.createNote(`prefix TARGET_TEXT suffix-${i}`, { path: `parallel-ce-${i}` }));
+    }
+
+    const results = await Promise.all(
+      notes.map((n) =>
+        updateNote.execute({
+          id: n.id,
+          content_edit: { old_text: "TARGET_TEXT", new_text: "REPLACED" },
+          force: true,
+        }),
+      ),
+    ) as any[];
+
+    for (let i = 0; i < N; i++) {
+      expect(results[i].content).toBe(`prefix REPLACED suffix-${i}`);
+    }
+  });
+
+  it("update-note PARALLEL SINGLES with shared old_text: 20 repeated trials, zero failures (flake hunt)", async () => {
+    for (let trial = 0; trial < 20; trial++) {
+      const trialDb = new Database(":memory:");
+      const trialStore = new SqliteStore(trialDb);
+      const tools = generateMcpTools(trialStore);
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      const N = 8;
+      const notes = [];
+      for (let i = 0; i < N; i++) {
+        notes.push(await trialStore.createNote(`prefix TARGET_TEXT suffix-${i}`, { path: `flake-${i}` }));
+      }
+      const outcomes = await Promise.allSettled(
+        notes.map((n) =>
+          updateNote.execute({
+            id: n.id,
+            content_edit: { old_text: "TARGET_TEXT", new_text: "REPLACED" },
+            force: true,
+          }),
+        ),
+      );
+      const failures = outcomes.filter((o) => o.status === "rejected");
+      expect(failures.length).toBe(0);
+    }
+  });
+
+  it("update-note with shared old_text against the SAME note: 1 succeeds, 7 correctly fail (documents the LIKELY source of the original report — not a bug)", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const note = await store.createNote("prefix TARGET_TEXT suffix", { path: "shared-ce" });
+
+    const outcomes = await Promise.allSettled(
+      Array.from({ length: 8 }, () =>
+        updateNote.execute({
+          id: note.id,
+          content_edit: { old_text: "TARGET_TEXT", new_text: "REPLACED" },
+          force: true,
+        }),
+      ),
+    );
+    const succeeded = outcomes.filter((o) => o.status === "fulfilled").length;
+    const failed = outcomes.filter((o) => o.status === "rejected");
+    expect(succeeded).toBe(1);
+    expect(failed).toHaveLength(7);
+    for (const f of failed) {
+      expect((f as PromiseRejectedResult).reason.error_type).toBe("content_edit_not_found");
+    }
+  });
+
   it("query-notes single note by id", async () => {
     const note = await store.createNote("Hello", { path: "test/note" });
     const tools = generateMcpTools(store);
@@ -3081,6 +3376,93 @@ describe("MCP tools", async () => {
     expect(result.map((n) => n.content)).toEqual(["Orphan"]);
   });
 
+  // ---- has_broken_links / include_broken_links (vault#555) ----
+
+  it("query-notes has_broken_links=true surfaces only notes with a dangling wikilink", async () => {
+    await store.createNote("[[Nonexistent Target]]", { id: "mq-broken", path: "mq-broken" });
+    await store.createNote("no links here", { id: "mq-clean", path: "mq-clean" });
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ has_broken_links: true, include_content: true }) as any[];
+    expect(result.map((n) => n.path)).toEqual(["mq-broken"]);
+  });
+
+  it("query-notes has_broken_links=false excludes notes with a dangling link", async () => {
+    await store.createNote("[[Nonexistent Target]]", { id: "mq-broken2", path: "mq-broken2" });
+    await store.createNote("no links here", { id: "mq-clean2", path: "mq-clean2" });
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ has_broken_links: false, include_content: true }) as any[];
+    expect(result.map((n) => n.path).sort()).toEqual(["mq-clean2"]);
+  });
+
+  it("query-notes has_broken_links is safe on a vault where no link has ever gone unresolved", async () => {
+    // Fresh store, beforeEach — the unresolved_wikilinks table has never
+    // been created. true should match nothing (not throw); false should
+    // be a no-op (matches everything).
+    await store.createNote("plain note", { id: "mq-nolinks", path: "mq-nolinks" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const truthy = await query.execute({ has_broken_links: true, include_content: true }) as any[];
+    expect(truthy).toEqual([]);
+    const falsy = await query.execute({ has_broken_links: false, include_content: true }) as any[];
+    expect(falsy.map((n) => n.path)).toEqual(["mq-nolinks"]);
+  });
+
+  it("a target created later resolves the wikilink and the note drops out of has_broken_links:true", async () => {
+    await store.createNote("[[Later Target]]", { id: "mq-fixable", path: "mq-fixable" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    expect((await query.execute({ has_broken_links: true }) as any[]).length).toBe(1);
+
+    await store.createNote("here now", { path: "Later Target" });
+    expect((await query.execute({ has_broken_links: true }) as any[]).length).toBe(0);
+  });
+
+  it("query-notes include_broken_links surfaces {target, relationship} for a single note", async () => {
+    await store.createNote("[[Missing Note]]", { id: "mq-single-broken", path: "mq-single-broken" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: "mq-single-broken", include_broken_links: true }) as any;
+    expect(result.broken_links).toEqual([{ target: "Missing Note", relationship: "wikilink" }]);
+  });
+
+  it("query-notes include_broken_links surfaces a structured link's unresolved_link entry too", async () => {
+    const created = await generateMcpTools(store).find((t) => t.name === "create-note")!.execute({
+      content: "body",
+      path: "mq-structured-broken",
+      links: [{ target: "Does Not Exist", relationship: "depends-on" }],
+    }) as any;
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: created.id, include_broken_links: true }) as any;
+    expect(result.broken_links).toEqual([{ target: "Does Not Exist", relationship: "depends-on" }]);
+  });
+
+  it("query-notes include_broken_links is [] for a note with no dangling links", async () => {
+    await store.createNote("clean", { id: "mq-clean-single", path: "mq-clean-single" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: "mq-clean-single", include_broken_links: true }) as any;
+    expect(result.broken_links).toEqual([]);
+  });
+
+  it("query-notes include_broken_links works in list mode, batched across the page", async () => {
+    await store.createNote("[[Ghost A]]", { id: "mq-list-a", path: "mq-list-a" });
+    await store.createNote("[[Ghost B]]", { id: "mq-list-b", path: "mq-list-b" });
+    await store.createNote("clean", { id: "mq-list-c", path: "mq-list-c" });
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ include_broken_links: true, include_content: true }) as any[];
+    const byId = new Map(result.map((n: any) => [n.id, n.broken_links]));
+    expect(byId.get("mq-list-a")).toEqual([{ target: "Ghost A", relationship: "wikilink" }]);
+    expect(byId.get("mq-list-b")).toEqual([{ target: "Ghost B", relationship: "wikilink" }]);
+    expect(byId.get("mq-list-c")).toEqual([]);
+  });
+
   it("query-notes metadata operator query routes through the indexed column", async () => {
     const { declareField } = await import("./indexed-fields.js");
     declareField(db, "priority", "INTEGER", "project");
@@ -3433,6 +3815,72 @@ describe("MCP tools", async () => {
     expect(result.fields.age.type).toBe("integer");
   });
 
+  // vault#555 fix 4 — a non-indexed field's `type` was never validated
+  // anywhere; a genuinely unrecognized type string was accepted and
+  // persisted verbatim, no error.
+  it("update-tag rejects an unrecognized field type (invalid_type)", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    let caught: any;
+    try {
+      await updateTag.execute({ tag: "widget", fields: { weird: { type: "frobnicator" } } });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(caught.error_type).toBe("tag_field_conflict");
+    expect(caught.violations).toHaveLength(1);
+    expect(caught.violations[0].field).toBe("weird");
+    expect(caught.violations[0].reason).toBe("invalid_type");
+
+    // Nothing persisted.
+    const record = await store.getTagRecord("widget");
+    expect(record?.fields ?? null).toBeFalsy();
+  });
+
+  // vault#555 fix 5 — one call declaring TWO bad fields (an unrecognized
+  // type AND a non-conforming default) reports BOTH violations together,
+  // not just the first one encountered.
+  it("update-tag reports an unrecognized type AND a bad default together in one call", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    let caught: any;
+    try {
+      await updateTag.execute({
+        tag: "widget",
+        fields: {
+          weird: { type: "frobnicator" },
+          bad_default: { type: "string", enum: ["a", "b"], default: "zzz" },
+        },
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(caught.violations).toHaveLength(2);
+    const byField = new Map(caught.violations.map((v: any) => [v.field, v.reason]));
+    expect(byField.get("weird")).toBe("invalid_type");
+    expect(byField.get("bad_default")).toBe("invalid_default");
+  });
+
+  it("update-tag accepts every recognized field type", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    const result = await updateTag.execute({
+      tag: "widget",
+      fields: {
+        a: { type: "string" },
+        b: { type: "number" },
+        c: { type: "integer" },
+        d: { type: "boolean" },
+        e: { type: "array" },
+        f: { type: "object" },
+      },
+    }) as any;
+    expect(result.fields.a.type).toBe("string");
+    expect(result.fields.f.type).toBe("object");
+  });
+
   it("find-path works with ID/path resolution", async () => {
     await store.createNote("A", { id: "a", path: "People/Alice" });
     await store.createNote("B", { id: "b" });
@@ -4343,6 +4791,58 @@ describe("schema validation (tags.fields)", async () => {
     expect(result.validation_status.warnings[0].reason).toBe("enum_mismatch");
   });
 
+  // vault#555 fix 3 — an enum-membership violation on an INDEXED
+  // (non-strict) field is stored, findable via `eq` (indexed⇒strict is
+  // TYPE-only, not enum-domain — a ratified policy, not a bug), but the
+  // advisory `enum_mismatch` warning used to be visible ONLY on the
+  // one-time create/update response — a caller reading the note back via
+  // query-notes (the natural way to re-check a stored value) saw nothing,
+  // contradicting "advisory violations surface as warnings."
+  it("query-notes surfaces validation_status (enum_mismatch on an indexed field) — single-id fetch", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+    const create = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await updateTag.execute({
+      tag: "widget",
+      fields: { status: { type: "string", enum: ["a", "b"], indexed: true } },
+    });
+    const created = await create.execute({ content: "x", tags: ["widget"], metadata: { status: "bogus" } }) as any;
+
+    // Findable via eq — indexed⇒strict is TYPE-only, enum stays advisory.
+    const found = await query.execute({ metadata: { status: { eq: "bogus" } }, include_content: true }) as any[];
+    expect(found).toHaveLength(1);
+    expect(found[0].validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+
+    // Single-id fetch also carries it.
+    const single = await query.execute({ id: created.id }) as any;
+    expect(single.validation_status.warnings[0].reason).toBe("enum_mismatch");
+    expect(single.validation_status.warnings[0].field).toBe("status");
+  });
+
+  it("query-notes surfaces validation_status on the default list path (lean NoteIndex shape)", async () => {
+    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 query = tools.find((t) => t.name === "query-notes")!;
+    await create.execute({ content: "x", tags: ["task"], metadata: { priority: "ULTRA" } });
+
+    // Default list mode (include_content omitted → lean NoteIndex).
+    const list = await query.execute({ tag: "task" }) as any[];
+    expect(list).toHaveLength(1);
+    expect(list[0].validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+  });
+
+  it("query-notes omits validation_status entirely when no tag declares fields (no behavior change)", async () => {
+    await store.createNote("plain note", { tags: ["untagged-schema"] });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const list = await query.execute({ tag: "untagged-schema" }) as any[];
+    expect(list[0].validation_status).toBeUndefined();
+  });
+
   it("validation never blocks the write — note exists with warnings attached", async () => {
     await store.upsertTagSchema("task", {
       fields: { priority: { type: "boolean" } },
@@ -4775,6 +5275,401 @@ describe("update-note if_missing=create (vault#309)", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// create-note `if_exists` — idempotent upsert on a path conflict (vault#555)
+// ---------------------------------------------------------------------------
+
+describe("create-note if_exists (vault#555)", async () => {
+  let store: SqliteStore;
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("default (no if_exists) still throws path_conflict — back-compat", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "first", path: "Inbox/dup" });
+    await expect(create.execute({ content: "second", path: "Inbox/dup" }))
+      .rejects.toThrow(/path_conflict/);
+  });
+
+  it('if_exists:"error" behaves identically to omitting it', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "first", path: "Inbox/dup-explicit" });
+    await expect(create.execute({ content: "second", path: "Inbox/dup-explicit", if_exists: "error" }))
+      .rejects.toThrow(/path_conflict/);
+  });
+
+  it('if_exists:"ignore" returns the existing note untouched, no mutation', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const first = await create.execute({
+      content: "original",
+      path: "Inbox/ignore-me",
+      tags: ["daily"],
+      metadata: { v: 1 },
+    }) as any;
+
+    const second = await create.execute({
+      content: "attempted overwrite",
+      path: "Inbox/ignore-me",
+      tags: ["other"],
+      metadata: { v: 2 },
+      if_exists: "ignore",
+    }) as any;
+
+    expect(second.existed).toBe(true);
+    expect(second.id).toBe(first.id);
+    expect(second.content).toBe("original"); // untouched
+    expect(second.metadata?.v).toBe(1); // untouched
+    expect(second.tags).toEqual(["daily"]); // "other" was never applied
+
+    // Confirm on disk too — no side effects at all.
+    const onDisk = await store.getNoteByPath("Inbox/ignore-me");
+    expect(onDisk!.content).toBe("original");
+    expect(onDisk!.tags).toEqual(["daily"]);
+  });
+
+  it('if_exists:"ignore" does not run schema-default backfill (genuinely zero mutation)', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    // Create the note BEFORE the schema declares a default, so the
+    // existing row is missing the field the schema would now backfill.
+    const first = await create.execute({ content: "x", path: "Inbox/predates-schema", tags: ["task"] }) as any;
+    expect(first.metadata?.priority).toBeUndefined();
+
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
+    });
+
+    const second = await create.execute({
+      content: "y",
+      path: "Inbox/predates-schema",
+      tags: ["task"],
+      if_exists: "ignore",
+    }) as any;
+    expect(second.existed).toBe(true);
+    expect(second.metadata?.priority).toBeUndefined(); // no backfill — zero mutation promise
+  });
+
+  it('if_exists:"update" full-replaces content, RFC-7386-merges metadata, and unions tags/links', async () => {
+    await store.createNote("target body", { id: "t-upd-target", path: "Targets/upd" });
+
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const first = await create.execute({
+      content: "v1",
+      path: "Inbox/update-me",
+      tags: ["daily"],
+      metadata: { a: 1, b: 2 },
+    }) as any;
+
+    const second = await create.execute({
+      content: "v2",
+      path: "Inbox/update-me",
+      tags: ["extra"],
+      metadata: { b: null, c: 3 }, // b deleted (RFC 7386), c added, a untouched
+      links: [{ target: "t-upd-target", relationship: "relates-to" }],
+      if_exists: "update",
+    }) as any;
+
+    expect(second.existed).toBe(true);
+    expect(second.id).toBe(first.id);
+    expect(second.content).toBe("v2"); // full replace
+    expect(second.metadata).toEqual({ a: 1, c: 3 }); // merged, b deleted
+    expect(second.tags?.sort()).toEqual(["daily", "extra"]); // union, nothing removed
+
+    const links = await store.getLinks(second.id, { direction: "outbound" });
+    expect(links.find((l) => l.relationship === "relates-to")?.targetId).toBe("t-upd-target");
+  });
+
+  it('if_exists:"update" with an omitted field leaves it untouched', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "v1", path: "Inbox/partial-update", metadata: { keep: "me" } });
+
+    const second = await create.execute({
+      path: "Inbox/partial-update", // no `content` — should stay "v1"
+      metadata: { added: true },
+      if_exists: "update",
+    }) as any;
+    expect(second.content).toBe("v1");
+    expect(second.metadata).toEqual({ keep: "me", added: true });
+  });
+
+  it('if_exists:"replace" wholesale-overwrites content + metadata but keeps id/createdAt and unions tags', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const first = await create.execute({
+      content: "v1",
+      path: "Inbox/replace-me",
+      tags: ["daily"],
+      metadata: { a: 1, b: 2 },
+    }) as any;
+
+    const second = await create.execute({
+      content: "v2",
+      path: "Inbox/replace-me",
+      tags: ["extra"],
+      metadata: { c: 3 }, // a and b are NOT merged in — wholesale replace
+      if_exists: "replace",
+    }) as any;
+
+    expect(second.existed).toBe(true);
+    expect(second.id).toBe(first.id);
+    expect(second.createdAt).toBe(first.createdAt);
+    expect(second.content).toBe("v2");
+    expect(second.metadata).toEqual({ c: 3 }); // a/b dropped, not merged
+    expect(second.tags?.sort()).toEqual(["daily", "extra"]); // tags stay additive
+  });
+
+  it('if_exists:"replace" with omitted content/metadata clears them to empty defaults', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "v1", path: "Inbox/replace-blank", metadata: { a: 1 } });
+
+    const second = await create.execute({
+      path: "Inbox/replace-blank",
+      if_exists: "replace",
+    }) as any;
+    expect(second.content).toBe("");
+    // An empty `{}` metadata collapses to `undefined` on read — the same
+    // convention every note with no metadata follows (rowToNote), not
+    // something special about `replace`.
+    expect(second.metadata).toBeUndefined();
+  });
+
+  it("if_exists is a no-op without a path — a pathless create can never conflict", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const a = await create.execute({ content: "one", if_exists: "ignore" }) as any;
+    const b = await create.execute({ content: "two", if_exists: "ignore" }) as any;
+    expect(a.id).not.toBe(b.id);
+    // `if_exists` was still passed, so `existed` is attached (there was
+    // simply nothing to conflict with) — `false`, not absent.
+    expect(a.existed).toBe(false);
+    expect(b.existed).toBe(false);
+  });
+
+  it("plain create-note calls (no if_exists) see zero response-shape change", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "plain" }) as any;
+    expect("existed" in result).toBe(false);
+  });
+
+  it("existed:false when if_exists is set but no conflict occurs (fresh insert)", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "fresh", path: "Inbox/fresh-one", if_exists: "update" }) as any;
+    expect(result.existed).toBe(false);
+  });
+
+  it("respects a per-item extension when disambiguating the conflict (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    // Two notes at the same path, different extensions — legal per vault#328.
+    await create.execute({ content: "csv body", path: "Reports/q1", extension: "csv" });
+    await create.execute({ content: "md body", path: "Reports/q1", extension: "md" });
+
+    // ignore against the CSV one specifically.
+    const result = await create.execute({
+      content: "attempted",
+      path: "Reports/q1",
+      extension: "csv",
+      if_exists: "ignore",
+    }) as any;
+    expect(result.existed).toBe(true);
+    expect(result.content).toBe("csv body");
+    expect(result.extension).toBe("csv");
+  });
+
+  it("batch: if_exists is per-item, not inherited from a top-level default", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "existing", path: "Inbox/batch-conflict" });
+
+    // Top-level if_exists is NOT merged into batch items (matches
+    // if_missing's contract on update-note) — the batch item below has no
+    // if_exists of its own, so it hits the default "error" path and the
+    // WHOLE batch rolls back, even though a top-level if_exists was passed.
+    await expect(create.execute({
+      if_exists: "ignore",
+      notes: [{ content: "conflict", path: "Inbox/batch-conflict" }],
+    })).rejects.toThrow(/path_conflict/);
+  });
+
+  it("batch: mixes fresh creates and if_exists hits in the same call, in order", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "pre-existing", path: "Inbox/batch-b" });
+
+    const result = await create.execute({
+      notes: [
+        { content: "a", path: "Inbox/batch-a", if_exists: "ignore" },
+        { content: "b-new", path: "Inbox/batch-b", if_exists: "ignore" },
+        { content: "c", path: "Inbox/batch-c", if_exists: "ignore" },
+      ],
+    }) as any[];
+
+    expect(result).toHaveLength(3);
+    expect(result[0].existed).toBe(false);
+    expect(result[1].existed).toBe(true);
+    expect(result[1].content).toBe("pre-existing"); // untouched
+    expect(result[2].existed).toBe(false);
+  });
+
+  it("a genuine schema violation on if_exists:update still rejects and mutates nothing", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { status: { type: "string", enum: ["open", "done"], strict: true, required: true } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "v1", path: "Inbox/strict-target", tags: ["task"], metadata: { status: "open" } });
+
+    await expect(create.execute({
+      content: "v2",
+      path: "Inbox/strict-target",
+      metadata: { status: "NOT-A-VALID-ENUM" },
+      if_exists: "update",
+    })).rejects.toThrow();
+
+    const onDisk = await store.getNoteByPath("Inbox/strict-target");
+    expect(onDisk!.content).toBe("v1"); // untouched — rejected before any write
+  });
+
+  it("if_exists:update re-validates against the CURRENT schema without re-supplying satisfied required fields", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { status: { type: "string", enum: ["open", "done"], strict: true, required: true } },
+    });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "v1", path: "Inbox/status-set", tags: ["task"], metadata: { status: "open" } });
+
+    // Only touching content — `status` is already satisfied by the
+    // EXISTING note, so re-validating the merged/projected shape (not the
+    // raw incoming item) must NOT demand it again.
+    const result = await create.execute({
+      content: "v2",
+      path: "Inbox/status-set",
+      if_exists: "update",
+    }) as any;
+    expect(result.content).toBe("v2");
+    expect(result.metadata?.status).toBe("open");
+  });
+
+  // vault#555 CRITICAL 2 (W8 fix-2 bug class): a tags-ONLY if_exists:"update"
+  // (no content/metadata) must still bump updated_at — store.tagNote genuinely
+  // mutates the note, and a frozen updated_at breaks cursor polling + sync.
+  it('if_exists:"update" with ONLY tags added still advances updated_at', async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const first = await create.execute({ content: "body", path: "Inbox/tagonly", tags: ["alpha"] }) as any;
+    const before = (await store.getNoteByPath("Inbox/tagonly"))!.updatedAt!;
+
+    // Ensure a strictly-later wall-clock so the bump is observable even if the
+    // two writes land in the same millisecond.
+    await new Promise((r) => setTimeout(r, 5));
+
+    const second = await create.execute({
+      path: "Inbox/tagonly",
+      tags: ["beta"], // ONLY a tag change — no content, no metadata
+      if_exists: "update",
+    }) as any;
+    expect(second.existed).toBe(true);
+    expect(second.tags?.sort()).toEqual(["alpha", "beta"]); // tag actually added
+    const after = (await store.getNoteByPath("Inbox/tagonly"))!.updatedAt!;
+    expect(after > before).toBe(true); // updated_at advanced
+    expect(second.id).toBe(first.id);
+  });
+
+  it('if_exists:"update" with ONLY links added still advances updated_at', async () => {
+    await store.createNote("target", { id: "tgt-linkonly", path: "Targets/linkonly" });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "body", path: "Inbox/linkonly", tags: ["alpha"] });
+    const before = (await store.getNoteByPath("Inbox/linkonly"))!.updatedAt!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    await create.execute({
+      path: "Inbox/linkonly",
+      links: [{ target: "tgt-linkonly", relationship: "relates-to" }],
+      if_exists: "update",
+    });
+    const after = (await store.getNoteByPath("Inbox/linkonly"))!.updatedAt!;
+    expect(after > before).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// create-note `summary` — compact batch response shape (vault#555)
+// ---------------------------------------------------------------------------
+
+describe("create-note summary (vault#555)", async () => {
+  let store: SqliteStore;
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("summary:true returns {created, ids, failed} instead of N full note objects", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      summary: true,
+      notes: [
+        { content: "a", path: "Inbox/sum-a" },
+        { content: "b", path: "Inbox/sum-b" },
+        { content: "c", path: "Inbox/sum-c" },
+      ],
+    }) as any;
+    expect(result.created).toBe(3);
+    expect(result.ids).toHaveLength(3);
+    expect(result.failed).toEqual([]);
+    // Not the full-object shape.
+    expect(result.notes).toBeUndefined();
+    expect(Array.isArray(result)).toBe(false);
+
+    // The ids really do resolve to the notes just created.
+    const onDisk = await store.getNoteByPath("Inbox/sum-a");
+    expect(result.ids).toContain(onDisk!.id);
+  });
+
+  it("summary:true `created` excludes if_exists hits — only counts brand-new inserts", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({ content: "pre-existing", path: "Inbox/sum-existing" });
+
+    const result = await create.execute({
+      summary: true,
+      notes: [
+        { content: "fresh", path: "Inbox/sum-fresh", if_exists: "ignore" },
+        { content: "ignored", path: "Inbox/sum-existing", if_exists: "ignore" },
+      ],
+    }) as any;
+    expect(result.created).toBe(1); // only the fresh one
+    expect(result.ids).toHaveLength(2); // both ids are still reported
+  });
+
+  it("summary is ignored on a single-note (non-batch) call", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "solo", summary: true }) as any;
+    expect(result.content).toBe("solo"); // full note object, not a summary
+    expect(result.created).toBeUndefined();
+  });
+
+  it("without summary, batch still returns full note objects (back-compat)", async () => {
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      notes: [{ content: "a", path: "Inbox/sum-nosummary" }],
+    }) as any[];
+    expect(Array.isArray(result)).toBe(true);
+    expect(result[0].content).toBe("a");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Schema inheritance via parent_names + `_default` universal parent — vault#270
 // ---------------------------------------------------------------------------