@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/.parachute/module.json

@@ -6,10 +6,21 @@
   "port": 1940,
   "paths": ["/vault/default"],
   "health": "/vault/default/health",
-  "managementUrl": "/admin/",
-  "uiUrl": "/admin/",
+  "managementUrl": "admin/",
+  "uiUrl": "admin/",
+  "configUiUrl": "/vault/admin/",
+  "focus": "core",
+  "adminCapabilities": ["config", "credentials"],
   "startCmd": ["parachute-vault", "serve"],
   "scopes": {
     "defines": ["vault:read", "vault:write", "vault:admin"]
-  }
+  },
+  "events": [
+    { "key": "note.created", "title": "A note was created" },
+    { "key": "note.updated", "title": "A note was updated" },
+    { "key": "note.deleted", "title": "A note was deleted" }
+  ],
+  "actions": [
+    { "key": "note.create", "title": "Create a note", "inputSchema": {} }
+  ]
 }

package/README.md

@@ -99,7 +99,7 @@ The daemon binds `0.0.0.0:1940` (or whatever you set in `PORT`) and serves REST,
 
 `vault init` asks two explicit questions: (1) install vault as an MCP server in `~/.claude.json`? (2) also surface the access token so you can paste it into other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or `curl`? Both default yes. Pass `--mcp` / `--no-mcp` and `--token` / `--no-token` for non-interactive installs.
 
-If you said yes to (2), the hub-issued JWT is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Mint a fresh one with `parachute auth mint-token --scope vault:<name>:<verb>` (or rewire an MCP client with `parachute-vault mcp-install`, or use the admin SPA Tokens page). As of vault 0.6.0 (vault#282 Stage 2) vault no longer mints its own `pvt_*` tokens — minting is the hub's job.
+If you said yes to (2), the hub-issued JWT is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Mint a fresh one with `parachute auth mint-token --scope vault:<name>:<verb>` (or rewire an MCP client with `parachute-vault mcp-install`, or use the admin SPA Tokens page). As of vault 0.5.0 (vault#282 Stage 2) vault no longer mints its own `pvt_*` tokens — minting is the hub's job.
 
 ### OAuth lives on the hub
 
@@ -122,7 +122,7 @@ Two ways to authenticate — pick based on the client, not the deployment:
 | **OAuth 2.1 + PKCE (browser flow, via hub)** | Claude Desktop, Parachute Daily, any third-party MCP client set up interactively | Click "Add integration", enter the vault MCP URL, a browser opens to the **hub's** consent page, sign in with hub credentials, done — no token ever touches your clipboard |
 | **Bearer token (hub JWT)** | Claude Code (auto-wired by `vault init`), CLI scripts, cron jobs, any non-interactive caller | `curl -H "Authorization: Bearer <hub-jwt>"` — mint one with `parachute-vault mcp-install` (MCP clients) or `parachute auth mint-token --scope vault:<name>:<verb>` (scripts) |
 
-As of 0.6.0 (vault#282 Stage 2) vault is a **pure hub resource-server**: both paths use a hub-signed JWT that vault validates against the hub's JWKS. (The OAuth path is the interactive browser handshake; the bearer path mints the same kind of JWT non-interactively.) The old vault-local `pvt_*` opaque token was dropped — vault no longer mints or accepts it. The server-wide `VAULT_AUTH_TOKEN` operator bearer remains for the no-granular-auth / cross-container path.
+As of 0.5.0 (vault#282 Stage 2) vault is a **pure hub resource-server**: both paths use a hub-signed JWT that vault validates against the hub's JWKS. (The OAuth path is the interactive browser handshake; the bearer path mints the same kind of JWT non-interactively.) The old vault-local `pvt_*` opaque token was dropped — vault no longer mints or accepts it. The server-wide `VAULT_AUTH_TOKEN` operator bearer remains for the no-granular-auth / cross-container path.
 
 ### Claude Code
 
@@ -219,7 +219,7 @@ parachute-vault 2fa backup-codes           # regenerate backup codes
 # Tokens — vault#282 Stage 2: vault no longer mints its own tokens. Mint a
 # hub JWT with `parachute-vault mcp-install` (MCP clients) or
 # `parachute auth mint-token --scope vault:<name>:<verb>` (scripts).
-parachute-vault tokens                     # list any vestigial pre-0.6.0 token rows (all vaults)
+parachute-vault tokens                     # list any vestigial pre-0.5.0 token rows (all vaults)
 parachute-vault tokens revoke <token-id>   # revoke a vestigial row (default vault; add --vault to target)
 
 # Obsidian
@@ -531,7 +531,7 @@ The SSG / sync pattern. Two equivalent forms — bracket-style is canonical goin
 curl -H "Authorization: Bearer $VAULT_TOKEN" \
   "http://localhost:1940/vault/default/api/notes?meta[updated_at][gte]=2026-04-01T00:00:00Z"
 
-# Flat form (DEPRECATED in 0.4.3; planned removal 0.6.0 per vault#288)
+# Flat form (DEPRECATED in 0.4.3; planned removal in a later 0.x per vault#288)
 curl -H "Authorization: Bearer $VAULT_TOKEN" \
   "http://localhost:1940/vault/default/api/notes?date_field=updated_at&date_from=2026-04-01T00:00:00Z"
 ```
@@ -704,13 +704,13 @@ For wiring up an AI client (Claude Code, Claude Desktop, Parachute Daily), see [
 
 ### Passing the key
 
-As of 0.6.0 (vault#282 Stage 2) vault accepts these bearers at every authenticated endpoint:
+As of 0.5.0 (vault#282 Stage 2) vault accepts these bearers at every authenticated endpoint:
 
 - **Hub-issued JWT** (`eyJ...`) — the user-credential path; what OAuth issues and what `parachute-vault mcp-install` / `parachute auth mint-token` produce. Audience-bound to `vault.<name>`, scope-narrowed (`vault:<name>:<verb>`).
 - **`VAULT_AUTH_TOKEN`** — the server-wide operator bearer (env var; full-admin against any vault on the server).
 - **`pvk_...`** — legacy global API keys from `config.yaml` / per-vault `vault.yaml` (still honored for existing deployments).
 
-The old vault-local `pvt_*` opaque token was **dropped at 0.6.0** — vault no longer mints or accepts it.
+The old vault-local `pvt_*` opaque token was **dropped at 0.5.0** — vault no longer mints or accepts it.
 
 ```bash
 # Header (preferred)
@@ -742,7 +742,7 @@ Two permission levels carry through the JWT scope verb:
 | `read` | Query, list, find-path, vault-info only |
 
 `parachute-vault tokens list` / `tokens revoke` remain only to clean up any
-vestigial pre-0.6.0 rows. Legacy `pvk_...` keys from config.yaml still work at
+vestigial pre-0.5.0 rows. Legacy `pvk_...` keys from config.yaml still work at
 runtime; the `vault keys` CLI commands were removed long ago.
 
 ### Public endpoints

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]]");
+  });
+});

package/core/src/expand.ts

@@ -22,6 +22,22 @@ export interface ExpandContext {
   mode: ExpandMode;
   /** Note IDs already expanded in this query. Shared across all expansions. */
   expanded: Set<string>;
+  /**
+   * Optional visibility predicate (tag-scope confidentiality, vault security
+   * review). When set and it returns `false` for a resolved target note, the
+   * wikilink is left UNRESOLVED — byte-identical to the not-found/unresolved
+   * branch, so an out-of-scope target is indistinguishable from a missing one
+   * (we never reveal existence differently across the scope boundary).
+   *
+   * Core stays scope-unaware: the server constructs this predicate from its
+   * tag-scope machinery and injects it; core only ever *calls* it. When
+   * unset (every unscoped caller), expansion behaves exactly as before.
+   *
+   * Applied at every hop — multi-hop (`expand_depth > 1`) expansion runs the
+   * predicate on each resolved target before inlining, so a deep chain can't
+   * tunnel out-of-scope content through an in-scope intermediary.
+   */
+  isVisible?: (note: Note) => boolean;
 }
 
 /**
@@ -62,14 +78,26 @@ export function expandContent(
     const noteId = resolveWikilink(ctx.db, target);
     if (!noteId) return match; // unresolved or ambiguous — leave as-is
 
+    // Resolve the target BEFORE the dedup check so the visibility gate can run
+    // first — an out-of-scope target must never enter `expanded` (otherwise a
+    // second reference to it would render `(expanded above)` and leak its
+    // existence via a different output than a genuinely-missing target).
+    const note = noteOps.getNote(ctx.db, noteId);
+    if (!note) return match; // shouldn't happen, but be safe
+
+    // Tag-scope confidentiality (vault security review): if a visibility
+    // predicate is installed and the resolved target is out of scope, leave
+    // the wikilink UNRESOLVED — byte-identical to the not-found / unresolved
+    // branches above. The out-of-scope case must be indistinguishable from a
+    // missing target so the response can't leak the target's existence. Runs
+    // at every hop, so multi-hop expansion can't tunnel out-of-scope content.
+    if (ctx.isVisible && !ctx.isVisible(note)) return match;
+
     if (ctx.expanded.has(noteId)) {
       return `${match} (expanded above)`;
     }
     ctx.expanded.add(noteId);
 
-    const note = noteOps.getNote(ctx.db, noteId);
-    if (!note) return match; // shouldn't happen, but be safe
-
     if (ctx.mode === "summary") {
       // Summary mode doesn't recurse: depth > 1 has no additional effect.
       return renderSummary(note);

package/core/src/indexed-fields.ts

@@ -101,7 +101,7 @@ export function listIndexedFields(db: Database): IndexedField[] {
 export function getIndexedField(db: Database, field: string): IndexedField | null {
   const row = db
     .prepare("SELECT field, sqlite_type, declarer_tags FROM indexed_fields WHERE field = ?")
-    .get(field) as IndexedFieldRow | undefined;
+    .get(field) as IndexedFieldRow | null;
   return row ? rowToField(row) : null;
 }