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

package/src/vault.test.ts

@@ -1554,7 +1554,16 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
-  test("update-note tags.add auto-populate does not bump updatedAt", async () => {
+  // vault#555 fix 2 REVISED this test's contract. Pre-fix-2 a tags-only
+  // `update-note` (here, adding a tag that ALSO triggers a schema-default
+  // backfill) did NOT bump `updated_at` — this test asserted that. Fix 2
+  // makes ANY tag mutation bump `updated_at` (so cursor/sync loops see it);
+  // the separate defaults backfill still rides `skipUpdatedAt: true` and
+  // doesn't itself bump. Net: the tag add bumps updatedAt exactly once, and
+  // the default still lands. (The old assertion passed only by
+  // create+update landing in the same millisecond — a latent flake fix 2
+  // turned into a real contradiction; caught on a review re-run.)
+  test("update-note tags.add bumps updatedAt AND still applies the schema default (vault#555 fix 2)", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores: close } = await import("./vault-store.ts");
@@ -1568,8 +1577,7 @@ describe("scoped MCP wrapper", async () => {
 
     const vaultStore = getVaultStore(vaultName);
     // vault#553 Decision B: backfill is explicit-`default`-only — declare
-    // one so this test still exercises an actual defaults-write (and can
-    // assert it lands without bumping updatedAt).
+    // one so this still exercises an actual defaults-write.
     await vaultStore.upsertTagSchema("person", {
       description: "A person",
       fields: { name: { type: "string", default: "unknown" } },
@@ -1582,9 +1590,13 @@ describe("scoped MCP wrapper", async () => {
 
     const note = await createNote.execute({ content: "Test" }) as any;
     const originalUpdatedAt = note.updatedAt;
+    await new Promise((r) => setTimeout(r, 5)); // deterministic ms gap
     await updateNote.execute({ id: note.id, tags: { add: ["person"] }, force: true });
     const after = await queryNotes.execute({ id: note.id }) as any;
-    expect(after.updatedAt).toBe(originalUpdatedAt);
+    // Fix 2: the tag mutation bumped updatedAt.
+    expect(after.updatedAt).not.toBe(originalUpdatedAt);
+    expect(new Date(after.updatedAt) > new Date(originalUpdatedAt)).toBe(true);
+    // The schema default still backfilled.
     expect(after.metadata.name).toBe("unknown");
 
     close();
@@ -1726,6 +1738,232 @@ describe("scoped MCP wrapper", async () => {
 
     closeAllStores();
   });
+
+  // vault#555 auth review — validation_status must not leak an out-of-scope
+  // co-tag's schema shape (field name / type / enum) to a scoped caller
+  // (the #560 leak class). A note the caller CAN see (in-scope tag) may also
+  // carry an out-of-scope tag whose schema it violates.
+  test("MCP query-notes scrubs out-of-scope tag schema from validation_status; only the in-scope tag's warning survives", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-vs-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    // In-scope tag "work" declares a field the note violates; out-of-scope
+    // "project-manhattan" declares a SECRET field/enum the note also violates.
+    await store.upsertTagSchema("work", { fields: { priority: { type: "string", enum: ["hi", "lo"] } } });
+    await store.upsertTagSchema("project-manhattan", { fields: { codeword: { type: "string", enum: ["fizzbuzz"] } } });
+    const note = await store.createNote("co-tagged", {
+      path: "CoTagged",
+      tags: ["work", "project-manhattan"],
+      metadata: { priority: "URGENT", codeword: "leaked" },
+    });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: note.id }) as any;
+
+    // The out-of-scope tag's SCHEMA SHAPE — the leak fix 3 introduced and
+    // this scrub closes — must appear nowhere in the whole response.
+    // `fizzbuzz` (its enum value) exists ONLY in project-manhattan's schema,
+    // so its total absence proves no schema-shape leak. (`codeword` is also
+    // a key in the note's OWN metadata, visible to anyone who can read the
+    // note, so it's not a schema-shape indicator.)
+    const serialized = JSON.stringify(result);
+    expect(serialized).not.toContain("fizzbuzz");
+    // The tag NAME must be gone from validation_status specifically. NOTE:
+    // it still appears in the note's `.tags` array — that's PRE-EXISTING
+    // scoped-read behavior (noteWithinTagScope has never scrubbed a returned
+    // note's tag set), independent of fix 3, and out of scope for this fix.
+    expect(JSON.stringify(result.validation_status)).not.toContain("project-manhattan");
+
+    // The in-scope tag's own warning DOES survive.
+    const vs = result.validation_status;
+    expect(vs).toBeTruthy();
+    expect(vs.schemas).toEqual(["work"]);
+    expect(vs.warnings).toHaveLength(1);
+    expect(vs.warnings[0].schema).toBe("work");
+    expect(vs.warnings[0].field).toBe("priority");
+
+    closeAllStores();
+  });
+
+  test("UNSCOPED query-notes still surfaces BOTH co-tags' validation_status (regression)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-vs-unscoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.upsertTagSchema("work", { fields: { priority: { type: "string", enum: ["hi", "lo"] } } });
+    await store.upsertTagSchema("project-manhattan", { fields: { codeword: { type: "string", enum: ["fizzbuzz"] } } });
+    const note = await store.createNote("co-tagged", {
+      path: "CoTagged",
+      tags: ["work", "project-manhattan"],
+      metadata: { priority: "URGENT", codeword: "leaked" },
+    });
+
+    const tools = generateScopedMcpTools(vaultName); // unscoped
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: note.id }) as any;
+    const vs = result.validation_status;
+    expect(vs.schemas.sort()).toEqual(["project-manhattan", "work"]);
+    expect(vs.warnings).toHaveLength(2);
+
+    closeAllStores();
+  });
+
+  // vault#555 auth-review CRITICAL: `if_exists` must NOT let a scoped MCP
+  // session read/update/replace an out-of-scope note by naming its path.
+  // The create-note wrapper pre-resolves the path and throws path_conflict on
+  // an out-of-scope hit (byte-identical to a genuine conflict). Each assertion
+  // MUST fail without the wrapper guard.
+  test('scoped create-note if_exists:"ignore" does NOT return an out-of-scope note (throws path_conflict)', async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-ignore-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("SECRET MCP PAYLOAD", { path: "Secret", tags: ["personal"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    // in-scope incoming tag passes the item-tag pre-check; the OUT-OF-SCOPE
+    // existing note at this path must still be blocked.
+    await expect(
+      create.execute({ content: "attempted read", path: "Secret", tags: ["work"], if_exists: "ignore" }),
+    ).rejects.toThrow(/path_conflict/);
+
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"update"/"replace" does NOT mutate an out-of-scope note', async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-mutate-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { keep: "me" } });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+
+    await expect(
+      create.execute({ content: "OVERWRITE", path: "Secret", tags: ["work"], metadata: { injected: true }, if_exists: "update" }),
+    ).rejects.toThrow(/path_conflict/);
+    await expect(
+      create.execute({ content: "REPLACE", path: "Secret", tags: ["work"], if_exists: "replace" }),
+    ).rejects.toThrow(/path_conflict/);
+
+    // Ground truth: the out-of-scope note is untouched by both attempts.
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ keep: "me" });
+    expect(onDisk.tags).toEqual(["personal"]);
+
+    closeAllStores();
+  });
+
+  test("scoped create-note if_exists against an IN-scope note works normally (guard doesn't over-block)", async () => {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `tagscope-ifexists-inscope-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const existing = await store.createNote("WORK BODY", { path: "MyWork", tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({ content: "x", path: "MyWork", tags: ["work"], if_exists: "ignore" }) as any;
+    expect(result.existed).toBe(true);
+    expect(result.id).toBe(existing.id);
+    expect(result.content).toBe("WORK BODY");
+
+    closeAllStores();
+  });
+
+  // vault#555 auth-review CRITICAL (RACE PATH — the incomplete-first-fix gap).
+  // The wrapper pre-check + core's proactive getNoteByPath can BOTH miss a note
+  // that a concurrent writer INSERTs, after which core's race backstop
+  // re-resolves the (now-existing, out-of-scope) winner and calls
+  // applyExistingNote on it. Without the in-core `ifExistsVisible` guard the
+  // out-of-scope content leaks / the note is mutated. We reproduce the exact
+  // TOCTOU by monkeypatching store.createNote to (a) create the out-of-scope
+  // note itself (simulating the concurrent winner) and (b) throw
+  // PathConflictError — driving execution straight into the backstop. Both
+  // assertions MUST fail without the in-core guard.
+  async function raceVault(mode: "ignore" | "update" | "replace") {
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+    const { PathConflictError } = await import("../core/src/notes.ts");
+
+    const vaultName = `tagscope-ifexists-race-${mode}-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+
+    // Monkeypatch createNote so the target path is created by a "concurrent
+    // writer" with an OUT-OF-SCOPE tag, then the real INSERT loses the race.
+    const origCreate = store.createNote.bind(store);
+    let raced = false;
+    (store as any).createNote = async (content: string, opts: any) => {
+      if (opts?.path === "Secret" && !raced) {
+        raced = true;
+        await origCreate("TOP SECRET RACE PAYLOAD", { path: "Secret", tags: ["personal"] });
+        throw new PathConflictError("Secret");
+      }
+      return origCreate(content, opts);
+    };
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const create = tools.find((t) => t.name === "create-note")!;
+    return { store, create, closeAllStores };
+  }
+
+  test('scoped create-note if_exists:"ignore" RACE backstop does NOT leak out-of-scope content', async () => {
+    const { store, create, closeAllStores } = await raceVault("ignore");
+    await expect(
+      create.execute({ content: "attempted", path: "Secret", tags: ["work"], if_exists: "ignore" }),
+    ).rejects.toThrow(/path_conflict/);
+    // The concurrently-created out-of-scope note is byte-unchanged and its
+    // payload never reached the caller (the throw carries only the path).
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD");
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"update" RACE backstop does NOT mutate the out-of-scope note', async () => {
+    const { store, create, closeAllStores } = await raceVault("update");
+    await expect(
+      create.execute({ content: "OVERWRITE", path: "Secret", tags: ["work"], metadata: { injected: true }, if_exists: "update" }),
+    ).rejects.toThrow(/path_conflict/);
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD"); // unmutated
+    expect(onDisk.metadata ?? {}).toEqual({});
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
+
+  test('scoped create-note if_exists:"replace" RACE backstop does NOT mutate the out-of-scope note', async () => {
+    const { store, create, closeAllStores } = await raceVault("replace");
+    await expect(
+      create.execute({ content: "REPLACE", path: "Secret", tags: ["work"], if_exists: "replace" }),
+    ).rejects.toThrow(/path_conflict/);
+    const onDisk = (await store.getNoteByPath("Secret"))!;
+    expect(onDisk.content).toBe("TOP SECRET RACE PAYLOAD"); // unmutated
+    expect(onDisk.tags).toEqual(["personal"]);
+    closeAllStores();
+  });
 });
 
 describe("auth permissions", () => {
@@ -3899,6 +4137,111 @@ describe("HTTP tag-scope confidentiality (security review)", async () => {
     expect(targets).toContain("NoSuchPersonal");
   });
 
+  // vault#555 auth-review CRITICAL: `if_exists` must NOT become a tag-scope
+  // bypass. A scoped token naming an out-of-scope note's PATH must not read
+  // (ignore), update, or replace it — treat it as a path_conflict (path taken,
+  // invisible to this caller). Each assertion MUST fail without the guard in
+  // applyExistingNote.
+  test('if_exists:"ignore" does NOT return an out-of-scope note by path (POST /notes)', async () => {
+    await store.createNote("SECRET WORK PAYLOAD", { path: "Secret", tags: ["personal"] });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "attempted read",
+        path: "Secret",
+        tags: ["work"], // in-scope incoming tag — passes the item-tag pre-check
+        if_exists: "ignore",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    // Path is taken but invisible to this caller → 409 path_conflict, and the
+    // secret content appears NOWHERE in the response.
+    expect(res.status).toBe(409);
+    const text = await res.text();
+    expect(text).not.toContain("SECRET WORK PAYLOAD");
+    expect(JSON.parse(text).error_type).toBe("path_conflict");
+  });
+
+  test('if_exists:"update" does NOT mutate an out-of-scope note by path (POST /notes)', async () => {
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { keep: "me" } });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "OVERWRITE ATTEMPT",
+        path: "Secret",
+        tags: ["work"],
+        metadata: { injected: true },
+        if_exists: "update",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(409);
+    // Ground truth: the out-of-scope note is byte-for-byte unchanged.
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ keep: "me" });
+    expect(onDisk.tags).toEqual(["personal"]); // "work" never applied
+  });
+
+  test('if_exists:"replace" does NOT mutate an out-of-scope note by path (POST /notes)', async () => {
+    const secret = await store.createNote("ORIGINAL SECRET", { path: "Secret", tags: ["personal"], metadata: { a: 1 } });
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "REPLACE ATTEMPT",
+        path: "Secret",
+        tags: ["work"],
+        if_exists: "replace",
+      }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(409);
+    const onDisk = (await store.getNote(secret.id))!;
+    expect(onDisk.content).toBe("ORIGINAL SECRET");
+    expect(onDisk.metadata).toEqual({ a: 1 });
+  });
+
+  test("UNSCOPED if_exists:ignore still returns the existing note (regression — guard is scope-gated)", async () => {
+    const existing = await store.createNote("PLAIN BODY", { path: "Plain", tags: ["work"] });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "x", path: "Plain", if_exists: "ignore" }),
+      store,
+      "",
+      "v",
+      NO_SCOPE,
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(existing.id);
+    expect(body.content).toBe("PLAIN BODY");
+  });
+
+  test("in-scope if_exists:ignore against an in-scope note works normally (guard doesn't over-block)", async () => {
+    const existing = await store.createNote("WORK BODY", { path: "MyWork", tags: ["work"] });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "x", path: "MyWork", tags: ["work"], if_exists: "ignore" }),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(existing.id);
+    expect(body.content).toBe("WORK BODY");
+  });
+
 });
 
 describe("HTTP /notes include_link_count + order_by=link_count (vault feedback #4)", async () => {
@@ -4185,6 +4528,34 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(body.tags).not.toContain("old");
   });
 
+  // vault#555 fix 2 — a tags-only (or links-only) PATCH with `force: true`
+  // (no `if_updated_at`) used to leave `updated_at` frozen: `updates` had no
+  // core fields, so `store.updateNote` was never called at all.
+  test("PATCH tags-only/links-only with force:true bumps updated_at", async () => {
+    await store.createNote("x", { id: "x", tags: ["old"] });
+    await store.createNote("y", { id: "y" });
+    const before = (await store.getNote("x"))!.updatedAt;
+    await new Promise((r) => setTimeout(r, 5));
+
+    const tagsRes = await handleNotes(
+      mkReq("PATCH", "/notes/x", { tags: { add: ["new"] }, force: true }),
+      store,
+      "/x",
+    );
+    const tagsBody = await tagsRes.json() as any;
+    expect(tagsBody.updatedAt).not.toBe(before);
+    expect(new Date(tagsBody.updatedAt) > new Date(before)).toBe(true);
+
+    await new Promise((r) => setTimeout(r, 5));
+    const linksRes = await handleNotes(
+      mkReq("PATCH", "/notes/x", { links: { add: [{ target: "y", relationship: "mentions" }] }, force: true }),
+      store,
+      "/x",
+    );
+    const linksBody = await linksRes.json() as any;
+    expect(new Date(linksBody.updatedAt) > new Date(tagsBody.updatedAt)).toBe(true);
+  });
+
   test("PATCH adds/removes links", async () => {
     await store.createNote("a", { id: "a" });
     await store.createNote("b", { id: "b" });
@@ -4248,6 +4619,59 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(body.links[0].targetId).toBe("c");
   });
 
+  // vault#555 — REST PATCH links.add gets the same basename/title
+  // resolution + lazy forward-ref queueing as the MCP update-note tool
+  // (both surfaces share core/wikilinks.ts's resolveOrQueueLink).
+  test("PATCH links.add resolves by BASENAME and warns+queues when unresolvable", async () => {
+    await store.createNote("a", { id: "a" });
+    await store.createNote("Bob's note", { path: "People/Bob" });
+    const byTitle = await handleNotes(
+      mkReq("PATCH", "/notes/a", { links: { add: [{ target: "Bob", relationship: "knows" }] }, force: true }),
+      store,
+      "/a",
+    );
+    expect(byTitle.status).toBe(200);
+    const byTitleBody = await byTitle.json() as any;
+    expect(byTitleBody.warnings).toBeUndefined();
+    expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(1);
+
+    const unresolved = await handleNotes(
+      mkReq("PATCH", "/notes/a", { links: { add: [{ target: "Not Yet Real", relationship: "wants" }] }, force: true }),
+      store,
+      "/a",
+    );
+    const unresolvedBody = await unresolved.json() as any;
+    expect(unresolvedBody.warnings).toBeDefined();
+    expect(unresolvedBody.warnings[0].code).toBe("unresolved_link");
+    expect(unresolvedBody.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#555 — POST /notes batch: a link to a note created LATER in the
+  // same batch must resolve (forward-ref), matching MCP create-note.
+  test("POST /notes batch: a link to a note created LATER in the same batch resolves (forward-ref)", async () => {
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        notes: [
+          { path: "RestA", content: "links to RestB", links: [{ target: "RestB", relationship: "knows" }] },
+          { path: "RestB", content: "the target" },
+        ],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any[];
+    const a = body.find((n: any) => n.path === "RestA");
+    expect(a.warnings).toBeUndefined();
+    const links = await store.getLinks(a.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.relationship).toBe("knows");
+  });
+
   test("PATCH without a link mutation or flag does NOT include links", async () => {
     await store.createNote("a", { id: "a" });
     await store.createNote("b", { id: "b" });
@@ -4436,6 +4860,42 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect((await store.getNote("x"))!.content).toBe("hi hi");
   });
 
+  // vault#555 fix 7 (INVESTIGATE) — a tester reported "old_text not found"
+  // failing 7/8 for batch/parallel content_edit calls sharing the same
+  // old_text. Not reproducible against DIFFERENT notes (see
+  // core/src/core.test.ts's matching investigation for the full writeup
+  // and the "SAME note" control that DOES reproduce "1 succeeds, 7 fail" —
+  // correct behavior, likely what the original report actually hit). REST
+  // parity check here: N parallel PATCH requests, same old_text, different
+  // notes, all succeed.
+  test("PATCH parallel: N concurrent content_edit calls with the SAME old_text on DIFFERENT notes all succeed", async () => {
+    const N = 8;
+    const notes = [];
+    for (let i = 0; i < N; i++) {
+      notes.push(await store.createNote(`prefix TARGET_TEXT suffix-${i}`, { path: `rest-ce-${i}` }));
+    }
+
+    const results = await Promise.all(
+      notes.map((n) =>
+        handleNotes(
+          mkReq("PATCH", `/notes/${n.id}`, {
+            content_edit: { old_text: "TARGET_TEXT", new_text: "REPLACED" },
+            force: true,
+          }),
+          store,
+          `/${n.id}`,
+        ),
+      ),
+    );
+    for (const res of results) {
+      expect(res.status).toBe(200);
+    }
+    for (let i = 0; i < N; i++) {
+      const fresh = await store.getNote(notes[i]!.id);
+      expect(fresh!.content).toBe(`prefix REPLACED suffix-${i}`);
+    }
+  });
+
   test("PATCH rejects content + append combination with 400", async () => {
     await store.createNote("seed", { id: "x" });
 
@@ -4618,6 +5078,87 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
   });
 });
 
+// vault#555 fix 3 — validation_status used to be visible ONLY on the
+// one-time create/update WRITE response; a caller reading the note back
+// (GET single note, or the structured-query list) saw nothing at all,
+// contradicting "advisory violations surface as warnings" for an
+// enum_mismatch on a non-strict (even indexed) field.
+describe("HTTP GET /notes — validation_status on reads (vault#555)", async () => {
+  test("GET /notes/:id surfaces validation_status (enum_mismatch on an indexed field)", async () => {
+    const res0 = await handleTags(
+      mkReq("PUT", "/tags/widget555", { fields: { status: { type: "string", enum: ["a", "b"], indexed: true } } }),
+      store,
+      "/widget555",
+    );
+    expect(res0.status).toBe(200);
+    const created = await store.createNote("x", { tags: ["widget555"], metadata: { status: "bogus" } });
+
+    const res = await handleNotes(mkReq("GET", `/notes/${created.id}`), store, `/${created.id}`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+    expect(body.validation_status.warnings[0].field).toBe("status");
+  });
+
+  test("GET /notes (structured query list) surfaces validation_status per note", async () => {
+    await store.upsertTagSchema("task555list", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    await store.createNote("x", { tags: ["task555list"], metadata: { priority: "ULTRA" } });
+
+    const res = await handleNotes(mkReq("GET", "/notes?tag=task555list"), store, "");
+    expect(res.status).toBe(200);
+    const body = await res.json() as any[];
+    expect(body).toHaveLength(1);
+    expect(body[0].validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+  });
+
+  test("GET /notes/:id and list both omit validation_status when no tag declares fields", async () => {
+    const note = await store.createNote("plain", { tags: ["plain555"] });
+    const single = await handleNotes(mkReq("GET", `/notes/${note.id}`), store, `/${note.id}`);
+    const singleBody = await single.json() as any;
+    expect(singleBody.validation_status).toBeUndefined();
+
+    const list = await handleNotes(mkReq("GET", "/notes?tag=plain555"), store, "");
+    const listBody = await list.json() as any[];
+    expect(listBody[0].validation_status).toBeUndefined();
+  });
+
+  // vault#555 auth review — REST parity for the validation_status scope
+  // scrub (the #560 leak class). A scoped caller reading a note co-tagged
+  // with an out-of-scope tag must not learn that tag's schema shape.
+  test("GET /notes/:id and list scrub out-of-scope co-tag schema from validation_status for a scoped caller", async () => {
+    await store.upsertTagSchema("workrs", { fields: { priority: { type: "string", enum: ["hi", "lo"] } } });
+    await store.upsertTagSchema("manhattanrs", { fields: { codeword: { type: "string", enum: ["fizzbuzz"] } } });
+    const note = await store.createNote("co-tagged", {
+      path: "CoTaggedRS",
+      tags: ["workrs", "manhattanrs"],
+      metadata: { priority: "URGENT", codeword: "leaked" },
+    });
+    const scope = { allowed: new Set(["workrs"]), raw: ["workrs"] };
+
+    // Single GET — `fizzbuzz` (the out-of-scope enum value) exists only in
+    // manhattanrs's schema, so its absence proves no schema-shape leak. The
+    // tag name is scrubbed from validation_status (still in `.tags` —
+    // pre-existing, out of scope; see the MCP counterpart test).
+    const single = await handleNotes(mkReq("GET", `/notes/${note.id}`), store, `/${note.id}`, undefined, scope);
+    const singleBody = await single.json() as any;
+    expect(JSON.stringify(singleBody)).not.toContain("fizzbuzz");
+    expect(JSON.stringify(singleBody.validation_status)).not.toContain("manhattanrs");
+    expect(singleBody.validation_status.schemas).toEqual(["workrs"]);
+    expect(singleBody.validation_status.warnings).toHaveLength(1);
+    expect(singleBody.validation_status.warnings[0].field).toBe("priority");
+
+    // List GET
+    const list = await handleNotes(mkReq("GET", "/notes?tag=workrs&include_content=true"), store, "", undefined, scope);
+    const listBody = await list.json() as any[];
+    expect(JSON.stringify(listBody)).not.toContain("fizzbuzz");
+    const target = listBody.find((n) => n.id === note.id);
+    expect(JSON.stringify(target.validation_status)).not.toContain("manhattanrs");
+    expect(target.validation_status.schemas).toEqual(["workrs"]);
+  });
+});
+
 describe("HTTP POST /notes — validation_status attachment (vault#287)", async () => {
   // Mirror of the PATCH cases for create. The MCP create-note path
   // attaches validation_status; HTTP POST must match (vault#287).
@@ -4677,6 +5218,206 @@ describe("HTTP POST /notes — validation_status attachment (vault#287)", async
   });
 });
 
+// vault#555 — HTTP POST /notes with if_exists: idempotent upsert on a path
+// conflict. Mirrors the MCP create-note tool's if_exists contract exactly
+// (independent REST-layer reimplementation, same core primitives).
+describe("HTTP POST /notes — if_exists (vault#555)", async () => {
+  test("default (no if_exists) still 409s — back-compat", async () => {
+    await store.createNote("first", { path: "Inbox/rest-dup" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "second", path: "Inbox/rest-dup" }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(409);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("path_conflict");
+  });
+
+  test('if_exists:"ignore" returns 201 with the existing note untouched + existed:true', async () => {
+    const first = await store.createNote("original", { path: "Inbox/rest-ignore", metadata: { v: 1 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "attempted overwrite",
+        path: "Inbox/rest-ignore",
+        metadata: { v: 2 },
+        if_exists: "ignore",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(first.id);
+    expect(body.content).toBe("original");
+    expect(body.metadata?.v).toBe(1);
+  });
+
+  test('if_exists:"update" full-replaces content and RFC-7386-merges metadata', async () => {
+    await store.createNote("v1", { path: "Inbox/rest-update", metadata: { a: 1, b: 2 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "v2",
+        path: "Inbox/rest-update",
+        metadata: { b: null, c: 3 },
+        if_exists: "update",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.content).toBe("v2");
+    expect(body.metadata).toEqual({ a: 1, c: 3 });
+  });
+
+  test('if_exists:"replace" wholesale-overwrites content + metadata, keeps id/createdAt', async () => {
+    const first = await store.createNote("v1", { path: "Inbox/rest-replace", metadata: { a: 1, b: 2 } });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "v2",
+        path: "Inbox/rest-replace",
+        metadata: { c: 3 },
+        if_exists: "replace",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.id).toBe(first.id);
+    expect(body.createdAt).toBe(first.createdAt);
+    expect(body.content).toBe("v2");
+    expect(body.metadata).toEqual({ c: 3 });
+  });
+
+  test("plain POST (no if_exists) sees zero response-shape change", async () => {
+    const res = await handleNotes(mkReq("POST", "/notes", { content: "plain" }), store, "");
+    const body = await res.json() as any;
+    expect("existed" in body).toBe(false);
+  });
+
+  test("batch: if_exists is per-item — a top-level default is NOT inherited", async () => {
+    await store.createNote("existing", { path: "Inbox/rest-batch-conflict" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        if_exists: "ignore",
+        notes: [{ content: "conflict", path: "Inbox/rest-batch-conflict" }],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(409);
+  });
+
+  test("summary:true returns {created, ids, failed} for a batch", async () => {
+    await store.createNote("pre-existing", { path: "Inbox/rest-sum-existing" });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        summary: true,
+        notes: [
+          { content: "fresh", path: "Inbox/rest-sum-fresh", if_exists: "ignore" },
+          { content: "ignored", path: "Inbox/rest-sum-existing", if_exists: "ignore" },
+        ],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.created).toBe(1);
+    expect(body.ids).toHaveLength(2);
+    expect(body.failed).toEqual([]);
+  });
+
+  test("summary is ignored on a single-note POST", async () => {
+    const res = await handleNotes(mkReq("POST", "/notes", { content: "solo", summary: true }), store, "");
+    const body = await res.json() as any;
+    expect(body.content).toBe("solo");
+    expect(body.created).toBeUndefined();
+  });
+
+  // vault#555 CRITICAL 2 (REST tripwire — the generalist-flagged coverage gap:
+  // the core-side tests didn't guard the REST gate, so reverting routes.ts's
+  // gate alone left all tests green). REST parity of the two core tests.
+  test('if_exists:"update" with ONLY tags added still advances updated_at (POST /notes)', async () => {
+    const first = await store.createNote("body", { path: "rest-tagonly", tags: ["alpha"] });
+    const before = first.updatedAt!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { path: "rest-tagonly", tags: ["beta"], if_exists: "update" }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.existed).toBe(true);
+    expect(body.tags?.sort()).toEqual(["alpha", "beta"]);
+    const after = (await store.getNote(first.id))!.updatedAt!;
+    expect(after > before).toBe(true);
+  });
+
+  test('if_exists:"update" with ONLY links added still advances updated_at (POST /notes)', async () => {
+    await store.createNote("target", { id: "rest-tgt-linkonly", path: "Targets/rest-linkonly" });
+    const first = await store.createNote("body", { path: "rest-linkonly", tags: ["alpha"] });
+    const before = first.updatedAt!;
+    await new Promise((r) => setTimeout(r, 5));
+
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        path: "rest-linkonly",
+        links: [{ target: "rest-tgt-linkonly", relationship: "relates-to" }],
+        if_exists: "update",
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const after = (await store.getNote(first.id))!.updatedAt!;
+    expect(after > before).toBe(true);
+  });
+});
+
+// vault#555 — has_broken_links / include_broken_links on GET /notes.
+describe("HTTP GET /notes — has_broken_links / include_broken_links (vault#555)", async () => {
+  test("has_broken_links=true filters to notes with a dangling wikilink", async () => {
+    await store.createNote("[[Nowhere]]", { path: "rest-broken" });
+    await store.createNote("clean", { path: "rest-clean" });
+    const res = await handleNotes(mkReq("GET", "/notes?has_broken_links=true&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.path)).toEqual(["rest-broken"]);
+  });
+
+  test("has_broken_links=false excludes them", async () => {
+    await store.createNote("[[Nowhere]]", { path: "rest-broken2" });
+    await store.createNote("clean", { path: "rest-clean2" });
+    const res = await handleNotes(mkReq("GET", "/notes?has_broken_links=false&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    expect(body.map((n) => n.path)).toEqual(["rest-clean2"]);
+  });
+
+  test("include_broken_links on a single note surfaces {target, relationship}", async () => {
+    await store.createNote("[[Ghost]]", { path: "rest-single-broken" });
+    const res = await handleNotes(mkReq("GET", "/notes?id=rest-single-broken&include_broken_links=true"), store, "");
+    const body = await res.json() as any;
+    expect(body.broken_links).toEqual([{ target: "Ghost", relationship: "wikilink" }]);
+  });
+
+  test("include_broken_links in list mode is batched per note", async () => {
+    await store.createNote("[[Ghost A]]", { path: "rest-list-a" });
+    await store.createNote("clean", { path: "rest-list-b" });
+    const res = await handleNotes(mkReq("GET", "/notes?include_broken_links=true&include_content=true"), store, "");
+    const body = await res.json() as any[];
+    const byPath = new Map(body.map((n: any) => [n.path, n.broken_links]));
+    expect(byPath.get("rest-list-a")).toEqual([{ target: "Ghost A", relationship: "wikilink" }]);
+    expect(byPath.get("rest-list-b")).toEqual([]);
+  });
+});
+
 // vault#309 — HTTP PATCH /notes/:id with if_missing: "create" mirrors
 // the MCP update-note path. Sync loops (Gitcoin Brain et al) use this
 // for idempotent upsert without a separate query-first round trip.