@openparachute/vault 0.6.0-rc.1 → 0.6.0

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

@@ -106,7 +106,7 @@ function parseMetadata(raw: string | null): Record<string, unknown> | 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;
+  ).get(noteId) as SummaryRow | null;
   if (!row) return undefined;
   return {
     id: row.id,
@@ -165,6 +165,83 @@ export function getLinksHydrated(
   }));
 }
 
+/**
+ * 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 +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];
@@ -209,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,
@@ -234,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,