@openparachute/vault 0.6.0-rc.1 → 0.6.1

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;
 }
 

package/core/src/link-count.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { getLinkCounts } from "./links.js";
+
+// Feature: link-count field (`include_link_count` / `linkCount`) +
+// `order_by=link_count` (vault feedback #4).
+//
+// LOCKED SEMANTICS exercised here:
+//   - degree = row count = (#rows source_id=id) + (#rows target_id=id)
+//   - both directions by default; outbound/inbound variants
+//   - self-loop (source_id==target_id) counts as degree 2 under `both`
+//   - the order_by sort key uses the SAME directional-sum definition, so
+//     field value == sort key for EVERY note, self-loops included
+//   - two typed links between the same pair count as 2 (row count)
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("getLinkCounts (core helper)", () => {
+  it("counts both directions as a row sum", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    // a → b, a → c  (a outbound 2)
+    // c → a          (a inbound 1)  => a degree 3
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("a", "c", "mentions");
+    await store.createLink("c", "a", "mentions");
+
+    const both = getLinkCounts(db, ["a", "b", "c"]);
+    expect(both.get("a")).toBe(3); // 2 outbound + 1 inbound
+    expect(both.get("b")).toBe(1); // 1 inbound
+    expect(both.get("c")).toBe(2); // 1 outbound (c→a) + 1 inbound (a→c)
+  });
+
+  it("outbound and inbound variants count only one direction", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions"); // a outbound, b inbound
+
+    expect(getLinkCounts(db, ["a"], "outbound").get("a")).toBe(1);
+    expect(getLinkCounts(db, ["a"], "inbound").get("a")).toBe(0);
+    expect(getLinkCounts(db, ["b"], "outbound").get("b")).toBe(0);
+    expect(getLinkCounts(db, ["b"], "inbound").get("b")).toBe(1);
+  });
+
+  it("returns 0 for ids with no links (id always present in map)", async () => {
+    await store.createNote("Lonely", { id: "lonely" });
+    const counts = getLinkCounts(db, ["lonely"]);
+    expect(counts.get("lonely")).toBe(0);
+  });
+
+  it("empty id list → empty map (no query)", () => {
+    expect(getLinkCounts(db, []).size).toBe(0);
+  });
+
+  it("self-loop counts as degree 2 under both (outbound + inbound)", async () => {
+    await store.createNote("S", { id: "s" });
+    await store.createLink("s", "s", "relates"); // self-loop
+
+    expect(getLinkCounts(db, ["s"], "both").get("s")).toBe(2);
+    expect(getLinkCounts(db, ["s"], "outbound").get("s")).toBe(1);
+    expect(getLinkCounts(db, ["s"], "inbound").get("s")).toBe(1);
+  });
+
+  it("two typed links between the same pair count as 2 (row count)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("a", "b", "cites"); // same pair, different relationship
+
+    expect(getLinkCounts(db, ["a"], "both").get("a")).toBe(2);
+    expect(getLinkCounts(db, ["b"], "both").get("b")).toBe(2);
+  });
+
+  it("dedupes repeated ids in the request (no double-count)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    const counts = getLinkCounts(db, ["a", "a", "a"]);
+    expect(counts.get("a")).toBe(1);
+  });
+
+  it("batch correctness over a large page (exceeds the chunk size)", async () => {
+    // 1000 notes > the 900-id chunk boundary; each note i links to note 0,
+    // so note 0 has inbound degree 999 and every other note has outbound 1.
+    for (let i = 0; i < 1000; i++) {
+      await store.createNote(`n${i}`, { id: `n${i}` });
+    }
+    for (let i = 1; i < 1000; i++) {
+      await store.createLink(`n${i}`, "n0", "mentions");
+    }
+    const ids = Array.from({ length: 1000 }, (_, i) => `n${i}`);
+    const counts = getLinkCounts(db, ids);
+    expect(counts.size).toBe(1000); // every id present even across chunks
+    expect(counts.get("n0")).toBe(999); // all inbound
+    expect(counts.get("n1")).toBe(1); // one outbound
+    expect(counts.get("n999")).toBe(1);
+  });
+});
+
+describe("order_by=link_count (engine)", () => {
+  // Helper: assert the field value (via getLinkCounts, both) equals the
+  // sort-key ordering produced by order_by=link_count for EVERY note.
+  async function assertFieldEqualsSortOrder(sort: "asc" | "desc") {
+    const ordered = await store.queryNotes({ orderBy: "link_count", sort });
+    const degrees = getLinkCounts(
+      db,
+      ordered.map((n) => n.id),
+      "both",
+    );
+    const seq = ordered.map((n) => degrees.get(n.id) ?? 0);
+    // The emitted SQL sorts by the same directional-sum degree, so the
+    // degree sequence must already be monotonic in the requested direction.
+    const sorted = [...seq].sort((a, b) => (sort === "desc" ? b - a : a - b));
+    expect(seq).toEqual(sorted);
+    return { ordered, degrees };
+  }
+
+  it("sorts by degree descending and the field matches the sort key", async () => {
+    await store.createNote("Hub", { id: "hub" });
+    await store.createNote("Mid", { id: "mid" });
+    await store.createNote("Leaf", { id: "leaf" });
+    // hub degree 3, mid degree 1, leaf degree 0
+    await store.createLink("hub", "mid", "a");
+    await store.createLink("hub", "leaf", "b");
+    await store.createLink("mid", "hub", "c"); // hub inbound +1 => 3, mid outbound +1 => 2? recount below
+
+    // Recount precisely: hub source: hub→mid, hub→leaf (2); hub target: mid→hub (1) = 3
+    // mid source: mid→hub (1); mid target: hub→mid (1) = 2
+    // leaf target: hub→leaf (1) = 1
+    const { ordered } = await assertFieldEqualsSortOrder("desc");
+    expect(ordered.map((n) => n.id)).toEqual(["hub", "mid", "leaf"]);
+  });
+
+  it("sorts ascending with DISTINCT degrees: non-decreasing sequence, pinned IDs", async () => {
+    // Distinct degrees so ascending order is unambiguous (not just the
+    // tiebreaker case): low=0, mid=1, high=2. This genuinely pins
+    // field==sort-key for the ascending path.
+    await store.createNote("Low", { id: "low" }); // degree 0
+    await store.createNote("Mid", { id: "mid" }); // degree 1
+    await store.createNote("High", { id: "high" }); // degree 2
+    await store.createNote("Other", { id: "other" }); // link partner
+    await store.createLink("mid", "other", "a"); // mid out 1 => degree 1
+    await store.createLink("high", "other", "b"); // high out 1
+    await store.createLink("other", "high", "c"); // high in 1 => degree 2
+    // (other: out 1 + in 1 + in 1 = degree 3, sits above all — fine, we
+    // assert the low/mid/high prefix explicitly below.)
+
+    const { ordered, degrees } = await assertFieldEqualsSortOrder("asc");
+    const seq = ordered.map((n) => degrees.get(n.id) ?? 0);
+    // Non-decreasing (assertFieldEqualsSortOrder already checks this; assert
+    // explicitly here too for the distinct-degree case).
+    for (let i = 1; i < seq.length; i++) {
+      expect(seq[i]!).toBeGreaterThanOrEqual(seq[i - 1]!);
+    }
+    // Ascending: the three distinct-degree notes appear in 0,1,2 order.
+    expect(ordered.map((n) => n.id)).toEqual(["low", "mid", "high", "other"]);
+    expect(degrees.get("low")).toBe(0);
+    expect(degrees.get("mid")).toBe(1);
+    expect(degrees.get("high")).toBe(2);
+    expect(degrees.get("other")).toBe(3);
+  });
+
+  it("self-loop: linkCount==2 AND its order_by position matches that 2", async () => {
+    // selfy has a self-loop (degree 2), plain has one inbound (degree 1),
+    // zero has none (degree 0). Descending order must place selfy first,
+    // and selfy's field value must be exactly 2 (not 1).
+    await store.createNote("Selfy", { id: "selfy" });
+    await store.createNote("Plain", { id: "plain" });
+    await store.createNote("Zero", { id: "zero" });
+    await store.createLink("selfy", "selfy", "loop"); // degree 2
+    await store.createLink("zero", "plain", "ref"); // plain inbound 1, zero outbound 1
+
+    const { ordered, degrees } = await assertFieldEqualsSortOrder("desc");
+    // selfy degree 2 is the max → first.
+    expect(ordered[0]!.id).toBe("selfy");
+    expect(degrees.get("selfy")).toBe(2);
+    // The field value (2) equals the sort key — selfy outranks plain/zero
+    // (both degree 1) precisely because the order_by subquery also counts
+    // the self-loop twice. A single OR-COUNT would have made it 1 and tied.
+    expect(degrees.get("plain")).toBe(1);
+    expect(degrees.get("zero")).toBe(1);
+  });
+
+  it("created_at is the stable tiebreaker among equal degrees", async () => {
+    // Three zero-degree notes; descending order falls back to created_at
+    // descending (the tiebreaker honors direction).
+    await store.createNote("First", { id: "first", created_at: "2026-01-01T00:00:00.000Z" });
+    await store.createNote("Second", { id: "second", created_at: "2026-01-02T00:00:00.000Z" });
+    await store.createNote("Third", { id: "third", created_at: "2026-01-03T00:00:00.000Z" });
+    const desc = await store.queryNotes({ orderBy: "link_count", sort: "desc" });
+    expect(desc.map((n) => n.id)).toEqual(["third", "second", "first"]);
+    const asc = await store.queryNotes({ orderBy: "link_count", sort: "asc" });
+    expect(asc.map((n) => n.id)).toEqual(["first", "second", "third"]);
+  });
+
+  it("does NOT require the field to be indexed (pseudo-field bypass)", async () => {
+    await store.createNote("A", { id: "a" });
+    // Would throw FIELD_NOT_INDEXED if it routed through requireIndexedField.
+    const results = await store.queryNotes({ orderBy: "link_count" });
+    expect(results.length).toBe(1);
+  });
+});
+
+describe("query-notes MCP surface: include_link_count", () => {
+  async function seed() {
+    await store.createNote("Hub", { id: "hub" });
+    await store.createNote("Leaf", { id: "leaf" });
+    await store.createNote("Self", { id: "self" });
+    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 degree 2
+  }
+
+  it("list mode: include_link_count injects linkCount; absent flag → no key", async () => {
+    await seed();
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const withCount = (await query.execute({ include_link_count: true })) as any[];
+    const hub = withCount.find((n) => n.id === "hub");
+    expect(hub.linkCount).toBe(2);
+    const self = withCount.find((n) => n.id === "self");
+    expect(self.linkCount).toBe(2); // self-loop = 2
+
+    const without = (await query.execute({})) as any[];
+    expect(without.every((n) => !("linkCount" in n))).toBe(true);
+  });
+
+  it("single-note mode: include_link_count → correct degree", async () => {
+    await seed();
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ id: "self", include_link_count: true })) as any;
+    expect(result.linkCount).toBe(2);
+  });
+
+  it("direction variants on the MCP surface", async () => {
+    await seed();
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const out = (await query.execute({
+      id: "hub",
+      include_link_count: true,
+      link_count_direction: "outbound",
+    })) as any;
+    expect(out.linkCount).toBe(1); // hub→leaf only
+    const inb = (await query.execute({
+      id: "hub",
+      include_link_count: true,
+      link_count_direction: "inbound",
+    })) as any;
+    expect(inb.linkCount).toBe(1); // leaf→hub only
+  });
+
+  it("unrecognized link_count_direction falls back to both (MCP normalizeLinkCountDirection)", async () => {
+    await seed();
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    // hub: both=2, outbound=1, inbound=1. A bogus value must degrade to
+    // `both` (2), distinct from either directional value (1).
+    const result = (await query.execute({
+      id: "hub",
+      include_link_count: true,
+      link_count_direction: "sideways",
+    })) as any;
+    expect(result.linkCount).toBe(2);
+  });
+
+  it("note with 0 links → linkCount: 0", async () => {
+    await store.createNote("Lonely", { id: "lonely" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ id: "lonely", include_link_count: true })) as any;
+    expect(result.linkCount).toBe(0);
+  });
+
+  it("order_by=link_count over MCP: field value == sort key for every note", async () => {
+    await seed();
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const ordered = (await query.execute({
+      order_by: "link_count",
+      sort: "desc",
+      include_link_count: true,
+    })) as any[];
+    // Every note carries linkCount, and the sequence is non-increasing.
+    const seq = ordered.map((n) => n.linkCount as number);
+    expect(seq).toEqual([...seq].sort((a, b) => b - a));
+    // hub (2), leaf (2), self (2) all degree 2 here.
+    for (const n of ordered) expect(typeof n.linkCount).toBe("number");
+  });
+});

package/core/src/links.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import type { Link, NoteSummary, HydratedLink } from "./types.js";
-import { getNoteTags } from "./notes.js";
+import { getNoteTagsForNotes } from "./notes.js";
 
 export function createLink(
   db: Database,
@@ -103,28 +103,25 @@ function parseMetadata(raw: string | null): Record<string, unknown> | undefined
   try { return JSON.parse(raw); } catch { return undefined; }
 }
 
-function getNoteSummary(db: Database, noteId: string): NoteSummary | undefined {
-  const row = db.prepare(
-    "SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id = ?",
-  ).get(noteId) as SummaryRow | undefined;
-  if (!row) return undefined;
-  return {
-    id: row.id,
-    path: row.path ?? undefined,
-    metadata: parseMetadata(row.metadata),
-    createdAt: row.created_at,
-    updatedAt: row.updated_at ?? undefined,
-    tags: getNoteTags(db, row.id),
-  };
-}
+/** IN-list chunk size — matches getLinkCounts' conservative bound-variable floor. */
+const IN_CHUNK = 900;
 
 function getNoteSummaries(db: Database, noteIds: string[]): Map<string, NoteSummary> {
   const map = new Map<string, NoteSummary>();
   if (noteIds.length === 0) return map;
-  const placeholders = noteIds.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id IN (${placeholders})`,
-  ).all(...noteIds) as SummaryRow[];
+  const ids = [...new Set(noteIds)];
+  const rows: SummaryRow[] = [];
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    rows.push(...db.prepare(
+      `SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as SummaryRow[]);
+  }
+  // ONE batched tag lookup for every summary on the page — this used to be
+  // a per-summary query, which made hydrating a well-linked note cost
+  // O(linked notes) round-trips (2026-06-10 perf measurements).
+  const tagsById = getNoteTagsForNotes(db, rows.map((r) => r.id));
   for (const row of rows) {
     map.set(row.id, {
       id: row.id,
@@ -132,7 +129,7 @@ function getNoteSummaries(db: Database, noteIds: string[]): Map<string, NoteSumm
       metadata: parseMetadata(row.metadata),
       createdAt: row.created_at,
       updatedAt: row.updated_at ?? undefined,
-      tags: getNoteTags(db, row.id),
+      tags: tagsById.get(row.id) ?? [],
     });
   }
   return map;
@@ -148,8 +145,11 @@ export function getLinksHydrated(
   opts?: { direction?: "outbound" | "inbound" | "both"; include_content?: boolean },
 ): HydratedLink[] {
   const links = getLinks(db, noteId, opts);
+  return hydrateLinks(db, links);
+}
 
-  // Collect all note IDs we need to hydrate
+/** Attach source/target note summaries to a set of links (batched). */
+function hydrateLinks(db: Database, links: Link[]): HydratedLink[] {
   const noteIds = new Set<string>();
   for (const link of links) {
     noteIds.add(link.sourceId);
@@ -165,6 +165,138 @@ export function getLinksHydrated(
   }));
 }
 
+/**
+ * Batch variant of `getLinksHydrated` for the `include_links` enrichment
+ * loops (MCP query-notes list path, REST GET /api/notes): hydrates links for
+ * a whole PAGE of notes in a constant number of queries — two indexed
+ * IN-list scans over `links` per chunk, one summary fetch, one batched tag
+ * lookup — instead of (1 link query + 1 summary query + N tag queries) per
+ * note. See the 2026-06-10 perf measurements (include_links scaled
+ * per-returned-note).
+ *
+ * Returns a map keyed by every requested note id (empty array when the note
+ * has no links). Each note's list contains links touching it in either
+ * direction, ordered created_at DESC — same contract as the single-note
+ * `getLinksHydrated`. A link between two notes that are BOTH on the page
+ * appears in both notes' lists, exactly as the per-note calls produced.
+ */
+export function getLinksHydratedForNotes(
+  db: Database,
+  noteIds: string[],
+): Map<string, HydratedLink[]> {
+  const result = new Map<string, HydratedLink[]>();
+  if (noteIds.length === 0) return result;
+  const ids = [...new Set(noteIds)];
+  for (const id of ids) result.set(id, []);
+
+  // Collect every link touching any requested note, deduped on the
+  // (source, target, relationship) primary key so a link whose endpoints
+  // are both on the page is fetched once.
+  const rowsByKey = new Map<string, LinkRow>();
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    for (const column of ["source_id", "target_id"] as const) {
+      const rows = db.prepare(
+        `SELECT * FROM links WHERE ${column} IN (${placeholders})`,
+      ).all(...chunk) as LinkRow[];
+      for (const row of rows) {
+        rowsByKey.set(`${row.source_id}|${row.target_id}|${row.relationship}`, row);
+      }
+    }
+  }
+
+  // Stable sort newest-first to mirror the single-note SQL's
+  // ORDER BY created_at DESC (ISO timestamps sort lexicographically).
+  const links = [...rowsByKey.values()]
+    .sort((a, b) => (a.created_at < b.created_at ? 1 : a.created_at > b.created_at ? -1 : 0))
+    .map(rowToLink);
+
+  const hydrated = hydrateLinks(db, links);
+  for (const link of hydrated) {
+    result.get(link.sourceId)?.push(link);
+    if (link.targetId !== link.sourceId) result.get(link.targetId)?.push(link);
+  }
+  return result;
+}
+
+/**
+ * Batch link-degree counter (vault feedback #4).
+ *
+ * Returns the link **degree** (raw row count) for each requested note id,
+ * never materializing link rows. Degree is defined as a sum of two
+ * directional row counts:
+ *
+ *   - `outbound` = `COUNT(*) FROM links WHERE source_id = id`
+ *   - `inbound`  = `COUNT(*) FROM links WHERE target_id = id`
+ *   - `both`     = outbound + inbound   (default)
+ *
+ * It is a **row count**, matching `getVaultStats.linkCount` (notes.ts):
+ * two typed links A→B (different `relationship`) count as 2, and a
+ * **self-loop** (source_id == target_id) counts as **degree 2** under
+ * `both` — once via the outbound query, once via the inbound query.
+ *
+ * ⚠️ This directional-sum definition MUST stay identical to the
+ * `order_by=link_count` sort key in `queryNotes` (notes.ts), which uses
+ * `(SELECT COUNT(*) ... source_id=n.id) + (SELECT COUNT(*) ... target_id=n.id)`.
+ * A single `COUNT(*) ... WHERE source_id=id OR target_id=id` would count a
+ * self-loop ONCE and diverge — do NOT use that shape here.
+ *
+ * Each direction is one grouped query over an existing B-tree index
+ * (`idx_links_source` / `idx_links_target`), so the whole page costs at
+ * most two index scans regardless of page size. The IN-list is chunked to
+ * stay under SQLite's bound-variable limit on very large pages.
+ *
+ * Returns 0 for ids with no links (every requested id is present in the map).
+ */
+export function getLinkCounts(
+  db: Database,
+  noteIds: string[],
+  direction: "both" | "outbound" | "inbound" = "both",
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  if (noteIds.length === 0) return counts;
+
+  // Dedupe so a repeated id doesn't inflate the IN-list or get summed twice
+  // when the same chunk runs the outbound + inbound grouped queries.
+  const ids = [...new Set(noteIds)];
+  for (const id of ids) counts.set(id, 0);
+
+  const wantOutbound = direction === "outbound" || direction === "both";
+  const wantInbound = direction === "inbound" || direction === "both";
+
+  // SQLite's default SQLITE_MAX_VARIABLE_NUMBER is 999 on older builds and
+  // 32766 on newer ones; chunk well under the conservative floor so the
+  // IN-list never trips the bind limit on a large page.
+  const CHUNK = 900;
+  for (let i = 0; i < ids.length; i += CHUNK) {
+    const chunk = ids.slice(i, i + CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+
+    if (wantOutbound) {
+      const rows = db.prepare(
+        `SELECT source_id AS id, COUNT(*) AS c FROM links
+         WHERE source_id IN (${placeholders}) GROUP BY source_id`,
+      ).all(...chunk) as { id: string; c: number }[];
+      for (const row of rows) {
+        counts.set(row.id, (counts.get(row.id) ?? 0) + row.c);
+      }
+    }
+
+    if (wantInbound) {
+      const rows = db.prepare(
+        `SELECT target_id AS id, COUNT(*) AS c FROM links
+         WHERE target_id IN (${placeholders}) GROUP BY target_id`,
+      ).all(...chunk) as { id: string; c: number }[];
+      for (const row of rows) {
+        counts.set(row.id, (counts.get(row.id) ?? 0) + row.c);
+      }
+    }
+  }
+
+  return counts;
+}
+
 // ---- Deeper Link Queries ----
 
 export interface TraversalNode {
@@ -178,14 +310,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];
@@ -209,6 +353,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,
@@ -234,6 +382,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,