@staix/vault-mem 0.2.2 → 0.2.3

package/src/vault-graph.ts

@@ -6,23 +6,24 @@ export interface GraphNode {
   label: string;
   type: string;
   domain: string;
-  description: string;
-  confidence: string;
+  description?: string;
+  confidence?: string;
   source_file: string;
-  topics: string;
+  topics?: string;
   community: number | null;
   degree: number;
 }
-export interface GraphEdge { source: string; target: string; relation: "wiki_link"; confidence_tag: "EXTRACTED"; confidence: 1 }
+export interface GraphEdge { source: string; target: string; relation: "wiki_link" | "fm_ref" | "bu_member" | "source_ref" | "related" | "supersedes"; field?: string; rel?: string; confidence_tag: "EXTRACTED"; confidence: 1 }
 export interface VaultGraph {
   directed: false;
   multigraph: false;
-  graph: { partitioner: "label-propagation"; iterations: number; max_iterations: number };
+  graph: { partitioner: "leiden"; resolution: number; modularity: number; iterations: number; max_iterations: number };
   nodes: GraphNode[];
   edges: GraphEdge[];
 }
 export interface GraphNeighborhood { start: string; hops: 1 | 2; nodes: GraphNode[]; edges: GraphEdge[]; truncated: boolean }
-const MAX_ITERATIONS = 32;
+/** Bound on Leiden levels summed over refinement rounds (`MAX_LEVELS` × `MAX_ROUNDS`). */
+const MAX_ITERATIONS = 32 * 8;
 const MAX_NODES = 10000;
 const MAX_EDGES = 100000;
 const FRONTMATTER = /^---\s*\n([\s\S]*?)\n---\s*\n/;
@@ -74,7 +75,7 @@ function mapping(value: unknown): value is Record<string, unknown> { return valu
 function truthy(value: unknown): boolean {
   return yamlTruthy(value);
 }
-function pyString(value: unknown): string {
+export function pyString(value: unknown): string {
   const scalar = scalarText(value);
   if (scalar !== undefined) return scalar;
   if (value === null || value === undefined) return "None";
@@ -116,28 +117,224 @@ function adjacency(graph: Pick<VaultGraph, "nodes" | "edges">): Map<string, Set<
   for (const edge of graph.edges) { neighbors.get(edge.source)?.add(edge.target); neighbors.get(edge.target)?.add(edge.source); }
   return neighbors;
 }
-function communities(nodes: GraphNode[], neighbors: Map<string, Set<string>>): number {
-  const labels = new Map(nodes.filter(node => !HUB_TYPES.has(node.type)).map(node => [node.id, node.id]));
-  let iterations = 0;
-  for (; iterations < MAX_ITERATIONS; iterations++) {
-    let changed = false;
-    for (const [id, current] of labels) {
-      const counts = new Map<string, number>();
-      for (const neighbor of neighbors.get(id)!) {
-        const label = labels.get(neighbor);
-        if (label !== undefined) counts.set(label, (counts.get(label) ?? 0) + 1);
+/** Leiden over the graph's own nodes and edges, with MOC/bu hubs excluded; writes `community` and the method metadata. */
+function communities(graph: VaultGraph): void {
+  const exclude = new Set(graph.nodes.filter(node => HUB_TYPES.has(node.type)).map(node => node.id));
+  const result = leidenCommunities(graph.nodes.map(node => node.id), graph.edges.map(edge => [edge.source, edge.target] as const), { exclude });
+  for (const node of graph.nodes) node.community = result.membership.get(node.id) ?? null;
+  graph.graph = { partitioner: "leiden", resolution: result.resolution, modularity: result.modularity, iterations: result.levels, max_iterations: MAX_ITERATIONS };
+}
+
+// ── Leiden (Traag, Waltman, van Eck 2019), modularity, deterministic ─────────────────────────────
+
+/** Resolution γ of the modularity objective. */
+export const LEIDEN_RESOLUTION = 1;
+const MAX_LEVELS = 32, MAX_ROUNDS = 8;
+interface WeightedGraph { n: number; start: Int32Array; to: Int32Array; weight: Float64Array; self: Float64Array; strength: Float64Array; m2: number }
+function weightedGraph(n: number, pairs: Map<number, number>, self: Float64Array): WeightedGraph {
+  const degree = new Int32Array(n);
+  for (const key of pairs.keys()) { degree[Math.floor(key / n)]!++; degree[key % n]!++; }
+  const start = new Int32Array(n + 1);
+  for (let i = 0; i < n; i++) start[i + 1] = start[i]! + degree[i]!;
+  const to = new Int32Array(start[n]!), weight = new Float64Array(start[n]!), fill = start.slice(0, n), strength = new Float64Array(n);
+  // Keys are visited in ascending order so every adjacency list is sorted by neighbor index.
+  for (const key of [...pairs.keys()].sort((a, b) => a - b)) {
+    const a = Math.floor(key / n), b = key % n, w = pairs.get(key)!;
+    to[fill[a]!] = b; weight[fill[a]!++] = w; to[fill[b]!] = a; weight[fill[b]!++] = w;
+    strength[a]! += w; strength[b]! += w;
+  }
+  let m2 = 0;
+  for (let i = 0; i < n; i++) { strength[i]! += 2 * self[i]!; m2 += strength[i]!; }
+  return { n, start, to, weight, self, strength, m2 };
+}
+/**
+ * Fast local moving (queue). Gains are compared as `k_in·2m − γ·k_v·K_C`, exact in floating point for integer weights.
+ * Ties keep the current community, then take the lowest community id. Returns whether any node moved.
+ */
+function moveNodes(g: WeightedGraph, comm: Int32Array, gamma: number): boolean {
+  const { n, start, to, weight, strength, m2 } = g;
+  const total = new Float64Array(n), size = new Int32Array(n);
+  for (let i = 0; i < n; i++) { total[comm[i]!]! += strength[i]!; size[comm[i]!]!++; }
+  const empty: number[] = [];
+  for (let c = n - 1; c >= 0; c--) if (!size[c]) empty.push(c);
+  const queue = new Int32Array(n), queued = new Uint8Array(n), neighbor = new Float64Array(n), seen = new Uint8Array(n), touched: number[] = [];
+  for (let i = 0; i < n; i++) { queue[i] = i; queued[i] = 1; }
+  let head = 0, count = n, moved = false;
+  while (count > 0) {
+    const v = queue[head]!; head = (head + 1) % n; count--; queued[v] = 0;
+    const own = comm[v]!, kv = strength[v]!;
+    for (let e = start[v]!; e < start[v + 1]!; e++) {
+      const c = comm[to[e]!]!;
+      if (!seen[c]) { seen[c] = 1; touched.push(c); }
+      neighbor[c]! += weight[e]!;
+    }
+    total[own]! -= kv; size[own]!--;
+    let best = own, bestScore = neighbor[own]! * m2 - gamma * kv * total[own]!;
+    for (const c of touched) {
+      if (c === own) continue;
+      const score = neighbor[c]! * m2 - gamma * kv * total[c]!;
+      if (score > bestScore || (score === bestScore && best !== own && c < best)) { best = c; bestScore = score; }
+    }
+    if (bestScore < 0 && size[own]! > 0) { best = empty.pop()!; bestScore = 0; }
+    comm[v] = best; total[best]! += kv; size[best]!++;
+    if (!size[own]) empty.push(own);
+    if (best !== own) {
+      moved = true;
+      for (let e = start[v]!; e < start[v + 1]!; e++) {
+        const u = to[e]!;
+        if (comm[u] !== best && !queued[u]) { queue[(head + count) % n] = u; queued[u] = 1; count++; }
       }
-      const next = [...counts].sort(([a, ac], [b, bc]) => bc - ac || compare(a, b))[0]?.[0] ?? current;
-      if (next !== current) { labels.set(id, next); changed = true; }
     }
-    if (!changed) { iterations++; break; }
+    for (const c of touched) { neighbor[c] = 0; seen[c] = 0; }
+    touched.length = 0;
+  }
+  return moved;
+}
+/**
+ * Refinement inside each community of `comm`, merging only well-connected singletons into well-connected subsets along
+ * edges (the greedy θ → 0 variant: the largest non-negative gain wins, ties to the lowest id). Returns the refined partition.
+ */
+function refine(g: WeightedGraph, comm: Int32Array, gamma: number): Int32Array {
+  const { n, start, to, weight, strength, m2 } = g;
+  const refined = new Int32Array(n), totalR = new Float64Array(n), external = new Float64Array(n), sizeR = new Int32Array(n), totalS = new Float64Array(n);
+  for (let i = 0; i < n; i++) { refined[i] = i; totalR[i] = strength[i]!; sizeR[i] = 1; totalS[comm[i]!]! += strength[i]!; }
+  for (let v = 0; v < n; v++) for (let e = start[v]!; e < start[v + 1]!; e++) if (comm[to[e]!] === comm[v]) external[v]! += weight[e]!;
+  const neighbor = new Float64Array(n), seen = new Uint8Array(n), touched: number[] = [];
+  for (let v = 0; v < n; v++) {
+    if (sizeR[refined[v]!] !== 1) continue;
+    const s = comm[v]!, kv = strength[v]!, ks = totalS[s]!, ext = external[refined[v]!]!;
+    if (ext * m2 < gamma * kv * (ks - kv)) continue;
+    for (let e = start[v]!; e < start[v + 1]!; e++) {
+      const u = to[e]!;
+      if (comm[u] !== s) continue;
+      const c = refined[u]!;
+      if (!seen[c]) { seen[c] = 1; touched.push(c); }
+      neighbor[c]! += weight[e]!;
+    }
+    let best = -1, bestScore = 0;
+    for (const c of touched) {
+      if (c === refined[v]) continue;
+      if (external[c]! * m2 < gamma * totalR[c]! * (ks - totalR[c]!)) continue;
+      const score = neighbor[c]! * m2 - gamma * kv * totalR[c]!;
+      if (score > bestScore || (score === bestScore && best !== -1 && c < best)) { best = c; bestScore = score; }
+    }
+    if (best >= 0 && bestScore > 0) {
+      const from = refined[v]!;
+      external[best] = external[best]! + ext - 2 * neighbor[best]!;
+      totalR[best]! += kv; sizeR[best]!++; refined[v] = best;
+      totalR[from] = 0; sizeR[from] = 0; external[from] = 0;
+    }
+    for (const c of touched) { neighbor[c] = 0; seen[c] = 0; }
+    touched.length = 0;
   }
-  const groups = new Map<string, string[]>();
-  for (const [id, label] of labels) { const group = groups.get(label) ?? []; group.push(id); groups.set(label, group); }
-  const ids = new Map<string, number>();
-  [...groups.values()].sort((a, b) => compare(a[0]!, b[0]!)).forEach((members, id) => { for (const member of members) ids.set(member, id); });
-  for (const node of nodes) node.community = ids.get(node.id) ?? null;
-  return iterations;
+  return refined;
+}
+/** Aggregate on `refined` (nodes numbered by first member), with `comm` as the initial partition of the aggregate graph. */
+function aggregate(g: WeightedGraph, refined: Int32Array, comm: Int32Array): { graph: WeightedGraph; nodeOf: Int32Array; comm: Int32Array } {
+  const index = new Int32Array(g.n).fill(-1), nodeOf = new Int32Array(g.n);
+  let count = 0;
+  for (let i = 0; i < g.n; i++) { const r = refined[i]!; if (index[r] === -1) index[r] = count++; nodeOf[i] = index[r]!; }
+  const self = new Float64Array(count), pairs = new Map<number, number>(), partition = new Int32Array(count);
+  const dense = new Int32Array(g.n).fill(-1);
+  let communities = 0;
+  for (let i = 0; i < g.n; i++) {
+    const a = nodeOf[i]!;
+    if (dense[comm[i]!] === -1) dense[comm[i]!] = communities++;
+    partition[a] = dense[comm[i]!]!;
+    self[a]! += g.self[i]!;
+    for (let e = g.start[i]!; e < g.start[i + 1]!; e++) {
+      const j = g.to[e]!;
+      if (j < i) continue;
+      const b = nodeOf[j]!, w = g.weight[e]!;
+      if (a === b) self[a]! += w;
+      else { const key = Math.min(a, b) * count + Math.max(a, b); pairs.set(key, (pairs.get(key) ?? 0) + w); }
+    }
+  }
+  return { graph: weightedGraph(count, pairs, self), nodeOf, comm: partition };
+}
+function modularity(g: WeightedGraph, comm: Int32Array, gamma: number): number {
+  if (!g.m2) return 0;
+  const inside = new Float64Array(g.n), total = new Float64Array(g.n);
+  for (let i = 0; i < g.n; i++) {
+    total[comm[i]!]! += g.strength[i]!; inside[comm[i]!]! += 2 * g.self[i]!;
+    for (let e = g.start[i]!; e < g.start[i + 1]!; e++) if (comm[g.to[e]!] === comm[i]) inside[comm[i]!]! += g.weight[e]!;
+  }
+  let q = 0;
+  for (let c = 0; c < g.n; c++) if (total[c]) q += inside[c]! / g.m2 - gamma * (total[c]! / g.m2) ** 2;
+  return q;
+}
+/** Split every community into its connected components (never lowers modularity), then renumber densely by first node. */
+function connectedSplit(g: WeightedGraph, comm: Int32Array): Int32Array {
+  const out = new Int32Array(g.n).fill(-1);
+  let next = 0;
+  const stack: number[] = [];
+  for (let i = 0; i < g.n; i++) {
+    if (out[i] !== -1) continue;
+    out[i] = next; stack.push(i);
+    while (stack.length) {
+      const v = stack.pop()!;
+      for (let e = g.start[v]!; e < g.start[v + 1]!; e++) { const u = g.to[e]!; if (out[u] === -1 && comm[u] === comm[i]) { out[u] = next; stack.push(u); } }
+    }
+    next++;
+  }
+  return out;
+}
+function leidenPass(base: WeightedGraph, initial: Int32Array, gamma: number): { comm: Int32Array; levels: number } {
+  let g = base, comm: Int32Array = initial.slice(), map: Int32Array = new Int32Array(base.n).map((_, i) => i), levels = 0;
+  for (; levels < MAX_LEVELS; levels++) {
+    moveNodes(g, comm, gamma);
+    let communities = 0;
+    const used = new Uint8Array(g.n);
+    for (let i = 0; i < g.n; i++) if (!used[comm[i]!]) { used[comm[i]!] = 1; communities++; }
+    if (communities === g.n) { levels++; break; }
+    const refined = refine(g, comm, gamma);
+    const next = aggregate(g, refined, comm);
+    if (next.graph.n === g.n) { levels++; break; } // no refinement merge: further levels cannot progress
+    map = map.map(x => next.nodeOf[x]!);
+    g = next.graph; comm = next.comm;
+  }
+  return { comm: connectedSplit(base, map.map(x => comm[x]!)), levels };
+}
+export interface LeidenResult { membership: Map<string, number>; modularity: number; levels: number; resolution: number }
+/**
+ * Deterministic Leiden for modularity over an undirected simple graph. Excluded ids get no community; every other id gets
+ * one (an isolate is a singleton). Duplicate pairs count once and a self-loop has weight 1, as in a networkx Graph. Nodes are
+ * indexed in code-point id order, so the result does not depend on input order. Communities are numbered by size
+ * (descending), then by their smallest member id, and every community induces a connected subgraph.
+ */
+export function leidenCommunities(ids: readonly string[], edges: readonly (readonly [string, string])[], options: { exclude?: ReadonlySet<string>; resolution?: number } = {}): LeidenResult {
+  const gamma = options.resolution ?? LEIDEN_RESOLUTION;
+  const order = [...new Set(ids)].filter(id => !options.exclude?.has(id)).sort(compare), index = new Map(order.map((id, i) => [id, i]));
+  const n = order.length, pairs = new Map<number, number>(), self = new Float64Array(n), selfSeen = new Uint8Array(n);
+  for (const [source, target] of edges) {
+    const a = index.get(source), b = index.get(target);
+    if (a === undefined || b === undefined) continue;
+    if (a === b) { if (!selfSeen[a]) { selfSeen[a] = 1; self[a] = 1; } continue; }
+    pairs.set(Math.min(a, b) * n + Math.max(a, b), 1);
+  }
+  const g = weightedGraph(n, pairs, self);
+  let comm: Int32Array = new Int32Array(n).map((_, i) => i), quality = modularity(g, comm, gamma), levels = 0;
+  for (let round = 0; round < MAX_ROUNDS; round++) {
+    const pass = leidenPass(g, comm, gamma), q = modularity(g, pass.comm, gamma);
+    levels += pass.levels;
+    if (round > 0 && !(q > quality)) break;
+    comm = pass.comm; quality = q;
+  }
+  const groups = new Map<number, number[]>();
+  for (let i = 0; i < n; i++) { const members = groups.get(comm[i]!) ?? []; members.push(i); groups.set(comm[i]!, members); }
+  const ranked = [...groups.values()].sort((a, b) => b.length - a.length || a[0]! - b[0]!);
+  const membership = new Map<string, number>();
+  ranked.forEach((members, id) => { for (const i of members) membership.set(order[i]!, id); });
+  return { membership, modularity: Math.round(quality * 1e6) / 1e6, levels, resolution: gamma };
+}
+/** Code-point string order, the tie-break every deterministic graph output uses. */
+export const codePointCompare = compare;
+/**
+ * The same deterministic Leiden as `buildGraph`, over an arbitrary undirected graph whose nodes are all clustered (no hub
+ * exclusion). Returns node id → community id (by size descending, then smallest member id).
+ */
+export function labelCommunities(ids: readonly string[], edges: readonly (readonly [string, string])[]): Map<string, number> {
+  return leidenCommunities(ids, edges).membership;
 }
 /** Pure transformation of the derived-index snapshot, preserving the reference wiki graph semantics. */
 export function buildGraph(snapshot: AnalysisSnapshot): VaultGraph {
@@ -161,11 +358,11 @@ export function buildGraph(snapshot: AnalysisSnapshot): VaultGraph {
       if (edges.size > MAX_EDGES) throw new Error(`graph: exceeds ${MAX_EDGES} edges`);
     }
   }
-  const graph: VaultGraph = { directed: false, multigraph: false, graph: { partitioner: "label-propagation", iterations: 0, max_iterations: MAX_ITERATIONS }, nodes,
+  const graph: VaultGraph = { directed: false, multigraph: false, graph: { partitioner: "leiden", resolution: LEIDEN_RESOLUTION, modularity: 0, iterations: 0, max_iterations: MAX_ITERATIONS }, nodes,
     edges: [...edges.values()].sort((a, b) => compare(a.source, b.source) || compare(a.target, b.target)) };
   const neighbors = adjacency(graph);
   for (const node of nodes) node.degree = neighbors.get(node.id)!.size + Number(neighbors.get(node.id)!.has(node.id));
-  graph.graph.iterations = communities(nodes, neighbors);
+  communities(graph);
   return graph;
 }
 export function graphNeighbors(graph: VaultGraph, start: string, hops: 1 | 2, limit: number): GraphNeighborhood {
@@ -199,7 +396,7 @@ export function graphReport(graph: VaultGraph, today: string): string {
     for (let i = 0; i < queue.length; i++) for (const neighbor of neighbors.get(queue[i]!)!) if (!seen.has(neighbor)) { seen.add(neighbor); queue.push(neighbor); }
   }
   const count = graph.nodes.length;
-  const out = [`# Graph Report (${today})`, "", "## Overview", "", "- **Mode**: wiki", "- **Partitioner**: deterministic label-propagation (32 iterations maximum)",
+  const out = [`# Graph Report (${today})`, "", "## Overview", "", "- **Mode**: wiki", "- **Partitioner**: deterministic Leiden (modularity)", `- **Resolution**: ${graph.graph.resolution}`, `- **Modularity**: ${graph.graph.modularity.toFixed(4)}`,
     `- **Nodes**: ${count} (${graph.nodes.filter(node => HUB_TYPES.has(node.type)).length} hubs excluded from clustering)`, `- **Edges**: ${graph.edges.length}`,
     `- **Communities**: ${groups.size}`, `- **Isolates**: ${graph.nodes.filter(node => node.degree === 0).length}`, `- **Connected components**: ${components}`,
     `- **Density**: ${(count > 1 ? 2 * graph.edges.length / (count * (count - 1)) : 0).toFixed(4)}`, "", "## God Nodes (Top Connected)", "", "| Rank | Node | Degree |", "|------|------|--------|"];
@@ -231,3 +428,11 @@ export function graphReport(graph: VaultGraph, today: string): string {
   else out.push("No cross-community edges found.");
   return out.join("\n") + "\n";
 }
+
+/** Recompute derived degrees and communities after adding workspace nodes and edges. */
+export function finalizeGraph(graph: VaultGraph): VaultGraph {
+  const neighbors = adjacency(graph);
+  for (const node of graph.nodes) node.degree = neighbors.get(node.id)!.size + Number(neighbors.get(node.id)!.has(node.id));
+  communities(graph);
+  return graph;
+}

package/src/workspace-graph.ts

@@ -0,0 +1,139 @@
+import { AnalysisYamlScalar, parseAnalysisYaml, yamlTruthy } from "./analysis-yaml.ts";
+import type { AnalysisSnapshot } from "./analysis-types.ts";
+import { buildGraph, finalizeGraph, pythonTitle, pyString, type GraphNode, type GraphEdge, type VaultGraph } from "./vault-graph.ts";
+import { posix } from "node:path";
+
+export interface WorkspaceSnapshot {
+  files: { path: string; text: string }[];
+  buSlugs: string[];
+  skipRoots: string[];
+  assertUnchanged?: () => void;
+  sourceTargets: Record<string, "file" | "directory" | "missing" | "denied">;
+}
+export const WORK_SKIP_DIRS = new Set([".git", "node_modules", ".venv", ".sync-conflicts", "temp", ".maru", ".pnpm-store", ".conductor", ".dotfiles", ".omx", ".omc", ".gstack", ".frontend-slides", ".claude", ".archive", "archive", "vault", "inbox", "sites", "dev", "shared", "_templates", "templates"]);
+const FIELDS = ["projects", "project", "vault_note", "topics", "attendees", "relatedMeetings", "relatedTasks"];
+const FRONTMATTER = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+const WIKI = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g;
+const PRIORITY = { wiki_link: 0, fm_ref: 1, bu_member: 2, source_ref: 3, related: 4, supersedes: 5 };
+export type WorkCounters = Record<"work_docs" | "yaml_fail" | "template_skip" | "related_unresolved" | "related_ambiguous" | "related_dir_skip" | "related_root_escape" | "related_home_escape" | "source_stub" | "source_dead" | "source_nonmd" | "source_skiproot" | "collisions" | "dup_edges", number>;
+export function workSkipped(path: string, roots: string[]): boolean {
+  const normalized = path.normalize("NFC").replace(/^\/+|\/+$/g, "");
+  return roots.some(root => normalized === root || normalized.startsWith(root + "/"));
+}
+function mapping(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof AnalysisYamlScalar); }
+export function workspaceFrontmatter(text: string): Record<string, unknown> {
+  const match = FRONTMATTER.exec(text);
+  if (!match) return {};
+  try { const value = parseAnalysisYaml(match[1]!); return mapping(value) ? value : {}; }
+  catch { return {}; } // The reference skips rejected YAML and counts work-doc failures.
+}
+function links(value: unknown): string[] { return [...pyString(value).matchAll(WIKI)].map(match => match[1]!.trim().normalize("NFC").toLowerCase().replaceAll(" ", "-")); }
+function coerce(value: unknown): string {
+  return value instanceof AnalysisYamlScalar && value.kind === "timestamp" ? value.text.replace(" ", "T") : pyString(value);
+}
+function label(path: string): string {
+  let stem = posix.basename(path, ".md").normalize("NFC");
+  const parent = posix.basename(posix.dirname(path));
+  if (["readme", "index"].includes(stem.toLowerCase()) && parent !== ".") stem = parent + "-" + stem;
+  return pythonTitle(stem.replaceAll("-", " "));
+}
+/** Reference source spelling: keep its ID spelling, including path segments, rather than silently remap it. */
+export function workspaceSource(fm: Record<string, unknown>): string | undefined {
+  if (typeof fm.source !== "string" || !fm.source.trim()) return undefined;
+  let raw = fm.source.trim().replace(/^"+|"+$/g, "").replace(/^'+|'+$/g, "");
+  if (!raw || raw.startsWith("http://") || raw.startsWith("https://")) return undefined;
+  if (raw.startsWith("work/")) raw = raw.slice(5);
+  return raw.normalize("NFC");
+}
+export function buildWorkspaceGraph(snapshot: AnalysisSnapshot, work: WorkspaceSnapshot): { graph: VaultGraph; counters: WorkCounters; relations: Record<string, number> } {
+  const graph = buildGraph(snapshot);
+  const counters: WorkCounters = { work_docs: 0, yaml_fail: 0, template_skip: 0, related_unresolved: 0, related_ambiguous: 0, related_dir_skip: 0, related_root_escape: 0, related_home_escape: 0, source_stub: 0, source_dead: 0, source_nonmd: 0, source_skiproot: 0, collisions: 0, dup_edges: 0 };
+  const vaultIds = new Set(graph.nodes.map(node => node.id));
+  const docs = new Map<string, { path: string; fm: Record<string, unknown>; body: string }>(), stems = new Map<string, string[]>();
+  for (const file of work.files) {
+    const match = FRONTMATTER.exec(file.text);
+    if (!match) continue;
+    if (match[1]!.includes("{{")) { counters.template_skip++; continue; }
+    const fm = workspaceFrontmatter(file.text);
+    if (!Object.keys(fm).length) { if (match[1]!.trim()) counters.yaml_fail++; continue; }
+    if (!yamlTruthy(fm.document_type) && !FIELDS.some(field => yamlTruthy(fm[field])) && !yamlTruthy(fm.related)) continue;
+    const path = file.path.normalize("NFC"), id = "work:" + path.slice(0, -3);
+    docs.set(id, { path, fm, body: file.text.slice(match[0].length) });
+    const key = posix.basename(path, ".md").toLowerCase().replaceAll(" ", "-");
+    stems.set(key, [...stems.get(key) ?? [], id]); counters.work_docs++;
+  }
+  const validBu = new Set(work.buSlugs), usedBu = new Set<string>();
+  const businessUnit = (fm: Record<string, unknown>) => pyString(fm.business_unit ?? "").replaceAll("[[", "").replaceAll("]]", "").trim();
+  for (const doc of docs.values()) { const bu = businessUnit(doc.fm); if (validBu.has(bu)) usedBu.add(bu); }
+  const node = (value: Omit<GraphNode, "degree" | "community">): GraphNode => ({ ...value, degree: 0, community: null });
+  for (const slug of [...usedBu].sort()) graph.nodes.push(node({ id: "bu:" + slug, type: "bu", domain: "bu", label: slug, source_file: "" }));
+  for (const [id, doc] of docs) graph.nodes.push(node({ id, label: label(doc.path), type: coerce(yamlTruthy(doc.fm.document_type) ? doc.fm.document_type : "work-doc"), domain: doc.path.split("/")[0]!, description: Array.from(coerce(yamlTruthy(doc.fm.title) ? doc.fm.title : yamlTruthy(doc.fm.description) ? doc.fm.description : "")).slice(0, 200).join(""), source_file: doc.path }));
+  if (graph.nodes.length > 20000) throw new Error("workspace graph: exceeds 20000 nodes");
+  const candidates: GraphEdge[] = [];
+  const add = (relation: GraphEdge["relation"], source: string, target: string, attrs: { rel?: string; field?: string } = {}) => {
+    if (candidates.length >= 200000) throw new Error("workspace graph: exceeds 200000 edge candidates");
+    candidates.push({ source, target, relation, confidence_tag: "EXTRACTED", confidence: 1, ...attrs });
+  };
+  for (const [id, doc] of docs) {
+    const related = doc.fm.related;
+    if (related !== null && related !== undefined) for (const entry of Array.isArray(related) ? related : [related]) {
+      const rtype = mapping(entry) ? entry.rel : undefined;
+      let value = pyString(mapping(entry) ? entry.doc ?? "" : entry).trim();
+      if (!value) continue;
+      value = value.replace(/\s*\([^)]*\)\s*$/, "").trim();
+      const wiki = links(value);
+      let target: string | undefined;
+      if (wiki.length) {
+        const targets = stems.get(wiki[0]!);
+        if (!targets?.length) counters.related_unresolved++;
+        else if (targets.length > 1) counters.related_ambiguous++;
+        else target = targets[0];
+      } else if (value.startsWith("~")) counters.related_home_escape++;
+      else {
+        const joined = posix.isAbsolute(value) ? posix.normalize(value) : posix.normalize(posix.join(posix.dirname(doc.path), value));
+        if (joined.startsWith("..")) counters.related_root_escape++;
+        else if (value.endsWith("/") || !joined.endsWith(".md")) counters.related_dir_skip++;
+        else if (docs.has("work:" + joined.slice(0, -3))) target = "work:" + joined.slice(0, -3);
+        else counters.related_unresolved++;
+      }
+      if (target) add("related", id, target, yamlTruthy(rtype) ? { rel: coerce(rtype) } : {});
+    }
+    for (const field of FIELDS) if (field in doc.fm) for (const key of links(doc.fm[field])) if (vaultIds.has(key)) add("fm_ref", id, key, { field });
+    for (const key of links(doc.body)) if (vaultIds.has(key)) add("wiki_link", id, key);
+    const bu = businessUnit(doc.fm); if (usedBu.has(bu)) add("bu_member", id, "bu:" + bu);
+  }
+  const stubs = new Set<string>();
+  for (const note of [...snapshot.notes].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+    const fm = workspaceFrontmatter(note.source), id = posix.basename(note.path, ".md"), raw = workspaceSource(fm);
+    if (raw !== undefined) {
+      const ext = posix.extname(raw), norm = raw.endsWith(".md") ? raw.slice(0, -3) : raw, target = "work:" + norm;
+      if (raw.endsWith("/") || (ext && ext !== ".md")) counters.source_nonmd++;
+      else if (docs.has(target)) add("source_ref", id, target);
+      else if (norm.split("/").some(part => WORK_SKIP_DIRS.has(part)) || workSkipped(norm, work.skipRoots) || work.sourceTargets[norm] === "denied") counters.source_skiproot++;
+      else if (work.sourceTargets[norm] === "file") {
+        if (!stubs.has(target)) { stubs.add(target); counters.source_stub++; graph.nodes.push(node({ id: target, type: "file", label: label(norm + ".md"), domain: norm.split("/")[0]!, source_file: norm + ".md" })); }
+        add("source_ref", id, target);
+      } else if (work.sourceTargets[norm] === "directory") counters.source_nonmd++;
+      else counters.source_dead++;
+    }
+    for (const field of ["supersedes", "superseded_by"]) if (yamlTruthy(fm[field])) for (const key of links(fm[field])) if (vaultIds.has(key)) add("supersedes", id, key, { field });
+  }
+  const known = new Set(graph.nodes.map(node => node.id)), best = new Map<string, GraphEdge>();
+  const pair = (edge: GraphEdge) => JSON.stringify([edge.source, edge.target].sort());
+  for (const edge of candidates) {
+    if (edge.source === edge.target || !known.has(edge.source) || !known.has(edge.target)) continue;
+    const key = pair(edge), current = best.get(key);
+    if (current) {
+      if (current.relation !== edge.relation) counters.collisions++; else counters.dup_edges++;
+    }
+    if (!current || PRIORITY[edge.relation] > PRIORITY[current.relation]) best.set(key, edge);
+  }
+  const edges = new Map(graph.edges.map(edge => [pair(edge), edge]));
+  for (const [key, edge] of best) edges.set(key, { ...edges.get(key), ...edge });
+  graph.edges = [...edges.values()];
+  if (graph.nodes.length > 20000 || graph.edges.length > 100000) throw new Error("workspace graph: node or edge bound exceeded");
+  finalizeGraph(graph);
+  const relations: Record<string, number> = {};
+  for (const edge of graph.edges) relations[edge.relation] = (relations[edge.relation] ?? 0) + 1;
+  return { graph, counters, relations };
+}

package/src/workspace-input.ts

@@ -0,0 +1,150 @@
+import { closeSync, constants, fstatSync, lstatSync, opendirSync, openSync, readSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import type { VaultSpec, VmemConfig } from "./config.ts";
+import type { AnalysisSnapshot } from "./analysis-types.ts";
+import { analysisRead } from "./analysis-input.ts";
+import { parseAnalysisYaml } from "./analysis-yaml.ts";
+import { isDenied } from "./platform.ts";
+import { sourceWorkspaceRoot } from "./source.ts";
+import { WORK_SKIP_DIRS, workspaceFrontmatter, workspaceSource, workSkipped, type WorkspaceSnapshot } from "./workspace-graph.ts";
+
+const CONFIG_SKIP = new Set([".git", "node_modules", ".venv", ".sync-conflicts", "archive", ".archive", "vault", "temp"]);
+export const WORK_MAX_FILES = 50000;
+/** Per-file bound for work docs that open with frontmatter (the only ones that can become nodes). */
+export const WORK_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const WORK_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+/** Bytes probed from every `.md` file to decide whether it opens with frontmatter; plain files are never read further. */
+const PROBE_BYTES = 4;
+/** Directory entries visited per walk (symlinks included), so a runaway tree fails explicitly instead of stalling. */
+export const WORK_MAX_ENTRIES = 2_000_000;
+const DEFAULT_ROOTS = ["scratchpad/memos", "scratchpad/temp"];
+function object(value: unknown): Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {}; }
+/** Filesystem-only snapshot. No directory or file symlinks are followed, including source stubs. */
+/** Test-only overrides of the reader bounds; production callers pass nothing and get the exported constants. */
+export interface WorkspaceLimits { files?: number; fileBytes?: number; bytes?: number; entries?: number }
+export function workspaceInput(snapshot: AnalysisSnapshot, vault: VaultSpec, config: VmemConfig, limits: WorkspaceLimits = {}): WorkspaceSnapshot {
+  const maxFiles = limits.files ?? WORK_MAX_FILES, maxFileBytes = limits.fileBytes ?? WORK_MAX_FILE_BYTES;
+  const maxBytes = limits.bytes ?? WORK_MAX_TOTAL_BYTES, maxEntries = limits.entries ?? WORK_MAX_ENTRIES;
+  const found = sourceWorkspaceRoot(vault);
+  if (!found) throw new Error("workspace graph: vault requires a registry");
+  const root = realpathSync(found);
+  if (root !== found || lstatSync(found).isSymbolicLink() || !lstatSync(found).isDirectory()) throw new Error("workspace graph: work root must be a plain directory");
+  const denied = (file: string) => isDenied(file, config.denyPaths ?? []);
+  if (denied(root)) throw new Error("workspace graph: work root is denied");
+  let filesRead = 0, bytesRead = 0, entriesSeen = 0;
+  const stamps = new Map<string, string>();
+  const stamp = (file: string) => { const stat = lstatSync(file, { bigint: true }); return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.mode].join(":"); };
+  const remember = (file: string) => {
+    const current = stamp(file), prior = stamps.get(file);
+    if (prior !== undefined && prior !== current) throw new Error("workspace graph: input changed during snapshot");
+    stamps.set(file, current);
+  };
+  /**
+   * FRONTMATTER_RE needs `---` then whitespace at offset 0; a file that cannot match is skipped unread, as in the reference.
+   * Every probed file counts once toward WORK_MAX_FILES and is stamped, so one that later gains frontmatter fails assertUnchanged.
+   */
+  const probed = new Set<string>();
+  const opensWithFrontmatter = (file: string): boolean => {
+    if (++filesRead > maxFiles) throw new Error("workspace graph: file count exceeds bound");
+    probed.add(file);
+    remember(file);
+    let fd: number;
+    try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+    try {
+      if (!fstatSync(fd).isFile()) return false;
+      const head = Buffer.alloc(PROBE_BYTES), n = readSync(fd, head, 0, PROBE_BYTES, 0);
+      return n === PROBE_BYTES && head.subarray(0, 3).toString("latin1") === "---" && /\s/.test(String.fromCharCode(head[3]!));
+    } finally { closeSync(fd); }
+  };
+  const read = (file: string, maximum = maxFileBytes): string => {
+    // A probed work doc was already counted; other reads (configs) count here.
+    if (!probed.has(file) && ++filesRead > maxFiles) throw new Error("workspace graph: file count exceeds bound");
+    remember(file);
+    const text = analysisRead(file, maximum);
+    if (text === null) throw new Error("workspace graph: input disappeared");
+    remember(file);
+    bytesRead += Buffer.byteLength(text);
+    if (bytesRead > maxBytes) throw new Error("workspace graph: total bytes exceed bound");
+    return text;
+  };
+  let skipRoots = DEFAULT_ROOTS;
+  const workspaceConfig = join(root, "workspace.config.yaml");
+  try {
+    const stat = lstatSync(workspaceConfig);
+    if (stat.isFile() && !stat.isSymbolicLink() && !denied(workspaceConfig)) {
+      const text = read(workspaceConfig, 1024 * 1024);
+      let data: Record<string, unknown> = {};
+      try { data = object(parseAnalysisYaml(text)); } catch { /* Reference falls back on malformed config. */ }
+      const paths = object(data.paths), scratchpad = object(data.scratchpad), configured = String(paths.scratchpad ?? "").trim();
+      let scratchRoot = "scratchpad";
+      if (configured) {
+        const expanded = configured === "~" ? homedir() : configured.startsWith("~/") ? join(homedir(), configured.slice(2)) : configured;
+        const absolute = resolve(expanded), rel = relative(root, absolute);
+        if (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel)) scratchRoot = rel.normalize("NFC").replace(/^\/+|\/+$/g, "");
+        else scratchRoot = "";
+      }
+      if (scratchRoot) skipRoots = [String(scratchpad.memos_subdir || "memos"), String(scratchpad.temp_subdir || "temp")].map(dir => scratchRoot + "/" + dir.normalize("NFC").replace(/^\/+|\/+$/g, ""));
+    }
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  const walk = (dir: string, skip: Set<string>, roots: string[], visit: (file: string, rel: string) => void): void => {
+    if (realpathSync(dir) !== dir || denied(dir)) return;
+    remember(dir);
+    const handle = opendirSync(dir), children: { name: string; directory: boolean; file: boolean }[] = [];
+    try {
+      for (;;) {
+        const entry = handle.readSync(); if (!entry) break;
+        if (++entriesSeen > maxEntries) throw new Error("workspace graph: directory entry count exceeds bound");
+        if (entry.isSymbolicLink()) continue;
+        children.push({ name: entry.name, directory: entry.isDirectory(), file: entry.isFile() });
+      }
+    } finally { handle.closeSync(); }
+    for (const entry of children) {
+      const file = join(dir, entry.name);
+      if (entry.file && !denied(file)) visit(file, relative(root, file).normalize("NFC"));
+    }
+    for (const entry of children) {
+      const file = join(dir, entry.name), rel = relative(root, file).normalize("NFC");
+      if (entry.directory && !skip.has(entry.name) && !workSkipped(rel, roots) && !denied(file)) walk(file, skip, roots, visit);
+    }
+    remember(dir);
+  };
+  const files: WorkspaceSnapshot["files"] = [], buSlugs = new Set<string>();
+  walk(root, WORK_SKIP_DIRS, skipRoots, (file, path) => { if (path.endsWith(".md") && opensWithFrontmatter(file)) files.push({ path, text: read(file) }); });
+  // The bu-config walk prunes fewer trees (it must see `.maru/`), like the reference's rglob, so it gets its own entry budget.
+  entriesSeen = 0;
+  walk(root, CONFIG_SKIP, [], (file, path) => {
+    if (!path.endsWith("/bu-config.yaml") && path !== "bu-config.yaml") return;
+    const text = read(file, 1024 * 1024);
+    try {
+      const data = object(parseAnalysisYaml(text)), slug = String(data.bu_id ?? "").replaceAll("[[", "").replaceAll("]]", "").trim();
+      if (/^[a-z0-9][a-z0-9-]*$/.test(slug)) buSlugs.add(slug);
+    } catch { /* Invalid bu config does not declare a hub. */ }
+  });
+  const plain = (candidate: string): "file" | "directory" | "missing" | "denied" => {
+    const rel = relative(root, candidate);
+    if (isAbsolute(rel) || rel === ".." || rel.startsWith(".." + sep)) return "missing";
+    let current = root;
+    for (const part of rel.split(sep)) {
+      current = join(current, part);
+      if (denied(current)) return "denied";
+      try { const stat = lstatSync(current); if (stat.isSymbolicLink()) return "missing"; remember(current); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR") return "missing"; throw error; }
+    }
+    const stat = lstatSync(candidate);
+    return stat.isFile() ? "file" : stat.isDirectory() ? "directory" : "missing";
+  };
+  const sourceTargets: WorkspaceSnapshot["sourceTargets"] = {};
+  for (const note of snapshot.notes) {
+    const raw = workspaceSource(workspaceFrontmatter(note.source));
+    if (raw === undefined) continue;
+    const norm = raw.endsWith(".md") ? raw.slice(0, -3) : raw;
+    if (norm.split("/").some(part => WORK_SKIP_DIRS.has(part)) || workSkipped(norm, skipRoots)) continue;
+    const file = plain(resolve(root, norm + ".md"));
+    sourceTargets[norm] = file === "file" || file === "denied" ? file : plain(resolve(root, norm)) === "directory" ? "directory" : "missing";
+  }
+  const assertUnchanged = () => { for (const [file, expected] of stamps) if (stamp(file) !== expected) throw new Error("workspace graph: input changed during build"); };
+  assertUnchanged();
+  return { files, buSlugs: [...buSlugs].sort(), skipRoots, sourceTargets, assertUnchanged };
+}