@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/graph/build-import-graph.mjs

@@ -0,0 +1,153 @@
+/**
+ * lib/graph/build-import-graph.mjs — static import-graph derivation.
+ *
+ * Walks lib/, bin/, scripts/, and tests/ for ESM/CJS source, parses each
+ * file's relative import/export-from/dynamic-import/require specifiers, and
+ * resolves them to repo-relative paths. Produces:
+ *   file|test --imports--> file|test     (directed module dependency)
+ *   file      --realizes--> capability   (derived: a capability's declared
+ *                                         verification tests transitively reach
+ *                                         the implementation files that realize it)
+ * Test files (*.test.mjs) are typed `test` so they merge with the registry's
+ * declared verification-test nodes. Bare and node: specifiers are ignored.
+ * Pure-JS, no AST library, per ADR-0001 — a tolerant regex over import forms
+ * is sufficient for this codebase's conventions.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+const SOURCE_ROOTS = ['lib', 'bin', 'scripts', 'tests'];
+const SOURCE_EXT = new Set(['.mjs', '.js', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', 'fixtures', '.git', '.cx']);
+const RESOLVE_ORDER = ['', '.mjs', '.js', '.cjs', '.json', '/index.mjs', '/index.js'];
+
+const IMPORT_RE = /(?:import|export)\s+(?:[^'"]*?\sfrom\s+)?['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function isTestPath(rel) {
+  return rel.endsWith('.test.mjs') || rel.endsWith('.test.js');
+}
+
+function nodeFor(rel) {
+  return isTestPath(rel) ? { type: 'test', id: `test:${rel}` } : { type: 'file', id: `file:${rel}` };
+}
+
+function walk(rootDir, dirRel, acc) {
+  const abs = path.join(rootDir, dirRel);
+  let entries;
+  try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') && e.name !== '.') { if (SKIP_DIRS.has(e.name)) continue; }
+    if (SKIP_DIRS.has(e.name)) continue;
+    const rel = dirRel ? path.join(dirRel, e.name) : e.name;
+    if (e.isDirectory()) { walk(rootDir, rel, acc); continue; }
+    if (!e.isFile()) continue;
+    const ext = path.extname(e.name);
+    if (SOURCE_EXT.has(ext) || (dirRel === 'bin' && ext === '')) acc.push(rel);
+  }
+}
+
+function extractSpecifiers(content) {
+  const specs = [];
+  let m;
+  IMPORT_RE.lastIndex = 0;
+  while ((m = IMPORT_RE.exec(content)) !== null) {
+    const spec = m[1] || m[2] || m[3];
+    if (spec) specs.push(spec);
+  }
+  return specs;
+}
+
+function resolveSpecifier(rootDir, importerRel, spec) {
+  if (!spec.startsWith('.') && !spec.startsWith('/')) return null;
+  const baseAbs = path.resolve(path.dirname(path.join(rootDir, importerRel)), spec);
+  for (const suffix of RESOLVE_ORDER) {
+    const cand = baseAbs + suffix;
+    try {
+      if (existsSync(cand) && statSync(cand).isFile()) return path.relative(rootDir, cand).split(path.sep).join('/');
+    } catch { /* keep trying */ }
+  }
+  return null;
+}
+
+function buildForwardAdj(edges) {
+  const adj = new Map();
+  for (const e of edges) {
+    if (e.rel !== 'imports') continue;
+    if (!adj.has(e.from)) adj.set(e.from, []);
+    adj.get(e.from).push(e.to);
+  }
+  return adj;
+}
+
+function closure(adj, startId) {
+  const seen = new Set();
+  const stack = [startId];
+  while (stack.length) {
+    const id = stack.pop();
+    for (const to of adj.get(id) || []) {
+      if (seen.has(to)) continue;
+      seen.add(to);
+      stack.push(to);
+    }
+  }
+  return seen;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir
+ * @param {object[]} [opts.validates] — validates edges (test→capability) from the
+ *   registry build; these derive realizes (file→capability) via test closures.
+ * @returns {{ nodes: object[], edges: object[] }}
+ */
+export function buildImportGraph({ rootDir, validates = [] }) {
+  const files = [];
+  for (const root of SOURCE_ROOTS) walk(rootDir, root, files);
+  files.sort();
+
+  const nodes = [];
+  const edges = [];
+  const known = new Set(files);
+
+  for (const rel of files) {
+    const self = nodeFor(rel);
+    nodes.push({ id: self.id, type: self.type, name: rel, attrs: { path: rel } });
+  }
+
+  for (const rel of files) {
+    let content;
+    try { content = readFileSync(path.join(rootDir, rel), 'utf8'); } catch { continue; }
+    const fromNode = nodeFor(rel);
+    const seen = new Set();
+    for (const spec of extractSpecifiers(content)) {
+      const target = resolveSpecifier(rootDir, rel, spec);
+      if (!target || target === rel || seen.has(target)) continue;
+      seen.add(target);
+      const toNode = nodeFor(target);
+      if (!known.has(target)) nodes.push({ id: toNode.id, type: toNode.type, name: target, attrs: { path: target } });
+      edges.push({ from: fromNode.id, to: toNode.id, rel: 'imports', source: 'import-graph' });
+    }
+  }
+
+  // Derive realizes: a capability's declared tests transitively reach the
+  // implementation files that realize it. Intentionally over-inclusive — a
+  // broad edge only widens impact, which is the safe direction for advisory use.
+
+  const adj = buildForwardAdj(edges);
+  const realizesSeen = new Set();
+  for (const v of validates) {
+    if (v.rel !== 'validates') continue;
+    const testId = v.from;
+    const capId = v.to;
+    for (const reached of closure(adj, testId)) {
+      if (!reached.startsWith('file:')) continue;
+      const key = `${reached}->${capId}`;
+      if (realizesSeen.has(key)) continue;
+      realizesSeen.add(key);
+      edges.push({ from: reached, to: capId, rel: 'realizes', source: 'import-graph' });
+    }
+  }
+
+  return { nodes, edges };
+}

package/lib/graph/cli.mjs

@@ -0,0 +1,110 @@
+/**
+ * lib/graph/cli.mjs — `construct matrix` command surface.
+ *
+ * Subcommands:
+ *   build        Regenerate the dependency graph from the registry seeds
+ *                (and, once available, the static import graph) into
+ *                <projectDir>/.cx/graph/.
+ *   stat         Print node/edge counts by type and relation.
+ *   query <id>   Print a node's dependencies and dependents.
+ *
+ * Seeds are read from the Construct package root (rootDir); the graph is
+ * persisted under the active project (projectDir) so it travels with .cx/.
+ */
+
+import { buildFromRegistry } from './build-from-registry.mjs';
+import { buildImportGraph } from './build-import-graph.mjs';
+import { buildCoChange } from './build-co-change.mjs';
+import { writeGraph, loadGraph, dependenciesOf, dependentsOf } from './store.mjs';
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+function runBuild({ rootDir, projectDir, json, coChange }) {
+  const reg = buildFromRegistry({ rootDir });
+  const validates = reg.edges.filter((e) => e.rel === 'validates');
+  const imp = buildImportGraph({ rootDir, validates });
+  const nodes = [...reg.nodes, ...imp.nodes];
+  const edges = [...reg.edges, ...imp.edges];
+
+  if (coChange) {
+    const sourceRels = imp.nodes.filter((n) => n.type === 'file' || n.type === 'test').map((n) => n.name);
+    const co = buildCoChange({ rootDir, sourceRels });
+    nodes.push(...co.nodes);
+    edges.push(...co.edges);
+  }
+
+  const sourceHash = reg.sourceHash;
+  const result = writeGraph(projectDir, { nodes, edges, generatedAt: isoNow(), sourceHash });
+  const meta = loadGraph(projectDir).meta;
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: true, ...result, meta }, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`✓ graph built: ${result.nodeCount} nodes, ${result.edgeCount} edges → ${result.dir}\n`);
+  process.stdout.write(`  nodes: ${JSON.stringify(meta.nodesByType)}\n`);
+  process.stdout.write(`  edges: ${JSON.stringify(meta.edgesByRel)}\n`);
+  return 0;
+}
+
+function runStat({ projectDir, json }) {
+  const graph = loadGraph(projectDir);
+  if (!graph.exists) {
+    process.stderr.write('No graph found. Run `construct matrix build` first.\n');
+    return 1;
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify(graph.meta, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`graph: ${graph.nodes.size} nodes, ${graph.edges.length} edges (generated ${graph.meta?.generatedAt ?? 'unknown'})\n`);
+  process.stdout.write(`  nodes: ${JSON.stringify(graph.meta?.nodesByType ?? {})}\n`);
+  process.stdout.write(`  edges: ${JSON.stringify(graph.meta?.edgesByRel ?? {})}\n`);
+  return 0;
+}
+
+function runQuery({ projectDir, id, json }) {
+  const graph = loadGraph(projectDir);
+  if (!graph.exists) {
+    process.stderr.write('No graph found. Run `construct matrix build` first.\n');
+    return 1;
+  }
+  const node = graph.nodes.get(id);
+  const deps = dependenciesOf(graph, id);
+  const dependents = dependentsOf(graph, id);
+  if (json) {
+    process.stdout.write(JSON.stringify({ id, found: !!node, node: node ?? null, dependencies: deps, dependents }, null, 2) + '\n');
+    return node ? 0 : 1;
+  }
+  if (!node) {
+    process.stderr.write(`node not found: ${id}\n`);
+    return 1;
+  }
+  process.stdout.write(`${id} (${node.type})\n`);
+  process.stdout.write(`  → dependencies (${deps.length}): ${deps.join(', ') || '(none)'}\n`);
+  process.stdout.write(`  ← dependents   (${dependents.length}): ${dependents.join(', ') || '(none)'}\n`);
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ rootDir: string, projectDir: string }} ctx
+ * @returns {number} exit code
+ */
+export function runGraphCli(args, { rootDir, projectDir }) {
+  const sub = args[0] || 'stat';
+  const json = args.includes('--json');
+  if (sub === 'build') return runBuild({ rootDir, projectDir, json, coChange: !args.includes('--no-co-change') });
+  if (sub === 'stat') return runStat({ projectDir, json });
+  if (sub === 'query') {
+    const id = args.slice(1).find((a) => !a.startsWith('--'));
+    if (!id) {
+      process.stderr.write('Usage: construct matrix query <node-id> [--json]\n');
+      return 1;
+    }
+    return runQuery({ projectDir, id, json });
+  }
+  process.stderr.write(`Unknown graph subcommand: ${sub}. Available: build, stat, query\n`);
+  return 1;
+}

package/lib/graph/impact-cli.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/graph/impact-cli.mjs — `construct impact` command surface.
+ *
+ * Maps changed files to the tests that should run and the capabilities and
+ * workflows they touch, using the living dependency graph. Advisory by default;
+ * `--run` executes the selected tests via `node --test`. Files come from
+ * positional args, or — when none are given — from `git diff --name-only HEAD`.
+ *
+ *   construct impact lib/oracle/synthesize.mjs
+ *   construct impact --run
+ *   git diff --name-only origin/main | construct impact --stdin --json
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { computeImpact } from './impact.mjs';
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+function gitChangedFiles(projectDir) {
+  const res = spawnSync('git', ['diff', '--name-only', 'HEAD'], { cwd: projectDir, encoding: 'utf8' });
+  if (res.status !== 0) return [];
+  return res.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ rootDir: string, projectDir: string }} ctx
+ * @returns {Promise<number>} exit code
+ */
+export async function runImpactCli(args, { projectDir }) {
+  const json = args.includes('--json');
+  const run = args.includes('--run');
+  const useStdin = args.includes('--stdin');
+  let files = args.filter((a) => !a.startsWith('--'));
+
+  if (useStdin) files = readStdin().split('\n').map((l) => l.trim()).filter(Boolean);
+  if (files.length === 0) files = gitChangedFiles(projectDir);
+
+  if (files.length === 0) {
+    process.stderr.write('No changed files given (args, --stdin, or git diff). Nothing to analyze.\n');
+    return 1;
+  }
+
+  const result = computeImpact({ rootDir: projectDir, changedFiles: files });
+
+  if (!result.graphPresent) {
+    process.stderr.write('No dependency graph found. Run `construct matrix build` first.\n');
+    return 1;
+  }
+
+  if (json && !run) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+
+  if (!json) {
+    process.stdout.write(`Changed: ${result.changed.length} file(s)\n`);
+    process.stdout.write(`Impacted capabilities (${result.impactedCapabilities.length}): ${result.impactedCapabilities.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Stale capabilities (${result.staleCapabilities.length}): ${result.staleCapabilities.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Impacted workflows (${result.impactedWorkflows.length}): ${result.impactedWorkflows.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Affected tests (${result.affectedTests.length}):\n`);
+    for (const t of result.affectedTests) process.stdout.write(`  ${t}\n`);
+    if (result.coverageGaps.length) {
+      process.stdout.write(`\n⚠ Coverage gap — changed files realizing no capability (${result.coverageGaps.length}):\n`);
+      for (const f of result.coverageGaps) process.stdout.write(`  ${f}\n`);
+    }
+    if (result.unknown.length) {
+      process.stdout.write(`\nNot in graph (${result.unknown.length}): ${result.unknown.join(', ')}\n`);
+    }
+  }
+
+  if (run) {
+    const runnable = result.affectedTests.filter((t) => existsSync(path.join(projectDir, t)));
+    if (runnable.length === 0) {
+      process.stdout.write('\nNo runnable affected tests on disk.\n');
+      return 0;
+    }
+    process.stdout.write(`\n▶ Running ${runnable.length} affected test(s)…\n`);
+    const res = spawnSync(process.execPath, ['--test', ...runnable], { cwd: projectDir, stdio: 'inherit' });
+    return res.status ?? 1;
+  }
+
+  return 0;
+}

package/lib/graph/impact.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/graph/impact.mjs — forward change-impact over the dependency graph.
+ *
+ * Given a set of changed files, computes the tests that should run, the
+ * capabilities and workflows impacted, and any changed file that realizes no
+ * capability (a coverage gap). Test selection is Test Impact Analysis over the
+ * static import graph: a test is affected if it transitively imports a changed
+ * file, or if it validates a capability that a changed file realizes. The
+ * union is intentionally conservative — over-selection is safe, under-selection
+ * silently ships untested change.
+ */
+
+import { loadGraph, dependentsOf, dependenciesOf } from './store.mjs';
+import { rollupStaleImpact } from '../certification/stale-impact.mjs';
+
+function isTestRel(rel) {
+  return rel.endsWith('.test.mjs') || rel.endsWith('.test.js');
+}
+
+function toNodeId(rel) {
+  return isTestRel(rel) ? `test:${rel}` : `file:${rel}`;
+}
+
+function reverseImportClosure(graph, startId) {
+  const reached = new Set();
+  const stack = [startId];
+  while (stack.length) {
+    const id = stack.pop();
+    for (const importer of dependentsOf(graph, id, 'imports')) {
+      if (reached.has(importer)) continue;
+      reached.add(importer);
+      stack.push(importer);
+    }
+  }
+  return reached;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir — project root holding .cx/graph/.
+ * @param {string[]} opts.changedFiles — repo-relative paths.
+ * @returns {{ changed: string[], unknown: string[], affectedTests: string[], impactedCapabilities: string[], impactedWorkflows: string[], staleCapabilities: string[], coverageGaps: string[], graphPresent: boolean }}
+ */
+export function computeImpact({ rootDir, changedFiles }) {
+  const graph = loadGraph(rootDir);
+  const norm = [...new Set((changedFiles || []).map((f) => f.split('\\').join('/').replace(/^\.\//, '')))].filter(Boolean);
+  if (!graph.exists) {
+    return {
+      changed: norm,
+      unknown: norm,
+      affectedTests: [],
+      impactedCapabilities: [],
+      impactedWorkflows: [],
+      staleCapabilities: rollupStaleImpact({ rootDir, changedFiles: norm }),
+      coverageGaps: [],
+      graphPresent: false,
+    };
+  }
+
+  const tests = new Set();
+  const capabilities = new Set();
+  const unknown = [];
+  const coverageGaps = [];
+
+  for (const rel of norm) {
+    const id = toNodeId(rel);
+    if (!graph.nodes.has(id)) { unknown.push(rel); continue; }
+
+    if (id.startsWith('test:')) tests.add(id);
+
+    for (const importer of reverseImportClosure(graph, id)) {
+      if (importer.startsWith('test:')) tests.add(importer);
+    }
+
+    const caps = dependenciesOf(graph, id, 'realizes');
+    for (const c of caps) capabilities.add(c);
+    if (id.startsWith('file:') && caps.length === 0) coverageGaps.push(rel);
+  }
+
+  // Capabilities reached transitively also pull in their declared verification
+  // tests; their embedded workflows complete the requirement trace.
+
+  for (const cap of [...capabilities]) {
+    for (const t of dependentsOf(graph, cap, 'validates')) tests.add(t);
+  }
+  for (const t of tests) {
+    for (const cap of dependenciesOf(graph, t, 'validates')) capabilities.add(cap);
+  }
+
+  const workflows = new Set();
+  for (const cap of capabilities) {
+    for (const wf of dependenciesOf(graph, cap, 'embeds')) workflows.add(wf);
+  }
+
+  const strip = (set, prefix) => [...set].map((id) => id.slice(prefix.length)).sort();
+  const impactedCapabilityIds = strip(capabilities, 'capability:');
+  const staleCapabilities = rollupStaleImpact({ rootDir, changedFiles: norm });
+  return {
+    changed: norm,
+    unknown,
+    affectedTests: [...tests].map((id) => id.slice('test:'.length)).sort(),
+    impactedCapabilities: impactedCapabilityIds,
+    impactedWorkflows: strip(workflows, 'workflow:'),
+    staleCapabilities,
+    coverageGaps: coverageGaps.sort(),
+    graphPresent: true,
+  };
+}

package/lib/graph/staleness.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/graph/staleness.mjs — dependency graph seed-hash staleness checks.
+ *
+ * Compares the hash of registry/contracts/workflow seed files against the
+ * hash stored at last graph build (.cx/graph/meta.json). Shared by Oracle,
+ * the doctor graph-staleness watcher, and PostToolUse advisories.
+ */
+
+import { hashFiles } from './build-from-registry.mjs';
+import { loadGraph } from './store.mjs';
+
+export const GRAPH_SEED_FILES = [
+  'registry/capabilities.json',
+  'specialists/contracts.json',
+  'lib/embedded-contract/workflow-defs.mjs',
+];
+
+/**
+ * @param {string} rootDir — project root holding .cx/graph/.
+ * @returns {{ present: boolean, stale: boolean, staleReason: string|null, currentHash?: string, storedHash?: string|null }}
+ */
+export function checkGraphStaleness(rootDir) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) {
+    return { present: false, stale: false, staleReason: null };
+  }
+
+  try {
+    const current = hashFiles(rootDir, GRAPH_SEED_FILES);
+    const stored = graph.meta?.sourceHash ?? null;
+    if (stored && current !== stored) {
+      return {
+        present: true,
+        stale: true,
+        staleReason: 'registry/contracts/workflow seeds changed since last build',
+        currentHash: current,
+        storedHash: stored,
+      };
+    }
+    return { present: true, stale: false, staleReason: null, currentHash: current, storedHash: stored };
+  } catch {
+    return { present: true, stale: false, staleReason: null };
+  }
+}

package/lib/graph/store.mjs

@@ -0,0 +1,172 @@
+/**
+ * lib/graph/store.mjs — typed, directed dependency-graph store.
+ *
+ * The substrate for Construct's living dependency matrix. Nodes are typed
+ * entities (file, module, workflow, capability, test, contract, surface,
+ * skill, rule) addressed by canonical ids of the form `type:key`. Edges are
+ * directed and carry a relation kind (imports, realizes, validates, covers,
+ * exposes, governed_by, uses, embeds, co_changes) and a provenance source
+ * (registry, import-graph, co-change, override).
+ *
+ * Persisted under `.cx/graph/` as deterministic JSONL so a graph round-trips
+ * losslessly and diffs cleanly: nodes.jsonl (sorted by id), edges.jsonl
+ * (sorted by from,rel,to), meta.json (generatedAt, sourceHash, counts).
+ * Dependency-free and pure-JS per ADR-0001.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+export const NODE_TYPES = new Set([
+  'file', 'module', 'workflow', 'capability', 'test', 'contract', 'surface', 'skill', 'rule',
+]);
+
+export const EDGE_RELS = new Set([
+  'imports', 'realizes', 'validates', 'covers', 'exposes', 'governed_by', 'uses', 'embeds', 'co_changes', 'contains',
+]);
+
+export const EDGE_SOURCES = new Set(['registry', 'import-graph', 'co-change', 'override']);
+
+const STORE_SUBDIR = path.join('.cx', 'graph');
+
+export function graphDir(rootDir) {
+  return path.join(rootDir, STORE_SUBDIR);
+}
+
+export function nodeId(type, key) {
+  return `${type}:${key}`;
+}
+
+function nodesPath(rootDir) { return path.join(graphDir(rootDir), 'nodes.jsonl'); }
+function edgesPath(rootDir) { return path.join(graphDir(rootDir), 'edges.jsonl'); }
+function metaPath(rootDir) { return path.join(graphDir(rootDir), 'meta.json'); }
+
+function readJsonl(filePath) {
+  if (!existsSync(filePath)) return [];
+  const out = [];
+  for (const line of readFileSync(filePath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+function writeAtomic(filePath, contents) {
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, contents, 'utf8');
+  renameSync(tmp, filePath);
+}
+
+// Canonical de-dup: nodes keyed by id (last write wins on attrs), edges keyed
+// by from|rel|to (weights summed so repeated co-change observations accumulate).
+
+function normalizeNodes(nodes) {
+  const byId = new Map();
+  for (const n of nodes) {
+    if (!n?.id || !n?.type) continue;
+    const prev = byId.get(n.id);
+    byId.set(n.id, prev ? { ...prev, ...n, attrs: { ...(prev.attrs || {}), ...(n.attrs || {}) } } : { id: n.id, type: n.type, name: n.name ?? n.id, attrs: n.attrs || {} });
+  }
+  return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+function edgeKey(e) { return `${e.from}|${e.rel}|${e.to}`; }
+
+function normalizeEdges(edges) {
+  const byKey = new Map();
+  for (const e of edges) {
+    if (!e?.from || !e?.to || !e?.rel) continue;
+    const key = edgeKey(e);
+    const prev = byKey.get(key);
+    if (prev) {
+      prev.weight = (prev.weight || 1) + (e.weight || 1);
+      if (e.source && !prev.sources.includes(e.source)) prev.sources.push(e.source);
+    } else {
+      byKey.set(key, { from: e.from, to: e.to, rel: e.rel, weight: e.weight || 1, sources: e.source ? [e.source] : (e.sources || []) });
+    }
+  }
+  return [...byKey.values()].sort((a, b) => (edgeKey(a) < edgeKey(b) ? -1 : 1));
+}
+
+function countBy(items, key) {
+  const out = {};
+  for (const it of items) { const k = it[key]; out[k] = (out[k] || 0) + 1; }
+  return out;
+}
+
+/**
+ * Persist a full graph (regenerate semantics). Nodes and edges are normalized
+ * and sorted; meta records counts and the caller-supplied source hash.
+ *
+ * @param {string} rootDir
+ * @param {{ nodes: object[], edges: object[], generatedAt?: string, sourceHash?: string }} graph
+ * @returns {{ nodeCount: number, edgeCount: number, dir: string }}
+ */
+export function writeGraph(rootDir, { nodes = [], edges = [], generatedAt = null, sourceHash = null } = {}) {
+  const dir = graphDir(rootDir);
+  mkdirSync(dir, { recursive: true });
+  const normNodes = normalizeNodes(nodes);
+  const normEdges = normalizeEdges(edges);
+  writeAtomic(nodesPath(rootDir), normNodes.map((n) => JSON.stringify(n)).join('\n') + (normNodes.length ? '\n' : ''));
+  writeAtomic(edgesPath(rootDir), normEdges.map((e) => JSON.stringify(e)).join('\n') + (normEdges.length ? '\n' : ''));
+  const meta = {
+    generatedAt,
+    sourceHash,
+    nodeCount: normNodes.length,
+    edgeCount: normEdges.length,
+    nodesByType: countBy(normNodes, 'type'),
+    edgesByRel: countBy(normEdges, 'rel'),
+  };
+  writeAtomic(metaPath(rootDir), JSON.stringify(meta, null, 2) + '\n');
+  return { nodeCount: normNodes.length, edgeCount: normEdges.length, dir };
+}
+
+/**
+ * Load the graph into an indexed, queryable view. Out/in adjacency maps make
+ * forward (dependencies) and reverse (dependents) traversal O(degree).
+ *
+ * @param {string} rootDir
+ * @returns {{ nodes: Map<string,object>, edges: object[], out: Map<string,object[]>, in: Map<string,object[]>, meta: object|null, exists: boolean }}
+ */
+export function loadGraph(rootDir) {
+  const nodeList = readJsonl(nodesPath(rootDir));
+  const edgeList = readJsonl(edgesPath(rootDir));
+  let meta = null;
+  try { meta = JSON.parse(readFileSync(metaPath(rootDir), 'utf8')); } catch { /* no meta */ }
+
+  const nodes = new Map();
+  for (const n of nodeList) nodes.set(n.id, n);
+  const out = new Map();
+  const inc = new Map();
+  for (const e of edgeList) {
+    if (!out.has(e.from)) out.set(e.from, []);
+    if (!inc.has(e.to)) inc.set(e.to, []);
+    out.get(e.from).push(e);
+    inc.get(e.to).push(e);
+  }
+  return { nodes, edges: edgeList, out, in: inc, meta, exists: existsSync(nodesPath(rootDir)) };
+}
+
+function filterRel(edges, rel) {
+  if (!rel) return edges;
+  const rels = Array.isArray(rel) ? new Set(rel) : new Set([rel]);
+  return edges.filter((e) => rels.has(e.rel));
+}
+
+/**
+ * Nodes that `id` points to along `rel` (its dependencies).
+ */
+export function dependenciesOf(graph, id, rel = null) {
+  return filterRel(graph.out.get(id) || [], rel).map((e) => e.to);
+}
+
+/**
+ * Nodes that point to `id` along `rel` (its dependents).
+ */
+export function dependentsOf(graph, id, rel = null) {
+  return filterRel(graph.in.get(id) || [], rel).map((e) => e.from);
+}
+
+export function nodesByType(graph, type) {
+  return [...graph.nodes.values()].filter((n) => n.type === type);
+}