@staix/vault-mem 0.2.2 → 0.2.4

package/src/ui/plugin.ts

@@ -0,0 +1,292 @@
+/**
+ * Console plugin (api 1) for acon: STAIxBWLB/agent-console contract, UX per vault-mem#48.
+ * The provider reuses the `vmem mcp` handlers in process, so the console acts with exactly the MCP rights and checks.
+ */
+import { readFileSync } from "node:fs";
+import type { ActionResult, Change, ConsolePlugin, ConsoleProvider, InboxItem } from "@staix/agent-console/contract";
+import { analysisInput } from "../analysis-input.ts";
+import { resolveHome } from "../home.ts";
+import { createVaultMcp } from "../mcp-vault.ts";
+import { validArguments } from "../mcp.ts";
+import { listPromotionCandidates } from "../promote.ts";
+import { loadRegistry } from "../registry.ts";
+import { lintVault } from "../vault-lint.ts";
+import type { LintCode } from "../analysis-types.ts";
+
+const asset = (name: string) => readFileSync(new URL(name, import.meta.url), "utf8");
+const VERSION = (JSON.parse(asset("../../package.json")) as { version: string }).version;
+const LINT_ERRORS: LintCode[] = ["L01", "L02", "L13"];
+const CACHE_MS = 60_000;
+
+type Args = Record<string, unknown>;
+const str = (v: unknown): string | undefined => typeof v === "string" && v.length > 0 ? v : undefined;
+const rec = (v: unknown): Record<string, unknown> => (v && typeof v === "object" ? v as Record<string, unknown> : {});
+/**
+ * The console's answer to a confirmed write. An applied write is done, together with any later step that failed
+ * (a log line, the agent-mem link, SYNC lines). A successful no-op (already linked, nothing to change, a retried
+ * confirmation) is success too, never a refusal. Anything else is refused with its first issue.
+ */
+export function confirmedOutcome(done: Args, verb: string): ActionResult {
+  if (done.applied === true) {
+    const missing = followUpProblems(done);
+    return { ok: true, message: missing.length ? `${verb}: applied, but ${missing.join("; ")}` : `${verb}: done` };
+  }
+  const issues = Array.isArray(done.issues) ? done.issues as { severity?: string }[] : [];
+  if (done.ok === true && !issues.some(i => i.severity !== "warning")) return { ok: true, message: `${verb}: already done, nothing changed` };
+  return { ok: false, error: firstIssue(done) };
+}
+const firstIssue = (r: Args): string => {
+  const issues = Array.isArray(r.issues) ? r.issues as { message?: string; severity?: string }[] : [];
+  return (issues.find(i => i.severity !== "warning") ?? issues[0])?.message ?? "refused";
+};
+
+/** `- 2026-10-31 09:12  LEARN  proj  src → dest  — note (vmem:agent)` as a row; unparsable lines keep their text. */
+export function parseLogLine(line: string): { at: string; type: string; project: string; source: string; dest?: string; note: string; agent: boolean } | { raw: string } {
+  const m = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2})  (\S+)  (\S+)  (.+?)(?: → (.+?))?  — (.*?)( \(vmem:agent\))?$/.exec(line.replace(/\n$/, ""));
+  if (!m) return { raw: line };
+  return { at: m[1]!, type: m[2]!, project: m[3]!, source: m[4]!, ...(m[5] ? { dest: m[5] } : {}), note: m[6]!, agent: m[7] !== undefined };
+}
+
+/** Lint strings carry the note path in the first backtick span; this turns them into typed findings. */
+export function typedFindings(findings: Record<string, string[]>): { code: string; severity: "error" | "warning"; path?: string; message: string }[] {
+  return Object.entries(findings).flatMap(([code, list]) => list.map(message => {
+    const path = /`(notes\/[^`]+\.md)`/.exec(message)?.[1];
+    return { code, severity: LINT_ERRORS.includes(code as LintCode) ? "error" as const : "warning" as const, ...(path ? { path } : {}), message };
+  }));
+}
+
+/** Failed steps after an applied write: the log receipt(s) of a write, a promotion or an org promotion, and the result's own issues. */
+export function followUpProblems(r: Args): string[] {
+  const out: string[] = [];
+  const failed = (x: unknown) => { const l = rec(x); if (l.ok === false) out.push(firstIssue(l)); };
+  const logs = rec(r.logs);
+  for (const receipt of [r.log, rec(r.note).log, logs.source, logs.target, r.provenance]) failed(receipt);
+  if (r.ok === false) out.push(firstIssue(r));
+  return [...new Set(out)];
+}
+
+/** Planned file changes of a vmem preview, as the shell's "What will change" list. */
+function changesOf(receipt: Args): Change[] {
+  const list = Array.isArray(receipt.changes) ? receipt.changes as { path: string; beforeSha: string | null; sha256: string | null }[] : [];
+  return list.map(c => ({ op: c.beforeSha === null ? "create" : c.sha256 === null ? "delete" : "modify", target: c.path }));
+}
+
+export const plugin: ConsolePlugin = {
+  manifest: {
+    api: 1, tool: "vmem", version: VERSION, title: "Vault", icon: "vault", pollMs: 15_000,
+    panels: [
+      { id: "overview", title: "Overview", order: 1 },
+      { id: "notes", title: "Search", order: 2 },
+      { id: "note", title: "Note", order: 3 },
+      { id: "promote", title: "Promote", order: 4 },
+      { id: "lint", title: "Lint", order: 5 },
+      { id: "log", title: "Log", order: 6 },
+    ],
+    capabilities: { actions: ["delete", "move", "promote", "promote-from-amem"], confirm: true, inbox: true, search: true },
+  },
+  async open(ctx): Promise<ConsoleProvider> {
+    const home = resolveHome().home;
+    const mcp = createVaultMcp(home);
+    const call = async (name: string, args: Args): Promise<Args> => rec(await mcp.handlers[name]!(args));
+    // The shell's tabs navigate without params, so the vault chosen on one panel is kept for the others.
+    // ponytail: one choice per provider; fine for H0's single person, per session once H1 serves several.
+    let chosen: string | undefined;
+    // An explicit vault must exist (undefined otherwise, like MCP's own check); only an omitted one falls back.
+    const vaultOf = (args: Args) => {
+      const asked = str(args.vault);
+      if (asked) { const spec = mcp.vaults.find(v => v.id === asked); if (spec) chosen = spec.id; return spec; }
+      return mcp.vaults.find(v => v.id === (chosen ?? mcp.defaultVault));
+    };
+    // The vault argument for an MCP call: an explicit id goes through unchanged so the handler refuses an unknown one.
+    const vaultArg = (args: Args) => str(args.vault) ?? vaultOf(args)?.id;
+    const pass = (args: Args) => { vaultOf(args); const v = vaultArg(args); return v ? { vault: v } : {}; };
+    /**
+     * Every option the MCP tool declares reaches it: the console never hand-picks arguments, so a supported
+     * operation cannot be lost on the way. Form text for array options is split on commas; the result is checked
+     * against the tool's own schema before anything runs.
+     */
+    const forward = (tool: string, args: Args, fixed: Args = {}): Args | string => {
+      const schema = mcp.tools.find(t => t.name === tool)?.inputSchema as { properties?: Record<string, { type?: unknown }> } | undefined;
+      const out: Args = {};
+      for (const [key, spec] of Object.entries(schema?.properties ?? {})) {
+        if (key === "confirm" || key === "fingerprint") continue;
+        let value = key in fixed ? fixed[key] : key === "vault" ? vaultArg(args) : args[key];
+        if (value === undefined || value === "") continue;
+        const types = Array.isArray(spec.type) ? spec.type : [spec.type];
+        if (typeof value === "string" && types.includes("array") && !types.includes("string")) value = value.split(",").map(v => v.trim()).filter(Boolean);
+        if (value === "true" && types.includes("boolean")) value = true;
+        out[key] = value;
+      }
+      return validArguments(out, schema ?? { type: "object" }) ? out : `invalid input for ${tool}`;
+    };
+
+    // ponytail: lint reads every note, so inbox polls reuse one result per vault for 60 s; invalidate on writes if it lags.
+    const lintCache = new Map<string, { at: number; report: ReturnType<typeof lintVault> }>();
+    const lint = (id: string) => {
+      const hit = lintCache.get(id);
+      if (hit && Date.now() - hit.at < CACHE_MS) return hit.report;
+      const spec = mcp.vaults.find(v => v.id === id)!;
+      const report = lintVault(analysisInput(home, id, { expectedVault: spec }).snapshot);
+      lintCache.set(id, { at: Date.now(), report });
+      return report;
+    };
+    const projectOf = new Map<string, string>();
+    const candidates = async () => {
+      try {
+        const { projects } = await listPromotionCandidates({ allProjects: true, limit: 50, piiPatterns: loadRegistry(home).piiPatterns });
+        for (const p of projects) for (const c of p.candidates) projectOf.set(c.id, c.project);
+        return { projects };
+      }
+      catch (error) { ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`); return { projects: [], unavailable: "agent-mem candidates are unavailable; see System" }; }
+    };
+
+    // The shell keys snooze and oldest-first order on `at`, so an item keeps the time it was first seen.
+    const firstSeen = new Map<string, string>();
+    const since = (id: string) => { const at = firstSeen.get(id) ?? new Date().toISOString(); firstSeen.set(id, at); return at; };
+    async function inbox(): Promise<InboxItem[]> {
+      const items: InboxItem[] = [];
+      for (const p of (await candidates()).projects) for (const c of p.candidates) items.push({
+        id: `mem:${c.id}`, group: "candidate", kind: "promotion", title: c.title ?? c.kind, detail: `${c.kind} memory to promote into a vault note`,
+        project: c.project, at: new Date(c.at).toISOString(),
+        // Promotion needs a domain and topics, so the item opens the Promote panel instead of offering a one-key verb.
+        verbs: [],
+        link: { panel: "promote", params: { id: c.id, project: c.project } },
+      });
+      for (const v of mcp.vaults.filter(x => x.kind === "personal")) {
+        let report;
+        try { report = lint(v.id); } catch (error) { ctx.log(`vmem: lint ${v.id} failed: ${error instanceof Error ? error.message : String(error)}`); continue; }
+        if (report.errors > 0) items.push({ id: `lint:${v.id}`, group: "alert", kind: "lint", title: `${report.errors} lint errors in ${v.id}`, detail: report.summary, at: since(`lint:${v.id}`),
+          chip: { text: `${report.errors} errors`, tone: "err" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
+        const stale = report.findings.L11 ?? [];
+        if (stale.length) items.push({ id: `stale:${v.id}`, group: "alert", kind: "lint", title: `Graph report is stale in ${v.id}`, detail: stale[0]!, at: since(`stale:${v.id}`),
+          chip: { text: "stale", tone: "warn" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
+      }
+      for (const id of firstSeen.keys()) if (!items.some(i => i.id === id)) firstSeen.delete(id);
+      return items;
+    }
+
+    /** One two-step operation: preview, and with the console's confirmation recompute and write only on the same fingerprint. */
+    async function twoStep(tool: string, args: Args | string, confirmed: boolean, fingerprint: string | undefined, describe: (preview: Args) => { verb: string; preview: string[]; changes: Change[]; warnings: string[] }): Promise<ActionResult> {
+      if (typeof args === "string") return { ok: false, error: args };
+      const preview = await call(tool, args);
+      if (preview.refused || preview.ok === false || typeof preview.fingerprint !== "string") return { ok: false, error: firstIssue(preview) };
+      if (!confirmed || fingerprint !== preview.fingerprint) {
+        const d = describe(preview);
+        return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
+      }
+      const done = await call(tool, { ...args, confirm: true, fingerprint });
+      if (done.applied === true) lintCache.clear();
+      return confirmedOutcome(done, describe(preview).verb);
+    }
+
+    return {
+      assets: { js: asset("./panel.js"), css: asset("./panel.css") },
+      async snapshot(input) {
+        const args = input as Args;
+        switch (input.panel) {
+          case "inbox": return { items: await inbox() };
+          case "search": {
+            const q = str(args.q);
+            if (!q) return { hits: [], total: 0 };
+            const limit = Math.min(10, Math.max(1, Number(args.limit) || 10));
+            const r = await call("vmem_search", { query: q, limit, ...pass(args) });
+            const hits = (Array.isArray(r.hits) ? r.hits as { path: string; title: string; description: string }[] : []).map(h => ({
+              id: h.path, kind: "note", title: h.title, detail: h.description, link: { panel: "note", params: { path: h.path } } }));
+            return { hits, total: hits.length };
+          }
+          case "overview": {
+            const status = await call("vmem_status", {});
+            const vault = vaultOf(args);
+            if (!vault) return { status, vault: null };
+            const [notes, mocs, log] = await Promise.all([call("vmem_list", { vault: vault.id, limit: 500 }), call("vmem_mocs", { vault: vault.id }), call("vmem_log_tail", { vault: vault.id, n: 8 })]);
+            const count = Array.isArray(notes.notes) ? notes.notes.length : 0;
+            return { status, vault: vault.id, noteCount: count, noteCountCapped: count >= 500, mocs: mocs.mocs ?? [], log: (Array.isArray(log.lines) ? log.lines as string[] : []).map(parseLogLine) };
+          }
+          case "notes": {
+            const q = str(args.q);
+            const r = q ? await call("vmem_search", { query: q, limit: 50, ...pass(args) }) : await call("vmem_list", { limit: 100, ...pass(args) });
+            return { q: q ?? "", notes: r.hits ?? r.notes ?? [], ...(r.refused ? { error: firstIssue(r) } : {}) };
+          }
+          case "note": {
+            const path = str(args.path);
+            if (!path) return { note: null };
+            const note = await call("vmem_read", { path, ...pass(args) });
+            if (note.refused) return { note: null, error: firstIssue(note) };
+            const links = await call("vmem_links", { path, ...pass(args) });
+            // vmem_promote always reads from the default personal vault, so offer it only there.
+            const promotable = vaultOf(args)?.id === mcp.defaultVault && vaultOf(args)?.kind === "personal";
+            return { note, links, orgVaults: promotable ? mcp.vaults.filter(v => v.kind === "org").map(v => v.id) : [] };
+          }
+          case "promote": return { ...(await candidates()), selected: str(args.id) ?? null };
+          case "lint": {
+            const vault = vaultOf(args);
+            if (!vault) return { findings: [] };
+            const report = lint(vault.id);
+            return { vault: vault.id, errors: report.errors, warnings: report.warnings, summary: report.summary, findings: typedFindings(report.findings) };
+          }
+          case "log": {
+            const vault = vaultOf(args);
+            if (!vault) return { rows: [] };
+            const r = await call("vmem_log_tail", { vault: vault.id, n: 100, ...(str(args.type) ? { type: args.type } : {}) });
+            return { vault: vault.id, rows: (Array.isArray(r.lines) ? r.lines as string[] : []).map(parseLogLine).reverse(), ...(r.ok === false ? { error: firstIssue(r) } : {}) };
+          }
+          default: return { error: `unknown panel ${input.panel}` };
+        }
+      },
+      async action(input) {
+        const args = input as Args, confirmed = input.confirmed === true, fingerprint = str(input.fingerprint);
+        switch (input.action) {
+          case "delete": {
+            const path = str(args.path) ?? str(args.id);
+            if (!path) return { ok: false, error: "path is required" };
+            return twoStep("vmem_delete", forward("vmem_delete", args, { path }), confirmed, fingerprint, p => {
+              const backlinks = Array.isArray(p.backlinks) ? p.backlinks as { source: string }[] : [];
+              return { verb: "Delete note", preview: [`delete ${path}`], changes: changesOf(p),
+                warnings: backlinks.length ? [`${backlinks.length} links point here: ${[...new Set(backlinks.map(b => b.source))].slice(0, 5).join(", ")}`] : [] };
+            });
+          }
+          case "move": {
+            const from = str(args.from), to = str(args.to);
+            if (!from || !to) return { ok: false, error: "from and to are required" };
+            return twoStep("vmem_move", forward("vmem_move", args), confirmed, fingerprint, p => ({ verb: "Move note", preview: [`move ${from} → ${to}`], changes: changesOf(p), warnings: [] }));
+          }
+          case "promote": {
+            const path = str(args.path), to = str(args.to);
+            if (!path || !to) return { ok: false, error: "path and to are required" };
+            if (vaultOf(args)?.id !== mcp.defaultVault) return { ok: false, error: `promotion to an org vault reads from ${mcp.defaultVault}; open the note there` };
+            return twoStep("vmem_promote", forward("vmem_promote", args), confirmed, fingerprint, p => {
+              const screen = rec(p.screen), dropped = Array.isArray(p.droppedLinks) ? p.droppedLinks as string[] : [];
+              const target = String(p.target ?? `${to}:${path}`);
+              // A rerun after an interrupted promotion only restores the source provenance.
+              const changes: Change[] = p.recovery === "provenance-only"
+                ? [{ op: "modify", target: path, note: `provenance → ${target}` }]
+                : [{ op: "create", target }, { op: "modify", target: path, note: "provenance" }, { op: "log", target: "log", note: "SYNC lines in both vaults" }];
+              return { verb: p.recovery === "provenance-only" ? "Restore provenance" : "Promote note", preview: String(p.text ?? "").split("\n"),
+                changes,
+                warnings: [...(dropped.length ? [`${dropped.length} links become plain text: ${dropped.slice(0, 5).join(", ")}`] : []), ...(screen.passed === false ? ["screen reported issues"] : [])] };
+            });
+          }
+          case "promote-from-amem": {
+            const id = (str(args.id) ?? "").replace(/^mem:/, "");
+            if (!/^[0-9a-f-]{32,36}$/i.test(id)) return { ok: false, error: "a memory id is required" };
+            if (!projectOf.has(id)) await candidates();
+            const project = str(args.project) ?? projectOf.get(id);
+            return twoStep("vmem_promote_from_amem", forward("vmem_promote_from_amem", args, { id, ...(project ? { project } : {}) }), confirmed, fingerprint, p => {
+              const dupes = Array.isArray(p.possibleDuplicates) ? p.possibleDuplicates as string[] : [];
+              // Linking an existing note writes no vault file; it records the link in agent-mem only.
+              const changes: Change[] = p.action === "link"
+                ? [{ op: "modify", target: `agent-mem mem:${id}`, note: `vault link → ${String(p.path)}` }]
+                : [{ op: "create", target: String(p.path ?? "note") }, { op: "log", target: "log", note: "LEARN line" }, { op: "modify", target: `agent-mem mem:${id}`, note: "vault link" }];
+              return { verb: p.action === "link" ? "Link memory" : "Promote memory", preview: String(p.text ?? `link mem:${id} → ${String(p.path)}`).split("\n"),
+                changes,
+                warnings: dupes.length ? [`possible duplicates: ${dupes.slice(0, 5).join(", ")}`] : [] };
+            });
+          }
+          default: return { ok: false, error: `unknown action ${input.action}` };
+        }
+      },
+    };
+  },
+};
+
+export default plugin;

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