@openparachute/vault 0.5.2 → 0.5.3-rc.2

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;
@@ -1894,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 ----
@@ -2013,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")!;

package/core/src/links.ts

@@ -255,14 +255,26 @@ export interface TraversalNode {
 /**
  * Traverse the link graph from a starting note up to `maxDepth` hops.
  * Returns all reachable notes with their depth and how they were reached.
+ *
+ * `isTraversable` (vault#439) is an OPTIONAL per-note predicate. When
+ * provided, a neighbor that fails the predicate is treated as a WALL: it is
+ * neither added to the results nor pushed onto the frontier, so the BFS
+ * cannot reach further notes THROUGH it. This makes a tag-scoped traversal
+ * symmetric with `find-path` (which guards every hop) — scope acts as a wall,
+ * not a sieve. Omitted (every unscoped / internal caller) → the full graph is
+ * walked exactly as before. Core stays scope-unaware: it receives a plain
+ * `(noteId) => boolean` closure and never imports the server's tag-scope
+ * module. The anchor `noteId` is never passed through the predicate — the
+ * caller is responsible for confirming the anchor is in scope before calling.
  */
 export function traverseLinks(
   db: Database,
   noteId: string,
-  opts?: { max_depth?: number; relationship?: string },
+  opts?: { max_depth?: number; relationship?: string; isTraversable?: (noteId: string) => boolean },
 ): TraversalNode[] {
   const maxDepth = opts?.max_depth ?? 2;
   const relFilter = opts?.relationship;
+  const isTraversable = opts?.isTraversable;
   const visited = new Set<string>([noteId]);
   const results: TraversalNode[] = [];
   let frontier = [noteId];
@@ -286,6 +298,10 @@ export function traverseLinks(
       for (const row of outbound) {
         if (!visited.has(row.target_id)) {
           visited.add(row.target_id);
+          // Wall (vault#439): an out-of-scope neighbor is marked visited (so
+          // it isn't re-evaluated) but is NOT added to the frontier or the
+          // results — the BFS can't traverse THROUGH it to reach notes beyond.
+          if (isTraversable && !isTraversable(row.target_id)) continue;
           nextFrontier.push(row.target_id);
           results.push({
             noteId: row.target_id,
@@ -311,6 +327,8 @@ export function traverseLinks(
       for (const row of inbound) {
         if (!visited.has(row.source_id)) {
           visited.add(row.source_id);
+          // Wall (vault#439): see the outbound branch above.
+          if (isTraversable && !isTraversable(row.source_id)) continue;
           nextFrontier.push(row.source_id);
           results.push({
             noteId: row.source_id,

package/core/src/mcp.ts

@@ -114,6 +114,15 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
  */
 export interface GenerateMcpToolsOpts {
   expandVisibility?: (note: Note) => boolean;
+  /**
+   * `nearTraversable` (vault#439) is an OPTIONAL per-note predicate threaded
+   * into the `near[]` graph BFS. When provided, the traversal refuses to walk
+   * THROUGH any note that fails the predicate — making a tag-scoped `near[]`
+   * query symmetric with `find-path` (scope is a wall, not a sieve). Core
+   * stays scope-unaware: it receives a plain `(noteId) => boolean` closure.
+   * Omitted (unscoped / internal callers) → the full graph is walked.
+   */
+  nearTraversable?: (noteId: string) => boolean;
 }
 
 /**
@@ -122,8 +131,9 @@ export interface GenerateMcpToolsOpts {
  * delete-tag, find-path, vault-info, prune-schema (admin).
  */
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
-  const db: Database = (store as any).db;
+  const db: Database = store.db;
   const expandVisibility = opts?.expandVisibility;
+  const nearTraversable = opts?.nearTraversable;
 
   return [
 
@@ -305,15 +315,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // --- Build near-scope (graph-filtered set of allowed IDs) ---
         //
-        // Tag-scope policy for `near[]` (output-filter, not hop-guard): core
-        // is scope-unaware, so this BFS walks the FULL graph from the anchor —
-        // including out-of-scope intermediate hops. For a tag-scoped session
-        // the server's `applyTagScopeWrappers` (mcp-tools.ts) tag-filters the
-        // RESULT list AFTER execute, so out-of-scope notes never survive into
-        // the response — no content/ids leak. This is ASYMMETRIC with
-        // `find-path`, which guards every hop (it returns the path itself, so
-        // an out-of-scope intermediary would be a leak there). The asymmetry is
-        // deliberate; tracked at vault#439.
+        // Tag-scope policy for `near[]` (vault#439 — hop-guard, symmetric with
+        // find-path): when the session is tag-scoped the server injects a
+        // `nearTraversable` predicate (mcp-tools.ts), and the BFS refuses to
+        // walk THROUGH out-of-scope notes — scope is a wall, not a sieve. So a
+        // token scoped to ["work"] can't reach an in-scope note at depth 2 via
+        // a #personal intermediary at depth 1. Core stays scope-unaware: it
+        // only invokes the injected closure. Unscoped sessions pass no
+        // predicate → the FULL graph is walked exactly as before. The
+        // `applyTagScopeWrappers` result-filter still runs afterward (defense
+        // in depth), but the wall makes it redundant for `near[]`.
         let nearScope: Set<string> | null = null;
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
@@ -323,6 +334,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
             relationship: near.relationship,
+            isTraversable: nearTraversable,
           });
           nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         }
@@ -579,17 +591,35 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           throw e;
         }
 
-        // Apply tag schema effects
+        // Apply tag schema effects, then re-read the notes whose metadata was
+        // actually default-filled so the response reflects the final on-disk
+        // state (the `created` entries were read before `applySchemaDefaults`
+        // ran, so default-filled metadata isn't on them yet). This mirrors the
+        // update-note path, which already re-reads post-defaults. The re-read
+        // is batched (`getNotes` = one `WHERE id IN (...)`) and skipped
+        // entirely when no defaults were applied, so the common no-defaults
+        // path adds zero extra reads.
+        const mutatedIds = new Set<string>();
         for (const note of created) {
           if (note.tags && note.tags.length > 0) {
-            await applySchemaDefaults(store, db, [note.id], note.tags);
+            for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
+              mutatedIds.add(id);
+            }
           }
         }
-
-        // Re-read after schema-default population so the response reflects the
-        // final on-disk state, then attach `validation_status` from any
-        // tag's `fields` declaration that applies to this note.
-        const final = created.map((n) => attachValidationStatus(store, db, n));
+        const refreshed =
+          mutatedIds.size === 0
+            ? created
+            : (() => {
+                const byId = new Map(
+                  noteOps.getNotes(db, [...mutatedIds]).map((n) => [n.id, n]),
+                );
+                return created.map((n) => byId.get(n.id) ?? n);
+              })();
+
+        // Attach `validation_status` from any tag's `fields` declaration that
+        // applies to this note, against the post-defaults state.
+        const final = refreshed.map((n) => attachValidationStatus(store, db, n));
         return batch ? final : final[0];
       },
     },
@@ -1394,9 +1424,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 // Tag schema effects — auto-populate defaults when tags are applied
 // ---------------------------------------------------------------------------
 
-async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<void> {
+/**
+ * Fill schema-declared default values into the metadata of the given notes
+ * for any field they omitted. Returns the IDs of the notes whose metadata was
+ * actually written — callers use this to re-read ONLY the mutated notes (and
+ * to skip the re-read entirely when nothing changed). The common no-schema /
+ * no-defaults path returns an empty array.
+ */
+async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return;
+  if (Object.keys(schemas).length === 0) return [];
 
   const defaults: Record<string, unknown> = {};
   for (const tag of tags) {
@@ -1408,8 +1445,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       }
     }
   }
-  if (Object.keys(defaults).length === 0) return;
+  if (Object.keys(defaults).length === 0) return [];
 
+  const mutated: string[] = [];
   for (const noteId of noteIds) {
     const note = noteOps.getNote(db, noteId);
     if (!note) continue;
@@ -1425,7 +1463,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       metadata: { ...existing, ...missing },
       skipUpdatedAt: true,
     });
+    mutated.push(noteId);
   }
+  return mutated;
 }
 
 function defaultForField(field: { type: string; enum?: string[] }): unknown {

package/core/src/types.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 
@@ -208,6 +209,15 @@ export interface HydratedLink extends Link {
 // ---- Store Interface ----
 
 export interface Store {
+  /**
+   * The underlying `bun:sqlite` handle. Exposed (read-only) so callers that
+   * need to run a raw query the Store interface doesn't surface — e.g. the
+   * token-table reverse-lookups in routes.ts and MCP tool generation in
+   * mcp.ts — can reach it without an `(store as any).db` cast. The concrete
+   * `Store` class declares this as `public readonly db: Database`. See vault#242.
+   */
+  readonly db: Database;
+
   // Notes
   createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.2",
+  "version": "0.5.3-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/config.test.ts

@@ -213,6 +213,72 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  // ----- vault#234: anchored api_keys field regexes ----------------------
+  // The api_keys field regexes (label/scope/key_hash/created_at/last_used_at)
+  // used to be unanchored, so a COMMENTED `# scope: read` line matched, and a
+  // value-less `scope: ` (trailing space) captured the NEXT field's token
+  // (`key_hash`). The writer never emits either shape — only hand-editing
+  // reaches these branches — but a malformed scope could silently mis-scope a
+  // key. The regexes are now line-anchored + horizontal-whitespace-bounded.
+
+  test("vault#234: commented `# scope:` line is ignored, scope falls back to default", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234"), { recursive: true });
+    // The only `scope:` line is commented out; the parser must NOT pick it up.
+    fs.writeFileSync(
+      path,
+      `name: mv234\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_cmt\n    label: commented\n    # scope: read\n    key_hash: sha256:cmt\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234");
+    const key = loaded!.api_keys.find((k) => k.id === "k_cmt");
+    expect(key).toBeDefined();
+    // Commented scope ignored → default "write", NOT "read".
+    expect(key!.scope).toBe("write");
+    expect(key!.key_hash).toBe("sha256:cmt");
+  });
+
+  test("vault#234: value-less `scope: ` (trailing space) does NOT capture the next field", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b"), { recursive: true });
+    // `scope: ` has a trailing space and no value; the OLD regex skipped the
+    // newline and captured `sha256:trailing` (the key_hash) as the scope.
+    fs.writeFileSync(
+      path,
+      `name: mv234b\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_trail\n    label: trailing\n    scope: \n    key_hash: sha256:trailing\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234b");
+    const key = loaded!.api_keys.find((k) => k.id === "k_trail");
+    expect(key).toBeDefined();
+    // The hash must NOT have been borrowed as the scope.
+    expect(key!.scope).not.toBe("sha256:trailing");
+    expect(key!.scope).toBe("write"); // default
+    // And the real key_hash is still parsed correctly.
+    expect(key!.key_hash).toBe("sha256:trailing");
+  });
+
+  test("vault#234: a valid `scope: read` still parses (positive control, both parsers)", () => {
+    const fs = require("fs");
+    // Vault-level parser.
+    const vpath = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c"), { recursive: true });
+    fs.writeFileSync(
+      vpath,
+      `name: mv234c\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_v\n    label: reader\n    scope: read\n    key_hash: sha256:v\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    expect(readVaultConfig("mv234c")!.api_keys.find((k) => k.id === "k_v")?.scope).toBe("read");
+
+    // Global parser, same grammar.
+    const gpath = join(process.env.PARACHUTE_HOME!, "vault", "config.yaml");
+    fs.writeFileSync(
+      gpath,
+      `port: 1940\napi_keys:\n  - id: k_g\n    label: reader\n    # scope: write\n    scope: read\n    key_hash: sha256:g\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    // The commented `# scope: write` is skipped; the real `scope: read` wins.
+    expect(readGlobalConfig().api_keys?.find((k) => k.id === "k_g")?.scope).toBe("read");
+  });
+
   test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
     // Regression for vault#354 reviewer finding: the .env holds
     // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a

package/src/config.ts

@@ -518,14 +518,32 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   }
 
   // Parse api_keys
+  //
+  // Accepted grammar (vault#234): each `id:` block is the writer's output —
+  // one field per line, indented two spaces under the `- id:` list item:
+  //
+  //     - id: <id>
+  //       label: <label>            # free text to end of line
+  //       scope: <scope>            # single token (read|write|admin|…)
+  //       key_hash: <hash>          # single token
+  //       created_at: "<iso>"       # quoted or bare, no embedded newline
+  //       last_used_at: "<iso>"
+  //
+  // Each field regex is line-anchored (`^...`, `m` flag) so a COMMENTED line
+  // (`# scope: read`) never matches — the line must begin with optional
+  // leading whitespace then the bare key. The value matcher uses horizontal
+  // whitespace only (`[^\S\r\n]*`, never `\s*`) after the colon so a
+  // value-less field (`scope: ` with a trailing space) can't skip the newline
+  // and capture the NEXT field's value. A missing optional field falls back to
+  // its default rather than borrowing a neighbor's token.
   const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
   for (const block of keyBlocks) {
     const idMatch = block.match(/^(\S+)/);
-    const labelMatch = block.match(/label:\s*(.+)/);
-    const scopeMatch = block.match(/scope:\s*(\S+)/);
-    const hashMatch = block.match(/key_hash:\s*(\S+)/);
-    const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-    const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+    const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+    const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+    const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+    const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+    const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
 
     if (idMatch && hashMatch) {
       config.api_keys.push({
@@ -1250,16 +1268,19 @@ export function readGlobalConfig(): GlobalConfig {
       }
 
       // Parse global api_keys
+      // Same line-anchored grammar as the vault-level parser above (vault#234)
+      // — commented lines don't match; a value-less field can't capture the
+      // next field's token across the newline.
       const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
       if (keyBlocks.length > 0) {
         config.api_keys = [];
         for (const block of keyBlocks) {
           const idMatch = block.match(/^(\S+)/);
-          const labelMatch = block.match(/label:\s*(.+)/);
-          const scopeMatch = block.match(/scope:\s*(\S+)/);
-          const hashMatch = block.match(/key_hash:\s*(\S+)/);
-          const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-          const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+          const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+          const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+          const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+          const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+          const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
           if (idMatch && hashMatch) {
             config.api_keys.push({
               id: idMatch[1]!,

package/src/mcp-tools.ts

@@ -7,6 +7,7 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import { getNoteTags } from "../core/src/notes.ts";
 import type { Note } from "../core/src/types.ts";
 import {
   buildVaultProjection,
@@ -135,9 +136,27 @@ export function generateScopedMcpTools(
     ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
     : undefined;
 
+  // Tag-scope hop-guard for `near[]` (vault#439): a per-note predicate the
+  // core BFS consults so it refuses to traverse THROUGH out-of-scope notes —
+  // symmetric with find-path. Reads from the SAME shared `allowedHolder` the
+  // result-filter populates; the query-notes wrapper `await getAllowed()`s
+  // (which fills the holder) before core's execute runs the BFS, so the
+  // allowlist is ready by the time this fires. Looks up each candidate note's
+  // tags by id (sync, core-native). Unscoped sessions install no predicate.
+  const nearTraversable = scoped
+    ? (noteId: string) =>
+        noteWithinTagScope(
+          { id: noteId, tags: getNoteTags(store.db, noteId) } as Note,
+          allowedHolder.value,
+          rawTags,
+        )
+    : undefined;
+
   const tools = generateMcpTools(
     store,
-    expandVisibility ? { expandVisibility } : undefined,
+    expandVisibility || nearTraversable
+      ? { ...(expandVisibility ? { expandVisibility } : {}), ...(nearTraversable ? { nearTraversable } : {}) }
+      : undefined,
   );
 
   overrideVaultInfo(tools, vaultName, auth);