@monoes/monograph 1.2.0 → 1.2.2

package/dist/src/graph/statistics.d.ts

@@ -1,4 +1,8 @@
 import type { MonographDb } from '../storage/db.js';
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export declare function invalidateGraphCache(db: MonographDb): void;
 /**
  * Graph density: ratio of actual edges to maximum possible directed edges.
  * For a directed graph with n nodes: max = n * (n - 1).
@@ -13,14 +17,29 @@ export declare function graphDensity(db: MonographDb): number;
  * We use the undirected approximation: treat edges as undirected, count triangles.
  */
 export declare function clusteringCoefficient(db: MonographDb): number;
+export interface PathStats {
+    /** Average shortest path length across all reachable pairs (i ≠ j). */
+    averagePathLength: number;
+    /** Maximum shortest path length (diameter) across all reachable pairs. */
+    diameter: number;
+}
+/**
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
+ */
+export declare function pathStats(db: MonographDb): PathStats;
 /**
  * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
  * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
  */
 export declare function averagePathLength(db: MonographDb): number;
 /**
  * Graph diameter: the maximum shortest path length across all reachable node pairs.
  * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
  */
 export declare function graphDiameter(db: MonographDb): number;
 //# sourceMappingURL=statistics.d.ts.map

package/dist/src/graph/statistics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../src/graph/statistics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAWpD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAsC7D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CA4BzD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAyBrD"}
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../src/graph/statistics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0BpD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAWpD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAsC7D;AAMD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS,CAuBpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAErD"}

package/dist/src/graph/statistics.js

@@ -1,12 +1,36 @@
 import { bfsFromNode } from 'graphology-traversal/bfs.js';
 import { loadGraphFromDb } from './loader.js';
+// ---------------------------------------------------------------------------
+// Module-level graph cache — avoids reloading the full graph on every call
+// when multiple statistics functions are invoked in the same request cycle.
+// TTL: 5 seconds; keyed by DB file path (better-sqlite3 exposes .name).
+// ---------------------------------------------------------------------------
+const GRAPH_CACHE_TTL_MS = 5_000;
+const _graphCache = new Map();
+function getGraph(db) {
+    const key = db.name ?? '__default__';
+    const now = Date.now();
+    const cached = _graphCache.get(key);
+    if (cached && now < cached.expiresAt)
+        return cached.graph;
+    const graph = loadGraphFromDb(db);
+    _graphCache.set(key, { graph, expiresAt: now + GRAPH_CACHE_TTL_MS });
+    return graph;
+}
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export function invalidateGraphCache(db) {
+    const key = db.name ?? '__default__';
+    _graphCache.delete(key);
+}
 /**
  * Graph density: ratio of actual edges to maximum possible directed edges.
  * For a directed graph with n nodes: max = n * (n - 1).
  * Ignores self-loops.
  */
 export function graphDensity(db) {
-    const graph = loadGraphFromDb(db);
+    const graph = getGraph(db);
     const n = graph.order;
     if (n < 2)
         return 0;
@@ -27,7 +51,7 @@ export function graphDensity(db) {
  * We use the undirected approximation: treat edges as undirected, count triangles.
  */
 export function clusteringCoefficient(db) {
-    const graph = loadGraphFromDb(db);
+    const graph = getGraph(db);
     if (graph.order === 0)
         return 0;
     // Build undirected adjacency sets
@@ -63,59 +87,48 @@ export function clusteringCoefficient(db) {
     return totalCoeff / countWithNeighbors;
 }
 /**
- * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
- * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
  */
-export function averagePathLength(db) {
-    const graph = loadGraphFromDb(db);
+export function pathStats(db) {
+    const graph = getGraph(db);
     const nodes = graph.nodes();
     if (nodes.length < 2)
-        return 0;
+        return { averagePathLength: 0, diameter: 0 };
     let totalLength = 0;
     let reachablePairs = 0;
+    let maxDist = 0;
     for (const source of nodes) {
-        const distances = new Map();
-        distances.set(source, 0);
         bfsFromNode(graph, source, (node, _attr, depth) => {
-            if (node !== source) {
-                distances.set(node, depth);
-            }
-        });
-        for (const [target, dist] of distances) {
-            if (target !== source && dist > 0) {
-                totalLength += dist;
+            if (node !== source && depth > 0) {
+                totalLength += depth;
                 reachablePairs++;
+                if (depth > maxDist)
+                    maxDist = depth;
             }
-        }
+        });
     }
-    if (reachablePairs === 0)
-        return 0;
-    return totalLength / reachablePairs;
+    return {
+        averagePathLength: reachablePairs === 0 ? 0 : totalLength / reachablePairs,
+        diameter: maxDist,
+    };
+}
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
+ */
+export function averagePathLength(db) {
+    return pathStats(db).averagePathLength;
 }
 /**
  * Graph diameter: the maximum shortest path length across all reachable node pairs.
  * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
  */
 export function graphDiameter(db) {
-    const graph = loadGraphFromDb(db);
-    const nodes = graph.nodes();
-    if (nodes.length < 2)
-        return 0;
-    let maxDist = 0;
-    for (const source of nodes) {
-        const distances = new Map();
-        distances.set(source, 0);
-        bfsFromNode(graph, source, (node, _attr, depth) => {
-            if (node !== source) {
-                distances.set(node, depth);
-            }
-        });
-        for (const [target, dist] of distances) {
-            if (target !== source && dist > maxDist) {
-                maxDist = dist;
-            }
-        }
-    }
-    return maxDist;
+    return pathStats(db).diameter;
 }
 //# sourceMappingURL=statistics.js.map

package/dist/src/graph/statistics.js.map

@@ -1 +1 @@
-{"version":3,"file":"statistics.js","sourceRoot":"","sources":["../../../src/graph/statistics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"statistics.js","sourceRoot":"","sources":["../../../src/graph/statistics.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/stats.d.ts

@@ -35,4 +35,6 @@ export declare function computeCouplingProfile(db: Database.Database): CouplingP
  * Quick stats summary (extends existing stats from monograph_stats MCP tool).
  */
 export declare function computeGraphStats(db: Database.Database): GraphStatsSummary;
+/** Format a GraphStatsSummary as structured text for LLM consumption. */
+export declare function formatGraphStats(s: GraphStatsSummary): string;
 //# sourceMappingURL=stats.d.ts.map

package/dist/src/graph/stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/graph/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,WAAW,CAAC;IAC1B,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,eAAe,CAAC;CAClC;AA8BD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,eAAe,CAgC7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,iBAAiB,CAmB1E"}
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/graph/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAwB3C,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,WAAW,CAAC;IAC1B,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,eAAe,CAAC;CAClC;AA8BD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,eAAe,CA8B7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,iBAAiB,CAkB1E;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAY7D"}

package/dist/src/graph/stats.js

@@ -1,3 +1,30 @@
+// Per-DB prepared statement cache to avoid re-parsing SQL on repeated calls
+const stmtCache = new WeakMap();
+function stmt(db, sql) {
+    let dbCache = stmtCache.get(db);
+    if (!dbCache) {
+        dbCache = new Map();
+        stmtCache.set(db, dbCache);
+    }
+    let s = dbCache.get(sql);
+    if (!s) {
+        s = db.prepare(sql);
+        dbCache.set(sql, s);
+    }
+    return s;
+}
+/** Binary search: returns index of first element > value in a sorted ascending array. */
+function upperBound(sorted, value) {
+    let lo = 0, hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
 function percentile(sorted, p) {
     if (sorted.length === 0)
         return 0;
@@ -33,13 +60,17 @@ function buildRiskProfile(values) {
  * Compute full coupling profile from SQLite.
  */
 export function computeCouplingProfile(db) {
-    const fanInRows = db.prepare('SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id').all();
-    const fanOutRows = db.prepare('SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id').all();
-    const totalFiles = db.prepare("SELECT COUNT(*) as n FROM nodes WHERE label = 'File'").get().n;
+    const fanInRows = stmt(db, 'SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id')
+        .all();
+    const fanOutRows = stmt(db, 'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id')
+        .all();
+    const totalFiles = stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+        .get().n;
     const fanInValues = fanInRows.map(r => r.c).sort((a, b) => a - b);
     const fanOutValues = fanOutRows.map(r => r.c).sort((a, b) => a - b);
     const p95FanIn = percentile(fanInValues, 95);
-    const couplingHighCount = fanInValues.filter(v => v > p95FanIn).length;
+    // Use binary search instead of O(N) filter to count elements above p95 threshold
+    const couplingHighCount = fanInValues.length - upperBound(fanInValues, p95FanIn);
     const couplingHighPct = fanInValues.length > 0
         ? Math.round((couplingHighCount / fanInValues.length) * 100)
         : 0;
@@ -58,10 +89,11 @@ export function computeCouplingProfile(db) {
  * Quick stats summary (extends existing stats from monograph_stats MCP tool).
  */
 export function computeGraphStats(db) {
-    const nodeCount = db.prepare('SELECT COUNT(*) as n FROM nodes').get().n;
-    const edgeCount = db.prepare('SELECT COUNT(*) as n FROM edges').get().n;
-    const communityCount = db.prepare("SELECT COUNT(DISTINCT community_id) as n FROM nodes WHERE community_id IS NOT NULL").get().n;
-    const fileCount = db.prepare("SELECT COUNT(*) as n FROM nodes WHERE label = 'File'").get().n;
+    const nodeCount = stmt(db, 'SELECT COUNT(*) as n FROM nodes').get().n;
+    const edgeCount = stmt(db, 'SELECT COUNT(*) as n FROM edges').get().n;
+    const communityCount = stmt(db, "SELECT COUNT(DISTINCT community_id) as n FROM nodes WHERE community_id IS NOT NULL").get().n;
+    const fileCount = stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+        .get().n;
     const couplingProfile = computeCouplingProfile(db);
     return {
         nodeCount,
@@ -71,4 +103,18 @@ export function computeGraphStats(db) {
         couplingProfile,
     };
 }
+/** Format a GraphStatsSummary as structured text for LLM consumption. */
+export function formatGraphStats(s) {
+    const cp = s.couplingProfile;
+    const lines = [
+        `Graph Stats`,
+        `  Nodes: ${s.nodeCount}  Edges: ${s.edgeCount}  Communities: ${s.communityCount}  Files: ${s.fileCount}`,
+        `Coupling Profile (${cp.totalFiles} files)`,
+        `  Fan-in p50/p75/p90/p95: ${cp.p50FanIn}/${cp.p75FanIn}/${cp.p90FanIn}/${cp.p95FanIn}`,
+        `  High-coupling (>p95): ${cp.couplingHighPct}%`,
+        `Fan-in Risk: low=${cp.fanInProfile.low}(${cp.fanInProfile.lowPct}%) med=${cp.fanInProfile.medium}(${cp.fanInProfile.mediumPct}%) high=${cp.fanInProfile.high}(${cp.fanInProfile.highPct}%) crit=${cp.fanInProfile.critical}(${cp.fanInProfile.criticalPct}%)`,
+        `Fan-out Risk: low=${cp.fanOutProfile.low}(${cp.fanOutProfile.lowPct}%) med=${cp.fanOutProfile.medium}(${cp.fanOutProfile.mediumPct}%) high=${cp.fanOutProfile.high}(${cp.fanOutProfile.highPct}%) crit=${cp.fanOutProfile.critical}(${cp.fanOutProfile.criticalPct}%)`,
+    ];
+    return lines.join('\n');
+}
 //# sourceMappingURL=stats.js.map

package/dist/src/graph/stats.js.map

@@ -1 +1 @@
-{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/graph/stats.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/graph/stats.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/subgraph.d.ts

@@ -5,4 +5,9 @@ export interface InducedSubgraph {
     edges: MonographEdge[];
 }
 export declare function extractInducedSubgraph(db: MonographDb, nodeIds: string[]): InducedSubgraph;
+/**
+ * Format an InducedSubgraph as structured text for LLM consumption.
+ * Groups nodes by file path and lists edges with relation + file:line hints.
+ */
+export declare function formatInducedSubgraph(sg: InducedSubgraph): string;
 //# sourceMappingURL=subgraph.d.ts.map

package/dist/src/graph/subgraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subgraph.d.ts","sourceRoot":"","sources":["../../../src/graph/subgraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAiBD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,eAAe,CAkE1F"}
+{"version":3,"file":"subgraph.d.ts","sourceRoot":"","sources":["../../../src/graph/subgraph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAwDD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,eAAe,CA6D1F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CA+BjE"}

package/dist/src/graph/subgraph.js

@@ -12,26 +12,55 @@
 // SQLite SQLITE_MAX_VARIABLE_NUMBER limit (32766). Edge query binds nodeIds once
 // (source_id IN chunk), then filters target in-memory — full limit available per chunk.
 const SQLITE_VAR_LIMIT = 32766;
+/** Cache of placeholder strings keyed by count: 1 → "?", 2 → "?,?", etc. */
+const placeholderCache = new Map();
+function placeholders(n) {
+    let ph = placeholderCache.get(n);
+    if (!ph) {
+        ph = Array(n).fill('?').join(',');
+        placeholderCache.set(n, ph);
+    }
+    return ph;
+}
+/**
+ * Prepared-statement caches per db instance — stored on the db object to avoid
+ * cross-db pollution while ensuring each unique chunk size is prepared at most once.
+ */
+function getStmtCaches(db) {
+    const key = '__subgraphStmtCache__';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dbAny = db;
+    if (!dbAny[key]) {
+        dbAny[key] = { nodes: new Map(), edges: new Map() };
+    }
+    return dbAny[key];
+}
 export function extractInducedSubgraph(db, nodeIds) {
     if (nodeIds.length === 0)
         return { nodes: [], edges: [] };
-    // Chunk helper to stay within SQLITE_MAX_VARIABLE_NUMBER
-    function queryChunked(ids, chunkSize, query) {
+    const stmts = getStmtCaches(db);
+    // Chunk helper — caches prepared statements by chunk size to avoid re-prepare per call.
+    function queryChunked(ids, chunkSize, stmtCache, sql) {
         const results = [];
         for (let i = 0; i < ids.length; i += chunkSize) {
             const chunk = ids.slice(i, i + chunkSize);
-            const ph = chunk.map(() => '?').join(',');
-            results.push(...query(ph, chunk));
+            const ph = placeholders(chunk.length);
+            let stmt = stmtCache.get(chunk.length);
+            if (!stmt) {
+                stmt = db.prepare(sql(ph));
+                stmtCache.set(chunk.length, stmt);
+            }
+            results.push(...stmt.all(...chunk));
         }
         return results;
     }
-    const rawNodes = queryChunked(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) => db.prepare(`SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties
-       FROM nodes WHERE id IN (${ph})`).all(...chunk));
+    const rawNodes = queryChunked(nodeIds, SQLITE_VAR_LIMIT, stmts.nodes, ph => `SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties FROM nodes WHERE id IN (${ph})`);
     // For edges: query by source_id chunks (1 bind per row), then filter target in-memory.
-    // Querying by both source+target would miss cross-chunk edges and requires 2× bind slots.
     const nodeSet = new Set(nodeIds);
-    const rawEdges = queryChunked(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) => db.prepare(`SELECT id, source_id, target_id, relation, confidence, confidence_score, reason, evidence
-       FROM edges WHERE source_id IN (${ph})`).all(...chunk).filter(e => nodeSet.has(e.target_id)));
+    const allSourceEdges = queryChunked(nodeIds, SQLITE_VAR_LIMIT, stmts.edges, 
+    // Drop unused 'evidence' column to reduce row data transfer
+    ph => `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason FROM edges WHERE source_id IN (${ph})`);
+    const rawEdges = allSourceEdges.filter(e => nodeSet.has(e.target_id));
     const nodes = rawNodes.map(n => ({
         id: n.id,
         label: n.label,
@@ -56,4 +85,39 @@ export function extractInducedSubgraph(db, nodeIds) {
     }));
     return { nodes, edges };
 }
+/**
+ * Format an InducedSubgraph as structured text for LLM consumption.
+ * Groups nodes by file path and lists edges with relation + file:line hints.
+ */
+export function formatInducedSubgraph(sg) {
+    if (sg.nodes.length === 0)
+        return 'Subgraph is empty.';
+    const lines = [`Subgraph: ${sg.nodes.length} nodes, ${sg.edges.length} edges`];
+    // Group nodes by file
+    const byFile = new Map();
+    for (const n of sg.nodes) {
+        const file = n.filePath ?? '(unknown)';
+        let list = byFile.get(file);
+        if (!list) {
+            list = [];
+            byFile.set(file, list);
+        }
+        list.push(n);
+    }
+    lines.push('\nNodes:');
+    for (const [file, nodes] of byFile) {
+        lines.push(`  ${file}`);
+        for (const n of nodes) {
+            const loc = n.startLine ? `:${n.startLine}` : '';
+            lines.push(`    ${n.label} ${n.name}${loc}`);
+        }
+    }
+    if (sg.edges.length > 0) {
+        lines.push('\nEdges:');
+        for (const e of sg.edges) {
+            lines.push(`  ${e.sourceId} --[${e.relation}]--> ${e.targetId}`);
+        }
+    }
+    return lines.join('\n');
+}
 //# sourceMappingURL=subgraph.js.map

package/dist/src/graph/subgraph.js.map

@@ -1 +1 @@
-{"version":3,"file":"subgraph.js","sourceRoot":"","sources":["../../../src/graph/subgraph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subgraph.js","sourceRoot":"","sources":["../../../src/graph/subgraph.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/topo-sort.d.ts

@@ -14,8 +14,23 @@ export interface TopoSortResult {
  * Files with no incoming edges on the reverse graph (i.e., no one imports them)
  * are leaves and appear in level 0.
  *
+ * The in-degree computation is pushed into SQL (GROUP BY aggregation) to avoid
+ * materialising the full edge table into JavaScript memory.
+ *
  * @param db - The MonographDb instance
  * @returns Object with `levels` (array of independent groups, leaf-first) and `cycleCount`.
  */
 export declare function topologicalLevelSort(db: MonographDb): TopoSortResult;
+/**
+ * Format topological sort levels as structured text.
+ *
+ * Resolves node IDs to names and file paths so LLMs can navigate directly
+ * to the source. Cycle nodes (if any) are clearly labelled.
+ *
+ * @param db - The MonographDb instance (for name resolution)
+ * @param result - Result from topologicalLevelSort()
+ * @param maxLevels - Max levels to include in output (default: all)
+ * @returns Structured text suitable for injection into LLM context
+ */
+export declare function formatTopoSort(db: MonographDb, result: TopoSortResult, maxLevels?: number): string;
 //# sourceMappingURL=topo-sort.d.ts.map

package/dist/src/graph/topo-sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topo-sort.d.ts","sourceRoot":"","sources":["../../../src/graph/topo-sort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B;;kFAE8E;IAC9E,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,GAAG,cAAc,CAgEpE"}
+{"version":3,"file":"topo-sort.d.ts","sourceRoot":"","sources":["../../../src/graph/topo-sort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B;;kFAE8E;IAC9E,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,GAAG,cAAc,CAyEpE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAoDR"}

package/dist/src/graph/topo-sort.js

@@ -5,30 +5,46 @@
  * Files with no incoming edges on the reverse graph (i.e., no one imports them)
  * are leaves and appear in level 0.
  *
+ * The in-degree computation is pushed into SQL (GROUP BY aggregation) to avoid
+ * materialising the full edge table into JavaScript memory.
+ *
  * @param db - The MonographDb instance
  * @returns Object with `levels` (array of independent groups, leaf-first) and `cycleCount`.
  */
 export function topologicalLevelSort(db) {
     const nodeRows = db.prepare('SELECT id FROM nodes').all();
-    const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all();
     if (nodeRows.length === 0)
         return { levels: [], cycleCount: 0 };
     const nodes = nodeRows.map(r => r.id);
-    // Build reverse graph: original edge src→tgt becomes tgt→src in reverse
-    // In-degree in the reverse graph = number of nodes that tgt imports (out-degree in original)
-    const reverseAdj = new Map();
+    // Compute in-degree (on the reverse graph) via SQL aggregation.
+    // In the original graph each edge src→tgt means "src imports tgt".
+    // In the reverse graph the edge becomes tgt→src, so src gains in-degree +1.
+    // We aggregate target_id counts grouped by source_id to get reverse-in-degree per node.
+    const inDegreeRows = db
+        .prepare(`SELECT source_id AS node_id, COUNT(*) AS cnt
+       FROM edges
+       WHERE source_id != target_id
+       GROUP BY source_id`)
+        .all();
     const inDegree = new Map();
-    for (const n of nodes) {
-        reverseAdj.set(n, []);
+    for (const n of nodes)
         inDegree.set(n, 0);
+    for (const { node_id, cnt } of inDegreeRows) {
+        if (inDegree.has(node_id))
+            inDegree.set(node_id, cnt);
     }
+    // Build reverse adjacency list — still needed for Kahn's BFS relaxation step.
+    // Fetch only what Kahn needs: target_id → [source_id, ...] (reverse direction).
+    const reverseAdj = new Map();
+    for (const n of nodes)
+        reverseAdj.set(n, []);
+    const edgeRows = db
+        .prepare('SELECT source_id, target_id FROM edges WHERE source_id != target_id')
+        .all();
     for (const { source_id: src, target_id: tgt } of edgeRows) {
-        if (src === tgt)
-            continue; // skip self-loops
         if (!reverseAdj.has(tgt) || !reverseAdj.has(src))
             continue;
         reverseAdj.get(tgt).push(src);
-        inDegree.set(src, (inDegree.get(src) ?? 0) + 1);
     }
     // Kahn's BFS on the reverse graph
     const queue = [];
@@ -39,7 +55,6 @@ export function topologicalLevelSort(db) {
     const levels = [];
     const visited = new Set();
     while (queue.length > 0) {
-        // All nodes currently at in-degree 0 form one level
         const level = [...queue];
         queue.length = 0;
         levels.push(level);
@@ -64,4 +79,62 @@ export function topologicalLevelSort(db) {
     }
     return { levels, cycleCount };
 }
+// ---------------------------------------------------------------------------
+// Structured text formatter for LLM consumption
+// ---------------------------------------------------------------------------
+/**
+ * Format topological sort levels as structured text.
+ *
+ * Resolves node IDs to names and file paths so LLMs can navigate directly
+ * to the source. Cycle nodes (if any) are clearly labelled.
+ *
+ * @param db - The MonographDb instance (for name resolution)
+ * @param result - Result from topologicalLevelSort()
+ * @param maxLevels - Max levels to include in output (default: all)
+ * @returns Structured text suitable for injection into LLM context
+ */
+export function formatTopoSort(db, result, maxLevels) {
+    if (result.levels.length === 0) {
+        return 'Topological sort: no nodes found.';
+    }
+    // Batch-resolve all node IDs
+    const allIds = result.levels.flat();
+    const CHUNK = 200;
+    const nodeInfo = new Map();
+    for (let i = 0; i < allIds.length; i += CHUNK) {
+        const chunk = allIds.slice(i, i + CHUNK);
+        const ph = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, name, file_path FROM nodes WHERE id IN (${ph})`)
+            .all(...chunk);
+        for (const row of rows) {
+            nodeInfo.set(row.id, { name: row.name ?? row.id, filePath: row.file_path });
+        }
+    }
+    const isCycleLevelIdx = result.cycleCount > 0 && result.levels.length > 0
+        ? result.levels.length - 1
+        : -1;
+    const displayLevels = maxLevels !== undefined ? result.levels.slice(0, maxLevels) : result.levels;
+    const lines = [
+        `Topological sort: ${result.levels.length - (result.cycleCount > 0 ? 1 : 0)} level${result.levels.length === 1 ? '' : 's'}` +
+            (result.cycleCount > 0 ? `, ${result.cycleCount} node${result.cycleCount === 1 ? '' : 's'} in cycles` : ''),
+        '',
+    ];
+    for (let li = 0; li < displayLevels.length; li++) {
+        const level = displayLevels[li];
+        const label = li === isCycleLevelIdx ? 'Cycle nodes (unresolvable order)' : `Level ${li}`;
+        lines.push(`${label} (${level.length} node${level.length === 1 ? '' : 's'}):`);
+        for (const id of level) {
+            const info = nodeInfo.get(id);
+            const name = info?.name ?? id;
+            const fp = info?.filePath;
+            lines.push(`  ${name}${fp ? ` — ${fp}` : ''}`);
+        }
+        lines.push('');
+    }
+    if (maxLevels !== undefined && result.levels.length > maxLevels) {
+        lines.push(`... (${result.levels.length - maxLevels} more level${result.levels.length - maxLevels === 1 ? '' : 's'} omitted)`);
+    }
+    return lines.join('\n').trimEnd();
+}
 //# sourceMappingURL=topo-sort.js.map