@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/core/src/content-range.ts

@@ -0,0 +1,185 @@
+/**
+ * Content range / pagination — bounded reads for large notes.
+ *
+ * MCP responses are size-limited: a 100KB+ transcript can't come back in
+ * one `query-notes` call, and a remote MCP client has no `curl | head -c`
+ * escape hatch. These helpers let a caller read note content in byte
+ * windows:
+ *
+ *   request:  `content_offset` (default 0) + `content_length` (byte budget)
+ *   response: `content` (the slice) + `content_offset` (effective start)
+ *             + `content_total_length` + `content_next_offset`
+ *             (`null` when the slice reaches the end)
+ *
+ * Unit is **UTF-8 bytes** — the same unit as `byteSize` on the lean
+ * NoteIndex shape, and the natural unit for budgeting response size. But
+ * naive byte-slicing can split a multi-byte codepoint, which would corrupt
+ * the JSON string. So slices always end on a codepoint boundary *within*
+ * the budget: a slice never exceeds `content_length` bytes but may come up
+ * to 3 bytes short when a multi-byte character straddles the cut. A
+ * `content_offset` that lands mid-codepoint (only possible when the caller
+ * computes offsets by hand — chained `content_next_offset` values are
+ * always boundary-aligned) is aligned DOWN to the codepoint's leading byte
+ * so no bytes are ever skipped; the effective start is echoed back as
+ * `content_offset` on the response.
+ *
+ * Reassembly invariant (pinned by content-range.test.ts): starting at
+ * offset 0 and following `content_next_offset` until `null`, the
+ * concatenation of slices is byte-identical to the full content.
+ */
+
+import { QueryError } from "./query-operators.js";
+
+/**
+ * Minimum accepted `content_length`. A UTF-8 codepoint is at most 4 bytes,
+ * so any budget >= 4 is guaranteed to make progress (the codepoint at the
+ * window start always fits). Budgets 1–3 could stall forever on a 4-byte
+ * emoji (empty slice, next_offset == offset); rejecting them up front is
+ * deterministic and simpler than a runtime "no progress" error.
+ */
+export const MIN_CONTENT_LENGTH = 4;
+
+export interface ContentRange {
+  /** Byte offset (UTF-8) to start reading from. */
+  offset: number;
+  /** Max bytes to return. Absent = read to the end. */
+  length?: number;
+}
+
+export interface ContentRangeFields {
+  content: string;
+  /** Effective start (requested offset aligned down to a codepoint boundary). */
+  content_offset: number;
+  /** Full content size in UTF-8 bytes. */
+  content_total_length: number;
+  /** Byte offset to resume from, or null when the slice reaches the end. */
+  content_next_offset: number | null;
+}
+
+function toNonNegativeInt(raw: unknown, name: string): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  let n: number;
+  if (typeof raw === "number") {
+    n = raw;
+  } else if (typeof raw === "string") {
+    if (raw.trim() === "") return undefined; // `?content_offset=` — treat empty as absent
+    if (!/^\d+$/.test(raw.trim())) {
+      throw new QueryError(
+        `invalid \`${name}\` value ${JSON.stringify(raw)} — must be a non-negative integer (UTF-8 byte count).`,
+        "INVALID_QUERY",
+      );
+    }
+    n = Number(raw.trim());
+  } else {
+    throw new QueryError(
+      `invalid \`${name}\` value — must be a non-negative integer (UTF-8 byte count).`,
+      "INVALID_QUERY",
+    );
+  }
+  if (!Number.isSafeInteger(n) || n < 0) {
+    throw new QueryError(
+      `invalid \`${name}\` value ${JSON.stringify(raw)} — must be a non-negative integer (UTF-8 byte count).`,
+      "INVALID_QUERY",
+    );
+  }
+  return n;
+}
+
+/**
+ * Parse the `content_offset` / `content_length` pair. Returns `null` when
+ * neither is present (range mode off — response shape byte-identical to
+ * the no-pagination behavior). Throws `QueryError` (INVALID_QUERY) on
+ * negative / non-integer values or a `content_length` below
+ * {@link MIN_CONTENT_LENGTH}.
+ *
+ * Accepts numbers (MCP params) and decimal strings (REST query params);
+ * empty strings count as absent.
+ */
+export function parseContentRange(offsetRaw: unknown, lengthRaw: unknown): ContentRange | null {
+  const offset = toNonNegativeInt(offsetRaw, "content_offset");
+  const length = toNonNegativeInt(lengthRaw, "content_length");
+  if (offset === undefined && length === undefined) return null;
+  if (length !== undefined && length < MIN_CONTENT_LENGTH) {
+    throw new QueryError(
+      `invalid \`content_length\` value ${JSON.stringify(lengthRaw)} — must be at least ${MIN_CONTENT_LENGTH} bytes (the size of the largest UTF-8 codepoint, so every window makes progress).`,
+      "INVALID_QUERY",
+    );
+  }
+  return { offset: offset ?? 0, ...(length !== undefined ? { length } : {}) };
+}
+
+/**
+ * The error both faces raise when range params are combined with a
+ * response shape that excludes content (`include_content=false`, or a
+ * list query left on its lean default). Centralized so MCP and REST emit
+ * the same message.
+ */
+export function contentRangeRequiresContent(): QueryError {
+  return new QueryError(
+    `content_offset/content_length apply to note content, but content is not included in this response shape. Pass include_content=true (lists default to false) or drop the range params.`,
+    "INVALID_QUERY",
+  );
+}
+
+/** True for UTF-8 continuation bytes (0b10xxxxxx). */
+function isContinuationByte(b: number): boolean {
+  return (b & 0xc0) === 0x80;
+}
+
+/**
+ * Slice `content` to the requested byte window, never splitting a UTF-8
+ * codepoint and never exceeding `range.length` bytes. See module doc for
+ * the alignment rules.
+ */
+export function sliceContentRange(content: string, range: ContentRange): ContentRangeFields {
+  const bytes = Buffer.from(content, "utf8");
+  const total = bytes.byteLength;
+
+  // At/past the end: empty slice, complete. Graceful (not an error) so a
+  // pagination loop that overshoots — e.g. the note shrank between calls —
+  // terminates cleanly on `content_next_offset: null`.
+  if (range.offset >= total) {
+    return {
+      content: "",
+      content_offset: total,
+      content_total_length: total,
+      content_next_offset: null,
+    };
+  }
+
+  // Align the start DOWN to the leading byte of the codepoint containing
+  // `offset` — never skip bytes (a forward-align would drop them from
+  // every window and break reassembly).
+  let start = range.offset;
+  while (start > 0 && isContinuationByte(bytes[start]!)) start--;
+
+  // Window end: budget capped at total. Align DOWN so the slice doesn't
+  // end mid-codepoint — under the budget, never over.
+  let end = range.length === undefined ? total : Math.min(start + range.length, total);
+  while (end > start && end < total && isContinuationByte(bytes[end]!)) end--;
+
+  return {
+    content: bytes.subarray(start, end).toString("utf8"),
+    content_offset: start,
+    content_total_length: total,
+    content_next_offset: end >= total ? null : end,
+  };
+}
+
+/**
+ * Apply a content range to a shaped response object in place: replaces
+ * `content` with the slice and adds `content_offset`,
+ * `content_total_length`, `content_next_offset`. No-op fields are never
+ * added when range mode is off — callers only invoke this with a parsed
+ * (non-null) range.
+ */
+export function applyContentRange(
+  result: { content?: unknown; [key: string]: unknown },
+  range: ContentRange,
+): void {
+  const fields = sliceContentRange(typeof result.content === "string" ? result.content : "", range);
+  result.content = fields.content;
+  result.content_offset = fields.content_offset;
+  result.content_total_length = fields.content_total_length;
+  result.content_next_offset = fields.content_next_offset;
+}

package/core/src/core.test.ts

@@ -4,6 +4,7 @@ import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { initSchema } from "./schema.js";
 import { decodeCursor } from "./cursor.js";
+import { traverseLinks } from "./links.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -972,6 +973,33 @@ describe("vault stats", async () => {
     expect(stats.topTags).toEqual([]);
     expect(stats.tagCount).toBe(0);
     expect(stats.linkCount).toBe(0);
+    expect(stats.contentBytes).toBe(0);
+  });
+
+  it("contentBytes sums ASCII content as raw byte length", async () => {
+    // "hello" = 5 bytes, "world!" = 6 bytes — for pure ASCII, bytes == chars.
+    await store.createNote("hello");
+    await store.createNote("world!");
+    const stats = await store.getVaultStats();
+    expect(stats.contentBytes).toBe(11);
+  });
+
+  it("contentBytes counts UTF-8 BYTES, not characters (multibyte)", async () => {
+    // The whole point of CAST(content AS BLOB): SQLite's bare LENGTH() would
+    // return the CHARACTER count, undercounting multibyte content.
+    //   - "é"  is U+00E9 → 2 bytes in UTF-8 (1 char)
+    //   - "你好" is 2 CJK chars → 6 bytes (3 bytes each)
+    //   - "😀" is 1 grapheme / 2 UTF-16 code units → 4 bytes in UTF-8
+    const content = "é你好😀";
+    const expectedBytes = Buffer.byteLength(content, "utf8"); // 2 + 6 + 4 = 12
+    expect(expectedBytes).toBe(12);
+    // And it's strictly MORE than the JS character count — proves we're not
+    // accidentally counting chars.
+    expect(expectedBytes).toBeGreaterThan([...content].length);
+
+    await store.createNote(content);
+    const stats = await store.getVaultStats();
+    expect(stats.contentBytes).toBe(expectedBytes);
   });
 
   it("counts total notes and tagCount", async () => {
@@ -1041,6 +1069,7 @@ describe("vault stats", async () => {
     expect(stats).toHaveProperty("topTags");
     expect(stats).toHaveProperty("tagCount");
     expect(stats).toHaveProperty("linkCount");
+    expect(stats).toHaveProperty("contentBytes");
   });
 
   it("counts resolved wikilinks in linkCount", async () => {
@@ -1866,6 +1895,59 @@ describe("links", async () => {
     const links = await store.getLinks("a");
     expect(links.filter((l) => l.relationship === "mentions")).toHaveLength(1);
   });
+
+  // vault#439 — traverseLinks isTraversable predicate (wall, not sieve).
+  // Topology: a -> b(blocked) -> c. A predicate that blocks `b` must make
+  // `c` unreachable (the BFS can't walk THROUGH b), not merely filtered out.
+  it("traverseLinks: isTraversable predicate is a wall (can't reach past a blocked hop)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "c", "relates");
+
+    const blocked = traverseLinks(db, "a", {
+      max_depth: 5,
+      isTraversable: (id) => id !== "b",
+    });
+    const ids = blocked.map((t) => t.noteId);
+    expect(ids).not.toContain("b"); // blocked hop is excluded from results
+    expect(ids).not.toContain("c"); // and unreachable beyond it
+  });
+
+  it("traverseLinks: no predicate walks the full graph (unchanged)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "c", "relates");
+
+    const all = traverseLinks(db, "a", { max_depth: 5 });
+    const ids = all.map((t) => t.noteId);
+    expect(ids).toContain("b");
+    expect(ids).toContain("c");
+  });
+
+  it("traverseLinks: an allowed alternate path still reaches the far node", async () => {
+    // a -> b(blocked) -> d ; a -> c(allowed) -> d. d reachable via c.
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createNote("D", { id: "d" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "d", "relates");
+    await store.createLink("a", "c", "relates");
+    await store.createLink("c", "d", "relates");
+
+    const res = traverseLinks(db, "a", {
+      max_depth: 5,
+      isTraversable: (id) => id !== "b",
+    });
+    const ids = res.map((t) => t.noteId);
+    expect(ids).not.toContain("b");
+    expect(ids).toContain("c");
+    expect(ids).toContain("d"); // reachable via the allowed c-path
+  });
 });
 
 // ---- Attachments ----
@@ -1985,6 +2067,41 @@ describe("MCP tools", async () => {
     expect(result[1].tags).toContain("doc");
   });
 
+  // vault#316 — the create-note tool re-reads each note AFTER
+  // `applySchemaDefaults` runs, so the response reflects the post-defaults
+  // on-disk state (matching the update-note path). Before the fix the
+  // response mapped over the pre-defaults in-memory objects, so a
+  // schema-default-filled field was missing from the returned note even
+  // though it had just been written to disk.
+  it("create-note response reflects post-applySchemaDefaults state (vault#316)", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+
+    // Single: default lands in the returned metadata.
+    const single = await createNote.execute({
+      content: "do the thing",
+      path: "Inbox/task-1",
+      tags: ["task"],
+    }) as any;
+    expect(single.metadata?.priority).toBe("high"); // first enum value
+    // Disk and response agree.
+    const onDisk = await store.getNoteByPath("Inbox/task-1");
+    expect((onDisk!.metadata as any)?.priority).toBe("high");
+
+    // Batch: each entry is re-read post-defaults too.
+    const batch = await createNote.execute({
+      notes: [
+        { content: "a", path: "Inbox/task-2", tags: ["task"] },
+        { content: "b", path: "Inbox/task-3", tags: ["task"] },
+      ],
+    }) as any[];
+    expect(batch[0].metadata?.priority).toBe("high");
+    expect(batch[1].metadata?.priority).toBe("high");
+  });
+
   it("create-note accepts extension field (vault#328)", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -2131,6 +2248,113 @@ describe("MCP tools", async () => {
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(0);
   });
 
+  // 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 () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b", path: "beta", tags: ["t"] });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      links: { add: [{ target: "b", relationship: "mentions" }] },
+      force: true,
+    }) as any;
+    expect(Array.isArray(result.links)).toBe(true);
+    expect(result.links).toHaveLength(1);
+    // Hydrated shape matches query-notes' include_links output.
+    const link = result.links[0];
+    expect(link.sourceId).toBe("a");
+    expect(link.targetId).toBe("b");
+    expect(link.relationship).toBe("mentions");
+    expect(link.targetNote.path).toBe("beta");
+    expect(link.targetNote.tags).toEqual(["t"]);
+  });
+
+  it("update-note echoes links on removal (post-removal 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 tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      links: { remove: [{ target: "b", relationship: "mentions" }] },
+      force: true,
+    }) as any;
+    expect(result.links).toHaveLength(1);
+    expect(result.links[0].targetId).toBe("c");
+  });
+
+  it("update-note with include_links echoes 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 tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      content: "updated",
+      include_links: true,
+      force: true,
+    }) as any;
+    expect(result.content).toBe("updated");
+    expect(result.links).toHaveLength(1);
+    expect(result.links[0].targetId).toBe("b");
+  });
+
+  it("update-note without a link mutation or flag does NOT echo links", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({ id: "a", content: "updated", force: true }) as any;
+    expect(result.content).toBe("updated");
+    expect(result).not.toHaveProperty("links");
+  });
+
+  it("update-note batch echoes links per-item (only on the mutated/flagged item)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      notes: [
+        // Item 0 mutates links → echoes.
+        { id: "a", links: { add: [{ target: "b", relationship: "mentions" }] }, force: true },
+        // Item 1 only edits content, no flag → no links key.
+        { id: "c", content: "C updated", force: true },
+      ],
+    }) as any[];
+    expect(result).toHaveLength(2);
+    expect(result[0].links).toHaveLength(1);
+    expect(result[0].links[0].targetId).toBe("b");
+    expect(result[1]).not.toHaveProperty("links");
+  });
+
+  it("update-note if_missing=create with include_links echoes links (no link mutation)", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    // The created note has no links yet and the payload declares none, so the
+    // echo is driven purely by the explicit `include_links` flag — closing the
+    // create-on-missing × flag-only matrix gap. Hydrated `links` key is present
+    // (empty array), not absent.
+    const result = await updateNote.execute({
+      id: "fresh-note",
+      content: "brand new",
+      if_missing: "create",
+      include_links: true,
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.content).toBe("brand new");
+    expect(Array.isArray(result.links)).toBe(true);
+    expect(result.links).toHaveLength(0);
+  });
+
   it("update-note removes wikilink brackets when removing wikilink-type link", async () => {
     await store.createNote("Target", { id: "target", path: "People/Alice" });
     const source = await store.createNote("See [[People/Alice]] for details", { id: "source" });
@@ -4932,43 +5156,65 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
     expect(idxZebra).toBeGreaterThan(idxAlpha);
   });
 
-  it("update-tag MCP rejects an invalid cardinality", async () => {
+  // ---- relationships is an opaque vocabulary map (vault#428) ----
+  // Vault no longer enforces the historical { target_tag, cardinality }
+  // shape. Apps (the Weaver / structural-link picker) declare a freeform
+  // vocabulary; vault stores + returns it verbatim. The old typed shape is
+  // still a valid value, so the loosening is a backwards-compatible superset.
+
+  it("update-tag MCP persists the opaque relationship-vocabulary map verbatim (vault#428)", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
-    await expect(
-      update.execute({
-        tag: "project",
-        relationships: {
-          owned_by: { target_tag: "person", cardinality: "bogus" },
-        },
-      }),
-    ).rejects.toThrow(/cardinality/);
+    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" },
+    };
+    await update.execute({ tag: "person", relationships: vocab });
+    const r = await store.getTagRecord("person");
+    expect(r?.relationships).toEqual(vocab);
   });
 
-  it("update-tag MCP accepts every cardinality in the named vocabulary", async () => {
+  it("update-tag MCP round-trips nested arbitrary relationship values verbatim", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
-    for (const card of ["one", "optional", "many", "many-required"]) {
-      await update.execute({
-        tag: `tag-${card}`,
-        relationships: {
-          rel: { target_tag: "other", cardinality: card },
-        },
-      });
-      const r = await store.getTagRecord(`tag-${card}`);
-      expect(r?.relationships?.rel?.cardinality).toBe(card);
-    }
+    const vocab = {
+      rel: { from: "a", to: "b", note: "freeform", weight: 3, optional: true, tags: ["x", "y"] },
+    };
+    await update.execute({ tag: "thing", relationships: vocab });
+    const r = await store.getTagRecord("thing");
+    expect(r?.relationships).toEqual(vocab);
+  });
+
+  it("update-tag MCP still accepts the historical typed shape (backwards-compat)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    const typed = { owned_by: { target_tag: "person", cardinality: "one", description: "DRI" } };
+    await update.execute({ tag: "project", relationships: typed });
+    const r = await store.getTagRecord("project");
+    expect(r?.relationships).toEqual(typed);
+  });
+
+  it("update-tag MCP accepts what used to be rejected (no inner-shape enforcement)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    // Formerly rejected: non-vocabulary cardinality + missing target_tag.
+    const formerlyInvalid = {
+      a: { target_tag: "person", cardinality: "bogus" },
+      b: { cardinality: "one" },
+    };
+    await update.execute({ tag: "loose", relationships: formerlyInvalid });
+    const r = await store.getTagRecord("loose");
+    expect(r?.relationships).toEqual(formerlyInvalid);
   });
 
-  it("update-tag MCP rejects a relationship missing target_tag", async () => {
+  it("update-tag MCP rejects a top-level array for relationships (must be a map)", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
     await expect(
-      update.execute({
-        tag: "project",
-        relationships: { owned_by: { cardinality: "one" } },
-      }),
-    ).rejects.toThrow(/target_tag/);
+      update.execute({ tag: "project", relationships: ["not", "a", "map"] as unknown as Record<string, unknown> }),
+    ).rejects.toThrow();
   });
 
   it("update-tag MCP sets parent_names and the hierarchy invalidates", async () => {
@@ -5609,6 +5855,13 @@ describe("vault projection (vault#271)", async () => {
     expect(md).toContain("#person");
     expect(md).toContain("vault-info");
     expect(md).toContain("list-tags { include_schema: true }");
+    // Scripting pointer (closes the "points nowhere" gap): the brief routes an
+    // agent to the HTTP API + the public guide, with the vault name baked into
+    // the copy-paste mint command.
+    expect(md).toContain("## Scripting & automation (beyond this session)");
+    expect(md).toContain("https://parachute.computer/scripting/");
+    expect(md).toContain("parachute auth mint-token --scope vault:test:read --ephemeral");
+    expect(md).toContain("vault/test/api");
   });
 
   it("markdown brief degrades gracefully when no schemas declared", async () => {

package/core/src/expand-visibility.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import { createNote } from "./notes.js";
+import { expandContent, type ExpandContext } from "./expand.js";
+import type { Note } from "./types.js";
+
+/**
+ * Security regression (vault security review — tag-scope confidentiality).
+ *
+ * `expandContent`'s optional `isVisible` predicate is the seam that keeps
+ * core scope-unaware while letting the server enforce tag scope during
+ * wikilink inlining. These tests pin the load-bearing invariant: when the
+ * predicate rejects a target, the wikilink is left UNRESOLVED — byte-for-byte
+ * identical to a genuinely-missing target, so the response can't reveal that
+ * the out-of-scope note exists. They MUST fail if the predicate is removed.
+ */
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+
+function ctx(over: Partial<ExpandContext> = {}): ExpandContext {
+  return { db, mode: "full", expanded: new Set<string>(), ...over };
+}
+
+describe("expandContent isVisible predicate (tag-scope confidentiality)", () => {
+  it("inlines an in-scope target's content when no predicate is set (baseline)", () => {
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const out = expandContent("see [[Secret]]", ctx(), 1);
+    expect(out).toContain("SECRET BODY");
+  });
+
+  it("leaves an out-of-scope wikilink unresolved — no content inlined", () => {
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    // Predicate: only #work notes are visible. The target is #personal.
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("see [[Secret]]", ctx({ isVisible }), 1);
+    expect(out).not.toContain("SECRET BODY");
+    // The wikilink stays literal.
+    expect(out).toBe("see [[Secret]]");
+  });
+
+  it("out-of-scope target is INDISTINGUISHABLE from a missing target", () => {
+    // Case A: target exists but is out of scope.
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const outOfScope = expandContent("see [[Secret]]", ctx({ isVisible }), 1);
+
+    // Case B: target genuinely does not exist (fresh db, same predicate).
+    const db2 = new Database(":memory:");
+    initSchema(db2);
+    const missing = expandContent("see [[Secret]]", { db: db2, mode: "full", expanded: new Set(), isVisible }, 1);
+
+    // Byte-identical output → existence is not leaked.
+    expect(outOfScope).toBe(missing);
+    expect(outOfScope).toBe("see [[Secret]]");
+  });
+
+  it("a second reference to an out-of-scope note does NOT render `(expanded above)`", () => {
+    // Pins that an out-of-scope note never enters the `expanded` set — else a
+    // repeat reference would render `(expanded above)` and leak existence via
+    // a different output than a missing target.
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("[[Secret]] and again [[Secret]]", ctx({ isVisible }), 1);
+    expect(out).toBe("[[Secret]] and again [[Secret]]");
+    expect(out).not.toContain("expanded above");
+    expect(out).not.toContain("SECRET BODY");
+  });
+
+  it("multi-hop (depth>1) does not leak out-of-scope content at any depth", () => {
+    // in-scope #work note → wikilinks an out-of-scope #personal note.
+    createNote(db, "DEEP SECRET", { path: "Deep", tags: ["personal"] });
+    createNote(db, "intro [[Deep]]", { path: "Mid", tags: ["work"] });
+    createNote(db, "top [[Mid]]", { path: "Top", tags: ["work"] });
+
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    // Depth 3 — would walk Top → Mid → Deep without the predicate.
+    const out = expandContent("[[Top]]", ctx({ isVisible }), 3);
+    // The in-scope Mid IS inlined; the out-of-scope Deep is NOT.
+    expect(out).toContain("intro");
+    expect(out).not.toContain("DEEP SECRET");
+    // The Deep wikilink stays literal inside Mid's inlined content.
+    expect(out).toContain("[[Deep]]");
+  });
+
+  it("predicate is also honored in summary mode", () => {
+    createNote(db, "x", {
+      path: "Secret",
+      tags: ["personal"],
+      metadata: { summary: "SECRET SUMMARY" },
+    });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("see [[Secret]]", ctx({ mode: "summary", isVisible }), 1);
+    expect(out).not.toContain("SECRET SUMMARY");
+    expect(out).toBe("see [[Secret]]");
+  });
+});