@openparachute/vault 0.5.1 → 0.5.2-rc.1

package/src/vault.test.ts

@@ -11,8 +11,13 @@ import { BunStore } from "./vault-store.ts";
 import { generateMcpTools } from "../core/src/mcp.ts";
 import { getLinksHydrated } from "../core/src/links.ts";
 import { buildVaultProjection } from "../core/src/vault-projection.ts";
-import { handleNotes, handleTags, handleFindPath, handleVault } from "./routes.ts";
+import { handleNotes, handleTags, handleFindPath, handleVault, handleUnresolvedWikilinks } from "./routes.ts";
+import { expandTokenTagScope } from "./tag-scope.ts";
+import type { TagScopeCtx } from "./routes.ts";
 import { extractApiKey } from "./auth.ts";
+import { startTranscriptionWorker } from "./transcription-worker.ts";
+import { setTranscriptionWorker } from "./transcription-registry.ts";
+import type { Store } from "../core/src/types.ts";
 
 let db: Database;
 let store: BunStore;
@@ -1462,6 +1467,143 @@ describe("scoped MCP wrapper", async () => {
 
     close();
   });
+
+  // -- tag-scope confidentiality: expand_links + include_links (security
+  //    review) -----------------------------------------------------------
+  //
+  // These pin the MCP side of the expand_links / include_links leaks. A
+  // tag-scoped session must NOT inline out-of-scope note content via
+  // expand_links, and must NOT hydrate out-of-scope neighbor summaries via
+  // include_links. The unscoped path must remain fully functional. They
+  // MUST fail if the predicate / link-scrub is removed.
+
+  test("MCP expand_links does NOT inline out-of-scope wikilinked content", 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-expand-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    // Out-of-scope #personal note holds the secret; in-scope #work note links it.
+    await store.createNote("SECRET PERSONAL BODY", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("intro [[Secret]]", { path: "Work", tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      id: work.id,
+      include_content: true,
+      expand_links: true,
+    }) as any;
+
+    expect(result.content).not.toContain("SECRET PERSONAL BODY");
+    // Wikilink stays literal — indistinguishable from not-found.
+    expect(result.content).toContain("[[Secret]]");
+
+    closeAllStores();
+  });
+
+  test("MCP expand_links multi-hop (depth>1) does not leak out-of-scope content", 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-expand-deep-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("DEEP PERSONAL SECRET", { path: "Deep", tags: ["personal"] });
+    await store.createNote("mid [[Deep]]", { path: "Mid", tags: ["work"] });
+    const top = await store.createNote("top [[Mid]]", { path: "Top", tags: ["work"] });
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      id: top.id,
+      include_content: true,
+      expand_links: true,
+      expand_depth: 3,
+    }) as any;
+
+    // In-scope Mid inlines; out-of-scope Deep never does, at any depth.
+    expect(result.content).toContain("mid");
+    expect(result.content).not.toContain("DEEP PERSONAL SECRET");
+
+    closeAllStores();
+  });
+
+  test("UNSCOPED MCP expand_links still inlines wikilinked content (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-expand-unscoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    await store.createNote("PERSONAL BODY", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("intro [[Secret]]", { path: "Work", tags: ["work"] });
+
+    // No auth → unscoped session. Expansion must behave exactly as before.
+    const tools = generateScopedMcpTools(vaultName);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({
+      id: work.id,
+      include_content: true,
+      expand_links: true,
+    }) as any;
+
+    expect(result.content).toContain("PERSONAL BODY");
+
+    closeAllStores();
+  });
+
+  test("MCP include_links strips out-of-scope NEIGHBOR summaries", 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-incl-links-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const secret = await store.createNote("secret", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("work", { path: "Work", tags: ["work"] });
+    await store.createLink(work.id, secret.id, "references");
+
+    const tools = generateScopedMcpTools(vaultName, authForTags(["work"]) as any);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: work.id, include_links: true }) as any;
+
+    const links = (result.links ?? []) as any[];
+    // No surviving link may reference the out-of-scope note's id/path.
+    const serialized = JSON.stringify(links);
+    expect(serialized).not.toContain(secret.id);
+    expect(serialized).not.toContain("Secret");
+
+    closeAllStores();
+  });
+
+  test("UNSCOPED MCP include_links still hydrates the full neighbor (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-incl-links-unscoped-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    const secret = await store.createNote("secret", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("work", { path: "Work", tags: ["work"] });
+    await store.createLink(work.id, secret.id, "references");
+
+    const tools = generateScopedMcpTools(vaultName);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = await query.execute({ id: work.id, include_links: true }) as any;
+
+    const links = (result.links ?? []) as any[];
+    expect(links.length).toBe(1);
+    expect(JSON.stringify(links)).toContain(secret.id);
+
+    closeAllStores();
+  });
 });
 
 describe("auth permissions", () => {
@@ -2721,6 +2863,171 @@ describe("HTTP /notes", async () => {
       const body = await res.json() as any[];
       expect(body.map((n) => n.content)).toEqual(["new"]);
     });
+
+    // ---- JSON `metadata=<json>` alias (symmetric with the MCP nested obj) ----
+    //
+    // Before this alias, a `?metadata={...}` param was silently dropped: the
+    // bracket grammar never matched it, `queryOpts.metadata` stayed undefined,
+    // and the query returned ALL tag-matching notes — a silent wrong result.
+
+    test("alias `metadata={field:{op:value}}` filters on an indexed field", async () => {
+      await declareIndexed();
+      await store.createNote("open-1", { metadata: { status: "open" } });
+      await store.createNote("open-2", { metadata: { status: "open" } });
+      await store.createNote("closed", { metadata: { status: "closed" } });
+      const q = encodeURIComponent(JSON.stringify({ status: { eq: "open" } }));
+      const res = await handleNotes(
+        mkReq("GET", `/notes?metadata=${q}&include_content=true`),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content).sort()).toEqual(["open-1", "open-2"]);
+    });
+
+    test("alias shorthand equality `metadata={field:value}` works via json_extract fallback", async () => {
+      // No declareIndexed — shorthand routes through the engine's json_extract
+      // exact-match path, no indexed declaration required.
+      await store.createNote("matches", { metadata: { status: "open" } });
+      await store.createNote("other", { metadata: { status: "closed" } });
+      const q = encodeURIComponent(JSON.stringify({ status: "open" }));
+      const res = await handleNotes(
+        mkReq("GET", `/notes?metadata=${q}&include_content=true`),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["matches"]);
+    });
+
+    test("alias and bracket form return identical results for the same indexed-field operator query", async () => {
+      await declareIndexed();
+      for (const p of [1, 2, 3, 4, 5]) {
+        await store.createNote(`p${p}`, { metadata: { priority: p } });
+      }
+      // JSON preserves the real number type 3; bracket form passes "3" as a
+      // string. Both must coerce to the same range result against the INTEGER
+      // indexed column — this guards the type-coercion edge.
+      const aliasQ = encodeURIComponent(JSON.stringify({ priority: { gte: 3 } }));
+      const aliasRes = await handleNotes(
+        mkReq("GET", `/notes?metadata=${aliasQ}&include_content=true`),
+        store,
+        "",
+      );
+      const bracketRes = await handleNotes(
+        mkReq("GET", "/notes?meta[priority][gte]=3&include_content=true"),
+        store,
+        "",
+      );
+      const aliasBody = await aliasRes.json() as any[];
+      const bracketBody = await bracketRes.json() as any[];
+      expect(aliasBody.map((n) => n.content).sort()).toEqual(["p3", "p4", "p5"]);
+      expect(aliasBody.map((n) => n.content).sort()).toEqual(
+        bracketBody.map((n) => n.content).sort(),
+      );
+    });
+
+    test("malformed JSON in `metadata=` rejects with 400 INVALID_QUERY", async () => {
+      const res = await handleNotes(
+        mkReq("GET", "/notes?metadata=" + encodeURIComponent("{not json")),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("JSON object");
+    });
+
+    test("non-object `metadata=` JSON (array) rejects with 400 INVALID_QUERY", async () => {
+      const res = await handleNotes(
+        mkReq("GET", "/notes?metadata=" + encodeURIComponent(JSON.stringify(["status"]))),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+    });
+
+    test("primitive-scalar `metadata=` JSON (number / bare string) rejects with 400 INVALID_QUERY", async () => {
+      // `metadata=42` and `metadata="open"` are valid JSON but not objects —
+      // both fall through the non-object branch.
+      for (const raw of ["42", JSON.stringify("open")]) {
+        const res = await handleNotes(
+          mkReq("GET", "/notes?metadata=" + encodeURIComponent(raw)),
+          store,
+          "",
+        );
+        expect(res.status).toBe(400);
+        const body = await res.json() as any;
+        expect(body.code).toBe("INVALID_QUERY");
+      }
+    });
+
+    test("empty-object alias `metadata={}` is treated as absent and composes with a bracket filter", async () => {
+      // `{}` carries no filter intent — it must neither set a metadata filter
+      // NOR trip the both-forms 400 guard. So `metadata={}` + a bracket
+      // metadata filter is a 200 filtered by the bracket form only.
+      await declareIndexed();
+      await store.createNote("hi", { metadata: { priority: 5 } });
+      await store.createNote("lo", { metadata: { priority: 1 } });
+      const res = await handleNotes(
+        mkReq("GET", "/notes?metadata=" + encodeURIComponent("{}") + "&meta[priority][gte]=3&include_content=true"),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      expect(body.map((n) => n.content)).toEqual(["hi"]);
+    });
+
+    test("both `metadata=` alias AND `meta[...]` bracket params present rejects with 400 INVALID_QUERY", async () => {
+      await declareIndexed();
+      const q = encodeURIComponent(JSON.stringify({ status: { eq: "open" } }));
+      const res = await handleNotes(
+        mkReq("GET", `/notes?metadata=${q}&meta[priority][gte]=3`),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("INVALID_QUERY");
+      expect(body.error).toContain("not both");
+    });
+
+    test("regression: previously-silently-dropped `?metadata={status:{eq:pending}}` now actually filters", async () => {
+      await declareIndexed();
+      await store.createNote("pending-1", { metadata: { status: "pending" } });
+      await store.createNote("pending-2", { metadata: { status: "pending" } });
+      await store.createNote("done", { metadata: { status: "done" } });
+      const q = encodeURIComponent(JSON.stringify({ status: { eq: "pending" } }));
+      const res = await handleNotes(
+        mkReq("GET", `/notes?metadata=${q}&include_content=true`),
+        store,
+        "",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json() as any[];
+      // Before the fix this returned ALL three notes (filter dropped). Now it
+      // returns only the two pending ones.
+      expect(body.map((n) => n.content).sort()).toEqual(["pending-1", "pending-2"]);
+    });
+
+    test("alias with an unknown operator surfaces the engine's 400 UNKNOWN_OPERATOR", async () => {
+      await declareIndexed();
+      const q = encodeURIComponent(JSON.stringify({ priority: { bogus: 5 } }));
+      const res = await handleNotes(
+        mkReq("GET", `/notes?metadata=${q}`),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.code).toBe("UNKNOWN_OPERATOR");
+    });
   });
 
   // -------------------------------------------------------------------------
@@ -2803,7 +3110,10 @@ describe("HTTP /notes", async () => {
       expect(res.status).toBe(404);
     });
 
-    test("400 invalid_target when target is not a transcript note", async () => {
+    test("400 no_failed_attachment when target is a regular note with no failed audio", async () => {
+      // A note without `transcript_status` frontmatter is treated as a
+      // possible legacy in-body memo (finding F). With no attachment carrying
+      // a failed transcription there's nothing to retry → no_failed_attachment.
       await store.createNote("regular note", { id: "regular" });
       const res = await handleNotes(
         mkReq("POST", "/notes/regular/retry-transcription"),
@@ -2813,7 +3123,7 @@ describe("HTTP /notes", async () => {
       );
       expect(res.status).toBe(400);
       const body = await res.json() as any;
-      expect(body.error).toBe("invalid_target");
+      expect(body.error).toBe("no_failed_attachment");
     });
 
     test("400 not_failed when transcript already succeeded", async () => {
@@ -2897,6 +3207,606 @@ describe("HTTP /notes", async () => {
       expect(res.status).toBe(405);
       delete process.env.ASSETS_DIR;
     });
+
+    // -----------------------------------------------------------------------
+    // Legacy in-body memo retry (finding F). The target is the memo note
+    // itself (no `transcript_status` frontmatter); it directly owns a failed
+    // audio attachment. The request must reset the attachment preserving
+    // `transcribe_origin: "legacy"` and re-arm `transcribe_stub: true` so the
+    // worker's legacy success path will write the transcript back into the
+    // body. End-to-end re-transcription is covered in
+    // transcription-worker.test.ts.
+    // -----------------------------------------------------------------------
+    async function seedLegacyFailedMemo(opts: {
+      noteId?: string;
+      audioPath?: string;
+      withFile?: boolean;
+    } = {}): Promise<{ noteId: string; attachmentId: string; audioPath: string }> {
+      const noteId = opts.noteId ?? "legacy-memo";
+      const audioPath = opts.audioPath ?? `${noteId}/voice.webm`;
+      // The capture body after a terminal failure: marker replaced the
+      // placeholder, embed intact, stub cleared by the worker.
+      const note = await store.createNote(
+        `# 🎙️ Voice memo\n\n_Recorded sometime._\n\n_Transcription unavailable._\n\n![[${audioPath}]]\n`,
+        { id: noteId },
+      );
+      const att = await store.addAttachment(note.id, audioPath, "audio/webm", {
+        transcribe_status: "failed",
+        // legacy origin is the default (undefined); leave it off to model the
+        // genuine legacy capture shape.
+        transcribe_error: "scribe down",
+        transcribe_attempts: 3,
+      });
+      const assetsRoot = join(tmpDir, "assets");
+      if (opts.withFile !== false) {
+        mkdirSync(join(assetsRoot, audioPath.split("/").slice(0, -1).join("/")), { recursive: true });
+        writeFileSync(join(assetsRoot, audioPath), Buffer.from([1, 2, 3]));
+      }
+      process.env.ASSETS_DIR = assetsRoot;
+      return { noteId, attachmentId: att.id, audioPath };
+    }
+
+    test("legacy in-body memo: 202, resets attachment (legacy origin) + re-arms stub", async () => {
+      const { noteId, attachmentId, audioPath } = await seedLegacyFailedMemo();
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${noteId}/retry-transcription`),
+        store,
+        `/${noteId}/retry-transcription`,
+        "default",
+      );
+      expect(res.status).toBe(202);
+      const body = await res.json() as any;
+      expect(body.status).toBe("queued");
+      expect(body.attachment_id).toBe(attachmentId);
+      expect(body.attachment_path).toBe(audioPath);
+      expect(body.transcript_note_id).toBe(noteId);
+
+      // Attachment reset to pending, legacy origin preserved (NOT flipped to
+      // auto — that would orphan the in-body embed), failure state cleared.
+      const att = await store.getAttachment(attachmentId);
+      expect(att?.metadata?.transcribe_status).toBe("pending");
+      expect(att?.metadata?.transcribe_origin).toBe("legacy");
+      expect(att?.metadata?.transcribe_error).toBeUndefined();
+      expect(att?.metadata?.transcribe_attempts).toBeUndefined();
+
+      // Stub re-armed on the note — without this the worker's legacy success
+      // path early-returns and never writes the transcript back.
+      const updated = await store.getNote(noteId);
+      expect((updated!.metadata as any)?.transcribe_stub).toBe(true);
+      // Body untouched by the retry request itself (embed + marker intact).
+      expect(updated!.content).toContain(`![[${audioPath}]]`);
+      expect(updated!.content).toContain("_Transcription unavailable._");
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("legacy in-body memo: 404 audio_missing when the file is gone", async () => {
+      const { noteId } = await seedLegacyFailedMemo({
+        noteId: "legacy-gone",
+        withFile: false,
+      });
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${noteId}/retry-transcription`),
+        store,
+        `/${noteId}/retry-transcription`,
+        "default",
+      );
+      expect(res.status).toBe(404);
+      const body = await res.json() as any;
+      expect(body.error).toBe("audio_missing");
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("legacy in-body memo: end-to-end retry round-trip (capture → fail → retry → success)", async () => {
+      // Start from the CANONICAL capture body (recorder.ts memoNoteContent
+      // shape): header + _Recorded_ + _Transcript pending._ + ![[embed]],
+      // with transcribe_stub: true.
+      const audioPath = "e2e/voice.webm";
+      const captureBody =
+        "# 🎙️ Voice memo\n\n_Recorded sometime._\n\n_Transcript pending._\n\n![[e2e/voice.webm]]\n";
+      await store.createNote(captureBody, {
+        id: "e2e-memo",
+        metadata: { transcribe_stub: true },
+      });
+      const att = await store.addAttachment("e2e-memo", audioPath, "audio/webm", {
+        transcribe_status: "pending",
+        transcribe_attempts: 2, // one more failure flips to terminal at maxAttempts=3
+      });
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, "e2e"), { recursive: true });
+      writeFileSync(join(assetsRoot, audioPath), Buffer.from([1, 2, 3]));
+      process.env.ASSETS_DIR = assetsRoot;
+
+      // What a first-try success would have produced (for the final assert).
+      const firstTrySuccessBody =
+        "# 🎙️ Voice memo\n\n_Recorded sometime._\n\nthe spoken words\n\n![[e2e/voice.webm]]\n";
+
+      // --- Phase 1: terminal failure. Worker writes the marker in place,
+      // preserving the embed, and clears the stub.
+      let fetchMode: "fail" | "succeed" = "fail";
+      const fetchImpl = (async () => {
+        if (fetchMode === "fail") {
+          return new Response("scribe down", { status: 500 });
+        }
+        return new Response(JSON.stringify({ text: "the spoken words" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      }) as typeof fetch;
+
+      const worker = startTranscriptionWorker({
+        vaultList: () => ["default"],
+        getStore: () => store as unknown as Store,
+        scribeUrl: "http://scribe.test",
+        resolveAssetsDir: () => process.env.ASSETS_DIR!,
+        pollIntervalMs: 10_000_000,
+        maxAttempts: 3,
+        fetchImpl,
+        logger: { error: () => {}, info: () => {} },
+      });
+      setTranscriptionWorker(worker);
+      try {
+        await worker.tick();
+
+        const failedNote = await store.getNote("e2e-memo");
+        // Marker replaced the placeholder in place; embed + surrounding body intact.
+        expect(failedNote!.content).toBe(
+          "# 🎙️ Voice memo\n\n_Recorded sometime._\n\n_Transcription unavailable._\n\n![[e2e/voice.webm]]\n",
+        );
+        expect((failedNote!.metadata as any)?.transcribe_stub).toBeUndefined();
+        const failedAtt = await store.getAttachment(att.id);
+        expect(failedAtt?.metadata?.transcribe_status).toBe("failed");
+
+        // --- Phase 2: retry via the legacy route form (POST on the memo note).
+        // Deregister the worker so the retry is "sweep-only" — that lets us
+        // observe the reset + stub re-arm deterministically before the worker
+        // picks the row back up (otherwise the route's fire-and-forget kick
+        // would race our assertions and complete the success in-line).
+        setTranscriptionWorker(null);
+        fetchMode = "succeed";
+        const retryRes = await handleNotes(
+          mkReq("POST", "/notes/e2e-memo/retry-transcription"),
+          store,
+          "/e2e-memo/retry-transcription",
+          "default",
+        );
+        expect(retryRes.status).toBe(202);
+        expect((await retryRes.json() as any).worker).toBe("sweep-only");
+
+        // Attachment back to pending + legacy origin; stub re-armed on the note.
+        const pendingAtt = await store.getAttachment(att.id);
+        expect(pendingAtt?.metadata?.transcribe_status).toBe("pending");
+        expect(pendingAtt?.metadata?.transcribe_origin).toBe("legacy");
+        const rearmed = await store.getNote("e2e-memo");
+        expect((rearmed!.metadata as any)?.transcribe_stub).toBe(true);
+
+        // --- Phase 3: worker succeeds on the retry (sweep tick). Transcript
+        // replaces the _Transcription unavailable._ marker IN PLACE; embed
+        // preserved; final body is byte-identical to a first-try success.
+        setTranscriptionWorker(worker);
+        await worker.tick();
+        const success = await store.getNote("e2e-memo");
+        expect(success!.content).toBe(firstTrySuccessBody);
+        expect(success!.content).toContain("![[e2e/voice.webm]]");
+        expect((success!.metadata as any)?.transcribe_stub).toBeUndefined();
+        const doneAtt = await store.getAttachment(att.id);
+        expect(doneAtt?.metadata?.transcribe_status).toBe("done");
+        expect(doneAtt?.metadata?.transcript).toBe("the spoken words");
+      } finally {
+        await worker.stop();
+        setTranscriptionWorker(null);
+        delete process.env.ASSETS_DIR;
+      }
+    });
+
+    // ---- Optimistic concurrency on the stub re-stamp (vault#435) ----------
+    // The retry endpoint does a read-transform-write on the memo note to
+    // re-arm `transcribe_stub: true`. Without an `if_updated_at` precondition,
+    // a user edit landing between the read (`resolveNote`) and this write is
+    // silently clobbered — the static-write/stale-read class of vault#208.
+    //
+    // We inject a store wrapper that fires a concurrent USER edit immediately
+    // before the route's first OC `updateNote` runs, making its precondition
+    // stale. The route must NOT clobber the user's edit; it must re-read and
+    // re-apply the metadata-only re-stamp against fresh content.
+
+    /**
+     * Wrap a store so the first `N` `updateNote` calls carrying an
+     * `if_updated_at` precondition fire `userEdit()` (a concurrent user write
+     * that bumps `updated_at`) just before delegating — forcing the precondition
+     * stale exactly `interfereTimes` times. Non-OC writes pass through.
+     *
+     * NOTE: duplicated in src/transcription-worker.test.ts (worker-layer race
+     * tests) — keep in sync.
+     */
+    function withRace(
+      base: Store,
+      interfereTimes: number,
+      userEdit: () => Promise<void>,
+    ): Store {
+      let fired = 0;
+      return new Proxy(base, {
+        get(target, prop, receiver) {
+          if (prop === "updateNote") {
+            return async (id: string, updates: any) => {
+              if (updates?.if_updated_at !== undefined && fired < interfereTimes) {
+                fired++;
+                // bun:sqlite stamps `updated_at` at ms granularity. Sleep so
+                // the concurrent user write lands at a strictly-greater
+                // timestamp than the precondition the route captured — making
+                // the conflict deterministic rather than racing inside the
+                // same millisecond.
+                await new Promise((r) => setTimeout(r, 5));
+                await userEdit();
+              }
+              return (target as any).updateNote(id, updates);
+            };
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }) as Store;
+    }
+
+    test("OC: single race → user edit survives, stub still re-armed (no clobber)", async () => {
+      const { noteId, attachmentId } = await seedLegacyFailedMemo({ noteId: "race-1" });
+
+      // One interference: the very first OC write conflicts; the route re-reads
+      // and re-applies against the user's new content.
+      const raceStore = withRace(store, 1, async () => {
+        // User appends a line to the body while the retry is in flight.
+        await store.updateNote(noteId, { append: "\n\nMY EDIT WHILE PENDING" });
+      });
+
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${noteId}/retry-transcription`),
+        raceStore,
+        `/${noteId}/retry-transcription`,
+        "default",
+      );
+      // (a) User edit NOT clobbered + (c) re-stamp succeeded on retry → 202.
+      expect(res.status).toBe(202);
+
+      const after = await store.getNote(noteId);
+      // (a) The user's concurrent edit survives.
+      expect(after!.content).toContain("MY EDIT WHILE PENDING");
+      // Original capture body also intact (re-stamp is metadata-only).
+      expect(after!.content).toContain("_Transcription unavailable._");
+      // (c) Stub re-armed despite the race.
+      expect((after!.metadata as any)?.transcribe_stub).toBe(true);
+
+      const att = await store.getAttachment(attachmentId);
+      expect(att?.metadata?.transcribe_status).toBe("pending");
+      expect(att?.metadata?.transcribe_origin).toBe("legacy");
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("OC: double race → 409 (user-facing request can retry)", async () => {
+      const { noteId } = await seedLegacyFailedMemo({ noteId: "race-2" });
+
+      // Interfere on BOTH the first write and the retry write → the route
+      // exhausts its single retry and surfaces 409.
+      const raceStore = withRace(store, 2, async () => {
+        await store.updateNote(noteId, { append: " x" });
+      });
+
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${noteId}/retry-transcription`),
+        raceStore,
+        `/${noteId}/retry-transcription`,
+        "default",
+      );
+      // (c) Double-conflict policy for a user-facing endpoint: 409.
+      expect(res.status).toBe(409);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("conflict");
+      expect(body.note_id).toBe(noteId);
+
+      // The note was never clobbered — the user's two appends are both present.
+      const after = await store.getNote(noteId);
+      expect(after!.content).toContain(" x x");
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("OC: happy path unchanged when no race occurs", async () => {
+      // With zero interference the OC write lands first-try, byte-identical to
+      // the pre-#435 behavior — guards against the precondition breaking the
+      // common path.
+      const { noteId } = await seedLegacyFailedMemo({ noteId: "race-0" });
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${noteId}/retry-transcription`),
+        store,
+        `/${noteId}/retry-transcription`,
+        "default",
+      );
+      expect(res.status).toBe(202);
+      const after = await store.getNote(noteId);
+      expect((after!.metadata as any)?.transcribe_stub).toBe(true);
+      delete process.env.ASSETS_DIR;
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// REST tag-scope confidentiality (security review). expand_links must not
+// inline out-of-scope wikilinked content; include_links must not hydrate
+// out-of-scope neighbor summaries; unresolved-wikilinks must not surface
+// out-of-scope source rows. Unscoped path stays fully functional. Each
+// security assertion MUST fail without the fix.
+// ---------------------------------------------------------------------------
+describe("HTTP tag-scope confidentiality (security review)", async () => {
+  // Build a TagScopeCtx the same way routing.ts does, so handlers see the
+  // exact shape a real tag-scoped request produces.
+  async function scopeCtx(roots: string[]): Promise<TagScopeCtx> {
+    return { allowed: await expandTokenTagScope(store, roots), raw: roots };
+  }
+  const NO_SCOPE: TagScopeCtx = { allowed: null, raw: null };
+
+  test("expand_links does NOT inline out-of-scope wikilinked content", async () => {
+    await store.createNote("SECRET PERSONAL BODY", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("intro [[Secret]]", { path: "Work", tags: ["work"] });
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?id=${work.id}&include_content=true&expand_links=true`),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    const body = await res.json() as any;
+    expect(body.content).not.toContain("SECRET PERSONAL BODY");
+    expect(body.content).toContain("[[Secret]]"); // literal — like not-found
+  });
+
+  test("UNSCOPED expand_links still inlines content (regression)", async () => {
+    await store.createNote("PERSONAL BODY", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("intro [[Secret]]", { path: "Work", tags: ["work"] });
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?id=${work.id}&include_content=true&expand_links=true`),
+      store,
+      "",
+      "v",
+      NO_SCOPE,
+    );
+    const body = await res.json() as any;
+    expect(body.content).toContain("PERSONAL BODY");
+  });
+
+  test("expand_links multi-hop (depth>1) does not leak out-of-scope content", async () => {
+    await store.createNote("DEEP PERSONAL SECRET", { path: "Deep", tags: ["personal"] });
+    await store.createNote("mid [[Deep]]", { path: "Mid", tags: ["work"] });
+    const top = await store.createNote("top [[Mid]]", { path: "Top", tags: ["work"] });
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?id=${top.id}&include_content=true&expand_links=true&expand_depth=3`),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    const body = await res.json() as any;
+    expect(body.content).toContain("mid");
+    expect(body.content).not.toContain("DEEP PERSONAL SECRET");
+  });
+
+  test("include_links strips out-of-scope NEIGHBOR summaries", async () => {
+    const secret = await store.createNote("secret", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("work", { path: "Work", tags: ["work"] });
+    await store.createLink(work.id, secret.id, "references");
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?id=${work.id}&include_links=true`),
+      store,
+      "",
+      "v",
+      await scopeCtx(["work"]),
+    );
+    const body = await res.json() as any;
+    const serialized = JSON.stringify(body.links ?? []);
+    expect(serialized).not.toContain(secret.id);
+    expect(serialized).not.toContain("Secret");
+  });
+
+  test("UNSCOPED include_links hydrates the full neighbor (regression)", async () => {
+    const secret = await store.createNote("secret", { path: "Secret", tags: ["personal"] });
+    const work = await store.createNote("work", { path: "Work", tags: ["work"] });
+    await store.createLink(work.id, secret.id, "references");
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?id=${work.id}&include_links=true`),
+      store,
+      "",
+      "v",
+      NO_SCOPE,
+    );
+    const body = await res.json() as any;
+    expect((body.links ?? []).length).toBe(1);
+    expect(JSON.stringify(body.links)).toContain(secret.id);
+  });
+
+  test("unresolved-wikilinks surfaces only in-scope source rows", async () => {
+    // #personal source with a dangling wikilink → out-of-scope row.
+    await store.createNote("p [[NoSuchPersonal]]", { path: "P", tags: ["personal"] });
+    // #work source with a dangling wikilink → in-scope row.
+    await store.createNote("w [[NoSuchWork]]", { path: "W", tags: ["work"] });
+
+    const res = handleUnresolvedWikilinks(
+      mkReq("GET", "/unresolved-wikilinks"),
+      store,
+      await scopeCtx(["work"]),
+    );
+    const body = await res.json() as any;
+    const targets = (body.unresolved as any[]).map((r) => r.target_path);
+    expect(targets).toContain("NoSuchWork");
+    expect(targets).not.toContain("NoSuchPersonal");
+    expect(body.count).toBe(1);
+  });
+
+  test("UNSCOPED unresolved-wikilinks surfaces every row (regression)", async () => {
+    await store.createNote("p [[NoSuchPersonal]]", { path: "P", tags: ["personal"] });
+    await store.createNote("w [[NoSuchWork]]", { path: "W", tags: ["work"] });
+
+    const res = handleUnresolvedWikilinks(
+      mkReq("GET", "/unresolved-wikilinks"),
+      store,
+      NO_SCOPE,
+    );
+    const body = await res.json() as any;
+    const targets = (body.unresolved as any[]).map((r) => r.target_path);
+    expect(targets).toContain("NoSuchWork");
+    expect(targets).toContain("NoSuchPersonal");
+  });
+
+});
+
+describe("HTTP /notes include_link_count + order_by=link_count (vault feedback #4)", async () => {
+  // Mirrors the MCP-surface tests in core/src/link-count.test.ts on the
+  // same fixtures so REST and MCP agree on the degree semantics.
+  async function seed() {
+    await store.createNote("Hub", { id: "hub", path: "hub", tags: ["t"] });
+    await store.createNote("Leaf", { id: "leaf", path: "leaf", tags: ["t"] });
+    await store.createNote("Self", { id: "self", path: "self", tags: ["t"] });
+    await store.createLink("hub", "leaf", "a"); // hub out 1, leaf in 1
+    await store.createLink("leaf", "hub", "b"); // hub in 1, leaf out 1 => both degree 2
+    await store.createLink("self", "self", "loop"); // self-loop => degree 2
+  }
+
+  test("list mode: include_link_count injects linkCount (both directions)", async () => {
+    await seed();
+    const res = await handleNotes(mkReq("GET", "/notes?include_link_count=true"), store, "");
+    const body = (await res.json()) as any[];
+    const byId = Object.fromEntries(body.map((n) => [n.id, n]));
+    expect(byId.hub.linkCount).toBe(2);
+    expect(byId.leaf.linkCount).toBe(2);
+    expect(byId.self.linkCount).toBe(2); // self-loop = 2
+  });
+
+  test("absent flag → no linkCount key (no behavior change)", async () => {
+    await seed();
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = (await res.json()) as any[];
+    expect(body.every((n) => !("linkCount" in n))).toBe(true);
+  });
+
+  test("note with 0 links → linkCount: 0", async () => {
+    await store.createNote("Lonely", { id: "lonely", path: "lonely" });
+    const res = await handleNotes(mkReq("GET", "/notes?include_link_count=true"), store, "");
+    const body = (await res.json()) as any[];
+    expect(body.find((n) => n.id === "lonely").linkCount).toBe(0);
+  });
+
+  test("single-note (?id=) mode: include_link_count → correct degree", async () => {
+    await seed();
+    const res = await handleNotes(mkReq("GET", "/notes?id=self&include_link_count=true"), store, "");
+    const body = (await res.json()) as any;
+    expect(body.linkCount).toBe(2);
+  });
+
+  test("single-note (/notes/:id) mode: include_link_count → correct degree", async () => {
+    await seed();
+    const res = await handleNotes(mkReq("GET", "/notes/self?include_link_count=true"), store, "/self");
+    const body = (await res.json()) as any;
+    expect(body.linkCount).toBe(2);
+  });
+
+  test("link_count_direction outbound / inbound variants", async () => {
+    await seed();
+    const out = await handleNotes(
+      mkReq("GET", "/notes?id=hub&include_link_count=true&link_count_direction=outbound"),
+      store,
+      "",
+    );
+    expect(((await out.json()) as any).linkCount).toBe(1); // hub→leaf
+    const inb = await handleNotes(
+      mkReq("GET", "/notes?id=hub&include_link_count=true&link_count_direction=inbound"),
+      store,
+      "",
+    );
+    expect(((await inb.json()) as any).linkCount).toBe(1); // leaf→hub
+  });
+
+  test("unrecognized link_count_direction falls back to both (REST parseLinkCountDirection)", async () => {
+    await seed();
+    // hub: both=2, outbound=1, inbound=1. A bogus value must degrade to
+    // `both` (2), distinct from either directional value (1).
+    const res = await handleNotes(
+      mkReq("GET", "/notes?id=hub&include_link_count=true&link_count_direction=sideways"),
+      store,
+      "",
+    );
+    expect(((await res.json()) as any).linkCount).toBe(2);
+  });
+
+  test("FTS branch: search + include_link_count → results carry linkCount", async () => {
+    // The full-text-search branch is a separate return path from the
+    // structured query; exercise the flag there explicitly.
+    await store.createNote("quokka sighting near the hub", { id: "fts-hub", path: "fts-hub" });
+    await store.createNote("a quokka friend", { id: "fts-friend", path: "fts-friend" });
+    await store.createLink("fts-hub", "fts-friend", "a"); // hub out1, friend in1
+    await store.createLink("fts-friend", "fts-hub", "b"); // hub in1 => hub degree 2
+    const res = await handleNotes(
+      mkReq("GET", "/notes?search=quokka&include_link_count=true"),
+      store,
+      "",
+    );
+    const body = (await res.json()) as any[];
+    const byId = Object.fromEntries(body.map((n) => [n.id, n]));
+    expect(byId["fts-hub"].linkCount).toBe(2);
+    expect(byId["fts-friend"].linkCount).toBe(2);
+  });
+
+  test("FTS branch: absent flag → no linkCount key", async () => {
+    await store.createNote("quokka sighting near the hub", { id: "fts-hub", path: "fts-hub" });
+    await store.createLink("fts-hub", "fts-hub", "loop");
+    const res = await handleNotes(mkReq("GET", "/notes?search=quokka"), store, "");
+    const body = (await res.json()) as any[];
+    expect(body.every((n) => !("linkCount" in n))).toBe(true);
+  });
+
+  test("order_by=link_count desc: field value == sort key for every note", async () => {
+    // Distinct degrees so the ordering is unambiguous: big=3, mid=2, small=0.
+    await store.createNote("Big", { id: "big", path: "big" });
+    await store.createNote("Mid", { id: "mid", path: "mid" });
+    await store.createNote("Small", { id: "small", path: "small" });
+    await store.createLink("big", "mid", "a"); // big out1, mid in1
+    await store.createLink("big", "small", "b"); // big out2, small in1
+    await store.createLink("mid", "big", "c"); // big in1 => big degree 3; mid out1 => mid degree 2
+    // small degree 1 (in from big). Adjust: make small degree 0 by removing
+    // — instead assert monotonic + field==sortkey, which is the real invariant.
+
+    const res = await handleNotes(
+      mkReq("GET", "/notes?order_by=link_count&sort=desc&include_link_count=true"),
+      store,
+      "",
+    );
+    const body = (await res.json()) as any[];
+    const seq = body.map((n) => n.linkCount as number);
+    // The injected field equals the sort key, so the sequence is non-increasing.
+    expect(seq).toEqual([...seq].sort((a, b) => b - a));
+    expect(body[0].id).toBe("big"); // degree 3 — the most-connected note
+    expect(body[0].linkCount).toBe(3);
+  });
+
+  test("order_by=link_count: self-loop note ranks by its degree-2 field value", async () => {
+    await store.createNote("Selfy", { id: "selfy", path: "selfy" });
+    await store.createNote("Plain", { id: "plain", path: "plain" });
+    await store.createNote("Zero", { id: "zero", path: "zero" });
+    await store.createLink("selfy", "selfy", "loop"); // degree 2
+    await store.createLink("zero", "plain", "ref"); // plain in1, zero out1
+
+    const res = await handleNotes(
+      mkReq("GET", "/notes?order_by=link_count&sort=desc&include_link_count=true"),
+      store,
+      "",
+    );
+    const body = (await res.json()) as any[];
+    expect(body[0].id).toBe("selfy"); // degree 2 outranks the degree-1 notes
+    expect(body[0].linkCount).toBe(2); // field == the sort key that put it first
+    const byId = Object.fromEntries(body.map((n) => [n.id, n]));
+    expect(byId.plain.linkCount).toBe(1);
+    expect(byId.zero.linkCount).toBe(1);
   });
 });
 
@@ -3026,6 +3936,78 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(0);
   });
 
+  // vault feedback #8 — the update response now echoes hydrated links when
+  // the request mutated links OR `?include_links=true` is passed, so callers
+  // no longer have to re-GET to confirm a link they just added/removed.
+  test("PATCH links.add echoes hydrated links on the response", async () => {
+    await store.createNote("a", { id: "a" });
+    await store.createNote("b", { id: "b", path: "People/Bob", tags: ["person"] });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/a", { links: { add: [{ target: "b", relationship: "mentions" }] }, force: true }),
+      store,
+      "/a",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(Array.isArray(body.links)).toBe(true);
+    expect(body.links).toHaveLength(1);
+    const link = body.links[0];
+    expect(link.sourceId).toBe("a");
+    expect(link.targetId).toBe("b");
+    expect(link.relationship).toBe("mentions");
+    // Hydrated shape matches GET / query-notes: targetNote summary present.
+    expect(link.targetNote.id).toBe("b");
+    expect(link.targetNote.path).toBe("People/Bob");
+    expect(link.targetNote.tags).toEqual(["person"]);
+  });
+
+  test("PATCH links.remove echoes the post-removal link set", async () => {
+    await store.createNote("a", { id: "a" });
+    await store.createNote("b", { id: "b" });
+    await store.createNote("c", { id: "c" });
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("a", "c", "mentions");
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/a", { links: { remove: [{ target: "b", relationship: "mentions" }] }, force: true }),
+      store,
+      "/a",
+    );
+    const body = await res.json() as any;
+    expect(Array.isArray(body.links)).toBe(true);
+    expect(body.links).toHaveLength(1);
+    expect(body.links[0].targetId).toBe("c");
+  });
+
+  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" });
+    await store.createLink("a", "b", "mentions");
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/a", { content: "updated", force: true }),
+      store,
+      "/a",
+    );
+    const body = await res.json() as any;
+    expect(body.content).toBe("updated");
+    expect(body).not.toHaveProperty("links");
+  });
+
+  test("PATCH ?include_links=true echoes current links even without a mutation", async () => {
+    await store.createNote("a", { id: "a" });
+    await store.createNote("b", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/a?include_links=true", { content: "updated", force: true }),
+      store,
+      "/a",
+    );
+    const body = await res.json() as any;
+    expect(body.content).toBe("updated");
+    expect(Array.isArray(body.links)).toBe(true);
+    expect(body.links).toHaveLength(1);
+    expect(body.links[0].targetId).toBe("b");
+  });
+
   test("PATCH resolves note by path", async () => {
     await store.createNote("x", { path: "Projects/README" });
     const res = await handleNotes(
@@ -3702,11 +4684,86 @@ describe("HTTP /tags", async () => {
     expect(buildVaultProjection(db).indexed_fields.map((f) => f.name)).toContain("aspect_ratio");
   });
 
-  test("PUT /tags/:name returns 400 with error_type: invalid_relationships on bad shape", async () => {
+  // ---- relationships is an opaque vocabulary map (vault#428) ----
+  // PUT persists the value verbatim with no inner-shape enforcement; GET
+  // returns it byte-for-byte. Only a top-level non-map (array/primitive)
+  // or non-serializable input is rejected with invalid_relationships.
+
+  test("PUT /tags/:name persists the opaque vocabulary map; GET returns it verbatim (vault#428)", async () => {
+    const vocab = {
+      "works-on": { from: "person", to: "project" },
+      "member-of": { from: "person", to: "organization" },
+      "partner-of": { from: "person", to: "person" },
+      "based-at": { from: "project", to: "place" },
+    };
+    const put = await handleTags(
+      mkReq("PUT", "/tags/person", { relationships: vocab }),
+      store,
+      "/person",
+    );
+    expect(put.status).toBe(200);
+
+    const get = await handleTags(mkReq("GET", "/tags/person"), store, "/person");
+    expect(get.status).toBe(200);
+    const body = await get.json() as any;
+    // Byte-for-byte: serialize both sides and compare exactly.
+    expect(JSON.stringify(body.relationships)).toBe(JSON.stringify(vocab));
+    expect(body.relationships).toEqual(vocab);
+  });
+
+  test("PUT /tags/:name still accepts the historical typed relationships shape (backwards-compat)", async () => {
+    const typed = { owned_by: { target_tag: "person", cardinality: "one", description: "DRI" } };
+    const put = await handleTags(
+      mkReq("PUT", "/tags/project", { relationships: typed }),
+      store,
+      "/project",
+    );
+    expect(put.status).toBe(200);
+    const get = await handleTags(mkReq("GET", "/tags/project"), store, "/project");
+    const body = await get.json() as any;
+    expect(body.relationships).toEqual(typed);
+  });
+
+  test("PUT /tags/:name round-trips nested arbitrary relationship values verbatim", async () => {
+    const vocab = { rel: { from: "a", to: "b", note: "freeform", weight: 3, tags: ["x", "y"] } };
+    const put = await handleTags(
+      mkReq("PUT", "/tags/thing", { relationships: vocab }),
+      store,
+      "/thing",
+    );
+    expect(put.status).toBe(200);
+    const get = await handleTags(mkReq("GET", "/tags/thing"), store, "/thing");
+    const body = await get.json() as any;
+    expect(body.relationships).toEqual(vocab);
+  });
+
+  test("PUT /tags/:name returns 400 invalid_relationships for a top-level array", async () => {
     const res = await handleTags(
-      mkReq("PUT", "/tags/person", {
-        relationships: { mentions: { target_tag: "topic", cardinality: "infinite" } },
-      }),
+      mkReq("PUT", "/tags/person", { relationships: ["not", "a", "map"] }),
+      store,
+      "/person",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("invalid_relationships");
+    expect(typeof body.error).toBe("string");
+    expect(body.error.length).toBeGreaterThan(0);
+  });
+
+  test("PUT /tags/:name returns 400 invalid_relationships for a top-level primitive", async () => {
+    const res = await handleTags(
+      mkReq("PUT", "/tags/person", { relationships: "just-a-string" as unknown as Record<string, unknown> }),
+      store,
+      "/person",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("invalid_relationships");
+  });
+
+  test("PUT /tags/:name returns 400 invalid_relationships for an empty relationship key", async () => {
+    const res = await handleTags(
+      mkReq("PUT", "/tags/person", { relationships: { "": { from: "a", to: "b" } } }),
       store,
       "/person",
     );